Joseph Doherty
dc9c0c950c
Apply the ZB.MOM.WW. prefix to all gateway-side projects, folders,
.csproj/.sln contents, C# namespaces, using directives, generated proto
C# (csharp_namespace + checked-in generated files), InternalsVisibleTo
attributes, project-name string literals (LoadProject, .sln lookups,
worker exe paths, staticwebassets manifest), and the install/script/doc
references that point at any of the above. Migrate the solution from
.sln to .slnx via `dotnet sln migrate` and delete the old file.
External-runtime identifiers are intentionally NOT prefixed so external
configuration keeps working:
- GatewayMetrics.cs MeterName ("MxGateway.Server")
- DashboardAuthenticationDefaults Scheme/Policy ("MxGateway.Dashboard")
- GatewayRequestLoggingMiddleware logger category ("MxGateway.Request")
- StaRuntime thread name ("MxGateway.Worker.STA")
- appsettings.json root section "MxGateway" + env-var prefix
MxGateway__... and secret-name MxGateway:ApiKeyPepper
- C:\ProgramData\MxGateway\ data dir paths
Also fixes two tests that were not rename-related but became visible
while validating the rename:
- WorkerLiveMxAccessSmokeTests.ShutDownAsync: cancellation that the
gateway service correctly maps to RpcException(Cancelled) per gRPC
convention was being misclassified as a stream fault. Added a sibling
catch on RpcException with StatusCode.Cancelled.
- IntegrationTestEnvironment.ResolveRepositoryRoot: extracted IsRepositoryRoot
and made it accept either a .git marker OR a .sln/.slnx next to src/
so the worker-exe walker works in non-git working copies.
clients/proto/proto-inputs.json's protoRoot updated to point at
src/ZB.MOM.WW.MxGateway.Contracts/Protos.
Verified by `dotnet build` and a full `dotnet test` of the .slnx with
MXGATEWAY_RUN_LIVE_{MXACCESS,LDAP,GALAXY}_TESTS=1:
Tests: 472/472 pass
Worker.Tests: 280/280 pass (4 dev-rig [Fact(Skip=...)] skipped)
IntegrationTests: 18/18 pass
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
103 lines
3.5 KiB
Markdown
103 lines
3.5 KiB
Markdown
# Parity Fixture Matrix
|
|
|
|
The parity fixture matrix defines the live-test scenarios used to compare
|
|
direct MXAccess behavior with the gateway-backed worker. It is a planning and
|
|
validation fixture, not a source of synthetic MXAccess behavior.
|
|
|
|
The matrix lives in
|
|
`clients/proto/fixtures/parity/parity-fixture-matrix.json`. It references the
|
|
local MXAccess capture set under
|
|
`C:/Users/dohertj2/Desktop/mxaccess/captures` and keeps capture paths relative
|
|
to that root so the repository does not copy raw capture artifacts.
|
|
|
|
## Scope
|
|
|
|
The matrix covers every public `LMXProxyServerClass` method represented by the
|
|
gateway contract:
|
|
|
|
- `Register`
|
|
- `Unregister`
|
|
- `AddItem`
|
|
- `AddItem2`
|
|
- `RemoveItem`
|
|
- `Advise`
|
|
- `UnAdvise`
|
|
- `AdviseSupervisory`
|
|
- `AddBufferedItem`
|
|
- `SetBufferedUpdateInterval`
|
|
- `Suspend`
|
|
- `Activate`
|
|
- `Write`
|
|
- `Write2`
|
|
- `WriteSecured`
|
|
- `WriteSecured2`
|
|
- `AuthenticateUser`
|
|
- `ArchestrAUserToId`
|
|
|
|
Each entry is either a `planned_fixture` or a `documented_gap`.
|
|
`WriteSecured` remains a documented gap because the current captures show
|
|
`0x80004021` before MXAccess emits a value-bearing write body.
|
|
`OperationComplete` and public `OnBufferedDataChange` batches also remain
|
|
documented gaps because no capture in the current set proves those public event
|
|
payloads from native MXAccess.
|
|
|
|
## Required Scenario Groups
|
|
|
|
The matrix pins the high-risk parity scenarios from the integration milestone:
|
|
|
|
| Scenario | Purpose |
|
|
|----------|---------|
|
|
| `invalid_handles` | Preserves invalid server, item, post-remove, and invalid-reference HRESULT/status behavior. |
|
|
| `write_statuses` | Compares successful writes, wrong-type writes, invalid references, arrays, and write-complete status arrays. |
|
|
| `secured_writes` | Covers observed `WriteSecured` rejection and authenticated `WriteSecured2` paths without logging credential-bearing values. |
|
|
| `add_item_context` | Ensures `AddItem2` and buffered registration pass context strings exactly as supplied. |
|
|
| `buffered_registration` | Tracks buffered item registration and interval setup separately from normal advice. |
|
|
|
|
## Comparison Format
|
|
|
|
Each live parity fixture should record one direct MXAccess result and one
|
|
gateway result for the same operation.
|
|
|
|
Direct MXAccess records include:
|
|
|
|
- method name,
|
|
- arguments after redaction,
|
|
- returned value,
|
|
- HRESULT,
|
|
- exception type,
|
|
- `MXSTATUS_PROXY[]` values,
|
|
- native event records in observed order.
|
|
|
|
Gateway records include:
|
|
|
|
- `MxCommandKind`,
|
|
- `ProtocolStatus`,
|
|
- `MxCommandReply.ReturnValue`,
|
|
- `MxCommandReply.Hresult`,
|
|
- repeated `MxCommandReply.Statuses`,
|
|
- safe diagnostic message,
|
|
- streamed `MxEvent` records in worker-sequence order.
|
|
|
|
Compare HRESULT, exception type, returned value, status array shape, raw status
|
|
fields, event family order, event payload shape, value projection, and raw
|
|
fallback metadata. The gateway must not convert an MXAccess command failure
|
|
into a transport failure when the worker captured HRESULT or status details.
|
|
|
|
## Validation
|
|
|
|
Run the parity fixture matrix tests after changing the matrix:
|
|
|
|
```bash
|
|
dotnet test src/ZB.MOM.WW.MxGateway.Tests/ZB.MOM.WW.MxGateway.Tests.csproj --filter FullyQualifiedName~ParityFixtureMatrixTests
|
|
```
|
|
|
|
Live MXAccess execution remains opt-in. The matrix defines which scenarios to
|
|
run when the installed MXAccess COM component and provider state are available;
|
|
normal unit tests only validate the repository fixture shape.
|
|
|
|
## Related Documentation
|
|
|
|
- [Gateway Testing](./GatewayTesting.md)
|
|
- [MXAccess Worker Instance Detailed Design](./MxAccessWorkerInstanceDesign.md)
|
|
- [Protobuf Contracts](./Contracts.md)
|