gRPC Streaming, Deadline and Backpressure

1. Streaming shape is an interaction contract, not a performance badge

A gRPC method can be unary, server-streaming, client-streaming, or bidirectional-streaming. The right choice follows the interaction: who produces multiple messages, whether both directions are independent, and how cancellation and partial completion should behave. Choosing streaming merely because “more messages are faster” is not evidence.

The bounded outcome of this lesson is gRPC Streaming Reliability Record v1. For one local inventory-feed interaction you will record the RPC shape, direction, explicit deadline, slow-receiver condition, write observation, cancellation observation, application buffer/admission rule, bounded result, and residual risk.

2. The local case

The fixture models an inventory service with three bounded interactions. GetSnapshot is unary. WatchUpdates is server-streaming: the client asks once and the server emits a bounded sequence of updates. CommandStream is bidirectional for the transfer exercise, where both sides may produce bursts.

The lesson does not claim that server-streaming is universally better than repeated unary calls. The baseline uses it because one request establishes a bounded feed and the server is the multi-message producer.

3. Deadline is part of the call policy

The official deadline guide says gRPC does not set a useful deadline for you by default; without an explicit deadline a client may wait effectively forever. A deadline is therefore an application decision. It must be realistic for the service and validated against observed latency rather than copied from a universal constant.

The local fixture includes a normal deadline and a deliberately short deadline. Before running either case, predict whether the stream should finish or terminate with DEADLINE_EXCEEDED. After the run, record the configured budget and observed status separately.

4. Deadline expiry is not proof that application work stopped

A client seeing DEADLINE_EXCEEDED proves that the RPC exceeded its deadline from that side. It does not by itself prove every worker, coroutine, queue task, or downstream call spawned by the server stopped. Server code must observe cancellation and stop application work it created.

The fixture therefore records two different facts: the client status and a server-side cleanup/cancellation marker. The evidence record is incomplete if it records only the status code.

5. Streaming flow control has a narrow job

Flow control is relevant to streaming RPCs and helps prevent a fast sender from overwhelming a receiver. The framework may delay progress when the receiver cannot accept more data. A successful write handoff is not proof that a message is already on the network or processed by the peer.

The learner runtime uses large bounded messages and a deliberately slow receiver. It records write/yield timing so you can look for waiting attributable to the bounded local run. That observation remains implementation evidence for this fixture; it is not a universal throughput guarantee.

6. Transport flow control is not business admission control

A transport can slow a sender and still leave your application with an unsafe queue, an unbounded producer, or work that should have been rejected earlier. The lab therefore requires a separate application buffer/admission rule. The starter gives you a bounded queue parameter but does not choose the final overload policy for you.

Your record must keep these layers separate: gRPC transport flow control, application queue capacity, domain admission/rejection, and retry policy. This lesson owns only the first two boundaries plus a bounded decision; it does not design a production-wide overload architecture.

7. Cancellation propagation and cleanup

Cancellation may be triggered explicitly, by deadline expiry, or by I/O failure. The local server checks whether the RPC is still active and stops its worker loop when cancellation is observed. The fixture writes a raw cleanup observation but does not convert that observation into a reliability verdict.

In a real service that calls other services, deadline/cancellation propagation can matter as well. The official guidance notes that propagation support is language dependent. This lesson does not claim every runtime or call chain behaves identically.

8. Deadlock boundary in manual streaming

The flow-control guide warns that synchronous/manual streaming patterns can deadlock when both sides write heavily and neither reads. The lab does not create an uncontrolled hang. Instead, a bounded watchdog simulation models a write-heavy/no-read discipline and classifies the design as a deadlock risk when progress cannot occur within the fixed bound.

The repair is a read/write discipline, not “increase the timeout until it passes.” In the transfer task, define when each side reads, when it may write, and what bounded queue/admission rule applies.

9. Baseline and negative probes

The baseline uses a server-streaming inventory feed, a realistic explicit deadline, a bounded message count, and a receiver that consumes fast enough to finish. The negative probes then change one dimension at a time: no explicit deadline versus short deadline, slow receiver, active-work cancellation, and bounded write-heavy/no-read simulation.

Changing one dimension at a time matters because otherwise you cannot attribute the observation. The evidence table keeps each run traceable to a single reliability question.

10. What the runner may and may not decide

The runner may start a disposable loopback gRPC server, execute bounded local probes, and write raw observations: statuses, timing samples, cleanup markers, and queue/watchdog results. It may not decide that your production system is safe, select the correct deadline for every environment, or claim transport flow control is a complete backpressure policy.

The learner must complete the prediction and decision file first. Without that file and explicit --confirm-local, the runner exits fail-closed.

11. Evidence record

For each case fill these fields: RPC Shape / Direction / Deadline / Slow Receiver Condition / Write Observation / Cancellation Observation / Application Buffer/Admission Rule / Result / Residual Risk. Keep official facts and local observations in separate arrays.

A strong row is specific: “server-streaming; 180 ms deadline; receiver sleeps 60 ms/message; client observed DEADLINE_EXCEEDED; server cleanup marker true; queue bound 4; result bounded failure; residual risk: timing is local grpcio 1.80.0 evidence only.” A weak row says “backpressure works.”

12. Transfer — bidirectional command stream

Now both sides may emit bursts. Define an independent read/write discipline, deadline and cancellation behavior, and a bounded overload rule. Do not copy the server-streaming policy mechanically. A bidirectional stream has two independent directions; a design where both sides synchronously write until buffers fill and only then read is precisely the risk you must avoid.

The transfer is complete only when you can explain which rule belongs to gRPC transport and which belongs to your application policy.

13. Freshness and limits

The source boundary is exactly three official gRPC pages: Core Concepts, Deadlines, and Flow Control. They were rechecked on 2026-09-15 with no material drift in the claims owned by this lesson. Re-review is due by 2026-10-17 or earlier if those pages materially change.

This lesson does not prove production capacity, cross-language timing equivalence, optimal deadlines, broker-like durability, exactly-once delivery, or a complete overload-control architecture. The local runtime evidence is deliberately bounded.