diff options
author | James M Snell <jasnell@gmail.com> | 2020-07-11 00:57:48 +0300 |
---|---|---|
committer | James M Snell <jasnell@gmail.com> | 2020-07-16 03:16:57 +0300 |
commit | fe4e7e4598fc4396a06cbf2eb2544ae9ce6f8d10 (patch) | |
tree | b91fc9913399ce517cadab61cb212c3901988e5f /doc/api/quic.md | |
parent | 346aeaf87493400fbeb53eeefb50b47537fb0cda (diff) |
quic: use promisified dns lookup
PR-URL: https://github.com/nodejs/node/pull/34283
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Diffstat (limited to 'doc/api/quic.md')
-rw-r--r-- | doc/api/quic.md | 41 |
1 files changed, 40 insertions, 1 deletions
diff --git a/doc/api/quic.md b/doc/api/quic.md index 671a4c681be..d362e55328b 100644 --- a/doc/api/quic.md +++ b/doc/api/quic.md @@ -269,7 +269,8 @@ added: REPLACEME * `type` {string} Can be one of `'udp4'`, `'upd6'`, or `'udp6-only'` to use IPv4, IPv6, or IPv6 with dual-stack mode disabled. **Default**: `'udp4'`. - * `lookup` {Function} A custom DNS lookup function. Default `dns.lookup()`. + * `lookup` {Function} A [custom DNS lookup function][]. + **Default**: undefined. * `maxConnections` {number} The maximum number of total active inbound connections. * `maxConnectionsPerHost` {number} The maximum number of inbound connections @@ -1505,6 +1506,8 @@ added: REPLACEME * `type` {string} Can be one of `'udp4'`, `'upd6'`, or `'udp6-only'` to use IPv4, IPv6, or IPv6 with dual-stack mode disabled. **Default**: `'udp4'`. + * `lookup` {Function} A [custom DNS lookup function][]. + **Default**: undefined. * Returns: {QuicEndpoint} Creates and adds a new `QuicEndpoint` to the `QuicSocket` instance. An @@ -1661,6 +1664,8 @@ added: REPLACEME passphrase: <string>]}`. The object form can only occur in an array. `object.passphrase` is optional. Encrypted keys will be decrypted with `object.passphrase` if provided, or `options.passphrase` if it is not. + * `lookup` {Function} A [custom DNS lookup function][]. + **Default**: undefined. * `activeConnectionIdLimit` {number} Must be a value between `2` and `8` (inclusive). Default: `2`. * `congestionAlgorithm` {string} Must be either `'reno'` or `'cubic'`. @@ -1836,6 +1841,8 @@ added: REPLACEME passphrase: <string>]}`. The object form can only occur in an array. `object.passphrase` is optional. Encrypted keys will be decrypted with `object.passphrase` if provided, or `options.passphrase` if it is not. + * `lookup` {Function} A [custom DNS lookup function][]. + **Default**: undefined. * `activeConnectionIdLimit` {number} * `congestionAlgorithm` {string} Must be either `'reno'` or `'cubic'`. **Default**: `'reno'`. @@ -2411,6 +2418,36 @@ added: REPLACEME Set to `true` if the `QuicStream` is unidirectional. +## Additional Notes + +### Custom DNS Lookup Functions + +By default, the QUIC implementation uses the `dns` module's +[promisified version of `lookup()`][] to resolve domains names +into IP addresses. For most typical use cases, this will be +sufficient. However, it is possible to pass a custom `lookup` +function as an option in several places throughout the QUIC API: + +* `net.createQuicSocket()` +* `quicsocket.addEndpoint()` +* `quicsocket.connect()` +* `quicsocket.listen()` + +The custom `lookup` function must teturn a `Promise` that is +resolved once the lookup is complete. It will be invoked with +two arguments: + +* `address` {string|undefined} The host name to resolve, or + `undefined` if no host name was provided. +* `family` {number} One of `4` or `6`, identifying either + IPv4 or IPv6. + +```js +async function myCustomLookup(address, type) { + return resolveTheAddressSomehow(address, type); +} +``` + [`crypto.getCurves()`]: crypto.html#crypto_crypto_getcurves [`stream.Readable`]: #stream_class_stream_readable [`tls.DEFAULT_ECDH_CURVE`]: #tls_tls_default_ecdh_curve @@ -2418,8 +2455,10 @@ Set to `true` if the `QuicStream` is unidirectional. [ALPN]: https://tools.ietf.org/html/rfc7301 [RFC 4007]: https://tools.ietf.org/html/rfc4007 [Certificate Object]: https://nodejs.org/dist/latest-v12.x/docs/api/tls.html#tls_certificate_object +[custom DNS lookup function]: #custom_dns_lookups [modifying the default cipher suite]: tls.html#tls_modifying_the_default_tls_cipher_suite [OpenSSL Options]: crypto.html#crypto_openssl_options [Perfect Forward Secrecy]: #tls_perfect_forward_secrecy +[promisified version of `lookup()`]: dns.html#dns_dnspromises_lookup_hostname_options ['qlog']: #quic_quicsession_qlog [qlog standard]: https://tools.ietf.org/id/draft-marx-qlog-event-definitions-quic-h3-00.html |