dohertj2/mxaccessgw
1
0
Fork 0
Code Issues 14 Pull Requests 2 Actions Packages Projects Releases Wiki Activity

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

Browse Source 
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.
This commit is contained in:
Joseph Doherty
2026-08-07 06:00:58 -04:00
parent cf66ebbcfb
commit d6b2f24c3f
30 changed files with 631 additions and 40 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/ClientBehaviorFixtures.md
+26
View File
@@ -44,6 +44,32 @@ 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
docs/ClientLibrariesDesign.md
+8 -1
View File
@@ -115,7 +115,14 @@ remove/write family, the parity-critical single-item helpers are:
`Activate`, and `Unregister`. Each is a thin wrapper over the same raw-command
machinery the bulk helpers use — it adds no wire surface — and runs the same
MXAccess-level reply validation (HRESULT `< 0` + per-item `MxStatusProxy`) as the
rest of the client. **MXAccess parity is preserved exactly**: e.g. `WriteSecured`
rest of the client. The per-item rule is **`MxStatusProxy` failure iff
`category != MX_STATUS_CATEGORY_OK`**; `success` is the raw COM member carried
for diagnostics only and never decides the verdict, so an absent entry is
success while a present entry with an unspecified category is a failure. The
shared fixtures in `clients/proto/fixtures/behavior/command-replies/` pin both
rules across all five clients (see
[Client Behavior Fixtures](./ClientBehaviorFixtures.md)).
**MXAccess parity is preserved exactly**: e.g. `WriteSecured`
failing before a prior `AuthenticateUser` + `AdviseSupervisory` surfaces the
native failure unchanged — the helper does not pre-validate or reorder it.