diff --git a/doc/api/quic.md b/doc/api/quic.md index 3667a05b394956..6143d3995cfaa8 100644 --- a/doc/api/quic.md +++ b/doc/api/quic.md @@ -1319,10 +1319,7 @@ added: REPLACEME --> New instances of `QuicSocket` are created using the `net.createQuicSocket()` -method. - -Once created, a `QuicSocket` can be configured to work as both a client and a -server. +method, and can be used as both a client and a server. #### Event: `'busy'` Emitted when the server busy state has been toggled using -`quicSocket.setServerBusy()`. The callback is invoked with a single -boolean argument indicating `true` if busy status is enabled, -`false` otherwise. This event is strictly informational. +`quicSocket.serverBusy = true | false`. The callback is invoked with no +arguments. Use the `quicsocket.serverBusy` property to determine the +current status. This event is strictly informational. ```js const { createQuicSocket } = require('net'); const socket = createQuicSocket(); -socket.on('busy', (busy) => { - if (busy) +socket.on('busy', () => { + if (socket.serverBusy) console.log('Server is busy'); else console.log('Server is not busy'); }); -socket.setServerBusy(true); -socket.setServerBusy(false); +socket.serverBusy = true; +socket.serverBusy = false; ``` This `'busy'` event may be emitted multiple times. @@ -1371,6 +1368,17 @@ Emitted before the `'close'` event if the `QuicSocket` was destroyed with an The `'error'` event will not be emitted multiple times. +#### Event: `'listening'` + + +Emitted after `quicsocket.listen()` is called and the `QuicSocket` has started +listening for incoming `QuicServerSession`s. The callback is invoked with +no arguments. + +The `'listening'` event will not be emitted multiple times. + #### Event: `'ready'` -Emitted when a new `QuicServerSession` has been created. +Emitted when a new `QuicServerSession` has been created. The callback is +invoked with a single argument providing the newly created `QuicServerSession` +object. + +```js +const { createQuicSocket } = require('net'); + +const options = getOptionsSomehow(); +const server = createQuicSocket({ server: options }); +server.listen(); + +server.on('session', (session) => { + // Attach session event listeners. +}); +``` The `'session'` event will be emitted multiple times. +The `'session'` event handler *may* be an async function. + +If the `'session'` event handler throws an error, or if it returns a `Promise` +that is rejected, the error will be handled by destroying the `QuicServerSession` +automatically and emitting a `'sessionError'` event on the `QuicSocket`. + +#### Event: `'sessionError'` + + +Emitted when an error occurs processing an event related to a specific +`QuicSession` 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 +`'sessionError'` event is emitted. + +```js +const { createQuicSocket } = require('net'); + +const options = getOptionsSomehow(); +const server = createQuicSocket({ server: options }); +server.listen(); + +server.on('session', (session) => { + throw new Error('boom'); +}); + +server.on('sessionError', (error, session) => { + console.log('error:', error.message); +}); +``` + #### quicsocket.addEndpoint(options) -* Type: {bigint} +* Type: {number} + +The length of time this `QuicSocket` has been bound to a local port. -A `BigInt` representing the length of time this `QuicSocket` has been bound -to a local port. +Read-only. #### quicsocket.bytesReceived -* Type: {bigint} +* Type: {number} + +The number of bytes received by this `QuicSocket`. -A `BigInt` representing the number of bytes received by this `QuicSocket`. +Read-only. #### quicsocket.bytesSent -* Type: {bigint} +* Type: {number} -A `BigInt` representing the number of bytes sent by this `QuicSocket`. +The number of bytes sent by this `QuicSocket`. + +Read-only. #### quicsocket.clientSessions -* Type: {bigint} +* Type: {number} -A `BigInt` representing the number of client `QuicSession` instances that -have been associated with this `QuicSocket`. +The number of client `QuicSession` instances that have been associated +with this `QuicSocket`. + +Read-only. #### quicsocket.close(\[callback\]) -* Type: {bigint} +* Type: {number} -A `BigInt` representing the length of time this `QuicSocket` has been active, +The length of time this `QuicSocket` has been active, + +Read-only. #### quicsocket.endpoints -* Type: {bigint} +* Type: {number} -A `BigInt` representing the length of time this `QuicSocket` has been listening -for connections. +The length of time this `QuicSocket` has been listening for connections. + +Read-only #### quicsocket.listening -* Type: {bigint} +* Type: {number} + +The number of packets received by this `QuicSocket` that have been ignored. -A `BigInt` representing the number of packets received by this `QuicSocket` that -have been ignored. +Read-only. #### quicsocket.packetsReceived -* Type: {bigint} +* Type: {number} + +The number of packets successfully received by this `QuicSocket`. -A `BigInt` representing the number of packets successfully received by this -`QuicSocket`. +Read-only #### quicsocket.packetsSent -* Type: {bigint} +* Type: {number} + +The number of packets sent by this `QuicSocket`. -A `BigInt` representing the number of packets sent by this `QuicSocket`. +Read-only #### quicsocket.pending +#### quicsocket.serverBusy + + +* Type: {boolean} When `true`, the `QuicSocket` will reject new connections. + +Setting `quicsocket.serverBusy` to `true` will tell the `QuicSocket` +to reject all new incoming connection requests using the `SERVER_BUSY` QUIC +error code. To begin receiving connections again, disable busy mode by setting +`quicsocket.serverBusy = false`. + #### quicsocket.serverBusyCount -* Type: {bigint} +* Type: {number} + +The number of `QuicSession` instances rejected due to server busy status. -A `BigInt` representing the number of `QuicSession` instances rejected -due to server busy status. +Read-only. #### quicsocket.serverSessions -* Type: {bigint} +* Type: {number} + +The number of server `QuicSession` instances that have been associated with +this `QuicSocket`. -A `BigInt` representing the number of server `QuicSession` instances that -have been associated with this `QuicSocket`. +Read-only. #### quicsocket.setDiagnosticPacketLoss(options) - -* `on` {boolean} When `true`, the `QuicSocket` will reject new connections. - **Defaults**: `true`. - -Calling `setServerBusy()` or `setServerBusy(true)` will tell the `QuicSocket` -to reject all new incoming connection requests using the `SERVER_BUSY` QUIC -error code. To begin receiving connections again, disable busy mode by calling -`setServerBusy(false)`. - #### quicsocket.statelessResetCount -* Type: {bigint} +* Type: {number} + +The number of stateless resets that have been sent. -A `BigInt` that represents the number of stateless resets that have been sent. +Read-only. #### quicsocket.toggleStatelessReset()