# 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](./ToolchainLinks.md) when a command is missing from `PATH`. ## Shared Inputs All clients generate bindings from the shared protobuf files under `src/MxGateway.Contracts/Protos`. Regenerate the published client descriptor after changing either `.proto` file or `clients/proto/proto-inputs.json`: ```powershell 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: ```powershell $env:MXGATEWAY_ENDPOINT = 'localhost:5000' $env:MXGATEWAY_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/MxGateway.Contracts/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: ```powershell dotnet build src/MxGateway.Contracts/MxGateway.Contracts.csproj ``` Build and test from the repository root: ```powershell dotnet build clients/dotnet/MxGateway.Client.sln dotnet test clients/dotnet/MxGateway.Client.sln --no-build ``` Create local package artifacts: ```powershell $dotnetPackageOutput = Join-Path (Get-Location) 'artifacts/clients/dotnet' dotnet pack clients/dotnet/MxGateway.Client/MxGateway.Client.csproj -c Release -p:PackageOutputPath="$dotnetPackageOutput" dotnet publish clients/dotnet/MxGateway.Client.Cli/MxGateway.Client.Cli.csproj -c Release -o artifacts/clients/dotnet/mxgw-dotnet ``` Run the CLI from source: ```powershell dotnet run --project clients/dotnet/MxGateway.Client.Cli -- version --json dotnet run --project clients/dotnet/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/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: ```powershell Push-Location clients/go ./generate-proto.ps1 Pop-Location ``` Build and test from `clients/go`: ```powershell Push-Location clients/go go test ./... go build ./... go vet ./... Pop-Location ``` Create a local CLI executable: ```powershell 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: ```powershell 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 `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: ```powershell Push-Location clients/rust cargo check --workspace Pop-Location ``` Build and test from `clients/rust`: ```powershell Push-Location clients/rust cargo fmt --all --check cargo test --workspace cargo check --workspace Pop-Location ``` Create local release artifacts: ```powershell Push-Location clients/rust cargo build --workspace --release cargo install --path crates/mxgw-cli --locked --force Pop-Location ``` Run the CLI from source: ```powershell 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 `mxaccess-gateway-client`. Generated modules live under `clients/python/src/mxgateway/generated`. Regenerate the Python bindings: ```powershell Push-Location clients/python ./generate-proto.ps1 Pop-Location ``` Install, test, and build a wheel from `clients/python`: ```powershell Push-Location clients/python python -m pip install -e ".[dev]" python -m pytest python -m pip wheel . --no-deps --wheel-dir "$env:TEMP\mxgateway-python-wheel" Pop-Location ``` Run the CLI from the editable install or with `python -m`: ```powershell 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 mxgateway_cli version --json Pop-Location ``` ## Java The Java workspace uses Gradle, Java 21, `mxgateway-client`, and `mxgateway-cli`. The Gradle protobuf plugin writes generated Java protobuf and gRPC sources under `clients/java/src/main/generated`. Regenerate Java bindings: ```powershell Push-Location clients/java gradle :mxgateway-client:generateProto Pop-Location ``` Build and test from `clients/java`: ```powershell Push-Location clients/java gradle test Pop-Location ``` Create local library and CLI artifacts: ```powershell Push-Location clients/java gradle :mxgateway-client:jar :mxgateway-cli:installDist Pop-Location ``` Run the CLI through Gradle: ```powershell Push-Location clients/java gradle :mxgateway-cli:run --args="version --json" gradle :mxgateway-cli:run --args="smoke --endpoint $env:MXGATEWAY_ENDPOINT --plaintext --api-key-env MXGATEWAY_API_KEY --item $env:MXGATEWAY_TEST_ITEM --json" gradle :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 ``` ## 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: ```powershell $env:MXGATEWAY_INTEGRATION = '1' $env:MXGATEWAY_ENDPOINT = 'localhost:5000' $env:MXGATEWAY_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](./ClientProtoGeneration.md) - [Client Libraries Detailed Design](./ClientLibrariesDesign.md) - [Client Behavior Fixtures](./ClientBehaviorFixtures.md) - [Toolchain Links](./ToolchainLinks.md)