Add stats.atSendCapacity

[jan-ivar]

Fixes #559. For discussion.

---

Preview | Diff

[jan-ivar]

These are modeled on estimatedSendRate, the lone stat specific to the WebTransport session, as opposed to all the other stats which are for the entire underlying connection.

I dunno if that was a mistake or not. We should discuss.

[jan-ivar]

Meeting:

• take out "datagrams" from isServerLimited
• Maybe add required to all four?

[jan-ivar]

Meeting:

• interest in going back to flat list of members. Right now we have:

   stats.sendRate.estimate;
   stats.sendRate.isDataLimited;
   stats.sendRate.isServerLimited;
   stats.sendRate.inSlowStart;

  Add a second PR to consider a flat list of members instead:

   stats.estimatedSendRate;
   stats.isSendingDataLimited;
   stats.isSendingServerLimited;
   stats.inSendingSlowStart;

• Instead of server limited, should (instead) count "BLOCKED frames"?

  stats.blockedFramesCount;

[jan-ivar]

Personally, I'm actually partial to a flat hierarchy a bit, since a hierarchy doesn't really solve ambiguity that much due to the ?. operator in JS. Example:

This will throw if stats or stats.sendRate is undefined:

stats.sendRate.isDataLimited;

This result in undefined (which might interpreted as false by websites):

stats.sendRate?.isDataLimited;

[jan-ivar]

@wilaw wrote in https://github.com/w3c/webtransport/issues/607#issuecomment-2206558189:

In the prior meeting, a comment was made that some of the proposed 'sending' stats may not be known, and that coercing a boolean value could cause a problem. Is this a real problem, or can robust defaults be chosen that will not mislead applications?

(replying here about stats we're still adding here)

If unavailable stats are mostly a problem at connection start, then defaults reflecting initial state should work.

stats.estimatedSendRate; //nullable stats.isSendingDataLimited; // default false

A connection is inherently data limited to start, so this would naturally default to (start out as) true, unless we can think of a name for the inverse state.

stats.isSendingServerLimited; // default false

Is it possible for a session to be both data limited AND server limited? If I have two long-lived streams, one server limited (receiving back pressure from the server) and the other data limited, would both be true? How would I know which applies to which?

stats.inSendingSlowStart; // default false stats.blockedFramesCount; // default 0

These seem fine to me.

[jan-ivar]

Meeting:

• no objections to flat
• suggest leaving Blocked frames to a different issue.
  • then we can remove stats.isSendingServerLimited if it ends up being redundant

[jan-ivar]

Meeting:

• bikeshed: atSendCapacity = false
• need to keep sending to stay there
• Note: atSendCapacity is not intended to replace the back-pressure signal. It is intended to signal the confidence level that you are at the estimated send rate. Capacity may increase or decrease based on network conditions.

[martinthomson]

Including what I typed into chat...

When false, it indicates that estimatedSendRate is not being fully utilized and could be an unreliable estimate of actual network capacity.

When true, it indicates that the data that the application sends is close to the estimatedSendRate. As long as that send rate is sustained, estimatedSendRate will adapt to network conditions and be a fair estimate of what capacity is available to the application.