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

@annevk commented on this pull request.

Thanks for your work on this!

There's two outstanding comments from @jyasskin as well that need to be addressed, though note that one is slightly incorrect with respect to URLs being strings.

Generally I would not talk about "downloading" here as that's its own term of art within the context of navigation. Fetch fetches or obtains.

To set expectations, this needs at least one more close look after these issues are addressed.

> @@ -8664,7 +8664,7 @@ to discuss. [[CSP]]
 <a>environment settings object</a> you're operating in. Web-exposed APIs are generally defined with
 Web IDL, 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 an
-<a for=/>element</a> would set the <a for=/>request</a>'s <a for=request>client</a> to the element's
+{{Element}} would set the <a for=/>request</a>'s <a for=request>client</a> to the element's

I prefer the lowercase non-code version.

> +<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
+<a for="fetch controller">terminate</a> it due to browser-internal circumstances.
+
+<p>In addition to terminating and aborting, callers may <a for="fetch controller">report timing</a>
+if this was not done automatically by passing the <a for=request>initiator type</a>, or
+<a for="fetch controller">extract full timing info</a> and handle it on the caller side (this is
+done only by navigations). The <a>fetch controller</a> is also used to
+<a for="fetch controller">process the next manual redirect</a> for <a for=/>requests</a> with
+<a for=request>redirect mode</a> set to "<code>manual</code>".
 
 <h2 id=acknowledgments class=no-num>Acknowledgments</h2>

Nit: eating newlines before this heading.

> @@ -8713,83 +8713,141 @@ relevant to you. The rest of the parameters are used less frequently, often for
 and they are documented in detail in the [[#requests]] section of this standard.
 
 
-<h3 id=fetch-elsewhere-fetch class=no-num>Invoking fetch</h3>
+<h3 id=fetch-elsewhere-fetch class=no-num>Processing Responses</h3>

Sentence case.

> -
-  <p>If the <a for=/>request</a>'s <a for=request>mode</a> is "<code>navigate</code>" and its
-  <a for=request>redirect mode</a> is "<code>manual</code>", then callers need to follow a very
-  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 downloaded in its entirety into a

s/downloaded/obtained/

>  
-<p>Aside from a <a for=/>request</a> the <a for=/>fetch</a> operation takes several optional
-arguments. For those arguments that take an algorithm: the algorithm will be called from a task (or
-in a <a for=/>parallel queue</a> if <a for=fetch><i>useParallelQueue</i></a> is true).
+<p>Once the <a for=/>request</a> is set up, determine how you would like to process the
+<a for=/>response</a>, and in particular at what stage you would like to receive a callback:

This now lacks the introduction that you need to invoke fetch. I think we should keep that as the text below refers to it.

> -  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 downloaded 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 accepts a <a for=/>response</a> and the final contents.

needs to accept two arguments: a response and null, failure, or a byte sequence*

Or the original phrasing of "is passed a response and ..." also works well.

> +  <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 downloaded 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 accepts a <a for=/>response</a> and the final contents.
+  The final contents could 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 downloaded <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
+    "https://stuff.example.com", and whose <a for=request>client</a> is <a>this</a>'s

A URL is not a string. So without the double quotes, but with `<code>`.

> - <dt><a for=fetch><i>processRequestBodyChunkLength</i></a>
- <dd><p>Takes an algorithm that will be passed the number of bytes that have been transmitted from
- the <a for=/>request</a>'s <a for=request>body</a>. The algorithm will be invoked for each
- transmitted chunk. Most standards will not need this.
-
- <dt><a for=fetch><i>processRequestEndOfBody</i></a>
- <dd><p>Takes an algorithm that will be passed nothing. Indicates <a for=/>request</a>'s
- <a for=request>body</a> has been transmitted. Most standards will not need this.
-
- <dt><a for=fetch><i>processEarlyHintsResponse</i></a>
- <dd><p>Takes an algorithm that will be passed a <a for=/>response</a> (whose
- <a for=response>status</a> is 103). Can only be used for navigations as defined by
- <cite>HTML</cite>. [[HTML]]
-
- <dt><a for=fetch><i>processResponse</i></a>
+ <dt>Upon Completion

Sentence case for these as well.

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

```suggestion
  <p>In some cases, there is no need for a <a for=/>response</a> at all, e.g., in the case of
```

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

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