Add ReadableByteStream definition

[tyoshino]

No description provided.

[tyoshino]

WIP

[domenic]

https://streams.spec.whatwg.org/branch-snapshots/readablebytestreamspec/ for preview. Has some minor errors. I will push an extra commit to fix those (but won't force-push in case you have work locally).

[domenic]

In terms of the MVP for helping MSE, I think we want:

• Complete class definitions
• AcquireReadableByteStreamReader(rbs) and ReadFromReadableByteStreamReader(reader, destView)
• The text sections filled in ("Readable Byte Streams" and "Using Readable Byte Streams").

I think it'd also be ideal to not have any known-inaccurate algorithms, and for the ones we're unsure on have a warning <div>.

[tyoshino]

Thanks for the advice. I've pushed one more commit. Yes, I found that dfn was missing for underlying byte stream but couldn't push the fixed one yesterday.

I tried to define ReadableByteStream without the default built-in queue. If it turns out to be not promising, I'll just revert them to just refer to ReadableStream's algorithms.

BTW, when I run ecmarkupify, npm complains like "... node_modules/ecmarkupify/package.json not found". Do you have any ideas what's happening?

[domenic]

BTW, when I run ecmarkupify, npm complains like "... node_modules/ecmarkupify/package.json not found". Do you have any ideas what's happening?

The only thing I can think of is make sure you are on a recent io.js and then do rm -rf node_modules && npm install. This should be done in the root, not in reference_implementation (which is a separate package).

[tyoshino]

Thanks! I didn't know I needed io.js. It works now.

[tyoshino]

Ready for review. This PR should also satisfy #312.

[domenic]

Will try to do review tonight or tomorrow morning.

What are your thoughts on a reference implementation/tests?

[domenic]

These informative sections don't seem quite complete. But, I can try my hand at expanding them.

[domenic]

OK, I guess I couldn't resist at least a high-level review.

I am a bit confused by the controller + underlying source model here. From what I can see, the idea is that pull() is called on each read, and each time it is called, you can call c.resolve(chunk) once. Is that the idea?

I thought though that ReadableByteStream was going to need an internal queue as well. Because what if someone doesn't read for a long time, and the kernel buffer starts getting full? Do we make underlying byte source implementers do their own buffering to handle that case?

Also I know we had a discussion in person which concluded that c.resolve(chunk) was better than return chunk or return promiseForChunk, mainly having to do with cancelation. Can you help remind me why that was important?

The resolve name is probably not the best but we can figure it out later. (Maybe it is fine but it feels like it's too tied to promise terminology, whereas promises are kind of more an implementation detail, that the underlying byte source should not need to know about.)

[domenic]

Hmm, this is complicated. With the queues and such. Could you summarize for me how it works? It looks similar to TeeReadableStream but I am betting there are important differences.

[tyoshino]

I am a bit confused by the controller + underlying source model here. From what I can see, the idea is that pull() is called on each read, and each time it is called, you can call c.resolve(chunk) once. Is that the idea?

Right. pull() is just a notification of read(). The user can call c.resolve(chunk) at any time.

The readable byte stream is kept as minimum as possible but able to represent invariants, constraints, semantics of the API surface completely. The controller is not designed considering usability. Maybe, I should not have added the controller API but only define abstract operations to manipulate the readable byte stream's state.

I thought though that ReadableByteStream was going to need an internal queue as well. Because what if someone doesn't read for a long time, and the kernel buffer starts getting full? Do we make underlying byte source implementers do their own buffering to handle that case?

The latter.

Also I know we had a discussion in person which concluded that c.resolve(chunk) was better than return chunk or return promiseForChunk, mainly having to do with cancelation. Can you help remind me why that was important?

You were imagining some example implementation of the underlying source where you're trying to encapsulate an async API that returns a promise. And you said that we basically want to return the promise (as-is or after some transform) than converting it to call to c.resolve(), etc.

The resolve name is probably not the best but we can figure it out later. (Maybe it is fine but it feels like it's too tied to promise terminology, whereas promises are kind of more an implementation detail, that the underlying byte source should not need to know about.)

Was using fulfill. Fulfill might be better as the streams are supposed to be enqueued non-promise values?

[domenic]

The readable byte stream is kept as minimum as possible but able to represent invariants, constraints, semantics of the API surface completely. The controller is not designed considering usability. Maybe, I should not have added the controller API but only define abstract operations to manipulate the readable byte stream's state.

I see. So we may want to make it clear that this is still undergoing revision. But the public API will be OK.

Do we make underlying byte source implementers do their own buffering to handle that case?

The latter.

This seems sad. Also I think we wanted to support buffering (in the non-BYOB case) to avoid "jitter"? Hmm.

You were imagining some example implementation of the underlying source where you're trying to encapsulate an async API that returns a promise. And you said that we basically want to return the promise (as-is or after some transform) than converting it to call to c.resolve(), etc.

Right, I remember the argument for using promises instead of c.resolve :). But I forget the argument for using c.resolve instead of promises. Sorry, I guess I was a bit unclear what my question was there.

Was using fulfill. Fulfill might be better as the streams are supposed to be enqueued non-promise values?

I meant more pick a verb that has nothing to do with promises. Looking through a thesaurus, here are some random options: answer, conclude, fill, finish, satisfy, produce, complete, finalize, respond.

---

Anyway, let's start merging stuff and iterating on it in further PRs and issues, using #300 as the central tracking issue once the dust settles. I think we should squash everything into a single commit that does the following:

• Remove ReadableByteStream reference implementation and tests
• Contains the contents of both this PR and Update byte stream spec #351

If this sounds good to you, let me know. If you are ready to go to sleep then I will do it (and file a few follow-up issues/PRs). Or if you want to take care of some other stuff first before we merge, or you want to work on the squashed commit yourself, then that's good too :).

[tyoshino]

Right, I remember the argument for using promises instead of c.resolve :). But I forget the argument for using c.resolve instead of promises. Sorry, I guess I was a bit unclear what my question was there.

IIRC, it was something like race between:

• the stream getting updated by the fulfillment/rejection callback set to the returned promise
• controller.close()

We were drawing timeline on a whiteboard to discuss this.

[domenic]

Yeah. I just wish we had captured it somewhere digital, haha.

[tyoshino]

If you are ready to go to sleep then I will do it (and file a few follow-up issues/PRs).

Thanks. I'm adding BYOB stuff in local copy but that doesn't block the work. I'm still in the office but wouldn't get time to do squashing, etc. before last train.

So, please :)

[domenic]

Merged as 5b47faa per plan at #343 (comment).