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. 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 And Status Conversion
Value fixtures live in `clients/proto/fixtures/behavior/values/`. Each case Value fixtures live in `clients/proto/fixtures/behavior/values/`. Each case