Fetch

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 Fetch Standard 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 Fetch Standard 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, Streams, and URL Standards. [ABNF] [ENCODING] [HTML] [HTTP][WEBIDL] [STREAMS] [URL] ABNF

means ABNF as modified by HTTP (in particular the addition #). Comparing two byte sequences in a byte-case-insensitive manner means comparing them exactly, byte for byte, except that the bytes in the range 0x41 to 0x5A, inclusive, are considered to also match their corresponding byte in the range 0x61 to 0x7A, inclusive.

A case-insensitive byte sequence is a byte sequence that when compared to another byte sequence does so in a byte-case-insensitive manner.

The case-insensitive byte sequences `Content-Type` and `content-TYPE` are equal.

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.

Credentials are HTTP cookies, TLS client certificates, and authentication entries.

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:

1. If request’s client is null, terminate these steps.

2. 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.

2.1. 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).

The HTTP whitespace bytes are 0x09, 0x0A, 0x0D, and 0x20.

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 cypher 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.

2.1.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 APIs as methods are actually "case-sensitive".

Using `patch` is highly likely to result in a `405 Method Not Allowed`. `PATCH` is much more likely to succeed.

There are no restrictions on methods. `CHICKEN` is perfectly acceptable (and not a misspelling of `CHECKIN`). Other than those that are normalized there are no casing restrictions either. `Egg` or `eGg` would be fine, though uppercase is encouraged for consistency.

2.1.2. Headers

A header list consists of zero or more headers.

A header list is essentially a specialized multimap. An ordered list of key-value pairs with potentially duplicate keys.

A header list (list) contains a name (name) if list contains a header whose name is a byte-case-insensitive match for name. To append a name/value (name/value) pair to a header list (list), run these steps:

append a new header whose name is name, byte-lowercased, and value is value, to list.

To delete a name (name) from a header list (list), remove all headers whose name is

name, byte-

lowercased, from list.

To set a name/value (name/value) pair in a header list (list), run these steps:

1. Byte-lowercase name.

2. If there are any headers in list

   contains

   whose name is name,

   then

   set the value of the first such header to value and remove the others.

3. Otherwise, append a new header whose name is name and value is value, to list.

To combine a name/value (name/value) pair in a header list (list), run these steps:

1. Byte-lowercase name.

2. If there are any headers in list

   contains

   whose name is name,

   then

   set the value of the first such header to its value, followed by `,`, followed by value.

3. Otherwise, append a new header whose name is name and value is value, to list.

Combine is used by XMLHttpRequest and the WebSocket protocol handshake.

To sort and combine a header list (list), run these steps:

1. Let headers be an empty list of name-value pairs with the key being the name and value the value.

2. Let names be all the names of the headers in list,

   byte-lowercased,

   with duplicates removed, and

   finally

   sorted lexicographically.

3. For each name in names, run these substeps:

   1. Let value be the combined value given name and list.

   2. Append name-value to headers.

4. Return headers.

A header consists of a name and value.

A name is a case-insensitive byte sequence that matches the field-name token production.

A value is a byte sequence that matches the following conditions:

• Has no leading or trailing HTTP whitespace bytes.

• Contains no 0x00, 0x0A or 0x0D bytes.

The definition of value is not defined in terms of an HTTP token production as it is broken.

To normalize a potentialValue, remove any leading and trailing HTTP whitespace bytes from potentialValue.

A combined value, given a name (name) and header list (list), is the values of all headers in list whose name is

name, separated from each other by `,`, in order.

A CORS-safelisted request-header is a header whose name is

one of

• `Accept`
• `Accept-Language`
• `Content-Language`
• `Content-Type` and whose value, once

• parsed, has a MIME type (ignoring parameters) that is `application/x-www-form-urlencoded`, `multipart/form-data`, or `text/plain`

or whose name is

one of

• `DPR`
• `Downlink`
• `Save-Data`
• `Viewport-Width`
• `Width`

and whose value, once

parsed, is not a failure.

A CORS non-wildcard request-header name is

`Authorization`.

A CORS-safelisted response-header name, given a CORS-exposed header-name list list, is a header name that is

one of

• `Cache-Control`
• `Content-Language`
• `Content-Type`
• `Expires`
• `Last-Modified`
• `Pragma`
• Any value in list that is not a forbidden response-header name.

A forbidden header name is a header name that is

one of

• `Accept-Charset`
• `Accept-Encoding`
• `Access-Control-Request-Headers`
• `Access-Control-Request-Method`
• `Connection`
• `Content-Length`
• `Cookie`
• `Cookie2`
• `Date`
• `DNT`
• `Expect`
• `Host`
• `Keep-Alive`
• `Origin`
• `Referer`
• `TE`
• `Trailer`
• `Transfer-Encoding`
• `Upgrade`
• `Via`

or a header name that starts with

`Proxy-` or `Sec-` (including being

just `Proxy-` or `Sec-`).

These are forbidden so the user agent remains in full control over them. Names starting with `Sec-` are reserved to allow new headers to be minted that are safe from APIs using fetch that allow control over headers by developers, such as XMLHttpRequest. [XHR]

A forbidden response-header name is a header name that is

one of:

• `Set-Cookie`
• `Set-Cookie2`

To

parse a header

value

given a name (name) and a header or a header list (

headers), run these steps:

1. If

   list does not contain name, then

   name is not in headers, return null.

2. If the ABNF for name allows a single header and

   list

   headers contains more than one,

   then

   return failure.

   If different error handling is needed, extract the desired header first.

3. Let values be an empty list.

4. For each header header list contains whose name is name, run these substeps:

   1. Let extract be the result of extracting header values from header.

   2. If extract is failure, then return failure.

   3. Append each value in extract, in order, to values.

5. Return values.

6. If parsing all the headers named name in headers, per the ABNF for name, failed, return failure.

7. Return one or more values resulting from parsing all the headers named name in headers, per the ABNF for name.

To extract a MIME type from a header list (headers), run these steps:

1. Let MIMEType be the result of

   extracting header list values given

   parsing `Content-Type`

   and

   in headers.

2. If MIMEType is null or failure, return the empty byte sequence.

3. Return MIMEType, byte-lowercased.

A default `User-Agent` value is a user-agent-defined value for the `User-Agent` header.

2.1.3. Statuses

A status is a code.

A null body status is a status that is 101, 204, 205, or 304.

An ok status is any status in the range 200 to 299, inclusive.

A redirect status is a status that is 301, 302, 303, 307, or 308.

2.1.4. Bodies

A body consists of:

• A stream (null or a ReadableStream object).

• A transmitted bytes (an integer), initially 0.

• A total bytes (an integer), initially 0.

• A source, initially null.

A body body is said to be done if body is null or body’s stream is closed or errored.

To wait for a body body, wait for body to be done.

To clone a body body, run these steps:

1. Let «out1, out2» be the result of teeing body’s stream. Rethrow any exceptions.

2. Set body’s stream to out1.

3. Return a body whose stream is out2 and other members are copied from body.

To handle content codings given codings and bytes, run these substeps:

1. If codings are not supported, return bytes.

2. Return the result of decoding bytes with the given codings as explained in HTTP. [HTTP] [HTTP-SEMANTICS] [HTTP-COND] [HTTP-CACHING] [HTTP-AUTH]

2.1.5. Requests

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 sandboxed-storage-area-URLs flag. Unless stated otherwise it is unset.

A request has an associated header list (a header list). Unless stated otherwise it is empty.

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 header names.

A request has an associated body (null or a body). Unless stated otherwise it is null.

This can be updated during redirects to null as described in HTTP fetch.

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 target client id (a string). Unless stated otherwise it is the empty string.

This is only used by navigation requests. It is the id of the target browsing context’s active document’s environment settings object.

A request has an associated window ("no-window", "client", or an environment settings object whose global object is a Window object). Unless stated otherwise it is "client".

The "client" value is changed to "no-window" or request’s client during fetching. It provides a convenient way for standards to not have to explicitly set request’s window.

A request has an associated keepalive flag. Unless stated otherwise it is unset.

This can be used to allow the request to outlive the environment settings object, e.g., navigator.sendBeacon and the HTML img element set this flag. Requests with this flag set are subject to additional processing requirements.

A request has an associated skip-service-

worker flag. Unless stated otherwise it is

unset.

A request has an associated initiator, which is the empty string, "download", "imageset", "manifest", or "xslt". Unless stated otherwise it is the empty string.

A request’s initiator is not particularly granular for the time being as other specifications do not require it to. It is primarily a specification device to assist defining CSP and Mixed Content. It is not exposed to JavaScript. [CSP] [MIX]

A request has an associated type, which is the empty string, "audio", "font", "image", "script", "style", "track", or "video". Unless stated otherwise it is the empty string.

A request has an associated destination, which is the empty string, "

document", "embed", "font", "image", "manifest", "media", "object", "report", "script", "serviceworker", "sharedworker", "style", "

worker", or "xslt". Unless stated otherwise it is the empty string.

A request has an associated priority (null or a user-agent-defined object). Unless otherwise stated it is null.

A request has an associated origin, which is "client" or an origin. Unless stated otherwise it is "client".

"client" is changed to an origin during fetching. It provides a convenient way for standards to not have to set request’s origin. Request’s origin can be changed during redirects too.

A request has an associated referrer, which is "no-referrer", "client", or a URL. Unless stated otherwise it is "client".

"client" is changed to "no-referrer" or a URL during fetching. It provides a convenient way for standards to not have to set request’s referrer.

A request has an associated referrer policy, which is a referrer policy. Unless stated otherwise it is the empty string. [REFERRER]

This can be used to override a referrer policy associated with an environment settings object.

A request has an associated client hints list, which is a client-hints list. Unless stated otherwise, it is the empty list.

This will be used to override a client hints list associated with an environment settings object. [CLIENT-HINTS]

A request has an associated synchronous flag. Unless stated otherwise it is unset.

A request has an associated mode, which is "same-origin", "cors", "no-cors", "navigate", or "websocket". Unless stated otherwise, it is "no-cors".

Even though the default request mode is "no-cors", standards are highly discouraged from using it for new features. It is rather unsafe. "navigate" and "websocket" are special values for the HTML Standard. [HTML]

A request has an associated use-CORS-preflight flag. Unless stated otherwise, it is unset.

A request has an associated credentials mode, which is "omit", "same-origin", or "include". Unless stated otherwise, it is "omit".

Request’s credentials mode controls the flow of credentials during a fetch. When request’s mode is "navigate", its credentials mode is assumed to be "include" and fetch does not currently account for other values. If HTML changes here, this standard will need corresponding changes.

A request has an associated use-URL-credentials flag. Unless stated otherwise, it is unset.

A request has an associated use-token-binding flag. Unless stated otherwise, it is unset.

Request’s use-token-binding flag controls whether the user agent will send the token binding ID for the origin of the request’s url when it transmits the request to the server. The token binding ID can be used by the server to, e.g., bind HTTP cookies or OAuth tokens that it issues to the user agent.

A request has an associated use-referred-token-binding flag. Unless stated otherwise, it is unset.

Request’s use-referred-token-binding flag controls whether the user agent will send the token binding ID used by the user agent for an alternate origin, in addition to the token binding ID used by the user agent for the origin of the request’s url, when it transmits the request to the server. This is used, e.g., by a relying party to indicate (via the user agent) to the server receiving the request that it wants the credential issued by the server to be bound to the token binding ID for the relying party’s origin. (Without this, a credential issued by the server in response to a request would be bound to request’s origin’s token binding ID).

A request has an associated referred-token-binding origin, which is an origin. Unless stated otherwise, it is null.

Request’s referred-token-binding origin specifies the origin used to determine the referred-token-binding ID, when its use-referred-token-binding flag is set.

A request has an associated cache mode, which is "default", "no-store", "reload", "no-cache", "force-cache", or "only-if-cached". Unless stated otherwise, it is "default".

A request has an associated redirect mode, which is "follow", "error", or "manual". Unless stated otherwise, it is "follow".

A request has associated integrity metadata (a string). Unless stated otherwise, it is the empty string.

A request has associated cryptographic nonce metadata (a string). Unless stated otherwise, it is the empty string.

A request has associated parser metadata which is the empty string, "parser-inserted", or "not-parser-inserted". Unless otherwise stated, it is the empty string.

A request’s cryptographic nonce metadata and parser metadata are generally populated from attributes and flags on the HTML element responsible for triggering a fetch. They are used by various algorithms in [CSP] to determine whether requests or responses should be blocked in a given context.

A request has an associated url list (a list of one or more URLs). Unless stated otherwise, it is a list containing a copy of request’s url.

A request has an associated current url. It is a pointer to the last URL in request’s url list.

A request has an associated redirect count. Unless stated otherwise, it is zero.

A request has an associated response tainting, which is "basic", "cors", or "opaque". Unless stated otherwise, it is "basic".

A request has an associated done flag. Unless stated otherwise, it is unset.

A request’s url list, current url, redirect count, response tainting, and done flag are used as bookkeeping details by the fetch algorithm.

A subresource request is a request whose destination is "

font", "image", "manifest", "

media", "

script", "

style", "

xslt", or the empty string.

A potential-navigation-or-subresource request is a request whose destination is "object" or "embed".

A non-subresource request is a request whose destination is "document", "report", "serviceworker", "sharedworker", or "worker".

A navigation request is a request whose destination is "document".

See handle fetch for usage of these terms. [SW]

To clone a request request, run these steps:

1. Let newRequest be a copy of request, except for its body.

2. If request’s body is non-null, set newRequest’s body to the result of cloning request’s body. Rethrow any exceptions.

3. Return newRequest.

To transmit body for a request request, run these steps:

1. Let body be request’s body.

2. If body is null, then queue a fetch task on request to process request end-of-body for request and abort these steps.

3. Let read be the result of reading a chunk from body’s stream.

   • When read is fulfilled with an object whose done property is false and whose value property is a Uint8Array object, run these substeps:

     1. Let bytes be the byte sequence represented by the Uint8Array object.

     2. Transmit bytes.

     3. Increase body’s transmitted bytes by bytes’s length.

     4. Run the above step again.

   • When read is fulfilled with an object whose done property is true, queue a fetch task on request to process request end-of-body for request.

   • When read is fulfilled with a value that matches with neither of the above patterns, or read is rejected, terminate the ongoing fetch with reason fatal.

2.1.6. Responses

The result of fetch is a response. A response evolves over time. That is, not all its fields are available straight away.

A response has an associated type which is "basic", "cors", "default", "error", "opaque", or "opaqueredirect". Unless stated otherwise, it is "default".

A response can have an associated termination reason which is end-user abort, fatal, or timeout.

A response has an associated url. It is a pointer to the last response URL in response’s url list and null if response’s url list is the empty list.

A response has an associated url list (a list of zero or more response URLs). Unless stated otherwise, it is the empty list.

Except for the last response URL, if any, a response’s url list cannot be exposed to script. That would violate atomic HTTP redirect handling.

A response has an associated status, which is a status. Unless stated otherwise it is 200.

A response has an associated status message. Unless stated otherwise it is `OK`.

A response has an associated header list (a header list). Unless stated otherwise it is empty.

A response has an associated body (null or a body). Unless stated otherwise it is null.

A response has an associated trailer (a header list). Unless stated otherwise it is empty.

A response has an associated HTTPS state (an HTTPS state value). Unless stated otherwise, it is "none".

A response has an associated CSP list, which is a list of Content Security Policy objects for the response. The list is empty unless otherwise specified. [CSP]

A response has an associated CORS-exposed header-name list (a list of zero or more header names). The list is empty unless otherwise specified.

A response will typically get its CORS-exposed header-name list set by

parsing the `Access-Control-Expose-Headers` header. This list is used by a CORS filtered response to determine which headers to expose.

A response can have an associated location URL (null, failure, or a URL). Unless specified otherwise, response has no location URL.

This concept is used for redirect handling in Fetch and in HTML’s navigate algorithm. It ensures `Location`

is parsed consistently and only once. [HTML]

A response whose type is "error" is known as a network error.

A network error is a response whose status is always 0, status message is always the empty byte sequence, header list is always empty, body is always null, and trailer is always empty.

A filtered response is a limited view on a response that is not a network error. This response is referred to as the filtered response’s associated internal response.

The fetch algorithm returns such a view to ensure APIs do not accidentally leak information. If the information is required, e.g., to feed image data to a decoder, the associated internal response can be used, which is only "accessible" to internal specification algorithms.

A basic filtered response is a filtered response whose type is "basic" and header list excludes any headers in internal response’s header list whose name is a forbidden response-header name.

A CORS filtered response is a filtered response whose type is "cors", header list excludes any headers in internal response’s header list whose name is not a CORS-safelisted response-header name, given internal response’s CORS-exposed header-name list, and trailer is empty.

An opaque filtered response is a filtered response whose type is "opaque", url list is the empty list, status is 0, status message is the empty byte sequence, header list is empty, body is null, and trailer is empty.

An opaque-redirect filtered response is a filtered response whose type is "opaqueredirect", status is 0, status message is the empty byte sequence, header list is empty, body is null, and trailer is empty.

To clone a response response, run these steps:

1. If response is a filtered response, return a new identical filtered response whose internal response is a clone of response’s internal response. Rethrow any exceptions.

2. Let newResponse be a copy of response, except for its body.

3. If response’s body is non-null, set newResponse’s body to the result of cloning response’s body. Rethrow any exceptions.

4. Return newResponse.

2.2. Authentication entries

An authentication entry and a proxy-authentication entry are tuples of username, password, and realm, associated with one or more requests.

User agents should allow both to be cleared together with HTTP cookies and similar tracking functionality.

Further details are defined by HTTP. [HTTP] [HTTP-SEMANTICS] [HTTP-COND] [HTTP-CACHING] [HTTP-AUTH]

2.3. Fetch groups

Each environment settings object has an associated fetch group.

A fetch group holds an ordered list of fetch records.

A fetch record has an associated request (a request).

A fetch record has an associated fetch (a fetch algorithm or null).

When a fetch group is terminated, for each associated fetch record whose request’s done flag or keepalive flag is unset, terminate the fetch record’s fetch with reason fatal.

2.4. Connections

A user agent has an associated connection pool. A connection pool consists of zero or more connections. Each connection is identified by an origin (an origin) and credentials (a boolean).

2.4.1. HTTP/2 Connection Reuse

HTTP/2 allows connections to be reused for multiple origin servers, as described in Section 9.1 of HTTP/2. [HTTP2]

HTTPS connections can be reused for a request if the TLS certificate for the connection is valid for the host in the URI. This happens when the certificate has multiple "subjectAltName" attributes or names with wildcards, one of which is valid for the authority in the URI.

2.4.2. Obtaining a Connection

To obtain a connection, given an origin and credentials, run these steps:

1. If connection pool contains a connection whose origin is origin or whose origin is authoritative for origin, and credentials is credentials, return that connection.

2. Let connection be the result of establishing an HTTP connection to origin. [HTTP] [HTTP2] [HTTP-SEMANTICS] [HTTP-COND] [HTTP-CACHING] [HTTP-AUTH] [TLS]

   If credentials is true and if the user agent supports Token Binding, propose the use of Token Binding while setting up a TLS connection by sending the highest supported Token Binding protocol version and supported cryptographic algorithms and parameters (the token-binding key parameters) in a token_binding Client Hello Extension, as described in section 2 of the Token Binding Negotiation spec [TOKBIND-NEGOTIATION]. If Token Binding Negotiation succeeds, indicating client-server agreement on protocol version and token-binding key parameters, update metadata for the TLS connection with the results of the negotiation.

   The user agent will use Token Binding for any request sent over a TLS connection for which Token Binding Negotiation was successful. Since Token Binding is used only when credentials is true, such a connection will not be pooled with connections that have credentials is false. Also, Token Binding is compatible with connection reuse - HTTP/2 requests to different origin servers coalesced over the same connection will use different token-binding keys if needed.

   If credentials is false, do not send a TLS client certificate.

   If establishing a connection does not succeed (e.g., a DNS, TCP, or TLS error), return failure.

3. Add connection to the connection pool with origin being origin and credentials being credentials.

4. Return connection.

This is intentionally a little vague as the finer points are still evolving. Describing this helps explain the <link rel=preconnect> feature and clearly stipulates that connections are keyed on credentials. The latter clarifies that e.g., TLS session identifiers are not reused across connections whose credentials are false with connections whose credentials are true.

2.5. Port blocking

To determine whether fetching a request request should be blocked due to a bad port, run these steps:

1. Let url be request’s current url.

2. Let scheme be url’s scheme.

3. Let port be url’s port.

4. If scheme is "ftp" and port is 20 or 21, then return allowed.

5. Otherwise, if scheme is a network scheme and port is a bad port, then return blocked.

6. Return allowed.

A port is a bad port if it is listed in the first column of the following table.

2.6. Should response to request be blocked due to its MIME type?

Run these steps:

1. Let MIMEType be the result of extracting a MIME type from response’s header list.

2. Let type be request’s type.

3. If type is "script" and one of the following is true, then return blocked:

   • MIMEType starts with `audio/`, `image/`, or `video/`.
   • MIMEType is `text/csv`.

4. Return allowed.

2.7. Client hints list

This section will be integrated into HTTP Client Hints. [CLIENT-HINTS]

A client hints list is a list of Client hint tokens, each of which is one of `dpr`, `save-data`, `viewport-width`, or `width`.

2.8. Streams

This section might be integrated into other standards, such as IDL.

2.8.1. ReadableStream

A ReadableStream object represents a stream of data. In this section, we define common operations for ReadableStream objects. [STREAMS]

To enqueue chunk into a ReadableStream object stream, run these steps:

1. Call ReadableStreamDefaultControllerEnqueue(stream.[[readableStreamController]], chunk). Rethrow any exceptions.

To close a ReadableStream object stream, run these steps:

1. Call ReadableStreamDefaultControllerClose(stream.[[readableStreamController]]). Rethrow any exceptions.

To error a ReadableStream object stream with given reason, run these steps:

1. Call ReadableStreamDefaultControllerError(stream.[[readableStreamController]]). reason). Rethrow any exceptions.

To construct a ReadableStream object with given strategy, pull action and cancel action, all of which are optional, run these steps:

1. Let init be a new object.

2. Set init["pull"] to a function that runs pull if pull is given.

3. Set init["cancel"] to a function that runs cancel if cancel is given.

4. Let stream be the result of calling the initial value of ReadableStream as constructor with init and strategy if given. Rethrow any exceptions.

5. Return stream.

To construct a fixed ReadableStream object with given chunks, run these steps:

1. Let stream be the result of constructing a ReadableStream object. Rethrow any exceptions.

2. For each chunk in chunks, enqueue chunk into stream. Rethrow any exceptions.

3. Close stream. Rethrow any exceptions.

4. Return stream.

To get a reader from a ReadableStream object stream, run these steps:

1. Let reader be the result of calling AcquireReadableStreamDefaultReader(stream). Rethrow any exceptions.

2. Return reader.

To read a chunk from a ReadableStream object with reader, return the result of calling ReadableStreamDefaultReaderRead(reader).

To read all bytes from a ReadableStream object with reader, run these steps:

1. Let promise be a new promise.

2. Let bytes be an empty byte sequence.

3. Let read be the result of calling ReadableStreamDefaultReaderRead(reader).

   • When read is fulfilled with an object whose done property is false and whose value property is a Uint8Array object, append the value property to bytes and run the above step again.

   • When read is fulfilled with an object whose done property is true, resolve promise with bytes.

   • When read is fulfilled with a value that matches with neither of the above patterns, reject promise with a TypeError.

   • When read is rejected with an error, reject promise with that error.

4. Return promise.

To cancel a ReadableStream object with reader and reason, return the result of calling ReadableStreamCancel(reader, reason).

Because the reader grants exclusive access, the actual mechanism of how to read cannot be observed. Implementations could use more direct mechanism if convenient.

To tee a ReadableStream object stream, run these steps:

1. Return the result of calling ReadableStreamTee(stream, true). Rethrow any exception.

An empty ReadableStream object is the result of constructing a fixed ReadableStream object with an empty list.

Constructing an empty ReadableStream object will not throw an exception.

A ReadableStream object stream is said to be readable if stream.[[state]] is "readable".

A ReadableStream object stream is said to be closed if stream.[[state]] is "closed".

A ReadableStream object stream is said to be errored if stream.[[state]] is "errored".

A ReadableStream object stream is said to be locked if the result of calling IsReadableStreamLocked(stream) is true.

A ReadableStream object stream is said to need more data if the following conditions hold:

• stream is readable.

• The result of calling ReadableStreamDefaultControllerGetDesiredSize(stream.[[readableStreamController]]). is positive.

A ReadableStream object stream is said to be disturbed if the result of calling IsReadableStreamDisturbed(stream) is true.

3. HTTP extensions

3.1. `Origin` header

The `Origin` request header indicates where a fetch originates from.

The `Origin` header is a version of the `Referer` [sic] header that does not reveal a path. It is used for all HTTP fetches whose CORS flag is set as well as those where request’s method is neither `GET` nor `HEAD`. Due to compatibility constraints it is not included in all fetches.

Its value ABNF:

Origin                           = origin-or-null

origin-or-null                   = origin / %x6E.75.6C.6C ; "null", case-sensitive
origin                           = scheme "://" host [ ":" port ]

This supplants the `Origin` header. [ORIGIN]

3.2. CORS protocol

To allow sharing responses cross-origin and allow for more versatile fetches than possible with HTML’s form element, the CORS protocol exists. It is layered on top of HTTP and allows responses to declare they can be shared with other origin.

It needs to be an opt-in mechanism to prevent leaking data from responses behind a firewall (intranets). Additionally, for requests including credentials it needs to be opt-in to prevent leaking potentially-sensitive data.

This section explains the CORS protocol as it pertains to server developers. Requirements for user agents are part of the fetch algorithm, except for the new HTTP header syntax.

3.2.1. General

The CORS protocol consists of a set of headers that indicates whether a response can be shared cross-origin.

For requests that are more involved than what is possible with HTML’s form element, a CORS-preflight request is performed, to ensure request’s current url supports the CORS protocol.

3.2.2. HTTP requests

A CORS request is an HTTP request that includes an `Origin` header. It cannot be reliably identified as participating in the CORS protocol as the `Origin` header is also included for all requests whose method is neither `GET` nor `HEAD`.

A CORS-preflight request is a CORS request that checks to see if the CORS protocol is understood. It uses `OPTIONS` as method and includes these headers:

`Access-Control-Request-Method`

Indicates which method a future CORS request to the same resource might use.

`Access-Control-Request-Headers`

Indicates which headers a future CORS request to the same resource might use.

3.2.3. HTTP responses

An HTTP response to a CORS request can include the following headers:

`Access-Control-Allow-Origin`

Indicates whether the response can be shared, via returning the literal value of the `Origin` request header (which can be `null`) or `*` in a response.

`Access-Control-Allow-Credentials`

Indicates whether the response can be shared when request’s credentials mode is "include".

For a CORS-preflight request, request’s credentials mode is always "omit", but for any subsequent CORS requests it might not be. Support therefore needs to be indicated as part of the HTTP response to the CORS-preflight request as well.

An HTTP response to a CORS-preflight request can include the following headers:

`Access-Control-Allow-Methods`

Indicates which methods are supported by the response’s url for the purposes of the CORS protocol.

The `Allow` header is not relevant for the purposes of the CORS protocol.

`Access-Control-Allow-Headers`

Indicates which headers are supported by the response’s url for the purposes of the CORS protocol.

`Access-Control-Max-Age`

Indicates how long the information provided by the `Access-Control-Allow-Methods` and `Access-Control-Allow-Headers` headers can be cached.

An HTTP response to a CORS request that is not a CORS-preflight request can also include the following header:

`Access-Control-Expose-Headers`

Indicates which headers can be exposed as part of the response by listing their names.

3.2.4. HTTP new-header syntax

ABNF for the values of the headers used by the CORS protocol:

Access-Control-Request-Method    = method
Access-Control-Request-Headers   = 1#field-name

wildcard                         = "*"
Access-Control-Allow-Origin      = origin-or-null / wildcard
Access-Control-Allow-Credentials = %x74.72.75.65 ; "true", case-sensitive
Access-Control-Expose-Headers    = #field-name / wildcard
Access-Control-Max-Age           = delta-seconds
Access-Control-Allow-Methods     = #method / wildcard
Access-Control-Allow-Headers     = #field-name-or-wildcard
field-name-or-wildcard           = field-name / wildcard

The difference between the Access-Control-Expose-Headers and Access-Control-Allow-Headers production is that the latter needs to be able to handle `*, Authorization` as header value whereas the former does not.

3.2.5. CORS protocol and credentials

When request’s credentials mode is "include" it has an impact on the functioning of the CORS protocol other than including credentials in the fetch.

var client = new XMLHttpRequest()
client.open("GET", "./")
client.withCredentials = true
/* … */

A request’s credentials mode is not necessarily observable on the server; only when credentials exist for a request can it be observed by virtue of the credentials being included. Note that even so, a CORS-preflight request never includes credentials.

The server developer therefore needs to decide whether or not responses "tainted" with credentials can be shared. And also needs to decide if requests necessitating a CORS-preflight request can include credentials. Generally speaking, both sharing responses and allowing requests with credentials is rather unsafe, and extreme care has to be taken to avoid the confused deputy problem.

To share responses with credentials, the `Access-Control-Allow-Origin` and `Access-Control-Allow-Credentials` headers are important. The following table serves to illustrate the various legal and illegal combinations for a request to https://rabbit.invalid/:

Similarly, `Access-Control-Expose-Headers`, `Access-Control-Allow-Methods`, and `Access-Control-Allow-Headers` response headers can only use `*` as value when request’s credentials mode is not "include".

3.2.6. Examples

var url = "https://bar.invalid/api?key=730d67a37d7f3d802e96396d00280768773813fbe726d116944d814422fc1a45&data=about:unicorn";
fetch(url).then(success, failure)

Origin: https://foo.invalid

fetch(url).then(response => {
  var hsts = response.headers.get("strict-transport-security"),
      csp = response.headers.get("content-security-policy")
  log(hsts, csp)
})

Content-Security-Policy: default-src 'self'
Strict-Transport-Security: max-age=31536000; includeSubdomains; preload
Access-Control-Expose-Headers: Content-Security-Policy

fetch(url, { credentials:"include" }).then(success, failure)

Access-Control-Allow-Origin: https://foo.invalid
Access-Control-Allow-Credentials: true

3.3. `X-Content-Type-Options` header

The `X-Content-Type-Options` response header can be used to require checking of a response’s `Content-Type` header against the type of a request.

Its value ABNF:

X-Content-Type-Options           = "nosniff" ; case-insensitive

3.3.1. Should response to request be blocked due to nosniff?

Run these steps:

1. If response’s header list

   does not contain

   has no header whose name is `X-Content-Type-Options`, then return allowed.

2. Let nosniff be the result of

   extracting header values from

   parsing the first header whose name is

   a byte-case-insensitive match for

   `X-Content-Type-Options` in response’s header list.

3. If nosniff is failure, then return allowed.

4. Let MIMEType be the result of extracting a MIME type from response’s header list.

5. Let type be request’s type.

6. If type is "script", and MIMEType (ignoring parameters) is not a JavaScript MIME type, then return blocked.

7. If type is "style" and MIMEType (ignoring parameters) is not `text/css`, then return blocked.

8. Return allowed.

Only "script" and "style" are considered as any exploits pertain to those types. Also, considering "image" was not compatible with deployed content.

3.4. Token Binding

In order to protect security tokens like HTTP cookies and OAuth tokens, user agents and servers can use a technique known as Token Binding to cryptographically associate a given token with a secret (a token-binding key) known only to a specific user agent. This association mitigates the risk that attackers can steal the token and use it themselves, as they will not be able to easily replicate the user agent’s secret, and therefore cannot replicate the cryptographic binding of the token.

Details are described in TOKBIND-NEGOTIATION, TOKBIND-PROTOCOL and TOKBIND-HTTPS and integration is defined here. [TOKBIND-NEGOTIATION], [TOKBIND-PROTOCOL], and [TOKBIND-HTTPS].

A token binding ID is the non-secret representation of a token-binding key, as described in section 3.2 of [TOKBIND-PROTOCOL].

At a very high level, a user agent negotiates the use of Token Binding with the server when it sets up a TLS connection to the server, and saves metadata (the Token Binding protocol version and token-binding key parameters resulting from the Token Binding negotiation) for the TLS connection. The user agent maintains a token-binding key store, where it saves different token-binding keys to be used with different servers. Whenever a token-binding key is needed, the user agent looks it up in the token-binding key store (creating it if needed).

The user agent uses a `Sec-Token-Binding` HTTP request header to transmit token binding metadata to the server. When a user agent sends a request to a server over a TLS connection for which Token Binding has been negotiated, it proves possession of the private key via data sent in the `Sec-Token-Binding` header. The server associates ('binds') credentials that it issues to that user agent with a token binding ID in that header. The server also verifies if bound credentials presented to it by a user agent match a token binding ID in that header.

The value of the `Sec-Token-Binding` header is a base64url-encoded string [RFC4648]:

Sec-Token-Binding       = 1*( ALPHA / DIGIT / "-" / "_" ) *2( "=" )

The data in a `Sec-Token-Binding` header is a Token Binding Message as specified in section 2 of the Token Binding over HTTP spec [TOKBIND-HTTPS]. A token binding message is a list of token bindings, where each token binding consists of a token binding ID, a token binding type and a cryptographic signature.

3.4.1. Federated Token Binding

In the scenario described above, servers bind tokens to be used by user agents with those servers. To enable existing web authorization protocols to use bound credentials, there is a need to support scenarios where bound credentials issued by one server (e.g., an identity provider) are presented by the user agent to a different server (e.g., a relying party). [TOKBIND-PROTOCOL] and [TOKBIND-HTTPS] describe support for Federated Token Binding.

A referred-token-binding ID is the token binding ID for a server other than the server to which the request is being sent.

Script code from an origin can set a request’s use-referred-token-binding flag to ask the user agent to send the token binding ID for that origin as a referred-token-binding ID in the Token Binding Message sent to a target server.

Alternately, servers that redirect a user agent to a different server can use the `Include-Referred-Token-Binding-ID` header.

Include-Referred-Token-Binding-ID = %x74.72.75.65 ; "true", case-sensitive

The value of this header is specified in section 5.3 of the Token Binding over HTTP spec [TOKBIND-HTTPS].

By setting the `Include-Referred-Token-Binding-ID` header to `true` in the redirect response, the origin that sends the redirect response (the "referring origin" in the Token Binding sense) tells the user agent to disclose the token binding ID used by the user agent for that origin to the target origin. The user agent does this while processing the `Include-Referred-Token-Binding-ID` header in the redirect response, by adding a referred-token-binding ID in the Token Binding Message that is created when the request is sent to the target server.

3.4.2. Getting a Token Binding Key

Get the token-binding key for an origin tokenBindingOrigin and token-binding key parameters tokenBindingKeyParameters, using the user agent’s token-binding key store, by running these substeps:

1. Let keyDomainName be null.

2. If tokenBindingOrigin’s host is an IP address, set keyDomainName to tokenBindingOrigin’s host.

   Otherwise, set keyDomainName to the registrable domain of tokenBindingOrigin’s host, determined by running the steps in the Algorithm section of Public Suffix List [PUBLIC-SUFFIX]

3. Let tokenBindingKeyPair be null.

4. Set tokenBindingKeyPair to the result of looking up the token-binding key pair for keyDomainName in the token-binding key store.

5. If tokenBindingKeyPair is null, create a new key pair for keyDomainName using tokenBindingKeyParameters, save it in the token-binding key store, and set tokenBindingKeyPair to that new key pair.

6. Return tokenBindingKeyPair.

3.4.3. Computing a Token Binding Header Value

If the user agent supports Token Binding, build the value that can be passed in a `Sec-Token-Binding` header for a request httpRequest and a connection tlsConnection, using the token-binding key store and the connection pool, by running these substeps:

1. If httpRequest’s use-token-binding flag is not set, then return null.

2. Initialize tokenBindingMessage to null.

3. If Token Binding was not negotiated for tlsConnection, return null.

4. Let providedTokenBindingKeyPair be the result of getting the token-binding key for the origin of httpRequest’s current url and tlsConnection’s token-binding key parameters metadata, obtained by following the steps in the Getting a Token Binding Key section of this document.

5. Let providedTokenBindingId be the result of computing a token binding ID from providedTokenBindingKeyPair, as described in section 3.2 of [TOKBIND-PROTOCOL].

6. Let providedTokenBinding be the result of computing a token binding using providedTokenBindingId and type provided_token_binding, containing a signature (using providedTokenBindingKeyPair) over the providedTokenBindingId as well as tlsConnection’s Exported Keying Material, as described in section 3.3 of [TOKBIND-PROTOCOL].

7. Set tokenBindingMessage to a list containing providedTokenBinding as the only token binding.

8. If httpRequest’s use-referred-token-binding flag is set, then run these substeps:

   1. Let referredTlsConnection be the result of getting a TLS connection for httpRequest’s referred-token-binding origin with credentials true from the connection pool.

   2. If Token Binding was not negotiated for referredTlsConnection, set referredTokenBinding to null.

   3. If Token Binding was negotiated for referredTlsConnection then:

      1. Let referredTokenBindingKeyPair be the result of getting the Token Binding key for httpRequest’s referred-token-binding origin and referredTlsConnection’s token-binding key parameters metadata, obtained by following the steps in the Getting a Token Binding Key section of this document.

      2. Let referredTokenBindingId be the result of computing a token binding ID from referredTokenBindingKeyPair, as described in section 3.2 of [TOKBIND-PROTOCOL].

      3. Let referredTokenBinding be the result of computing a token binding using referredTokenBindingId and type referred_token_binding, containing a signature (using referredTokenBindingKeyPair) over the referredTokenBindingId as well as tlsConnection’s Exported Keying Material, as described in section 3.3 of [TOKBIND-PROTOCOL].

   4. If referredTokenBinding is not null, add it to tokenBindingMessage.

9. If tokenBindingMessage is not null, compute and return its base64url-encoding [RFC4648]. Otherwise return null.

4. Fetching

To perform a fetch using request, run the steps below. An ongoing fetch can be terminated with reason reason, which must be end-user abort, fatal, timeout, or garbage collection.

The user agent may be asked to suspend the ongoing fetch. The user agent may either accept or ignore the suspension request. The suspended fetch can be resumed. The user agent should ignore the suspension request if the ongoing fetch is updating the response in the HTTP cache for the request.

The user agent does not update the entry in the HTTP cache for a request if request’s cache mode is "no-store" or a `Cache-Control: no-store` header appears in the response. [HTTP-CACHING]

1. If request’s window is "client", set request’s window to request’s client, if request’s client’s global object is a Window object, and to "no-window" otherwise.

2. If request’s origin is "client", set request’s origin to request’s client’s origin.

3. If request’s header list does not contain a header whose name is `Accept`,

   then

   run these substeps:

   1. Let value be `*/*`.

   2. If request is a navigation request, a user agent should set value to `text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8`.

   3. Otherwise, a user agent should set value to the first matching statement, if any, switching on request’s type:

      "image"

      `image/png,image/svg+xml,image/*;q=0.8,*/*;q=0.5`

      "style"

      `text/css,*/*;q=0.1`

   4. Append `Accept`/value to request’s header list.

4. If request’s header list does not contain a header whose name is `Accept-Language`, user agents should append `Accept-Language`/an appropriate value to request’s header list.

5. If request’s priority is null, use request’s initiator, type, and destination appropriately in setting it to a user-agent-defined object.

   The user-agent-defined object could encompass stream weight and dependency for HTTP/2, and equivalent information used to prioritize dispatch and processing of HTTP/1 fetches.

6. If request is a navigation request, a user agent should, for each header name (

   hintName

   hint-name) in the first column of the following table, if hint-name is not in request’s header list

   does not contain hintName

   ,

   then

   append

   hintName/the

   hint-name/hint-value given in the same row on the second column, to request’s header list.

   Name Value

   hint-name	hint-value
   `dpr`	a suitable dpr value
   `save-data`	a suitable save-data value
   `viewport-width`	a suitable viewport-width value

7. If request is a subresource request, run these substeps:

   1. If the request’s client hints list is not empty, then run these substeps for each

      hintName

      hint-name in the list:

      1. Set value to the first matching statement, if any, switching on

         hintName

         hint-name:

         "dpr"

         a suitable dpr value

         "save-data"

         a suitable save-data value

         "viewport-width"

         a suitable viewport-width value

         "width"

         a suitable width value

      2. Append

         hintName

         hint-name/value to request’s header list.

   2. Let record be a new fetch record consisting of request and this instance of the fetch algorithm.

   3. Append record to request’s client’s fetch group list of fetch records.

8. Return the result of performing a main fetch using request.