doc: remove "is recommended" from crypto legacy API text

.github/CODEOWNERS

@@ -13,16 +13,16 @@
 /CODE_OF_CONDUCT.md @nodejs/tsc @nodejs/community-committee
 /CONTRIBUTING.md @nodejs/tsc @nodejs/community-committee
 /LICENSE @nodejs/tsc @nodejs/community-committee
-/docs/guides/contributing/code-of-conduct.md @nodejs/tsc @nodejs/community-committee
+/doc/guides/contributing/code-of-conduct.md @nodejs/tsc @nodejs/community-committee
 # TODO(mmarchini): the bot doens't have a notion of precedence, that might
 # change when move the codeowners code to an Action, at which point we can
 # uncomment the line below
-# /docs/guides/contributing/*.md @nodejs/tsc
-/docs/guides/contributing/issues.md @nodejs/tsc
-/docs/guides/contributing/pull-requests.md @nodejs/tsc
-/docs/guides/collaborator-guide.md @nodejs/tsc
-/docs/guides/offboarding.md @nodejs/tsc
-/docs/guides/onboarding-extras.md @nodejs/tsc
+# /doc/guides/contributing/*.md @nodejs/tsc
+/doc/guides/contributing/issues.md @nodejs/tsc
+/doc/guides/contributing/pull-requests.md @nodejs/tsc
+/doc/guides/collaborator-guide.md @nodejs/tsc
+/doc/guides/offboarding.md @nodejs/tsc
+/doc/guides/onboarding-extras.md @nodejs/tsc
 
 # net
 
@@ -38,7 +38,7 @@
 /lib/internal/net.js @nodejs/net
 /lib/internal/socket_list.js @nodejs/net
 /lib/internal/js_stream_socket.js @nodejs/net
-/src/cares_wrap.h @nodejs/net
+/src/cares_wrap.cc @nodejs/net
 /src/connect_wrap.* @nodejs/net
 /src/connection_wrap.* @nodejs/net
 /src/node_sockaddr* @nodejs/net
@@ -58,7 +58,6 @@
 
 /deps/llhttp/* @nodejs/http @nodejs/net
 /doc/api/http.md @nodejs/http @nodejs/net
-/doc/api/http2.md @nodejs/http @nodejs/net
 /lib/_http_* @nodejs/http @nodejs/net
 /lib/http.js @nodejs/http @nodejs/net
 /lib/https.js @nodejs/crypto @nodejs/net @nodejs/http
@@ -68,7 +67,7 @@
 # http2
 
 /deps/nghttp2/* @nodejs/http2 @nodejs/net
-/doc/api/http2.md @nodejs/http2 @nodejs/net
+/doc/api/http2.md @nodejs/http2 @nodejs/http @nodejs/net
 /lib/http2.js @nodejs/http2 @nodejs/net
 /lib/internal/http2/* @nodejs/http2 @nodejs/net
 /src/node_http2* @nodejs/http2 @nodejs/net

.github/workflows/linters.yml

@@ -77,3 +77,11 @@ jobs:
         run: |
           make lint-py-build || true
           NODE=$(which node) make lint-py
+
+  lint-codeowners:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - uses: mszostok/codeowners-validator@v0.4.0
+        with:
+          checks: "files,duppatterns"

doc/api/crypto.md

@@ -106,9 +106,10 @@ console.log(Certificate.verifySpkac(Buffer.from(spkac)));
 
 ### Legacy API
 
-As a still supported legacy interface, it is possible (but not recommended) to
-create new instances of the `crypto.Certificate` class as illustrated in the
-examples below.
+> Stability: 0 - Deprecated
+
+As a legacy interface, it is possible to create new instances of
+the `crypto.Certificate` class as illustrated in the examples below.
 
 #### `new crypto.Certificate()`
 

doc/api/deprecations.md

@@ -2776,6 +2776,20 @@ Type: Documentation-only
 
 [`socket.bufferSize`][] is just an alias for [`writable.writableLength`][].
 
+<a id="DEP0XXX"></a>
+### DEP0XXX: `new crypto.Certificate()`
+<!-- YAML
+changes:
+  - version: REPLACEME
+    pr-url: https://github.com/nodejs/node/pull/34697
+    description: Documentation-only deprecation.
+-->
+
+Type: Documentation-only
+
+The [`crypto.Certificate()` constructor][] is deprecated. Use
+[static methods of `crypto.Certificate()`][] instead.
+
 [`--pending-deprecation`]: cli.html#cli_pending_deprecation
 [`--throw-deprecation`]: cli.html#cli_throw_deprecation
 [`Buffer.allocUnsafeSlow(size)`]: buffer.html#buffer_static_method_buffer_allocunsafeslow_size
@@ -2798,6 +2812,7 @@ Type: Documentation-only
 [`clearTimeout()`]: timers.html#timers_cleartimeout_timeout
 [`console.error()`]: console.html#console_console_error_data_args
 [`console.log()`]: console.html#console_console_log_data_args
+[`crypto.Certificate()` constructor]: crypto.html#crypto_legacy_api
 [`crypto.DEFAULT_ENCODING`]: crypto.html#crypto_crypto_default_encoding
 [`crypto.createCipher()`]: crypto.html#crypto_crypto_createcipher_algorithm_password_options
 [`crypto.createCipheriv()`]: crypto.html#crypto_crypto_createcipheriv_algorithm_key_iv_options
@@ -2897,3 +2912,4 @@ Type: Documentation-only
 [from_arraybuffer]: buffer.html#buffer_static_method_buffer_from_arraybuffer_byteoffset_length
 [from_string_encoding]: buffer.html#buffer_static_method_buffer_from_string_encoding
 [legacy `urlObject`]: url.html#url_legacy_urlobject
+[static methods of `crypto.Certificate()`]: crypto.html#crypto_class_certificate

doc/api/errors.md

@@ -2139,11 +2139,6 @@ import 'package-name'; // supported
 
 `import` with URL schemes other than `file` and `data` is unsupported.
 
-<a id="ERR_V8BREAKITERATOR"></a>
-### `ERR_V8BREAKITERATOR`
-
-The V8 `BreakIterator` API was used but the full ICU data set is not installed.
-
 <a id="ERR_VALID_PERFORMANCE_ENTRY_TYPE"></a>
 ### `ERR_VALID_PERFORMANCE_ENTRY_TYPE`
 
@@ -2555,6 +2550,11 @@ An attempt was made to launch a Node.js process with an unknown `stdout` or
 `stderr` file type. This error is usually an indication of a bug within Node.js
 itself, although it is possible for user code to trigger it.
 
+<a id="ERR_V8BREAKITERATOR"></a>
+### `ERR_V8BREAKITERATOR`
+
+The V8 `BreakIterator` API was used but the full ICU data set is not installed.
+
 <a id="ERR_VALUE_OUT_OF_RANGE"></a>
 ### `ERR_VALUE_OUT_OF_RANGE`
 <!-- YAML

doc/api/fs.md

@@ -4548,8 +4548,8 @@ added: v10.0.0
   file descriptor is closed, or will be rejected if an error occurs while
   closing.
 
-Closes the file handle. Will wait for any pending operation on the handle
-to complete before completing.
+Closes the file handle after waiting for any pending operation on the handle to
+complete.
 
 ```js
 const fsPromises = require('fs').promises;

doc/api/http2.md

@@ -2,6 +2,10 @@
 <!-- YAML
 added: v8.4.0
 changes:
+  - version: REPLACEME
+    pr-url: https://github.com/nodejs/node/pull/34664
+    description: Requests with the `host` header (with or without
+                 `:authority`) can now be sent/received.
   - version: v10.10.0
     pr-url: https://github.com/nodejs/node/pull/22466
     description: HTTP/2 is now Stable. Previously, it had been Experimental.
@@ -2530,7 +2534,7 @@ For incoming headers:
   `access-control-max-age`, `access-control-request-method`, `content-encoding`,
   `content-language`, `content-length`, `content-location`, `content-md5`,
   `content-range`, `content-type`, `date`, `dnt`, `etag`, `expires`, `from`,
-  `if-match`, `if-modified-since`, `if-none-match`, `if-range`,
+  `host`, `if-match`, `if-modified-since`, `if-none-match`, `if-range`,
   `if-unmodified-since`, `last-modified`, `location`, `max-forwards`,
   `proxy-authorization`, `range`, `referer`,`retry-after`, `tk`,
   `upgrade-insecure-requests`, `user-agent` or `x-content-type-options` are
@@ -2909,8 +2913,10 @@ added: v8.4.0
 
 * {string}
 
-The request authority pseudo header field. It can also be accessed via
-`req.headers[':authority']`.
+The request authority pseudo header field. Because HTTP/2 allows requests
+to set either `:authority` or `host`, this value is derived from
+`req.headers[':authority']` if present. Otherwise, it is derived from
+`req.headers['host']`.
 
 #### `request.complete`
 <!-- YAML
@@ -3709,6 +3715,18 @@ following additional properties:
 * `type` {string} Either `'server'` or `'client'` to identify the type of
   `Http2Session`.
 
+## Note on `:authority` and `host`
+
+HTTP/2 requires requests to have either the `:authority` pseudo-header
+or the `host` header. Prefer `:authority` when constructing an HTTP/2
+request directly, and `host` when converting from HTTP/1 (in proxies,
+for instance).
+
+The compatibility API falls back to `host` if `:authority` is not
+present. See [`request.authority`][] for more information. However,
+if you don't use the compatibility API (or use `req.headers` directly),
+you need to implement any fall-back behaviour yourself.
+
 [ALPN Protocol ID]: https://www.iana.org/assignments/tls-extensiontype-values/tls-extensiontype-values.xhtml#alpn-protocol-ids
 [ALPN negotiation]: #http2_alpn_negotiation
 [Compatibility API]: #http2_compatibility_api
@@ -3749,6 +3767,7 @@ following additional properties:
 [`net.Socket.prototype.unref()`]: net.html#net_socket_unref
 [`net.Socket`]: net.html#net_class_net_socket
 [`net.connect()`]: net.html#net_net_connect
+[`request.authority`]: #http2_request_authority
 [`request.socket`]: #http2_request_socket
 [`request.socket.getPeerCertificate()`]: tls.html#tls_tlssocket_getpeercertificate_detailed
 [`response.end()`]: #http2_response_end_data_encoding_callback

doc/api/quic.md

@@ -1246,12 +1246,16 @@ empty object when the key exchange is not ephemeral. The supported types are
 
 For example: `{ type: 'ECDH', name: 'prime256v1', size: 256 }`.
 
-#### `quicclientsession.setSocket(socket])`
+#### `quicclientsession.setSocket(socket[, natRebinding])`
 <!-- YAML
 added: REPLACEME
 -->
 
 * `socket` {QuicSocket} A `QuicSocket` instance to move this session to.
+* `natRebinding` {boolean} When `true`, indicates that the local address is to
+  be changed without triggering address validation. This will be rare and will
+  typically be used only to test resiliency in NAT rebind scenarios.
+  **Default**: `false`.
 * Returns: {Promise}
 
 Migrates the `QuicClientSession` to the given `QuicSocket` instance. If the new
@@ -1441,6 +1445,24 @@ error will be thrown if `quicsock.addEndpoint()` is called either after
 the `QuicSocket` has already started binding to the local ports, or after
 the `QuicSocket` has been destroyed.
 
+#### `quicsocket.blockList`
+<!-- YAML
+added: REPLACEME
+-->
+
+* Type: {net.BlockList}
+
+A {net.BlockList} instance used to define rules for remote IPv4 or IPv6
+addresses that this `QuicSocket` is not permitted to interact with. The
+rules can be specified as either specific individual addresses, ranges
+of addresses, or CIDR subnet ranges.
+
+When listening as a server, if a packet is received from a blocked address,
+the packet will be ignored.
+
+When connecting as a client, if the remote IP address is blocked, the
+connection attempt will be rejected.
+
 #### `quicsocket.bound`
 <!-- YAML
 added: REPLACEME

doc/guides/commit-queue.md

@@ -50,7 +50,7 @@ of the commit queue:
 
 ## Implementation
 
-The [action](/.github/workflows/commit_queue.yml) will run on scheduler
+The [action](../../.github/workflows/commit-queue.yml) will run on scheduler
 events every five minutes. Five minutes is the smallest number accepted by
 the scheduler. The scheduler is not guaranteed to run every five minutes, it
 might take longer between runs.
@@ -73,7 +73,7 @@ a Jenkins token from
 `octokit/graphql-action` is used to fetch all Pull Requests with the
 `commit-queue` label. The output is a JSON payload, so `jq` is used to turn
 that into a list of PR ids we can pass as arguments to
-[`commit-queue.sh`](./tools/actions/commit-queue.sh).
+[`commit-queue.sh`](../../tools/actions/commit-queue.sh).
 
 > The personal token only needs permission for public repositories and to read
 > profiles, we can use the GITHUB_TOKEN for write operations. Jenkins token is

lib/_http_agent.js

@@ -39,12 +39,11 @@ const { async_id_symbol } = require('internal/async_hooks').symbols;
 const {
   codes: {
     ERR_INVALID_ARG_TYPE,
-    ERR_INVALID_OPT_VALUE,
     ERR_OUT_OF_RANGE,
   },
 } = require('internal/errors');
 const { once } = require('internal/util');
-const { validateNumber } = require('internal/validators');
+const { validateNumber, validateOneOf } = require('internal/validators');
 
 const kOnKeylog = Symbol('onkeylog');
 const kRequestOptions = Symbol('requestOptions');
@@ -99,9 +98,7 @@ function Agent(options) {
   this.maxTotalSockets = this.options.maxTotalSockets;
   this.totalSocketCount = 0;
 
-  if (this.scheduling !== 'fifo' && this.scheduling !== 'lifo') {
-    throw new ERR_INVALID_OPT_VALUE('scheduling', this.scheduling);
-  }
+  validateOneOf(this.scheduling, 'scheduling', ['fifo', 'lifo'], true);
 
   if (this.maxTotalSockets !== undefined) {
     validateNumber(this.maxTotalSockets, 'maxTotalSockets');

lib/dns.js

@@ -49,6 +49,7 @@ const {
 const {
   validatePort,
   validateString,
+  validateOneOf,
 } = require('internal/validators');
 
 const {
@@ -114,8 +115,7 @@ function lookup(hostname, options, callback) {
     family = options >>> 0;
   }
 
-  if (family !== 0 && family !== 4 && family !== 6)
-    throw new ERR_INVALID_OPT_VALUE('family', family);
+  validateOneOf(family, 'family', [0, 4, 6], true);
 
   if (!hostname) {
     emitInvalidHostnameWarning(hostname);

lib/internal/blocklist.js

@@ -26,8 +26,13 @@ const {
 } = require('internal/errors').codes;
 
 class BlockList {
-  constructor() {
-    this[kHandle] = new BlockListHandle();
+  constructor(handle = new BlockListHandle()) {
+    // The handle argument is an intentionally undocumented
+    // internal API. User code will not be able to create
+    // a BlockListHandle object directly.
+    if (!(handle instanceof BlockListHandle))
+      throw new ERR_INVALID_ARG_TYPE('handle', 'BlockListHandle', handle);
+    this[kHandle] = handle;
     this[kHandle][owner_symbol] = this;
   }
 

lib/internal/child_process.js

@@ -21,7 +21,7 @@ const {
     ERR_MISSING_ARGS
   }
 } = require('internal/errors');
-const { validateString } = require('internal/validators');
+const { validateString, validateOneOf } = require('internal/validators');
 const EventEmitter = require('events');
 const net = require('net');
 const dgram = require('dgram');
@@ -345,13 +345,9 @@ ChildProcess.prototype.spawn = function(options) {
   const ipcFd = stdio.ipcFd;
   stdio = options.stdio = stdio.stdio;
 
-  if (options.serialization !== undefined &&
-      options.serialization !== 'json' &&
-      options.serialization !== 'advanced') {
-    throw new ERR_INVALID_OPT_VALUE('options.serialization',
-                                    options.serialization);
-  }
 
+  validateOneOf(options.serialization, 'options.serialization',
+                [undefined, 'json', 'advanced'], true);
   const serialization = options.serialization || 'json';
 
   if (ipc !== undefined) {

lib/internal/dns/promises.js

@@ -31,7 +31,8 @@ const {
 } = codes;
 const {
   validatePort,
-  validateString
+  validateString,
+  validateOneOf,
 } = require('internal/validators');
 
 function onlookup(err, addresses) {
@@ -116,8 +117,7 @@ function lookup(hostname, options) {
     family = options >>> 0;
   }
 
-  if (family !== 0 && family !== 4 && family !== 6)
-    throw new ERR_INVALID_OPT_VALUE('family', family);
+  validateOneOf(family, 'family', [0, 4, 6], true);
 
   return createLookupPromise(family, hostname, all, hints, verbatim);
 }

lib/internal/errors.js

@@ -1432,10 +1432,6 @@ E('ERR_UNSUPPORTED_DIR_IMPORT', "Directory import '%s' is not supported " +
 E('ERR_UNSUPPORTED_ESM_URL_SCHEME', 'Only file and data URLs are supported ' +
   'by the default ESM loader', Error);
 
-E('ERR_V8BREAKITERATOR',
-  'Full ICU data not installed. See https://github.com/nodejs/node/wiki/Intl',
-  Error);
-
 // This should probably be a `TypeError`.
 E('ERR_VALID_PERFORMANCE_ENTRY_TYPE',
   'At least one valid performance entry type is required', Error);

lib/internal/http2/compat.js

@@ -50,7 +50,8 @@ const {
   kSocket,
   kRequest,
   kProxySocket,
-  assertValidPseudoHeader
+  assertValidPseudoHeader,
+  getAuthority
 } = require('internal/http2/util');
 const { _checkIsHttpToken: checkIsHttpToken } = require('_http_common');
 
@@ -395,7 +396,7 @@ class Http2ServerRequest extends Readable {
   }
 
   get authority() {
-    return this[kHeaders][HTTP2_HEADER_AUTHORITY];
+    return getAuthority(this[kHeaders]);
   }
 
   get scheme() {