Re: [whatwg/fetch] Editorial: Add prose about constructing a request (PR #1585)

@domenic commented on this pull request.



> @@ -1694,10 +1697,10 @@ and "<code>webidentity</code>" as fetches with those destinations skip service w
 not always relevant and might require different behavior.
 
 <div class=note>
- <p>The following table illustrates the relationship between a <a for=/>request</a>'s
- <a for=request>initiator</a>, <a for=request>destination</a>, CSP directives, and features. It is
- not exhaustive with respect to features. Features need to have the relevant values defined in their
- respective standards.
+ <p>The following <dfn lt="destination table">table</dfn> illustrates the relationship between a

I would either make this `<dfn>destination table</dfn>`, or not make it a `<dfn>` and instead just add an `id=""` to the note. The latter seems a bit cleaner, as having a definition inside a non-normative section is weird.

> @@ -8385,6 +8388,83 @@ correctly. This section aims to give some advice.
 
 <p class=XXX>This is a work in progress.
 
+<h3 id=fetch-elsewhere-request>Populating a request</h3>
+
+<p>The first step in <a for=/>fetching</a> is to create a <a for=/>request</a>, and populate its
+<a for=struct>items</a>.
+
+<p>Start by setting the <a for=/>request</a>'s <a for=request>URL</a> and <a for=request>method</a>,
+as defined by HTTP. If your `<code>POST</code>` or `<code>PUT</code>` <a for=/>request</a> needs a
+body, you can assign or stream it to <a for=/>request</a>'s <a for=request>body</a>. [[HTTP]]

"you can assign or stream it" is confusing. How would you stream it?

I think the most common pattern here will be to use a byte sequence as the body, using the helper we recently defined: https://whatpr.org/fetch/1585.html#byte-sequence-as-a-body . I'd suggest referencing that as the primary method, and mentioning you can construct a new [=body=] for advanced cases.

> @@ -8385,6 +8388,83 @@ correctly. This section aims to give some advice.
 
 <p class=XXX>This is a work in progress.
 
+<h3 id=fetch-elsewhere-request>Populating a request</h3>
+
+<p>The first step in <a for=/>fetching</a> is to create a <a for=/>request</a>, and populate its
+<a for=struct>items</a>.
+
+<p>Start by setting the <a for=/>request</a>'s <a for=request>URL</a> and <a for=request>method</a>,
+as defined by HTTP. If your `<code>POST</code>` or `<code>PUT</code>` <a for=/>request</a> needs a
+body, you can assign or stream it to <a for=/>request</a>'s <a for=request>body</a>. [[HTTP]]
+
+<p>Choose your <a for=/>request</a>'s <a for=request>destination</a> using the guidance in the
+<a>destination table</a>. <a for=request>destinations</a> affect

```suggestion
<a>destination table</a>. <a for=request>Destinations</a> affect
```

> @@ -8385,6 +8388,83 @@ correctly. This section aims to give some advice.
 
 <p class=XXX>This is a work in progress.
 
+<h3 id=fetch-elsewhere-request>Populating a request</h3>
+
+<p>The first step in <a for=/>fetching</a> is to create a <a for=/>request</a>, and populate its
+<a for=struct>items</a>.
+
+<p>Start by setting the <a for=/>request</a>'s <a for=request>URL</a> and <a for=request>method</a>,
+as defined by HTTP. If your `<code>POST</code>` or `<code>PUT</code>` <a for=/>request</a> needs a
+body, you can assign or stream it to <a for=/>request</a>'s <a for=request>body</a>. [[HTTP]]
+
+<p>Choose your <a for=/>request</a>'s <a for=request>destination</a> using the guidance in the
+<a>destination table</a>. <a for=request>destinations</a> affect
+<cite>Content Security Policy</cite> and have other implications such as the
+`<code>sec-fetch-dest</code>` header, so they are much more than informative metadata. If a new

```suggestion
[:Sec-Fetch-Dest:] header, so they are much more than informative metadata. If a new
```

> +file an issue in the <a href=https://github.com/whatwg/fetch/issues>Fetch Github repository</a> to
+discuss. [[!CSP]]

Usually we do these as `<a href="https://github.com/whatwg/fetch/issues/new?title=What%20destination%20should%20my%20feature%20use">file an issue</a> to discuss`.

> +
+<p>Choose your <a for=/>request</a>'s <a for=request>destination</a> using the guidance in the
+<a>destination table</a>. <a for=request>destinations</a> affect
+<cite>Content Security Policy</cite> and have other implications such as the
+`<code>sec-fetch-dest</code>` header, so they are much more than informative metadata. If a new
+feature requires a <a for=request>destination</a> that's not in the <a>destination table</a>, please
+file an issue in the <a href=https://github.com/whatwg/fetch/issues>Fetch Github repository</a> to
+discuss. [[!CSP]]
+
+<p>Set your <a for=/>request</a>'s <a for=request>client</a> to the
+<a>environment settings object</a> you're operating in. Web-exposed APIs are generally defined with
+the [[WEBIDL inline]], for which every object that implements an <a>interface</a> has a
+<a>relevant settings object</a> you can use. For example, a <a for=/>request</a> associated with a
+DOM <a for=/>element</a> would set the <a for=/>request</a>'s <a for=request>client</a> to the
+element's <a>node document</a>'s <a>relevant settings object</a>. All features that are directly
+web-exposed by JavaScript, HTML, CSS, or other <code>Document</code> subresources should have A

```suggestion
web-exposed by JavaScript, HTML, CSS, or other {{Document}} subresources should have a
```

> +
+<p>Set your <a for=/>request</a>'s <a for=request>client</a> to the
+<a>environment settings object</a> you're operating in. Web-exposed APIs are generally defined with
+the [[WEBIDL inline]], for which every object that implements an <a>interface</a> has a
+<a>relevant settings object</a> you can use. For example, a <a for=/>request</a> associated with a
+DOM <a for=/>element</a> would set the <a for=/>request</a>'s <a for=request>client</a> to the
+element's <a>node document</a>'s <a>relevant settings object</a>. All features that are directly
+web-exposed by JavaScript, HTML, CSS, or other <code>Document</code> subresources should have A
+<a for=request>client</a>.
+
+<p>If your <a for=/>fetching</a> is not directly web-exposed, e.g. it is sent in the background
+without relying on a current {{Window}} or {{Worker}}, leave <a for=/>request</a>'s
+<a for=request>client</a> as null and set the <a for=/>request</a>'s <a for=request>origin</a>,
+<a for=request>policy container</a>, and <a for=request>referrer</a> to appropriate values instead,
+e.g. by copying them from the <a>environment settings object</a> ahead of time. In these more
+advanced cases, make sure the details of how your fetch handles <cite>Content Security Place</cote>

```suggestion
advanced cases, make sure the details of how your fetch handles <cite>Content Security Policy</cite>
```

> +<p>If your <a for=/>fetching</a> is not directly web-exposed, e.g. it is sent in the background
+without relying on a current {{Window}} or {{Worker}}, leave <a for=/>request</a>'s
+<a for=request>client</a> as null and set the <a for=/>request</a>'s <a for=request>origin</a>,
+<a for=request>policy container</a>, and <a for=request>referrer</a> to appropriate values instead,
+e.g. by copying them from the <a>environment settings object</a> ahead of time. In these more
+advanced cases, make sure the details of how your fetch handles <cite>Content Security Place</cote>
+and <a for=/>referrer policy</a> are fleshed out. Also make sure you handle concurrency, as
+callbacks would be posted on a <a>parallel queue</a>. [[!REFERRER]] [[!CSP]]
+
+<p>Think through the way you intend to handle cross-origin resources. Some features may only work in
+the <a>same origin</a>, in which case set your <a for=/>request</a> <a for=request>mode</a> to
+"<code>same-origin</code>". Otherwise, new web-exposed features should almost always set their
+<a for=request>mode</a> to "<code>cors</code>". 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
+<a href=https://github.com/whatwg/fetch>Fetch Standard</a>.

Similar suggestion for issue-filing markup.

> +callbacks would be posted on a <a>parallel queue</a>. [[!REFERRER]] [[!CSP]]
+
+<p>Think through the way you intend to handle cross-origin resources. Some features may only work in
+the <a>same origin</a>, in which case set your <a for=/>request</a> <a for=request>mode</a> to
+"<code>same-origin</code>". Otherwise, new web-exposed features should almost always set their
+<a for=request>mode</a> to "<code>cors</code>". 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
+<a href=https://github.com/whatwg/fetch>Fetch Standard</a>.
+
+<p>Figure out if your fetch needs to be reported to [[RESOURCE-TIMING inline]], and with which
+<a for=request>initiator type</a>. By passing an <a for=request>initiator type</a> to the
+<a for=/>request</a>, reporting to <cite>Resource Timing</cite> will be done automatically once the
+fetch is done and the <a for=/>response</a> is fully downloaded.  [[RESOURCE-TIMING]]
+
+<p>If your request requires additional HTTP headers, <a for="header list">append</a> them to your

Don't you actually just set the header list? Since header list is, as you recently explained to me, more like "extra header list"?

> +fetch is done and the <a for=/>response</a> is fully downloaded.  [[RESOURCE-TIMING]]
+
+<p>If your request requires additional HTTP headers, <a for="header list">append</a> them to your
+<a for=/>request</a>'s <a for=request>header list</a>. Note that sending custom headers may have
+implications, such as requiring a <a>CORS-preflight fetch</a>, so handle with care.
+
+<p>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:
+
+<dl>
+ <dt><a for=request>credentials mode</a>
+ <dd><p>Set to "<code>include</code>" if <a for=/>credentials</a> are to be sent with cross-origin
+ requests.
+
+ <dt><a for=request>integrity metadata</a>
+ <dd><p>Verifies that the content of the resource matches a pre-calculated string hash.

I think very few fetches will need this. (Only ones initiated by API surfaces which have an explicit place for web developers to put the integrity, basically.) Not sure if it's worth mentioning.

> +<dl>
+ <dt><a for=request>credentials mode</a>
+ <dd><p>Set to "<code>include</code>" if <a for=/>credentials</a> are to be sent with cross-origin
+ requests.
+
+ <dt><a for=request>integrity metadata</a>
+ <dd><p>Verifies that the content of the resource matches a pre-calculated string hash.
+
+ <dt><a for=request>referrer policy</a>
+ <dd><p>Allows using a different <a for=/>referrer policy</a> from the one provided by the
+ <a for=/>policy container</a>. [[!REFERRER]]
+
+ <dt><a for=request>cryptographic nonce metadata</a>
+ <dd><p>If the site's <cite>Content Security Policy</cite> specifies a <a grammar>nonce-source</a>
+ for this <a for=/>request</a>'s <a for=request>destination</a>, any request without a
+ [[CSP#match-nonce-to-source-list|matching]] value in this field will be blocked.

Ditto.

> + <dt><a for=request>integrity metadata</a>
+ <dd><p>Verifies that the content of the resource matches a pre-calculated string hash.
+
+ <dt><a for=request>referrer policy</a>
+ <dd><p>Allows using a different <a for=/>referrer policy</a> from the one provided by the
+ <a for=/>policy container</a>. [[!REFERRER]]
+
+ <dt><a for=request>cryptographic nonce metadata</a>
+ <dd><p>If the site's <cite>Content Security Policy</cite> specifies a <a grammar>nonce-source</a>
+ for this <a for=/>request</a>'s <a for=request>destination</a>, any request without a
+ [[CSP#match-nonce-to-source-list|matching]] value in this field will be blocked.
+</dl>
+
+<p>Browse through the rest of the parameters for <a for=/>request</a> 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 <a href="#requests">Requests</a> section of this standard.

Use bikeshed auto-links for the section here, if possible.

> + <dd><p>Verifies that the content of the resource matches a pre-calculated string hash.
+
+ <dt><a for=request>referrer policy</a>
+ <dd><p>Allows using a different <a for=/>referrer policy</a> from the one provided by the
+ <a for=/>policy container</a>. [[!REFERRER]]
+
+ <dt><a for=request>cryptographic nonce metadata</a>
+ <dd><p>If the site's <cite>Content Security Policy</cite> specifies a <a grammar>nonce-source</a>
+ for this <a for=/>request</a>'s <a for=request>destination</a>, any request without a
+ [[CSP#match-nonce-to-source-list|matching]] value in this field will be blocked.
+</dl>
+
+<p>Browse through the rest of the parameters for <a for=/>request</a> 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 <a href="#requests">Requests</a> section of this standard.
+

I think service-workers mode often needs configuring for the type of "exotic" fetches we've seen recently. Maybe mention it in the section on null-client fetches.

Similarly such fetches will probably need to set the referrer.

> + <dd><p>Verifies that the content of the resource matches a pre-calculated string hash.
+
+ <dt><a for=request>referrer policy</a>
+ <dd><p>Allows using a different <a for=/>referrer policy</a> from the one provided by the
+ <a for=/>policy container</a>. [[!REFERRER]]
+
+ <dt><a for=request>cryptographic nonce metadata</a>
+ <dd><p>If the site's <cite>Content Security Policy</cite> specifies a <a grammar>nonce-source</a>
+ for this <a for=/>request</a>'s <a for=request>destination</a>, any request without a
+ [[CSP#match-nonce-to-source-list|matching]] value in this field will be blocked.
+</dl>
+
+<p>Browse through the rest of the parameters for <a for=/>request</a> 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 <a href="#requests">Requests</a> section of this standard.
+
 

Cache mode and redirect mode are other parameters I sometimes see changed.

-- 
Reply to this email directly or view it on GitHub:
https://github.com/whatwg/fetch/pull/1585#pullrequestreview-1241579111
You are receiving this because you are subscribed to this thread.

Message ID: <whatwg/fetch/pull/1585/review/1241579111@github.com>