From 2af4581a0abe55559ece95f1b542bb4a404f0d31 Mon Sep 17 00:00:00 2001
From: jdcormie <jdcormie@google.com>
Date: Fri, 7 Aug 2026 11:24:52 -0700
Subject: [PATCH] stub: Clarify flow control javadoc

Remove vestigial references to credit-based flow control and the
suggestion that a request() for messages directly corresponds to the
number of messages a peer could subsequently send before its end of the
stream went !isReady(). In fact, okhttp, netty and binder transports all
use buffers meaning the sender's stream can be isReady() even when the
receiver has no outstanding request()s for messages. Furthermore, those
buffers are sized in bytes and messages are not all the same size. So
consuming an inbound's next message may not cause a non-ready outbound
to become ready again.

Replace this with a short discussion of what is actually guaranteed by
every transport.
---
 .../java/io/grpc/stub/CallStreamObserver.java | 23 ++++++++++++++-----
 .../grpc/stub/ClientCallStreamObserver.java   |  3 +--
 .../grpc/stub/ServerCallStreamObserver.java   |  3 +--
 3 files changed, 19 insertions(+), 10 deletions(-)

diff --git a/stub/src/main/java/io/grpc/stub/CallStreamObserver.java b/stub/src/main/java/io/grpc/stub/CallStreamObserver.java
index 52dd046831d..ecdfbbbd941 100644
--- a/stub/src/main/java/io/grpc/stub/CallStreamObserver.java
+++ b/stub/src/main/java/io/grpc/stub/CallStreamObserver.java
@@ -47,6 +47,17 @@
  * <p>Like {@code StreamObserver}, implementations are not required to be thread-safe; if multiple
  * threads will be writing to an instance concurrently, the application must synchronize its calls.
  *
+ * <p>On flow control: {@link #isReady} returns whether an observer can accept more messages without
+ * excessive buffering. Readiness is affected by the volume of messages previously sent and how much
+ * of that data has been delivered to the peer application. This library considers delivery complete
+ * when the {@link #onNext} callback returns. Other gRPC libraries define this differently.
+ *
+ * <p>The link between local readiness and peer message consumption may not be immediate and may not
+ * be reflected message-for-message. All that's guaranteed is this: if an outbound is accepting
+ * messages but the peer is not consuming them, the outbound's {@link #isReady} will eventually
+ * return false. If, later, the peer does consume enough of those messages, the outbound observer
+ * will eventually become ready again.
+ *
  * <p>DO NOT MOCK: The API is too complex to reliably mock. Use InProcessChannelBuilder to create
  * "real" RPCs suitable for testing.
  *
@@ -87,9 +98,10 @@ public abstract class CallStreamObserver<V> implements StreamObserver<V> {
   public abstract void setOnReadyHandler(Runnable onReadyHandler);
 
   /**
-   * Disables automatic flow control where a token is returned to the peer after a call
-   * to the 'inbound' {@link io.grpc.stub.StreamObserver#onNext(Object)} has completed. If disabled
-   * an application must make explicit calls to {@link #request} to receive messages.
+   * Disables automatic flow control, a mode where another message is implicitly {@link #request}ed
+   * after each call to the inbound's {@link StreamObserver#onNext(Object)} returns.
+   *
+   * <p>If disabled an application must make explicit calls to {@link #request} to receive messages.
    *
    * <p>On client-side this method may only be called during {@link
    * ClientResponseObserver#beforeStart}. On server-side it may only be called during the initial
@@ -108,7 +120,7 @@ public abstract class CallStreamObserver<V> implements StreamObserver<V> {
    *   </li>
    * </ul>
    * </p>
-   * 
+   *
    * <p>This API is being replaced, but is not yet deprecated. On server-side it being replaced
    * with {@link ServerCallStreamObserver#disableAutoRequest}. On client-side {@link
    * ClientCallStreamObserver#disableAutoRequestWithInitial disableAutoRequestWithInitial(1)}.
@@ -116,8 +128,7 @@ public abstract class CallStreamObserver<V> implements StreamObserver<V> {
   public abstract void disableAutoInboundFlowControl();
 
   /**
-   * Requests the peer to produce {@code count} more messages to be delivered to the 'inbound'
-   * {@link StreamObserver}.
+   * Requests that {@code count} more messages be delivered to the 'inbound' {@link StreamObserver}.
    *
    * <p>This method is safe to call from multiple threads without external synchronization.
    *
diff --git a/stub/src/main/java/io/grpc/stub/ClientCallStreamObserver.java b/stub/src/main/java/io/grpc/stub/ClientCallStreamObserver.java
index 8f420fa77e4..4a173520359 100644
--- a/stub/src/main/java/io/grpc/stub/ClientCallStreamObserver.java
+++ b/stub/src/main/java/io/grpc/stub/ClientCallStreamObserver.java
@@ -92,8 +92,7 @@ public void disableAutoRequestWithInitial(int request) {
   public abstract void setOnReadyHandler(Runnable onReadyHandler);
 
   /**
-   * Requests the peer to produce {@code count} more messages to be delivered to the 'inbound'
-   * {@link StreamObserver}.
+   * Requests that {@code count} more messages be delivered to the 'inbound' {@link StreamObserver}.
    *
    * <p>This method is safe to call from multiple threads without external synchronization.
    *
diff --git a/stub/src/main/java/io/grpc/stub/ServerCallStreamObserver.java b/stub/src/main/java/io/grpc/stub/ServerCallStreamObserver.java
index 6ffea3500cc..cc5fbaf3fb0 100644
--- a/stub/src/main/java/io/grpc/stub/ServerCallStreamObserver.java
+++ b/stub/src/main/java/io/grpc/stub/ServerCallStreamObserver.java
@@ -147,8 +147,7 @@ public void disableAutoRequest() {
   public abstract void setOnReadyHandler(Runnable onReadyHandler);
 
   /**
-   * Requests the peer to produce {@code count} more messages to be delivered to the 'inbound'
-   * {@link StreamObserver}.
+   * Requests that {@code count} more messages be delivered to the 'inbound' {@link StreamObserver}.
    *
    * <p>This method is safe to call from multiple threads without external synchronization.
    *