From 2570ff36e75f73febd114cf1e41ca1d6bbd317a7 Mon Sep 17 00:00:00 2001 From: James M Snell Date: Tue, 17 Dec 2024 20:25:57 -0800 Subject: [PATCH] quic: make multiple fixes, cleanups and simplifications --- doc/api/cli.md | 9 + doc/api/quic.md | 397 +- lib/internal/quic/quic.js | 305 +- lib/internal/quic/state.js | 32 +- lib/internal/quic/stats.js | 23 - lib/internal/quic/symbols.js | 34 +- lib/quic.js | 5 + src/node_builtins.cc | 1 + src/quic/application.cc | 209 +- src/quic/application.h | 11 +- src/quic/bindingdata.h | 6 +- src/quic/endpoint.cc | 216 +- src/quic/endpoint.h | 10 +- src/quic/http3.cc | 134 +- src/quic/http3.h | 33 +- src/quic/session.cc | 3714 +++++++++-------- src/quic/session.h | 253 +- src/quic/sessionticket.cc | 5 +- src/quic/streams.cc | 40 +- src/quic/streams.h | 36 +- src/quic/tlscontext.cc | 20 +- src/quic/tlscontext.h | 1 + src/quic/transportparams.cc | 22 +- src/quic/transportparams.h | 2 +- test/parallel/test-process-get-builtin.mjs | 2 + test/parallel/test-quic-handshake.js | 89 + ...-quic-internal-endpoint-listen-defaults.js | 11 +- .../test-quic-internal-endpoint-options.js | 4 +- ...test-quic-internal-endpoint-stats-state.js | 6 - test/parallel/test-require-resolve.js | 2 + 30 files changed, 3061 insertions(+), 2571 deletions(-) create mode 100644 test/parallel/test-quic-handshake.js diff --git a/doc/api/cli.md b/doc/api/cli.md index 2425c504156575..386aabe115ab1e 100644 --- a/doc/api/cli.md +++ b/doc/api/cli.md @@ -966,6 +966,14 @@ If the ES module being `require()`'d contains top-level `await`, this flag allows Node.js to evaluate the module, try to locate the top-level awaits, and print their location to help users find them. +### `--experimental-quic` + + + +Enables the experimental `node:quic` built-in module. + ### `--experimental-require-module` * `error` {any} -* Returns: {Promise} Forcefully closes the endpoint by forcing all open sessions to be immediately -closed. Returns `endpoint.closed`. +closed. ### `endpoint.destroyed` @@ -383,6 +394,8 @@ added: REPLACEME added: REPLACEME --> +A `QuicSession` represents the local side of a QUIC connection. + ### `session.close()` * `error` {any} -* Returns: {Promise} + +Immediately destroy the session. All streams will be destroys and the +session will be closed. ### `session.destroyed` @@ -416,6 +438,8 @@ added: REPLACEME * {boolean} +True if `session.destroy()` has been called. Read only. + ### `session.endpoint` * `options` {Object} - * `headers` {Object} + * `body` {ArrayBuffer | ArrayBufferView | Blob} * Returns: {quic.QuicStream} +Open a new bidirectional stream. If the `body` option is not specified, +the outgoing stream will be half-closed. + ### `session.openUnidirectionalStream([options])` * `options` {Object} - * `headers` {Object + * `body` {ArrayBuffer | ArrayBufferView | Blob} * Returns: {quic.QuicStream} +Open a new unidirectional stream. If the `body` option is not specified, +the outgoing stream will be closed. + ### `session.path` -* `datagram` {Uint8Array} +* `datagram` {string|ArrayBufferView} * Returns: {bigint} +Sends an unreliable datagram to the remote peer, returning the datagram ID. +If the datagram payload is specified as an `ArrayBufferView`, then ownership of +that view will be transfered to the underlying stream. + ### `session.state` +Initiate a key update for the session. + ### `session[Symbol.asyncDispose]()` +Calls `session.close()` and returns a promise that fulfills when the +session has closed. + ## Class: `QuicSessionState` - -* {boolean} - ### `sessionState.isHandshakeCompleted` - -* {bigint} - ### `sessionStats.handshakeCompletedAt` - -* {bigint} - ### `sessionStats.bytesReceived` - -* {bigint} - ### `sessionStats.maxBytesInFlights` * `error` {any} -* Returns: {Promise} + +Immediately and abruptly destroys the stream. ### `stream.destroyed` @@ -918,6 +950,8 @@ added: REPLACEME * {boolean} +True if `stream.destroy()` has been called. + ### `stream.direction` - -* {quic.OnHeadersCallback} +The callback to invoke when the stream is blocked. Read/write. ### `stream.onreset` @@ -958,13 +990,7 @@ added: REPLACEME * {quic.OnStreamErrorCallback} -### `stream.ontrailers` - - - -* {quic.OnTrailersCallback} +The callback to invoke when the stream is reset. Read/write. ### `stream.pull(callback)` @@ -974,13 +1000,8 @@ added: REPLACEME * `callback` {quic.OnPullCallback} -### `stream.sendHeaders(headers)` - - - -* `headers` {Object} +Read received data from the stream. The callback will be invoked with the +next chunk of received data. ### `stream.session` @@ -990,6 +1011,8 @@ added: REPLACEME * {quic.QuicSession} +The session that created this stream. Read only. + ### `stream.state` - -* {boolean} - ### `streamState.wantsReset` - -* {boolean} - ### `streamState.writeEnded` - -#### `applicationOptions.maxHeaderPairs` - - - -* {bigint|number} The maximum number of header pairs that can be received. - -#### `applicationOptions.maxHeaderLength` - - - -* {bigint|number} The maximum number of header bytes that can be received. - -#### `applicationOptions.maxFieldSectionSize` - - - -* {bigint|number} The maximum header field section size. - -#### `applicationOptions.qpackMaxDTableCapacity` - - - -* {bigint|number} The QPack maximum dynamic table capacity. - -#### `applicationOptions.qpackEncoderMaxDTableCapacity` - - - -* {bigint|number} The QPack encoder maximum dynamic table capacity. - -#### `applicationOptions.qpackBlockedStreams` - - - -* {bigint|number} The maximum number of QPack blocked streams. - -#### `applicationOptions.enableConnectProtocol` - - - -* {boolean} - -True to allow use of the `CONNECT` method when using HTTP/3. - -#### `applicationOptions.enableDatagrams` - - - -* {boolean} - -True to allow use of unreliable datagrams. - ### Type: `EndpointOptions` -#### `sessionOptions.application` - - - -* {quic.ApplicationOptions} - -The application-level options to use for the session. - -#### `sessionOptions.minVersion` +#### `sessionOptions.alpn` -* {number} +* {string} -The minimum QUIC version number to allow. This is an advanced option that users -typically won't have need to specify. +The ALPN protocol identifier. -#### `sessionOptions.preferredAddressPolicy` +#### `sessionOptions.ca` -* {string} One of `'use'`, `'ignore'`, or `'default'`. +* {ArrayBuffer|ArrayBufferView|ArrayBuffer\[]|ArrayBufferView\[]} -When the remote peer advertises a preferred address, this option specifies whether -to use it or ignore it. +The CA certificates to use for sessions. -#### `sessionOptions.qlog` +#### `sessionOptions.certs` -* {boolean} - -True if qlog output should be enabled. - -#### `sessionOptions.sessionTicket` - - +* {ArrayBuffer|ArrayBufferView|ArrayBuffer\[]|ArrayBufferView\[]} -* {ArrayBufferView} A session ticket to use for 0RTT session resumption. +The TLS certificates to use for sessions. -#### `sessionOptions.tls` +#### `sessionOptions.ciphers` -* {quic.TlsOptions} +* {string} -The TLS options to use for the session. +The list of supported TLS 1.3 cipher algorithms. -#### `sessionOptions.transportParams` +#### `sessionOptions.crl` -* {quic.TransportParams} +* {ArrayBuffer|ArrayBufferView|ArrayBuffer\[]|ArrayBufferView\[]} -The QUIC transport parameters to use for the session. +The CRL to use for sessions. -#### `sessionOptions.version` +#### `sessionOptions.groups` -* {number} - -The QUIC version number to use. This is an advanced option that users typically -won't have need to specify. - -### Type: `TlsOptions` +* {string} - +The list of support TLS 1.3 cipher groups. -#### `tlsOptions.sni` +#### `sessionOptions.keylog` -* {string} +* {boolean} -The peer server name to target. +True to enable TLS keylogging output. -#### `tlsOptions.alpn` +#### `sessionOptions.keys` -* {string} +* {KeyObject|CryptoKey|KeyObject\[]|CryptoKey\[]} -The ALPN protocol identifier. +The TLS crypto keys to use for sessions. -#### `tlsOptions.ciphers` +#### `sessionOptions.minVersion` -* {string} +* {number} -The list of supported TLS 1.3 cipher algorithms. +The minimum QUIC version number to allow. This is an advanced option that users +typically won't have need to specify. -#### `tlsOptions.groups` +#### `sessionOptions.preferredAddressPolicy` -* {string} +* {string} One of `'use'`, `'ignore'`, or `'default'`. -The list of support TLS 1.3 cipher groups. +When the remote peer advertises a preferred address, this option specifies whether +to use it or ignore it. -#### `tlsOptions.keylog` +#### `sessionOptions.qlog` -* {boolean} - -True to require verification of TLS client certificate. +* {ArrayBufferView} A session ticket to use for 0RTT session resumption. -#### `tlsOptions.tlsTrace` +#### `sessionOptions.sni` -* {boolean} +* {string} -True to enable TLS tracing output. +The peer server name to target. -#### `tlsOptions.verifyPrivateKey` +#### `sessionOptions.tlsTrace` -* {KeyObject|CryptoKey|KeyObject\[]|CryptoKey\[]} +* {quic.TransportParams} -The TLS crypto keys to use for sessions. +The QUIC transport parameters to use for the session. -#### `tlsOptions.certs` +#### `sessionOptions.verifyClient` -* {ArrayBuffer|ArrayBufferView|ArrayBuffer\[]|ArrayBufferView\[]} +* {boolean} -The TLS certificates to use for sessions. +True to require verification of TLS client certificate. -#### `tlsOptions.ca` +#### `sessionOptions.verifyPrivateKey` -* {ArrayBuffer|ArrayBufferView|ArrayBuffer\[]|ArrayBufferView\[]} +* {boolean} -The CA certificates to use for sessions. +True to require private key verification. -#### `tlsOptions.crl` +#### `sessionOptions.version` -* {ArrayBuffer|ArrayBufferView|ArrayBuffer\[]|ArrayBufferView\[]} +* {number} -The CRL to use for sessions. +The QUIC version number to use. This is an advanced option that users typically +won't have need to specify. ### Type: `TransportParams` @@ -1990,24 +1901,6 @@ added: REPLACEME * `this` {quic.QuicStream} * `error` {any} -### Callback: `OnHeadersCallback` - - - -* `this` {quic.QuicStream} -* `headers` {Object} -* `kind` {string} - -### Callback: `OnTrailersCallback` - - - -* `this` {quic.QuicStream} - ### Callback: `OnPullCallback`