Files

T

Joseph Doherty 0c6e5b3ace feat(clients): CLI-15 surface ReplayGap reconnect sentinel as typed signal (4/5 clients)

The gateway emits a ReplayGap sentinel MxEvent at the head of a StreamEvents
stream resumed via after_worker_sequence when the requested cursor predates the
oldest retained event. Clients previously ignored it, silently mis-treating a
lossy resume as continuous. Each client now surfaces the sentinel as a distinct,
typed, non-terminal signal (never synthesized, never swallowed) so a consumer can
detect the gap and re-snapshot; resume contract is
after_worker_sequence = oldest_available_sequence - 1.

- .NET: MxEventStreamItem (IsReplayGap/ReplayGap/Event) via new StreamEventItemsAsync
  + AsStreamItemsAsync extension. Build clean, 87 passed.
- Go: EventResult.ReplayGap field + IsReplayGap(); ReplayGap type alias. build/vet/test clean.
- Rust: EventItem enum (Event/ReplayGap); EventStream now yields Result<EventItem, Error>;
  CLI renders REPLAY_GAP line / replayGap JSON. fmt/check/test/clippy clean.
- Python: ReplayGap dataclass; stream_events yields pb.MxEvent | ReplayGap. 131 passed.
- Shared docs: ClientLibrariesDesign non-goals reframed (reconnect-replay protocol is
  consumable; auto-reconnect stays a non-goal); CrossLanguageSmokeMatrix resume-gap note.

Java client is deferred to the windev batch (no local JRE); CLI-15 stays open until it lands.

Claude-Session: https://claude.ai/code/session_01DMXXvNuPekkkrTEyPNxEkW

2026-07-09 16:22:28 -04:00

4.3 KiB

Raw Blame History

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.

When stream-events is resumed with an after_worker_sequence cursor that predates the oldest event still in the gateway's replay ring, the gateway emits a single ReplayGap sentinel at the head of the stream. Every client surfaces this as a distinct, typed, non-terminal signal (see each client README); the resume contract is after_worker_sequence = oldest_available_sequence - 1. The default smoke sequence opens a fresh stream (no cursor) and does not exercise the gap path; a resume-with-gap fixture case is tracked separately (TST-24).

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.

4.3 KiB Raw Blame History