Joseph Doherty
1.7 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
Run the focused tests after changing the frame protocol:
dotnet test src/MxGateway.Tests/MxGateway.Tests.csproj --filter WorkerFrameProtocolTests
Run the gateway build because the frame protocol is part of
MxGateway.Server:
dotnet build src/MxGateway.Server/MxGateway.Server.csproj