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

@domenic commented on this pull request.

Still some nits.

> @@ -1693,11 +1696,11 @@ and "<code>webidentity</code>" as fetches with those destinations skip service w
 "<code>xslt</code>" 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.
 
-<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.
+<div class=note id="destination-table">
+ <p>The following table llustrates the relationship between a

This entire paragraph's diff seems unnecessary, and mostly just inserts a typo.

> +body, you set <a for=/>request</a>'s <a for=request>body</a> to a <a for=/>byte sequence</a>
+<a for="byte sequence">as a body</a>, or to a new <a for=/>body</a> whose <a for=body>stream</a>
+is a {{ReadableStream}} you created.  [[HTTP]]
+
+<p>Choose your <a for=/>request</a>'s <a for=request>destination</a> using the guidance in the
+<a href="#destination-table">destination table</a>. <a for=request>Destinations</a> affect
+<cite>Content Security Policy</cite> 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 <a for=request>destination</a> that's not in the
+<a href="#destination-table">destination table</a>, please
+<a href="https://github.com/whatwg/fetch/issues/new?title=What%20destination%20should%20my%20feature%20use">file an issue</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

```suggestion
Web IDL, for which every object that implements an <a>interface</a> has 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>, <a for=request>service-workers mode</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

```suggestion
details of how your fetch handles <cite>Content Security Place</cite> and
```

> +<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>, <a for=request>service-workers mode</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

```suggestion
<a for=/>referrer policy</a> are fleshed out. Also make sure you handle concurrency, as callbacks (see [[#fetch-elsewhere-fetch]])
```

> +
+<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, set its <a for=request>header list</a> to
+a <a for=/>header list</a> that contains those headers, e.g.
+« (`<code>My-Header-Name</code>`, `<code>My-Header-Value</code>`) ». Note that sending custom
+headers may have implications, such as requiring a <a>CORS-preflight fetch</a>, so handle with care.
+
+<p>If you want to override the default caching mechanism, e.g. disable caching for this
+<a for=/>request</a>, set the request's <a for=request>cache mode</a> to a value other than
+"<code>default</code>".
+
+<p>Determine if your request should support redirects. If it doesn't, set its

```suggestion
<p>Determine whether you want your request to support redirects. If you don't, set its
```

> +
+<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

Still missing this

-- 
Reply to this email directly or view it on GitHub:
https://github.com/whatwg/fetch/pull/1585#pullrequestreview-1252851058

You are receiving this because you are subscribed to this thread.

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