quic: align stream priority with W3C WebTransport sendOrder

[SparshGarg999]

Summary

Align the experimental QUIC stream prioritization options with W3C WebTransport priority semantics by adding the numeric sendOrder option.

Description

Currently, Node's experimental QUIC implementation supports a string-based priority level ('high', 'default', 'low'). However, the W3C WebTransport specification defines stream priority using a grouped sendGroup and a numeric sendOrder property (where lower values represent higher priority/urgency).

To align Node's QUIC stream priority API with WebTransport's semantics, this commit introduces the numeric sendOrder option.

• sendOrder maps directly to the underlying raw QUIC stream urgency value (an integer in the range [0, 7]).
• When sendOrder is specified at stream creation (via createBidirectionalStream or createUnidirectionalStream) or via setPriority(), it overrides/takes precedence over the string-based priority level.
• The priority getter is updated to return sendOrder alongside level and incremental properties, exposing the exact urgency level of the stream.
• Validates that sendOrder is an integer in the range [0, 7] and throws appropriate errors (ERR_OUT_OF_RANGE / ERR_INVALID_ARG_TYPE) for invalid inputs.

Verification

Updated test/parallel/test-quic-h3-priority.mjs to:

1. Verify sendOrder value returned in the priority getter matches the priority level or explicit sendOrder value set.
2. Verify setting sendOrder at stream creation time.
3. Verify updating sendOrder via setPriority().
4. Validate error throwing for invalid sendOrder types and out-of-range values.

Fixes: #63654

[nodejs-github-bot]

Review requested:

• @nodejs/quic

[martenrichter]

@SparshGarg999
But this lacks the sendGroups. And think it should be something handled upstream in ngtcp2.
And sendOrder in W3C is not limited to {0,7].

[SparshGarg999]

Reopening to address the feedback properly. I'll fix the sendOrder range issue (it should accept any integer, not just [0,7]) and note sendGroups as a follow-up that requires upstream ngtcp2 support.

[SparshGarg999]

Hi! I've updated the implementation to address your feedback:

1. Accepting any integer: The sendOrder option now accepts any integer (matching the W3C WebTransport long long type) instead of being restricted to [0, 7].
2. Clamping to QUIC urgency: We clamp the input to the supported [0, 7] range internally for the underlying QUIC urgency, with comments added to document this mapping.
3. Priority direction and sendGroups: I added clear JSDoc and inline documentation clarifying that W3C's priority direction is inverted relative to QUIC urgency, and that full support for sendGroups and the full integer range without clamping requires upstream ngtcp2 / nghttp3 changes.
4. Tests: Updated the test suite in test-quic-h3-priority.mjs to verify that out-of-bounds values are correctly accepted and clamped, and verified all style/linting checks pass 100% cleanly.

[jasnell]

In the QUIC Team call we've discussed prioritization a bit and I think we're going to back off, at least for now, having a prioritization API on the QuicStream level. Once we've completed separating out the Http3Stream API that will allow setting priority via header.

The main motivation for holding off for now is that we need to take some time to figure out what exactly the correct API for prioritization should be given that there are a couple of different models currently at play.

So for now, going to mark this as "Request changes" but we'll be coming back to this.

/cc @nodejs/quic

[SparshGarg999]

Thanks for the update and clarification, @jasnell! That makes complete sense. Backing off stream-level prioritization until Http3Stream is separated out and priority can be cleanly handled via headers (RFC 9218) is a very sensible path forward.

In the meantime, I have rebased this branch onto the latest main and resolved the merge conflicts so that it remains clean. Whenever the team is ready to resume the prioritization discussion or adapt this for Http3Stream, I’m happy to follow up or help adjust the PR accordingly.