quic: add autoWrap option to auto-attach HTTP/3

Author: pimterry

doc/api/quic.md

@@ -476,7 +476,8 @@ added: v23.8.0
 
 * `address` {string|net.SocketAddress}
 * `options` {quic.SessionOptions}
-* Returns: {Promise} a promise for a {quic.QuicSession}
+* Returns: {Promise} a promise for a {quic.QuicSession}, or {quic.Http3Session}
+  if [`sessionOptions.autoWrap`][] is enabled and an HTTP/3 ALPN is negotiated.
 
 Initiate a new client-side session.
 
@@ -3061,6 +3062,23 @@ list that the client also supports.
 
 This option is required; omitting it throws `ERR_MISSING_OPTION`.
 
+#### `sessionOptions.autoWrap`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+* Type: {boolean}
+* **Default:** `true`
+
+If this option is set for [`quic.connect()`][] or [`quic.listen()`][], then
+sessions are automatically exposed as wrapped [`Http3Session`][] instances
+instead of raw [`QuicSession`][], if an HTTP/3 ALPN (`h3` or an `h3-*` draft)
+is negotiated.
+
+Set this to `false` to always receive a raw [`QuicSession`][] and configure
+HTTP/3 yourself with [`Http3Session.from()`][] instead.
+
 #### `sessionOptions.ca`
 
 <!-- YAML
@@ -3816,7 +3834,7 @@ added: v23.8.0
 -->
 
 * `this` {quic.QuicEndpoint}
-* `session` {quic.QuicSession}
+* `session` {quic.QuicSession|quic.Http3Session}
 
 The callback function that is invoked when a new server session is initiated by
 a remote peer. It is called once the peer's TLS `ClientHello` has been
@@ -4063,10 +4081,13 @@ added:
  - v24.20.0
 -->
 
-HTTP/3, backed by `nghttp3`, can run on top of a QUIC session by attaching
-an [`Http3Session`][]. Negotiating the `'h3'` ALPN tells the peer which
-protocol to speak, but does not change how the connection works locally,
-so both are needed. See [`new Http3Session()`][] for more details.
+HTTP/3, backed by `nghttp3`, runs on top of a QUIC session as an
+[`Http3Session`][]. By default, [`quic.listen()`][] and [`quic.connect()`][]
+provide one whenever an HTTP/3 ALPN is negotiated (see
+[`sessionOptions.autoWrap`][]).
+
+HTTP/3 can also be configured manually, by setting `autoWrap: false` and using
+the [`Http3Session.from()`][] API to attach HTTP/3 to an existing QUIC session.
 
 Attaching the HTTP/3 application enables a number of stream- and
 session-level capabilities that are not available to non-HTTP/3
@@ -4104,13 +4125,13 @@ applications:
 ### Minimal HTTP/3 client
 
 ```mjs
-import { connect, Http3Session } from 'node:quic';
+import { connect } from 'node:quic';
 import process from 'node:process';
 
-const session = Http3Session.from(await connect('example.com:443', {
+const session = await connect('example.com:443', {
   alpn: 'h3',
   servername: 'example.com',
-}));
+});
 await session.opened;
 
 const stream = await session.createBidirectionalStream({
@@ -4155,15 +4176,11 @@ A few things to note:
 ### Minimal HTTP/3 server
 
 ```mjs
-import { listen, Http3Session } from 'node:quic';
+import { listen } from 'node:quic';
 
 const encoder = new TextEncoder();
 
-const endpoint = await listen((quicSession) => {
-  // Attaching HTTP/3 has to happen here, synchronously, before the
-  // callback returns.
-  const session = Http3Session.from(quicSession);
-
+const endpoint = await listen((session) => {
   // The session.onstream callback fires for each new client-initiated
   // stream. It is optional here: with `onheaders` configured below,
   // request streams are consumed through that callback.
@@ -4999,6 +5016,7 @@ throughput issues caused by flow control.
 [`session.onstream`]: #sessiononstream
 [`session.opened`]: #sessionopened
 [`session.sendDatagram()`]: #sessionsenddatagramdatagram-encoding
+[`sessionOptions.autoWrap`]: #sessionoptionsautowrap
 [`sessionOptions.cc`]: #sessionoptionscc
 [`sessionOptions.ciphers`]: #sessionoptionsciphers
 [`sessionOptions.datagramDropPolicy`]: #sessionoptionsdatagramdroppolicy

lib/internal/quic/quic.js

@@ -19,6 +19,7 @@ const {
   PromiseResolve,
   PromiseWithResolvers,
   SafeSet,
+  StringPrototypeStartsWith,
   Symbol,
   SymbolAsyncDispose,
   SymbolAsyncIterator,
@@ -407,6 +408,8 @@ const endpointRegistry = new SafeSet();
  * @property {string|string[]} [alpn] The ALPN protocol identifier(s).
  *   For client sessions, a single string. For server sessions, an array
  *   of protocol names in preference order.
+ * @property {boolean} [autoWrap] Whether to provide the session wrapped in the
+ *   application matching its ALPN (e.g. an Http3Session for 'h3').
  * @property {string} [ciphers] The TLS ciphers
  * @property {string} [groups] The TLS key-exchange groups
  * @property {Array<'zlib'|'brotli'|'zstd'>} [certificateCompression] The
@@ -1320,6 +1323,21 @@ function updateHeaderInterest(handle, inner) {
   );
 }
 
+/**
+ * Wraps a new session in the application matching its ALPN, if any. The
+ * http3 module is loaded lazily, as it depends on this one.
+ * @param {QuicSession} session
+ * @param {string} alpn
+ * @returns {QuicSession|Http3Session}
+ */
+function autoWrapSession(session, alpn) {
+  if (alpn === 'h3' || StringPrototypeStartsWith(alpn, 'h3-')) {
+    const { Http3Session } = require('internal/quic/http3');
+    return Http3Session.from(session);
+  }
+  return session;
+}
+
 /**
  * Applies session and stream callbacks from an options object to a session.
  * @param {QuicSession} session
@@ -4385,6 +4403,7 @@ class QuicEndpoint {
     stats: undefined,
     truncatedReads: undefined,
     onsession: undefined,
+    autoWrap: undefined,
     sessionCallbacks: undefined,
   };
 
@@ -4690,10 +4709,12 @@ class QuicEndpoint {
       onwanttrailers,
       // Stored on the endpoint and applied to each incoming session.
       truncatedReads,
+      autoWrap,
       ...rest
     } = options;
 
     inner.truncatedReads = truncatedReads;
+    inner.autoWrap = autoWrap;
 
     // Store session and stream callbacks to apply to each new incoming session.
     inner.sessionCallbacks = {
@@ -4725,15 +4746,17 @@ class QuicEndpoint {
    * Initiates a session with a remote endpoint.
    * @param {object} address
    * @param {SessionOptions} [options]
-   * @returns {QuicSession}
+   * @param {string} alpn The client's offered ALPN
+   * @returns {QuicSession|Http3Session}
    */
-  [kConnect](address, options) {
+  [kConnect](address, options, alpn) {
     assertEndpointNotClosedOrClosing(this);
     assertEndpointIsNotBusy(this);
     validateObject(options, 'options');
     const {
       sessionTicket,
       truncatedReads,
+      autoWrap,
       ...rest
     } = options;
 
@@ -4750,7 +4773,7 @@ class QuicEndpoint {
     if (options.verifyPeer !== undefined) {
       session[kVerifyPeer] = options.verifyPeer;
     }
-    return session;
+    return autoWrap ? autoWrapSession(session, alpn) : session;
   }
 
   /**
@@ -4984,6 +5007,8 @@ class QuicEndpoint {
     if (inner.sessionCallbacks) {
       applyCallbacks(session, inner.sessionCallbacks);
     }
+    const wrapped = inner.autoWrap ?
+      autoWrapSession(session, session.alpnProtocol) : session;
     if (onEndpointServerSessionChannel.hasSubscribers) {
       onEndpointServerSessionChannel.publish({
         __proto__: null,
@@ -4997,7 +5022,7 @@ class QuicEndpoint {
     // endpoint with the error rather than surfacing as an unhandled
     // exception or unhandled rejection coming out of the C++ -> JS
     // boundary.
-    safeCallbackInvoke(inner.onsession, this, session);
+    safeCallbackInvoke(inner.onsession, this, wrapped);
   }
 
   // Called by the QuicSession when it closes to remove itself from
@@ -5472,6 +5497,7 @@ function processSessionOptions(options, config = kEmptyObject) {
     streamIdleTimeout,
     verifyPeer = 'auto',
     truncatedReads = 'error',
+    autoWrap,
     // Session callbacks that can be set at construction time to avoid
     // race conditions with events that fire during or immediately
     // after the handshake.
@@ -5554,6 +5580,8 @@ function processSessionOptions(options, config = kEmptyObject) {
 
   const tls = processTlsOptions(options, forServer);
 
+  if (autoWrap !== undefined) validateBoolean(autoWrap, 'options.autoWrap');
+
   const actualEndpoint = processEndpointOption(endpoint,
                                                reuseEndpoint,
                                                forServer,
@@ -5584,6 +5612,7 @@ function processSessionOptions(options, config = kEmptyObject) {
     },
     verifyPeer,
     truncatedReads,
+    autoWrap: autoWrap ?? true,
     qlog,
     maxPayloadSize,
     unacknowledgedPacketThreshold,
@@ -5675,7 +5704,8 @@ async function connect(address, options = kEmptyObject) {
     });
   }
 
-  const session = endpoint[kConnect](address[kSocketAddressHandle], rest);
+  const session = endpoint[kConnect](address[kSocketAddressHandle], rest,
+                                     options.alpn);
 
   if (onEndpointClientSessionChannel.hasSubscribers) {
     onEndpointClientSessionChannel.publish({

test/parallel/test-quic-alpn-h3.mjs

@@ -14,9 +14,9 @@ const { createPrivateKey } = await import('node:crypto');
 const key = createPrivateKey(fixtures.readKey('agent1-key.pem'));
 const cert = fixtures.readKey('agent1-cert.pem');
 
-// Negotiating the h3 ALPN does not itself activate HTTP/3. The ALPN is
-// reported as usual, but the session keeps the default application unless it
-// has an Http3Session attached.
+// With autoWrap off, negotiating the h3 ALPN does not activate HTTP/3. The
+// ALPN is reported as usual, but the session keeps the default application
+// unless an Http3Session is attached.
 
 const serverOpened = Promise.withResolvers();
 
@@ -27,13 +27,15 @@ const serverEndpoint = await listen(mustCall(async (serverSession) => {
   serverOpened.resolve();
 }), {
   alpn: ['h3'],
+  autoWrap: false,
   sni: { '*': { keys: [key], certs: [cert] } },
 });
 
 assert.notStrictEqual(serverEndpoint.address, undefined);
 
 const clientSession = await connect(serverEndpoint.address, {
   alpn: 'h3',
+  autoWrap: false,
   servername: 'localhost',
   verifyPeer: 'manual',
 });

test/parallel/test-quic-h3-attach.mjs

@@ -46,16 +46,6 @@ assert.throws(() => new Http3Session(), { code: 'ERR_ILLEGAL_CONSTRUCTOR' });
     assert.throws(() => Http3Session.from(quicSession),
                   { code: 'ERR_INVALID_STATE' });
 
-    // HTTP/3 frames every stream, so raw streams can no longer be opened:
-    const rawRefused = {
-      code: 'ERR_INVALID_STATE',
-      message: /Raw QUIC streams cannot be created/,
-    };
-    assert.rejects(quicSession.createUnidirectionalStream(), rawRefused)
-      .then(mustCall());
-    assert.rejects(quicSession.createBidirectionalStream(), rawRefused)
-      .then(mustCall());
-
     // Incoming streams are now reported through the Http3Session only:
     assert.throws(() => { quicSession.onstream = () => {}; }, {
       code: 'ERR_INVALID_STATE',

test/parallel/test-quic-h3-autowrap.mjs

@@ -0,0 +1,81 @@
+// Flags: --experimental-quic --no-warnings
+
+// Test: sessions arrive wrapped in the application matching their ALPN,
+// unless autoWrap is false. Servers know the negotiated protocol before
+// surfacing a session, and clients offer exactly one.
+
+import { hasQuic, skip, mustCall } from '../common/index.mjs';
+import assert from 'node:assert';
+import * as fixtures from '../common/fixtures.mjs';
+
+if (!hasQuic) {
+  skip('QUIC is not enabled');
+}
+
+const { listen, connect, Http3Session } = await import('node:quic');
+const { createPrivateKey } = await import('node:crypto');
+
+const key = createPrivateKey(fixtures.readKey('agent1-key.pem'));
+const cert = fixtures.readKey('agent1-cert.pem');
+const clientOpts = { servername: 'localhost', verifyPeer: 'manual' };
+
+const isHttp3 = (session) => session instanceof Http3Session;
+
+// Both sides wrap by ALPN.
+{
+  const seen = [];
+  const endpoint = await listen(mustCall((session) => {
+    seen.push(isHttp3(session));
+    session.onerror = () => {};
+  }, 3), {
+    alpn: ['h3', 'h3-29', 'other'],
+    sni: { '*': { keys: [key], certs: [cert] } },
+  });
+
+  // One protocol: wrapped up front, before the handshake.
+  const single = await connect(endpoint.address, { ...clientOpts, alpn: 'h3' });
+  assert.ok(isHttp3(single));
+  assert.throws(() => Http3Session.from(single.quicSession),
+                { code: 'ERR_INVALID_STATE' });
+  await single.opened;
+  await single.close();
+
+  // Draft ALPNs count as HTTP/3 too.
+  const draft = await connect(endpoint.address, { ...clientOpts, alpn: 'h3-29' });
+  assert.ok(isHttp3(draft));
+  await draft.opened;
+  await draft.close();
+
+  // A non-HTTP/3 protocol stays a plain QuicSession on both sides.
+  const other = await connect(endpoint.address, { ...clientOpts, alpn: 'other' });
+  assert.ok(!isHttp3(other));
+  await other.opened;
+  await other.close();
+
+  await endpoint.close();
+  assert.deepStrictEqual(seen, [true, true, false]);
+}
+
+// Opting out gives the raw session on either side, to attach yourself.
+{
+  const endpoint = await listen(mustCall((quicSession) => {
+    assert.ok(!isHttp3(quicSession));
+    Http3Session.from(quicSession);
+  }), {
+    alpn: ['h3'],
+    autoWrap: false,
+    sni: { '*': { keys: [key], certs: [cert] } },
+  });
+  const quicSession = await connect(endpoint.address,
+                                    { ...clientOpts, alpn: 'h3', autoWrap: false });
+  assert.ok(!isHttp3(quicSession));
+  const session = Http3Session.from(quicSession);
+  await session.opened;
+  await session.close();
+  await endpoint.close();
+}
+
+for (const autoWrap of [1, 'yes', null]) {
+  await assert.rejects(connect('127.0.0.1:1', { ...clientOpts, alpn: 'h3', autoWrap }),
+                       { code: 'ERR_INVALID_ARG_TYPE', message: /options\.autoWrap/ });
+}

test/parallel/test-quic-h3-uni-stream-teardown.mjs

@@ -15,7 +15,7 @@ if (!hasQuic) {
 }
 
 const { createPrivateKey } = await import('node:crypto');
-const { listen, connect, Http3Session } = await import('node:quic');
+const { listen, connect } = await import('node:quic');
 
 const key = createPrivateKey(fixtures.readKey('agent1-key.pem'));
 const cert = fixtures.readKey('agent1-cert.pem');
@@ -25,11 +25,11 @@ const endpoint = await listen(mustNotCall(), {
   sni: { '*': { keys: [key], certs: [cert] } },
 });
 
-const session = new Http3Session(await connect(endpoint.address, {
+const session = await connect(endpoint.address, {
   alpn: 'h3',
   servername: 'localhost',
   verifyPeer: 'manual',
-}));
+});
 
 const refused = {
   code: 'ERR_INVALID_STATE',