docs(clients): add slow-consumer/backpressure comparison table (mxaccessgw#204)
Claude-Session: https://claude.ai/code/session_01GT67AEHd2Acv1YPwGfXEoV
This commit is contained in:
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user