From 6689061ec44a66470615d98aea3074df9403405f Mon Sep 17 00:00:00 2001
From: Rui Fan <1996fanrui@gmail.com>
Date: Tue, 15 Sep 2026 12:21:25 +0200
Subject: [PATCH] [FLINK-40668][network] Document why the recovery drain cannot
 stall on zero-credit needsRecovery channels

---
 .../io/network/partition/consumer/RemoteInputChannel.java     | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/flink-runtime/src/main/java/org/apache/flink/runtime/io/network/partition/consumer/RemoteInputChannel.java b/flink-runtime/src/main/java/org/apache/flink/runtime/io/network/partition/consumer/RemoteInputChannel.java
index c22ba964ae19a..7d6c98d73e9f2 100644
--- a/flink-runtime/src/main/java/org/apache/flink/runtime/io/network/partition/consumer/RemoteInputChannel.java
+++ b/flink-runtime/src/main/java/org/apache/flink/runtime/io/network/partition/consumer/RemoteInputChannel.java
@@ -784,7 +784,9 @@ public void onBuffer(Buffer buffer, int sequenceNumber, int backlog, int subpart
         boolean recycleBuffer = true;
 
         // The first buffer from the producer proves the upstream reader is registered and the
-        // connection is live; release any recovery-side awaiter. On later buffers this is a cheap
+        // connection is live; release any recovery-side awaiter (see requestRecoveryBufferBlocking).
+        // During recovery this first arrival is typically the upstream's EndOfOutputChannelStateEvent,
+        // which is guaranteed and passes the zero-credit gate. On later buffers this is a cheap
         // idempotent no-op (the latch count is already zero).
         upstreamReady.countDown();