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

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>

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.05%. Comparing base (4551732) to head (4684e2a).
⚠️ Report is 461 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main   #65331      +/-   ##
==========================================
- Coverage   90.30%   90.05%   -0.26%     
==========================================
  Files         751      754       +3     
  Lines      250235   255723    +5488     
  Branches    47305    48314    +1009     
==========================================
+ Hits       225987   230299    +4312     
- Misses      15619    16557     +938     
- Partials     8629     8867     +238

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

... and 210 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).

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

quic: fix lint and bugfixes

2e12c73

jasnell reviewed Aug 17, 2026

View reviewed changes

martenrichter and others added 6 commits August 17, 2026 05:26

quic: lint and fixup

df547b6

quic: waitUntilAvailable change default behavor and fixes

d862d2b

doc: Update quic.md remove trailing whitespace

2a75220

Update quic.md that the promise is rejected

856cc1b

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

87c51a8

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

4684e2a

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

Uh oh!

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!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

codecov Bot commented Aug 16, 2026 •

edited

Loading