fetch.spec.whatwg.orgFetch Standard

Fetch Living Standard — Last Updated 14 May 2024 Participate: GitHub whatwg/fetch ( new issue , open issues ) Chat on Matrix Commits: GitHub whatwg/fetch/commits Snapshot as of this commit @fetchstandard Tests: web-platform-tests fetch/ ( ongoing work ) Translations (non-normative) : 日本語 Abstract The Fetch standard defines requests, responses, and the process that binds them: fetching. Table of Contents Goals 1 Preface 2 Infrastructure 2.1 URL 2.2 HTTP 2.2.1 Methods 2.2.2 Headers 2.2.3 Statuses 2.2.4 Bodies 2.2.5 Requests 2.2.6 Responses 2.2.7 Miscellaneous 2.3 Authentication entries 2.4 Fetch groups 2.5 Resolving domains 2.6 Connections 2.7 Network partition keys 2.8 HTTP cache partitions 2.9 Port blocking 2.10 Should response to request be blocked due to its MIME type? 3 HTTP extensions 3.1 ` Origin ` header 3.2 CORS protocol 3.2.1 General 3.2.2 HTTP requests 3.2.3 HTTP responses 3.2.4 HTTP new-header syntax 3.2.5 CORS protocol and credentials 3.2.6 Examples 3.2.7 CORS protocol exceptions 3.3 ` Content-Length ` header 3.4 ` Content-Type ` header 3.5 ` X-Content-Type-Options ` header 3.5.1 Should response to request be blocked due to nosniff? 3.6 ` Cross-Origin-Resource-Policy ` header 3.7 ` Sec-Purpose ` header 4 Fetching 4.1 Main fetch 4.2 Scheme fetch 4.3 HTTP fetch 4.4 HTTP-redirect fetch 4.5 HTTP-network-or-cache fetch 4.6 HTTP-network fetch 4.7 CORS-preflight fetch 4.8 CORS-preflight cache 4.9 CORS check 4.10 TAO check 5 Fetch API 5.1 Headers class 5.2 BodyInit unions 5.3 Body mixin 5.4 Request class 5.5 Response class 5.6 Fetch method 5.7 Garbage collection 6 data: URLs Background reading HTTP header layer division Atomic HTTP redirect handling Basic safe CORS protocol setup CORS protocol and HTTP caches WebSockets Using fetch in other standards Setting up a request Invoking fetch and processing responses Manipulating an ongoing fetch Acknowledgments Intellectual property rights Index Terms defined by this specification Terms defined by reference References Normative References Informative References IDL Index Goals The goal is to unify fetching across the web platform and provide consistent handling of everything that involves, including: URL schemes Redirects Cross-origin semantics CSP [CSP] Fetch Metadata [FETCH-METADATA] Service workers [SW] Mixed Content [MIX]A null body status is a status that is 101, 103, 204, 205, or 304. An ok status is a status in the range 200 to 299, inclusive. A redirect status is a status that is 301, 302, 303, 307, or 308. 2.2.4. Bodies A body consists of: A stream (a ReadableStream object). A source (null, a byte sequence , a Blob object, or a FormData object), initially null. A length (null or an integer), initially null. To clone a body body , run these steps: Let « out1 , out2 » be the result of teeing body ’s stream . Set body ’s stream to out1 . Return a body whose stream is out2 and other members are copied from body . To get a byte sequence bytes as a body , return the body of the result of safely extracting bytes . To incrementally read a body body , given an algorithm processBodyChunk , an algorithm processEndOfBody , an algorithm processBodyError , and an optional null, parallel queue , or global object taskDestination (default null), run these steps. processBodyChunk must be an algorithm accepting a byte sequence . processEndOfBody must be an algorithm accepting no arguments. processBodyError must be an algorithm accepting an exception. If taskDestination is null, then set taskDestination to the result of starting a new parallel queue . Let reader be the result of getting a reader for body ’s stream . This operation will not throw an exception. Perform the incrementally-read loop given reader , taskDestination , processBodyChunk , processEndOfBody , and processBodyError . To perform the incrementally-read loop , given a ReadableStreamDefaultReader object reader , parallel queue or global object taskDestination , algorithm processBodyChunk , algorithm processEndOfBody , and algorithm processBodyError : Let readRequest be the following read request : chunk steps , given chunk Let continueAlgorithm be null. If chunk is not a Uint8Array object, then set continueAlgorithm to this step: run processBodyError given a TypeError . Otherwise: Let bytes be a copy of chunk . Implementations are strongly encouraged to use an implementation strategy that avoids this copy where possible. Set continueAlgorithm to these steps: Run processBodyChunk given bytes . Perform the incrementally-read loop given reader , taskDestination , processBodyChunk , processEndOfBody , and processBodyError . Queue a fetch task given continueAlgorithm and taskDestination . close steps Queue a fetch task given processEndOfBody and taskDestination . error steps , given e Queue a fetch task to run processBodyError given e , with taskDestination . Read a chunk from reader given readRequest . To fully read a body body , given an algorithm processBody , an algorithm processBodyError , and an optional null, parallel queue , or global object taskDestination (default null), run these steps. processBody must be an algorithm accepting a byte sequence . processBodyError must be an algorithm optionally accepting an exception . If taskDestination is null, then set taskDestination to the result of starting a new parallel queue . Let successSteps given a byte sequence bytes be to queue a fetch task to run processBody given bytes , with taskDestination . Let errorSteps optionally given an exception exception be to queue a fetch task to run processBodyError given exception , with taskDestination . Let reader be the result of getting a reader for body ’s stream . If that threw an exception, then run errorSteps with that exception and return. Read all bytes from reader , given successSteps and errorSteps . A body with type is a tuple that consists of a body (a body ) and a type (a header value or null). To handle content codings given codings and bytes , run these steps: If codings are not supported, then return bytes . Return the result of decoding bytes with codings as explained in HTTP, if decoding does not result in an error, and failure otherwise. [HTTP] 2.2.5. Requests This section documents how requests work in detail. To get started, see Setting up a request . The input to fetch is a request . A request has an associated method (a method ). Unless stated otherwise it is ` GET `. This can be updated during redirects to ` GET ` as described in HTTP fetch . A request has an associated URL (a URL ). Implementations are encouraged to make this a pointer to the first URL in request ’s URL list . It is provided as a distinct field solely for the convenience of other standards hooking into Fetch. A request has an associated local-URLs-only flag . Unless stated otherwise it is unset. A request has an associated header list (a header list ). Unless stated otherwise it is « ». A request has an associated unsafe-request flag . Unless stated otherwise it is unset. The unsafe-request flag is set by APIs such as fetch() and XMLHttpRequest to ensure a CORS-preflight fetch is done based on the supplied method and header list . It does not free an API from outlawing forbidden methods and forbidden request-headers . A request has an associated body (null, a byte sequence , or a body ). Unless stated otherwise it is null. A byte sequence will be safely extracted into a body early on in fetch . As part of HTTP fetch it is possible for this field to be set to null due to certain redirects. A request has an associated client (null or an environment settings object ). A request has an associated reserved client (null, an environment , or an environment settings object ). Unless stated otherwise it is null. This is only used by navigation requests and worker requests, but not service worker requests. It references an environment for a navigation request and an environment settings object for a worker request. A request has an associated replaces client id (a string)....