Add Streams support

[annevk]

In 9224c4c#commitcomment-19169480 @jakearchibald @tyoshino @ricea are having a discussion about adding https://streams.spec.whatwg.org/ to the Encoding Standard that I'd prefer us to continue in this issue (and the eventual pull request). That will make it easier to track for other folks participating in this repository. Hope that's okay.

[inexorabletash]

I'd love PRs for https://github.com/inexorabletash/text-encoding too. hint hint

[ricea]

I think the first issue to resolve is whether the API should be

var stringReadable = byteReadable.pipeThrough(TextDecoder.stream());

or

var stringReadable = byteReadable.pipeThrough(new TextDecoder());

My spec patch currently implements the first one. The second one is clearly more readable, but it makes it unclear what this does:

var decoder = new TextDecoder();
decoder.decode(new Uint8Array([0xE0]), {stream: true});
setTimeout(() => decoder.decode(new Uint8Array([0xA0]), {stream: true}), 1);
var stringReadable = byteReadable.pipeThrough(decoder);

@jakearchibald in 9224c4c#commitcomment-19186596 suggested that decode() should throw if either the readable or writable streams are locked. This gives predictable behaviour: in the above example, the first call to decode() would work, and the byteReadable stream would have to start with a byte in the range 0xA0 to 0xBF. The second call to decode() would throw, because pipeThrough() has locked the writable member of decoder.

I expressed some other concerns about the second option in 9224c4c#commitcomment-19186596.

[annevk]

The main problem with the first option as I see is that stream() ends up creating an object there's no way to create through a constructor. And while we have some of that in the platform, the preference from the developer community is that we avoid such magical creation patterns.

As for the concern about sharing logic with Streams with the second option, that should be doable. We can refactor both standards as needed. That leaves the performance issue which I don't feel qualified to comment on.

[jakearchibald]

@ricea can you talk a bit more about the performance issue?

If the piped stream is enqueued using JS, won't there be a similar de-opt? What about:

const decoder = new TextDecoder();

jsCreatedStream.pipeTo(decoder.writable, {preventClose: true}).then(() => {
  return fetchStream.pipeThrough(decoder);
});

How would that be different from:

const decoder = new TextDecoder();

decoder.decode(whatever, {stream: true});
fetchStream.pipeThrough(decoder);

[ricea]

@jakearchibald Both ReadableStream and WritableStream contain a queue. A natural optimisation for TransformStream is to eliminate one or both of those queues. This works even if both ends of the pipe are JS. If either end of the pipe is an inbuilt stream then more exciting optimisations become possible.

The object returned by TextDecoder.stream() in my draft spec is an instance of TransformStream, so any optimisations that have been implemented for TransformStream automatically apply. I am assuming that TextDecoder will never be a subclass of TransformStream. Any optimisation that can be implemented for TransformStream can also be implemented for TextDecoder, but unless user agents carefully share implementation code with this in mind, optimisations applied to one will not automatically apply to the other.

Concretely speaking, in Chrome the implementation of TextDecoder is in C++ but TransformStream is due to be implemented in Javascript. My expectation is that general piping optimisations will apply to TextDecoder but optimisations specific to TransformStream are unlikely to be ported to TextDecoder unless there is specific demand.

I don't mean to suggest this is a showstopper. It is just something I am interested in feedback on.

With regards to:

jsCreatedStream.pipeTo(decoder.writable, {preventClose: true}).then(() => {
  return fetchStream.pipeThrough(decoder);
});

I can describe how I think it will work in the optimisation proof-of-concept that @tyoshino has been working on. The decoder stream starts out with a Javascript source, so it is in "visible side-effects" mode. Even after switching to reading from fetchStream it remains in that mode until the data from jsCreatedStream has been completely drained. At that point it can transparently switch to "full optimisation" mode. Hopefully @tyoshino will correct me if I've got this completely wrong.

[jakearchibald]

@ricea

Thanks for the detailed explanation!

I am assuming that TextDecoder will never be a subclass of TransformStream

It could be. If that isn't possible, there could be a behind-the-scenes TransformStream and its writable and readable are bound on TextDecoder. Turning TextDecoder into a full transform stream would be my preference, but maybe I'm missing the blocker.

Ideally .decode/.encode would be respecced to use the underlying transform stream. The tricky bit is (as far as I can tell) is allowing the legacy methods to synchronously return.

[annevk]

Either a subclass or shared implementation seems doable. Subclass might be workable here, but not sure it is for all objects that need to interoperate with streams in due course.

[domenic]

The main problem with the first option as I see is that stream() ends up creating an object there's no way to create through a constructor. And while we have some of that in the platform, the preference from the developer community is that we avoid such magical creation patterns.

There is a way to create it: it directly uses the TransformStream constructor. There's no magic going on here, just an algorithm for assembling the constructor arguments.

In general I think a clean break between the stream interface and the old interface would be preferable, instead of a confusing mismash which has both APIs on the same object, and which raises questions about what happens when you mix them. (Answerable questions, but the answers are not necessarily intuitive.)

[ricea]

I am leaning slightly towards the "overloaded class" approach because it will look better on a slide. In other words, this syntax:

var stringReadable = byteReadable.pipeThrough(new TextDecoder());

with .decode() throwing an exception if called when the stream is in use.

I think I can spec it relatively simply by delegating to a TransformStream. Whether or not to inherit from TransformStream can then be postponed to a separate discussion.

The spec for TransformStream is not ready yet, so we don't need to make a decision immediately. I expect it will be ready in the first half of November.

Incidentally, I made minor updates to the Stream patch at http://htmlpreview.github.io/?https://github.com/ricea/encoding-streams/blob/master/patch.html, however it still uses the TransformStream.stream() syntax.

[annevk]

Is it correct that this proposal automatically takes buffer reuse into account as stated in #69? If so, we should probably duplicate that issue against this one.

[domenic]

Hmm. I think right now we haven't quite integrated readable byte streams into transform streams. See whatwg/streams#601

[ricea]

Hmm. I think right now we haven't quite integrated readable byte streams into transform streams. See whatwg/streams#601

I had doubts whether byte support in TransformStream was useful when it didn't exist in WritableStream. But #69 provides a clear use-case.

[ricea]

I have updated the proposed patch for the spec to make the TextEncoder & TextDecoder objects behave as stream transformers directly as we discussed here. Internally they delegate to a TransformStream object which provides the glue logic.

http://htmlpreview.github.io/?https://github.com/ricea/encoding-streams/blob/master/patch.html

@yhirano identified an issue during review. Consider the following code:

let dec = new TextDecoder();
let writer = dec.writable.getWriter();
writer.write(incompleteByteSequence);
writer.releaseLock();
await doSomethingWith(dec.readable);
let what = dec.decode(moreBytes);

Here dec.decode() does not throw because the lock on writable was released. I am assuming that the lock on readable has also been released.

The issue is that the contents of what now depend on whether doSomethingWith() read from readable or not. TransformStream does not call transform() until a read happens, in order to respect backpressure[1]. If doSomethingWith() piped readable to a native stream it may be nondeterministic whether anything was read or not.

Our proposed solution is to make TextDecoder lock into a particular mode the first time decode() or the decode and enqueue chunk algorithm was called. Once it was locked into one mode attempting to use it the other way would be an error.

This doesn't make the above code deterministic, but it means that if incompleteByteSequence had indeed been processed then decode() would throw, which is hopefully better than producing garbage output.

Thoughts?

[1] This is a gross simplification.

[annevk]

Can't we lock the moment you invoke getWriter()?