Skip to content

Be clearer about how Fetch creates ReadableStreams. #781

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 4 commits into from
Aug 10, 2018
Merged

Be clearer about how Fetch creates ReadableStreams. #781

Changes from 2 commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
c7893b6
Be clearer about the underlying source of a constructed ReadableStream.
jyasskin Aug 1, 2018
a3e0245
Call CreateReadableStream instead of the ReadableStream() constructor.
jyasskin Aug 3, 2018
b80938e
Replace strategy param with its contents.
jyasskin Aug 6, 2018
f514b21
initial nits
annevk Aug 9, 2018
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
43 changes: 35 additions & 8 deletions fetch.bs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1876,18 +1876,45 @@ with given <var>strategy</var>, <var>pull</var> action and <var>cancel</var> act
are optional, run these steps:

<ol>
<li><p>Let <var>init</var> be a new object.
<li><p>Let <var>startAlg</var> be an algorithm that returns <code>undefined</code>.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Personally I find it clearer just to write out "startAlgorithm" in full.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done.


<li><p>Set <var>init</var>["pull"] to a function that runs <var>pull</var> if <var>pull</var> is
given.
<li><p>Let <var>pullAlg</var> be an algorithm that returns:

<li><p>Set <var>init</var>["cancel"] to a function that runs <var>cancel</var> if
<var>cancel</var> is given.
<dl class=switch>
<dt>If <var>pull</var> is given
<dd>the result of [=promise-calling=] <var>pull</var>().
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@annevk usually objects to using the promises guide. However, I don't see much alternative except for copying the phrasing that the promises guide uses.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There's also https://streams.spec.whatwg.org/#promise-call, but it requires a non-undefined object parameter. @domenic, it looks like the underlying https://tc39.github.io/ecma262/#sec-call can take undefined there; would it make sense to allow that in PromiseCall()?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Very out-of-context question: What is the reasoning for objection to using the promises guide? Haven't read all of it, just curious (sorry this is not the best place).

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@domfarolino Possibly w3ctag/promises-guide#52.

I know of one trap in there: because aggregating promises uses Promise.all() it calls the current (not original) value of Promise.reject() which may have been replaced. This makes it unsafe to use in algorithms that are not re-entrant or are otherwise vulnerable to unexpected JS execution.There may be other traps I don't know about.

Having said that, we use it in the streams standard and I think it is fine if you use it with care.

<dt>Otherwise
<dd>[=a promise resolved with=] <code>undefined</code>.
</dl>

<li><p>Let <var>cancelAlg</var> be an algorithm that takes a <var>reason</var> and returns:
<dl class=switch>
<dt>If <var>cancel</var> is given
<dd>the result of [=promise-calling=] <var>cancel</var>(<var>reason</var>).
<dt>Otherwise
<dd>[=a promise resolved with=] <code>undefined</code>.
</dl>

<li><p>Let <var>stream</var> be the result of calling the initial value of {{ReadableStream}} as
constructor with <var>init</var> and <var>strategy</var> if given.
<li><p>Let <var>highWaterMark</var> be:
<dl class=switch>
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The need to unpack the strategy argument is unfortunate. If the reference in HTTP-Network-Fetch is the only usage, I would prefer to change that from the (scary) phrasing:

Let strategy be an object. The user agent may choose any object.

to something like

Let highWaterMark be a be a non-negative, non-NaN number, chosen by the user agent.
Let sizeAlgorithm be an algorithm that accepts chunk objects and returns a number, chosen by the user agent.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yep. I didn't do that because I'm nervous about other callers outside Fetch, but I could leave a note here about the previous state and expect them to update.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I've done this and added the note.

<dt>If <var>strategy</var> is given and <var>strategy</var>.<a spec=streams for="queuing
strategy">highWaterMark</a> exists
<dd><var>strategy</var>.<a spec=streams for="queuing strategy">highWaterMark</a>.
<dt>Otherwise
<dd><code>1</code>.
</dl>

<li><p>Let <var>sizeAlg</var> be:
<dl class=switch>
<dt>If <var>strategy</var> is given and <var>strategy</var>.<a idl spec=streams for="queuing
strategy" lt="size()">size</a> exists
<dd><var>strategy</var>.size.
<dt>Otherwise
<dd>an algorithm that returns <code>1</code>.
</dl>

<li><p>Return <var>stream</var>.
<li><p>Return [$CreateReadableStream$](<var>startAlg</var>, <var>pullAlg</var>,
<var>cancelAlg</var>, <var>highWaterMark</var>, <var>sizeAlg</var>).
</ol>

<p>To
Expand Down