FF102 User define byte stream interface - not experimental

[hamishwillee]

FF102 brings support for the following interfaces:

• ReadableByteStreamController
• ReadableStreamBYOBReader
• ReadableStreamBYOBRequest

This work includes updates to the above classes (and their properties and methods), along with a new guide Using_readable_byte_streams.

There are lots of other minor changes to related docs to cross link the new docs and also minor fixes to things like TransformStreams and streaming API doc while trying to get my head around the above.

Other docs work can be tracked in #16816

[github-actions]

Preview URLs

• https://pr16818.content.dev.mdn.mozit.cloud/en-US/docs/Web/API/ReadableByteStreamController/byobRequest
• https://pr16818.content.dev.mdn.mozit.cloud/en-US/docs/Web/API/ReadableByteStreamController/close
• https://pr16818.content.dev.mdn.mozit.cloud/en-US/docs/Web/API/ReadableByteStreamController/desiredSize
• https://pr16818.content.dev.mdn.mozit.cloud/en-US/docs/Web/API/ReadableByteStreamController/enqueue
• https://pr16818.content.dev.mdn.mozit.cloud/en-US/docs/Web/API/ReadableByteStreamController/error
• https://pr16818.content.dev.mdn.mozit.cloud/en-US/docs/Web/API/ReadableByteStreamController
• https://pr16818.content.dev.mdn.mozit.cloud/en-US/docs/Web/API/ReadableStream/ReadableStream
• https://pr16818.content.dev.mdn.mozit.cloud/en-US/docs/Web/API/ReadableStream/getReader
• https://pr16818.content.dev.mdn.mozit.cloud/en-US/docs/Web/API/ReadableStreamBYOBReader/ReadableStreamBYOBReader
• https://pr16818.content.dev.mdn.mozit.cloud/en-US/docs/Web/API/ReadableStreamBYOBReader/cancel
• https://pr16818.content.dev.mdn.mozit.cloud/en-US/docs/Web/API/ReadableStreamBYOBReader/closed
• https://pr16818.content.dev.mdn.mozit.cloud/en-US/docs/Web/API/ReadableStreamBYOBReader/read
• https://pr16818.content.dev.mdn.mozit.cloud/en-US/docs/Web/API/ReadableStreamBYOBReader/releaseLock
• https://pr16818.content.dev.mdn.mozit.cloud/en-US/docs/Web/API/ReadableStreamBYOBReader
• https://pr16818.content.dev.mdn.mozit.cloud/en-US/docs/Web/API/ReadableStreamBYOBRequest/respond
• https://pr16818.content.dev.mdn.mozit.cloud/en-US/docs/Web/API/ReadableStreamBYOBRequest/respondWithNewView
• https://pr16818.content.dev.mdn.mozit.cloud/en-US/docs/Web/API/ReadableStreamBYOBRequest/view
• https://pr16818.content.dev.mdn.mozit.cloud/en-US/docs/Web/API/ReadableStreamBYOBRequest
• https://pr16818.content.dev.mdn.mozit.cloud/en-US/docs/Web/API/ReadableStreamDefaultReader/releaseLock
• https://pr16818.content.dev.mdn.mozit.cloud/en-US/docs/Web/API/ReadableStreamDefaultReader
• https://pr16818.content.dev.mdn.mozit.cloud/en-US/docs/Web/API/Streams_API/Concepts
• https://pr16818.content.dev.mdn.mozit.cloud/en-US/docs/Web/API/Streams_API/Using_readable_byte_streams
• https://pr16818.content.dev.mdn.mozit.cloud/en-US/docs/Web/API/Streams_API/Using_readable_streams
• https://pr16818.content.dev.mdn.mozit.cloud/en-US/docs/Web/API/Streams_API/Using_writable_streams
• https://pr16818.content.dev.mdn.mozit.cloud/en-US/docs/Web/API/Streams_API
• https://pr16818.content.dev.mdn.mozit.cloud/en-US/docs/Web/API/TransformStream

Flaws

Note! 25 documents with no flaws that don't need to be listed. 🎉

URL: /en-US/docs/Web/API/ReadableStreamBYOBRequest/respondWithNewView
Title: ReadableStreamBYOBRequest.respondWithNewView()
on GitHub
Flaw count: 2

• macros:
  • wrong xref macro used (consider changing which macro you use)
  • wrong xref macro used (consider changing which macro you use)

External URLs

URL: /en-US/docs/Web/API/ReadableStream/ReadableStream
Title: ReadableStream()
on GitHub

No new external URLs

---

URL: /en-US/docs/Web/API/ReadableStream/getReader
Title: ReadableStream.getReader()
on GitHub

No new external URLs

---

URL: /en-US/docs/Web/API/ReadableStreamBYOBReader
Title: ReadableStreamBYOBReader
on GitHub

No new external URLs

---

URL: /en-US/docs/Web/API/ReadableStreamBYOBReader/closed
Title: ReadableStreamBYOBReader.closed
on GitHub

No new external URLs

---

URL: /en-US/docs/Web/API/ReadableStreamBYOBReader/read
Title: ReadableStreamBYOBReader.read()
on GitHub

No new external URLs

---

URL: /en-US/docs/Web/API/ReadableStreamBYOBReader/ReadableStreamBYOBReader
Title: ReadableStreamBYOBReader()
on GitHub

No new external URLs

---

URL: /en-US/docs/Web/API/ReadableStreamBYOBReader/cancel
Title: ReadableStreamBYOBReader.cancel()
on GitHub

No new external URLs

---

URL: /en-US/docs/Web/API/ReadableStreamBYOBReader/releaseLock
Title: ReadableStreamBYOBReader.releaseLock()
on GitHub

No new external URLs

---

URL: /en-US/docs/Web/API/Streams_API
Title: Streams API
on GitHub

No new external URLs

---

URL: /en-US/docs/Web/API/Streams_API/Using_readable_streams
Title: Using readable streams
on GitHub

• https://mdn.github.io/dom-examples/streams/png-transform-stream/ (1 time) (Note! This may be a new URL 👀)

---

URL: /en-US/docs/Web/API/Streams_API/Using_readable_byte_streams
Title: Using readable byte streams
on GitHub

• https://nodejs.org/api/fs.html (2 times) (Note! This may be a new URL 👀)

---

URL: /en-US/docs/Web/API/Streams_API/Concepts
Title: Streams API concepts
on GitHub

No new external URLs

---

URL: /en-US/docs/Web/API/Streams_API/Using_writable_streams
Title: Using writable streams
on GitHub

No new external URLs

---

URL: /en-US/docs/Web/API/ReadableStreamBYOBRequest
Title: ReadableStreamBYOBRequest
on GitHub

No new external URLs

---

URL: /en-US/docs/Web/API/ReadableStreamBYOBRequest/respondWithNewView
Title: ReadableStreamBYOBRequest.respondWithNewView()
on GitHub

No new external URLs

---

URL: /en-US/docs/Web/API/ReadableStreamBYOBRequest/view
Title: ReadableStreamBYOBRequest.view
on GitHub

No new external URLs

---

URL: /en-US/docs/Web/API/ReadableStreamBYOBRequest/respond
Title: ReadableStreamBYOBRequest.respond()
on GitHub

No new external URLs

---

URL: /en-US/docs/Web/API/ReadableByteStreamController
Title: ReadableByteStreamController
on GitHub

No new external URLs

---

URL: /en-US/docs/Web/API/ReadableByteStreamController/enqueue
Title: ReadableByteStreamController.enqueue()
on GitHub

No new external URLs

---

URL: /en-US/docs/Web/API/ReadableByteStreamController/error
Title: ReadableByteStreamController.error()
on GitHub

No new external URLs

---

URL: /en-US/docs/Web/API/ReadableByteStreamController/desiredSize
Title: ReadableByteStreamController.desiredSize
on GitHub

• https://streams.spec.whatwg.org/ (1 time) (Note! This may be a new URL 👀)

---

URL: /en-US/docs/Web/API/ReadableByteStreamController/close
Title: ReadableByteStreamController.close()
on GitHub

No new external URLs

---

URL: /en-US/docs/Web/API/ReadableByteStreamController/byobRequest
Title: ReadableByteStreamController.byobRequest
on GitHub

No new external URLs

---

URL: /en-US/docs/Web/API/ReadableStreamDefaultReader
Title: ReadableStreamDefaultReader
on GitHub

No new external URLs

---

URL: /en-US/docs/Web/API/ReadableStreamDefaultReader/releaseLock
Title: ReadableStreamDefaultReader.releaseLock()
on GitHub

No new external URLs

---

URL: /en-US/docs/Web/API/TransformStream
Title: TransformStream
on GitHub

No new external URLs

(this comment was updated 2022-07-12 00:04:04.359661)

[hamishwillee]

@wbamberg If you're happy with this please approve but don't merge.

[mgaudet]

Hey @domenic and @mathiasbynens:

Hamish has been working up the MDN documentation for user defined byte streams, based partially on my explanations at the bottom of this bug. I would love it if either of you had the time, if you could take a peek as well for accuracy.

[hamishwillee]

Thanks @mgaudet . FYI @domenic and @mathiasbynens

This PR is now worth looking at. ReadableStreamBYOBRequest, ReadableByteStreamController and reader docs are all updated and should be accurate. But they don't yet have examples. I also need to create the high level intro.

The work continues ...

[hamishwillee]

@mgaudet Howdy, FYI, the first draft of the guide is now done in https://pr16818.content.dev.mdn.mozit.cloud/en-US/docs/Web/API/Streams_API/Using_readable_byte_streams

The examples clarified a few things for me, as they always do, including that the auto buffer allocation is ignored if you have a byte reader. Now that I have the examples I plan to flesh out all the pages tomorrow. That means this should be ready for proper remove in about 24 hours. I'll ping the spec authors then too.

[mgaudet]

I am on vacation this week, so won’t be able to take a look till the 11th.

[hamishwillee]

@domenic and @mathiasbynens . First draft complete. There might be tweaks but the shape of it is done. Matthew is hoping to review next week. If you have comments, in particular about https://pr16818.content.dev.mdn.mozit.cloud/en-US/docs/Web/API/Streams_API/Using_readable_byte_streams they would be much appreciated.

EDIT: Added request for review in whatwg/streams#1237

[MattiasBuelens]

Reviewed about half of the files, will try to get through the rest later this week. Overall it's looking very good, nice work! 👏

[hamishwillee]

Thanks @teoli2003
I accepted reviews and did a rebase which fixed up some of the other page type stuff.

YOu raised a few questions about cases where a reject is not used. I can remove these if you like. I left them in because originally this was a generally purpose mock and I wasn't sure whether I'd add error fail cases etc. They aren't needed, but nor do they do much harm. So unless you say "must be commented or removed" then I lean to leaving them along - in particular since most are hidden.

[teoli2003]

I proposed an alternative, your call. I'm approving, and let you merge it.

[MattiasBuelens]

Some final nits, other than that this LGTM. Thank you so much for this excellent write-up! 😄

[mgaudet]

I did a cursory review, but I'm very happy that the spec authors found the time to review this, and I will defer to their expertise. LGTM as well :)

[hamishwillee]

Thanks @teoli2003 - I accepted all your nits and will merge.

Thanks @MattiasBuelens for your reviews. This took longer for me to get my head around than necessary. FYI only - these will seem stupid to you:

• the byob naming seemed odd. It took me forever to understand the the buffer that is BYOB is provided by the reader. The reason this is confusing is because it might not be BYOB and I started looking at this from the stream constructor end.
• There isn't always a BYOB buffer - it gets created when appropriate.
• The autoallocation only applies for default reader.
• The change you made to the releaseLock is much better! The original way made it hard to sensibly manage unlocking.

At some point it might be worth me/someone coming back and adding a mock backpressure. IMO the ability to try stuff in live examples adds a lot of value.

@mgaudet You've gone above and beyond. Really appreciate it. Note the comment from @MattiasBuelens that the spec does not require that if a byobRequest is provided that it is used - you can enqueue if you like and the controller should handle that. If FF does something different it might be off spec. I'll leave you guys to chat about that elsewhere.