From 1963b4094e9491b256d22fe35695744f4c9fa63f Mon Sep 17 00:00:00 2001 From: Noam Rosenthal Date: Mon, 2 Jan 2023 17:17:20 +0200 Subject: [PATCH 01/25] Editorial: Add prose about constructing a request This intends to be a summary of informative notes in the #Requests section, into a concise "starter" guide to populating a request, which is usually the tricky bit of using Fetch. Requested by authors of other specs, see for example: https://github.com/w3ctag/design-principles/issues/238 https://github.com/fedidcg/FedCM/issues/320 --- fetch.bs | 50 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 50 insertions(+) diff --git a/fetch.bs b/fetch.bs index 7e24ae7c3..e69409970 100644 --- a/fetch.bs +++ b/fetch.bs @@ -8437,6 +8437,56 @@ correctly. This section aims to give some advice.

This is a work in progress. +

Constructing a request

+ +

The first step in fetching is to create a request, and populate its +multiple associated parameters. + +

A request oftenmost has a client, which is the +environment settings object that initiatated the request, and the receiver of the different +response callbacks. It then expects a URL, and an HTTP +method, `GET` by default. `POST` and +`PUT` requests also accept a body, which is sent together with the +request. + +

Requests accept an optional header list parameter, custom HTTP headers to be +sent alongside the request. Note that sending custom headers may have implications, +such as requiring a CORS-preflight fetch, so handle with care. + +

One of the most important things when constructing a request is understanding how +it's supposed to handle cross-origin resources. This is expressed in the request's +mode. Some features are supposed to work only in the context of the +same origin, in which case the "same-origin" mode is +appropriate. For new features that require accessing cross-origin resources, "cors" +should be used, alongside a credentials mode, which defines whether the +request is anonymous or authenticated (e.g. with cookies and client certificates). The +"no-cors" mode is used for backwards compatibility with features +that existed before the CORS mechanism was introduced. To use "no-cors" in a new +feature, please discuss on the Fetch Github repository. +"navigate" and "websocket" are reserved for specific features. + +

A request accepts a few security-related parameters that are often configured, such +as integrity metadata, a string hash of the actual data that verifies that the +received resource matches an expectation, a cryptographic nonce metadata and +parser metadata, which allows more fine-grained security via +Content Security Policy, and referrer policy, which allows the +request to use a different referrer policy from the one provided by the +client. [[!CSP]] [[!REFERRER]] + +

A request also accepts a few metadata parameters, the important one being +destination. destinations affect +Content Security Policy and have other implications such as the +`sec-fetch-dest` header, so they are much more than informative metadata. If a new +feature requires a destination that's not in the list of +destinations, please file an issue in the +Fetch Github repository. An aditional metadata +paramater is initiator type, which specifies that the fetching +should mark resource timing automatically once the response's +body is fully downloaded. [[!CSP]] [[RESOURCE-TIMING]] + +

The rest of the parameters for request are used less frequently, and they are +documented in detail in the Requests section of this standard. +

Invoking fetch

From e409fd14d549774cea63d9220d99e608d5a7876b Mon Sep 17 00:00:00 2001 From: Noam Rosenthal Date: Wed, 4 Jan 2023 16:11:50 +0200 Subject: [PATCH 02/25] Rephrase to be more howto style --- fetch.bs | 114 +++++++++++++++++++++++++++++++------------------------ 1 file changed, 65 insertions(+), 49 deletions(-) diff --git a/fetch.bs b/fetch.bs index e69409970..a267e6cef 100644 --- a/fetch.bs +++ b/fetch.bs @@ -1515,6 +1515,9 @@ these steps:

Requests

+

This section documents how requests work in detail. To get started with populating a +request, see populating a request. +

The input to fetch is a request. @@ -1701,10 +1704,10 @@ and "webidentity" as fetches with those destinations skip service w not always relevant and might require different behavior.

-

The following table illustrates the relationship between a request's - initiator, destination, CSP directives, and features. It is - not exhaustive with respect to features. Features need to have the relevant values defined in their - respective standards. +

The following table illustrates the relationship between a + request's initiator, destination, CSP + directives, and features. It is not exhaustive with respect to features. Features need to have the + relevant values defined in their respective standards. @@ -8437,55 +8440,68 @@ correctly. This section aims to give some advice.

This is a work in progress. -

Constructing a request

+

Populating a request

The first step in fetching is to create a request, and populate its multiple associated parameters. -

A request oftenmost has a client, which is the -environment settings object that initiatated the request, and the receiver of the different -response callbacks. It then expects a URL, and an HTTP -method, `GET` by default. `POST` and -`PUT` requests also accept a body, which is sent together with the -request. - -

Requests accept an optional header list parameter, custom HTTP headers to be -sent alongside the request. Note that sending custom headers may have implications, -such as requiring a CORS-preflight fetch, so handle with care. - -

One of the most important things when constructing a request is understanding how -it's supposed to handle cross-origin resources. This is expressed in the request's -mode. Some features are supposed to work only in the context of the -same origin, in which case the "same-origin" mode is -appropriate. For new features that require accessing cross-origin resources, "cors" -should be used, alongside a credentials mode, which defines whether the -request is anonymous or authenticated (e.g. with cookies and client certificates). The -"no-cors" mode is used for backwards compatibility with features -that existed before the CORS mechanism was introduced. To use "no-cors" in a new -feature, please discuss on the Fetch Github repository. -"navigate" and "websocket" are reserved for specific features. - -

A request accepts a few security-related parameters that are often configured, such -as integrity metadata, a string hash of the actual data that verifies that the -received resource matches an expectation, a cryptographic nonce metadata and -parser metadata, which allows more fine-grained security via -Content Security Policy, and referrer policy, which allows the -request to use a different referrer policy from the one provided by the -client. [[!CSP]] [[!REFERRER]] - -

A request also accepts a few metadata parameters, the important one being -destination. destinations affect -Content Security Policy and have other implications such as the -`sec-fetch-dest` header, so they are much more than informative metadata. If a new -feature requires a destination that's not in the list of -destinations, please file an issue in the -Fetch Github repository. An aditional metadata -paramater is initiator type, which specifies that the fetching -should mark resource timing automatically once the response's -body is fully downloaded. [[!CSP]] [[RESOURCE-TIMING]] - -

The rest of the parameters for request are used less frequently, and they are -documented in detail in the Requests section of this standard. +

Start by setting the request's URL and method, +as defined by HTTP. If your `POST` or `PUT` request needs a +body, you can assign or stream it to request's body. [[HTTP]] + +

Set your request's client to the +environment settings object you're operating in. Web-exposed APIs usually operate on +platform objects (e.g. a Web IDL based API), which have a +relevant settings object. For example, a request associated with a DOM +element would set the request's client to the element's +node document's relevant settings object. [[WEBIDL]] + +

Choose your request's destination. +destinations affect Content Security Policy and have other +implications such as the `sec-fetch-dest` header, so they are much more than +informative metadata. If a new feature requires a destination that's not in the +destination table, please file an issue in the +Fetch Github repository to discuss. [[!CSP]] + +

Think through the way you intend to handle cross-origin resources. Some features may only work in +the same origin, in which case set your request mode to +"same-origin". As a general rule, modern web-exposed features that fetch cross-origin +resources should use "cors" and decide on the credentials mode on a +case by case basis. For example, font loading uses "same-origin" (credentials are only +sent in same-origin requests), video posters use "include" (credentials are always +sent), and many features make this configurable in the API. If your feature is not web-exposed, or +you think there is another reason for it to fetch cross-origin resources without CORS, discuss this +with your security team and ping contributors of the +Fetch Standard. + +

Figure out if your fetch needs to be reported to Resource Timing, and with which +initiator type. By passing an initiator type to the +request, reporting to Resource Timing will be done automatically once the +fetch is done and the response is fully downloaded. [[RESOURCE-TIMING]] + +

If your request requires additional HTTP headers, append them to your +request's header list. Note that sending custom headers may have +implications, such as requiring a CORS-preflight fetch, so handle with care. + +

Check if your request needs one or more of the additional security-related parameters. The +following ones are often configurable, e.g. by an HTML attribute: + +

+
integrity metadata +

Verifies that the content of the resource matches a pre-calculated string hash. + +

referrer policy +

Allows using a different referrer policy from the one provided by the + environment settings object. [[!REFERRER]] + +

cryptographic nonce metadata +

Together with Content Security Policy, ensures that only elements that provide + this predetermined string can fetch this resource. +

+ +

Browse through the rest of the parameters for request to see if something else is +relevant to you. The rest of the parameters are used less frequently, often for special purposes, +and they are documented in detail in the Requests section of this standard.

Invoking fetch

From 8e2b505e5400709d24b0dda2f0cce2fbcd8081e7 Mon Sep 17 00:00:00 2001 From: Noam Rosenthal Date: Wed, 4 Jan 2023 16:13:52 +0200 Subject: [PATCH 03/25] typo --- fetch.bs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/fetch.bs b/fetch.bs index a267e6cef..818cf7ac4 100644 --- a/fetch.bs +++ b/fetch.bs @@ -8494,7 +8494,7 @@ following ones are often configurable, e.g. by an HTML attribute:

Allows using a different referrer policy from the one provided by the environment settings object. [[!REFERRER]] -

cryptographic nonce metadata +
cryptographic nonce metadata

Together with Content Security Policy, ensures that only elements that provide this predetermined string can fetch this resource. From b21fe3da87d1a53c0ba9cebe155fd900bcbb4abb Mon Sep 17 00:00:00 2001 From: Noam Rosenthal Date: Thu, 5 Jan 2023 07:35:18 +0200 Subject: [PATCH 04/25] Update fetch.bs Co-authored-by: Jeffrey Yasskin --- fetch.bs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/fetch.bs b/fetch.bs index 818cf7ac4..94d842ba0 100644 --- a/fetch.bs +++ b/fetch.bs @@ -8443,7 +8443,7 @@ correctly. This section aims to give some advice.

Populating a request

The first step in fetching is to create a request, and populate its -multiple associated parameters. +items.

Start by setting the request's URL and method, as defined by HTTP. If your `POST` or `PUT` request needs a From 690004d0b3ccb775c94ca413815c88589de43287 Mon Sep 17 00:00:00 2001 From: Noam Rosenthal Date: Thu, 5 Jan 2023 07:35:28 +0200 Subject: [PATCH 05/25] Update fetch.bs Co-authored-by: Jeffrey Yasskin --- fetch.bs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/fetch.bs b/fetch.bs index 94d842ba0..4f118bfae 100644 --- a/fetch.bs +++ b/fetch.bs @@ -8452,7 +8452,7 @@ body, you can assign or stream it to request's body<

Set your request's client to the environment settings object you're operating in. Web-exposed APIs usually operate on platform objects (e.g. a Web IDL based API), which have a -relevant settings object. For example, a request associated with a DOM +relevant settings object you can use. For example, a request associated with a DOM element would set the request's client to the element's node document's relevant settings object. [[WEBIDL]] From ba70f234b12b02fc75a1944fbbc27e9776713922 Mon Sep 17 00:00:00 2001 From: Noam Rosenthal Date: Thu, 5 Jan 2023 07:35:40 +0200 Subject: [PATCH 06/25] Update fetch.bs Co-authored-by: Jeffrey Yasskin --- fetch.bs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/fetch.bs b/fetch.bs index 4f118bfae..9ba6ec75b 100644 --- a/fetch.bs +++ b/fetch.bs @@ -1516,7 +1516,7 @@ these steps:

Requests

This section documents how requests work in detail. To get started with populating a -request, see populating a request. +request, see [[#fetch-elsewhere-request]].

The input to fetch is a request. From 7debfee970bb51ddd4fd13529d7a904f5d923dbe Mon Sep 17 00:00:00 2001 From: Noam Rosenthal Date: Thu, 5 Jan 2023 07:36:14 +0200 Subject: [PATCH 07/25] Update fetch.bs Co-authored-by: Jeffrey Yasskin --- fetch.bs | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/fetch.bs b/fetch.bs index 9ba6ec75b..de35d99f6 100644 --- a/fetch.bs +++ b/fetch.bs @@ -8465,9 +8465,11 @@ informative metadata. If a new feature requires a destination

Think through the way you intend to handle cross-origin resources. Some features may only work in the same origin, in which case set your request mode to -"same-origin". As a general rule, modern web-exposed features that fetch cross-origin -resources should use "cors" and decide on the credentials mode on a -case by case basis. For example, font loading uses "same-origin" (credentials are only +"same-origin". Otherwise, new web-exposed features should almost always set their mode to +"cors". + +

Next, pick the credentials mode depending on the details of your feature. +For example, font loading uses "same-origin" (credentials are only sent in same-origin requests), video posters use "include" (credentials are always sent), and many features make this configurable in the API. If your feature is not web-exposed, or you think there is another reason for it to fetch cross-origin resources without CORS, discuss this From 13c12bc7e35a8426467cd56280910e9c0b182ed9 Mon Sep 17 00:00:00 2001 From: Noam Rosenthal Date: Thu, 5 Jan 2023 07:36:22 +0200 Subject: [PATCH 08/25] Update fetch.bs Co-authored-by: Jeffrey Yasskin --- fetch.bs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/fetch.bs b/fetch.bs index de35d99f6..2dbadaf46 100644 --- a/fetch.bs +++ b/fetch.bs @@ -8473,7 +8473,7 @@ For example, font loading uses "same-origin" (credentials are only sent in same-origin requests), video posters use "include" (credentials are always sent), and many features make this configurable in the API. If your feature is not web-exposed, or you think there is another reason for it to fetch cross-origin resources without CORS, discuss this -with your security team and ping contributors of the +with a security team and ping contributors of the Fetch Standard.

Figure out if your fetch needs to be reported to Resource Timing, and with which From 1ade14c7ef6c2165ad2f72174e5820d4bf46a272 Mon Sep 17 00:00:00 2001 From: Noam Rosenthal Date: Thu, 5 Jan 2023 07:36:35 +0200 Subject: [PATCH 09/25] Update fetch.bs Co-authored-by: Jeffrey Yasskin --- fetch.bs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/fetch.bs b/fetch.bs index 2dbadaf46..076deb0e1 100644 --- a/fetch.bs +++ b/fetch.bs @@ -8476,7 +8476,7 @@ you think there is another reason for it to fetch cross-origin resources without with a security team and ping contributors of the Fetch Standard. -

Figure out if your fetch needs to be reported to Resource Timing, and with which +

Figure out if your fetch needs to be reported to [[RESOURCE-TIMING inline]], and with which initiator type. By passing an initiator type to the request, reporting to Resource Timing will be done automatically once the fetch is done and the response is fully downloaded. [[RESOURCE-TIMING]] From 8330d9024dda07ce53ba8bab0d7aeb52d6f27194 Mon Sep 17 00:00:00 2001 From: Noam Rosenthal Date: Thu, 5 Jan 2023 07:37:43 +0200 Subject: [PATCH 10/25] Update fetch.bs Co-authored-by: Jeffrey Yasskin --- fetch.bs | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/fetch.bs b/fetch.bs index 076deb0e1..7d059578a 100644 --- a/fetch.bs +++ b/fetch.bs @@ -8497,8 +8497,9 @@ following ones are often configurable, e.g. by an HTML attribute: environment settings object. [[!REFERRER]]

cryptographic nonce metadata -

Together with Content Security Policy, ensures that only elements that provide - this predetermined string can fetch this resource. +

If the site's Content Security Policy specifies a nonce-source + for this request's destination, any request without a + [[CSP#match-nonce-to-source-list|matching]] value in this field will be blocked.

Browse through the rest of the parameters for request to see if something else is From 0f756f43310c280859ac6dca721002dbed8834ae Mon Sep 17 00:00:00 2001 From: Noam Rosenthal Date: Fri, 6 Jan 2023 09:59:10 +0200 Subject: [PATCH 11/25] Update fetch.bs Co-authored-by: Jeffrey Yasskin --- fetch.bs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/fetch.bs b/fetch.bs index 7d059578a..39693b0c1 100644 --- a/fetch.bs +++ b/fetch.bs @@ -8450,8 +8450,8 @@ as defined by HTTP. If your `POST` or `PUT` r body, you can assign or stream it to request's body. [[HTTP]]

Set your request's client to the -environment settings object you're operating in. Web-exposed APIs usually operate on -platform objects (e.g. a Web IDL based API), which have a +environment settings object you're operating in. Web-exposed APIs are generally defined with +the [[WEBIDL inline]], for which every object that implements an interface has a relevant settings object you can use. For example, a request associated with a DOM element would set the request's client to the element's node document's relevant settings object. [[WEBIDL]] From 6657a94c624de6761dc04c91538b50b23506e30b Mon Sep 17 00:00:00 2001 From: Noam Rosenthal Date: Fri, 6 Jan 2023 09:59:17 +0200 Subject: [PATCH 12/25] Update fetch.bs Co-authored-by: Jeffrey Yasskin --- fetch.bs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/fetch.bs b/fetch.bs index 39693b0c1..69bbe0b8d 100644 --- a/fetch.bs +++ b/fetch.bs @@ -8456,7 +8456,7 @@ the [[WEBIDL inline]], for which every object that implements an interfaceelement would set the request's client to the element's node document's relevant settings object. [[WEBIDL]] -

Choose your request's destination. +

Choose your request's destination using the guidance in the destination table. destinations affect Content Security Policy and have other implications such as the `sec-fetch-dest` header, so they are much more than informative metadata. If a new feature requires a destination that's not in the From bd6e06e50434178c8f7514eaa6c59022ed4375f2 Mon Sep 17 00:00:00 2001 From: Noam Rosenthal Date: Fri, 6 Jan 2023 09:59:23 +0200 Subject: [PATCH 13/25] Update fetch.bs Co-authored-by: Jeffrey Yasskin --- fetch.bs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/fetch.bs b/fetch.bs index 69bbe0b8d..d614f0a4f 100644 --- a/fetch.bs +++ b/fetch.bs @@ -8461,7 +8461,7 @@ the [[WEBIDL inline]], for which every object that implements an interfacesec-fetch-dest` header, so they are much more than informative metadata. If a new feature requires a destination that's not in the destination table, please file an issue in the -Fetch Github repository to discuss. [[!CSP]] +Fetch Github repository to discuss. [[!CSP]]

Think through the way you intend to handle cross-origin resources. Some features may only work in the same origin, in which case set your request mode to From 68a719ad0463cc0a1ee5a72dddcb05892c4e90e0 Mon Sep 17 00:00:00 2001 From: Noam Rosenthal Date: Sat, 7 Jan 2023 09:33:22 +0200 Subject: [PATCH 14/25] Add section about no-client requests --- fetch.bs | 51 +++++++++++++++++++++++++++++++-------------------- 1 file changed, 31 insertions(+), 20 deletions(-) diff --git a/fetch.bs b/fetch.bs index d614f0a4f..ee399f1c2 100644 --- a/fetch.bs +++ b/fetch.bs @@ -8449,31 +8449,38 @@ correctly. This section aims to give some advice. as defined by HTTP. If your `POST` or `PUT` request needs a body, you can assign or stream it to request's body. [[HTTP]] +

Choose your request's destination using the guidance in the +destination table. destinations affect +Content Security Policy and have other implications such as the +`sec-fetch-dest` header, so they are much more than informative metadata. If a new +feature requires a destination that's not in the destination table, please +file an issue in the Fetch Github repository to +discuss. [[!CSP]] +

Set your request's client to the environment settings object you're operating in. Web-exposed APIs are generally defined with the [[WEBIDL inline]], for which every object that implements an interface has a -relevant settings object you can use. For example, a request associated with a DOM -element would set the request's client to the element's -node document's relevant settings object. [[WEBIDL]] - -

Choose your request's destination using the guidance in the destination table. -destinations affect Content Security Policy and have other -implications such as the `sec-fetch-dest` header, so they are much more than -informative metadata. If a new feature requires a destination that's not in the -destination table, please file an issue in the -Fetch Github repository to discuss. [[!CSP]] +relevant settings object you can use. For example, a request associated with a +DOM element would set the request's client to the +element's node document's relevant settings object. All features that are directly +web-exposed by JavaScript, HTML, CSS, or other Document subresources should have A +client. + +

If your fetching is not directly web-exposed, e.g. it is sent in the background +without relying on a current {{Window}} or {{Worker}}, leave request's +client as null and set the request's origin, +policy container, and referrer to appropriate values instead, +e.g. by copying them from the environment settings object ahead of time. In these more +advanced cases, make sure the details of how your fetch handles Content Security Place +and referrer policy are fleshed out. Also make sure you handle concurrency, as +callbacks would be posted on a parallel queue. [[!REFERRER]] [[!CSP]]

Think through the way you intend to handle cross-origin resources. Some features may only work in the same origin, in which case set your request mode to -"same-origin". Otherwise, new web-exposed features should almost always set their mode to -"cors". - -

Next, pick the credentials mode depending on the details of your feature. -For example, font loading uses "same-origin" (credentials are only -sent in same-origin requests), video posters use "include" (credentials are always -sent), and many features make this configurable in the API. If your feature is not web-exposed, or -you think there is another reason for it to fetch cross-origin resources without CORS, discuss this -with a security team and ping contributors of the +"same-origin". Otherwise, new web-exposed features should almost always set their +mode to "cors". If your feature is not web-exposed, or you think +there is another reason for it to fetch cross-origin resources without CORS, discuss this with a +security team and ping contributors of the Fetch Standard.

Figure out if your fetch needs to be reported to [[RESOURCE-TIMING inline]], and with which @@ -8489,12 +8496,16 @@ implications, such as requiring a CORS-preflight fetch, so handle with ca following ones are often configurable, e.g. by an HTML attribute:

+
credentials mode +

Set to "include" if credentials are to be sent with cross-origin + requests. +

integrity metadata

Verifies that the content of the resource matches a pre-calculated string hash.

referrer policy

Allows using a different referrer policy from the one provided by the - environment settings object. [[!REFERRER]] + policy container. [[!REFERRER]]

cryptographic nonce metadata

If the site's Content Security Policy specifies a nonce-source From d1cfa864437e9a2e4efb672ae88ae5b8ee95abb5 Mon Sep 17 00:00:00 2001 From: Noam Rosenthal Date: Tue, 10 Jan 2023 09:38:22 +0200 Subject: [PATCH 15/25] Update fetch.bs Co-authored-by: Domenic Denicola --- fetch.bs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/fetch.bs b/fetch.bs index ee399f1c2..77337e7e1 100644 --- a/fetch.bs +++ b/fetch.bs @@ -8452,7 +8452,7 @@ body, you can assign or stream it to request's body<

Choose your request's destination using the guidance in the destination table. destinations affect Content Security Policy and have other implications such as the -`sec-fetch-dest` header, so they are much more than informative metadata. If a new +[:Sec-Fetch-Dest:] header, so they are much more than informative metadata. If a new feature requires a destination that's not in the destination table, please file an issue in the Fetch Github repository to discuss. [[!CSP]] From af0db38cf2a236a31a826da9b0151f69ad1213de Mon Sep 17 00:00:00 2001 From: Noam Rosenthal Date: Tue, 10 Jan 2023 10:33:18 +0200 Subject: [PATCH 16/25] Address some notes --- fetch.bs | 67 +++++++++++++++++++++++--------------------------------- 1 file changed, 28 insertions(+), 39 deletions(-) diff --git a/fetch.bs b/fetch.bs index 77337e7e1..785800e1c 100644 --- a/fetch.bs +++ b/fetch.bs @@ -1703,8 +1703,8 @@ and "webidentity" as fetches with those destinations skip service w "xslt" as that too can cause script execution. It is not included in the list as it is not always relevant and might require different behavior. -

-

The following table illustrates the relationship between a +

+

The following table llustrates the relationship between a request's initiator, destination, CSP directives, and features. It is not exhaustive with respect to features. Features need to have the relevant values defined in their respective standards. @@ -8447,15 +8447,17 @@ correctly. This section aims to give some advice.

Start by setting the request's URL and method, as defined by HTTP. If your `POST` or `PUT` request needs a -body, you can assign or stream it to request's body. [[HTTP]] +body, you set request's body to a byte sequence +as a body, or to a new body whose stream +is a {{ReadableStream}} you created. [[HTTP]]

Choose your request's destination using the guidance in the -destination table. destinations affect +[[#destination-table]]. Destinations affect Content Security Policy and have other implications such as the [:Sec-Fetch-Dest:] header, so they are much more than informative metadata. If a new feature requires a destination that's not in the destination table, please -file an issue in the Fetch Github repository to -discuss. [[!CSP]] +file an issue +to discuss. [[!CSP]]

Set your request's client to the environment settings object you're operating in. Web-exposed APIs are generally defined with @@ -8469,53 +8471,40 @@ web-exposed by JavaScript, HTML, CSS, or other Document subresource

If your fetching is not directly web-exposed, e.g. it is sent in the background without relying on a current {{Window}} or {{Worker}}, leave request's client as null and set the request's origin, -policy container, and referrer to appropriate values instead, -e.g. by copying them from the environment settings object ahead of time. In these more -advanced cases, make sure the details of how your fetch handles Content Security Place -and referrer policy are fleshed out. Also make sure you handle concurrency, as -callbacks would be posted on a parallel queue. [[!REFERRER]] [[!CSP]] +policy container, service-workers mode, and +referrer to appropriate values instead, e.g. by copying them from the +environment settings object ahead of time. In these more advanced cases, make sure the +details of how your fetch handles Content Security Place and +referrer policy are fleshed out. Also make sure you handle concurrency, as callbacks +would be posted on a parallel queue. [[!REFERRER]] [[!CSP]]

Think through the way you intend to handle cross-origin resources. Some features may only work in -the same origin, in which case set your request mode to +the same origin, in which case set your request's mode to "same-origin". Otherwise, new web-exposed features should almost always set their mode to "cors". If your feature is not web-exposed, or you think -there is another reason for it to fetch cross-origin resources without CORS, discuss this with a -security team and ping contributors of the -Fetch Standard. +there is another reason for it to fetch cross-origin resources without CORS, please +file an issue +to discuss. For cross-origin requests, also determines if credentials are to be +included with the requests, in which case set your request's +credentials mode to "include",

Figure out if your fetch needs to be reported to [[RESOURCE-TIMING inline]], and with which initiator type. By passing an initiator type to the request, reporting to Resource Timing will be done automatically once the fetch is done and the response is fully downloaded. [[RESOURCE-TIMING]] -

If your request requires additional HTTP headers, append them to your -request's header list. Note that sending custom headers may have -implications, such as requiring a CORS-preflight fetch, so handle with care. - -

Check if your request needs one or more of the additional security-related parameters. The -following ones are often configurable, e.g. by an HTML attribute: - -

-
credentials mode -

Set to "include" if credentials are to be sent with cross-origin - requests. - -

integrity metadata -

Verifies that the content of the resource matches a pre-calculated string hash. +

If your request requires additional HTTP headers, set its header list to +a header list that contains those headers, e.g. +« (`My-Header-Name`, `My-Header-Value`) ». Note that sending custom headers may +have implications, such as requiring a CORS-preflight fetch, so handle with care. -

referrer policy -

Allows using a different referrer policy from the one provided by the - policy container. [[!REFERRER]] - -

cryptographic nonce metadata -

If the site's Content Security Policy specifies a nonce-source - for this request's destination, any request without a - [[CSP#match-nonce-to-source-list|matching]] value in this field will be blocked. -

+

If you want to override the default caching mechanism, e.g. disable caching for this +request, set the request's cache mode to a value other than +"default".

Browse through the rest of the parameters for request to see if something else is relevant to you. The rest of the parameters are used less frequently, often for special purposes, -and they are documented in detail in the Requests section of this standard. +and they are documented in detail in the [[#requests]] section of this standard.

Invoking fetch

From 105475b39e72a4129094e2f3be000bfd0a06716a Mon Sep 17 00:00:00 2001 From: Noam Rosenthal Date: Tue, 10 Jan 2023 11:22:00 +0200 Subject: [PATCH 17/25] Add redirect-mode --- fetch.bs | 3 +++ 1 file changed, 3 insertions(+) diff --git a/fetch.bs b/fetch.bs index 785800e1c..79863f375 100644 --- a/fetch.bs +++ b/fetch.bs @@ -8502,6 +8502,9 @@ have implications, such as requiring a CORS-preflight fetch, so handle wi request, set the request's cache mode to a value other than "default". +

Determine if your request should support redirects. If it doesn't, set its +redirect mode to "error". +

Browse through the rest of the parameters for request to see if something else is relevant to you. The rest of the parameters are used less frequently, often for special purposes, and they are documented in detail in the [[#requests]] section of this standard. From 6152d2ab44558f37c97ffab1c430b63a77a61525 Mon Sep 17 00:00:00 2001 From: Noam Rosenthal Date: Wed, 11 Jan 2023 06:49:15 +0200 Subject: [PATCH 18/25] nits --- fetch.bs | 23 +++++++++++++---------- 1 file changed, 13 insertions(+), 10 deletions(-) diff --git a/fetch.bs b/fetch.bs index 79863f375..8165e88c3 100644 --- a/fetch.bs +++ b/fetch.bs @@ -1515,8 +1515,8 @@ these steps:

Requests

-

This section documents how requests work in detail. To get started with populating a -request, see [[#fetch-elsewhere-request]]. +

This section documents how requests work in detail. To get started, see +[[#fetch-elsewhere-request]].

The input to fetch is a request. @@ -8440,7 +8440,7 @@ correctly. This section aims to give some advice.

This is a work in progress. -

Populating a request

+

Setting up a request

The first step in fetching is to create a request, and populate its items. @@ -8452,10 +8452,11 @@ body, you set request's body to a byte is a {{ReadableStream}} you created. [[HTTP]]

Choose your request's destination using the guidance in the -[[#destination-table]]. Destinations affect +destination table. Destinations affect Content Security Policy and have other implications such as the [:Sec-Fetch-Dest:] header, so they are much more than informative metadata. If a new -feature requires a destination that's not in the destination table, please +feature requires a destination that's not in the +destination table, please file an issue to discuss. [[!CSP]] @@ -8484,9 +8485,11 @@ the same origin, in which case set your request's mode to "cors". If your feature is not web-exposed, or you think there is another reason for it to fetch cross-origin resources without CORS, please file an issue -to discuss. For cross-origin requests, also determines if credentials are to be -included with the requests, in which case set your request's -credentials mode to "include", +to discuss. + +

For cross-origin requests, also determines if credentials are to be included with +the requests, in which case set your request's credentials mode to +"include",

Figure out if your fetch needs to be reported to [[RESOURCE-TIMING inline]], and with which initiator type. By passing an initiator type to the @@ -8495,8 +8498,8 @@ fetch is done and the response is fully downloaded. [[RESOURCE-TIM

If your request requires additional HTTP headers, set its header list to a header list that contains those headers, e.g. -« (`My-Header-Name`, `My-Header-Value`) ». Note that sending custom headers may -have implications, such as requiring a CORS-preflight fetch, so handle with care. +« (`My-Header-Name`, `My-Header-Value`) ». Note that sending custom +headers may have implications, such as requiring a CORS-preflight fetch, so handle with care.

If you want to override the default caching mechanism, e.g. disable caching for this request, set the request's cache mode to a value other than From f028f4bf27804aaa5d5a274a6bd5bc90fe747557 Mon Sep 17 00:00:00 2001 From: Noam Rosenthal Date: Wed, 18 Jan 2023 08:23:04 +0200 Subject: [PATCH 19/25] Update fetch.bs Co-authored-by: Domenic Denicola --- fetch.bs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/fetch.bs b/fetch.bs index 8165e88c3..805b8f390 100644 --- a/fetch.bs +++ b/fetch.bs @@ -8462,7 +8462,7 @@ to discuss. [[!CSP]]

Set your request's client to the environment settings object you're operating in. Web-exposed APIs are generally defined with -the [[WEBIDL inline]], for which every object that implements an interface has a +Web IDL, for which every object that implements an interface has a relevant settings object you can use. For example, a request associated with a DOM element would set the request's client to the element's node document's relevant settings object. All features that are directly From baf471f5a3279175713dccc9b922f99786526212 Mon Sep 17 00:00:00 2001 From: Noam Rosenthal Date: Wed, 18 Jan 2023 08:23:14 +0200 Subject: [PATCH 20/25] Update fetch.bs Co-authored-by: Domenic Denicola --- fetch.bs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/fetch.bs b/fetch.bs index 805b8f390..407470d74 100644 --- a/fetch.bs +++ b/fetch.bs @@ -8475,7 +8475,7 @@ without relying on a current {{Window}} or {{Worker}}, leave requestpolicy container, service-workers mode, and referrer to appropriate values instead, e.g. by copying them from the environment settings object ahead of time. In these more advanced cases, make sure the -details of how your fetch handles Content Security Place and +details of how your fetch handles Content Security Place and referrer policy are fleshed out. Also make sure you handle concurrency, as callbacks would be posted on a parallel queue. [[!REFERRER]] [[!CSP]] From 03ad3e67876ed362e72d3a2e45a7dac56e0fbf5a Mon Sep 17 00:00:00 2001 From: Noam Rosenthal Date: Wed, 18 Jan 2023 08:23:27 +0200 Subject: [PATCH 21/25] Update fetch.bs Co-authored-by: Domenic Denicola --- fetch.bs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/fetch.bs b/fetch.bs index 407470d74..2cbc6e447 100644 --- a/fetch.bs +++ b/fetch.bs @@ -8476,7 +8476,7 @@ without relying on a current {{Window}} or {{Worker}}, leave requestreferrer to appropriate values instead, e.g. by copying them from the environment settings object ahead of time. In these more advanced cases, make sure the details of how your fetch handles Content Security Place and -referrer policy are fleshed out. Also make sure you handle concurrency, as callbacks +referrer policy are fleshed out. Also make sure you handle concurrency, as callbacks (see [[#fetch-elsewhere-fetch]]) would be posted on a parallel queue. [[!REFERRER]] [[!CSP]]

Think through the way you intend to handle cross-origin resources. Some features may only work in From 389f0f207e26029357331217efe2ea5a58b21528 Mon Sep 17 00:00:00 2001 From: Noam Rosenthal Date: Wed, 18 Jan 2023 08:23:37 +0200 Subject: [PATCH 22/25] Update fetch.bs Co-authored-by: Domenic Denicola --- fetch.bs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/fetch.bs b/fetch.bs index 2cbc6e447..e1d43ea1d 100644 --- a/fetch.bs +++ b/fetch.bs @@ -8505,7 +8505,7 @@ headers may have implications, such as requiring a CORS-preflight fetch, request, set the request's cache mode to a value other than "default". -

Determine if your request should support redirects. If it doesn't, set its +

Determine whether you want your request to support redirects. If you don't, set its redirect mode to "error".

Browse through the rest of the parameters for request to see if something else is From 696b455bc3486ba20c5a0178edbfdc496e00946e Mon Sep 17 00:00:00 2001 From: Noam Rosenthal Date: Wed, 18 Jan 2023 08:25:39 +0200 Subject: [PATCH 23/25] Remove unnecessary table changes --- fetch.bs | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/fetch.bs b/fetch.bs index e1d43ea1d..2561e0fa9 100644 --- a/fetch.bs +++ b/fetch.bs @@ -1704,10 +1704,10 @@ and "webidentity" as fetches with those destinations skip service w not always relevant and might require different behavior.

-

The following table llustrates the relationship between a - request's initiator, destination, CSP - directives, and features. It is not exhaustive with respect to features. Features need to have the - relevant values defined in their respective standards. +

The following table illustrates the relationship between a request's + initiator, destination, CSP directives, and features. It is + not exhaustive with respect to features. Features need to have the relevant values defined in their + respective standards.

From db14cacb4878671a4de3c688852b26b9ce41cd2d Mon Sep 17 00:00:00 2001 From: Noam Rosenthal Date: Wed, 18 Jan 2023 08:25:24 +0200 Subject: [PATCH 24/25] Update fetch.bs Co-authored-by: Domenic Denicola --- fetch.bs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/fetch.bs b/fetch.bs index 2561e0fa9..a7b5b4954 100644 --- a/fetch.bs +++ b/fetch.bs @@ -8466,7 +8466,7 @@ Web IDL, for which every object that implements an interface has a relevant settings object you can use. For example, a request associated with a DOM element would set the request's client to the element's node document's relevant settings object. All features that are directly -web-exposed by JavaScript, HTML, CSS, or other Document subresources should have A +web-exposed by JavaScript, HTML, CSS, or other {{Document}} subresources should have a client.

If your fetching is not directly web-exposed, e.g. it is sent in the background From dd89623a3ee6c60b94745e0df2c9166eb419105a Mon Sep 17 00:00:00 2001 From: Anne van Kesteren Date: Thu, 2 Mar 2023 05:01:52 -0800 Subject: [PATCH 25/25] nits --- fetch.bs | 50 +++++++++++++++++++++++++------------------------- 1 file changed, 25 insertions(+), 25 deletions(-) diff --git a/fetch.bs b/fetch.bs index a7b5b4954..3b8ad1e25 100644 --- a/fetch.bs +++ b/fetch.bs @@ -1703,7 +1703,7 @@ and "webidentity" as fetches with those destinations skip service w "xslt" as that too can cause script execution. It is not included in the list as it is not always relevant and might require different behavior. -

+

The following table illustrates the relationship between a request's initiator, destination, CSP directives, and features. It is not exhaustive with respect to features. Features need to have the relevant values defined in their @@ -8440,6 +8440,7 @@ correctly. This section aims to give some advice.

This is a work in progress. +

Setting up a request

The first step in fetching is to create a request, and populate its @@ -8447,37 +8448,36 @@ correctly. This section aims to give some advice.

Start by setting the request's URL and method, as defined by HTTP. If your `POST` or `PUT` request needs a -body, you set request's body to a byte sequence -as a body, or to a new body whose stream -is a {{ReadableStream}} you created. [[HTTP]] +body, you set request's body to a byte sequence, or to +a new body whose stream is a {{ReadableStream}} you created. [[HTTP]]

Choose your request's destination using the guidance in the destination table. Destinations affect -Content Security Policy and have other implications such as the -[:Sec-Fetch-Dest:] header, so they are much more than informative metadata. If a new -feature requires a destination that's not in the -destination table, please +Content Security Policy and have other implications such as the [:Sec-Fetch-Dest:] +header, so they are much more than informative metadata. If a new feature requires a +destination that's not in the destination table, +please file an issue -to discuss. [[!CSP]] +to discuss. [[CSP]]

Set your request's client to the environment settings object you're operating in. Web-exposed APIs are generally defined with Web IDL, for which every object that implements an interface has a -relevant settings object you can use. For example, a request associated with a -DOM element would set the request's client to the -element's node document's relevant settings object. All features that are directly -web-exposed by JavaScript, HTML, CSS, or other {{Document}} subresources should have a +relevant settings object you can use. For example, a request associated with an +element would set the request's client to the element's +node document's relevant settings object. All features that are directly web-exposed +by JavaScript, HTML, CSS, or other {{Document}} subresources should have a client. -

If your fetching is not directly web-exposed, e.g. it is sent in the background +

If your fetching is not directly web-exposed, e.g., it is sent in the background without relying on a current {{Window}} or {{Worker}}, leave request's client as null and set the request's origin, policy container, service-workers mode, and -referrer to appropriate values instead, e.g. by copying them from the +referrer to appropriate values instead, e.g., by copying them from the environment settings object ahead of time. In these more advanced cases, make sure the -details of how your fetch handles Content Security Place and -referrer policy are fleshed out. Also make sure you handle concurrency, as callbacks (see [[#fetch-elsewhere-fetch]]) -would be posted on a parallel queue. [[!REFERRER]] [[!CSP]] +details of how your fetch handles Content Security Policy and +referrer policy are fleshed out. Also make sure you handle concurrency, as callbacks +(see [[#fetch-elsewhere-fetch]]) would be posted on a parallel queue. [[REFERRER]] [[CSP]]

Think through the way you intend to handle cross-origin resources. Some features may only work in the same origin, in which case set your request's mode to @@ -8489,19 +8489,19 @@ to discuss.

For cross-origin requests, also determines if credentials are to be included with the requests, in which case set your request's credentials mode to -"include", +"include". -

Figure out if your fetch needs to be reported to [[RESOURCE-TIMING inline]], and with which +

Figure out if your fetch needs to be reported to Resource Timing, and with which initiator type. By passing an initiator type to the request, reporting to Resource Timing will be done automatically once the -fetch is done and the response is fully downloaded. [[RESOURCE-TIMING]] +fetch is done and the response is fully downloaded. [[RESOURCE-TIMING]]

If your request requires additional HTTP headers, set its header list to -a header list that contains those headers, e.g. -« (`My-Header-Name`, `My-Header-Value`) ». Note that sending custom -headers may have implications, such as requiring a CORS-preflight fetch, so handle with care. +a header list that contains those headers, e.g., « (`My-Header-Name`, +`My-Header-Value`) ». Sending custom headers may have implications, such as requiring a +CORS-preflight fetch, so handle with care. -

If you want to override the default caching mechanism, e.g. disable caching for this +

If you want to override the default caching mechanism, e.g., disable caching for this request, set the request's cache mode to a value other than "default".