- From: Domenic Denicola <notifications@github.com>
- Date: Tue, 28 Mar 2023 19:10:52 -0700
- To: whatwg/fetch <fetch@noreply.github.com>
- Cc: Subscribed <subscribed@noreply.github.com>
- Message-ID: <whatwg/fetch/pull/1614/review/1362147275@github.com>
@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>
Received on Wednesday, 29 March 2023 02:11:05 UTC