WebSocketStream

[ricea]

こんにちはTAG!

I'm requesting a TAG review of:

• Name: WebSocketStream
• Specification URL: TBD, but API design is at: https://docs.google.com/document/d/1La1ehXw76HP6n1uUeks-WJGFgAnpX2tCjKts7QFJ57Y/edit
• Explainer (containing user needs and example code)¹: https://github.com/ricea/websocketstream-explainer/blob/master/README.md
• GitHub issues (if you prefer feedback filed there): https://github.com/ricea/websocketstream-explainer/issues
• Tests: TBD
• Primary contacts (and their relationship to the specification): ricea (primary author)

Further details:

• Relevant time constraints or deadlines: None at this time
• I have read and filled out the Self-Review Questionnare on Security and Privacy. The assessment is here.
• I have reviewed the TAG's API Design Principles
• The group where the work on this specification is: TBD

We recommend the explainer to be in Markdown. On top of the usual information expected in the explainer, it is strongly recommended to add:

• Links to major pieces of multi-stakeholder review or discussion of this specification:
• Links to major unresolved issues or opposition with this specification:

You should also know that...

This proposal is still in the early stages. I plan to implement it in Blink to gather feedback, but we won't necessarily ship it. There will be an origin trial to gauge interest from developers.

We'd prefer the TAG provide feedback as (please select one):

• open issues in our GitHub repo for each point of feedback
• open a single issue in our GitHub repo for the entire review
• leave review feedback as a comment in this issue and @-notify [github usernames]

---

Please preview the issue and check that the links work before submitting. In particular, if anything links to a URL which requires authentication (e.g. Google document), please make sure anyone with the link can access the document.

¹ For background, see our explanation of how to write a good explainer.

[ricea]

See also the review of the existing WebSocket API at #268.

[martinthomson]

@ricea, The underlying protocol supports large messages. How do you anticipate handling very large messages, such as ones that can't be backed by physical memory (or in the extreme, logical memory)? It seems like you don't get back pressure in that case.

Would it be better to provide a stream of streams, or use the fetch mixin for each chunk?

[ricea]

@martinthomson My tentative plan is to use a stream of streams. My concern is that this will be hard to understand and use, which is one reason why I'm not trying to tackle it yet.

Using the fetch mixin for each chunk is a really interesting idea. I think it has potential.

The way I see backpressure working with a stream-of-streams is that you have to read the whole of one message before it will give you another one. I think it's possible to explain and justify this with a stream-of-streams, but with a stream-of-bodies people might strongly object that they should be able to just discard the message without reading it. I'm not sure what to do about that.

[torgo]

Hi @ricea what is the intended venue for this work?

[dbaron]

I'm curious if there is or should be any relationship to the work on Web Transport (#389) -- e.g., if Web Transport is now looking at doing a more stream-based API -- should that be similar to or based on or converge with this?

[ricea]

@torgo What I've been discussing is removing the WebSocket parts from the Fetch Standard and HTML Standard and combining them into a new "WebSocket Standard". Then that would be a natural home for WebSocketStream.

I must admit I haven't given much consideration to a plan B.

[ricea]

I'm curious if there is or should be any relationship to the work on Web Transport (#389) -- e.g., if Web Transport is now looking at doing a more stream-based API -- should that be similar to or based on or converge with this?

I expect they will be similar. WebTransport has a lot more variables which may dictate a different API shape. I hope that experience with WebSocketStream will inform the design of WebTransport.

[martinthomson]

If it were me, any work in this area might want to be chartered alongside (as in the same group) as what does WebTransport. Assuming that both are done, that is. I would want the same API in both cases.

As for stream of streams, we don't want to expose the GC, so we would need to have each body drained. Most of the accessors aren't a problem, but if you get a stream, then that stream would need to be exhausted before the next message can appear.

[ricea]

There are now some tests at https://github.com/web-platform-tests/wpt/tree/master/websockets/stream-tentative. I need to add a lot more.

[dbaron]

@kenchris and I are looking at this in a breakout at the TAG face-to-face meeting in Tokyo.

I'm a little unclear on what code using this stream-of-streams model would look like; if you're going down that route, it would be interesting to see an explainer. It sounds like you might be talking about this for a later version of the API.

That said, we're happy to see this area being worked on -- the stated goals seem worthwhile -- and would again encourage you to make sure this effort fits well with other areas of work like web transport that are happening at the same time.

I feel like to find a bit of time outside of this meeting to look into this in a little bit more detail -- but on the other hand maybe that makes more sense slightly later in the process. Would you like to get more feedback at this stage, or do you think it would be better to wait a bit before taking a closer look at the spec?

[ricea]

I'm a little unclear on what code using this stream-of-streams model would look like; if you're going down that route, it would be interesting to see an explainer. It sounds like you might be talking about this for a later version of the API.

For reading, something like

for await (const message of webSocketStream.readable) {
  for await (const chunk of message) {
    await processChunk(chunk);
  }
  await processEndOfMessage();
}

It would probably be good for me to write up a set of proposals for how streaming within a message should work, but I want to get the first iteration of WebSocketStream standardised first.

Would you like to get more feedback at this stage, or do you think it would be better to wait a bit before taking a closer look at the spec?

At this point I'm waiting for feedback from the origin trial before proceeding with standardisation. While I welcome any input, it would probably be a more efficient use of your time to wait until there is a draft standard.

[ylafon]

Also the comment made by @dbaron on WebTransport is worth exploring, both specifications seem to have similar goals. Would it be possible to have an explainer about the fundamental differences between the two approaches and what would prevent defining only one API there?

[dbaron]

For what it's worth -- maybe a more general way to frame my previous comment is that perhaps it would be helpful if the explainer assumed a bit less knowledge about the space already. It doesn't need to explain the web from first principles, but having a few more paragraphs to explain the basics of what this is building on would likely be helpful.

[dbaron]

@kenchris and I are looking at this in a breakout at our Wellington face-to-face.

We're curious what the status of this is. There was discussion in the past about changing to a stream-of-streams model? Has that been abandoned, or is that going to move forwards?

It would also be useful to have some explainer updates to explain how this fits with other work and perhaps how it relates to both specification and reality of web sockets (see earlier comment).

It sounds like there is implementation work proceeding and this is available behind a flag, and it sounds like there's been some performance work on that implementation. Is that for the stream-of-messages (or stream-of-chunks) model?

Is it at a stage where TAG feedback would be useful, or would that be more useful at some point in the past or future?

[ricea]

We're curious what the status of this is. There was discussion in the past about changing to a stream-of-streams model? Has that been abandoned, or is that going to move forwards?

We are leaning towards shipping based on developer feedback, but we haven't made a final decision.

It's possible we will support a stream-of-streams model in the future, but I expect to only support stream-of-messages (strings or BufferSources) in the first shipped version.

It would also be useful to have some explainer updates to explain how this fits with other work and perhaps how it relates to both specification and reality of web sockets (see earlier comment).

Sorry, I have been remiss in updating the explainer. I will do it but I can't guarantee when.

It sounds like there is implementation work proceeding and this is available behind a flag, and it sounds like there's been some performance work on that implementation. Is that for the stream-of-messages (or stream-of-chunks) model?

Yes, it is available behind the experimental-web-platform-features flag in Chrome and I have done some performance work in response to early feedback. This is the stream-of-messages model.

Is it at a stage where TAG feedback would be useful, or would that be more useful at some point in the past or future?

Yes. Initial developer response to the API shape is positive, so more feedback would be useful at this point.

[dbaron]

Which of the documents represent the current state of things well, for us to focus on when giving feedback?

[ricea]

Which of the documents represent the current state of things well, for us to focus on when giving feedback?

https://github.com/ricea/websocketstream-explainer/blob/master/README.md is still accurate but I haven't yet updated it it to address the deficiencies noted here. Sorry.

I'm also interested in feedback in the behaviour described in ricea/websocketstream-explainer#6, which I have not yet added to the explainer.

[tomayac]

FYI, I have written about this API some weeks ago. The article sparked quite some developer interest in the topic.

[kenchris]

Hi there, any update on this?

What is the cross-browser/vendor support story? Also in what venue is this work taking place?

[kenchris]

Ping @ricea

[ricea]

@kenchris Sorry, there hasn't been much progress yet. Expect more activity in the next month. The expected venue is WHATWG.

We will need cross-browser buy-in for standardisation, so it will be solidified soon. Currently there have only been informal discussions.

[crowlKats]

What is the state on this?
It would be great to see a proper spec written for WebSocketStream as there is some interest at Deno to implement it.

[kenchris]

Is it OK if we close this, and you reopen when/if you get cross-browser buy in? @ricea

[ricea]

Is it OK if we close this, and you reopen when/if you get cross-browser buy in? @ricea

Yes, that's fine.