docs(clients): add slow-consumer/backpressure comparison table (mxaccessgw#204)

Claude-Session: https://claude.ai/code/session_01GT67AEHd2Acv1YPwGfXEoV
This commit is contained in:
Joseph Doherty
2026-11-09 12:31:32 -05:00
parent 7c377cac7b
commit ad7d2cbef0
+21
View File
@@ -120,6 +120,27 @@ Clients use these fixtures to verify that stream helpers preserve
Wrappers must not reorder, coalesce, or drop events while reading the fixture.
### Slow-Consumer And Backpressure Behavior
Each client treats a consumer that falls behind differently. The gateway side is
the same for all of them: a subscriber whose bounded server-side event channel
overflows is disconnected with an `EventQueueOverflow` fault (surfaced as gRPC
`ResourceExhausted`) rather than having events silently dropped; see
`MxGateway:Events:BackpressurePolicy` in `GatewayConfiguration.md`. The table
covers only what each client does on its own side of the wire.
| Client | Client-side buffer | Default | When the consumer falls behind | Non-dropping alternative |
|---|---|---|---|---|
| .NET | none; `StreamEventsAsync` is a pull-based `IAsyncEnumerable<MxEvent>` | n/a | gRPC/HTTP-2 flow control applies back-pressure to the server, which can then overflow its per-subscriber channel | the same stream (it never drops client-side) |
| Go | buffered channel from `Session.Events`/`EventsAfter`, sized by `Options.EventBufferSize` | 1024 | the call is cancelled; buffered results are still delivered in order, then a final result matching `errors.Is(err, mxgateway.ErrSlowConsumer)` | `SubscribeEvents`/`SubscribeEventsAfter` block instead of dropping |
| Java | bounded queue behind the `streamEvents` iterator, sized by `MxGatewayClientOptions.eventQueueCapacity(n)` | 1024 | the call is cancelled; buffered events stay readable and `MxGatewayException` is thrown only after they are drained | `streamEventsAsync(request, StreamObserver<MxEvent>)` delivers on the gRPC thread with no client-side queue |
| Python | none; `Session.stream_events` is an async iterator over the gRPC call | n/a | gRPC flow control applies back-pressure to the server | the same stream |
| Rust | none; `EventStream` is a boxed `Stream` over the tonic response (the design requires any helper channel to be bounded) | n/a | gRPC flow control applies back-pressure to the server | the same stream |
After a slow-consumer cancel or an `EventQueueOverflow` disconnect, reopen with
the last seen `afterWorkerSequence`; if it predates the replay ring the stream
opens with the replay-gap sentinel described in `Event Streams` above.
## Value And Status Conversion
Value fixtures live in `clients/proto/fixtures/behavior/values/`. Each case