quic: defer server session emit until TLS ClientHello is processed by pimterry · Pull Request #64132 · nodejs/node

pimterry · 2026-06-25T15:18:20Z

Extracted from #63995. It's not identical to the implementation there, I did a little more cleanup and refactoring here, and dropped some parts that aren't relevant without the latest changes in that PR, but it's reviewable standalone.

This change means servers can access servername & alpnProtocol synchronously as soon as the event is fired - all key session data is available and it's immediately usable. New getters are exposed for that. This also ensures we don't fire session events for totally invalid TLS handshakes - fundamental errors, bad SNI/ALPN values, or anything else that our TLS config would reject.

It does so without waiting for any more round trips that before, in any normal flow: it just defers the session event to the end of the client hello processing which should be momentarily after the previous behaviour. In very strange flows (if the first flight from the client doesn't contain the full client hello) then this could introduce a more significant delay, but AFAICT no normal client should ever do that (and we'd have to do some kind of wait regardless eventually if they did - we can't really do anything useful without a complete client hello).

This is just intended to improve UX and smooth the path towards dynamic Application selection (as used in #63995). A few things this doesn't do:

It doesn't wait for handshake completion. It's just processing of the client hello. Completion would imply an extra round trip, and thereby defeat 0RTT benefits entirely.
It doesn't improve security (though it helps avoid some footguns). Existing mechanisms already ensure we can't read or write data that isn't correctly within the TLS handshake (deferred data on new connections until the handshake completes, or allowing early data that's explicitly marked as such on resumed connections)
It doesn't change client behaviour. In the client case, the session is available on creation, and you always have to wait for opened. Dynamic app selection there would wait for full handshake completion anyway, since that's the only way to know the confirmed ALPN, which you'll want in most cases (though we don't currently support multiple ALPN for clients anyway). All deferred for later.
It doesn't expose these failed TLS sessions in any way. In future we will probably want a tlsClientError analogue, but imo that was true before as well and we can continue to defer it for now. Most servers aren't that interested in clients who fail to connect, it's not a top priority.

This ensures we don't fire session events for totally invalid TLS handshakes - fundamental errors, bad SNI/ALPN values, or anything else that our TLS config would reject. Instead, it means servers can access servername & alpnProtocol synchronously as soon as the event is fired - all key session data is available and it's immediately usable. We don't want to defer further to handshake completed, since that'd be an extra RT, and defeat 0RTT benefits entirely. ClientHello processed without errors is sufficient for now. This isn't a security mechanism. Existing structures will defer actually sending & receiving anything that's not marked explicitly as early data until the handshake completes anyway. Signed-off-by: Tim Perry <pimterry@gmail.com>

nodejs-github-bot · 2026-06-25T15:18:26Z

Review requested:

@nodejs/quic

jasnell · 2026-07-06T00:36:14Z

+ auto emits = std::move(impl_->deferred_emits_);
+ for (auto& emit : emits) {
+ if (is_destroyed()) return;
+ emit();


Since each of these is a C++-to-JavaScript call, I wonder if it would be possible to batch them to a new callback. Essentially, rather than enqueuing a function, enqueue the arguments and type of emit, send them all to JavaScript at once and process each one there instead. Calls from C++-to-JavaScript can be a bit expensive to set up.

This can be looked at later tho.

I've left this for now. It looks likely to be a little fiddly, and I think it rarely comes up (just a couple of 0RTT events, or keylog/qlog when they're enabled) but we can explore as an optimization later.

nodejs-github-bot · 2026-07-07T03:31:00Z

CI: https://ci.nodejs.org/job/node-test-pull-request/74617/

…ssed Cache ALPN & servername once set, update field types and docs.

nodejs-github-bot · 2026-07-08T14:47:06Z

CI: https://ci.nodejs.org/job/node-test-pull-request/74665/

codecov · 2026-07-08T16:08:19Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 90.24%. Comparing base (e6a8d06) to head (8d11c96).
⚠️ Report is 420 commits behind head on main.

Additional details and impacted files

@@ Coverage Diff @@## main #64132 +/- ##
==========================================
- Coverage 92.01% 90.24% -1.78% 
==========================================
Files 379 741 +362 Lines 166972 241037 +74065 Branches 25554 45411 +19857 ==========================================
+ Hits 153639 217513 +63874 - Misses 13041 15108 +2067 - Partials 292 8416 +8124

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

... and 543 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.

nodejs-github-bot · 2026-07-08T18:39:40Z

CI: https://ci.nodejs.org/job/node-test-pull-request/74676/

pimterry · 2026-07-23T12:56:06Z

@jasnell when you have a sec, I'd love a re-review here to land this. That last commit is just fixes for the points from your review.

nodejs-github-bot · 2026-07-23T13:44:52Z

Landed in f9715fc

This ensures we don't fire session events for totally invalid TLS handshakes - fundamental errors, bad SNI/ALPN values, or anything else that our TLS config would reject. Instead, it means servers can access servername & alpnProtocol synchronously as soon as the event is fired - all key session data is available and it's immediately usable. We don't want to defer further to handshake completed, since that'd be an extra RT, and defeat 0RTT benefits entirely. ClientHello processed without errors is sufficient for now. This isn't a security mechanism. Existing structures will defer actually sending & receiving anything that's not marked explicitly as early data until the handshake completes anyway. Signed-off-by: Tim Perry <pimterry@gmail.com> PR-URL: #64132 Reviewed-By: James M Snell <jasnell@gmail.com>

pimterry · 2026-06-25T15:18:20Z

Extracted from #63995. It's not identical to the implementation there, I did a little more cleanup and refactoring here, and dropped some parts that aren't relevant without the latest changes in that PR, but it's reviewable standalone.

This change means servers can access servername & alpnProtocol synchronously as soon as the event is fired - all key session data is available and it's immediately usable. New getters are exposed for that. This also ensures we don't fire session events for totally invalid TLS handshakes - fundamental errors, bad SNI/ALPN values, or anything else that our TLS config would reject.

It does so without waiting for any more round trips that before, in any normal flow: it just defers the session event to the end of the client hello processing which should be momentarily after the previous behaviour. In very strange flows (if the first flight from the client doesn't contain the full client hello) then this could introduce a more significant delay, but AFAICT no normal client should ever do that (and we'd have to do some kind of wait regardless eventually if they did - we can't really do anything useful without a complete client hello).

This is just intended to improve UX and smooth the path towards dynamic Application selection (as used in #63995). A few things this doesn't do:

It doesn't wait for handshake completion. It's just processing of the client hello. Completion would imply an extra round trip, and thereby defeat 0RTT benefits entirely.
It doesn't improve security (though it helps avoid some footguns). Existing mechanisms already ensure we can't read or write data that isn't correctly within the TLS handshake (deferred data on new connections until the handshake completes, or allowing early data that's explicitly marked as such on resumed connections)
It doesn't change client behaviour. In the client case, the session is available on creation, and you always have to wait for opened. Dynamic app selection there would wait for full handshake completion anyway, since that's the only way to know the confirmed ALPN, which you'll want in most cases (though we don't currently support multiple ALPN for clients anyway). All deferred for later.
It doesn't expose these failed TLS sessions in any way. In future we will probably want a tlsClientError analogue, but imo that was true before as well and we can continue to defer it for now. Most servers aren't that interested in clients who fail to connect, it's not a top priority.

This ensures we don't fire session events for totally invalid TLS handshakes - fundamental errors, bad SNI/ALPN values, or anything else that our TLS config would reject. Instead, it means servers can access servername & alpnProtocol synchronously as soon as the event is fired - all key session data is available and it's immediately usable. We don't want to defer further to handshake completed, since that'd be an extra RT, and defeat 0RTT benefits entirely. ClientHello processed without errors is sufficient for now. This isn't a security mechanism. Existing structures will defer actually sending & receiving anything that's not marked explicitly as early data until the handshake completes anyway. Signed-off-by: Tim Perry <pimterry@gmail.com>

nodejs-github-bot · 2026-06-25T15:18:26Z

Review requested:

@nodejs/quic

jasnell · 2026-07-06T00:36:14Z

+ auto emits = std::move(impl_->deferred_emits_);
+ for (auto& emit : emits) {
+ if (is_destroyed()) return;
+ emit();


Since each of these is a C++-to-JavaScript call, I wonder if it would be possible to batch them to a new callback. Essentially, rather than enqueuing a function, enqueue the arguments and type of emit, send them all to JavaScript at once and process each one there instead. Calls from C++-to-JavaScript can be a bit expensive to set up.

This can be looked at later tho.

I've left this for now. It looks likely to be a little fiddly, and I think it rarely comes up (just a couple of 0RTT events, or keylog/qlog when they're enabled) but we can explore as an optimization later.

nodejs-github-bot · 2026-07-07T03:31:00Z

CI: https://ci.nodejs.org/job/node-test-pull-request/74617/

…ssed Cache ALPN & servername once set, update field types and docs.

nodejs-github-bot · 2026-07-08T14:47:06Z

CI: https://ci.nodejs.org/job/node-test-pull-request/74665/

codecov · 2026-07-08T16:08:19Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 90.24%. Comparing base (e6a8d06) to head (8d11c96).
⚠️ Report is 420 commits behind head on main.

Additional details and impacted files

@@ Coverage Diff @@## main #64132 +/- ##
==========================================
- Coverage 92.01% 90.24% -1.78% 
==========================================
Files 379 741 +362 Lines 166972 241037 +74065 Branches 25554 45411 +19857 ==========================================
+ Hits 153639 217513 +63874 - Misses 13041 15108 +2067 - Partials 292 8416 +8124

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

... and 543 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.

nodejs-github-bot · 2026-07-08T18:39:40Z

CI: https://ci.nodejs.org/job/node-test-pull-request/74676/

pimterry · 2026-07-23T12:56:06Z

@jasnell when you have a sec, I'd love a re-review here to land this. That last commit is just fixes for the points from your review.

nodejs-github-bot · 2026-07-23T13:44:52Z

Landed in f9715fc

This ensures we don't fire session events for totally invalid TLS handshakes - fundamental errors, bad SNI/ALPN values, or anything else that our TLS config would reject. Instead, it means servers can access servername & alpnProtocol synchronously as soon as the event is fired - all key session data is available and it's immediately usable. We don't want to defer further to handshake completed, since that'd be an extra RT, and defeat 0RTT benefits entirely. ClientHello processed without errors is sufficient for now. This isn't a security mechanism. Existing structures will defer actually sending & receiving anything that's not marked explicitly as early data until the handshake completes anyway. Signed-off-by: Tim Perry <pimterry@gmail.com> PR-URL: #64132 Reviewed-By: James M Snell <jasnell@gmail.com>

pimterry · 2026-06-25T15:18:20Z

Extracted from #63995. It's not identical to the implementation there, I did a little more cleanup and refactoring here, and dropped some parts that aren't relevant without the latest changes in that PR, but it's reviewable standalone.

This change means servers can access servername & alpnProtocol synchronously as soon as the event is fired - all key session data is available and it's immediately usable. New getters are exposed for that. This also ensures we don't fire session events for totally invalid TLS handshakes - fundamental errors, bad SNI/ALPN values, or anything else that our TLS config would reject.

It does so without waiting for any more round trips that before, in any normal flow: it just defers the session event to the end of the client hello processing which should be momentarily after the previous behaviour. In very strange flows (if the first flight from the client doesn't contain the full client hello) then this could introduce a more significant delay, but AFAICT no normal client should ever do that (and we'd have to do some kind of wait regardless eventually if they did - we can't really do anything useful without a complete client hello).

This is just intended to improve UX and smooth the path towards dynamic Application selection (as used in #63995). A few things this doesn't do:

It doesn't wait for handshake completion. It's just processing of the client hello. Completion would imply an extra round trip, and thereby defeat 0RTT benefits entirely.
It doesn't improve security (though it helps avoid some footguns). Existing mechanisms already ensure we can't read or write data that isn't correctly within the TLS handshake (deferred data on new connections until the handshake completes, or allowing early data that's explicitly marked as such on resumed connections)
It doesn't change client behaviour. In the client case, the session is available on creation, and you always have to wait for opened. Dynamic app selection there would wait for full handshake completion anyway, since that's the only way to know the confirmed ALPN, which you'll want in most cases (though we don't currently support multiple ALPN for clients anyway). All deferred for later.
It doesn't expose these failed TLS sessions in any way. In future we will probably want a tlsClientError analogue, but imo that was true before as well and we can continue to defer it for now. Most servers aren't that interested in clients who fail to connect, it's not a top priority.

This ensures we don't fire session events for totally invalid TLS handshakes - fundamental errors, bad SNI/ALPN values, or anything else that our TLS config would reject. Instead, it means servers can access servername & alpnProtocol synchronously as soon as the event is fired - all key session data is available and it's immediately usable. We don't want to defer further to handshake completed, since that'd be an extra RT, and defeat 0RTT benefits entirely. ClientHello processed without errors is sufficient for now. This isn't a security mechanism. Existing structures will defer actually sending & receiving anything that's not marked explicitly as early data until the handshake completes anyway. Signed-off-by: Tim Perry <pimterry@gmail.com>

nodejs-github-bot · 2026-06-25T15:18:26Z

Review requested:

@nodejs/quic

jasnell · 2026-07-06T00:36:14Z

+ auto emits = std::move(impl_->deferred_emits_);
+ for (auto& emit : emits) {
+ if (is_destroyed()) return;
+ emit();


Since each of these is a C++-to-JavaScript call, I wonder if it would be possible to batch them to a new callback. Essentially, rather than enqueuing a function, enqueue the arguments and type of emit, send them all to JavaScript at once and process each one there instead. Calls from C++-to-JavaScript can be a bit expensive to set up.

This can be looked at later tho.

I've left this for now. It looks likely to be a little fiddly, and I think it rarely comes up (just a couple of 0RTT events, or keylog/qlog when they're enabled) but we can explore as an optimization later.

nodejs-github-bot · 2026-07-07T03:31:00Z

CI: https://ci.nodejs.org/job/node-test-pull-request/74617/

…ssed Cache ALPN & servername once set, update field types and docs.

nodejs-github-bot · 2026-07-08T14:47:06Z

CI: https://ci.nodejs.org/job/node-test-pull-request/74665/

codecov · 2026-07-08T16:08:19Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 90.24%. Comparing base (e6a8d06) to head (8d11c96).
⚠️ Report is 420 commits behind head on main.

Additional details and impacted files

@@ Coverage Diff @@## main #64132 +/- ##
==========================================
- Coverage 92.01% 90.24% -1.78% 
==========================================
Files 379 741 +362 Lines 166972 241037 +74065 Branches 25554 45411 +19857 ==========================================
+ Hits 153639 217513 +63874 - Misses 13041 15108 +2067 - Partials 292 8416 +8124

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

... and 543 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.

nodejs-github-bot · 2026-07-08T18:39:40Z

CI: https://ci.nodejs.org/job/node-test-pull-request/74676/

pimterry · 2026-07-23T12:56:06Z

@jasnell when you have a sec, I'd love a re-review here to land this. That last commit is just fixes for the points from your review.

nodejs-github-bot · 2026-07-23T13:44:52Z

Landed in f9715fc

This ensures we don't fire session events for totally invalid TLS handshakes - fundamental errors, bad SNI/ALPN values, or anything else that our TLS config would reject. Instead, it means servers can access servername & alpnProtocol synchronously as soon as the event is fired - all key session data is available and it's immediately usable. We don't want to defer further to handshake completed, since that'd be an extra RT, and defeat 0RTT benefits entirely. ClientHello processed without errors is sufficient for now. This isn't a security mechanism. Existing structures will defer actually sending & receiving anything that's not marked explicitly as early data until the handshake completes anyway. Signed-off-by: Tim Perry <pimterry@gmail.com> PR-URL: #64132 Reviewed-By: James M Snell <jasnell@gmail.com>

pimterry · 2026-06-25T15:18:20Z

Extracted from #63995. It's not identical to the implementation there, I did a little more cleanup and refactoring here, and dropped some parts that aren't relevant without the latest changes in that PR, but it's reviewable standalone.

This change means servers can access servername & alpnProtocol synchronously as soon as the event is fired - all key session data is available and it's immediately usable. New getters are exposed for that. This also ensures we don't fire session events for totally invalid TLS handshakes - fundamental errors, bad SNI/ALPN values, or anything else that our TLS config would reject.

It does so without waiting for any more round trips that before, in any normal flow: it just defers the session event to the end of the client hello processing which should be momentarily after the previous behaviour. In very strange flows (if the first flight from the client doesn't contain the full client hello) then this could introduce a more significant delay, but AFAICT no normal client should ever do that (and we'd have to do some kind of wait regardless eventually if they did - we can't really do anything useful without a complete client hello).

This is just intended to improve UX and smooth the path towards dynamic Application selection (as used in #63995). A few things this doesn't do:

It doesn't wait for handshake completion. It's just processing of the client hello. Completion would imply an extra round trip, and thereby defeat 0RTT benefits entirely.
It doesn't improve security (though it helps avoid some footguns). Existing mechanisms already ensure we can't read or write data that isn't correctly within the TLS handshake (deferred data on new connections until the handshake completes, or allowing early data that's explicitly marked as such on resumed connections)
It doesn't change client behaviour. In the client case, the session is available on creation, and you always have to wait for opened. Dynamic app selection there would wait for full handshake completion anyway, since that's the only way to know the confirmed ALPN, which you'll want in most cases (though we don't currently support multiple ALPN for clients anyway). All deferred for later.
It doesn't expose these failed TLS sessions in any way. In future we will probably want a tlsClientError analogue, but imo that was true before as well and we can continue to defer it for now. Most servers aren't that interested in clients who fail to connect, it's not a top priority.

This ensures we don't fire session events for totally invalid TLS handshakes - fundamental errors, bad SNI/ALPN values, or anything else that our TLS config would reject. Instead, it means servers can access servername & alpnProtocol synchronously as soon as the event is fired - all key session data is available and it's immediately usable. We don't want to defer further to handshake completed, since that'd be an extra RT, and defeat 0RTT benefits entirely. ClientHello processed without errors is sufficient for now. This isn't a security mechanism. Existing structures will defer actually sending & receiving anything that's not marked explicitly as early data until the handshake completes anyway. Signed-off-by: Tim Perry <pimterry@gmail.com>

nodejs-github-bot · 2026-06-25T15:18:26Z

Review requested:

@nodejs/quic

jasnell · 2026-07-06T00:36:14Z

+ auto emits = std::move(impl_->deferred_emits_);
+ for (auto& emit : emits) {
+ if (is_destroyed()) return;
+ emit();


Since each of these is a C++-to-JavaScript call, I wonder if it would be possible to batch them to a new callback. Essentially, rather than enqueuing a function, enqueue the arguments and type of emit, send them all to JavaScript at once and process each one there instead. Calls from C++-to-JavaScript can be a bit expensive to set up.

This can be looked at later tho.

I've left this for now. It looks likely to be a little fiddly, and I think it rarely comes up (just a couple of 0RTT events, or keylog/qlog when they're enabled) but we can explore as an optimization later.

nodejs-github-bot · 2026-07-07T03:31:00Z

CI: https://ci.nodejs.org/job/node-test-pull-request/74617/

…ssed Cache ALPN & servername once set, update field types and docs.

nodejs-github-bot · 2026-07-08T14:47:06Z

CI: https://ci.nodejs.org/job/node-test-pull-request/74665/

codecov · 2026-07-08T16:08:19Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 90.24%. Comparing base (e6a8d06) to head (8d11c96).
⚠️ Report is 420 commits behind head on main.

Additional details and impacted files

@@ Coverage Diff @@## main #64132 +/- ##
==========================================
- Coverage 92.01% 90.24% -1.78% 
==========================================
Files 379 741 +362 Lines 166972 241037 +74065 Branches 25554 45411 +19857 ==========================================
+ Hits 153639 217513 +63874 - Misses 13041 15108 +2067 - Partials 292 8416 +8124

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

... and 543 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.

nodejs-github-bot · 2026-07-08T18:39:40Z

CI: https://ci.nodejs.org/job/node-test-pull-request/74676/

pimterry · 2026-07-23T12:56:06Z

@jasnell when you have a sec, I'd love a re-review here to land this. That last commit is just fixes for the points from your review.

nodejs-github-bot · 2026-07-23T13:44:52Z

Landed in f9715fc

This ensures we don't fire session events for totally invalid TLS handshakes - fundamental errors, bad SNI/ALPN values, or anything else that our TLS config would reject. Instead, it means servers can access servername & alpnProtocol synchronously as soon as the event is fired - all key session data is available and it's immediately usable. We don't want to defer further to handshake completed, since that'd be an extra RT, and defeat 0RTT benefits entirely. ClientHello processed without errors is sufficient for now. This isn't a security mechanism. Existing structures will defer actually sending & receiving anything that's not marked explicitly as early data until the handshake completes anyway. Signed-off-by: Tim Perry <pimterry@gmail.com> PR-URL: #64132 Reviewed-By: James M Snell <jasnell@gmail.com>

pimterry · 2026-06-25T15:18:20Z

Extracted from #63995. It's not identical to the implementation there, I did a little more cleanup and refactoring here, and dropped some parts that aren't relevant without the latest changes in that PR, but it's reviewable standalone.

This change means servers can access servername & alpnProtocol synchronously as soon as the event is fired - all key session data is available and it's immediately usable. New getters are exposed for that. This also ensures we don't fire session events for totally invalid TLS handshakes - fundamental errors, bad SNI/ALPN values, or anything else that our TLS config would reject.

It does so without waiting for any more round trips that before, in any normal flow: it just defers the session event to the end of the client hello processing which should be momentarily after the previous behaviour. In very strange flows (if the first flight from the client doesn't contain the full client hello) then this could introduce a more significant delay, but AFAICT no normal client should ever do that (and we'd have to do some kind of wait regardless eventually if they did - we can't really do anything useful without a complete client hello).

This is just intended to improve UX and smooth the path towards dynamic Application selection (as used in #63995). A few things this doesn't do:

It doesn't wait for handshake completion. It's just processing of the client hello. Completion would imply an extra round trip, and thereby defeat 0RTT benefits entirely.
It doesn't improve security (though it helps avoid some footguns). Existing mechanisms already ensure we can't read or write data that isn't correctly within the TLS handshake (deferred data on new connections until the handshake completes, or allowing early data that's explicitly marked as such on resumed connections)
It doesn't change client behaviour. In the client case, the session is available on creation, and you always have to wait for opened. Dynamic app selection there would wait for full handshake completion anyway, since that's the only way to know the confirmed ALPN, which you'll want in most cases (though we don't currently support multiple ALPN for clients anyway). All deferred for later.
It doesn't expose these failed TLS sessions in any way. In future we will probably want a tlsClientError analogue, but imo that was true before as well and we can continue to defer it for now. Most servers aren't that interested in clients who fail to connect, it's not a top priority.

This ensures we don't fire session events for totally invalid TLS handshakes - fundamental errors, bad SNI/ALPN values, or anything else that our TLS config would reject. Instead, it means servers can access servername & alpnProtocol synchronously as soon as the event is fired - all key session data is available and it's immediately usable. We don't want to defer further to handshake completed, since that'd be an extra RT, and defeat 0RTT benefits entirely. ClientHello processed without errors is sufficient for now. This isn't a security mechanism. Existing structures will defer actually sending & receiving anything that's not marked explicitly as early data until the handshake completes anyway. Signed-off-by: Tim Perry <pimterry@gmail.com>

nodejs-github-bot · 2026-06-25T15:18:26Z

Review requested:

@nodejs/quic

jasnell · 2026-07-06T00:36:14Z

+ auto emits = std::move(impl_->deferred_emits_);
+ for (auto& emit : emits) {
+ if (is_destroyed()) return;
+ emit();


Since each of these is a C++-to-JavaScript call, I wonder if it would be possible to batch them to a new callback. Essentially, rather than enqueuing a function, enqueue the arguments and type of emit, send them all to JavaScript at once and process each one there instead. Calls from C++-to-JavaScript can be a bit expensive to set up.

This can be looked at later tho.

I've left this for now. It looks likely to be a little fiddly, and I think it rarely comes up (just a couple of 0RTT events, or keylog/qlog when they're enabled) but we can explore as an optimization later.

nodejs-github-bot · 2026-07-07T03:31:00Z

CI: https://ci.nodejs.org/job/node-test-pull-request/74617/

…ssed Cache ALPN & servername once set, update field types and docs.

nodejs-github-bot · 2026-07-08T14:47:06Z

CI: https://ci.nodejs.org/job/node-test-pull-request/74665/

codecov · 2026-07-08T16:08:19Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 90.24%. Comparing base (e6a8d06) to head (8d11c96).
⚠️ Report is 420 commits behind head on main.

Additional details and impacted files

@@ Coverage Diff @@## main #64132 +/- ##
==========================================
- Coverage 92.01% 90.24% -1.78% 
==========================================
Files 379 741 +362 Lines 166972 241037 +74065 Branches 25554 45411 +19857 ==========================================
+ Hits 153639 217513 +63874 - Misses 13041 15108 +2067 - Partials 292 8416 +8124

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

... and 543 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.

nodejs-github-bot · 2026-07-08T18:39:40Z

CI: https://ci.nodejs.org/job/node-test-pull-request/74676/

pimterry · 2026-07-23T12:56:06Z

@jasnell when you have a sec, I'd love a re-review here to land this. That last commit is just fixes for the points from your review.

nodejs-github-bot · 2026-07-23T13:44:52Z

Landed in f9715fc

This ensures we don't fire session events for totally invalid TLS handshakes - fundamental errors, bad SNI/ALPN values, or anything else that our TLS config would reject. Instead, it means servers can access servername & alpnProtocol synchronously as soon as the event is fired - all key session data is available and it's immediately usable. We don't want to defer further to handshake completed, since that'd be an extra RT, and defeat 0RTT benefits entirely. ClientHello processed without errors is sufficient for now. This isn't a security mechanism. Existing structures will defer actually sending & receiving anything that's not marked explicitly as early data until the handshake completes anyway. Signed-off-by: Tim Perry <pimterry@gmail.com> PR-URL: #64132 Reviewed-By: James M Snell <jasnell@gmail.com>

pimterry · 2026-06-25T15:18:20Z

Extracted from #63995. It's not identical to the implementation there, I did a little more cleanup and refactoring here, and dropped some parts that aren't relevant without the latest changes in that PR, but it's reviewable standalone.

This change means servers can access servername & alpnProtocol synchronously as soon as the event is fired - all key session data is available and it's immediately usable. New getters are exposed for that. This also ensures we don't fire session events for totally invalid TLS handshakes - fundamental errors, bad SNI/ALPN values, or anything else that our TLS config would reject.

It does so without waiting for any more round trips that before, in any normal flow: it just defers the session event to the end of the client hello processing which should be momentarily after the previous behaviour. In very strange flows (if the first flight from the client doesn't contain the full client hello) then this could introduce a more significant delay, but AFAICT no normal client should ever do that (and we'd have to do some kind of wait regardless eventually if they did - we can't really do anything useful without a complete client hello).

This is just intended to improve UX and smooth the path towards dynamic Application selection (as used in #63995). A few things this doesn't do:

It doesn't wait for handshake completion. It's just processing of the client hello. Completion would imply an extra round trip, and thereby defeat 0RTT benefits entirely.
It doesn't improve security (though it helps avoid some footguns). Existing mechanisms already ensure we can't read or write data that isn't correctly within the TLS handshake (deferred data on new connections until the handshake completes, or allowing early data that's explicitly marked as such on resumed connections)
It doesn't change client behaviour. In the client case, the session is available on creation, and you always have to wait for opened. Dynamic app selection there would wait for full handshake completion anyway, since that's the only way to know the confirmed ALPN, which you'll want in most cases (though we don't currently support multiple ALPN for clients anyway). All deferred for later.
It doesn't expose these failed TLS sessions in any way. In future we will probably want a tlsClientError analogue, but imo that was true before as well and we can continue to defer it for now. Most servers aren't that interested in clients who fail to connect, it's not a top priority.

This ensures we don't fire session events for totally invalid TLS handshakes - fundamental errors, bad SNI/ALPN values, or anything else that our TLS config would reject. Instead, it means servers can access servername & alpnProtocol synchronously as soon as the event is fired - all key session data is available and it's immediately usable. We don't want to defer further to handshake completed, since that'd be an extra RT, and defeat 0RTT benefits entirely. ClientHello processed without errors is sufficient for now. This isn't a security mechanism. Existing structures will defer actually sending & receiving anything that's not marked explicitly as early data until the handshake completes anyway. Signed-off-by: Tim Perry <pimterry@gmail.com>

nodejs-github-bot · 2026-06-25T15:18:26Z

Review requested:

@nodejs/quic

jasnell · 2026-07-06T00:36:14Z

+ auto emits = std::move(impl_->deferred_emits_);
+ for (auto& emit : emits) {
+ if (is_destroyed()) return;
+ emit();


Since each of these is a C++-to-JavaScript call, I wonder if it would be possible to batch them to a new callback. Essentially, rather than enqueuing a function, enqueue the arguments and type of emit, send them all to JavaScript at once and process each one there instead. Calls from C++-to-JavaScript can be a bit expensive to set up.

This can be looked at later tho.

I've left this for now. It looks likely to be a little fiddly, and I think it rarely comes up (just a couple of 0RTT events, or keylog/qlog when they're enabled) but we can explore as an optimization later.

nodejs-github-bot · 2026-07-07T03:31:00Z

CI: https://ci.nodejs.org/job/node-test-pull-request/74617/

…ssed Cache ALPN & servername once set, update field types and docs.

nodejs-github-bot · 2026-07-08T14:47:06Z

CI: https://ci.nodejs.org/job/node-test-pull-request/74665/

codecov · 2026-07-08T16:08:19Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 90.24%. Comparing base (e6a8d06) to head (8d11c96).
⚠️ Report is 420 commits behind head on main.

Additional details and impacted files

@@ Coverage Diff @@## main #64132 +/- ##
==========================================
- Coverage 92.01% 90.24% -1.78% 
==========================================
Files 379 741 +362 Lines 166972 241037 +74065 Branches 25554 45411 +19857 ==========================================
+ Hits 153639 217513 +63874 - Misses 13041 15108 +2067 - Partials 292 8416 +8124

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

... and 543 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.

nodejs-github-bot · 2026-07-08T18:39:40Z

CI: https://ci.nodejs.org/job/node-test-pull-request/74676/

pimterry · 2026-07-23T12:56:06Z

@jasnell when you have a sec, I'd love a re-review here to land this. That last commit is just fixes for the points from your review.

nodejs-github-bot · 2026-07-23T13:44:52Z

Landed in f9715fc

This ensures we don't fire session events for totally invalid TLS handshakes - fundamental errors, bad SNI/ALPN values, or anything else that our TLS config would reject. Instead, it means servers can access servername & alpnProtocol synchronously as soon as the event is fired - all key session data is available and it's immediately usable. We don't want to defer further to handshake completed, since that'd be an extra RT, and defeat 0RTT benefits entirely. ClientHello processed without errors is sufficient for now. This isn't a security mechanism. Existing structures will defer actually sending & receiving anything that's not marked explicitly as early data until the handshake completes anyway. Signed-off-by: Tim Perry <pimterry@gmail.com> PR-URL: #64132 Reviewed-By: James M Snell <jasnell@gmail.com>

pimterry · 2026-06-25T15:18:20Z

Extracted from #63995. It's not identical to the implementation there, I did a little more cleanup and refactoring here, and dropped some parts that aren't relevant without the latest changes in that PR, but it's reviewable standalone.

This change means servers can access servername & alpnProtocol synchronously as soon as the event is fired - all key session data is available and it's immediately usable. New getters are exposed for that. This also ensures we don't fire session events for totally invalid TLS handshakes - fundamental errors, bad SNI/ALPN values, or anything else that our TLS config would reject.

It does so without waiting for any more round trips that before, in any normal flow: it just defers the session event to the end of the client hello processing which should be momentarily after the previous behaviour. In very strange flows (if the first flight from the client doesn't contain the full client hello) then this could introduce a more significant delay, but AFAICT no normal client should ever do that (and we'd have to do some kind of wait regardless eventually if they did - we can't really do anything useful without a complete client hello).

This is just intended to improve UX and smooth the path towards dynamic Application selection (as used in #63995). A few things this doesn't do:

It doesn't wait for handshake completion. It's just processing of the client hello. Completion would imply an extra round trip, and thereby defeat 0RTT benefits entirely.
It doesn't improve security (though it helps avoid some footguns). Existing mechanisms already ensure we can't read or write data that isn't correctly within the TLS handshake (deferred data on new connections until the handshake completes, or allowing early data that's explicitly marked as such on resumed connections)
It doesn't change client behaviour. In the client case, the session is available on creation, and you always have to wait for opened. Dynamic app selection there would wait for full handshake completion anyway, since that's the only way to know the confirmed ALPN, which you'll want in most cases (though we don't currently support multiple ALPN for clients anyway). All deferred for later.
It doesn't expose these failed TLS sessions in any way. In future we will probably want a tlsClientError analogue, but imo that was true before as well and we can continue to defer it for now. Most servers aren't that interested in clients who fail to connect, it's not a top priority.

This ensures we don't fire session events for totally invalid TLS handshakes - fundamental errors, bad SNI/ALPN values, or anything else that our TLS config would reject. Instead, it means servers can access servername & alpnProtocol synchronously as soon as the event is fired - all key session data is available and it's immediately usable. We don't want to defer further to handshake completed, since that'd be an extra RT, and defeat 0RTT benefits entirely. ClientHello processed without errors is sufficient for now. This isn't a security mechanism. Existing structures will defer actually sending & receiving anything that's not marked explicitly as early data until the handshake completes anyway. Signed-off-by: Tim Perry <pimterry@gmail.com>

nodejs-github-bot · 2026-06-25T15:18:26Z

Review requested:

@nodejs/quic

jasnell · 2026-07-06T00:36:14Z

+ auto emits = std::move(impl_->deferred_emits_);
+ for (auto& emit : emits) {
+ if (is_destroyed()) return;
+ emit();


Since each of these is a C++-to-JavaScript call, I wonder if it would be possible to batch them to a new callback. Essentially, rather than enqueuing a function, enqueue the arguments and type of emit, send them all to JavaScript at once and process each one there instead. Calls from C++-to-JavaScript can be a bit expensive to set up.

This can be looked at later tho.

I've left this for now. It looks likely to be a little fiddly, and I think it rarely comes up (just a couple of 0RTT events, or keylog/qlog when they're enabled) but we can explore as an optimization later.

nodejs-github-bot · 2026-07-07T03:31:00Z

CI: https://ci.nodejs.org/job/node-test-pull-request/74617/

…ssed Cache ALPN & servername once set, update field types and docs.

nodejs-github-bot · 2026-07-08T14:47:06Z

CI: https://ci.nodejs.org/job/node-test-pull-request/74665/

codecov · 2026-07-08T16:08:19Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 90.24%. Comparing base (e6a8d06) to head (8d11c96).
⚠️ Report is 420 commits behind head on main.

Additional details and impacted files

@@ Coverage Diff @@## main #64132 +/- ##
==========================================
- Coverage 92.01% 90.24% -1.78% 
==========================================
Files 379 741 +362 Lines 166972 241037 +74065 Branches 25554 45411 +19857 ==========================================
+ Hits 153639 217513 +63874 - Misses 13041 15108 +2067 - Partials 292 8416 +8124

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

... and 543 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.

nodejs-github-bot · 2026-07-08T18:39:40Z

CI: https://ci.nodejs.org/job/node-test-pull-request/74676/

pimterry · 2026-07-23T12:56:06Z

@jasnell when you have a sec, I'd love a re-review here to land this. That last commit is just fixes for the points from your review.

nodejs-github-bot · 2026-07-23T13:44:52Z

Landed in f9715fc

This ensures we don't fire session events for totally invalid TLS handshakes - fundamental errors, bad SNI/ALPN values, or anything else that our TLS config would reject. Instead, it means servers can access servername & alpnProtocol synchronously as soon as the event is fired - all key session data is available and it's immediately usable. We don't want to defer further to handshake completed, since that'd be an extra RT, and defeat 0RTT benefits entirely. ClientHello processed without errors is sufficient for now. This isn't a security mechanism. Existing structures will defer actually sending & receiving anything that's not marked explicitly as early data until the handshake completes anyway. Signed-off-by: Tim Perry <pimterry@gmail.com> PR-URL: #64132 Reviewed-By: James M Snell <jasnell@gmail.com>

pimterry · 2026-06-25T15:18:20Z

Extracted from #63995. It's not identical to the implementation there, I did a little more cleanup and refactoring here, and dropped some parts that aren't relevant without the latest changes in that PR, but it's reviewable standalone.

This change means servers can access servername & alpnProtocol synchronously as soon as the event is fired - all key session data is available and it's immediately usable. New getters are exposed for that. This also ensures we don't fire session events for totally invalid TLS handshakes - fundamental errors, bad SNI/ALPN values, or anything else that our TLS config would reject.

It does so without waiting for any more round trips that before, in any normal flow: it just defers the session event to the end of the client hello processing which should be momentarily after the previous behaviour. In very strange flows (if the first flight from the client doesn't contain the full client hello) then this could introduce a more significant delay, but AFAICT no normal client should ever do that (and we'd have to do some kind of wait regardless eventually if they did - we can't really do anything useful without a complete client hello).

This is just intended to improve UX and smooth the path towards dynamic Application selection (as used in #63995). A few things this doesn't do:

It doesn't wait for handshake completion. It's just processing of the client hello. Completion would imply an extra round trip, and thereby defeat 0RTT benefits entirely.
It doesn't improve security (though it helps avoid some footguns). Existing mechanisms already ensure we can't read or write data that isn't correctly within the TLS handshake (deferred data on new connections until the handshake completes, or allowing early data that's explicitly marked as such on resumed connections)
It doesn't change client behaviour. In the client case, the session is available on creation, and you always have to wait for opened. Dynamic app selection there would wait for full handshake completion anyway, since that's the only way to know the confirmed ALPN, which you'll want in most cases (though we don't currently support multiple ALPN for clients anyway). All deferred for later.
It doesn't expose these failed TLS sessions in any way. In future we will probably want a tlsClientError analogue, but imo that was true before as well and we can continue to defer it for now. Most servers aren't that interested in clients who fail to connect, it's not a top priority.

This ensures we don't fire session events for totally invalid TLS handshakes - fundamental errors, bad SNI/ALPN values, or anything else that our TLS config would reject. Instead, it means servers can access servername & alpnProtocol synchronously as soon as the event is fired - all key session data is available and it's immediately usable. We don't want to defer further to handshake completed, since that'd be an extra RT, and defeat 0RTT benefits entirely. ClientHello processed without errors is sufficient for now. This isn't a security mechanism. Existing structures will defer actually sending & receiving anything that's not marked explicitly as early data until the handshake completes anyway. Signed-off-by: Tim Perry <pimterry@gmail.com>

nodejs-github-bot · 2026-06-25T15:18:26Z

Review requested:

@nodejs/quic

jasnell · 2026-07-06T00:36:14Z

+ auto emits = std::move(impl_->deferred_emits_);
+ for (auto& emit : emits) {
+ if (is_destroyed()) return;
+ emit();


Since each of these is a C++-to-JavaScript call, I wonder if it would be possible to batch them to a new callback. Essentially, rather than enqueuing a function, enqueue the arguments and type of emit, send them all to JavaScript at once and process each one there instead. Calls from C++-to-JavaScript can be a bit expensive to set up.

This can be looked at later tho.

I've left this for now. It looks likely to be a little fiddly, and I think it rarely comes up (just a couple of 0RTT events, or keylog/qlog when they're enabled) but we can explore as an optimization later.

nodejs-github-bot · 2026-07-07T03:31:00Z

CI: https://ci.nodejs.org/job/node-test-pull-request/74617/

…ssed Cache ALPN & servername once set, update field types and docs.

nodejs-github-bot · 2026-07-08T14:47:06Z

CI: https://ci.nodejs.org/job/node-test-pull-request/74665/

codecov · 2026-07-08T16:08:19Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 90.24%. Comparing base (e6a8d06) to head (8d11c96).
⚠️ Report is 420 commits behind head on main.

Additional details and impacted files

@@ Coverage Diff @@## main #64132 +/- ##
==========================================
- Coverage 92.01% 90.24% -1.78% 
==========================================
Files 379 741 +362 Lines 166972 241037 +74065 Branches 25554 45411 +19857 ==========================================
+ Hits 153639 217513 +63874 - Misses 13041 15108 +2067 - Partials 292 8416 +8124

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

... and 543 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.

nodejs-github-bot · 2026-07-08T18:39:40Z

CI: https://ci.nodejs.org/job/node-test-pull-request/74676/

pimterry · 2026-07-23T12:56:06Z

@jasnell when you have a sec, I'd love a re-review here to land this. That last commit is just fixes for the points from your review.

nodejs-github-bot · 2026-07-23T13:44:52Z

Landed in f9715fc

This ensures we don't fire session events for totally invalid TLS handshakes - fundamental errors, bad SNI/ALPN values, or anything else that our TLS config would reject. Instead, it means servers can access servername & alpnProtocol synchronously as soon as the event is fired - all key session data is available and it's immediately usable. We don't want to defer further to handshake completed, since that'd be an extra RT, and defeat 0RTT benefits entirely. ClientHello processed without errors is sufficient for now. This isn't a security mechanism. Existing structures will defer actually sending & receiving anything that's not marked explicitly as early data until the handshake completes anyway. Signed-off-by: Tim Perry <pimterry@gmail.com> PR-URL: #64132 Reviewed-By: James M Snell <jasnell@gmail.com>

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 Jun 25, 2026

pimterry mentioned this pull request Jun 25, 2026
Split HTTP/3 module out from QUIC #63995
Open

jasnell reviewed Jul 6, 2026
View reviewed changes

Comment threaddoc/api/quic.md Outdated

jasnell reviewed Jul 6, 2026
View reviewed changes

Comment threadlib/internal/quic/quic.js Outdated

jasnell reviewed Jul 6, 2026
View reviewed changes

jasnell approved these changes Jul 6, 2026
View reviewed changes

This comment was marked as outdated.
Sign in to view

fixup! quic: defer server session emit until TLS ClientHello is proce…
8d11c96
…ssed Cache ALPN & servername once set, update field types and docs.

pimterry requested a review from jasnell July 8, 2026 14:46

This comment was marked as outdated.
Sign in to view

jasnell approved these changes Jul 23, 2026
View reviewed changes

pimterry added the commit-queue PRs queued for automated landing through the Commit Queue. label Jul 23, 2026

nodejs-github-bot removed the commit-queue PRs queued for automated landing through the Commit Queue. label Jul 23, 2026

nodejs-github-bot merged commit f9715fc into nodejs:mainJul 23, 2026
68 checks passed

aduh95 mentioned this pull request Jul 30, 2026
2026-07-22, Version 26.6.0 (Current) #64655
Merged

github-actionsBot mentioned this pull request Aug 21, 2026
2026-08-26, Version 24.20.0 'Krypton' (LTS) #65461
Merged

pimterry mentioned this pull request Aug 24, 2026
quic: reuse TLS pause machinery to drop event deferral & improve 0RTT #65522
Merged