Files

T

Joseph Doherty d6b2f24c3f fix(CLI-37,CLI-38): make status/HRESULT reply validation conformant across all five clients

One cross-client conformance pass; also closes first-cycle CLI-08.

CLI-37: an MxStatusProxy entry is a failure iff `category !=
MX_STATUS_CATEGORY_OK`. The proto contract has always said so — `success` is
the raw 16-bit COM member carried verbatim for diagnostics, not a boolean — but
four clients branched on `success` alone and .NET required both, so the same
gateway reply produced opposite verdicts per language. An absent entry stays
success; a present entry with an UNSPECIFIED category is a failure, because the
worker always maps a category and an unmapped one is not proven OK.

CLI-38: a reply fails on HRESULT iff `hresult` is present and negative, so
positive COM success codes such as S_FALSE (1) pass. .NET/Go/Java used `!= 0`,
which errored on a parity-preserving S_FALSE that Python and Rust accepted.
This makes the existing ClientLibrariesDesign.md claim true rather than
rewriting the doc to describe the divergence.

Four shared fixtures pin both rules cross-client, and each language suite also
carries a table test for the two edges a fixture cannot express (absent entry,
UNSPECIFIED category). A Java test fake that built a status with a bare
`setSuccess(1)` and no category is fixed — under the category rule that reply
was never a success.

2026-08-07 06:00:58 -04:00

5.3 KiB

Raw Blame History

Client Behavior Fixtures

Client behavior fixtures define the shared expectations used by the official .NET, Go, Rust, Python, and Java clients. They keep wrapper behavior aligned while each language exposes idiomatic APIs over the same protobuf contract.

Fixture Set

The fixture manifest is clients/proto/fixtures/behavior/manifest.json. clients/proto/proto-inputs.json references the fixture root through behaviorFixtureRoot so generators and client test projects can discover the same files they use for descriptor inputs.

The fixture set contains:

command reply protobuf JSON,
ordered event stream protobuf JSON samples,
MxValue conversion case sets,
MxStatusProxy conversion case sets,
authentication and authorization error expectations,
timeout and cancellation behavior expectations.

Protobuf message fixtures use protobuf JSON field names and enum values. Files that describe client wrapper behavior use explicit JSON fields instead of a proto message because those expectations apply above the generated transport types.

Command Replies

Command reply fixtures live in clients/proto/fixtures/behavior/command-replies/. They parse as mxaccess_gateway.v1.MxCommandReply.

Clients use these fixtures to verify that successful and failed MXAccess commands both carry the full reply details:

protocolStatus,
hresult,
returnValue,
repeated statuses,
method-specific reply payloads when MXAccess returns out parameters.

MXAccess failures remain command replies when the gateway reached the worker and the worker captured HRESULT or MXSTATUS_PROXY details. Client wrappers should map those replies to rich command errors without discarding the raw reply.

Reply Validation Conformance

Four command reply fixtures pin the two reply-validation rules every client applies, because both rules have edges where a naive reading disagrees with the wire contract:

Fixture	Reply	Expected verdict
`write.status-category-error-success-set.reply.json`	one status with `success = 1`, `category = MX_STATUS_CATEGORY_COMMUNICATION_ERROR`	failure
`write.status-category-ok-success-zero.reply.json`	one status with `success = 0`, `category = MX_STATUS_CATEGORY_OK`	success
`write.hresult-s-false.reply.json`	`hresult = 1` (`S_FALSE`), statuses OK	success
`write.hresult-e-fail.reply.json`	`hresult = -2147467259` (`E_FAIL`), statuses OK	failure

The rules those fixtures lock in are:

Status entries. An MxStatusProxy entry is a failure exactly when category != MX_STATUS_CATEGORY_OK. success mirrors the raw 16-bit COM member and is diagnostics only, so it never participates in the verdict — the proto contract makes category authoritative. An absent entry is success (nothing was reported); a present entry with MX_STATUS_CATEGORY_UNSPECIFIED is a failure, because the worker always maps a category and an unmapped one is not proven OK.
HRESULT. A reply fails on HRESULT exactly when hresult is present and negative. Positive COM success codes such as S_FALSE pass, matching COM semantics.

Event Streams

Event stream fixtures live in clients/proto/fixtures/behavior/event-streams/. Each file contains an ordered events array whose entries parse as mxaccess_gateway.v1.MxEvent.

Clients use these fixtures to verify that stream helpers preserve workerSequence order and expose each native event family:

OnDataChange,
OnWriteComplete,
OperationComplete,
OnBufferedDataChange.

Wrappers must not reorder, coalesce, or drop events while reading the fixture.

Value And Status Conversion

Value fixtures live in clients/proto/fixtures/behavior/values/. Each case contains a value object that parses as mxaccess_gateway.v1.MxValue.

Status fixtures live in clients/proto/fixtures/behavior/statuses/. Each case contains a status object that parses as mxaccess_gateway.v1.MxStatusProxy.

Clients use these fixtures to verify typed projections and raw fallback behavior. A language helper may expose native booleans, integers, strings, arrays, and timestamps, but it must keep rawDiagnostic, raw data type fields, and raw byte payloads accessible when conversion is incomplete.

Auth, Timeout, And Cancel Behavior

Authentication fixtures live in clients/proto/fixtures/behavior/auth/. They separate UNAUTHENTICATED from PERMISSION_DENIED so clients map missing or invalid credentials differently from missing scopes. Expected output strings contain only redacted credentials.

Timeout and cancellation fixtures live in clients/proto/fixtures/behavior/timeout-cancel/. They document that canceling or timing out a client call stops the client from waiting, but it does not abort an in-flight MXAccess COM call on the worker STA. Clients should follow up with GetSessionState or CloseSession before reusing handles after an uncertain command timeout.

Validation

Run the fixture validation tests after changing the behavior fixture set:

powershell -ExecutionPolicy Bypass -File scripts/validate-client-behavior-fixtures.ps1

The script runs the focused C# contract tests that parse all protobuf JSON fixtures and validate deterministic wrapper expectation files.

5.3 KiB Raw Blame History