Joseph Doherty
10534ec906
TST-27: docs/GatewayConfiguration.md's ShowTagValues row no longer says "Reserved" — it now states what false (default) does (DashboardEventBroadcaster blanks tag values from a deep-cloned MxEvent before the SignalR events-hub mirror), the security relevance (no per-session hub ACL yet, so this redaction is the only thing between a low-trust Viewer and other sessions' tag values), and the honest scope limit (does not cover /browse). WRK-26 (discharges IPC-29): docs/MxAccessWorkerInstanceDesign.md's "Outbound Queues" section rewritten from the stale five-level priority list to the two-class Control/Event scheduler actually shipped, with the collapsed- decision rationale, and the overflow paragraph rewritten to the implemented fail-fast. docs/WorkerFrameProtocol.md gained a "Write Scheduling And Sequencing" section describing HEAD truthfully: WRK-23's peek-stamp-commit sequencing is live, WRK-25's event-batch flush coalescing is not (the drain loop still awaits each event write individually), and WRK-22's cancellation tombstone is not yet defined (noted as pending, not documented as shipped). CLI-42: clients/rust/README.md and docs/ClientPackaging.md document the vendored Rust proto layout matching build.rs — repo-path-first resolution falling back to clients/rust/protos/, the check-codegen.ps1 Check 3 refresh rule, and why cargo package/publish run without --no-verify. CLI-43: docs/style-guides/JavaStyleGuide.md now says Java 17 (Ignition 8.3 baseline), mirroring CLI-12's wording, matching the shipped build.gradle. IPC-28: docs/Grpc.md's exception-mapping prose gained CommandTooLarge -> ResourceExhausted, and the Invoke section gained the oversized-payload sentence, cross-referencing GatewayConfiguration.md's headroom rule. Tracking: TST-27, WRK-26, CLI-42, CLI-43, IPC-28 flipped to Done and IPC-29 marked discharged-by-WRK-26 in 00-tracking.md and the 20/30/50/60 domain registers, with a 2026-08-07 change-log entry. Doc-only change; no source, proto, or test edits.
277 lines
9.4 KiB
Markdown
277 lines
9.4 KiB
Markdown
# 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/ZB.MOM.WW.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 = '<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:
|
|
|
|
```powershell
|
|
dotnet build src/ZB.MOM.WW.MxGateway.Contracts/ZB.MOM.WW.MxGateway.Contracts.csproj
|
|
```
|
|
|
|
Build and test from the repository root:
|
|
|
|
```powershell
|
|
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:
|
|
|
|
```powershell
|
|
$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:
|
|
|
|
```powershell
|
|
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:
|
|
|
|
```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.
|
|
|
|
`build.rs` resolves its `.proto` inputs repo-path-first, then vendored: it
|
|
prefers the canonical protos under `src/ZB.MOM.WW.MxGateway.Contracts/Protos`
|
|
so an in-repo edit is live immediately, and falls back to the copies vendored
|
|
into `clients/rust/protos/` only when the canonical directory is absent — the
|
|
case for a published crate unpacked outside this repo. The vendored copies
|
|
are declared in `Cargo.toml`'s `include` list, so `cargo package`/`cargo
|
|
publish` ship them inside the `.crate`, making the crate buildable standalone
|
|
with no access to the rest of the mxaccessgw repo. Any Contracts proto change
|
|
must refresh `clients/rust/protos/` in the same commit; `scripts/check-codegen.ps1`
|
|
Check 3 byte-compares the vendored copies against the canonical protos and
|
|
fails on drift. Because the vendored protos make a standalone build possible,
|
|
`cargo package`/`cargo publish` run **with** verification (no `--no-verify`) —
|
|
a `cargo package` that cannot build from the vendored tree alone would mean
|
|
the vendored copies are stale, and verification is what catches that before
|
|
publish.
|
|
|
|
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 `zb-mom-ww-mxaccess-gateway-client`. Generated modules
|
|
live under `clients/python/src/zb_mom_ww_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 zb_mom_ww_mxgateway_cli version --json
|
|
Pop-Location
|
|
```
|
|
|
|
## Java
|
|
|
|
The Java workspace uses Gradle, Java 17, `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:
|
|
|
|
```powershell
|
|
Push-Location clients/java
|
|
gradle :zb-mom-ww-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 :zb-mom-ww-mxgateway-client:jar :zb-mom-ww-mxgateway-cli:installDist
|
|
Pop-Location
|
|
```
|
|
|
|
Run the CLI through Gradle:
|
|
|
|
```powershell
|
|
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
|
|
```
|
|
|
|
## 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 = '<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](./ClientProtoGeneration.md)
|
|
- [Client Libraries Detailed Design](./ClientLibrariesDesign.md)
|
|
- [Client Behavior Fixtures](./ClientBehaviorFixtures.md)
|
|
- [Toolchain Links](./ToolchainLinks.md)
|