mxaccessgw/docs/ClientPackaging.md

Client Packaging

This document defines the clean-checkout commands for building, packaging, and running the official MXAccess Gateway clients. Use the tool paths and versions in Toolchain Links when a command is missing from PATH.

Shared Inputs

All clients generate bindings from the shared protobuf files under src/ZB.MOM.WW.MxGateway.Contracts/Protos. Regenerate the published client descriptor after changing either .proto file or clients/proto/proto-inputs.json:

scripts/publish-client-proto-inputs.ps1
scripts/publish-client-proto-inputs.ps1 -Check

Generated protobuf and gRPC files are generator output. Do not edit them by hand.

Environment

The examples use these common variables:

$env:MXGATEWAY_ENDPOINT = 'localhost:5000'
$env:MXGATEWAY_API_KEY = '<gateway-api-key>'
$env:MXGATEWAY_TEST_ITEM = 'TestObject.TestInt'

Use plaintext only for a local gateway. Use TLS when the gateway crosses a machine boundary or uses a production certificate.

.NET

The .NET client uses .NET 10 and references src/ZB.MOM.WW.MxGateway.Contracts/ZB.MOM.WW.MxGateway.Contracts.csproj for generated C# contract types. clients/dotnet/generated remains reserved for client-local generator output if the client later decouples from the contracts project.

Regenerate the generated C# contract types:

dotnet build src/ZB.MOM.WW.MxGateway.Contracts/ZB.MOM.WW.MxGateway.Contracts.csproj

Build and test from the repository root:

dotnet build clients/dotnet/ZB.MOM.WW.MxGateway.Client.slnx
dotnet test clients/dotnet/ZB.MOM.WW.MxGateway.Client.slnx --no-build

Create local package artifacts:

$dotnetPackageOutput = Join-Path (Get-Location) 'artifacts/clients/dotnet'
dotnet pack clients/dotnet/ZB.MOM.WW.MxGateway.Client/ZB.MOM.WW.MxGateway.Client.csproj -c Release -p:PackageOutputPath="$dotnetPackageOutput"
dotnet publish clients/dotnet/ZB.MOM.WW.MxGateway.Client.Cli/ZB.MOM.WW.MxGateway.Client.Cli.csproj -c Release -o artifacts/clients/dotnet/mxgw-dotnet

Run the CLI from source:

dotnet run --project clients/dotnet/ZB.MOM.WW.MxGateway.Client.Cli -- version --json
dotnet run --project clients/dotnet/ZB.MOM.WW.MxGateway.Client.Cli -- smoke --endpoint "http://$env:MXGATEWAY_ENDPOINT" --api-key-env MXGATEWAY_API_KEY --item $env:MXGATEWAY_TEST_ITEM --json
dotnet run --project clients/dotnet/ZB.MOM.WW.MxGateway.Client.Cli -- smoke --endpoint "https://mxgateway.example.local:5001" --tls --ca-file C:\certs\mxgateway-ca.pem --server-name mxgateway.example.local --api-key-env MXGATEWAY_API_KEY --item $env:MXGATEWAY_TEST_ITEM --json

Go

The Go client is the module gitea.dohertylan.com/dohertj2/mxaccessgw/clients/go. Generated Go files live under clients/go/internal/generated.

Regenerate the Go bindings:

Push-Location clients/go
./generate-proto.ps1
Pop-Location

Build and test from clients/go:

Push-Location clients/go
go test ./...
go build ./...
go vet ./...
Pop-Location

Create a local CLI executable:

Push-Location clients/go
New-Item -ItemType Directory -Force ../../artifacts/clients/go | Out-Null
go build -o ../../artifacts/clients/go/mxgw-go.exe ./cmd/mxgw-go
Pop-Location

Run the CLI from source:

Push-Location clients/go
go run ./cmd/mxgw-go version -json
go run ./cmd/mxgw-go smoke -endpoint $env:MXGATEWAY_ENDPOINT -plaintext -api-key-env MXGATEWAY_API_KEY -item $env:MXGATEWAY_TEST_ITEM -json
go run ./cmd/mxgw-go smoke -endpoint mxgateway.example.local:5001 -ca-cert C:\certs\mxgateway-ca.pem -server-name-override mxgateway.example.local -api-key-env MXGATEWAY_API_KEY -item $env:MXGATEWAY_TEST_ITEM -json
Pop-Location

Rust

The Rust workspace builds the zb-mom-ww-mxgateway-client library crate and the mxgw CLI crate. build.rs generates tonic and prost modules into Cargo build output on each build that needs updated protobuf output.

Regenerate and compile Rust bindings:

Push-Location clients/rust
cargo check --workspace
Pop-Location

Build and test from clients/rust:

Push-Location clients/rust
cargo fmt --all --check
cargo test --workspace
cargo check --workspace
Pop-Location

Create local release artifacts:

Push-Location clients/rust
cargo build --workspace --release
cargo install --path crates/mxgw-cli --locked --force
Pop-Location

Run the CLI from source:

Push-Location clients/rust
cargo run -p mxgw-cli -- version --json
cargo run -p mxgw-cli -- smoke --endpoint "http://127.0.0.1:5000" --plaintext --api-key-env MXGATEWAY_API_KEY --item $env:MXGATEWAY_TEST_ITEM --json
cargo run -p mxgw-cli -- smoke --endpoint "https://mxgateway.example.local:5001" --tls --ca-file C:\certs\mxgateway-ca.pem --server-name-override mxgateway.example.local --api-key-env MXGATEWAY_API_KEY --item $env:MXGATEWAY_TEST_ITEM --json
Pop-Location

Python

The Python package is zb-mom-ww-mxaccess-gateway-client. Generated modules live under clients/python/src/zb_mom_ww_mxgateway/generated.

Regenerate the Python bindings:

Push-Location clients/python
./generate-proto.ps1
Pop-Location

Install, test, and build a wheel from clients/python:

Push-Location clients/python
python -m pip install -e ".[dev]"
python -m pytest
python -m build --outdir "$env:TEMP\mxgateway-python-dist"
Pop-Location

python -m build (sdist plus wheel) is the canonical build method — it is what scripts/pack-clients.ps1 runs for the Python package. Use python -m pip wheel . --no-deps only for a quick wheel-only build.

Run the CLI from the editable install or with python -m:

Push-Location clients/python
mxgw-py version --json
mxgw-py smoke --endpoint $env:MXGATEWAY_ENDPOINT --plaintext --api-key-env MXGATEWAY_API_KEY --item $env:MXGATEWAY_TEST_ITEM --json
mxgw-py smoke --endpoint mxgateway.example.local:5001 --tls --ca-file C:\certs\mxgateway-ca.pem --server-name-override mxgateway.example.local --api-key-env MXGATEWAY_API_KEY --item $env:MXGATEWAY_TEST_ITEM --json
python -m zb_mom_ww_mxgateway_cli version --json
Pop-Location

Java

The Java workspace uses Gradle, Java 21, and the subprojects zb-mom-ww-mxgateway-client and zb-mom-ww-mxgateway-cli. The Gradle protobuf plugin writes generated Java protobuf and gRPC sources under clients/java/src/main/generated.

Regenerate Java bindings:

Push-Location clients/java
gradle :zb-mom-ww-mxgateway-client:generateProto
Pop-Location

Build and test from clients/java:

Push-Location clients/java
gradle test
Pop-Location

Create local library and CLI artifacts:

Push-Location clients/java
gradle :zb-mom-ww-mxgateway-client:jar :zb-mom-ww-mxgateway-cli:installDist
Pop-Location

Run the CLI through Gradle:

Push-Location clients/java
gradle :zb-mom-ww-mxgateway-cli:run --args="version --json"
gradle :zb-mom-ww-mxgateway-cli:run --args="smoke --endpoint $env:MXGATEWAY_ENDPOINT --plaintext --api-key-env MXGATEWAY_API_KEY --item $env:MXGATEWAY_TEST_ITEM --json"
gradle :zb-mom-ww-mxgateway-cli:run --args="smoke --endpoint mxgateway.example.local:5001 --ca-file C:\certs\mxgateway-ca.pem --server-name-override mxgateway.example.local --api-key-env MXGATEWAY_API_KEY --item $env:MXGATEWAY_TEST_ITEM --json"
Pop-Location

Packing All Clients

scripts/pack-clients.ps1 runs every client's native packaging command and drops the artifacts into one directory so a release does not depend on running each per-language command by hand. It packs the .NET NuGet packages (ZB.MOM.WW.MxGateway.Contracts and ZB.MOM.WW.MxGateway.Client), the Python sdist and wheel (python -m build), the Rust .crate (cargo package), and the Java jars plus generated POM (gradle assemble and the publication tasks). Go has no artifact to pack — it is released by git-tagging, so the script prints the scripts/tag-go-module.ps1 command and skips it.

pwsh scripts/pack-clients.ps1
pwsh scripts/pack-clients.ps1 -Languages dotnet,python

Artifacts land in -OutputDir (default dist/). Each language runs its regression tests first unless -SkipTests is set. With -Publish, every package is pushed to the internal Gitea feed; this requires the GITEA_USERNAME and GITEA_TOKEN environment variables and the script refuses to publish if either is missing.

Integration Tests

Client integration checks are opt-in because they need a live gateway and a gateway host that can create MXAccess worker sessions. Set the common environment before running a client smoke:

$env:MXGATEWAY_INTEGRATION = '1'
$env:MXGATEWAY_ENDPOINT = 'localhost:5000'
$env:MXGATEWAY_API_KEY = '<gateway-api-key>'
$env:MXGATEWAY_TEST_ITEM = 'TestObject.TestInt'
$env:MXGATEWAY_TEST_CONTEXT = ''
$env:MXGATEWAY_TEST_WRITE_VALUE = '123'

Run the bounded smoke command for each client against the same item. The smoke commands open a session, register a client name, add one item, advise it, and close the session. The .NET and Python smoke commands also read a bounded event stream; the Go, Rust, and Java smoke commands exercise the command path and can be paired with their stream-events commands after a session is open.

Client-side cancellation or timeout stops waiting for the gateway response. It does not abort an MXAccess COM call that is already executing on the worker STA.

Related Documentation

• Client Proto Generation
• Client Libraries Detailed Design
• Client Behavior Fixtures
• Toolchain Links