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>
99 lines
2.9 KiB
Markdown
99 lines
2.9 KiB
Markdown
# 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.
|
|
|
|
## 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)
|