diff --git a/doc/api/quic.md b/doc/api/quic.md index dee7f65f55cd49..318f48cc62094e 100644 --- a/doc/api/quic.md +++ b/doc/api/quic.md @@ -25,11 +25,6 @@ const { createQuicSocket } = require('net'); // Create the QUIC UDP IPv4 socket bound to local IP port 1234 const socket = createQuicSocket({ endpoint: { port: 1234 } }); -// Tell the socket to operate as a server using the given -// key and certificate to secure new connections, using -// the fictional 'hello' application protocol. -socket.listen({ key, cert, alpn: 'hello' }); - socket.on('session', (session) => { // A new server side session has been created! @@ -53,9 +48,14 @@ socket.on('session', (session) => { }); }); -socket.on('listening', () => { - // The socket is listening for sessions! -}); +// Tell the socket to operate as a server using the given +// key and certificate to secure new connections, using +// the fictional 'hello' application protocol. +(async function() { + await socket.listen({ key, cert, alpn: 'hello' }); + console.log('The socket is listening for sessions!'); +})(); + ``` ## QUIC Basics @@ -110,11 +110,13 @@ const { createQuicSocket } = require('net'); // Create a QuicSocket associated with localhost and port 1234 const socket = createQuicSocket({ endpoint: { port: 1234 } }); -const client = socket.connect({ - address: 'example.com', - port: 4567, - alpn: 'foo' -}); +(async function() { + const client = await socket.connect({ + address: 'example.com', + port: 4567, + alpn: 'foo' + }); +})(); ``` As soon as the `QuicClientSession` is created, the `address` provided in @@ -135,20 +137,22 @@ New instances of `QuicServerSession` are created internally by the using the `listen()` method. ```js +const { createQuicSocket } = require('net'); + const key = getTLSKeySomehow(); const cert = getTLSCertSomehow(); -socket.listen({ - key, - cert, - alpn: 'foo' -}); +const socket = createQuicSocket(); socket.on('session', (session) => { session.on('secure', () => { // The QuicServerSession can now be used for application data }); }); + +(async function() { + await socket.listen({ key, cert, alpn: 'foo' }); +})(); ``` As with client `QuicSession` instances, the `QuicServerSession` cannot be @@ -1275,20 +1279,17 @@ added: REPLACEME Set to `true` if the `QuicClientSession` is ready for use. False if the `QuicSocket` has not yet been bound. -#### quicclientsession.setSocket(socket, callback]) +#### quicclientsession.setSocket(socket]) * `socket` {QuicSocket} A `QuicSocket` instance to move this session to. -* `callback` {Function} A callback function that will be invoked once the - migration to the new `QuicSocket` is complete. +* Returns: {Promise} Migrates the `QuicClientSession` to the given `QuicSocket` instance. If the new `QuicSocket` has not yet been bound to a local UDP port, it will be bound prior -to attempting the migration. If the `QuicClientSession` is not yet ready to -migrate, the callback will be invoked with an `Error` using the code -`ERR_OPERATION_FAILED`. +to attempting the migration. ### Class: QuicServerSession extends QuicSession @@ -1877,13 +1882,10 @@ added: REPLACEME [OpenSSL Options][]. * `sessionIdContext` {string} Opaque identifier used by servers to ensure session state is not shared between applications. Unused by clients. +* Returns: {Promise} -* `callback` {Function} - -Listen for new peer-initiated sessions. - -If a `callback` is given, it is registered as a handler for the -`'session'` event. +Listen for new peer-initiated sessions. Returns a `Promise` that is resolved +once the `QuicSocket` is actively listening. #### quicsocket.listenDuration -* Type: {number} - -The number of stateless resets that have been sent. +* Type: {boolean} `true` if stateless reset processing is enabled; `false` + if disabled. -Read-only. +By default, a listening `QuicSocket` will generate stateless reset tokens when +appropriate. The `disableStatelessReset` option may be set when the +`QuicSocket` is created to disable generation of stateless resets. The +`quicsocket.statelessReset` property allows stateless reset to be turned on and +off dynamically through the lifetime of the `QuicSocket`. -#### quicsocket.toggleStatelessReset() +#### quicsocket.statelessResetCount -* Returns {boolean} `true` if stateless reset processing is enabled; `false` - if disabled. +* Type: {number} -By default, a listening `QuicSocket` will generate stateless reset tokens when -appropriate. The `disableStatelessReset` option may be set when the -`QuicSocket` is created to disable generation of stateless resets. The -`toggleStatelessReset()` function allows stateless reset to be turned on and -off dynamically through the lifetime of the `QuicSocket`. +The number of stateless resets that have been sent. + +Read-only. #### quicsocket.unref();