Skip to content

Commit 79c0e89

Browse files
committedJul 16, 2020
quic: implement QuicSocket Promise API, part 1
PR-URL: #34283 Reviewed-By: Anna Henningsen <anna@addaleax.net>
1 parent 53b12f0 commit 79c0e89

File tree

42 files changed

+1596
-2083
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

42 files changed

+1596
-2083
lines changed
 

‎doc/api/quic.md

+59-53
Original file line numberDiff line numberDiff line change
@@ -25,11 +25,6 @@ const { createQuicSocket } = require('net');
2525
// Create the QUIC UDP IPv4 socket bound to local IP port 1234
2626
const socket = createQuicSocket({ endpoint: { port: 1234 } });
2727

28-
// Tell the socket to operate as a server using the given
29-
// key and certificate to secure new connections, using
30-
// the fictional 'hello' application protocol.
31-
socket.listen({ key, cert, alpn: 'hello' });
32-
3328
socket.on('session', (session) => {
3429
// A new server side session has been created!
3530

@@ -53,9 +48,14 @@ socket.on('session', (session) => {
5348
});
5449
});
5550

56-
socket.on('listening', () => {
57-
// The socket is listening for sessions!
58-
});
51+
// Tell the socket to operate as a server using the given
52+
// key and certificate to secure new connections, using
53+
// the fictional 'hello' application protocol.
54+
(async function() {
55+
await socket.listen({ key, cert, alpn: 'hello' });
56+
console.log('The socket is listening for sessions!');
57+
})();
58+
5959
```
6060

6161
## QUIC Basics
@@ -110,11 +110,13 @@ const { createQuicSocket } = require('net');
110110
// Create a QuicSocket associated with localhost and port 1234
111111
const socket = createQuicSocket({ endpoint: { port: 1234 } });
112112

113-
const client = socket.connect({
114-
address: 'example.com',
115-
port: 4567,
116-
alpn: 'foo'
117-
});
113+
(async function() {
114+
const client = await socket.connect({
115+
address: 'example.com',
116+
port: 4567,
117+
alpn: 'foo'
118+
});
119+
})();
118120
```
119121

120122
As soon as the `QuicClientSession` is created, the `address` provided in
@@ -135,20 +137,22 @@ New instances of `QuicServerSession` are created internally by the
135137
using the `listen()` method.
136138

137139
```js
140+
const { createQuicSocket } = require('net');
141+
138142
const key = getTLSKeySomehow();
139143
const cert = getTLSCertSomehow();
140144

141-
socket.listen({
142-
key,
143-
cert,
144-
alpn: 'foo'
145-
});
145+
const socket = createQuicSocket();
146146

147147
socket.on('session', (session) => {
148148
session.on('secure', () => {
149149
// The QuicServerSession can now be used for application data
150150
});
151151
});
152+
153+
(async function() {
154+
await socket.listen({ key, cert, alpn: 'foo' });
155+
})();
152156
```
153157

154158
As with client `QuicSession` instances, the `QuicServerSession` cannot be
@@ -1275,20 +1279,17 @@ added: REPLACEME
12751279
Set to `true` if the `QuicClientSession` is ready for use. False if the
12761280
`QuicSocket` has not yet been bound.
12771281

1278-
#### quicclientsession.setSocket(socket, callback])
1282+
#### quicclientsession.setSocket(socket])
12791283
<!-- YAML
12801284
added: REPLACEME
12811285
-->
12821286

12831287
* `socket` {QuicSocket} A `QuicSocket` instance to move this session to.
1284-
* `callback` {Function} A callback function that will be invoked once the
1285-
migration to the new `QuicSocket` is complete.
1288+
* Returns: {Promise}
12861289

12871290
Migrates the `QuicClientSession` to the given `QuicSocket` instance. If the new
12881291
`QuicSocket` has not yet been bound to a local UDP port, it will be bound prior
1289-
to attempting the migration. If the `QuicClientSession` is not yet ready to
1290-
migrate, the callback will be invoked with an `Error` using the code
1291-
`ERR_OPERATION_FAILED`.
1292+
to attempting the migration.
12921293

12931294
### Class: QuicServerSession extends QuicSession
12941295
<!-- YAML
@@ -1394,7 +1395,7 @@ added: REPLACEME
13941395

13951396
Emitted after the `QuicSocket` has been destroyed and is no longer usable.
13961397

1397-
The `'close'` event will not be emitted multiple times.
1398+
The `'close'` event will only ever be emitted once.
13981399

13991400
#### Event: `'endpointClose'`
14001401
<!-- YAML
@@ -1419,7 +1420,7 @@ added: REPLACEME
14191420
Emitted before the `'close'` event if the `QuicSocket` was destroyed with an
14201421
`error`.
14211422

1422-
The `'error'` event will not be emitted multiple times.
1423+
The `'error'` event will only ever be emitted once.
14231424

14241425
#### Event: `'listening'`
14251426
<!-- YAML
@@ -1430,7 +1431,7 @@ Emitted after `quicsocket.listen()` is called and the `QuicSocket` has started
14301431
listening for incoming `QuicServerSession`s. The callback is invoked with
14311432
no arguments.
14321433

1433-
The `'listening'` event will not be emitted multiple times.
1434+
The `'listening'` event will only ever be emitted once.
14341435

14351436
#### Event: `'ready'`
14361437
<!-- YAML
@@ -1439,7 +1440,7 @@ added: REPLACEME
14391440

14401441
Emitted once the `QuicSocket` has been bound to a local UDP port.
14411442

1442-
The `'ready'` event will not be emitted multiple times.
1443+
The `'ready'` event will only ever be emitted once.
14431444

14441445
#### Event: `'session'`
14451446
<!-- YAML
@@ -1455,11 +1456,12 @@ const { createQuicSocket } = require('net');
14551456

14561457
const options = getOptionsSomehow();
14571458
const server = createQuicSocket({ server: options });
1458-
server.listen();
14591459

14601460
server.on('session', (session) => {
14611461
// Attach session event listeners.
14621462
});
1463+
1464+
server.listen();
14631465
```
14641466

14651467
The `'session'` event will be emitted multiple times.
@@ -1517,7 +1519,7 @@ added: REPLACEME
15171519

15181520
Creates and adds a new `QuicEndpoint` to the `QuicSocket` instance. An
15191521
error will be thrown if `quicsock.addEndpoint()` is called either after
1520-
the `QuicSocket` has already started binding to the local ports or after
1522+
the `QuicSocket` has already started binding to the local ports, or after
15211523
the `QuicSocket` has been destroyed.
15221524

15231525
#### quicsocket.bound
@@ -1721,10 +1723,9 @@ added: REPLACEME
17211723
* `type`: {string} Identifies the type of UDP socket. The value must either
17221724
be `'udp4'`, indicating UDP over IPv4, or `'udp6'`, indicating UDP over
17231725
IPv6. **Default**: `'udp4'`.
1726+
* Returns: {Promise}
17241727

1725-
Create a new `QuicClientSession`. This function can be called multiple times
1726-
to create sessions associated with different endpoints on the same
1727-
client endpoint.
1728+
Returns a `Promise` that resolves a new `QuicClientSession`.
17281729

17291730
#### quicsocket.destroy(\[error\])
17301731
<!-- YAML
@@ -1745,6 +1746,8 @@ added: REPLACEME
17451746

17461747
Will be `true` if the `QuicSocket` has been destroyed.
17471748

1749+
Read-only.
1750+
17481751
#### quicsocket.duration
17491752
<!-- YAML
17501753
added: REPLACEME
@@ -1765,7 +1768,9 @@ added: REPLACEME
17651768

17661769
An array of `QuicEndpoint` instances associated with the `QuicSocket`.
17671770

1768-
#### quicsocket.listen(\[options\]\[, callback\])
1771+
Read-only.
1772+
1773+
#### quicsocket.listen(\[options\])
17691774
<!-- YAML
17701775
added: REPLACEME
17711776
-->
@@ -1877,13 +1882,10 @@ added: REPLACEME
18771882
[OpenSSL Options][].
18781883
* `sessionIdContext` {string} Opaque identifier used by servers to ensure
18791884
session state is not shared between applications. Unused by clients.
1885+
* Returns: {Promise}
18801886

1881-
* `callback` {Function}
1882-
1883-
Listen for new peer-initiated sessions.
1884-
1885-
If a `callback` is given, it is registered as a handler for the
1886-
`'session'` event.
1887+
Listen for new peer-initiated sessions. Returns a `Promise` that is resolved
1888+
once the `QuicSocket` is actively listening.
18871889

18881890
#### quicsocket.listenDuration
18891891
<!-- YAML
@@ -1905,6 +1907,8 @@ added: REPLACEME
19051907

19061908
Set to `true` if the `QuicSocket` is listening for new connections.
19071909

1910+
Read-only.
1911+
19081912
#### quicsocket.packetsIgnored
19091913
<!-- YAML
19101914
added: REPLACEME
@@ -1947,6 +1951,8 @@ added: REPLACEME
19471951

19481952
Set to `true` if the socket is not yet bound to the local UDP port.
19491953

1954+
Read-only.
1955+
19501956
#### quicsocket.ref()
19511957
<!-- YAML
19521958
added: REPLACEME
@@ -2004,30 +2010,30 @@ by artificially dropping received or transmitted packets.
20042010

20052011
This method is *not* to be used in production applications.
20062012

2007-
#### quicsocket.statelessResetCount
2013+
#### quicsocket.statelessReset
20082014
<!-- YAML
20092015
added: REPLACEME
20102016
-->
20112017

2012-
* Type: {number}
2013-
2014-
The number of stateless resets that have been sent.
2018+
* Type: {boolean} `true` if stateless reset processing is enabled; `false`
2019+
if disabled.
20152020

2016-
Read-only.
2021+
By default, a listening `QuicSocket` will generate stateless reset tokens when
2022+
appropriate. The `disableStatelessReset` option may be set when the
2023+
`QuicSocket` is created to disable generation of stateless resets. The
2024+
`quicsocket.statelessReset` property allows stateless reset to be turned on and
2025+
off dynamically through the lifetime of the `QuicSocket`.
20172026

2018-
#### quicsocket.toggleStatelessReset()
2027+
#### quicsocket.statelessResetCount
20192028
<!-- YAML
20202029
added: REPLACEME
20212030
-->
20222031

2023-
* Returns {boolean} `true` if stateless reset processing is enabled; `false`
2024-
if disabled.
2032+
* Type: {number}
20252033

2026-
By default, a listening `QuicSocket` will generate stateless reset tokens when
2027-
appropriate. The `disableStatelessReset` option may be set when the
2028-
`QuicSocket` is created to disable generation of stateless resets. The
2029-
`toggleStatelessReset()` function allows stateless reset to be turned on and
2030-
off dynamically through the lifetime of the `QuicSocket`.
2034+
The number of stateless resets that have been sent.
2035+
2036+
Read-only.
20312037

20322038
#### quicsocket.unref();
20332039
<!-- YAML

0 commit comments

Comments
 (0)
Please sign in to comment.