quic: add option waitUntilAvailable to creating streams by martenrichter · Pull Request #65331 · nodejs/node

martenrichter · 2026-08-16T18:20:40Z

We add an option to createBidirectionalStream and
createUnidirectionalStream to fail immediately,
if the flow control's stream budget does not
allow stream creation.
The behavior matches W3C webtransport's behavior.

Fixes #65321

nodejs-github-bot · 2026-08-16T18:20:46Z

Review requested:

@nodejs/quic

codecov · 2026-08-16T20:00:08Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 90.36%. Comparing base (8812357) to head (f450014).
⚠️ Report is 36 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main   #65331      +/-   ##
==========================================
- Coverage   90.36%   90.36%   -0.01%     
==========================================
  Files         790      792       +2     
  Lines      274292   275325    +1033     
  Branches    52510    52757     +247     
==========================================
+ Hits       247874   248788     +914     
- Misses      16901    16964      +63     
- Partials     9517     9573      +56

Files with missing lines	Coverage Δ
lib/internal/quic/quic.js	`100.00% <100.00%> (ø)`

... and 53 files with indirect coverage changes

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

jasnell · 2026-08-17T03:06:43Z

 });

-// Second stream is created but queued as pending because the
+try {


Use assert.rejects(...)?

jasnell · 2026-08-17T03:07:10Z

-  body: encoder.encode('stream 2'),
+const s3 = await clientSession.createBidirectionalStream({
+  body: encoder.encode('stream 3'),
+  waitUntilAvailable: true


This is the default right?

jasnell · 2026-08-17T03:07:40Z

+  waitUntilAvailable: false
+});
+await s4.closed;
+await allDone.promise;


await Promise.all([s4.closed, allDone.promise]);

jasnell · 2026-08-17T03:08:04Z

@@ -42,6 +42,7 @@ const s1 = await clientSession.createUnidirectionalStream({
 // Second uni stream is pending (limit = 1).
 const s2 = await clientSession.createUnidirectionalStream({
  body: encoder.encode('uni 2'),
+  waitUntilAvailable: true,


If waitUntilAvailable: true is the default we don't need to change all these, right?

No you suggested to default it to false.

Which matches W3C

Sorry, that was a mistake on my part. Since it returns a promise for the stream, I think it's more ergonomic to wait by default. The Web Transport API impl can easily pass false but I think what most users would likely typically expect is that the promise resolves with the stream when the stream is actually available.

Ok, I will change this.

jasnell · 2026-08-17T03:09:44Z

    writing more. **Default:** `65536` (64 KB).
+  * `waitUntilAvailable` {boolean} When true the promise will wait until flow
+    control will allow to open the stream. If set to false, the function
+    will fail synchronously, if flow control will not allow to open the stream


These methods return a promise. While it may fail synchronously internally, it should return a rejected promise and not throw synchronously.

Do you have the C++ command in mind?

Or will it be automatically like this through the js side and I do not have to change anything on the c++ side?

jasnell · 2026-08-17T03:10:23Z

+    control will allow to open the stream. If set to false, the function
+    will fail synchronously, if flow control will not allow to open the stream
+    immediately.
+    **Default:** `false`


Default should be true I think... just from an ergonomics point of view.

Your initial suggestion was in the other direction. W3C WT uses also false.
P.S: I have to leave my dev machine for a while, so I might not update this for a while.

I have tried to fix the remaining stuff using the github web ui....

martenrichter · 2026-09-03T15:33:47Z

@jasnell I just ping this, was not on the dashboard in the call. It should be almost ready, I will test it at the weekend. (Btw. where is the quic dashboard, I do not find it in this repo)

jasnell · 2026-09-05T02:53:57Z

Added to the project board! will try to do a follow up review on monday

martenrichter · 2026-09-05T05:58:47Z

@jasnell and where can I find the project board ?

pimterry · 2026-09-05T08:57:48Z

It's at https://github.com/orgs/nodejs/projects/17/ @martenrichter, I think it's marked as private so you won't be able to see it though, that's probably the issue. @jasnell is that intentional? Could just be public. I can't change it, it says org owners only.

martenrichter · 2026-09-05T09:03:11Z

Yes, I get a 404 .

martenrichter · 2026-09-05T16:41:18Z

I am currently testing some tests, that verify, if stream limits are respected. But it does not seem to be the case. I will investigate and report back if this PR is affected or if the problem is with another part of the code.

martenrichter · 2026-09-05T17:22:17Z

Well, interesting #createStream in QuicSession is async but has no async operation in it.

If a stream, due to stream limits, is not immediately created, the #createStream promise will return nevertheless.
One can only synchronously poll the pending property or use the session's onstream callback.
I wonder if this is a good api, or if we should instead:
(i) not return immediately for a pending stream and settle the promise once it arrive. Though one could not manipulate the stream then, or
(ii) offer a promise or other callback on the QuicStream to wait asynchronously for materilization of the pending stream.

@pimterry @jasnell what do you think?

martenrichter · 2026-09-05T18:01:41Z

Correction: you do not seem to get a pending stream through onstream .

jasnell · 2026-09-06T15:40:04Z

The design intent here was to return the QuicStream object as quickly as possible even if the stream itself is still pending to be opened... to be able to set things like error handlers or start queuing up outbound data optimistically. I think maybe the best approach would be ii... offering a promise on the QuicStream that is resolved when the stream is materialized.

martenrichter · 2026-09-06T15:41:56Z

Ok, I agree, a separate PR is almost ready, just the last bugs needs to be found.

martenrichter · 2026-09-06T17:48:49Z

Added a separate PR #65862 for the other issue.
My webtransport tests for stream limits work fine after these to PRs.

pimterry · 2026-09-07T16:23:38Z

Ok, so we're going to make createStream sync once #65862 is in place then? That makes total sense to me, seems cleaner and it's nice to be able to drop a promise step completely.

If we do that, waitUntilAvailable as is doesn't make much sense though, since nothing ever waits at all.

Maybe we should just expose the remaining budget directly, so cases who care about the budget before they open the stream can precisely check it instead? More flexible, and easy to do: just exposing ngtcp2_conn_get_streams_bidi_left2 and ngtcp2_conn_get_streams_uni_left2 to JS, or zero if the session isn't yet open or already closed.

martenrichter · 2026-09-07T16:30:02Z

Well the name waitUntilAvailable comes from Webtransport, and yes I assumed, that we were waiting for the stream.

Exposing the budget would be an alternative. But we can't put it in state, as we would also have a caching issue.
I do not have much experinence with speed, would such a call into C++ be expensive? As in this scenario, a caller would have to cross the js to c++ barrier twice.

May be we just rename it to failIfNotAvailable? (Or anything similar, may be a better idea from native speakers.

pimterry · 2026-09-07T16:53:18Z

I think the performance cost is roughly the same in either case (querying the budget or passing failIfNotAvailable): either we go into C++ to create the stream and then back to JS to fail, or we go into C++ to query the budget and then back to JS to report it. In theory we could cache the budget though, if we need to, by updating it whenever a stream opens or MAX_STREAMS frames arrive (extend_max_local_streams_bidi/uni callbacks).

Different is mostly API UX, so I guess it depends how people will use this. Exposing the budget gives you strictly more information (maybe you want to create 2 streams, and know that you have enough budget for both beforehand) but it's slightly less convenient to check it and throw yourself, instead of just passing failIfNotAvailable: true for the very simple case. I'm not sure how people would actually want to use this though, any idea?

martenrichter · 2026-09-07T16:59:03Z

I am also not sure. These last two issues just came up, when I tried to implement W3C webtransport.
Though I know many people use my lib for games and open constantly streams and close them. (I do audio/video transmission, but I reuse streams, as early UA implementation had issues with properly closing streams). Though waitUntilAvailable is a newer option. (I think it was established, if I remember correctly, as Chromium and Firefox behaved differently on creating streams, and in the end they added an option for both behaviors).

martenrichter · 2026-09-08T06:10:49Z

Btw. I did not remove the async yet. I just noted that it is currently not used. There may be some benefits to keep it, for example, we could use async commands in the future.

We add an option to createBidirectionalStream and createUnidirectionalStream to fail immediately, if the flow control's stream budget does not allow stream creation. The behavior matches W3C webtransport's behavior. Fixes nodejs#65321 Signed-off-by: Marten Richter <marten.richter@freenet.de>

martenrichter · 2026-09-27T05:55:38Z

Sorry for the lack of progress; I was away for the last few weeks. I have been back and rebasing my PRs since yesterday, which has taken some time due to the refactoring.
Here, it seems that some new issues with stream flow control were introduced. I am checking this locally and will report back and likely fix it in this PR. (I am waiting for the force push until I have found the underlying reason.)

jasnell · 2026-09-27T06:00:28Z

Yeah I spotted an issue earlier this week that I think was introduced by the byte budget changes. Haven't had the opportunity to track it down yet

martenrichter · 2026-09-27T06:05:07Z

Well, then I will start with tracking it down now; the test in this PR seems to be susceptible to it.

martenrichter · 2026-09-27T06:07:25Z

Currently my best bet is the comment:

 // We don't have to listen for stream_close - nghttp3 only closes when
      // ReceiveStreamClose requests it, when we've already handled this.
      nullptr

in http3.cc, but we will see.

martenrichter · 2026-09-27T06:26:38Z

Got it, the capsule for extending the stream limit is not sent. Next step: I figure out why. SendPendingData is probably not triggered.

martenrichter · 2026-09-27T07:46:19Z

Found it, it was just a badly rebased test.

nodejs-github-bot added c++ Issues and PRs that require attention from people who are familiar with C++. lib / src Issues and PRs involving general changes in the lib/ or src/ directories. needs-ci PRs that need a full CI run. labels Aug 16, 2026

martenrichter mentioned this pull request Aug 16, 2026

quic: Add mechanism similar to waitUntilAvailable to create(Bi|Uni)directionalStream #65321

Open

jasnell reviewed Aug 17, 2026

View reviewed changes

trivikr added the quic Issues and PRs related to the QUIC transport implementation. label Sep 7, 2026

martenrichter and others added 7 commits September 26, 2026 19:37

quic: fix lint and bugfixes

de676ca

quic: lint and fixup

0f70c99

quic: waitUntilAvailable change default behavor and fixes

61dcbff

doc: Update quic.md remove trailing whitespace

5d0981d

Update quic.md that the promise is rejected

01c9c58

Update test-quic-stream-limits-uni.mjs for new default vals

f5cc0a1

Update test-quic-stream-pending.mjs for new waitUntilAvail...

4354ef3

quic: fix test after rebase

f450014

martenrichter force-pushed the waituntilavailable branch from 4684e2a to f450014 Compare September 27, 2026 07:45

Uh oh!

Conversation

martenrichter commented Aug 16, 2026

Uh oh!

nodejs-github-bot commented Aug 16, 2026

Uh oh!

codecov Bot commented Aug 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

martenrichter commented Sep 3, 2026

Uh oh!

jasnell commented Sep 5, 2026

Uh oh!

martenrichter commented Sep 5, 2026

Uh oh!

pimterry commented Sep 5, 2026

Uh oh!

martenrichter commented Sep 5, 2026

Uh oh!

martenrichter commented Sep 5, 2026

Uh oh!

martenrichter commented Sep 5, 2026

Uh oh!

martenrichter commented Sep 5, 2026

Uh oh!

jasnell commented Sep 6, 2026

Uh oh!

martenrichter commented Sep 6, 2026

Uh oh!

martenrichter commented Sep 6, 2026

Uh oh!

pimterry commented Sep 7, 2026

Uh oh!

martenrichter commented Sep 7, 2026

Uh oh!

pimterry commented Sep 7, 2026

Uh oh!

martenrichter commented Sep 7, 2026

Uh oh!

martenrichter commented Sep 8, 2026

Uh oh!

martenrichter commented Sep 27, 2026

Uh oh!

jasnell commented Sep 27, 2026

Uh oh!

martenrichter commented Sep 27, 2026

Uh oh!

martenrichter commented Sep 27, 2026

Uh oh!

martenrichter commented Sep 27, 2026

Uh oh!

codecov Bot commented Aug 16, 2026 •

edited

Loading