diff --git a/doc/api/quic.md b/doc/api/quic.md index af6883f61d2f49..fd43c2f96be1b6 100644 --- a/doc/api/quic.md +++ b/doc/api/quic.md @@ -32,17 +32,24 @@ used as both a client and a server. import { QuicEndpoint } from 'node:quic'; const endpoint = new QuicEndpoint(); +const alpn = 'foo'; // Server... +const keys = getKeysSomehow(); +const cets = getCertsSomehow(); + endpoint.listen((session) => { session.onstream = (stream) => { // Handle the stream.... }; -}); +}, { alpn, keys, certs }); // Client... -const client = endpoint.connect('123.123.123.123:8888'); -const stream = client.openBidirectionalStream(); +const enc = new TextEncoder(); +const client = endpoint.connect('123.123.123.123:8888', { alpn }); +const stream = client.openUnidirectionalStream({ + body: enc.encode('hello world'), +}); ``` ### `new QuicEndpoint([options])` @@ -130,10 +137,9 @@ added: REPLACEME --> * `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 +389,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 +433,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 +945,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 +985,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 +995,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 +1006,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 +1896,6 @@ added: REPLACEME * `this` {quic.QuicStream} * `error` {any} -### Callback: `OnHeadersCallback` - - - -* `this` {quic.QuicStream} -* `headers` {Object} -* `kind` {string} - -### Callback: `OnTrailersCallback` - - - -* `this` {quic.QuicStream} - ### Callback: `OnPullCallback`