Skip to content

Commit

Permalink
Using fetch in other standards
Browse files Browse the repository at this point in the history
Closes #1306.
  • Loading branch information
annevk authored Oct 12, 2021
1 parent 6f37b51 commit fe28b66
Showing 1 changed file with 57 additions and 0 deletions.
57 changes: 57 additions & 0 deletions fetch.bs
Original file line number Diff line number Diff line change
Expand Up @@ -7879,6 +7879,63 @@ resource — for non-<a>CORS requests</a> as well as <a>CORS
requests</a> — and do not use `<code>Vary</code>`.


<h2 id=fetch-elsewhere class=no-num>Using fetch in other standards</h2>

<p>In its essence <a for=/>fetching</a> is an exchange of a <a for=/>request</a> for a
<a for=/>response</a>. In reality it is rather complex mechanism for standards to adopt and use
correctly. This section aims to give some advice.

<p class=warning>Always ask domain experts for review.

<p class=XXX>This is a work in progress.


<h3 id=fetch-elsewhere-fetch class=no-num>Invoking fetch</h3>

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

<dl>
<dt><a for=fetch><i>processRequestBody</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>processResponse</i></a>
<dd><p>Takes an algorithm that will be passed a <a for=/>response</a>. Indicates
<a for=/>response</a>'s <a for=response>header list</a> has been received and initialized. This
is primarily useful for standards that want to operate on <a for=/>response</a>'s
<a for=response>body</a>'s <a for=body>stream</a> directly.

<dt><a for=fetch><i>processResponseEndOfBody</i></a>
<dd>
<p>Takes an algorithm that will be passed a <a for=/>response</a> and null, failure, or a
<a>byte sequence</a>. This is useful for standards that wish to operate on the entire
<a for=/>response</a>'s <a for=response>body</a>, of which the result of reading it is supplied as
second argument.

<p>It might be surprising that a <a for=/>network error</a> will have null as second argument.

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

<dt><a for=fetch><i>processResponseDone</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>.

<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.
</dl>


<h2 id=acknowledgments class=no-num>Acknowledgments</h2>

<p>Thanks to
Expand Down

0 comments on commit fe28b66

Please sign in to comment.