{ "type": "module", "source": "doc/api/quic.md", "modules": [ { "textRaw": "QUIC", "name": "quic", "introduced_in": "v15.0.0", "stability": 1, "stabilityText": "Experimental", "desc": "
The net
module provides an implementation of the QUIC protocol. To\naccess it, the Node.js binary must be compiled using the\n--experimental-quic
configuration flag.
const { createQuicSocket } = require('net');\n
\n'use strict';\n\nconst key = getTLSKeySomehow();\nconst cert = getTLSCertSomehow();\n\nconst { createQuicSocket } = require('net');\n\n// Create the QUIC UDP IPv4 socket bound to local IP port 1234\nconst socket = createQuicSocket({ endpoint: { port: 1234 } });\n\nsocket.on('session', async (session) => {\n // A new server side session has been created!\n\n // The peer opened a new stream!\n session.on('stream', (stream) => {\n // Let's say hello\n stream.end('Hello World');\n\n // Let's see what the peer has to say...\n stream.setEncoding('utf8');\n stream.on('data', console.log);\n stream.on('end', () => console.log('stream ended'));\n });\n\n const uni = await session.openStream({ halfOpen: true });\n uni.write('hi ');\n uni.end('from the server!');\n});\n\n// Tell the socket to operate as a server using the given\n// key and certificate to secure new connections, using\n// the fictional 'hello' application protocol.\n(async function() {\n await socket.listen({ key, cert, alpn: 'hello' });\n console.log('The socket is listening for sessions!');\n})();\n\n
",
"modules": [
{
"textRaw": "QUIC basics",
"name": "quic_basics",
"desc": "QUIC is a UDP-based network transport protocol that includes built-in security\nvia TLS 1.3, flow control, error correction, connection migration,\nmultiplexing, and more.
\nWithin the Node.js implementation of the QUIC protocol, there are three main\ncomponents: the QuicSocket
, the QuicSession
and the QuicStream
.
A QuicSocket
encapsulates a binding to one or more local UDP ports. It is\nused to send data to, and receive data from, remote endpoints. Once created,\na QuicSocket
is associated with a local network address and IP port and can\nact as both a QUIC client and server simultaneously. User code at the\nJavaScript level interacts with the QuicSocket
object to:
QuicSession
instances;QuicSession
instances; orUnlike the net.Socket
and tls.TLSSocket
, a QuicSocket
instance cannot be\ndirectly used by user code at the JavaScript level to send or receive data over\nthe network.
A QuicSession
represents a logical connection between two QUIC endpoints (a\nclient and a server). In the JavaScript API, each is represented by the\nQuicClientSession
and QuicServerSession
specializations.
At any given time, a QuicSession
exists is one of four possible states:
Initial
- Entered as soon as the QuicSession
is created.Handshake
- Entered as soon as the TLS 1.3 handshake between the client and\nserver begins. The handshake is always initiated by the client.Ready
- Entered as soon as the TLS 1.3 handshake completes. Once the\nQuicSession
enters the Ready
state, it may be used to exchange\napplication data using QuicStream
instances.Closed
- Entered as soon as the QuicSession
connection has been\nterminated.New instances of QuicClientSession
are created using the connect()
\nfunction on a QuicSocket
as in the example below:
const { createQuicSocket } = require('net');\n\n// Create a QuicSocket associated with localhost and port 1234\nconst socket = createQuicSocket({ endpoint: { port: 1234 } });\n\n(async function() {\n const client = await socket.connect({\n address: 'example.com',\n port: 4567,\n alpn: 'foo'\n });\n})();\n
\nAs soon as the QuicClientSession
is created, the address
provided in\nthe connect options will be resolved to an IP address (if necessary), and\nthe TLS 1.3 handshake will begin. The QuicClientSession
cannot be used\nto exchange application data until after the 'secure'
event has been\nemitted by the QuicClientSession
object, signaling the completion of\nthe TLS 1.3 handshake.
client.on('secure', () => {\n // The QuicClientSession can now be used for application data\n});\n
\nNew instances of QuicServerSession
are created internally by the\nQuicSocket
if it has been configured to listen for new connections\nusing the listen()
method.
const { createQuicSocket } = require('net');\n\nconst key = getTLSKeySomehow();\nconst cert = getTLSCertSomehow();\n\nconst socket = createQuicSocket();\n\nsocket.on('session', (session) => {\n session.on('secure', () => {\n // The QuicServerSession can now be used for application data\n });\n});\n\n(async function() {\n await socket.listen({ key, cert, alpn: 'foo' });\n})();\n
\nAs with client QuicSession
instances, the QuicServerSession
cannot be\nused to exchange application data until the 'secure'
event has been emitted.
QUIC uses the TLS 1.3 ALPN (\"Application-Layer Protocol Negotiation\")\nextension to identify the application level protocol that is using the QUIC\nconnection. Every QuicSession
instance has an ALPN identifier that must be\nspecified in either the connect()
or listen()
options. ALPN identifiers that\nare known to Node.js (such as the ALPN identifier for HTTP/3) will alter how the\nQuicSession
and QuicStream
objects operate internally, but the QUIC\nimplementation for Node.js has been designed to allow any ALPN to be specified\nand used.
Once a QuicSession
transitions to the Ready
state, QuicStream
instances\nmay be created and used to exchange application data. On a general level, all\nQuicStream
instances are simply Node.js Duplex Streams that allow\nbidirectional data flow between the QUIC client and server. However, the\napplication protocol negotiated for the QuicSession
may alter the semantics\nand operation of a QuicStream
associated with the session. Specifically,\nsome features of the QuicStream
(e.g. headers) are enabled only if the\napplication protocol selected is known by Node.js to support those features.
Once the QuicSession
is ready, a QuicStream
may be created by either the\nclient or server, and may be unidirectional or bidirectional.
The openStream()
method is used to create a new QuicStream
:
// Create a new bidirectional stream\nasync function createStreams(session) {\n const stream1 = await session.openStream();\n\n // Create a new unidirectional stream\n const stream2 = await session.openStream({ halfOpen: true });\n}\n
\nAs suggested by the names, a bidirectional stream allows data to be sent on\na stream in both directions, by both client and server, regardless of which\npeer opened the stream. A unidirectional stream can be written to only by the\nQuicSession that opened it.
\nThe 'stream'
event is emitted by the QuicSession
when a new QuicStream
\nhas been initiated by the connected peer:
session.on('stream', (stream) => {\n if (stream.bidirectional) {\n stream.write('Hello World');\n stream.end();\n }\n stream.on('data', console.log);\n stream.on('end', () => {});\n});\n
",
"modules": [
{
"textRaw": "QuicStream headers",
"name": "quicstream_headers",
"desc": "Some QUIC application protocols (like HTTP/3) use headers.
\nThere are four kinds of headers that the Node.js QUIC implementation\nis capable of handling dependent entirely on known application protocol\nsupport:
\nThese categories correlate exactly with the equivalent HTTP\nconcepts:
\n1xx
status code.If headers are supported by the application protocol in use for\na given QuicSession
, the 'initialHeaders'
, 'informationalHeaders'
,\nand 'trailingHeaders'
events will be emitted by the QuicStream
\nobject when headers are received; and the submitInformationalHeaders()
,\nsubmitInitialHeaders()
, and submitTrailingHeaders()
methods can be\nused to send headers.
HTTP/3 is an application layer protocol that uses QUIC as the transport.
\nTBD
", "type": "module", "displayName": "QUIC and HTTP/3" }, { "textRaw": "QUIC JavaScript API", "name": "quic_javascript_api", "methods": [ { "textRaw": "`net.createQuicSocket([options])`", "type": "method", "name": "createQuicSocket", "meta": { "added": [ "v15.0.0" ], "changes": [] }, "signatures": [ { "params": [ { "textRaw": "`options` {Object}", "name": "options", "type": "Object", "options": [ { "textRaw": "`client` {Object} A default configuration for QUIC client sessions created using `quicsocket.connect()`.", "name": "client", "type": "Object", "desc": "A default configuration for QUIC client sessions created using `quicsocket.connect()`." }, { "textRaw": "`disableStatelessReset` {boolean} When `true` the `QuicSocket` will not send stateless resets. **Default**: `false`.", "name": "disableStatelessReset", "type": "boolean", "desc": "When `true` the `QuicSocket` will not send stateless resets. **Default**: `false`." }, { "textRaw": "`endpoint` {Object} An object describing the local address to bind to.", "name": "endpoint", "type": "Object", "desc": "An object describing the local address to bind to.", "options": [ { "textRaw": "`address` {string} The local address to bind to. This may be an IPv4 or IPv6 address or a host name. If a host name is given, it will be resolved to an IP address.", "name": "address", "type": "string", "desc": "The local address to bind to. This may be an IPv4 or IPv6 address or a host name. If a host name is given, it will be resolved to an IP address." }, { "textRaw": "`port` {number} The local port to bind to.", "name": "port", "type": "number", "desc": "The local port to bind to." }, { "textRaw": "`type` {string} Can be one of `'udp4'`, `'upd6'`, or `'udp6-only'` to use IPv4, IPv6, or IPv6 with dual-stack mode disabled. **Default**: `'udp4'`.", "name": "type", "type": "string", "desc": "Can be one of `'udp4'`, `'upd6'`, or `'udp6-only'` to use IPv4, IPv6, or IPv6 with dual-stack mode disabled. **Default**: `'udp4'`." } ] }, { "textRaw": "`lookup` {Function} A [custom DNS lookup function][]. **Default**: undefined.", "name": "lookup", "type": "Function", "desc": "A [custom DNS lookup function][]. **Default**: undefined." }, { "textRaw": "`maxConnections` {number} The maximum number of total active inbound connections.", "name": "maxConnections", "type": "number", "desc": "The maximum number of total active inbound connections." }, { "textRaw": "`maxConnectionsPerHost` {number} The maximum number of inbound connections allowed per remote host. Default: `100`.", "name": "maxConnectionsPerHost", "type": "number", "desc": "The maximum number of inbound connections allowed per remote host. Default: `100`." }, { "textRaw": "`maxStatelessResetsPerHost` {number} The maximum number of stateless resets that the `QuicSocket` is permitted to send per remote host. Default: `10`.", "name": "maxStatelessResetsPerHost", "type": "number", "desc": "The maximum number of stateless resets that the `QuicSocket` is permitted to send per remote host. Default: `10`." }, { "textRaw": "`qlog` {boolean} Whether to enable ['qlog'][] for incoming sessions. (For outgoing client sessions, set `client.qlog`.) Default: `false`.", "name": "qlog", "type": "boolean", "desc": "Whether to enable ['qlog'][] for incoming sessions. (For outgoing client sessions, set `client.qlog`.) Default: `false`." }, { "textRaw": "`retryTokenTimeout` {number} The maximum number of *seconds* for retry token validation. Default: `10` seconds.", "name": "retryTokenTimeout", "type": "number", "desc": "The maximum number of *seconds* for retry token validation. Default: `10` seconds." }, { "textRaw": "`server` {Object} A default configuration for QUIC server sessions.", "name": "server", "type": "Object", "desc": "A default configuration for QUIC server sessions." }, { "textRaw": "`statelessResetSecret` {Buffer|Uint8Array} A 16-byte `Buffer` or `Uint8Array` providing the secret to use when generating stateless reset tokens. If not specified, a random secret will be generated for the `QuicSocket`. **Default**: `undefined`.", "name": "statelessResetSecret", "type": "Buffer|Uint8Array", "desc": "A 16-byte `Buffer` or `Uint8Array` providing the secret to use when generating stateless reset tokens. If not specified, a random secret will be generated for the `QuicSocket`. **Default**: `undefined`." }, { "textRaw": "`validateAddress` {boolean} When `true`, the `QuicSocket` will use explicit address validation using a QUIC `RETRY` frame when listening for new server sessions. Default: `false`.", "name": "validateAddress", "type": "boolean", "desc": "When `true`, the `QuicSocket` will use explicit address validation using a QUIC `RETRY` frame when listening for new server sessions. Default: `false`." } ] } ] } ], "desc": "The net.createQuicSocket()
function is used to create new QuicSocket
\ninstances associated with a local UDP address.
The QuicEndpoint
wraps a local UDP binding used by a QuicSocket
to send\nand receive data. A single QuicSocket
may be bound to multiple\nQuicEndpoint
instances at any given time.
Users will not create instances of QuicEndpoint
directly.
Tells the kernel to join a multicast group at the given multicastAddress
and\nmulticastInterface
using the IP_ADD_MEMBERSHIP
socket option. If the\nmulticastInterface
argument is not specified, the operating system will\nchoose one interface and will add membership to it. To add membership to every\navailable interface, call addMembership()
multiple times, once per\ninterface.
Binds the QuicEndpoint
if it has not already been bound. User code will\nnot typically be responsible for binding a QuicEndpoint
as the owning\nQuicSocket
will do that automatically.
options
<Object>\nsignal
<AbortSignal> Optionally allows the bind()
to be canceled\nusing an AbortController
.The quicendpoint.bind()
function returns Promise
that will be resolved\nwith the address once the bind operation is successful.
If the QuicEndpoint
has been destroyed, or is destroyed while the Promise
\nis pending, the Promise
will be rejected with an ERR_INVALID_STATE
error.
If an AbortSignal
is specified in the options
and it is triggered while\nthe Promise
is pending, the Promise
will be rejected with an AbortError
.
If quicendpoint.bind()
is called again while a previously returned Promise
\nis still pending or has already successfully resolved, the previously returned\npending Promise
will be returned. If the additional call to\nquicendpoint.bind()
contains an AbortSignal
, the signal
will be ignored.
Closes and destroys the QuicEndpoint
. Returns a Promise
that is resolved\nonce the QuicEndpoint
has been destroyed, or rejects if the QuicEndpoint
\nis destroyed with an error.
The Promise
cannot be canceled. Once quicendpoint.close()
is called, the\nQuicEndpoint
will be destroyed.
Closes and destroys the QuicEndpoint
instance making it unusable.
Instructs the kernel to leave a multicast group at multicastAddress
using the\nIP_DROP_MEMBERSHIP
socket option. This method is automatically called by the\nkernel when the socket is closed or the process terminates, so most apps will\nnever have reason to call this.
If multicastInterface
is not specified, the operating system will attempt to\ndrop membership on all valid interfaces.
Sets or clears the SO_BROADCAST
socket option. When set to true
, UDP\npackets may be sent to a local interface's broadcast address.
All references to scope in this section are referring to IPv6 Zone Indices,\nwhich are defined by RFC 4007. In string form, an IP with a scope index\nis written as 'IP%scope'
where scope is an interface name or interface\nnumber.
Sets the default outgoing multicast interface of the socket to a chosen\ninterface or back to system interface selection. The multicastInterface must\nbe a valid string representation of an IP from the socket's family.
\nFor IPv4 sockets, this should be the IP configured for the desired physical\ninterface. All packets sent to multicast on the socket will be sent on the\ninterface determined by the most recent successful use of this call.
\nFor IPv6 sockets, multicastInterface should include a scope to indicate the\ninterface as in the examples that follow. In IPv6, individual send calls can\nalso use explicit scope in addresses, so only packets sent to a multicast\naddress without specifying an explicit scope are affected by the most recent\nsuccessful use of this call.
\nOn most systems, where scope format uses the interface name:
\nconst { createQuicSocket } = require('net');\nconst socket = createQuicSocket({ endpoint: { type: 'udp6', port: 1234 } });\n\nsocket.on('ready', () => {\n socket.endpoints[0].setMulticastInterface('::%eth1');\n});\n
\nOn Windows, where scope format uses an interface number:
\nconst { createQuicSocket } = require('net');\nconst socket = createQuicSocket({ endpoint: { type: 'udp6', port: 1234 } });\n\nsocket.on('ready', () => {\n socket.endpoints[0].setMulticastInterface('::%2');\n});\n
\nAll systems use an IP of the host on the desired physical interface:
\nconst { createQuicSocket } = require('net');\nconst socket = createQuicSocket({ endpoint: { type: 'udp4', port: 1234 } });\n\nsocket.on('ready', () => {\n socket.endpoints[0].setMulticastInterface('10.0.0.2');\n});\n
",
"modules": [
{
"textRaw": "Call results",
"name": "call_results",
"desc": "A call on a socket that is not ready to send or no longer open may throw a\nNot running Error.
\nIf multicastInterface can not be parsed into an IP then an EINVAL
System\nError is thrown.
On IPv4, if multicastInterface
is a valid address but does not match any\ninterface, or if the address does not match the family then a System Error\nsuch as EADDRNOTAVAIL
or EPROTONOSUP
is thrown.
On IPv6, most errors with specifying or omitting scope will result in the\nsocket continuing to use (or returning to) the system's default interface\nselection.
\nA socket's address family's ANY address (IPv4 '0.0.0.0'
or IPv6 '::'
)\ncan be used to return control of the sockets default outgoing interface to\nthe system for future multicast packets.
Sets or clears the IP_MULTICAST_LOOP
socket option. When set to true
,\nmulticast packets will also be received on the local interface.
Sets the IP_MULTICAST_TTL
socket option. While TTL generally stands for\n\"Time to Live\", in this context it specifies the number of IP hops that a\npacket is allowed to travel through, specifically for multicast traffic. Each\nrouter or gateway that forwards a packet decrements the TTL. If the TTL is\ndecremented to 0
by a router, it will not be forwarded.
The argument passed to setMulticastTTL()
is a number of hops between\n0
and 255
. The default on most systems is 1
but can vary.
Sets the IP_TTL
socket option. While TTL generally stands for \"Time to Live\",\nin this context it specifies the number of IP hops that a packet is allowed to\ntravel through. Each router or gateway that forwards a packet decrements the\nTTL. If the TTL is decremented to 0
by a router, it will not be forwarded.\nChanging TTL values is typically done for network probes or when multicasting.
The argument to setTTL()
is a number of hops between 1
and 255
.\nThe default on most systems is 64
but can vary.
An object containing the address information for a bound QuicEndpoint
.
The object will contain the properties:
\naddress
<string> The local IPv4 or IPv6 address to which the QuicEndpoint
is\nbound.family
<string> Either 'IPv4'
or 'IPv6'
.port
<number> The local IP port to which the QuicEndpoint
is bound.If the QuicEndpoint
is not bound, quicendpoint.address
is an empty object.
Set to true
if the QuicEndpoint
is bound to the local UDP port.
Set to true
if the QuicEndpoint
is in the process of closing.
Set to true
if the QuicEndpoint
has been destroyed.
The system file descriptor the QuicEndpoint
is bound to. This property\nis not set on Windows.
Set to true
if the QuicEndpoint
is in the process of binding to\nthe local UDP port.
The QuicSession
is an abstract base class that defines events, methods, and\nproperties that are shared by both QuicClientSession
and QuicServerSession
.
Users will not create instances of QuicSession
directly.
Emitted after the QuicSession
has been destroyed and is no longer usable.
The 'close'
event will not be emitted more than once.
Emitted immediately before the 'close'
event if the QuicSession
was\ndestroyed with an error.
The callback will be invoked with a single argument:
\nerror
<Object> An Error
object.The 'error'
event will not be emitted more than once.
Emitted when key material is generated or received by a QuicSession
\n(typically during or immediately following the handshake process). This keying\nmaterial can be stored for debugging, as it allows captured TLS traffic to be\ndecrypted. It may be emitted multiple times per QuicSession
instance.
The callback will be invoked with a single argument:
\nline
<Buffer> Line of ASCII text, in NSS SSLKEYLOGFILE format.A typical use case is to append received lines to a common text file, which is\nlater used by software (such as Wireshark) to decrypt the traffic:
\nconst log = fs.createWriteStream('/tmp/ssl-keys.log', { flags: 'a' });\n// ...\nsession.on('keylog', (line) => log.write(line));\n
\nThe 'keylog'
event will be emitted multiple times.
Emitted when a path validation result has been determined. This event\nis strictly informational. When path validation is successful, the\nQuicSession
will automatically update to use the new validated path.
The callback will be invoked with three arguments:
\nresult
<string> Either 'failure'
or 'success'
, denoting the status\nof the path challenge.local
<Object> The local address component of the tested path.remote
<Object> The remote address component of the tested path.The 'pathValidation'
event will be emitted multiple times.
Emitted after the TLS handshake has been completed.
\nThe callback will be invoked with two arguments:
\nservername
<string> The SNI servername requested by the client.alpnProtocol
<string> The negotiated ALPN protocol.cipher
<Object> Information about the selected cipher algorithm.\n\nThese will also be available using the quicsession.servername
,\nquicsession.alpnProtocol
, and quicsession.cipher
properties.
The 'secure'
event will not be emitted more than once.
Emitted when a new QuicStream
has been initiated by the connected peer.
The 'stream'
event may be emitted multiple times.
The number of retransmissions caused by delayed acknowledgments.
" }, { "textRaw": "`address` Type: {Object}", "type": "Object", "name": "Type", "meta": { "added": [ "v15.0.0" ], "changes": [] }, "options": [ { "textRaw": "`address` {string} The local IPv4 or IPv6 address to which the `QuicSession` is bound.", "name": "address", "type": "string", "desc": "The local IPv4 or IPv6 address to which the `QuicSession` is bound." }, { "textRaw": "`family` {string} Either `'IPv4'` or `'IPv6'`.", "name": "family", "type": "string", "desc": "Either `'IPv4'` or `'IPv6'`." }, { "textRaw": "`port` {number} The local IP port to which the `QuicSocket` is bound.", "name": "port", "type": "number", "desc": "The local IP port to which the `QuicSocket` is bound." } ], "desc": "An object containing the local address information for the QuicSocket
to which\nthe QuicSession
is currently associated.
The ALPN protocol identifier negotiated for this session.
" }, { "textRaw": "`quicsession.authenticated`", "name": "authenticated", "desc": "\nTrue if the certificate provided by the peer during the TLS 1.3\nhandshake has been verified.
" }, { "textRaw": "`authenticationError` Type: {Object} An error object", "type": "Object", "name": "Type", "desc": "If quicsession.authenticated
is false, returns an Error
object\nrepresenting the reason the peer certificate verification failed.
The total number of bidirectional streams created for this QuicSession
.
The total number of times the QuicSession
has been blocked from sending\nstream data due to flow control.
Such blocks indicate that transmitted stream data is not being consumed\nquickly enough by the connected peer.
" }, { "textRaw": "`bytesInFlight` Type: {number}", "type": "number", "name": "Type", "meta": { "added": [ "v15.0.0" ], "changes": [] }, "desc": "The total number of unacknowledged bytes this QUIC endpoint has transmitted\nto the connected peer.
" }, { "textRaw": "`bytesReceived` Type: {number}", "type": "number", "name": "Type", "meta": { "added": [ "v15.0.0" ], "changes": [] }, "desc": "The total number of bytes received from the peer.
" }, { "textRaw": "`bytesSent` Type: {number}", "type": "number", "name": "Type", "meta": { "added": [ "v15.0.0" ], "changes": [] }, "desc": "The total number of bytes sent to the peer.
" }, { "textRaw": "`cipher` Type: {Object}", "type": "Object", "name": "Type", "meta": { "added": [ "v15.0.0" ], "changes": [] }, "options": [ { "textRaw": "`name` {string} The cipher algorithm name.", "name": "name", "type": "string", "desc": "The cipher algorithm name." }, { "textRaw": "`type` {string} The TLS version (currently always `'TLSv1.3'`).", "name": "type", "type": "string", "desc": "The TLS version (currently always `'TLSv1.3'`)." } ], "desc": "Information about the cipher algorithm selected for the session.
" }, { "textRaw": "`closeCode` Type: {Object}", "type": "Object", "name": "Type", "meta": { "added": [ "v15.0.0" ], "changes": [] }, "options": [ { "textRaw": "`code` {number} The error code reported when the `QuicSession` closed.", "name": "code", "type": "number", "desc": "The error code reported when the `QuicSession` closed." }, { "textRaw": "`family` {number} The type of error code reported (`0` indicates a QUIC protocol level error, `1` indicates a TLS error, `2` represents an application level error.)", "name": "family", "type": "number", "desc": "The type of error code reported (`0` indicates a QUIC protocol level error, `1` indicates a TLS error, `2` represents an application level error.)" } ], "desc": "Set to true
if the QuicSession
is in the process of a graceful shutdown.
Set to true
if the QuicSession
is in the process of a graceful shutdown.
Set to true
if the QuicSession
has been destroyed.
The length of time the QuicSession
was active.
TBD
" }, { "textRaw": "`quicsession.handshakeContinuationHistogram`", "name": "handshakeContinuationHistogram", "meta": { "added": [ "v15.0.0" ], "changes": [] }, "desc": "TBD
" }, { "textRaw": "`handshakeComplete` Type: {boolean}", "type": "boolean", "name": "Type", "meta": { "added": [ "v15.0.0" ], "changes": [] }, "desc": "Set to true
if the TLS handshake has completed.
Set to true
when the TLS handshake completion has been confirmed.
The length of time taken to complete the TLS handshake.
" }, { "textRaw": "`idleTimeout` Type: {boolean}", "type": "boolean", "name": "Type", "meta": { "added": [ "v15.0.0" ], "changes": [] }, "desc": "Set to true
if the QuicSession
was closed due to an idle timeout.
The number of key update operations that have occurred.
" }, { "textRaw": "`latestRTT` Type: {number}", "type": "number", "name": "Type", "meta": { "added": [ "v15.0.0" ], "changes": [] }, "desc": "The most recently recorded RTT for this QuicSession
.
The number of lost-packet retransmissions that have been performed on\nthis QuicSession
.
The total number of bytes the QuicSession
is currently allowed to\nsend to the connected peer.
The maximum number of in-flight bytes recorded for this QuicSession
.
The highest cumulative number of bidirectional and unidirectional streams\nthat can currently be opened. The values are set initially by configuration\nparameters when the QuicSession
is created, then updated over the lifespan\nof the QuicSession
as the connected peer allows new streams to be created.
The minimum RTT recorded so far for this QuicSession
.
The total number of QuicStreams
initiated by the connected peer.
If qlog
support is enabled for QuicSession
, the quicsession.qlog
property\nprovides a stream.Readable
that may be used to access the qlog
event\ndata according to the qlog standard. For client QuicSessions
, the\nquicsession.qlog
property will be undefined
until the 'qlog'
event\nis emitted.
An object containing the remote address information for the connected peer.
" }, { "textRaw": "`selfInitiatedStreamCount` Type: {number}", "type": "number", "name": "Type", "meta": { "added": [ "v15.0.0" ], "changes": [] }, "desc": "The total number of QuicStream
instances initiated by this QuicSession
.
The SNI servername requested for this session by the client.
" }, { "textRaw": "`smoothedRTT` Type: {number}", "type": "number", "name": "Type", "meta": { "added": [ "v15.0.0" ], "changes": [] }, "desc": "The modified RTT calculated for this QuicSession
.
The QuicSocket
the QuicSession
is associated with.
True if the QuicSession
was closed due to QUIC stateless reset.
The total number of unidirectional streams created on this QuicSession
.
On server QuicSession
instances, set to true
on completion of the TLS\nhandshake if early data is enabled. On client QuicSession
instances,\nset to true on handshake completion if early data is enabled and was\naccepted by the server.
Begins a graceful close of the QuicSession
. Existing QuicStream
instances\nwill be permitted to close naturally. New QuicStream
instances will not be\npermitted. Once all QuicStream
instances have closed, the QuicSession
\ninstance will be destroyed. Returns a Promise
that is resolved once the\nQuicSession
instance is destroyed.
Destroys the QuicSession
immediately causing the close
event to be emitted.\nIf error
is not undefined
, the error
event will be emitted immediately\nbefore the close
event.
Any QuicStream
instances that are still opened will be abruptly closed.
Returns an object representing the local certificate. The returned object has\nsome properties corresponding to the fields of the certificate.
\nIf there is no local certificate, or if the QuicSession
has been destroyed,\nan empty object will be returned.
Returns an object representing the peer's certificate. If the peer does not\nprovide a certificate, or if the QuicSession
has been destroyed, an empty\nobject will be returned.
If the full certificate chain was requested (details
equals true
), each\ncertificate will include an issuerCertificate
property containing an object\nrepresenting the issuer's certificate.
Returns a Promise
that resolves a new QuicStream
.
The Promise
will be rejected if the QuicSession
has been destroyed, is in\nthe process of a graceful shutdown, or the QuicSession
is otherwise blocked\nfrom opening a new stream.
The ping()
method will trigger the underlying QUIC connection to serialize\nany frames currently pending in the outbound queue if it is able to do so.\nThis has the effect of keeping the connection with the peer active and resets\nthe idle and retransmission timers. The ping()
method is a best-effort\nthat ignores any errors that may occur during the serialization and send\noperations. There is no return value and there is no way to monitor the status\nof the ping()
operation.
Initiates QuicSession key update.
\nAn error will be thrown if called before quicsession.handshakeConfirmed
\nis equal to true
.
The QuicClientSession
class implements the client side of a QUIC connection.\nInstances are created using the quicsocket.connect()
method.
The 'sessionTicket'
event is emitted when a new TLS session ticket has been\ngenerated for the current QuicClientSession
. The callback is invoked with\ntwo arguments:
sessionTicket
<Buffer> The serialized session ticket.remoteTransportParams
<Buffer> The serialized remote transport parameters\nprovided by the QUIC server.The sessionTicket
and remoteTransportParams
are useful when creating a new\nQuicClientSession
to more quickly resume an existing session.
The 'sessionTicket'
event may be emitted multiple times.
The 'qlog'
event is emitted when the QuicClientSession
is ready to begin\nproviding qlog
event data. The callback is invoked with a single argument:
qlog
<stream.Readable> A stream.Readable
that is also available using\nthe quicsession.qlog
property.The 'usePreferredAddress'
event is emitted when the client QuicSession
\nis updated to use the server-advertised preferred address. The callback is\ninvoked with a single address
argument:
address
<Object>\n\nThis event is purely informational and will be emitted only when\npreferredAddressPolicy
is set to 'accept'
.
The 'usePreferredAddress'
event will not be emitted more than once.
An object representing the type, name, and size of parameter of an ephemeral\nkey exchange in Perfect Forward Secrecy on a client connection. It is an\nempty object when the key exchange is not ephemeral. The supported types are\n'DH'
and 'ECDH'
. The name
property is available only when type is\n'ECDH'
.
For example: { type: 'ECDH', name: 'prime256v1', size: 256 }
.
Migrates the QuicClientSession
to the given QuicSocket
instance. If the new\nQuicSocket
has not yet been bound to a local UDP port, it will be bound prior\nto attempting the migration.
The QuicServerSession
class implements the server side of a QUIC connection.\nInstances are created internally and are emitted using the QuicSocket
\n'session'
event.
New instances of QuicSocket
are created using the net.createQuicSocket()
\nmethod, and can be used as both a client and a server.
Emitted when the server busy state has been toggled using\nquicSocket.serverBusy = true | false
. The callback is invoked with no\narguments. Use the quicsocket.serverBusy
property to determine the\ncurrent status. This event is strictly informational.
const { createQuicSocket } = require('net');\n\nconst socket = createQuicSocket();\n\nsocket.on('busy', () => {\n if (socket.serverBusy)\n console.log('Server is busy');\n else\n console.log('Server is not busy');\n});\n\nsocket.serverBusy = true;\nsocket.serverBusy = false;\n
\nThis 'busy'
event may be emitted multiple times.
Emitted after the QuicSocket
has been destroyed and is no longer usable.
The 'close'
event will only ever be emitted once.
Emitted after a QuicEndpoint
associated with the QuicSocket
closes and\nhas been destroyed. The handler will be invoked with two arguments:
endpoint
<QuicEndpoint> The QuicEndpoint
that has been destroyed.error
<Error> An Error
object if the QuicEndpoint
was destroyed because\nof an error.When all of the QuicEndpoint
instances associated with a QuicSocket
have\nclosed, the QuicEndpoint
will also automatically close.
Emitted before the 'close'
event if the QuicSocket
was destroyed with an\nerror
.
The 'error'
event will only ever be emitted once.
Emitted after quicsocket.listen()
is called and the QuicSocket
has started\nlistening for incoming QuicServerSession
s. The callback is invoked with\nno arguments.
The 'listening'
event will only ever be emitted once.
Emitted once the QuicSocket
has been bound to a local UDP port.
The 'ready'
event will only ever be emitted once.
Emitted when a new QuicServerSession
has been created. The callback is\ninvoked with a single argument providing the newly created QuicServerSession
\nobject.
const { createQuicSocket } = require('net');\n\nconst options = getOptionsSomehow();\nconst server = createQuicSocket({ server: options });\n\nserver.on('session', (session) => {\n // Attach session event listeners.\n});\n\nserver.listen();\n
\nThe 'session'
event will be emitted multiple times.
The 'session'
event handler can be an async function.
If the 'session'
event handler throws an error, or if it returns a Promise
\nthat is rejected, the error will be handled by destroying the QuicServerSession
\nautomatically and emitting a 'sessionError'
event on the QuicSocket
.
Emitted when an error occurs processing an event related to a specific\nQuicSession
instance. The callback is invoked with two arguments:
error
<Error> The error that was either thrown or rejected.session
<QuicSession> The QuicSession
instance that was destroyed.The QuicSession
instance will have been destroyed by the time the\n'sessionError'
event is emitted.
const { createQuicSocket } = require('net');\n\nconst options = getOptionsSomehow();\nconst server = createQuicSocket({ server: options });\nserver.listen();\n\nserver.on('session', (session) => {\n throw new Error('boom');\n});\n\nserver.on('sessionError', (error, session) => {\n console.log('error:', error.message);\n});\n
"
}
],
"methods": [
{
"textRaw": "`quicsocket.addEndpoint(options)`",
"type": "method",
"name": "addEndpoint",
"meta": {
"added": [
"v15.0.0"
],
"changes": []
},
"signatures": [
{
"return": {
"textRaw": "Returns: {QuicEndpoint}",
"name": "return",
"type": "QuicEndpoint"
},
"params": [
{
"textRaw": "`options`: {Object} An object describing the local address to bind to.",
"name": "options",
"type": "Object",
"desc": "An object describing the local address to bind to.",
"options": [
{
"textRaw": "`address` {string} The local address to bind to. This may be an IPv4 or IPv6 address or a host name. If a host name is given, it will be resolved to an IP address.",
"name": "address",
"type": "string",
"desc": "The local address to bind to. This may be an IPv4 or IPv6 address or a host name. If a host name is given, it will be resolved to an IP address."
},
{
"textRaw": "`port` {number} The local port to bind to.",
"name": "port",
"type": "number",
"desc": "The local port to bind to."
},
{
"textRaw": "`type` {string} Can be one of `'udp4'`, `'upd6'`, or `'udp6-only'` to use IPv4, IPv6, or IPv6 with dual-stack mode disabled. **Default**: `'udp4'`.",
"name": "type",
"type": "string",
"desc": "Can be one of `'udp4'`, `'upd6'`, or `'udp6-only'` to use IPv4, IPv6, or IPv6 with dual-stack mode disabled. **Default**: `'udp4'`."
},
{
"textRaw": "`lookup` {Function} A [custom DNS lookup function][]. **Default**: undefined.",
"name": "lookup",
"type": "Function",
"desc": "A [custom DNS lookup function][]. **Default**: undefined."
}
]
}
]
}
],
"desc": "Creates and adds a new QuicEndpoint
to the QuicSocket
instance. An\nerror will be thrown if quicsocket.addEndpoint()
is called either after\nthe QuicSocket
has already started binding to the local ports, or after\nthe QuicSocket
has been destroyed.
Gracefully closes the QuicSocket
. Existing QuicSession
instances will be\npermitted to close naturally. New QuicClientSession
and QuicServerSession
\ninstances will not be allowed. The returns Promise
will be resolved once\nthe QuicSocket
is destroyed.
Returns a Promise
that resolves a new QuicClientSession
.
Destroys the QuicSocket
then emits the 'close'
event when done. The 'error'
\nevent will be emitted after 'close'
if the error
is not undefined
.
Listen for new peer-initiated sessions. Returns a Promise
that is resolved\nonce the QuicSocket
is actively listening.
The quicsocket.setDiagnosticPacketLoss()
method is a diagnostic only tool\nthat can be used to simulate packet loss conditions for this QuicSocket
\nby artificially dropping received or transmitted packets.
This method is not to be used in production applications.
" } ], "properties": [ { "textRaw": "`blockList` Type: {net.BlockList}", "type": "net.BlockList", "name": "Type", "meta": { "added": [ "v15.0.0" ], "changes": [] }, "desc": "A <net.BlockList> instance used to define rules for remote IPv4 or IPv6\naddresses that this QuicSocket
is not permitted to interact with. The\nrules can be specified as either specific individual addresses, ranges\nof addresses, or CIDR subnet ranges.
When listening as a server, if a packet is received from a blocked address,\nthe packet will be ignored.
\nWhen connecting as a client, if the remote IP address is blocked, the\nconnection attempt will be rejected.
" }, { "textRaw": "`bound` Type: {boolean}", "type": "boolean", "name": "Type", "meta": { "added": [ "v15.0.0" ], "changes": [] }, "desc": "Will be true
if the QuicSocket
has been successfully bound to a local UDP\nport. Initially the value is false
.
QuicSocket
instances are not bound to a local UDP port until the first time\neither quicsocket.listen()
or quicsocket.connect()
is called. The 'ready'
\nevent will be emitted once the QuicSocket
has been bound and the value of\nquicsocket.bound
will become true
.
Read-only.
" }, { "textRaw": "`boundDuration` Type: {number}", "type": "number", "name": "Type", "meta": { "added": [ "v15.0.0" ], "changes": [] }, "desc": "The length of time this QuicSocket
has been bound to a local port.
Read-only.
" }, { "textRaw": "`bytesReceived` Type: {number}", "type": "number", "name": "Type", "meta": { "added": [ "v15.0.0" ], "changes": [] }, "desc": "The number of bytes received by this QuicSocket
.
Read-only.
" }, { "textRaw": "`bytesSent` Type: {number}", "type": "number", "name": "Type", "meta": { "added": [ "v15.0.0" ], "changes": [] }, "desc": "The number of bytes sent by this QuicSocket
.
Read-only.
" }, { "textRaw": "`clientSessions` Type: {number}", "type": "number", "name": "Type", "meta": { "added": [ "v15.0.0" ], "changes": [] }, "desc": "The number of client QuicSession
instances that have been associated\nwith this QuicSocket
.
Read-only.
" }, { "textRaw": "`destroyed` Type: {boolean}", "type": "boolean", "name": "Type", "meta": { "added": [ "v15.0.0" ], "changes": [] }, "desc": "Will be true
if the QuicSocket
has been destroyed.
Read-only.
" }, { "textRaw": "`duration` Type: {number}", "type": "number", "name": "Type", "meta": { "added": [ "v15.0.0" ], "changes": [] }, "desc": "The length of time this QuicSocket
has been active,
Read-only.
" }, { "textRaw": "`endpoints` Type: {QuicEndpoint[]}", "type": "QuicEndpoint[]", "name": "Type", "meta": { "added": [ "v15.0.0" ], "changes": [] }, "desc": "An array of QuicEndpoint
instances associated with the QuicSocket
.
Read-only.
" }, { "textRaw": "`listenDuration` Type: {number}", "type": "number", "name": "Type", "meta": { "added": [ "v15.0.0" ], "changes": [] }, "desc": "The length of time this QuicSocket
has been listening for connections.
Read-only
" }, { "textRaw": "`listening` Type: {boolean}", "type": "boolean", "name": "Type", "meta": { "added": [ "v15.0.0" ], "changes": [] }, "desc": "Set to true
if the QuicSocket
is listening for new connections.
Read-only.
" }, { "textRaw": "`packetsIgnored` Type: {number}", "type": "number", "name": "Type", "meta": { "added": [ "v15.0.0" ], "changes": [] }, "desc": "The number of packets received by this QuicSocket
that have been ignored.
Read-only.
" }, { "textRaw": "`packetsReceived` Type: {number}", "type": "number", "name": "Type", "meta": { "added": [ "v15.0.0" ], "changes": [] }, "desc": "The number of packets successfully received by this QuicSocket
.
Read-only
" }, { "textRaw": "`packetsSent` Type: {number}", "type": "number", "name": "Type", "meta": { "added": [ "v15.0.0" ], "changes": [] }, "desc": "The number of packets sent by this QuicSocket
.
Read-only
" }, { "textRaw": "`pending` Type: {boolean}", "type": "boolean", "name": "Type", "meta": { "added": [ "v15.0.0" ], "changes": [] }, "desc": "Set to true
if the socket is not yet bound to the local UDP port.
Read-only.
" }, { "textRaw": "`serverBusy` Type: {boolean} When `true`, the `QuicSocket` will reject new connections.", "type": "boolean", "name": "Type", "meta": { "added": [ "v15.0.0" ], "changes": [] }, "desc": "Setting quicsocket.serverBusy
to true
will tell the QuicSocket
\nto reject all new incoming connection requests using the SERVER_BUSY
QUIC\nerror code. To begin receiving connections again, disable busy mode by setting\nquicsocket.serverBusy = false
.
The number of QuicSession
instances rejected due to server busy status.
Read-only.
" }, { "textRaw": "`serverSessions` Type: {number}", "type": "number", "name": "Type", "meta": { "added": [ "v15.0.0" ], "changes": [] }, "desc": "The number of server QuicSession
instances that have been associated with\nthis QuicSocket
.
Read-only.
" }, { "textRaw": "`statelessReset` Type: {boolean} `true` if stateless reset processing is enabled; `false` if disabled.", "type": "boolean", "name": "Type", "meta": { "added": [ "v15.0.0" ], "changes": [] }, "desc": "By default, a listening QuicSocket
will generate stateless reset tokens when\nappropriate. The disableStatelessReset
option may be set when the\nQuicSocket
is created to disable generation of stateless resets. The\nquicsocket.statelessReset
property allows stateless reset to be turned on and\noff dynamically through the lifetime of the QuicSocket
.
The number of stateless resets that have been sent.
\nRead-only.
" } ], "modules": [ { "textRaw": "`quicsocket.unref();`", "name": "`quicsocket.unref();`", "meta": { "added": [ "v15.0.0" ], "changes": [] }, "type": "module", "displayName": "`quicsocket.unref();`" } ] }, { "textRaw": "Class: `QuicStream extends stream.Duplex`", "type": "class", "name": "QuicStream", "meta": { "added": [ "v15.0.0" ], "changes": [] }, "desc": "Emitted when the QuicStream
has been prevented from sending queued data for\nthe QuicStream
due to congestion control.
Emitted when the QuicStream
has is completely closed and the underlying\nresources have been freed.
Emitted when the QuicStream
has received a block of informational headers.
Support for headers depends entirely on the QUIC Application used as identified\nby the alpn
configuration option. In QUIC Applications that support headers,\ninformational header blocks typically come before initial headers.
The event handler is invoked with a single argument representing the block of\nHeaders as an object.
\nstream('informationalHeaders', (headers) => {\n // Use headers\n});\n
"
},
{
"textRaw": "Event: `'initialHeaders'`",
"type": "event",
"name": "initialHeaders",
"meta": {
"added": [
"v15.0.0"
],
"changes": []
},
"params": [],
"desc": "Emitted when the QuicStream
has received a block of initial headers.
Support for headers depends entirely on the QUIC Application used as identified\nby the alpn
configuration option. HTTP/3, for instance, supports two kinds of\ninitial headers: request headers for HTTP request messages and response headers\nfor HTTP response messages. For HTTP/3 QUIC streams, request and response\nheaders are each emitted using the 'initialHeaders'
event.
The event handler is invoked with a single argument representing the block of\nHeaders as an object.
\nstream('initialHeaders', (headers) => {\n // Use headers\n});\n
"
},
{
"textRaw": "Event: `'trailingHeaders'`",
"type": "event",
"name": "trailingHeaders",
"meta": {
"added": [
"v15.0.0"
],
"changes": []
},
"params": [],
"desc": "Emitted when the QuicStream
has received a block of trailing headers.
Support for headers depends entirely on the QUIC Application used as identified\nby the alpn
configuration option. Trailing headers typically follow any data\ntransmitted on the QuicStream
, and therefore typically emit sometime after the\nlast 'data'
event but before the 'close'
event. The precise timing may\nvary from one QUIC application to another.
The event handler is invoked with a single argument representing the block of\nHeaders as an object.
\nstream('trailingHeaders', (headers) => {\n // Use headers\n});\n
"
},
{
"textRaw": "Event: `'readable'`",
"type": "event",
"name": "readable",
"meta": {
"added": [
"v15.0.0"
],
"changes": []
},
"params": []
}
],
"properties": [
{
"textRaw": "`quicstream.bidirectional`",
"name": "bidirectional",
"desc": "\nWhen true
, the QuicStream
is bidirectional. Both the readable and\nwritable sides of the QuicStream
Duplex
are open.
Read-only.
" }, { "textRaw": "`bytesReceived` Type: {number}", "type": "number", "name": "Type", "meta": { "added": [ "v15.0.0" ], "changes": [] }, "desc": "The total number of bytes received for this QuicStream
.
Read-only.
" }, { "textRaw": "`bytesSent` Type: {number}", "type": "number", "name": "Type", "meta": { "added": [ "v15.0.0" ], "changes": [] }, "desc": "The total number of bytes sent by this QuicStream
.
Read-only.
" }, { "textRaw": "`clientInitiated` Type: {boolean}", "type": "boolean", "name": "Type", "meta": { "added": [ "v15.0.0" ], "changes": [] }, "desc": "Will be true
if the QuicStream
was initiated by a QuicClientSession
\ninstance.
Read-only.
" }, { "textRaw": "`quicstream.dataAckHistogram`", "name": "dataAckHistogram", "meta": { "added": [ "v15.0.0" ], "changes": [] }, "desc": "TBD
" }, { "textRaw": "`quicstream.dataRateHistogram`", "name": "dataRateHistogram", "meta": { "added": [ "v15.0.0" ], "changes": [] }, "desc": "TBD
" }, { "textRaw": "`quicstream.dataSizeHistogram`", "name": "dataSizeHistogram", "meta": { "added": [ "v15.0.0" ], "changes": [] }, "desc": "TBD
" }, { "textRaw": "`duration` Type: {number}", "type": "number", "name": "Type", "meta": { "added": [ "v15.0.0" ], "changes": [] }, "desc": "The length of time the QuicStream
has been active.
Read-only.
" }, { "textRaw": "`finalSize` Type: {number}", "type": "number", "name": "Type", "meta": { "added": [ "v15.0.0" ], "changes": [] }, "desc": "The total number of bytes successfully received by the QuicStream
.
Read-only.
" }, { "textRaw": "`id` Type: {number}", "type": "number", "name": "Type", "meta": { "added": [ "v15.0.0" ], "changes": [] }, "desc": "The numeric identifier of the QuicStream
.
Read-only.
" }, { "textRaw": "`maxAcknowledgedOffset` Type: {number}", "type": "number", "name": "Type", "meta": { "added": [ "v15.0.0" ], "changes": [] }, "desc": "The highest acknowledged data offset received for this QuicStream
.
Read-only.
" }, { "textRaw": "`maxExtendedOffset` Type: {number}", "type": "number", "name": "Type", "meta": { "added": [ "v15.0.0" ], "changes": [] }, "desc": "The maximum extended data offset that has been reported to the connected peer.
\nRead-only.
" }, { "textRaw": "`maxReceivedOffset` Type: {number}", "type": "number", "name": "Type", "meta": { "added": [ "v15.0.0" ], "changes": [] }, "desc": "The maximum received offset for this QuicStream
.
Read-only.
" }, { "textRaw": "`serverInitiated` Type: {boolean}", "type": "boolean", "name": "Type", "meta": { "added": [ "v15.0.0" ], "changes": [] }, "desc": "Will be true
if the QuicStream
was initiated by a QuicServerSession
\ninstance.
Read-only.
" }, { "textRaw": "`session` Type: {QuicSession}", "type": "QuicSession", "name": "Type", "meta": { "added": [ "v15.0.0" ], "changes": [] }, "desc": "The QuicServerSession
or QuicClientSession
to which the\nQuicStream
belongs.
Read-only.
" }, { "textRaw": "`unidirectional` Type: {boolean}", "type": "boolean", "name": "Type", "meta": { "added": [ "v15.0.0" ], "changes": [] }, "desc": "Will be true
if the QuicStream
is unidirectional. Whether the QuicStream
\nwill be readable or writable depends on whether the quicstream.session
is\na QuicClientSession
or QuicServerSession
, and whether the QuicStream
\nwas initiated locally or remotely.
quicstream.session | \nquicstream.serverInitiated | \nReadable | \nWritable | \n
---|---|---|---|
QuicClientSession | \ntrue | \nY | \nN | \n
QuicServerSession | \ntrue | \nN | \nY | \n
QuicClientSession | \nfalse | \nN | \nY | \n
QuicServerSession | \nfalse | \nY | \nN | \n
quicstream.session | \nquicstream.clientInitiated | \nReadable | \nWritable | \n
---|---|---|---|
QuicClientSession | \ntrue | \nN | \nY | \n
QuicServerSession | \ntrue | \nY | \nN | \n
QuicClientSession | \nfalse | \nY | \nN | \n
QuicServerSession | \nfalse | \nN | \nY | \n
Read-only.
" } ], "methods": [ { "textRaw": "`quicstream.close()`", "type": "method", "name": "close", "meta": { "added": [ "v15.0.0" ], "changes": [] }, "signatures": [ { "return": { "textRaw": "Returns: {Promise}", "name": "return", "type": "Promise" }, "params": [] } ], "desc": "Closes the QuicStream
by ending both sides of the QuicStream
Duplex
.\nReturns a Promise
that is resolved once the QuicStream
has been destroyed.
If the selected QUIC application protocol supports push streams, then the\npushStream()
method will initiate a new push promise and create a new\nunidirectional QuicStream
object used to fulfill that push.
Currently only HTTP/3 supports the use of pushStream()
.
If the selected QUIC application protocol does not support push streams, an\nerror will be thrown.
" }, { "textRaw": "`quicstream.sendFD(fd[, options])`", "type": "method", "name": "sendFD", "meta": { "added": [ "v15.0.0" ], "changes": [] }, "signatures": [ { "params": [ { "textRaw": "`fd` {number|FileHandle} A readable file descriptor.", "name": "fd", "type": "number|FileHandle", "desc": "A readable file descriptor." }, { "textRaw": "`options` {Object}", "name": "options", "type": "Object", "options": [ { "textRaw": "`offset` {number} The offset position at which to begin reading. Default: `-1`.", "name": "offset", "type": "number", "desc": "The offset position at which to begin reading. Default: `-1`." }, { "textRaw": "`length` {number} The amount of data from the fd to send. Default: `-1`.", "name": "length", "type": "number", "desc": "The amount of data from the fd to send. Default: `-1`." } ] } ] } ], "desc": "Instead of using a QuicStream
as a writable stream, send data from a given\nfile descriptor.
If offset
is set to a non-negative number, reading starts from that position\nand the file offset will not be advanced.\nIf length
is set to a non-negative number, it gives the maximum number of\nbytes that are read from the file.
The file descriptor or FileHandle
is not closed when the stream is closed,\nso it will need to be closed manually once it is no longer needed.\nUsing the same file descriptor concurrently for multiple streams\nis not supported and may result in data loss. Re-using a file descriptor\nafter a stream has finished is supported.
Instead of using a QuicStream
as a writable stream, send data from a given\nfile path.
The options.onError
callback will be called if the file could not be opened.\nIf offset
is set to a non-negative number, reading starts from that position.\nIf length
is set to a non-negative number, it gives the maximum number of\nbytes that are read from the file.
TBD
" }, { "textRaw": "`quicstream.submitInitialHeaders(headers)`", "type": "method", "name": "submitInitialHeaders", "meta": { "added": [ "v15.0.0" ], "changes": [] }, "signatures": [ { "params": [ { "textRaw": "`headers` {Object}", "name": "headers", "type": "Object" } ] } ], "desc": "TBD
" }, { "textRaw": "`quicstream.submitTrailingHeaders(headers)`", "type": "method", "name": "submitTrailingHeaders", "meta": { "added": [ "v15.0.0" ], "changes": [] }, "signatures": [ { "params": [ { "textRaw": "`headers` {Object}", "name": "headers", "type": "Object" } ] } ], "desc": "TBD
" } ] } ], "type": "module", "displayName": "QUIC JavaScript API" }, { "textRaw": "Additional notes", "name": "additional_notes", "modules": [ { "textRaw": "Custom DNS lookup functions", "name": "custom_dns_lookup_functions", "desc": "By default, the QUIC implementation uses the dns
module's\npromisified version of lookup()
to resolve domains names\ninto IP addresses. For most typical use cases, this will be\nsufficient. However, it is possible to pass a custom lookup
\nfunction as an option in several places throughout the QUIC API:
net.createQuicSocket()
quicsocket.addEndpoint()
quicsocket.connect()
quicsocket.listen()
The custom lookup
function must return a Promise
that is\nresolved once the lookup is complete. It will be invoked with\ntwo arguments:
address
<string> | <undefined> The host name to resolve, or\nundefined
if no host name was provided.family
<number> One of 4
or 6
, identifying either\nIPv4 or IPv6.async function myCustomLookup(address, type) {\n // TODO(@jasnell): Make this example more useful\n return resolveTheAddressSomehow(address, type);\n}\n
",
"type": "module",
"displayName": "Custom DNS lookup functions"
},
{
"textRaw": "Online Certificate Status Protocol (OCSP)",
"name": "online_certificate_status_protocol_(ocsp)",
"desc": "The QUIC implementation supports use of OCSP during the TLS 1.3 handshake\nof a new QUIC session.
", "modules": [ { "textRaw": "Requests", "name": "requests", "desc": "A QuicServerSession
can receive and process OCSP requests by setting the\nocspHandler
option in the quicsocket.listen()
function. The value of\nthe ocspHandler
is an async function that must return an object with the\nOCSP response and, optionally, a new <tls.SecureContext> to use during the\nhandshake.
The handler function will be invoked with two arguments:
\ntype
: <string> Will always be request
for QuicServerSession
.options
: <Object>\nservername
<string> The SNI server name.context
<tls.SecureContext> The SecureContext
currently used.async function ocspServerHandler(type, { servername, context }) {\n // Process the request...\n return { data: Buffer.from('The OCSP response') };\n}\n\nsock.listen({ ocspHandler: ocspServerHandler });\n
",
"type": "module",
"displayName": "Requests"
},
{
"textRaw": "Responses",
"name": "responses",
"desc": "A QuicClientSession
can receive and process OCSP responses by setting the\nocspHandler
option in the quicsocket.connect()
function. The value of\nthe ocspHandler
is an async function with no expected return value.
The handler function will be invoked with two arguments:
\ntype
: <string> Will always be response
for QuicClientSession
.options
: <Object>\ndata
: <Buffer> The OCSP response provided by the serverasync function ocspClientHandler(type, { data }) {\n console.log(data.toString());\n}\n\nsock.connect({ ocspHandler: ocspClientHandler });\n
",
"type": "module",
"displayName": "Responses"
}
],
"type": "module",
"displayName": "Online Certificate Status Protocol (OCSP)"
},
{
"textRaw": "Handling client hello",
"name": "handling_client_hello",
"desc": "When quicsocket.listen()
is called, a <tls.SecureContext> is created and used\nby default for all new QuicServerSession
instances. There are times, however,\nwhen the <tls.SecureContext> to be used for a QuicSession
can only be\ndetermined once the client initiates a connection. This is accomplished using\nthe clientHelloHandler
option when calling quicsocket.listen()
.
The value of clientHelloHandler
is an async function that is called at the\nstart of a new QuicServerSession
. It is invoked with three arguments:
alpn
<string> The ALPN protocol identifier specified by the client.servername
<string> The SNI server name specified by the client.ciphers
<string[]> The array of TLS 1.3 ciphers specified by the client.The clientHelloHandler
can return a new <tls.SecureContext> object that will\nbe used to continue the TLS handshake. If the function returns undefined
, the\ndefault <tls.SecureContext> will be used. Returning any other value will cause\nan error to be thrown that will destroy the QuicServerSession
instance.
const server = createQuicSocket();\n\nserver.listen({\n async clientHelloHandler(alpn, servername, ciphers) {\n console.log(alpn);\n console.log(servername);\n console.log(ciphers);\n }\n});\n
",
"type": "module",
"displayName": "Handling client hello"
}
],
"type": "module",
"displayName": "Additional notes"
}
],
"type": "module",
"displayName": "QUIC"
}
]
}