Skip to content
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

Jump to bottom

Update endpoint pair example and fix citation #1318

Merged
merged 6 commits into from
Jul 12, 2024
Merged

Update endpoint pair example and fix citation #1318

Changes from 2 commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
24240e6
Update endpoint pair example and fix citation
jan-ivar Jul 9, 2024
aa5cf91
simplify example
jan-ivar Jul 9, 2024
a745d0c
Make example look more like the API it references.
jan-ivar Jul 10, 2024
a146a0e
Revert "Make example look more like the API it references."
jan-ivar Jul 11, 2024
85a4176
revert example.
jan-ivar Jul 11, 2024
cecef0e
Revert example prose
jan-ivar Jul 11, 2024
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
16 changes: 8 additions & 8 deletions index.bs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7459,19 +7459,19 @@ readable and writable streams represent the two ends of a longer pipeline, with
web developer code insert [=transform streams=] into the middle of them.

<div class="example" id="example-endpoint-pair-usage">
Assuming we had a web-platform-provided function `createEndpointPair()`, web developers would write
code like so:
Assuming we had a web-platform-provided interface `Transformer` that had `readable` and
`writable` attributes, web developers would write code like so:

<xmp highlight="js">
const { readable, writable } = createEndpointPair();
readable.pipeThrough(new TransformStream(...)).pipeTo(writable);
async function handleTransformer({readable, writable}) {
await readable.pipeThrough(new TransformStream(...)).pipeTo(writable);
}
</xmp>
Copy link
Member

Choose a reason for hiding this comment

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

This example has been simplified a bit too much I think. It talks about a platform-provided Transformer interface but that interface is now super-implicit, because of the destructuring of function arguments. I think reverting to something like

const { readable, writable } = createTransformer();
readable.pipeThrough(new TransformStream(...)).pipeTo(writable);

would work better.

Additionally, the point of createEndpointPair() was to match the official name given in the standard, "endpoint pair". So I think that that was even better.

Can you say more about why you changed this example?

Copy link
Contributor Author

Choose a reason for hiding this comment

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

I read "web-platform-provided function createEndpointPair()" as a callout to the same-shaped sender.createEncodedStreams() method removed in w3c/webrtc-encoded-transform#64.

I was trying to maintain this similarity to the API it's referencing. But the spec's worker-only API is different. From MDN and blog post examples:

// main.html
const worker = new Worker("worker.js");
sender.transform = new RTCRtpScriptTransform(worker);

// worker.js
onrtctransform = async ({transformer: {readable, writable}}) => {
  await readable.pipeThrough(new TransformStream(...)).pipeTo(writable);
};

The spec fires an event with the transformer which has no constructor. The event part seemed unnecessary but I can try to add it if the context is useful.

Copy link
Member

@domenic domenic Jul 11, 2024 •
edited
Loading

Choose a reason for hiding this comment

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

Sorry, this seems to have gone in the opposite direction of what I'm requesting. The point of this example is not to reference any other API. (That's the purpose of the note below, which you helpfully edited for accuracy.) It's to give an example of the simplest possible concept of an endpoint pair, i.e. a platform-provided API that returns a { readable, writable } object.

The naming is especially important, as we're trying to illustrate the "endpoint pair" concept defined above, not some sort of "transformer" concept which this document does not define.

Can you revert it to its previous version?

</div>

<p class="example" id="example-endpoint-pair-webrtc"><cite>WebRTC Insertable Media using
Streams</cite> is an example of this technique, with its `sender.createEncodedStreams()` and
`receiver.createEncodedStreams()` methods.
<!-- TODO cite it and cross-link to it https://github.com/tobie/specref/issues/620 -->
<p class="example" id="example-endpoint-pair-webrtc"><cite>WebRTC Encoded Transform</cite>
is an example of this technique, with its {{RTCRtpScriptTransformer}} interface which has
both `readable` and `writable` attributes.

Despite such endpoint pairs obeying the `readable`/`writable` property contract, it never makes
sense to pass them to {{ReadableStream/pipeThrough()}}.
Expand Down