diff --git a/doc/api/esm.md b/doc/api/esm.md index d1b2d786b38534..2b7b90545a35e5 100644 --- a/doc/api/esm.md +++ b/doc/api/esm.md @@ -764,6 +764,74 @@ const dynamicLibrary = await import.source('./library.wasm'); const instance = await WebAssembly.instantiate(dynamicLibrary, importObject); ``` +### JavaScript String Builtins + + + +When importing WebAssembly modules, the +[WebAssembly JS String Builtins Proposal][] is automatically enabled through the +ESM Integration. This allows WebAssembly modules to directly use efficient +compile-time string builtins from the `wasm:js-string` namespace. + +For example, the following Wasm module exports a string `getLength` function using +the `wasm:js-string` `length` builtin: + +```text +(module + ;; Compile-time import of the string length builtin. + (import "wasm:js-string" "length" (func $string_length (param externref) (result i32))) + + ;; Define getLength, taking a JS value parameter assumed to be a string, + ;; calling string length on it and returning the result. + (func $getLength (param $str externref) (result i32) + local.get $str + call $string_length + ) + + ;; Export the getLength function. + (export "getLength" (func $get_length)) +) +``` + +```js +import { getLength } from './string-len.wasm'; +getLength('foo'); // Returns 3. +``` + +Wasm builtins are compile-time imports that are linked during module compilation +rather than during instantiation. They do not behave like normal module graph +imports and they cannot be inspected via `WebAssembly.Module.imports(mod)` +or virtualized unless recompiling the module using the direct +`WebAssembly.compile` API with string builtins disabled. + +Importing a module in the source phase before it has been instantiated will also +use the compile-time builtins automatically: + +```js +import source mod from './string-len.wasm'; +const { exports: { getLength } } = await WebAssembly.instantiate(mod, {}); +getLength('foo'); // Also returns 3. +``` + +### Reserved Wasm Namespaces + + + +When importing WebAssembly modules through the ESM Integration, they cannot use +import module names or import/export names that start with reserved prefixes: + +* `wasm-js:` - reserved in all module import names, module names and export + names. +* `wasm:` - reserved in module import names and export names (imported module + names are allowed in order to support future builtin polyfills). + +Importing a module using the above reserved names will throw a +`WebAssembly.LinkError`. + ## Top-level `await` @@ -1206,6 +1274,7 @@ resolution for ESM specifiers is [commonjs-extension-resolution-loader][]. [Source Phase Imports]: https://github.com/tc39/proposal-source-phase-imports [Terminology]: #terminology [URL]: https://url.spec.whatwg.org/ +[WebAssembly JS String Builtins Proposal]: https://github.com/WebAssembly/js-string-builtins [`"exports"`]: packages.md#exports [`"type"`]: packages.md#type [`--input-type`]: cli.md#--input-typetype diff --git a/doc/api/tls.md b/doc/api/tls.md index 5fde522dc9ae31..7be5ee7fb29a56 100644 --- a/doc/api/tls.md +++ b/doc/api/tls.md @@ -2260,6 +2260,54 @@ openssl pkcs12 -certpbe AES-256-CBC -export -out client-cert.pem \ The server can be tested by connecting to it using the example client from [`tls.connect()`][]. +## `tls.setDefaultCACertificates(certs)` + + + +* `certs` {string\[]|ArrayBufferView\[]} An array of CA certificates in PEM format. + +Sets the default CA certificates used by Node.js TLS clients. If the provided +certificates are parsed successfully, they will become the default CA +certificate list returned by [`tls.getCACertificates()`][] and used +by subsequent TLS connections that don't specify their own CA certificates. +The certificates will be deduplicated before being set as the default. + +This function only affects the current Node.js thread. Previous +sessions cached by the HTTPS agent won't be affected by this change, so +this method should be called before any unwanted cachable TLS connections are +made. + +To use system CA certificates as the default: + +```cjs +const tls = require('node:tls'); +tls.setDefaultCACertificates(tls.getCACertificates('system')); +``` + +```mjs +import tls from 'node:tls'; +tls.setDefaultCACertificates(tls.getCACertificates('system')); +``` + +This function completely replaces the default CA certificate list. To add additional +certificates to the existing defaults, get the current certificates and append to them: + +```cjs +const tls = require('node:tls'); +const currentCerts = tls.getCACertificates('default'); +const additionalCerts = ['-----BEGIN CERTIFICATE-----\n...']; +tls.setDefaultCACertificates([...currentCerts, ...additionalCerts]); +``` + +```mjs +import tls from 'node:tls'; +const currentCerts = tls.getCACertificates('default'); +const additionalCerts = ['-----BEGIN CERTIFICATE-----\n...']; +tls.setDefaultCACertificates([...currentCerts, ...additionalCerts]); +``` + ## `tls.getCACertificates([type])`