fetch.spec.whatwg.orgFetch Standard

Fetch Living Standard — Last Updated 16 January 2020 Participate: GitHub whatwg/fetch ( new issue , open issues ) IRC: #whatwg on Freenode 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 Connections 2.6 Port blocking 2.7 Should response to request be blocked due to its MIME type? 2.8 Streams 2.8.1 ReadableStream 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-Type ` header 3.4 ` X-Content-Type-Options ` header 3.4.1 Should response to request be blocked due to nosniff? 3.5 CORB 3.6 ` Cross-Origin-Resource-Policy ` 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 Body mixin 5.3 Request class 5.4 Response class 5.5 Fetch method 5.6 Garbage collection 6 WebSocket protocol alterations 6.1 Connections 6.2 Opening handshake 7 data: URLs Background reading HTTP header layer division Atomic HTTP redirect handling Basic safe CORS protocol setup CORS protocol and HTTP caches Acknowledgments Index Terms defined by this specification Terms defined by reference References Normative References Informative References IDL Index Goals To unify fetching across the web platform this specification supplants a number of algorithms and specifications: HTML Standard’s fetch and potentially CORS-enabled fetch algorithms [HTML] CORS [CORS] HTTP ` Origin ` header semantics [ORIGIN] Unifying fetching provides consistent handling of: URL schemes Redirects Cross-origin semantics CSP [CSP] Service workers [SW] Mixed Content [MIX] ` Referer ` [REFERRER] 1. Preface At a high level, fetching a resource is a fairly simple operation. A request goes in, a response comes out. The details of that operation are however quite involved and used to not be written down carefully and differ from one API to the next. Numerous APIs provide the ability to fetch a resource, e.g. HTML’s img and script element, CSS' cursor and list-style-image , the navigator.sendBeacon() and self.importScripts() JavaScript APIs. The provides a unified architecture for these features so they are all consistent when it comes to various aspects of fetching, such as redirects and the CORS protocol. The also defines the fetch() JavaScript API, which exposes most of the networking functionality at a fairly low level of abstraction. 2. Infrastructure This specification depends on the Infra Standard. [INFRA] This specification uses terminology from the ABNF, Encoding, HTML, HTTP, IDL, MIME Sniffing, Streams, and URL Standards. [ABNF] [ENCODING] [HTML] [HTTP] [WEBIDL] [MIMESNIFF] [STREAMS] [URL] ABNF means ABNF as augmented by HTTP (in particular the addition # ) and RFC 7405. [RFC7405] Credentials are HTTP cookies, TLS client certificates, and authentication entries (for HTTP authentication). [COOKIES] [TLS] [HTTP-AUTH] Tasks that are queued by this standard are annotated as one of: process request body process request end-of-body process response process response end-of-body process response done To queue a fetch task on request request to run an operation , run these steps: If request ’s client is null, terminate these steps. Queue a task to run an operation on request ’s client ’s responsible event loop using the networking task source . To queue a fetch-request-done task , given a request , queue a fetch task on request to process request end-of-body for request . To serialize an integer , represent it as a string of the shortest possible decimal number. This will be replaced by a more descriptive algorithm in Infra. See infra/201 . 2.1. URL A local scheme is a scheme that is " about ", " blob ", or " data ". A URL is local if its scheme is a local scheme . This definition is also used by Referrer Policy . [REFERRER] An HTTP(S) scheme is a scheme that is " http " or " https ". A network scheme is a scheme that is " ftp " or an HTTP(S) scheme . A fetch scheme is a scheme that is " about ", " blob ", " data ", " file ", or a network scheme . HTTP(S) scheme , network scheme , and fetch scheme are also used by HTML . [HTML] A response URL is a URL for which implementations need not store the fragment as it is never exposed. When serialized , the exclude fragment flag is set, meaning implementations can store the fragment nonetheless. 2.2. HTTP While fetching encompasses more than just HTTP, it borrows a number of concepts from HTTP and applies these to resources obtained via other means (e.g., data URLs). An HTTP tab or space is U+0009 TAB or U+0020 SPACE. HTTP whitespace is U+000A LF, U+000D CR, or an HTTP tab or space . HTTP whitespace is only useful for specific constructs that are reused outside the context of HTTP headers (e.g., MIME types ). For HTTP header values, using HTTP tab or space is preferred, and outside that context ASCII whitespace is preferred. Unlike ASCII whitespace this excludes U+000C FF. An HTTP newline byte is 0x0A (LF) or 0x0D (CR). An HTTP tab or space byte is 0x09 (HT) or 0x20 (SP). An HTTP whitespace byte is an HTTP newline byte or HTTP tab or space byte . An HTTPS state value is " none ", " deprecated ", or " modern ". A response delivered over HTTPS will typically have its HTTPS state set to " modern ". A user agent can use " deprecated " in a transition period. E.g., while removing support for a hash function, weak cipher suites, certificates for an "Internal Name", or certificates with an overly long validity period. How exactly a user agent can use " deprecated " is not defined by this specification. An environment settings object typically derives its HTTPS state from a response . To collect an HTTP quoted string from a string input , given a position variable position and optionally an extract-value flag , run these steps: Let positionStart be position . Let value be the empty string. Assert: the code point at position within input is U+0022 ("). Advance position by 1. While true: Append the result of collecting a sequence of code points that are not U+0022 (") or U+005C (\) from input , given position , to value . If position is past the end of input , then break . Let quoteOrBackslash be the code point at position within input . Advance position by 1. If quoteOrBackslash is U+005C (\), then: If position is past the end of input , then append U+005C (\) to value and break . Append the code point at position within input to value . Advance position by 1. Otherwise: Assert: quoteOrBackslash is U+0022 ("). Break . If the extract-value flag is set, then return value . Return the code points from positionStart to position , inclusive, within input . The extract-value flag argument makes this algorithm suitable for getting, decoding, and splitting and parse a MIME type , as well as other header value parsers that might need this. 2.2.1. Methods A method is a byte sequence that matches the method token production. A CORS-safelisted method is a method that is ` GET `, ` HEAD `, or ` POST `. A forbidden method is a method that is a byte-case-insensitive match for ` CONNECT `, ` TRACE `, or ` TRACK `. [HTTPVERBSEC1] , [HTTPVERBSEC2] , [HTTPVERBSEC3] To normalize a method , if it is a byte-case-insensitive match for ` DELETE `, ` GET `, ` HEAD `, ` OPTIONS `, ` POST `, or ` PUT `, byte-uppercase it. Normalization is done for backwards compatibility and consistency across AP...