Merge remote-tracking branch 'origin/main' into agent-2/issue-33-implement-graceful-shutdown
# Conflicts: # src/MxGateway.Worker.Tests/Ipc/WorkerPipeSessionTests.cs # src/MxGateway.Worker/Ipc/WorkerPipeClient.cs # src/MxGateway.Worker/Ipc/WorkerPipeSession.cs
This commit is contained in:
Joseph Doherty
@@ -0,0 +1,106 @@
|
||||
# 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.
|
||||
|
||||
## 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:
|
||||
|
||||
```bash
|
||||
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.
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- [Client Proto Generation](./client-proto-generation.md)
|
||||
- [Client Libraries Detailed Design](./client-libraries-design.md)
|
||||
- [Protobuf Contracts](./Contracts.md)
|
||||
@@ -18,6 +18,7 @@ starting `MxGateway.Worker.exe` or loading MXAccess COM. The harness scripts:
|
||||
- `WorkerHello` and `WorkerReady` startup,
|
||||
- command replies with matching correlation ids,
|
||||
- ordered `WorkerEvent` frames,
|
||||
- `WorkerHeartbeat` frames,
|
||||
- `WorkerFault` frames,
|
||||
- shutdown acknowledgements,
|
||||
- malformed protobuf payloads and oversized frame headers,
|
||||
@@ -43,6 +44,8 @@ event streaming behavior:
|
||||
dotnet test src/MxGateway.Tests/MxGateway.Tests.csproj --filter FullyQualifiedName~FakeWorkerHarnessTests
|
||||
dotnet test src/MxGateway.Tests/MxGateway.Tests.csproj --filter FullyQualifiedName~SessionWorkerClientFactoryFakeWorkerTests
|
||||
dotnet test src/MxGateway.Tests/MxGateway.Tests.csproj --filter FullyQualifiedName~GatewayEndToEndFakeWorkerSmokeTests
|
||||
dotnet test src/MxGateway.Tests/MxGateway.Tests.csproj --filter FullyQualifiedName~WorkerClientTests
|
||||
dotnet test src/MxGateway.Worker.Tests/MxGateway.Worker.Tests.csproj -p:Platform=x86 --filter FullyQualifiedName~WorkerPipeSessionTests
|
||||
```
|
||||
|
||||
Run the gateway test project after shared gateway test infrastructure changes:
|
||||
|
||||
@@ -29,6 +29,7 @@ Language-specific plans:
|
||||
Shared generation inputs:
|
||||
|
||||
- `docs/client-proto-generation.md`
|
||||
- `docs/ClientBehaviorFixtures.md`
|
||||
- `clients/proto/proto-inputs.json`
|
||||
|
||||
Language style guides:
|
||||
@@ -310,6 +311,11 @@ CLI output should support JSON for automated tests.
|
||||
Unit tests must run without a live gateway. Use fake gRPC services, mock
|
||||
transports, or generated test servers depending on language.
|
||||
|
||||
Shared behavior fixtures live in `clients/proto/fixtures/behavior`. Every
|
||||
client should include tests that load the fixture manifest and verify wrapper
|
||||
behavior against the common command reply, event stream, value conversion,
|
||||
status conversion, auth error, and timeout/cancel cases.
|
||||
|
||||
Required unit test areas:
|
||||
|
||||
- options parsing,
|
||||
|
||||
@@ -16,6 +16,7 @@ records:
|
||||
- the public and worker source files,
|
||||
- the descriptor set path,
|
||||
- golden fixture locations,
|
||||
- behavior fixture locations,
|
||||
- generated-code output directories for each planned client.
|
||||
|
||||
The source files listed by the manifest are:
|
||||
@@ -99,6 +100,17 @@ Go clients should generate `mxaccess_gateway.proto` and
|
||||
`protoc-gen-go` and `protoc-gen-go-grpc`. Keep generated packages internal
|
||||
unless the wrapper API intentionally exposes raw protobuf messages.
|
||||
|
||||
The Go scaffold provides a repo-local generation script:
|
||||
|
||||
```powershell
|
||||
clients/go/generate-proto.ps1
|
||||
```
|
||||
|
||||
The script maps both proto files into the internal Go package
|
||||
`gitea.dohertylan.com/dohertj2/mxaccessgw/clients/go/internal/generated` because
|
||||
the source `.proto` files do not carry Go-specific `go_package` options. This
|
||||
keeps language-specific packaging outside the public contract files.
|
||||
|
||||
Rust clients should use `tonic-build` or the selected protobuf generator from
|
||||
the Rust client build script, with generated modules placed under
|
||||
`clients/rust/src/generated` or included from the build output according to the
|
||||
@@ -125,9 +137,30 @@ The fixtures use protobuf JSON field names and enum values. Contract tests parse
|
||||
them with the generated C# types so schema drift is caught before client
|
||||
generation work starts.
|
||||
|
||||
## Behavior Fixtures
|
||||
|
||||
Cross-language behavior fixtures live in
|
||||
`clients/proto/fixtures/behavior`. The manifest
|
||||
`clients/proto/fixtures/behavior/manifest.json` lists command replies, ordered
|
||||
event stream samples, value conversion cases, status conversion cases, auth
|
||||
error expectations, and timeout/cancel expectations.
|
||||
|
||||
The behavior fixtures let each generated client wrapper test the same
|
||||
expectations without a live gateway. Protobuf message fixtures parse with the
|
||||
generated types. Auth and timeout/cancel files describe wrapper behavior above
|
||||
the generated transport layer, including credential redaction and the rule that
|
||||
client cancellation does not abort an in-flight MXAccess COM call.
|
||||
|
||||
Run the focused validation script after changing these fixtures:
|
||||
|
||||
```powershell
|
||||
scripts/validate-client-behavior-fixtures.ps1
|
||||
```
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- [Protobuf Contracts](./Contracts.md)
|
||||
- [Client Libraries Detailed Design](./client-libraries-design.md)
|
||||
- [Client Behavior Fixtures](./ClientBehaviorFixtures.md)
|
||||
- [Client Libraries Implementation Plan](./implementation-plan-clients.md)
|
||||
- [Protobuf Style Guide](./style-guides/ProtobufStyleGuide.md)
|
||||
|
||||
@@ -16,6 +16,7 @@ Recommended layout:
|
||||
|
||||
```text
|
||||
clients/dotnet/
|
||||
MxGateway.Client.sln
|
||||
MxGateway.Client/
|
||||
MxGateway.Client.csproj
|
||||
GatewayClient.cs
|
||||
@@ -41,6 +42,12 @@ Target framework:
|
||||
<TargetFramework>net10.0</TargetFramework>
|
||||
```
|
||||
|
||||
The scaffold uses a project reference to
|
||||
`src/MxGateway.Contracts/MxGateway.Contracts.csproj` for generated protobuf and
|
||||
gRPC types. `clients/dotnet/generated` remains reserved for client-local
|
||||
generator output if the .NET client later needs to decouple from the contracts
|
||||
project.
|
||||
|
||||
Expected packages:
|
||||
|
||||
- `Grpc.Net.Client`
|
||||
|
||||
@@ -625,13 +625,19 @@ Do not drop or coalesce events in v1.
|
||||
|
||||
## Heartbeat And Watchdog
|
||||
|
||||
The worker heartbeat should prove that:
|
||||
`WorkerPipeSession` starts the heartbeat loop after the gateway validates
|
||||
`WorkerHello` and receives `WorkerReady`. Heartbeats continue until
|
||||
`WorkerShutdown`, cancellation, or a pipe/protocol failure stops the session.
|
||||
The loop uses `WorkerPipeSessionOptions.HeartbeatInterval`; the default matches
|
||||
the gateway worker heartbeat interval.
|
||||
|
||||
The worker heartbeat proves that:
|
||||
|
||||
- pipe writer is alive,
|
||||
- worker host is alive,
|
||||
- STA has recently pumped or completed work.
|
||||
|
||||
Heartbeat payload should include:
|
||||
Heartbeat payload includes:
|
||||
|
||||
- worker process id,
|
||||
- session id,
|
||||
@@ -642,13 +648,19 @@ Heartbeat payload should include:
|
||||
- event sequence,
|
||||
- current command correlation id if any.
|
||||
|
||||
The STA watchdog should warn when:
|
||||
`MxAccessStaSession.CaptureHeartbeat()` reads `StaRuntime.LastActivityUtc` and
|
||||
`StaCommandDispatcher` queue state without touching the raw MXAccess COM object
|
||||
outside the STA. Event queue depth and event sequence are reported as zero until
|
||||
the event queue implementation owns those counters.
|
||||
|
||||
- one command exceeds its expected duration,
|
||||
- the STA has not pumped messages within the heartbeat grace period,
|
||||
- event queue depth remains high.
|
||||
|
||||
The worker can report the problem, but the gateway owns the final kill decision.
|
||||
The STA watchdog currently emits a `WorkerFault` with
|
||||
`WorkerFaultCategory.StaHung` when `LastStaActivityUtc` is older than
|
||||
`WorkerPipeSessionOptions.HeartbeatGrace`. The fault includes the current
|
||||
command correlation id when a command is active. Command duration and high event
|
||||
queue depth remain observable through heartbeat fields until dedicated
|
||||
thresholds own those warnings. The worker reports stale STA activity, but the
|
||||
gateway owns the final kill decision through its existing heartbeat and worker
|
||||
lifecycle policy.
|
||||
|
||||
## Shutdown
|
||||
|
||||
|
||||
Reference in New Issue
Block a user