diff --git a/README.md b/README.md index 169d0cab13d..fe58899affc 100644 --- a/README.md +++ b/README.md @@ -86,6 +86,24 @@ Using [benchmark-http2.js](https://github.com/nodejs/undici/blob/main/benchmarks Node.js includes a built-in `fetch()` implementation powered by undici starting from Node.js v18. However, there are important differences between using the built-in fetch and installing undici as a separate module. +### WebAssembly requirement + +Undici's HTTP/1 parser requires WebAssembly. There is no alternative parser when +WebAssembly is unavailable, for example in Node.js configurations where +`--jitless` disables it. The existence of `fetch` does not imply that it can make +HTTP/1 requests in that environment. + +When the HTTP/1 parser is needed without WebAssembly, Client and dispatcher +requests fail with an `Error` whose code is `ERR_WEBASSEMBLY_NOT_SUPPORTED`. +`fetch` rejects with a `TypeError` carrying that error in `error.cause`. Importing +Undici, accessing `fetch`, and using `Headers`, `FormData`, `Request`, or `Response` +do not themselves require the HTTP/1 parser. + +The error is defined locally in Undici and does not depend on Node.js providing +that error code. For built-in fetch, this behavior depends on the bundled Undici +version. Node.js receives upstream fixes through its normal vendored Undici +update, rather than changes to the generated bundle alone. + ### Built-in Fetch (Node.js v18+) Node.js's built-in fetch is powered by a bundled version of undici: diff --git a/docs/docs/api/Errors.md b/docs/docs/api/Errors.md index c00729009f9..57ad0afa883 100644 --- a/docs/docs/api/Errors.md +++ b/docs/docs/api/Errors.md @@ -18,7 +18,7 @@ if (err instanceof errors.ConnectTimeoutError) { } ``` -All errors, except [`HTTPParserError`][], extend [`UndiciError`][]. Each error +All errors, except [`HTTPParserError`][] and `WebAssemblyNotSupportedError`, extend [`UndiciError`][]. Each error carries a stable `code` string (for example `UND_ERR_CONNECT_TIMEOUT`) and a `name`. @@ -52,6 +52,35 @@ on a well-known symbol rather than the prototype chain. * `name` {string} Always `'UndiciError'`. * `code` {string} Always `'UND_ERR'`. +## Class: `WebAssemblyNotSupportedError` + +* Extends: {Error} + +WebAssembly is unavailable when Undici initializes its HTTP/1 parser. Undici does +not provide an alternative parser for environments without WebAssembly, including +Node.js configurations where `--jitless` disables it. The check is performed when +the parser is needed, not when importing Undici or accessing `fetch`. + +* `name` {string} Always `'Error'`. +* `code` {string} Always `'ERR_WEBASSEMBLY_NOT_SUPPORTED'`. +* `message` {string} By default `'WebAssembly is not supported in this environment, but is required for HTTP/1 parsing'`. + +Client and dispatcher requests report this error directly. `fetch` rejects with +a `TypeError` whose `cause` is this error: + +```js +try { + await fetch('http://localhost:3000') +} catch (error) { + if (error.cause?.code === 'ERR_WEBASSEMBLY_NOT_SUPPORTED') { + // HTTP/1 parsing requires WebAssembly in this environment. + } +} +``` + +`Headers`, `FormData`, `Request`, `Response`, and other operations that do not need +the HTTP/1 parser remain usable without WebAssembly. + ## Class: `ConnectTimeoutError`