# 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:

1. `open-session`
2. `register`
3. `add-item`
4. `advise`
5. `stream-events`
6. `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:

```powershell
$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](./GatewayConfiguration.md#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:

```bash
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.

## Related Documentation

- [Gateway Testing](./GatewayTesting.md)
- [Client Libraries Detailed Design](./ClientLibrariesDesign.md)
- [Client Proto Generation](./ClientProtoGeneration.md)