Re: [whatwg/fetch] Editorial: Reword how-to section to explain how to use callbacks & controller (PR #1614)

@domenic commented on this pull request.

Lots of editorial nits... please keep these sorts of things in mind for self-review in the future.

> -  specific flow with this algorithm to get the intended behavior. They should compute the
-  appropriate <a for=response>location URL</a>, and if it is non-null or failure, then they should
-  call <a for="fetch controller">process the next manual redirect</a>. This will result in
-  <a for=fetch><i>processResponse</i></a> being called again, with the next <a for=/>response</a>
-  in the redirect chain.
-
- <dt><a for=fetch><i>processResponseEndOfBody</i></a>
- <dd><p>Takes an algorithm that will be passed a <a for=/>response</a>. Indicates the network is
- done transmitting the response. This does not read <a for=/>response</a>'s
- <a for=response>body</a>.
+  <p>This is the most common way in which clients handle a <a for=/>response</a>, for example
+  <a lt="fetch a classic script">scripts</a> and <a lt="fetch a style resource">style resources</a>.
+  The <a for=/>response</a>'s <a for=response>body</a> is obtained in its entirety into a
+  <a>byte sequence</a>, and then processed by the client.
+
+  <p>To process a <a for=/>response</a> upon completion, pass an algorithm to the

```suggestion
  <p>To process a <a for=/>response</a> upon completion, pass an algorithm as the
```

> -  call <a for="fetch controller">process the next manual redirect</a>. This will result in
-  <a for=fetch><i>processResponse</i></a> being called again, with the next <a for=/>response</a>
-  in the redirect chain.
-
- <dt><a for=fetch><i>processResponseEndOfBody</i></a>
- <dd><p>Takes an algorithm that will be passed a <a for=/>response</a>. Indicates the network is
- done transmitting the response. This does not read <a for=/>response</a>'s
- <a for=response>body</a>.
+  <p>This is the most common way in which clients handle a <a for=/>response</a>, for example
+  <a lt="fetch a classic script">scripts</a> and <a lt="fetch a style resource">style resources</a>.
+  The <a for=/>response</a>'s <a for=response>body</a> is obtained in its entirety into a
+  <a>byte sequence</a>, and then processed by the client.
+
+  <p>To process a <a for=/>response</a> upon completion, pass an algorithm to the
+  <a for=fetch><i>processResponseConsumeBody</i></a> argument of <a for/>fetch</a>. The given
+  algorithm is passed a <a for=/>response</a> and the null, failure, or a <a>byte sequence</a>.

```suggestion
  algorithm is passed a <a for=/>response</a> and null, failure, or a <a>byte sequence</a>.
```

>  
- <dt><a for=fetch><i>processResponseConsumeBody</i></a>
+ <dt>Headers first, then Chunk-by-chunk

```suggestion
 <dt>Headers first, then chunk-by-chunk
```

> -
-   <dt>failure
-   <dd>Attempting to <a for=body>fully read</a> the contents of the <a for=/>response</a>'s
-   <a for=response>body</a> failed, e.g., due to an I/O error.
-
-   <dt>a <a>byte sequence</a>
-   <dd><a for=body>Fully reading</a> the contents of the <a for=/>response</a>'s
-   <a for=response>body</a> succeeded.
-  </dl>
-
-  <p class=warning>A standard that uses this argument cannot operate on <a for=/>response</a>'s
-  <a for=response>body</a> itself as providing this argument will cause it to be read and it can be
-  read only once.
+  <p>In some cases, for example when playing video or progressively loading images, clients might
+  want to stream the response, and process it one chunk at a time. The <a for=/>response</a> is
+  handed over to the Fetch caller once the headers are processed, and the caller

```suggestion
  handed over to the fetch caller once the headers are processed, and the caller
```

> -
-   <dt>a <a>byte sequence</a>
-   <dd><a for=body>Fully reading</a> the contents of the <a for=/>response</a>'s
-   <a for=response>body</a> succeeded.
-  </dl>
-
-  <p class=warning>A standard that uses this argument cannot operate on <a for=/>response</a>'s
-  <a for=response>body</a> itself as providing this argument will cause it to be read and it can be
-  read only once.
+  <p>In some cases, for example when playing video or progressively loading images, clients might
+  want to stream the response, and process it one chunk at a time. The <a for=/>response</a> is
+  handed over to the Fetch caller once the headers are processed, and the caller
+  continues from there.
+
+  <p>To process a <a for=/>response</a> chunk-by-chunk, pass an algorithm to the
+  <a for=fetch><i>processResponse</i></a> argument of <a for/>fetch</a>. The given

```suggestion
  <a for=fetch><i>processResponse</i></a> argument of <a for=/>fetch</a>. The given
```

> -  <p class=warning>A standard that uses this argument cannot operate on <a for=/>response</a>'s
-  <a for=response>body</a> itself as providing this argument will cause it to be read and it can be
-  read only once.
+  <p>In some cases, for example when playing video or progressively loading images, clients might
+  want to stream the response, and process it one chunk at a time. The <a for=/>response</a> is
+  handed over to the Fetch caller once the headers are processed, and the caller
+  continues from there.
+
+  <p>To process a <a for=/>response</a> chunk-by-chunk, pass an algorithm to the
+  <a for=fetch><i>processResponse</i></a> argument of <a for/>fetch</a>. The given
+  algorithm is passed a <a for=/>response</a> when the response's headers have been
+  received and is responsible for reading the <a for=/>response</a>'s
+  <a for=response>body</a>'s <a for=body>stream</a> in order to download the rest
+  of the response. For convenience, you may also pass an algorithm to the
+  <a for=fetch><i>processResponseEndOfBody</i></a> argument, which is called once you have finished
+  obtaining the response and its <a for=response>body</a>. Note that unlike

Maybe "fully reading the response's body"? I don't know what it means to "obtain the response and its body".

You keep using "obtain" below as well... I think you read bodies, you don't obtain them.

I see @annevk seems to be advocating for "obtain" though, so maybe I'm off-base?

> -  read only once.
+  <p>In some cases, for example when playing video or progressively loading images, clients might
+  want to stream the response, and process it one chunk at a time. The <a for=/>response</a> is
+  handed over to the Fetch caller once the headers are processed, and the caller
+  continues from there.
+
+  <p>To process a <a for=/>response</a> chunk-by-chunk, pass an algorithm to the
+  <a for=fetch><i>processResponse</i></a> argument of <a for/>fetch</a>. The given
+  algorithm is passed a <a for=/>response</a> when the response's headers have been
+  received and is responsible for reading the <a for=/>response</a>'s
+  <a for=response>body</a>'s <a for=body>stream</a> in order to download the rest
+  of the response. For convenience, you may also pass an algorithm to the
+  <a for=fetch><i>processResponseEndOfBody</i></a> argument, which is called once you have finished
+  obtaining the response and its <a for=response>body</a>. Note that unlike
+  <a for=fetch><i>processResponseConsumeBody</i></a>, passing the
+  <a for=fetch><i>processResponse</i></a> or  <a for=fetch><i>processResponseEndOfBody</i></a>

```suggestion
  <a for=fetch><i>processResponse</i></a> or <a for=fetch><i>processResponseEndOfBody</i></a> arguments
```

> +  continues from there.
+
+  <p>To process a <a for=/>response</a> chunk-by-chunk, pass an algorithm to the
+  <a for=fetch><i>processResponse</i></a> argument of <a for/>fetch</a>. The given
+  algorithm is passed a <a for=/>response</a> when the response's headers have been
+  received and is responsible for reading the <a for=/>response</a>'s
+  <a for=response>body</a>'s <a for=body>stream</a> in order to download the rest
+  of the response. For convenience, you may also pass an algorithm to the
+  <a for=fetch><i>processResponseEndOfBody</i></a> argument, which is called once you have finished
+  obtaining the response and its <a for=response>body</a>. Note that unlike
+  <a for=fetch><i>processResponseConsumeBody</i></a>, passing the
+  <a for=fetch><i>processResponse</i></a> or  <a for=fetch><i>processResponseEndOfBody</i></a>
+  does not guarantee that the response will be fully obtained, and callers are responsible to
+  obtain it themselves.
+
+  <p>The <a for=fetch><i>processResponse</i></a> is also useful for handling the

```suggestion
  <p>The <a for=fetch><i>processResponse</i></a> argument is also useful for handling the
```

> +  <p>This is the most common way in which clients handle a <a for=/>response</a>, for example
+  <a lt="fetch a classic script">scripts</a> and <a lt="fetch a style resource">style resources</a>.
+  The <a for=/>response</a>'s <a for=response>body</a> is obtained in its entirety into a
+  <a>byte sequence</a>, and then processed by the client.
+
+  <p>To process a <a for=/>response</a> upon completion, pass an algorithm to the
+  <a for=fetch><i>processResponseConsumeBody</i></a> argument of <a for/>fetch</a>. The given
+  algorithm is passed a <a for=/>response</a> and the null, failure, or a <a>byte sequence</a>.
+  The second argument would be null if there was a <a>network error</a>, failure if there was an
+  error while downloading, or a <a>byte sequence</a> representing the successfully obtained
+  <a for=response>body</a>.
+
+  <div id=example-callback-upon-completion class=example>
+   <ol>
+    <li><p>Let <var>request</var> be a <a for=/>request</a> whose <a for=request>URL</a> is
+    "<code>https://stuff.example.com</code>", and whose <a for=request>client</a> is <a>this</a>'s

```suggestion
    <code>https://stuff.example.com</code>, and whose <a for=request>client</a> is <a>this</a>'s
```

>  
- <dt><a for=fetch><i>useParallelQueue</i></a>
- <dd><p>Takes a <a for=/>boolean</a> that defaults to false. Indicates where the algorithms passed
- as arguments will be invoked. Hopefully most standards will not need this.
+ <dt>Ignore the response
+ <dd>
+  <p>In some cases, there is no need for a <a for=/>response</a> at all, e.g., in the case of
+  <code>navigator.sendBeacon()</code>. Processing a response and passing callbacks to

```suggestion
  {{Navigator/sendBeacon()|navigator.sendBeacon()}}. Processing a response and passing callbacks to
```

>  
- <dt><a for=fetch><i>useParallelQueue</i></a>
- <dd><p>Takes a <a for=/>boolean</a> that defaults to false. Indicates where the algorithms passed
- as arguments will be invoked. Hopefully most standards will not need this.
+ <dt>Ignore the response
+ <dd>
+  <p>In some cases, there is no need for a <a for=/>response</a> at all, e.g., in the case of
+  <code>navigator.sendBeacon()</code>. Processing a response and passing callbacks to
+  <a for=/>fetch</a> is optional, so omitting the callback would <a for=/>fetch</a> without
+  expecting a response. In such cases, the <a for=/>response</a>'s <a for=response>body</a>'s
+  <a for=body>stream</a> will be discarded, and the caller does not have to worry about downloading
+  the contents unnecessarily.
+
+  <p id=example-no-callback class=example><a for=/>Fetch</a> a <a for=/>request</a> whose
+  <a for=request>URL</a> is <code>https://fire-and-forget.example.com</code>

```suggestion
  <a for=request>URL</a> is <code>https://fire-and-forget.example.com</code>,
```

> +<a for=fetch><i>processRequestEndOfBody</i></a> notify the client of request body uploading
+progress.
+
+<p>Note that the <a for=/>fetch</a> operation starts in the same thread from which it was called,
+and then breaks off to run its internal operations <a>in parallel</a>. The aforementioned callbacks
+are posted to a given <a for=/>event loop</a> which is, by default, the
+<a for=request>client</a>'s <a for="environment settings object">global object</a>. To process
+responses <a>in parallel</a> and handle interactions with the main thread by yourself,
+<a for=/>fetch</a> with <a for=fetch><i>useParallelQueue</i></a> set to true.
+
+
+<h3 id=fetch-elsewhere-ongoing>Manipulating an ongoing fetch</h3>
+
+<p>To manipulate a <a for=/>fetch</a> operation that has already started, use the
+<a for=/>fetch controller</a> returned by calling <a for=/>fetch</a>. For example, you may
+<a for="fetch controller">Abort</a> the <a>fetch controller</a> due the user or page logic, or

```suggestion
<a for="fetch controller">abort</a> the <a>fetch controller</a> due the user or page logic, or
```

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

Message ID: <whatwg/fetch/pull/1614/review/1362147275@github.com>