Fetch

Abstract

The Fetch standard defines requests, responses, and the process that binds them; fetching.

Table of Contents

1. Goals
2. 1 Conformance
3. 2 Infrastructure
   1. 2.1 HTTP
      1. 2.1.1 Methods
      2. 2.1.2 Headers
      3. 2.1.3 Bodies
      4. 2.1.4 Requests
      5. 2.1.5 Responses
   2. 2.2 Authentication entries
4. 3 HTTP extensions
   1. 3.1 `Origin` header
   2. 3.2 CORS protocol
      1. 3.2.1 General
      2. 3.2.2 HTTP requests
      3. 3.2.3 HTTP responses
      4. 3.2.4 HTTP new header syntax
5. 4 Fetching
   1. 4.1 Basic fetch
   2. 4.2 HTTP fetch
   3. 4.3 HTTP network or cache fetch
   4. 4.4 CORS preflight fetch
   5. 4.5 CORS preflight cache
   6. 4.6 CORS check
6. 5 Fetch API
   1. 5.1 Headers class
   2. 5.2 Body mixin
   3. 5.3 Request class
   4. 5.4 Response class
   5. 5.5 Structured cloning of Headers, Request, and Response objects
   6. 5.6 Fetch method
7. Background reading
   1. HTTP header layer division
   2. Atomic HTTP redirect handling
   3. Basic safe CORS protocol setup
   4. CORS protocol and HTTP caches
8. References
9. Acknowledgments

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 Conformance

All diagrams, examples, and notes in this specification are non-normative, as are all sections explicitly marked non-normative. Everything else in this specification is normative.

The key words "MUST", "MUST NOT", "REQUIRED", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in the normative parts of this specification are to be interpreted as described in RFC2119. For readability, these words do not appear in all uppercase letters in this specification. [RFC2119]

2 Infrastructure

This specification uses terminology from the Encoding, HTML, and URL Standards. [ENCODING] [HTML] [URL]

A byte sequence with bytes in the range 0x00 to 0x7F is represented as a utf-8 encoded string with code points in the range U+0000 to U+007F. To avoid confusion with an actual string backticks are used.

"true" is a string, while `true` is a byte sequence.

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 are considered to also match their corresponding byte in the range 0x61 to 0x7A.

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.

To byte lowercase a byte sequence, increase each byte it contains, in the range 0x41 to 0x5A, by 0x20.

To byte uppercase a byte sequence, subtract each byte it contains, in the range 0x61 to 0x7A, by 0x20.

To queue a fetch task on request request to run an operation, queue a task to run an operation on request's client's responsible event loop using the networking task source.

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

2.1.1 Methods

A method is a byte sequence that matches the Method token production.

A simple method is a method that is `GET`, `HEAD`, or `POST`.

A forbidden method is a method that is a byte case-insensitive match for one of `CONNECT`, `TRACE`, and `TRACK`. [HTTPVERBSEC]

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

2.1.2 Headers

A header list consists of zero or more headers.

To append a name/value (name/value) pair to a header list (list), 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 whose name is name, 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 whose name is name, set the value of the first such header to value, followed by 0x2C 0x20, followed by value.

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

Combine solely exists for XMLHttpRequest.

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 field-value token production and contains no 0x0A or 0x0D bytes.

Allowing 0x0A and 0x0D bytes can lead to reparsing issues.

A simple header is a header whose name is either one of `Accept`, `Accept-Language`, and `Content-Language`, or whose name is `Content-Type` and value, once parsed, has a MIME type (ignoring parameters) that is one of `application/x-www-form-urlencoded`, `multipart/form-data`, and `text/plain`.

A forbidden header name is a header name that either 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`
• `User-Agent`
• `Via`

or starts with `Proxy-` or `Sec-` (including when it is 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 either a header or a header list (headers), run these steps:

1. If name is not in headers, return null.

2. If the ABNF for name allows a single header and headers contains more than one, return failure.

   That if you require different error handling, you need to extract the desired header first.

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

4. 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 parsing `Content-Type` in headers.

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

3. Return MIMEType, byte lowercased.

2.1.3 Bodies

A body is a byte stream. It has an associated transmitted which is an integer and initially 0, length which is an integer and initially 0, and error flag which is initially unset.

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]

2.1.4 Requests

The input to fetch is a request.

A request has an associated method (a method). Unless stated otherwise it is `GET`.

A request has an associated url (a URL).

This is updated during redirects as described in HTTP fetch.

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.

A request has an associated client (an environment settings object).

A request has an associated skip service worker flag. Unless stated otherwise it is unset.

A request has an associated context, which is one of audio, beacon, cspreport, download, embed, eventsource, favicon, fetch, font, form, frame, hyperlink, iframe, image, imageset, import, internal, location, manifest, object, ping, plugin, prefetch, script, serviceworker, sharedworker, subresource, style, track, video, worker, xmlhttprequest, and xslt.

A request has an associated context frame type, which is one of auxiliary, top-level, nested, and none. Unless stated otherwise it is none.

Remove auxiliary? Not sure it is distinctive enough.

A request has an associated origin (an origin). Unless stated otherwise it is an opaque identifier.

A request has an associated force Origin header flag. Unless stated otherwise it is unset.

A request has an associated same-origin data URL flag. Unless stated otherwise it is unset.

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

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

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

A request has an associated mode, which is one of same-origin, no CORS, CORS, and CORS-with-forced-preflight. Unless stated otherwise, it is no CORS.

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

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

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

If header list contains a header whose name is one of `If-Modified-Since`, `If-None-Match`, `If-Unmodified-Since`, `If-Match`, and `If-Range`, fetch will set cache mode to no-store if it is default.

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

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

A request has an associated response tainting, which is one of basic, CORS, and opaque. Unless stated otherwise, it is basic.

A request's redirect count and response tainting are used as bookkeeping details by the fetch algorithm.

2.1.5 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 one of basic, CORS, default, error, and opaque. Unless stated otherwise, it is default.

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

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

A response has an associated 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 cache state which is one of none, local, validated, and partial. Unless stated otherwise, it is none.

A response has an associated TLS state which is one of unauthenticated, deprecated authentication, and authenticated. Unless stated otherwise, it is unauthenticated.

A response delivered over TLS will typically have its TLS state set to authenticated.

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 aways empty, body is always null, and cache state is always none.

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, header list excludes any headers in internal response's header list whose name is `Set-Cookie` or `Set-Cookie2`.

A CORS filtered response is a filtered response whose type is CORS, header list excludes all headers in internal response's header list, except those whose name is either one of `Cache-Control`, `Content-Language`, `Content-Type`, `Expires`, `Last-Modified`, and `Pragma`, and except those whose name is one of the values resulting from parsing `Access-Control-Expose-Headers` in internal response's header list.

An opaque filtered response is a filtered response whose type is opaque, status is 0, status message is the empty byte sequence, header list is an empty list, body is null, and cache state is none.

In other words, an opaque filtered response is nearly indistinguishable from a network error. When introducing new APIs, do not use the internal response for internal specification algorithms as you will leak information.

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 either to be cleared together with HTTP cookies and similar tracking functionality.

Further details are defined by HTTP. [HTTPAUTH]

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 `POST`. 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 resources cross-origin and allow for more versatile HTTP requests than possible with HTML's form element, the platform has a CORS protocol layered on top of HTTP. It allows resources to declare they can be shared with resources residing on a different origin.

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

This section explains the CORS protocol as it pertains to servers. Requirements for user agents are part of the fetch algorithm.

3.2.1 General

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

For HTTP requests that are more involved than what is possible with HTML's form element, a CORS preflight fetch is performed, to ensure the resource understands the CORS protocol.

3.2.2 HTTP requests

An HTTP request can be identified as pertaining in the CORS protocol if it includes an `Origin` header. This is named a CORS request.

An HTTP request can be identified as being a check to see if the CORS protocol is understood if it is a CORS request, 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.

This is named a CORS preflight request.

3.2.3 HTTP responses

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

`Access-Control-Allow-Origin`

Indicates whether a resource 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 a resource 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 resource 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 resource 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 HTTP response, via 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   = #field-name

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

4 Fetching

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

The CORS flag is a bookkeeping detail for handling redirects. Only use the request parameter in other standards.

1. If request's url contains a Known HSTS Host, modify it per the requirements of the "URI [sic] Loading and Port Mapping" chapter of HTTP Strict Transport Security. [HSTS]

2. If request's referrer is not no referrer, set request's referrer to the result of invoking determine request's referrer. [REFERRER]

   As stated in Referrer Policy, user agents can provide the end user with options to override request's referrer to no referrer or have it expose less sensitive information.

3. If request's synchronous flag is unset and fetch is not invoked recursively, run the remaining steps in parallel.

4. Let response be the value corresponding to the first matching statement:

   should fetching request be blocked as mixed content returns blocked [MIX]

   should fetching request be blocked as content security returns blocked [CSP]

   A network error.

   request's url's origin is request's origin and the CORS flag is unset

   request's url's scheme is "data" and request's same-origin data URL flag is set

   request's url's scheme is "about"

   The result of performing a basic fetch using request.

   request's mode is same-origin

   A network error.

   request's mode is no CORS

   Set request's response tainting to opaque.

   The result of performing a basic fetch using request.

   request's url's scheme is not one of "http" and "https"

   A network error.

   request's mode is CORS-with-forced-preflight

   request's unsafe request flag is set and either request's method is not a simple method or a header in request's header list is not a simple header

   Set request's response tainting to CORS.

   The result of performing an HTTP fetch using request with the CORS flag and CORS preflight flag set.

   Otherwise

   Set request's response tainting to CORS.

   The result of performing an HTTP fetch using request with the CORS flag set.

5. If fetch is invoked recursively, return response.

6. Set response's url to request's url.

7. If should response to request be blocked as mixed content returns blocked, set response to a network error. [MIX]

8. If response is not a network error, set response to the following filtered response with response as its internal response, depending on request's response tainting:

   basic

   basic filtered response

   CORS

   CORS filtered response

   opaque

   opaque filtered response

9. If request's synchronous flag is set, wait for either end-of-file to have been pushed to response's body or for response to have a termination reason, and then return response.

   This terminates fetch.

10. If request's body is non-null and request's url's scheme is "http" or "https", queue a fetch task on request to process request end-of-file for request.

11. Queue a fetch task on request to process response for response.

12. If response's body is null, run these substeps:

    1. Queue a fetch task on request to process response body for response.

    2. Queue a fetch task on request to process response end-of-file for response.

13. Otherwise, if response's body is non-null, run these substeps:

    1. Whenever response's body's is pushed to, for and as long as response has no termination reason and end-of-file has not been pushed, queue a fetch task on request to process response body for response.

    2. Once end-of-file has been pushed to response's body or response has a termination reason, queue a fetch task on request to process response end-of-file for response.

       Ideally FTP/HTTP define this in more detail and this becomes a set of simple hooks.

    Use the networking task source for these tasks.

4.1 Basic fetch

To perform a basic fetch using request, switch on request's url's scheme, and run the associated steps:

"about"

If request's url's scheme data is "blank", return a response whose header list consist of a single header whose name is `Content-Type` and value is `text/html;charset=utf-8`, body is the empty byte sequence, and TLS state is request's client's TLS state.

Otherwise, return a network error.

URLs such as "about:config" are handled during navigation and result in a network error in the context of fetching.

"blob"

1. Let blob be request's url's object.

2. If blob is null, return a network error.

3. Let length be blob's size attribute value.

4. Let response be a new response.

5. Append `Content-Length`/length to response's header list.

6. Append `Content-Type`/blob's type attribute value to response's header list.

7. Set response's TLS state to request's client's TLS state.

8. Set response's body to the result of performing the read operation on blob.

9. Return response.

"data"

If request's method is `GET` and obtaining a resource from request's url does not return failure, return a response whose header list consist of a single header whose name is `Content-Type` and value is the MIME type and parameters returned from obtaining a resource, body is the data returned from obtaining a resource, and TLS state is request's client's TLS state. [DATAURL]

Otherwise, return a network error.

"file"

"ftp"

For now, unfortunate as it is, file and ftp URLs are left as an exercise for the reader.

When in doubt, return a network error.

"filesystem"

If request's sandboxed storage area URLs flag is set, return a network error.

Otherwise, … this scheme still needs to be defined.

"http"

"https"

Return the result of performing an HTTP fetch using request.

Otherwise

Return a network error.

4.2 HTTP fetch

To perform an HTTP fetch using request with an optional CORS flag, CORS preflight flag, and authentication fetch flag, run these steps:

The CORS flag is still a bookkeeping detail. The CORS preflight flag and authentication fetch flag are too. The former indicates a CORS preflight request is required and the latter indicates an attempt to authenticate.

1. Let response be null.

2. If request's skip service worker flag is unset and request's client's global object is not a ServiceWorkerGlobalScope object, run these substeps: [HTML] [SW]

   1. Set response to the result of invoking handle fetch for request. [SW]

   2. If either response's type is opaque and request's mode is not no CORS or response's type is error, return a network error.

3. If response is null, run these substeps:

   1. If the CORS preflight flag is set and one of these conditions is true:

      • There is no method cache match for request's method using request, and either request's method is a not simple method or request's mode is CORS-with-forced-preflight.
      • There is at least one header in request's header list for whose name there is no header name cache match using request and which is not a simple header.

      Then run these subsubsteps:

      1. Let response be the result of performing a CORS preflight fetch using request.

      2. If response is a network error, return response.

   2. Set request's skip service worker flag.

      There might be redirects. Alternatively, request's authentication flag is set and the CORS flag is unset.

   3. Let credentials flag be set if either request's credentials mode is include, or request's credentials mode is same-origin and the CORS flag is unset, and unset otherwise.

   4. If request's cache mode is default and request's header list contains a header named `If-Modified-Since`, `If-None-Match`, `If-Unmodified-Since`, `If-Match`, or `If-Range`, set request's cache mode to no-store.

   5. Set response to the result of performing an HTTP network or cache fetch using request with credentials flag if set and authentication fetch flag if set.

   6. If the CORS flag is set and a CORS check for request and response returns failure, return a network error.

      There is no need to apply this to a response from a service worker.

4. Then, switch on response's status:

   304

   1. If request's cache mode is neither default nor no-cache, do nothing.

   2. Otherwise, run these subsubsteps:

      1. If there is no entry in the HTTP cache for request and response, return a network error.

      2. Set response to the result of obtaining a response from the HTTP cache using request and response.

         This changes response entirely, including its status which is most likely 200 now.

         Set response's cache state to validated.

   301

   302

   303

   307

   308

   1. Let location be the result of parsing `Location` in response's header list.

   2. If location is null, return response.

   3. If location is failure, return a network error.

   4. Let locationURL be the result of parsing location with request's url.

   5. If locationURL is failure, return a network error.

   6. If request's redirect count is twenty, return a network error.

   7. Increase request's redirect count by one.

   8. Unset request's same-origin data URL flag.

   9. If the CORS preflight flag is set, set response's type to error and set request's manual redirect flag. This way we avoid running the substeps below.

   10. If request's manual redirect flag is unset, run these substeps:

       1. If the CORS flag is set and locationURL's origin is not request's url's origin, set request's origin to an opaque identifier.

       2. If the CORS flag is set and either locationURL's username is not the empty string or locationURL's password is non-null, return a network error.

       3. Set request's url to locationURL.

       4. Return the result of performing a fetch using request, with the CORS flag set if set.

   401

   1. If request's authentication flag is unset or the CORS flag is set, return response.

   2. Needs testing: multiple `WWW-Authenticate` headers, missing, parsing issues.

   3. If request's use URL credentials flag is unset, or the authentication fetch flag is set, run these substeps:

      1. Let username and password be the result of prompting the end user for a username and password, respectively.

      2. Set the username given request's url and username.

      3. Set the password given request's url and password.

   4. Return the result of performing an HTTP fetch using request, with the authentication fetch flag set.

   407

   1. Needs testing: multiple `Proxy-Authenticate` headers, missing, parsing issues.

   2. Prompt the end user as appropriate and store the result as appropriate as a proxy authentication entry. [HTTP]

      Remaining details surrounding proxy authentication are defined by HTTP.

   3. Return the result of performing an HTTP fetch using request.

   Otherwise

   Do nothing.

5. If the authentication fetch flag is set, create an authentication entry for request and the given realm. [HTTPAUTH]

6. If the CORS preflight flag is set and response is a network error, clear cache entries using request.

7. Return response. Typically response's body is still being pushed to after returning.

4.3 HTTP network or cache fetch

To perform a HTTP network or cache fetch using request with an optional credentials flag and authentication fetch flag, run these steps:

The authentication fetch flag is still a bookkeeping detail. The credentials flag is one too.

1. Let HTTPRequest be a copy of request, except that HTTPRequest's body is a tee of request's body.

   Headers need to be added without affecting request. Due to redirects or authentication failure, it can get reused.

2. Append `Referer`/empty byte sequence, if HTTPRequest's referrer is no referrer, and `Referer`/HTTPRequest's referrer, serialized and utf-8 encoded, otherwise, to HTTPRequest's header list.

3. If HTTPRequest's force Origin header flag is set, append `Origin`/HTTPRequest's origin, serialized and utf-8 encoded, to HTTPRequest's header list.

4. If credentials flag is set, run these substeps:

   1. Modify HTTPRequest's header list per HTTP State Management Mechanism. [COOKIES]

   2. Let authorizationValue be null.

   3. If there's an authentication entry for HTTPRequest and either HTTPRequest's use URL credentials flag is unset or HTTPRequest's url does not include credentials, set authorizationValue to authentication entry.

   4. Otherwise, if HTTPRequest's url does include credentials and the authentication fetch flag is set, set authorizationValue to HTTPRequest's url, converted to an `Authorization` value.

   5. If authorizationValue is non-null, append `Authorization`/authorizationValue to HTTPRequest's header list.

5. If there's a proxy authentication entry, use it as appropriate.

   This intentionally does not depend on HTTPRequest's credentials mode.

6. Let response be null.

7. If request's cache mode is neither no-store nor reload, and there is a complete response in the HTTP cache for request run these substeps:

   1. If request's cache mode is either force cache or only-if-cached, set response to the response in the HTTP cache for request.

   2. Otherwise, if request's cache mode is default and the response in the HTTP cache for request does not require revalidation, set response to that response and set response's cache state to local.

   3. Otherwise, if request's cache mode is either default or no-cache, and the response in the HTTP cache for request does require revalidation, modify HTTPRequest's header list with revalidation headers.

8. Otherwise, if request's cache mode is either default or force cache, and there is a partial response in the HTTP cache for request, modify HTTPRequest's header list with resume headers.

9. If response is null and request's cache mode is only-if-cached, return a network error.

10. If response is null, modify HTTPRequest's header list per HTTP.

    It would be great if we could make this more normative somehow. At this point headers such as `Accept-Encoding`, `Connection`, `DNT`, and `Host`, are to be appended if necessary.

    `Accept-Charset` must not be included. `Accept` and `Accept-Language` must not be included at this point. See HTTP header layer division.

11. If response is null, set response to the result of making an HTTP request, using HTTPRequest, following the requirements from HTTP, and waiting until either all the headers are transmitted or a network error was returned. If a network error was returned due to fetch being terminated with reason reason, set response's termination reason to reason. [HTTP]

    If response is not a network error and request's cache mode is not no-store, update response in the HTTP cache for request.

    If response was retrieved over TLS set its TLS state to either deprecated authentication or authenticated. [TLS]

    The exact determination here is up to user agents for the time being. User agents are strongly encouraged to only succeed TLS connections with strong security properties and return network errors otherwise.

    If HTTPRequest's body is non-null, run these substeps:

    1. If HTTPRequest's body's payload body length is known, set HTTPRequest's body's length to HTTPRequest's body's payload body length.

    2. Whenever HTTPRequest's body is read from (i.e. is transmitted), increase HTTPRequest's body's transmitted with the amount of payload body bytes transmitted and then queue a fetch task on request to process request body for HTTPRequest.

       Use the networking task source.

    Run these substeps in parallel, after the outer set of steps has returned:

    1. If response's body is non-null, set response's body's length to response's body's payload body length.

    2. Whenever one or more bytes are transmitted, let bytes be the transmitted bytes and run these subsubsteps:

       1. Increase response's body's transmitted with bytes' length.

       2. Let codings be the result of parsing `Content-Encoding` in response's header list.

       3. Set bytes to the result of handling content codings given codings and bytes.

       4. Push bytes to response's body.

    3. If at any point fetch is terminated with reason reason, set response's termination reason to reason.

    These are run in parallel as at this point it is unclear whether response's body is relevant (response might be a redirect).

12. Delete `Content-Encoding` from response's header list if one of the following conditions is true:

    • Parsing `Content-Encoding` in response's header list returns `gzip` and parsing `Content-Type in response's header list returns `application/gzip`, `application/x-gunzip`, or `application/x-gzip`.
    • Parsing `Content-Encoding` in response's header list returns `compress` and parsing `Content-Type in response's header list returns `application/compress` or `application/x-compress.

    This deals with broken Apache configurations. Ideally HTTP would define this.

    Gecko bug 1030660 looks into whether this quirk can be removed.

13. If credentials flag is set and response's header list contains one or more headers named `Set-Cookie`, run these substeps:

    1. Wait until ownership of the storage mutex can be taken by this instance of the fetch algorithm.

    2. Take ownership of the storage mutex.

    3. Update the cookies. [COOKIES]

       This is a fingerprinting vector.

    4. Release the storage mutex so that it is once again free.

14. Return response. Typically response's body is still being pushed to after returning.

4.4 CORS preflight fetch

To perform a CORS preflight fetch using request, run these steps:

1. Let preflight be a new request whose method is `OPTIONS`, url is request's url, origin is request's origin, force Origin header flag is set, referrer is request's referrer,

2. Set `Access-Control-Request-Method` to request's method in preflight's header list.

3. Let headers be the names of request's header list's headers, excluding duplicates, sorted lexicographically, and byte lowercased.

4. Let value be the items in headers separated from each other by 0x2C 0x20.

5. Set `Access-Control-Request-Headers` to value in preflight's header list.

6. Let response be the result of performing an HTTP network or cache fetch using preflight.

7. If a CORS check for request and response returns success and response's status is in the range 200 to 299, run these substeps:

   The CORS check is done on request rather than preflight to ensure the correct credentials mode is used.

   1. Let methods be the result of parsing `Access-Control-Allow-Methods` in response's header list.

   2. Let headerNames be the result of parsing `Access-Control-Allow-Headers` in response's header list.

   3. If either methods or headerNames is failure, return a network error.

   4. If methods is null and request's mode is CORS-with-forced-preflight, set methods to request's method.

      This ensures that a CORS preflight fetch that happened due to request's mode being CORS-with-forced-preflight is cached.

   5. If request's method is not in methods and is not a simple method, return a network error.

   6. If one of request's header list' names is not in headerNames and its corresponding header is not a simple header, return a network error.

   7. Let max-age be the result of parsing `Access-Control-Max-Age` in response's header list.

   8. If max-age is failure or null, set max-age to zero.

   9. If max-age is greater than an imposed limit on max-age, set max-age to the imposed limit.

   10. If the user agent does not provide for a cache, return response.

   11. For each method in methods for which there is a method cache match using request, set matching entry's max-age to max-age.

   12. For each method in methods for which there is no method cache match using request, create a new entry in CORS preflight cache as follows:

       origin

       request's origin

       url

       request's url

       max-age

       max-age

       credentials

       False if request's credentials mode is not include, and true otherwise

       method

       method

   13. For each headerName in headerNames for which there is a header name cache match using request, set matching entry's max-age to max-age.

   14. For each headerName in headerNames for which there is no header name cache match using request, create a new entry in CORS preflight cache as follows:

       origin

       request's origin

       url

       request's url

       max-age

       max-age

       credentials

       False if request's credentials mode is not include, and true otherwise

       header name

       headerName

   15. Return response.

8. Otherwise, return a network error.

4.5 CORS preflight cache

A CORS preflight cache consists of a collection of entries where each entry has these fields: origin, url, max-age, credentials, method, and header name.

Entries must be removed after the seconds specified in the max-age field have passed since storing the entry. Entries may be removed before that moment arrives.

To clear cache entries given a request, remove any entries in the CORS preflight cache whose origin is request's origin and whose url is request's url.

There is a cache match for request if origin is request's origin, url is request's url, and either credentials is false and request's credentials mode is not include or credentials is true.

There is a method cache match for method using request when there is an entry in CORS preflight cache for which there is a cache match for request and its method is method.

There is a header name cache match for headerName using request when there is an entry in CORS preflight cache for which there is a cache match for request and its header name is headerName.

4.6 CORS check

To perform a CORS check for a request and response, run these steps:

1. Let origin be the result of parsing `Access-Control-Allow-Origin` in response's header list.

2. If origin is null or failure, return failure.

   Null is not `null`.

3. If request's credentials mode is not include and origin is `*`, return success.

4. If request's origin, serialized and utf-8 encoded, is not origin, return failure.

5. If request's credentials mode is not include, return success.

6. Let credentials be the result of parsing `Access-Control-Allow-Credentials` in response's header list.

7. If credentials is `true`, return success.

   It has been suggested to check for origin not being `null` here as that would be equal to allowing credentials and `*` which is also forbidden.

8. Return failure.

5 Fetch API

The fetch() method is relatively low-level API for fetching resources. It covers slightly more ground than XMLHttpRequest, although it is currently lacking when it comes to reporting progression.

fetch("/music/pk/altes-kamuffel.flac")
  .then(res => res.blob()).then(playBlob)

fetch("/", {method:"HEAD"})
  .then(res => log(res.headers.get("strict-transport-security")))

fetch("https://pk.example/berlin-calling.json", {mode:"cors"})
  .then(res => {
    if(res.headers.get("content-type") == "application/json") {
      return res.json()
    } else {
      throw new TypeError()
    }
  }).then(processJSON)

5.1 Headers class

typedef (Headers or sequence<sequence<ByteString>> or OpenEndedDictionary<ByteString>) HeadersInit;

var meta = { "Content-Type": "text/xml", "Breaking-Bad": "<3" }
new Headers(meta)

[Constructor(optional HeadersInit init),
 Exposed=(Window,Worker)]
interface Headers {
  void append(ByteString name, ByteString value);
  void delete(ByteString name);
  ByteString? get(ByteString name);
  sequence<ByteString> getAll(ByteString name);
  boolean has(ByteString name);
  void set(ByteString name, ByteString value);
  iterable<ByteString, ByteString>;
};

A Headers object has an associated header list (a header list).

A Headers object also has an associated guard, which is one of immutable, request, request-no-CORS, response and none (initially none).

immutable exists for service workers. [SW]

To fill a Headers object (headers) with a given object (object), run these steps:

1. If object is a Headers object, copy its header list as headerListCopy and then for each header in headerListCopy, retaining order, append header's name/header's value to headers. Rethrow any exception.

   Once Headers.prototype[Symbol.iterator] is defined this special casing will no longer be needed.

2. Otherwise, if object is a sequence, then for each header in object, run these substeps:

   1. If header does not contain exactly two items, throw a TypeError.

   2. Append header's first item/header's second item to headers. Rethrow any exception.

3. Otherwise, if object is an open-ended dictionary, then for each header in object, run these substeps:

   1. Set header's key to header's key, converted to ByteString. Rethrow any exception.

   2. Append header's key/header's value to headers. Rethrow any exception.

The Headers(init) constructor, when invoked, must run these steps:

1. Let headers be a new Headers object.

2. If init is given, fill headers with init. Rethrow any exception.

3. Return headers.

To append a name/value (name/value) pair to a Headers object (headers), run these steps:

1. If name is not a name or value is not a value, throw a TypeError.

2. If guard is immutable, throw a TypeError.

3. Otherwise, if guard is request and name is a forbidden header name, return.

4. Otherwise, if guard is request-no-CORS and name/value is not a simple header, return.

5. Otherwise, if guard is response and name is a forbidden response header name, return.

6. Append name/value to header list.

The append(name, value) method, when invoked, must append name/value to the context object and rethrow any exception.

The delete(name) method, when invoked, must run these steps:

1. If name is not a name, throw a TypeError.

2. If guard is immutable, throw a TypeError.

3. Otherwise, if guard is request and name is a forbidden header name, return.

4. Otherwise, if guard is request-no-CORS and name/`invalid` is not a simple header, return.

5. Otherwise, if guard is response and name is a forbidden response header name, return.

6. Delete name from header list.

The get(name) method, when invoked, must run these steps:

1. If name is not a name, throw a TypeError.

2. Return the value of the first header in header list whose name is name, and null otherwise.

The getAll(name) method, when invoked, must run these steps:

1. If name is not a name, throw a TypeError.

2. Return the values of all headers in header list whose name is name, in list order, and the empty sequence otherwise.

The has(name) method, when invoked, must run these steps:

1. If name is not a name, throw a TypeError.

2. Return true if there is a header in header list whose name is name, and false otherwise.

The set(name, value) method, when invoked, must run these steps:

1. If name is not a name or value is not a value, throw a TypeError.

2. If guard is immutable, throw a TypeError.

3. Otherwise, if guard is request and name is a forbidden header name, return.

4. Otherwise, if guard is request-no-CORS and name/value is not a simple header, return.

5. Otherwise, if guard is response and name is a forbidden response header name, return.

6. Set name/value in header list.

The value pairs to iterate over are the headers in the header list with the key being the name and value the value.

5.2 Body mixin

typedef object JSON;
typedef (Blob or BufferSource or FormData or URLSearchParams or USVString) BodyInit;

To extract a byte stream and a `Content-Type` value from object, run these steps:

1. Let stream be an empty byte stream.

2. Let Content-Type be null.

3. Switch on object's type:

   Blob

   Push a copy of object's contents to stream.

   If object's type attribute is not the empty byte sequence, set Content-Type to its value.

   BufferSource

   Push a copy of object to stream.

   FormData

   Push the result of running the multipart/form-data encoding algorithm, with object as form data set and with utf-8 as the explicit character encoding, to stream.

   Set Content-Type to `multipart/form-data;boundary=`, followed by the multipart/form-data boundary string generated by the multipart/form-data encoding algorithm.

   URLSearchParams

   Push the result of running the application/x-www-form-urlencoded serializer, with data's associated list of name-value pairs as pairs, to stream.

   Set Content-Type to `application/x-www-form-urlencoded;charset=UTF-8`.

   USVString

   Push the result of running utf-8 encode on object to stream.

   Set Content-Type to `text/plain;charset=UTF-8`.

4. Return stream and Content-Type.

[NoInterfaceObject]
interface Body {
  readonly attribute boolean bodyUsed;
  Promise<ArrayBuffer> arrayBuffer();
  Promise<Blob> blob();
  Promise<FormData> formData();
  Promise<JSON> json();
  Promise<USVString> text();
};

Formats you would not want a network layer to be dependent upon, such as HTML, will likely not be exposed here. Rather, an HTML parser API might accept a stream in due course.

Objects implementing the Body mixin gain an associated body (a byte stream), a used flag (initially unset), and a MIME type (initially the empty byte sequence).

The bodyUsed attribute's getter must return true if the used flag is set, and false otherwise.

Objects implementing the Body mixin also have an associated consume body algorithm, which given a type, runs these steps:

1. Let p be a new promise.

2. If used flag is set, reject p with a TypeError.

3. Otherwise, set used flag and then run these substeps in parallel:

   1. Let stream be body.

   2. If stream is null, set stream to an empty byte sequence.

   3. Let bytes be the result of reading from stream until it returns end-of-stream.

   4. Switch on type:

      ArrayBuffer

      Resolve p with an ArrayBuffer whose contents are bytes.

      Blob

      Resolve p with a Blob whose contents are bytes and type is MIME type.

      FormData

      If MIME type (ignoring parameters) is `multipart/form-data`, run these subsubsteps:

      1. Parse bytes, using the value of the `boundary` parameter from MIME type and utf-8 as encoding, per the rules set forth in Returning Values from Forms: multipart/form-data. [RFC2388]

      2. If that fails for some reason, reject p with a TypeError.

      3. Otherwise, resolve p with a new FormData object, running create an entry for each entry as the result of the parsing operation and appending it to entries.

      The above is a rough approximation of what is required for `multipart/form-data`, a more detailed parsing specification is to be written. Volunteers welcome.

      Otherwise, if MIME type (ignoring parameters) is `application/x-www-form-urlencoded`, run these subsubsteps:

      1. Let entries be the result of parsing bytes.

      2. If entries is failure, reject p with a TypeError.

      3. Resolve p with a new FormData object whose entries are entries.

      Otherwise, reject p with a TypeError.

      JSON

      Let JSON be the result of invoking the initial value of the parse property of the JSON object with the result of running utf-8 decode on bytes as argument.

      If that threw an exception, reject p with that exception.

      Otherwise, resolve p with JSON.

      text

      Resolve p with the result of running utf-8 decode on bytes.

4. Return p.

The arrayBuffer() method, when invoked, must return the result of running consume body with ArrayBuffer.

The blob() method, when invoked, must return the result of running consume body with Blob.

The formData() method, when invoked, must return the result of running consume body with FormData.

The json() method, when invoked, must return the result of running consume body with JSON.

The text() method, when invoked, must return the result of running consume body with text.

5.3 Request class

Expose client member? See SW #318.

typedef (Request or USVString) RequestInfo;

[Constructor(RequestInfo input, optional RequestInit init),
 Exposed=(Window,Worker)]
interface Request {
  readonly attribute ByteString method;
  readonly attribute USVString url;
  readonly attribute Headers headers;

  readonly attribute RequestContext context;
  readonly attribute DOMString referrer;
  readonly attribute RequestMode mode;
  readonly attribute RequestCredentials credentials;
  readonly attribute RequestCache cache;

  Request clone();
};
Request implements Body;

dictionary RequestInit {
  ByteString method;
  HeadersInit headers;
  BodyInit body;
  RequestMode mode;
  RequestCredentials credentials;
  RequestCache cache;
};

enum RequestContext {
  "audio", "beacon", "cspreport", "download", "embed", "eventsource", "favicon", "fetch",
  "font", "form", "frame", "hyperlink", "iframe", "image", "imageset", "import",
  "internal", "location", "manifest", "object", "ping", "plugin", "prefetch", "script",
  "serviceworker", "sharedworker", "subresource", "style", "track", "video", "worker",
  "xmlhttprequest", "xslt"
};
enum RequestMode { "same-origin", "no-cors", "cors" };
enum RequestCredentials { "omit", "same-origin", "include" };
enum RequestCache { "default", "no-store", "reload", "no-cache", "force-cache", "only-if-cached" };

A Request object has an associated request (a request).

A Request object also has an associated Headers object which is itself associated with request's header list and whose guard is request.

A Request object's body is its request's body.

The Request(input, init) constructor must run these steps:

1. If input is a Request object and input's body is non-null, run these substeps:

   1. If input's used flag is set, throw a TypeError.

   2. Set input's used flag.

2. Let request be input's associated request, if input is a Request object, and a new request otherwise.

3. Set request to a new request whose url is request's url, method is request's method, header list is a copy of request's header list, unsafe request flag is set, body is request's body, client is entry settings object, origin is entry settings object's origin, force Origin header flag is set, same-origin data URL flag is set, referrer is client, context is fetch, mode is request's mode, credentials mode is request's credentials mode, and cache mode is request's cache mode.

4. Let fallbackMode be null.

5. Let fallbackCredentials be null.

6. Let fallbackCache be null.

7. If input is a string, run these substeps:

   1. Let parsedURL be the result of parsing input with entry settings object's API base URL.

   2. If parsedURL is failure, throw a TypeError.

   3. Set request's url to parsedURL.

   4. Set fallbackMode to CORS.

   5. Set fallbackCredentials to omit.

   6. Set fallbackCache to default.

8. Let mode be init's mode member if it is present, and fallbackMode otherwise.

9. If mode is non-null, set request's mode to mode.

10. Let credentials be init's credentials member if it is present, and fallbackCredentials otherwise.

11. If credentials is non-null, set request's credentials mode to credentials.

12. Let cache be init's cache member if it is present, and fallbackCache otherwise.

13. If cache is non-null, set request's cache mode to cache.

14. If init's method member is present, let method be it and run these substeps:

    1. If method is not a method or method is a forbidden method, throw a TypeError.

    2. Normalize method.

    3. Set request's method to method.

15. Let r be a new Request object associated with request and a new Headers object.

16. Let headers be a copy of r's Headers object.

17. If init's headers member is present, set headers to init's headers member.

18. Empty r's request's header list.

19. If r's request's mode is no CORS, run these substeps:

    1. If r's request's method is not a simple method, throw a TypeError.

    2. Set r's Headers object's guard to request-no-CORS.

20. Fill r's Headers object with headers. Rethrow any exceptions.

21. If init's body member is present, run these substeps:

    1. Let stream and Content-Type be the result of extracting init's body member.

    2. Set r's request's body to stream.

    3. If Content-Type is non-null and r's request's header list contains no header named `Content-Type`, append `Content-Type`/Content-Type to r's Headers object. Rethrow any exception.

22. Set r's MIME type to the result of extracting a MIME type from r's request's header list.

23. Return r.

The method attribute's getter must return request's method.

The url attribute's getter must return request's url, serialized with the exclude fragment flag set.

The headers attribute's getter must return the associated Headers object.

The context attribute's getter must return request's context.

The referrer attribute's getter must return the empty string if request's referrer is no referrer, "about:client" if request's referrer is client and request's referrer, serialized, otherwise.

The mode attribute's getter must return the value corresponding to the first matching statement, switching on request's mode:

same-origin

"same-origin"

no CORS

"no-cors"

CORS

CORS-with-forced-preflight

"cors"

The credentials attribute's getter must return request's credentials mode.

The cache attribute's getter must return the value corresponding to the first matching statement, switching on request's cache mode:

force cache

"force-cache"

Otherwise

Value as is.

The clone() method, when invoked, must run these steps:

1. If used flag is set, throw a TypeError.

2. Let newRequest be a copy of request, except that newRequest's body is a tee of request's body.

3. Let r be a new Request object associated with newRequest and a new Headers object.

4. Return r.

5.4 Response class

[Constructor(optional BodyInit body, optional ResponseInit init),
 Exposed=(Window,Worker)]
interface Response {
  static Response error();
  static Response redirect(USVString url, optional unsigned short status = 302);

  readonly attribute ResponseType type;

  readonly attribute USVString url;
  readonly attribute unsigned short status;
  readonly attribute ByteString statusText;
  readonly attribute Headers headers;

  Response clone();
};
Response implements Body;

dictionary ResponseInit {
  unsigned short status = 200;
  ByteString statusText = "OK";
  HeadersInit headers;
};

enum ResponseType { "basic", "cors", "default", "error", "opaque" };

A Response object has an associated response (a response).

A Response object also has an associated Headers object which is itself associated with response's header list and whose guard is response.

A Response object's body is its response's body.

The Response(body, init) constructor, when invoked, must run these steps:

1. If init's status member is not in the range 200 to 599, throw a RangeError.

2. If init's statusText member does not match the Reason-Phrase token production, throw a TypeError.

3. Let r be a new Response object, associated with a new response and a new Headers object.

4. Set r's response's status to init's status member.

5. Set r's response's status message to init's statusText member.

6. If init's headers member is present, run these substeps:

   1. Empty r's response's header list.

   2. Fill r's Headers object with init's headers member. Rethrow any exceptions.

7. If body is given, run these substeps:

   1. Let stream and Content-Type be the result of extracting body.

   2. Set r's response's body to stream.

   3. If Content-Type is non-null and r's response's header list contains no header named `Content-Type`, append `Content-Type`/Content-Type to r's response's header list.

8. Set r's MIME type to the result of extracting a MIME type from r's response's header list.

9. Set r's response's TLS state to entry settings object's TLS state.

10. Return r.

The static error() method, when invoked, must run return a new Response object, associated with a new network error and a new Headers object.

The static redirect(url, status) method, when invoked, must run these steps:

1. Let parsedURL be the result of parsing url with entry settings object's API base URL.

2. If parsedURL is failure, throw a TypeError.

3. If status is not one of 301, 302, 303, 307, and 308, throw a RangeError.

4. Let r be a new Response object, associated with a new response and a new Headers object.

5. Set r's response's status to status.

6. Set `Location` to parsedURL, serialized and utf-8 encoded, in r's response's header list.

7. Return r.

The type attribute's getter must return response's type.

The url attribute's getter must return the empty string if response's url is null and response's url, serialized with the exclude fragment flag set, otherwise. [URL]

The status attribute's getter must return response's status.

The statusText attribute's getter must return response's status message.

The headers attribute's getter must return the associated Headers object.

The clone() method, when invoked, must run these steps:

1. If used flag is set, throw a TypeError.

2. Let newResponse be a copy of response, except that newResponse's body is a tee of request's body.

3. Let r be a new Response object associated with newResponse and a new Headers object.

4. Return r.

5.5 Structured cloning of Headers, Request, and Response objects

Unlikely to happen anytime soon due to difficulty of cloning promises and streams. See SW #313 for details.

5.6 Fetch method

[NoInterfaceObject]
interface GlobalFetch {
  Promise<Response> fetch(RequestInfo input, optional RequestInit init);
};
Window implements GlobalFetch;
WorkerGlobalScope implements GlobalFetch;

The fetch(input, init) method, must run these steps:

1. Let p be a new promise.

2. Let r be the associated request of the result of invoking the initial value of Request as constructor with input and init as arguments. If this throws an exception, reject p with it.

3. Run the following in parallel:

   Fetch r.

   To process response for response, run these substeps:

   1. If response's type is error, reject p with a TypeError.

   2. Otherwise, resolve p with new Response object associated with response.

   To process response body for response, do nothing.

   To process response end-of-file for response, do nothing.

4. Return p.

Background reading

This section and its subsections are informative only.

HTTP header layer division

For the purposes of fetching, the platform has an API layer (HTML's img, CSS' background-image), service worker layer, and network & cache layer. `Accept` and `Accept-Language` are set at the API layer (typically by the user agent). Most other headers controlled by the user agent, such as `Accept-Encoding`, `Host`, and `Referer`, are set in the network & cache layer. Developers can set headers either at the API layer or in the service worker layer (typically through a Request object). Developers have almost no control over forbidden headers, but can control `Accept` and have the means to constrain and disable `Referer` for instance.

Atomic HTTP redirect handling

Throughout the platform, redirects (a response whose status is one of 301, 302, 303, 307, and 308) are not exposed to APIs. Exposing redirects might leak information not otherwise available through a cross-site scripting attack.

A fetch to https://example.org/auth that includes a Cookie marked HttpOnly could result in a redirect to https://other-origin.invalid/4af955781ea1c84a3b11. This new URL contains a secret. If we expose redirects that secret would be available through a cross-site scripting attack.

Basic safe CORS protocol setup

For resources where data is protected through IP authentication or a firewall (unfortunately relatively common still), using the CORS protocol is unsafe. (This is the reason why the CORS protocol had to be invented.)

However, otherwise using the following header is:

Access-Control-Allow-Origin: *

Even if a resource exposes additional information based on cookie or HTTP authentication, using the above header will not reveal it. It will share the resource with APIs such as XMLHttpRequest, much like it is already shared with curl and wget.

Thus in other words, if a resource cannot be accessed from a random device connected to the web using curl and wget the aforementioned header is not to be included. If it can be accessed however, it is perfectly fine to do so.

CORS protocol and HTTP caches

If CORS protocol requirements are more complicated than setting `Access-Control-Allow-Origin` to * or a static origin, `Vary` is to be used. [HTML] [HTTP]

Vary: Access-Control-Allow-Origin

References

Acknowledgments

Thanks to Adam Barth, Alexey Proskuryakov, Ángel González, Anssi Kostiainen, Arne Johannessen, Arthur Barstow, Axel Rauschmayer, Ben Kelly, Benjamin Hawkes-Lewis, Bert Bos, Björn Höhrmann, Boris Zbarsky, Brad Hill, Brad Porter, Cameron McCormack, Clement Pellerin, Collin Jackson, David Håsäther, David Orchard, Domenic Denicola, Dean Jackson, Eric Lawrence, Frank Ellerman, Frederick Hirsch, Gavin Carothers, Glenn Maynard, Graham Klyne, Hal Lockhart, Hallvord R. M. Steen, Henri Sivonen, Honza Bambas, Ian Hickson, Jake Archibald, James Graham, Janusz Majnert, Jeff Hodges, Jeffrey Yasskin, Jesse M. Heines, Jonas Sicking, Julian Reschke, Jussi Kalliokoski, Kenji Baheux, Lachlan Hunt, Lucas Gonze, 呂康豪 (Kang-Hao Lu), Maciej Stachowiak, Marc Silbey, Marcos Caceres, Mark Nottingham, Mark S. Miller, Martin Dürst, Matt Falkenhagen, Matt Oshry, Matt Womer, Mhano Harkness, Michael Smith, Mike West, Mohamed Zergaoui, Nikhil Marathe, Nikunj Mehta, Odin Hørthe Omdal, Ondřej Žára, Philip Jägenstedt, R. Auburn, Sharath Udupa, Shivakumar Jagalur Matt, Simon Pieters, Sunava Dutta, Surya Ismail, 吉野剛史 (Takeshi Yoshino), Thomas Roessler, Tobie Langel, Tomás Aparicio, 保呂毅 (Tsuyoshi Horo), Tyler Close, Vladimir Dzhuvinov, Wayne Carr, and Zhenbin Xu for being awesome.

This standard is written by Anne van Kesteren (Mozilla, annevk@annevk.nl).

Per CC0, to the extent possible under law, the editor has waived all copyright and related or neighboring rights to this work.