Joseph Doherty
18ce2922e2
Worker.Tests-003: removed the wall-clock `Elapsed < 2s` assertion from InvokeAsync_WakesIdlePumpForQueuedCommand; the awaited completion against a 30s idle period already proves the wake event drove dispatch. Worker.Tests-004: MxAccessStaSession.Dispose now joins the alarm poll task after cancelling the CTS (consistent with ShutdownGracefullyAsync), and Dispose_StopsAlarmPollLoop asserts deterministically instead of via Task.Delay. Worker.Tests-005: undisposed MemoryStream instances across the frame-protocol and pipe-session tests are now `using` declarations. Worker.Tests-006: Dispose_StopsAlarmPollLoop now constructs MxAccessStaSession with `using` so a failed assertion cannot leak the STA poll loop. Worker.Tests-007: docs/WorkerFrameProtocol.md verification section corrected to target MxGateway.Worker.Tests / MxGateway.Worker with -p:Platform=x86. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2.1 KiB
Worker Frame Protocol
The gateway uses the worker frame protocol to move WorkerEnvelope protobuf
messages over a bidirectional named pipe. The frame layer is deliberately small:
it handles message boundaries, size limits, protobuf parsing, and envelope
validation before higher-level worker client code routes commands, replies,
events, and faults.
Frame Format
Each frame starts with a four-byte little-endian unsigned payload length,
followed by the serialized WorkerEnvelope payload:
uint32 little-endian payload_length
payload_length bytes protobuf WorkerEnvelope
The reader rejects zero-length payloads and payloads larger than the configured maximum before allocating the payload buffer. The default maximum is 16 MiB, matching the gateway process design.
Envelope Validation
WorkerFrameReader and WorkerFrameWriter validate each envelope against the
owning session before returning or writing it:
protocol_versionmust match the configured worker protocol version,session_idmust match the owning gateway session,- the envelope must contain one typed
bodyvalue.
Protocol violations throw WorkerFrameProtocolException with a
WorkerFrameProtocolErrorCode so callers can distinguish malformed frames,
oversized frames, protocol version mismatches, and session mismatches.
Verification
The frame protocol lives in MxGateway.Worker.Ipc (WorkerFrameReader,
WorkerFrameWriter, WorkerFrameProtocolOptions) and is covered by
src/MxGateway.Worker.Tests/Ipc/WorkerFrameProtocolTests.cs. The worker is an
x86 process, so build and test it with -p:Platform=x86.
Run the focused tests after changing the frame protocol:
dotnet test src/MxGateway.Worker.Tests/MxGateway.Worker.Tests.csproj -p:Platform=x86 --filter WorkerFrameProtocolTests
Run the x86 worker build because the frame protocol is part of
MxGateway.Worker:
dotnet build src/MxGateway.Worker/MxGateway.Worker.csproj -p:Platform=x86