Intent to Deprecate and Remove: Deprecate WebTransport incomingHighWaterMark/outgoingHighWaterMark

[Chromestatus]

Contact emails

kpan...@microsoft.com

Explainer

No information provided

Specification

https://w3c.github.io/webtransport/#dom-webtransportdatagramduplexstream-incomingmaxbuffereddatagrams,https://github.com/web-platform-tests/wpt/pull/58612/changes

Summary

The incomingHighWaterMark and outgoingHighWaterMark attributes on WebTransportDatagramDuplexStream are deprecated in favor of incomingMaxBufferedDatagrams and outgoingMaxBufferedDatagrams, following a spec rename. The attribute type also changes from long to unsigned long. Developers should migrate to the new attribute names. The old names will show a console deprecation warning and will be removed in a future release.

Blink component

Blink>Network>WebTransport

Web Feature ID

webtransport

Motivation

The WebTransport specification renamed two attributes on WebTransportDatagramDuplexStream: - incomingHighWaterMark → incomingMaxBufferedDatagrams - outgoingHighWaterMark → outgoingMaxBufferedDatagrams The attribute type was also changed from long to unsigned long. The new names better describe the attributes' purpose (they control the maximum number of buffered datagrams, not a byte-based high water mark). The new attribute names are already exposed alongside the old ones. The old names should be deprecated and removed to align with the specification and avoid developer confusion from having two names for the same thing.

Initial public proposal

No information provided

Goals for experimentation

None

Debuggability

No information provided

Requires code in //chrome?

False

Tracking bug

https://issues.chromium.org/issues/494380213

Estimated milestones

No milestones specified

Link to entry on the Chrome Platform Status

https://chromestatus.com/feature/5143839699501056?gate=4911413786181632

This intent message was generated by Chrome Platform Status.

[Daniel Bratell]

Do you have a suggested "removal milestone"? 

We have found that unless we name a specific milestone, many people ignore deprecation warnings and then they pile up and we get warning fatigue.

Also, do you have usage data? Use Counters or some other kind of upper limit on how many might be affected?

/Daniel

--
You received this message because you are subscribed to the Google Groups "blink-dev" group.
To unsubscribe from this group and stop receiving emails from it, send an email to blink-dev+...@chromium.org.
To view this discussion visit https://groups.google.com/a/chromium.org/d/msgid/blink-dev/69d61ffa.050a0220.1c79a0.099e.GAE%40google.com.

[Alex Russell]

Why was this renamed? Why would we agree to a cosmetic change after shipping?

Best,

Alex

To unsubscribe from this group and stop receiving emails from it, send an email to blink-dev+unsubscribe@chromium.org.

[Nidhi Jaju]

> Why was this renamed? Why would we agree to a cosmetic change after shipping?

While we shipped our initial implementation of WebTransport in 2021, the specification has evolved since then as it progressed through the IETF and W3C, other browsers have also brought implementation experience, and other groups like Media over QUIC (MoQ) have highlighted the need for updates/additions to the spec.

https://github.com/w3c/webtransport/issues/723 explains some of the reasoning behind this change. In the Streams API, a "high water mark" is a signal for backpressure and flow control, whereas in WebTransport, these attributes actually represent a hard cap on the number of datagrams retained in the queue. If this limit is exceeded, datagrams are dropped rather than just signaling backpressure, so the new names avoid developer confusion by more accurately describing the behavior.

Best,
Nidhi

[Alex Russell]

Hey Nidhi,

Thanks for all of this background. I'm sure naming alignment might be nice, but it doesn't seem obvious to me that we should agree to a change post-launch, particularly without usage data. In general, the I2S process should be thought of as pouring concrete; everything's fluid until it has set. As a result, we have a dislike of this sort of casual renaming post-launch. The evidentiary bar to support a rename is high, although you might be able to support strict aliasing with less pushback.

Best,

Alex

[Nidhi Jaju]

Hi Alex,

My understanding is that when WebTransport was initially shipped in Chromium, the core functionality of the W3C spec was considered fairly stable, and the decision was made to launch prior to Candidate Recommendation status. On the path to Candidate Recommendation, there have been some updates in response to implementation experience from other implementors and needs from use cases like MoQ. While we don't want to casually rename attributes for minor cosmetic reasons, this rename updates the attribute's name so that its meaning aligns with the reality of the functionality it provides.

The WebTransport API overall is used by 0.0025% of page loads, and the highWaterMark attribute can only be a subset of that. However, we're starting to see some adoption in the ecosystem, especially with the specs nearing completion and other major browsers shipping WebTransport implementations, so we'd like to make these changes while there's still an opportunity to minimize developer and compatibility impact.

WebTransport is also included in Interop 2026, so we're expecting to make additional updates to align our implementation with the current state of the spec as it enters Candidate Recommendation status.

Best,
Nidhi

To unsubscribe from this group and stop receiving emails from it, send an email to blink-dev+...@chromium.org.

[Philip Jägenstedt]

Hi Nidhi,

Given the very low usage, that this was already agreed to in the WG, and that it's not merely cosmetic but matches reality better, LGTM1.

Best regards,

Philip

To view this discussion visit https://groups.google.com/a/chromium.org/d/msgid/blink-dev/CAMZNYANHu1%3DUq-6f_fbXN0h%2BwXnN%2Bbkp5QLhRfcpGUw_U99Cvg%40mail.gmail.com.

[Philip Jägenstedt]

My LGTM is conditional on a removal milestone for the old names asrequested by Daniel. Since aliases are extremely cheap to keep around. https://www.chromium.org/blink/launching-features/ suggests "as many milestones as possible to respond to the deprecation" but more than 6 milestones would seem excessive to me. I'd suggest 3 milestones.