diff --git a/docs/ClientBehaviorFixtures.md b/docs/ClientBehaviorFixtures.md index 3d7f1958..d18817c5 100644 --- a/docs/ClientBehaviorFixtures.md +++ b/docs/ClientBehaviorFixtures.md @@ -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` | 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)` 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