Skip to content

doc: document fetch() differences from the Fetch Standard #62236

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
kovan wants to merge 2 commits into
base: main
Choose a base branch
from
+36 −0
Open

doc: document fetch() differences from the Fetch Standard #62236

Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
0c51ed0
doc: document fetch() differences from the Fetch Standard
kovan Mar 13, 2026
bc825f9
doc: fix incorrect claim about Host header in fetch
kovan Mar 25, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
35 changes: 35 additions & 0 deletions doc/api/globals.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -586,6 +586,38 @@ import { setGlobalDispatcher } from 'undici';
setGlobalDispatcher(new MyAgent());
```

### Differences from the standard

The Node.js `fetch` implementation is based on [undici][] and runs in a
server-side environment, so it differs from browser-based Fetch
implementations in several ways:

* **No CORS enforcement.** Browsers restrict cross-origin requests via
[CORS][]. Node.js does not send preflight requests or validate
`Access-Control-Allow-Origin` headers, since server-side requests do
not have an origin. All cross-origin requests are allowed by default.
* **No forbidden headers.** The [Fetch Standard][] forbids setting
certain headers (such as `Cookie`, `Host`, and `Origin`) in browser
contexts. Node.js removes these restrictions, allowing full control
Copy link
Copy Markdown
Contributor

@bakkot bakkot Mar 25, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't think this is true? Not for Host anyway. nodejs/undici#2369

Copy link
Copy Markdown
Contributor Author

@kovan kovan Mar 25, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good catch, thanks. Host is unconditionally deleted by undici before dispatch (httpNetworkOrCacheFetch sets it from the URL). Updated the section to say "Fewer forbidden headers" and note the Host restriction specifically.

Copy link
Copy Markdown
Contributor

@bakkot bakkot Mar 25, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That's accurate but your commit message is wrong. The fix for the referenced CVE was about the host/cookie headers incorrectly carrying through redirects. The change to forbid setting Host on initial requests happened in nodejs/undici#2322 and was unrelated.

Incidentally, if you're using LLMs for any part of this, it's polite to disclose that.

Copy link
Copy Markdown
Contributor Author

@kovan kovan Mar 25, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You're right, thanks for the correction. The CVE was about headers leaking through cross-origin redirects, not about the initial request restriction. Updated the commit message to reference undici#2322 instead.

Re LLMs: yes, I use Claude Code as part of my workflow. Happy to add a note if there's a preferred format.

Copy link
Copy Markdown
Contributor

@bakkot bakkot Mar 25, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The usual thing is to add a line in the PR description describing what parts (of the code and also your comments) were done by the LLM vs you, and whether the correctness of the parts the LLM did is something you've reviewed and are qualified to review.

Copy link
Copy Markdown
Contributor Author

@kovan kovan Mar 25, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Updated the PR description with an AI disclosure section.

over all request headers.
* **`Response` accepts async iterables.** `new Response(body)` accepts
async iterables as the `body` argument. This is a Node.js extension
not present in the Fetch Standard.
* **Response bodies must be consumed.** In browsers, garbage collection
eventually releases unused response bodies. The Node.js garbage
collector is less aggressive, so not consuming or canceling response
bodies can lead to connection leaks. Always consume the body (e.g.,
with `response.text()` or `response.body.cancel()`) or use `HEAD`
requests when only headers are needed.
* **`Content-Encoding` layer limit.** Node.js limits the number of
`Content-Encoding` layers (e.g., nested gzip) in a response to 5, to
prevent resource exhaustion attacks. Browsers do not impose this
limit.
* **Manual redirect returns the actual response.** When the `redirect`
option is set to `"manual"`, Node.js returns the actual redirect
response. Browsers return a filtered response with type
`"opaqueredirect"` instead.

### Related classes

The following globals are available to use with `fetch`:
Expand Down Expand Up @@ -1344,9 +1376,11 @@ changes:

A browser-compatible implementation of [`WritableStreamDefaultWriter`][].

[CORS]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/CORS
[CommonJS module]: modules.md
[CommonJS modules]: modules.md
[ECMAScript module]: esm.md
[Fetch Standard]: https://fetch.spec.whatwg.org/
[Navigator API]: https://html.spec.whatwg.org/multipage/system-state.html#the-navigator-object
[RFC 5646]: https://www.rfc-editor.org/rfc/rfc5646.txt
[Web Crypto API]: webcrypto.md
Expand Down Expand Up @@ -1420,5 +1454,6 @@ A browser-compatible implementation of [`WritableStreamDefaultWriter`][].
[buffer section]: buffer.md
[built-in objects]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects
[timers]: timers.md
[undici]: https://undici.nodejs.org
[webassembly-mdn]: https://developer.mozilla.org/en-US/docs/WebAssembly
[webassembly-org]: https://webassembly.org