Cross-Language Smoke Matrix

The cross-language smoke matrix defines the documented commands used to compare official clients against the same live gateway flow. It is a repository validation fixture and command reference; normal unit tests validate the matrix shape without connecting to a gateway.

The matrix lives in clients/proto/fixtures/smoke/cross-language-smoke-matrix.json.

Scope

The matrix covers the supported client languages:

.NET
Go
Rust
Python
Java

Each client entry defines commands for the same required operation sequence:

open-session
register
add-item
advise
stream-events
close-session

The optional write command is documented separately because writing changes provider state and should only run when the operator supplies a safe test value.

Integration Gate

Cross-language smoke execution is opt-in. Runners should skip the matrix unless this variable is set:

$env:MXGATEWAY_INTEGRATION = "1"

The shared inputs are:

Variable	Default	Purpose
`MXGATEWAY_ENDPOINT`	`localhost:5000`	Gateway endpoint used by client CLIs.
`MXGATEWAY_API_KEY`	Empty	API key source for authenticated gateway deployments.
`MXGATEWAY_TEST_ITEM`	`TestChildObject.TestInt`	MXAccess item used by `add-item`.
`MXGATEWAY_TEST_WRITE_VALUE`	Empty	Enables the optional write step when set by a runner.

The commands in the matrix use MXGATEWAY_API_KEY through each CLI's api-key-env flag. They must not embed bearer tokens or raw API keys.

TLS variant

The matrix runs over plaintext (h2c) by default. A TLS variant exists but stays a manual/opt-in run, consistent with the gate above, because it needs the gateway started with an HTTPS endpoint (an https:// MXGATEWAY_ENDPOINT) and each CLI switched to its TLS flag (--tls / -tls / --plaintext=false / plaintext=False). The clients are lenient by default and accept the gateway's auto-generated self-signed certificate without extra trust setup, except the Rust CLI, which is pin-only and needs --ca-file or --require-certificate-validation (and Python uses trust-on-first-use). See Gateway Configuration — Automatic self-signed certificate and each client README for the per-client TLS flags.

JSON Comparison

Every command in the matrix requests JSON output. A runner can compare the normalized smoke record across languages with these fields:

language,
operation,
session id,
server handle,
item handle,
event count,
event family,
worker sequence,
protocol status,
HRESULT,
status arrays,
close status.

Failure output must include the client language, endpoint, and redacted auth context. Auth context identifies the source, such as MXGATEWAY_API_KEY, but does not include the secret value.

Bundled Smoke Commands

Each client also exposes a bundled smoke command. Those commands are useful for quick local checks, but the full cross-language matrix uses explicit operation commands because not every bundled smoke command streams events yet. The explicit sequence remains the parity baseline for issue-level validation.

Validation

Run the matrix shape tests after changing the smoke matrix:

dotnet test src/ZB.MOM.WW.MxGateway.Tests/ZB.MOM.WW.MxGateway.Tests.csproj --filter FullyQualifiedName~CrossLanguageSmokeMatrixTests

Live execution remains a separate opt-in step because it depends on a running gateway, the installed MXAccess worker path, and provider state.

3.7 KiB Raw Blame History