v8.9.0

Author: h7lin

cli/force_async_hooks_checks.md

@@ -0,0 +1,7 @@
+<!-- YAML
+added: v8.8.0
+-->
+
+Enables runtime checks for `async_hooks`. These can also be enabled dynamically
+by enabling one of the `async_hooks` hooks.
+

cli/node_no_http2_1.md

@@ -0,0 +1,6 @@
+<!-- YAML
+added: v8.8.0
+-->
+
+When set to `1`, the `http2` module is suppressed.
+

crypto/crypto_publicdecrypt_key_buffer.md

@@ -0,0 +1,20 @@
+<!-- YAML
+added: v1.1.0
+-->
+- `key` {Object | string}
+  - `key` {string} A PEM encoded public or private key.
+  - `passphrase` {string} An optional passphrase for the private key.
+  - `padding` {crypto.constants} An optional padding value defined in
+    `crypto.constants`, which may be: `crypto.constants.RSA_NO_PADDING` or
+    `RSA_PKCS1_PADDING`.
+- `buffer` {Buffer | TypedArray | DataView}
+- Returns: {Buffer} A new `Buffer` with the decrypted content.
+
+Decrypts `buffer` with `key`.
+
+`key` can be an object or a string. If `key` is a string, it is treated as
+the key with no passphrase and will use `RSA_PKCS1_PADDING`.
+
+Because RSA public keys can be derived from private keys, a private key may
+be passed instead of a public key.
+

crypto/crypto_publicencrypt_key_buffer.md

@@ -0,0 +1,21 @@
+<!-- YAML
+added: v0.11.14
+-->
+- `key` {Object | string}
+  - `key` {string} A PEM encoded public or private key.
+  - `passphrase` {string} An optional passphrase for the private key.
+  - `padding` {crypto.constants} An optional padding value defined in
+    `crypto.constants`, which may be: `crypto.constants.RSA_NO_PADDING`,
+    `RSA_PKCS1_PADDING`, or `crypto.constants.RSA_PKCS1_OAEP_PADDING`.
+- `buffer` {Buffer | TypedArray | DataView}
+- Returns: {Buffer} A new `Buffer` with the encrypted content.
+
+Encrypts the content of `buffer` with `key` and returns a new
+[`Buffer`][] with encrypted content.
+
+`key` can be an object or a string. If `key` is a string, it is treated as
+the key with no passphrase and will use `RSA_PKCS1_OAEP_PADDING`.
+
+Because RSA public keys can be derived from private keys, a private key may
+be passed instead of a public key.
+

dgram/socket_getrecvbuffersize.md

@@ -0,0 +1,6 @@
+<!-- YAML
+added: v8.7.0
+-->
+
+* Returns {number} the `SO_RCVBUF` socket receive buffer size in bytes.
+

dgram/socket_getsendbuffersize.md

@@ -0,0 +1,6 @@
+<!-- YAML
+added: v8.7.0
+-->
+
+* Returns {number} the `SO_SNDBUF` socket send buffer size in bytes.
+

errors/err_async_callback.md

@@ -0,0 +1,5 @@
+
+Used with `AsyncHooks` to indicate an attempt of registering something that is
+not a function as a callback.
+
+<a id="ERR_ASYNC_TYPE"></a>

errors/err_async_type.md

@@ -0,0 +1,5 @@
+
+Used when the type of an asynchronous resource is invalid. Note that users are
+also able to define their own types when using the public embedder API.
+
+<a id="ERR_ENCODING_INVALID_ENCODED_DATA"></a>

errors/err_encoding_invalid_encoded_data.md

@@ -0,0 +1,5 @@
+
+Used by the `util.TextDecoder()` API when the data provided is invalid
+according to the encoding provided.
+
+<a id="ERR_ENCODING_NOT_SUPPORTED"></a>

errors/err_encoding_not_supported.md

@@ -0,0 +1,5 @@
+
+Used by the `util.TextDecoder()` API when the encoding provided is not one of
+the [WHATWG Supported Encodings][].
+
+<a id="ERR_FALSY_VALUE_REJECTION"></a>

errors/err_http2_header_required.md

@@ -0,0 +1,4 @@
+
+Used when a required header is missing in an HTTP/2 message.
+
+<a id="ERR_HTTP2_HEADER_SINGLE_VALUE"></a>

errors/err_http2_headers_after_respond.md

@@ -0,0 +1,5 @@
+
+Used when trying to specify additional headers after an HTTP/2 response
+initiated.
+
+<a id="ERR_HTTP2_HEADERS_OBJECT"></a>

errors/err_http_invalid_char.md

@@ -0,0 +1,5 @@
+
+Used when an invalid character is found in an HTTP response status message
+(reason phrase).
+
+<a id="ERR_HTTP_INVALID_STATUS_CODE"></a>

errors/err_invalid_async_id.md

@@ -0,0 +1,5 @@
+
+Used with `AsyncHooks` when an invalid `asyncId` or `triggerAsyncId` is passed.
+An id less than -1 should never happen.
+
+<a id="ERR_INVALID_CALLBACK"></a>

errors/err_invalid_performance_mark.md

@@ -0,0 +1,5 @@
+
+Used by the Performance Timing API (`perf_hooks`) when a performance mark is
+invalid.
+
+<a id="ERR_INVALID_PROTOCOL"></a>

errors/err_napi_cons_function.md

@@ -0,0 +1,4 @@
+
+Used by the `N-API` when a constructor passed is not a function.
+
+<a id="ERR_NAPI_CONS_PROTOTYPE_OBJECT"></a>

errors/err_napi_cons_prototype_object.md

@@ -0,0 +1,4 @@
+
+Used by the `N-API` when `Constructor.prototype` is not an object.
+
+<a id="ERR_NO_ICU"></a>

errors/err_outofmemory.md

@@ -0,0 +1,5 @@
+
+Used generically to identify that an operation caused an out of memory
+condition.
+
+<a id="ERR_SOCKET_ALREADY_BOUND"></a>

errors/err_socket_closed.md

@@ -0,0 +1,4 @@
+
+Used when an attempt is made to operate on an already closed socket.
+
+<a id="ERR_SOCKET_DGRAM_NOT_RUNNING"></a>

errors/err_tls_cert_altname_invalid.md

@@ -0,0 +1,5 @@
+
+Used with TLS, when the hostname/IP of the peer does not match any of the
+subjectAltNames in its certificate.
+
+<a id="ERR_TLS_DH_PARAM_SIZE"></a>

errors/err_tls_dh_param_size.md

@@ -0,0 +1,7 @@
+
+Used with TLS when the parameter offered for the Diffie-Hellman (`DH`)
+key-agreement protocol is too small. By default, the key length must be greater
+than or equal to 1024 bits to avoid vulnerabilities, even though it is strongly
+recommended to use 2048 bits or larger for stronger security.
+
+<a id="ERR_TLS_HANDSHAKE_TIMEOUT"></a>

errors/err_tls_handshake_timeout.md

@@ -0,0 +1,5 @@
+
+A TLS error emitted by the server whenever a TLS/SSL handshake times out. In
+this case, the server must also abort the connection.
+
+<a id="ERR_TLS_RENEGOTIATION_FAILED"></a>

errors/err_tls_renegotiation_failed.md

@@ -0,0 +1,4 @@
+
+Used when a TLS renegotiation request has failed in a non-specific way.
+
+<a id="ERR_TLS_REQUIRED_SERVER_NAME"></a>

errors/err_tls_required_server_name.md

@@ -0,0 +1,5 @@
+
+Used with TLS, when calling the `server.addContext()` method without providing
+a hostname in the first parameter.
+
+<a id="ERR_TLS_SESSION_ATTACK"></a>

errors/err_tls_session_attack.md

@@ -0,0 +1,5 @@
+
+Used when an excessive amount of TLS renegotiations is detected, which is a
+potential vector for denial-of-service attacks.
+
+<a id="ERR_TRANSFORM_ALREADY_TRANSFORMING"></a>

errors/err_transform_already_transforming.md

@@ -0,0 +1,5 @@
+
+Used in Transform streams when the stream finishes while it is still
+transforming.
+
+<a id="ERR_TRANSFORM_WITH_LENGTH_0"></a>

errors/err_transform_with_length_0.md

@@ -0,0 +1,5 @@
+
+Used in Transform streams when the stream finishes with data still in the write
+buffer.
+
+<a id="ERR_UNKNOWN_SIGNAL"></a>

esm/dynamic_instantiate_hook.md

@@ -0,0 +1,23 @@
+
+To create a custom dynamic module that doesn't correspond to one of the
+existing `format` interpretations, the `dynamicInstantiate` hook can be used.
+This hook is called only for modules that return `format: "dynamic"` from
+the `resolve` hook.
+
+```js
+export async function dynamicInstantiate(url) {
+  return {
+    exports: ['customExportName'],
+    execute: (exports) => {
+      // get and set functions provided for pre-allocated export names
+      exports.customExportName.set('value');
+    }
+  };
+}
+```
+
+With the list of module exports provided upfront, the `execute` function will
+then be called at the exact point of module evalutation order for that module
+in the import tree.
+
+[Node.js EP for ES Modules]: https://github.com/nodejs/node-eps/blob/master/002-es-modules.md

esm/loader_hooks.md

@@ -0,0 +1,9 @@
+
+<!-- type=misc -->
+
+To customize the default module resolution, loader hooks can optionally be
+provided via a `--loader ./loader-name.mjs` argument to Node.
+
+When hooks are used they only apply to ES module loading and not to any
+CommonJS modules loaded.
+

esm/resolve_hook.md

@@ -0,0 +1,73 @@
+
+The resolve hook returns the resolved file URL and module format for a
+given module specifier and parent file URL:
+
+```js
+import url from 'url';
+
+export async function resolve(specifier, parentModuleURL, defaultResolver) {
+  return {
+    url: new URL(specifier, parentModuleURL).href,
+    format: 'esm'
+  };
+}
+```
+
+The default NodeJS ES module resolution function is provided as a third
+argument to the resolver for easy compatibility workflows.
+
+In addition to returning the resolved file URL value, the resolve hook also
+returns a `format` property specifying the module format of the resolved
+module. This can be one of `"esm"`, `"cjs"`, `"json"`, `"builtin"` or
+`"addon"`.
+
+For example a dummy loader to load JavaScript restricted to browser resolution
+rules with only JS file extension and Node builtin modules support could
+be written:
+
+```js
+import url from 'url';
+import path from 'path';
+import process from 'process';
+
+const builtins = new Set(
+  Object.keys(process.binding('natives')).filter((str) =>
+    /^(?!(?:internal|node|v8)\/)/.test(str))
+);
+const JS_EXTENSIONS = new Set(['.js', '.mjs']);
+
+export function resolve(specifier, parentModuleURL/*, defaultResolve */) {
+  if (builtins.has(specifier)) {
+    return {
+      url: specifier,
+      format: 'builtin'
+    };
+  }
+  if (/^\.{0,2}[/]/.test(specifier) !== true && !specifier.startsWith('file:')) {
+    // For node_modules support:
+    // return defaultResolve(specifier, parentModuleURL);
+    throw new Error(
+      `imports must begin with '/', './', or '../'; '${specifier}' does not`);
+  }
+  const resolved = new url.URL(specifier, parentModuleURL);
+  const ext = path.extname(resolved.pathname);
+  if (!JS_EXTENSIONS.has(ext)) {
+    throw new Error(
+      `Cannot load file with non-JavaScript file extension ${ext}.`);
+  }
+  return {
+    url: resolved.href,
+    format: 'esm'
+  };
+}
+```
+
+With this loader, running:
+
+```console
+NODE_OPTIONS='--experimental-modules --loader ./custom-loader.mjs' node x.js
+```
+
+would load the module `x.js` as an ES module with relative resolution support
+(with `node_modules` loading skipped in this example).
+

http/server_listen.md

@@ -0,0 +1,4 @@
+
+Starts the HTTP server listening for connections.
+This method is identical to [`server.listen()`][] from [`net.Server`][].
+

http2/client_side_example.md

@@ -0,0 +1,30 @@
+
+The following illustrates an HTTP/2 client:
+
+```js
+const http2 = require('http2');
+const fs = require('fs');
+const client = http2.connect('https://localhost:8443', {
+  ca: fs.readFileSync('localhost-cert.pem')
+});
+client.on('socketError', (err) => console.error(err));
+client.on('error', (err) => console.error(err));
+
+const req = client.request({ ':path': '/' });
+
+req.on('response', (headers, flags) => {
+  for (const name in headers) {
+    console.log(`${name}: ${headers[name]}`);
+  }
+});
+
+req.setEncoding('utf8');
+let data = '';
+req.on('data', (chunk) => { data += chunk; });
+req.on('end', () => {
+  console.log(`\n${data}`);
+  client.destroy();
+});
+req.end();
+```
+

http2/server_side_example.md

@@ -0,0 +1,34 @@
+
+The following illustrates a simple, plain-text HTTP/2 server using the
+Core API:
+
+```js
+const http2 = require('http2');
+const fs = require('fs');
+
+const server = http2.createSecureServer({
+  key: fs.readFileSync('localhost-privkey.pem'),
+  cert: fs.readFileSync('localhost-cert.pem')
+});
+server.on('error', (err) => console.error(err));
+server.on('socketError', (err) => console.error(err));
+
+server.on('stream', (stream, headers) => {
+  // stream is a Duplex
+  stream.respond({
+    'content-type': 'text/html',
+    ':status': 200
+  });
+  stream.end('<h1>Hello World</h1>');
+});
+
+server.listen(8443);
+```
+
+To generate the certificate and key for this example, run:
+
+```bash
+openssl req -x509 -newkey rsa:2048 -nodes -sha256 -subj '/CN=localhost' \
+  -keyout localhost-privkey.pem -out localhost-cert.pem
+```
+

https/server_listen.md

@@ -0,0 +1,4 @@
+
+Starts the HTTPS server listening for encrypted connections.
+This method is identical to [`server.listen()`][] from [`net.Server`][].
+

modules/require_resolve_paths_request.md

@@ -0,0 +1,9 @@
+<!-- YAML
+added: v8.9.0
+-->
+
+* `request` {string} The module path whose lookup paths are being retrieved.
+* Returns: {Array}
+
+Returns an array containing the paths searched during resolution of `request`.
+