From 5fd0f6087be823e5595b8ca067dee9cd28c31c69 Mon Sep 17 00:00:00 2001
From: Marten Richter <marten.richter@tu-berlin.de>
Date: Sun, 6 Sep 2026 19:19:35 +0200
Subject: [PATCH 1/6] quic: add promise to QuicStream for pending strms

before this PR, it was necessary to poll, if a
stream can not be created immediately due to
flow control.
This PR adds a promise to QuicStream, that fulfills,
when a stream is available and ready.

Signed-off-by: Marten Richter <marten.richter@freenet.de>
---
 doc/api/quic.md                               | 13 ++++++++
 lib/internal/quic/quic.js                     | 33 +++++++++++++++++++
 lib/internal/quic/symbols.js                  |  2 ++
 src/quic/bindingdata.h                        |  1 +
 src/quic/streams.cc                           | 13 +++++++-
 src/quic/streams.h                            |  4 +++
 .../test-quic-internal-setcallbacks.mjs       |  1 +
 .../test-quic-stream-limits-pending.mjs       | 12 +++++++
 test/parallel/test-quic-stream-limits-uni.mjs | 13 ++++++++
 typings/internalBinding/quic.d.ts             |  1 +
 10 files changed, 92 insertions(+), 1 deletion(-)

diff --git a/doc/api/quic.md b/doc/api/quic.md
index 9cbff24bc086..12fc7339625d 100644
--- a/doc/api/quic.md
+++ b/doc/api/quic.md
@@ -1921,6 +1921,19 @@ Either `'application'` or `'transport'`. Indicates the namespace of
 added: v23.8.0
 -->
 
+### `stream.ready`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+* Type: {Promise}
+
+A promise that is immediately fulfilled, if the stream fits within
+flow control limits or fulfilled when the pending stream is created.
+It rejects, if a pending stream is closed with an error before being
+created.
+
 ### `stream.closed`
 
 <!-- YAML
diff --git a/lib/internal/quic/quic.js b/lib/internal/quic/quic.js
index 95288775d42a..596a85d32a46 100644
--- a/lib/internal/quic/quic.js
+++ b/lib/internal/quic/quic.js
@@ -184,6 +184,7 @@ const kEmptyObject = { __proto__: null };
 
 const {
   kAttachFileHandle,
+  kAvailable,
   kBlocked,
   kConnect,
   kDatagram,
@@ -948,6 +949,11 @@ setCallbacks({
   },
 
   // QuicStream callbacks
+  onStreamAvailable() {
+    debug('stream available callback', this[kOwner]);
+    this[kOwner][kAvailable]();
+  },
+
   onStreamBlocked() {
     debug('stream blocked callback', this[kOwner]);
     // Called when the stream C++ handle has been blocked by flow control.
@@ -1602,6 +1608,7 @@ class QuicStream {
     fileHandle: undefined,
     headers: undefined,
     pendingTrailers: undefined,
+    pendingStream: PromiseWithResolvers(),
     onerror: undefined,
     onblocked: undefined,
     onreset: undefined,
@@ -1655,6 +1662,10 @@ class QuicStream {
     inner.state = new QuicStreamState(
       kPrivateConstructor, handle.state, handle.stateByteOffset);
 
+    if (!inner.state.pending) {
+      inner.pendingStream.resolve();
+    }
+
     if (hasObserver('quic')) {
       startPerf(this, kPerfEntry, { type: 'quic', name: 'QuicStream' });
     }
@@ -1719,6 +1730,15 @@ class QuicStream {
     return this.#inner.state.pending;
   }
 
+  /**
+   * Promise that resolves once the stream is available and not pending.
+   * @type {Promise<void>}
+   */
+  get ready() {
+    assertIsQuicStream(this);
+    return this.#inner.pendingStream.promise;
+  }
+
   /**
    * True if any data on this stream was received as 0-RTT (early data)
    * before the TLS handshake completed. Early data is less secure and
@@ -2597,6 +2617,13 @@ class QuicStream {
     } else {
       inner.pendingClose.resolve();
     }
+    if (inner.pending) {
+      if (error !== undefined) {
+        inner.pendingStream.reject(error);
+      } else {
+        inner.pendingStream.resolve(error);
+      }
+    }
     debug('stream closed');
     if (onStreamClosedChannel.hasSubscribers) {
       onStreamClosedChannel.publish({
@@ -2642,6 +2669,12 @@ class QuicStream {
     }
   }
 
+  [kAvailable]() {
+    // The formerly pending stream is now available
+    const inner = this.#inner;
+    inner.pendingStream.resolve();
+  }
+
   [kBlocked]() {
     const inner = this.#inner;
     // The blocked event should only be called if the stream was created with
diff --git a/lib/internal/quic/symbols.js b/lib/internal/quic/symbols.js
index 60d9d7084a01..1ed44ebe2b13 100644
--- a/lib/internal/quic/symbols.js
+++ b/lib/internal/quic/symbols.js
@@ -28,6 +28,7 @@ const {
 // public API.
 
 const kAttachFileHandle = Symbol('kAttachFileHandle');
+const kAvailable = Symbol('kAvailable');
 const kBlocked = Symbol('kBlocked');
 const kConnect = Symbol('kConnect');
 const kDrain = Symbol('kDrain');
@@ -63,6 +64,7 @@ const kVersionNegotiation = Symbol('kVersionNegotiation');
 
 module.exports = {
   kAttachFileHandle,
+  kAvailable,
   kBlocked,
   kConnect,
   kDatagram,
diff --git a/src/quic/bindingdata.h b/src/quic/bindingdata.h
index e56c861261ad..96ac6a349182 100644
--- a/src/quic/bindingdata.h
+++ b/src/quic/bindingdata.h
@@ -55,6 +55,7 @@ class SessionManager;
   V(session_path_validation, SessionPathValidation)                            \
   V(session_ticket, SessionTicket)                                             \
   V(session_version_negotiation, SessionVersionNegotiation)                    \
+  V(stream_available, StreamAvailable)                                         \
   V(stream_blocked, StreamBlocked)                                             \
   V(stream_close, StreamClose)                                                 \
   V(stream_created, StreamCreated)                                             \
diff --git a/src/quic/streams.cc b/src/quic/streams.cc
index 9a11bb4d591e..b49b40a41ac7 100644
--- a/src/quic/streams.cc
+++ b/src/quic/streams.cc
@@ -1191,12 +1191,15 @@ void Stream::NotifyStreamOpened(stream_id id) {
   // yet, but just for completeness, let's make sure.
   if (outbound_) session().ResumeStream(id);
 
+  // We inform, the js side that the pending stream is now available
+  EmitStreamAvailable();
+
   // This may make application data sendable, so keep it as the final action:
   // sending can eventually call into JavaScript and destroy the stream.
   BaseObjectPtr<Stream> self(this);
   auto& application = session().application();
-  error_code internal_error = application.GetInternalErrorCode();
   if (!application.StreamOpened(*this) && !is_destroyed()) {
+    error_code internal_error = application.GetInternalErrorCode();
     Destroy(QuicError::ForApplication(internal_error));
   }
 }
@@ -1779,6 +1782,14 @@ void Stream::SendStopSending(error_code code) {
 
 // ============================================================================
 
+void Stream::EmitStreamAvailable() {
+  if (!env()->can_call_into_js()) {
+    return;
+  }
+  CallbackScope<Stream> cb_scope(this);
+  MakeCallback(BindingData::Get(env()).stream_available_callback(), 0, nullptr);
+}
+
 void Stream::EmitBlocked() {
   // state()->wants_block will be set from the javascript side if the
   // stream object has a handler for the blocked event.
diff --git a/src/quic/streams.h b/src/quic/streams.h
index 1ea85f216524..182237c6334d 100644
--- a/src/quic/streams.h
+++ b/src/quic/streams.h
@@ -433,6 +433,10 @@ class Stream final : public AsyncWrap,
 
   // JavaScript callouts
 
+  // Notifies the JavaScript side that a previously pending stream
+  // is now available.
+  void EmitStreamAvailable();
+
   // Notifies the JavaScript side that the stream has been destroyed.
   void EmitClose(const QuicError& error);
 
diff --git a/test/parallel/test-quic-internal-setcallbacks.mjs b/test/parallel/test-quic-internal-setcallbacks.mjs
index 08d4c1bbfc9a..910f1fa97a74 100644
--- a/test/parallel/test-quic-internal-setcallbacks.mjs
+++ b/test/parallel/test-quic-internal-setcallbacks.mjs
@@ -26,6 +26,7 @@ const callbacks = {
   onSessionOrigin() {},
   onSessionGoaway() {},
   onSessionVersionNegotiation() {},
+  onStreamAvailable() {},
   onStreamCreated() {},
   onStreamBlocked() {},
   onStreamClose() {},
diff --git a/test/parallel/test-quic-stream-limits-pending.mjs b/test/parallel/test-quic-stream-limits-pending.mjs
index bd7bcd51fff8..f2e06a18387f 100644
--- a/test/parallel/test-quic-stream-limits-pending.mjs
+++ b/test/parallel/test-quic-stream-limits-pending.mjs
@@ -38,20 +38,31 @@ const serverEndpoint = await listen(mustCall((serverSession) => {
 const clientSession = await connect(serverEndpoint.address);
 await clientSession.opened;
 
+let ready = 0;
+
 // First stream opens immediately (within the limit).
 const s1 = await clientSession.createBidirectionalStream({
   body: encoder.encode('stream 1'),
 });
 
+s1.ready.then(() => {
+  ready++;
+});
+
 // Second stream is created but queued as pending because the
 // server only allows 1 concurrent bidi stream.
 const s2 = await clientSession.createBidirectionalStream({
   body: encoder.encode('stream 2'),
 });
 
+s2.ready.then(() => {
+  ready++;
+});
+
 // s2 should be pending until s1 closes and the server grants
 // more stream credits.
 assert.strictEqual(s2.pending, true);
+assert.strictEqual(ready, 1);
 
 // Drain and close the first stream.
 for await (const _ of s1) { /* drain */ } // eslint-disable-line no-unused-vars
@@ -60,6 +71,7 @@ await s1.closed;
 // After s1 closes, the server sends MAX_STREAMS which opens s2.
 // Wait for the server to receive both streams.
 await allDone.promise;
+assert.strictEqual(ready, 2);
 
 // s2 should no longer be pending.
 for await (const _ of s2) { /* drain */ } // eslint-disable-line no-unused-vars
diff --git a/test/parallel/test-quic-stream-limits-uni.mjs b/test/parallel/test-quic-stream-limits-uni.mjs
index a7427508ca1a..01c821f3f879 100644
--- a/test/parallel/test-quic-stream-limits-uni.mjs
+++ b/test/parallel/test-quic-stream-limits-uni.mjs
@@ -34,20 +34,33 @@ const serverEndpoint = await listen(mustCall((serverSession) => {
 const clientSession = await connect(serverEndpoint.address);
 await clientSession.opened;
 
+let ready = 0;
+
 // First uni stream opens immediately.
 const s1 = await clientSession.createUnidirectionalStream({
   body: encoder.encode('uni 1'),
 });
 
+s1.ready.then(() => {
+  ready++;
+});
+
 // Second uni stream is pending (limit = 1).
 const s2 = await clientSession.createUnidirectionalStream({
   body: encoder.encode('uni 2'),
 });
+
+s2.ready.then(() => {
+  ready++;
+});
+assert.strictEqual(ready, 1);
+
 assert.strictEqual(s2.pending, true);
 
 // Wait for both to complete.
 await s1.closed;
 await allDone.promise;
+assert.strictEqual(ready, 2);
 await s2.closed;
 
 await clientSession.close();
diff --git a/typings/internalBinding/quic.d.ts b/typings/internalBinding/quic.d.ts
index ef4c2b81684c..8d7adb1a4ed5 100644
--- a/typings/internalBinding/quic.d.ts
+++ b/typings/internalBinding/quic.d.ts
@@ -19,6 +19,7 @@ interface QuicCallbacks {
                                 versions: number[],
                                 supports: number[]) => void;
   onStreamCreated: (stream: Stream) => void;
+  onStreamAvailable: () => void;
   onStreamBlocked: () => void;
   onStreamClose: (error: [number,bigint,string]) => void;
   onStreamReset: (error: [number,bigint,string]) => void;

From 5f205d51b7acf578708a5b7ec37126c75a23ea50 Mon Sep 17 00:00:00 2001
From: Marten Richter <marten.richter@tu-berlin.de>
Date: Sun, 6 Sep 2026 19:57:55 +0200
Subject: [PATCH 2/6] quic: fix lint

---
 test/parallel/test-quic-stream-limits-pending.mjs | 2 ++
 test/parallel/test-quic-stream-limits-uni.mjs     | 2 ++
 2 files changed, 4 insertions(+)

diff --git a/test/parallel/test-quic-stream-limits-pending.mjs b/test/parallel/test-quic-stream-limits-pending.mjs
index f2e06a18387f..a1c9a569be6f 100644
--- a/test/parallel/test-quic-stream-limits-pending.mjs
+++ b/test/parallel/test-quic-stream-limits-pending.mjs
@@ -45,6 +45,7 @@ const s1 = await clientSession.createBidirectionalStream({
   body: encoder.encode('stream 1'),
 });
 
+// eslint-disable-next-line node-core/must-call-assert
 s1.ready.then(() => {
   ready++;
 });
@@ -55,6 +56,7 @@ const s2 = await clientSession.createBidirectionalStream({
   body: encoder.encode('stream 2'),
 });
 
+// eslint-disable-next-line node-core/must-call-assert
 s2.ready.then(() => {
   ready++;
 });
diff --git a/test/parallel/test-quic-stream-limits-uni.mjs b/test/parallel/test-quic-stream-limits-uni.mjs
index 01c821f3f879..a2353b0bfb24 100644
--- a/test/parallel/test-quic-stream-limits-uni.mjs
+++ b/test/parallel/test-quic-stream-limits-uni.mjs
@@ -41,6 +41,7 @@ const s1 = await clientSession.createUnidirectionalStream({
   body: encoder.encode('uni 1'),
 });
 
+// eslint-disable-next-line node-core/must-call-assert
 s1.ready.then(() => {
   ready++;
 });
@@ -50,6 +51,7 @@ const s2 = await clientSession.createUnidirectionalStream({
   body: encoder.encode('uni 2'),
 });
 
+// eslint-disable-next-line node-core/must-call-assert
 s2.ready.then(() => {
   ready++;
 });

From a21a26e5f1c0b2fe60b409b9bb931c8cc8949801 Mon Sep 17 00:00:00 2001
From: Marten Richter <marten.richter@tu-berlin.de>
Date: Tue, 8 Sep 2026 07:54:12 +0200
Subject: [PATCH 3/6] quic: use opened instead ready for QuicStream

---
 doc/api/quic.md                                   |  2 +-
 lib/internal/quic/quic.js                         |  2 +-
 test/parallel/test-quic-stream-limits-pending.mjs | 14 +++++++-------
 test/parallel/test-quic-stream-limits-uni.mjs     | 14 +++++++-------
 4 files changed, 16 insertions(+), 16 deletions(-)

diff --git a/doc/api/quic.md b/doc/api/quic.md
index 12fc7339625d..c960f8a8aad2 100644
--- a/doc/api/quic.md
+++ b/doc/api/quic.md
@@ -1921,7 +1921,7 @@ Either `'application'` or `'transport'`. Indicates the namespace of
 added: v23.8.0
 -->
 
-### `stream.ready`
+### `stream.open`
 
 <!-- YAML
 added: REPLACEME
diff --git a/lib/internal/quic/quic.js b/lib/internal/quic/quic.js
index 596a85d32a46..d33f600f2b87 100644
--- a/lib/internal/quic/quic.js
+++ b/lib/internal/quic/quic.js
@@ -1734,7 +1734,7 @@ class QuicStream {
    * Promise that resolves once the stream is available and not pending.
    * @type {Promise<void>}
    */
-  get ready() {
+  get opened() {
     assertIsQuicStream(this);
     return this.#inner.pendingStream.promise;
   }
diff --git a/test/parallel/test-quic-stream-limits-pending.mjs b/test/parallel/test-quic-stream-limits-pending.mjs
index a1c9a569be6f..570a1369719e 100644
--- a/test/parallel/test-quic-stream-limits-pending.mjs
+++ b/test/parallel/test-quic-stream-limits-pending.mjs
@@ -38,7 +38,7 @@ const serverEndpoint = await listen(mustCall((serverSession) => {
 const clientSession = await connect(serverEndpoint.address);
 await clientSession.opened;
 
-let ready = 0;
+let opened = 0;
 
 // First stream opens immediately (within the limit).
 const s1 = await clientSession.createBidirectionalStream({
@@ -46,8 +46,8 @@ const s1 = await clientSession.createBidirectionalStream({
 });
 
 // eslint-disable-next-line node-core/must-call-assert
-s1.ready.then(() => {
-  ready++;
+s1.opened.then(() => {
+  opened++;
 });
 
 // Second stream is created but queued as pending because the
@@ -57,14 +57,14 @@ const s2 = await clientSession.createBidirectionalStream({
 });
 
 // eslint-disable-next-line node-core/must-call-assert
-s2.ready.then(() => {
-  ready++;
+s2.opened.then(() => {
+  opened++;
 });
 
 // s2 should be pending until s1 closes and the server grants
 // more stream credits.
 assert.strictEqual(s2.pending, true);
-assert.strictEqual(ready, 1);
+assert.strictEqual(opened, 1);
 
 // Drain and close the first stream.
 for await (const _ of s1) { /* drain */ } // eslint-disable-line no-unused-vars
@@ -73,7 +73,7 @@ await s1.closed;
 // After s1 closes, the server sends MAX_STREAMS which opens s2.
 // Wait for the server to receive both streams.
 await allDone.promise;
-assert.strictEqual(ready, 2);
+assert.strictEqual(opened, 2);
 
 // s2 should no longer be pending.
 for await (const _ of s2) { /* drain */ } // eslint-disable-line no-unused-vars
diff --git a/test/parallel/test-quic-stream-limits-uni.mjs b/test/parallel/test-quic-stream-limits-uni.mjs
index a2353b0bfb24..f3686ca45e3c 100644
--- a/test/parallel/test-quic-stream-limits-uni.mjs
+++ b/test/parallel/test-quic-stream-limits-uni.mjs
@@ -34,7 +34,7 @@ const serverEndpoint = await listen(mustCall((serverSession) => {
 const clientSession = await connect(serverEndpoint.address);
 await clientSession.opened;
 
-let ready = 0;
+let opened = 0;
 
 // First uni stream opens immediately.
 const s1 = await clientSession.createUnidirectionalStream({
@@ -42,8 +42,8 @@ const s1 = await clientSession.createUnidirectionalStream({
 });
 
 // eslint-disable-next-line node-core/must-call-assert
-s1.ready.then(() => {
-  ready++;
+s1.opened.then(() => {
+  opened++;
 });
 
 // Second uni stream is pending (limit = 1).
@@ -52,17 +52,17 @@ const s2 = await clientSession.createUnidirectionalStream({
 });
 
 // eslint-disable-next-line node-core/must-call-assert
-s2.ready.then(() => {
-  ready++;
+s2.opened.then(() => {
+  opened++;
 });
-assert.strictEqual(ready, 1);
+assert.strictEqual(opened, 1);
 
 assert.strictEqual(s2.pending, true);
 
 // Wait for both to complete.
 await s1.closed;
 await allDone.promise;
-assert.strictEqual(ready, 2);
+assert.strictEqual(opened, 2);
 await s2.closed;
 
 await clientSession.close();

From dc01a8d76443ad419384875a13c19fb386b82ba4 Mon Sep 17 00:00:00 2001
From: Marten Richter <marten.richter@tu-berlin.de>
Date: Tue, 8 Sep 2026 08:07:27 +0200
Subject: [PATCH 4/6] quic: fix rejection of opened promise and add test

---
 lib/internal/quic/quic.js                         |  2 +-
 test/parallel/test-quic-stream-limits-pending.mjs | 15 ++++++++++++++-
 2 files changed, 15 insertions(+), 2 deletions(-)

diff --git a/lib/internal/quic/quic.js b/lib/internal/quic/quic.js
index d33f600f2b87..33e419002495 100644
--- a/lib/internal/quic/quic.js
+++ b/lib/internal/quic/quic.js
@@ -2617,7 +2617,7 @@ class QuicStream {
     } else {
       inner.pendingClose.resolve();
     }
-    if (inner.pending) {
+    if (inner.state.pending) {
       if (error !== undefined) {
         inner.pendingStream.reject(error);
       } else {
diff --git a/test/parallel/test-quic-stream-limits-pending.mjs b/test/parallel/test-quic-stream-limits-pending.mjs
index 570a1369719e..76cd932df888 100644
--- a/test/parallel/test-quic-stream-limits-pending.mjs
+++ b/test/parallel/test-quic-stream-limits-pending.mjs
@@ -6,7 +6,7 @@
 //         and open when existing streams close.
 // initialMaxStreamsUni limits concurrent uni streams (same behavior).
 
-import { hasQuic, skip, mustCall } from '../common/index.mjs';
+import { hasQuic, skip, mustCall, mustNotCall } from '../common/index.mjs';
 import assert from 'node:assert';
 
 if (!hasQuic) {
@@ -61,6 +61,13 @@ s2.opened.then(() => {
   opened++;
 });
 
+// Third stream is created but queued as pending because the
+// server only allows 1 concurrent bidi stream.
+const s3 = await clientSession.createBidirectionalStream({
+  body: encoder.encode('stream 3'),
+});
+
+
 // s2 should be pending until s1 closes and the server grants
 // more stream credits.
 assert.strictEqual(s2.pending, true);
@@ -70,6 +77,12 @@ assert.strictEqual(opened, 1);
 for await (const _ of s1) { /* drain */ } // eslint-disable-line no-unused-vars
 await s1.closed;
 
+const err = new Error('Test error');
+s3.destroy(err);
+
+await assert.rejects(stream.closed, err);
+
+
 // After s1 closes, the server sends MAX_STREAMS which opens s2.
 // Wait for the server to receive both streams.
 await allDone.promise;

From 5570ac6d40c61c71463ae2ae6137678c41af0a65 Mon Sep 17 00:00:00 2001
From: Marten Richter <marten.richter@tu-berlin.de>
Date: Tue, 8 Sep 2026 08:21:07 +0200
Subject: [PATCH 5/6] quic: fix lint and test

---
 test/parallel/test-quic-stream-limits-pending.mjs | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/test/parallel/test-quic-stream-limits-pending.mjs b/test/parallel/test-quic-stream-limits-pending.mjs
index 76cd932df888..2d81b0d79096 100644
--- a/test/parallel/test-quic-stream-limits-pending.mjs
+++ b/test/parallel/test-quic-stream-limits-pending.mjs
@@ -6,7 +6,7 @@
 //         and open when existing streams close.
 // initialMaxStreamsUni limits concurrent uni streams (same behavior).
 
-import { hasQuic, skip, mustCall, mustNotCall } from '../common/index.mjs';
+import { hasQuic, skip, mustCall } from '../common/index.mjs';
 import assert from 'node:assert';
 
 if (!hasQuic) {
@@ -80,7 +80,7 @@ await s1.closed;
 const err = new Error('Test error');
 s3.destroy(err);
 
-await assert.rejects(stream.closed, err);
+await Promise.all([assert.rejects(s3.opened, err), assert.rejects(s3.closed, err)]);
 
 
 // After s1 closes, the server sends MAX_STREAMS which opens s2.

From ddfdc5dd054eec1687c8ab34294a0085c4ce227e Mon Sep 17 00:00:00 2001
From: Marten Richter <marten.richter@tu-berlin.de>
Date: Wed, 9 Sep 2026 07:59:11 +0200
Subject: [PATCH 6/6] quic: fix doc opened instead of open

---
 doc/api/quic.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/doc/api/quic.md b/doc/api/quic.md
index c960f8a8aad2..19995000b20e 100644
--- a/doc/api/quic.md
+++ b/doc/api/quic.md
@@ -1921,7 +1921,7 @@ Either `'application'` or `'transport'`. Indicates the namespace of
 added: v23.8.0
 -->
 
-### `stream.open`
+### `stream.opened`
 
 <!-- YAML
 added: REPLACEME