From b89aa3ea1ba8bf8fd73839bed833403f2edc99bf Mon Sep 17 00:00:00 2001 From: Jan-Ivar Bruaroey Date: Mon, 25 Sep 2023 16:36:41 -0400 Subject: [PATCH 1/3] Define [=underlying connection=] for connection-level stats. --- index.bs | 63 ++++++++++++++++++++++++++++---------------------------- 1 file changed, 32 insertions(+), 31 deletions(-) diff --git a/index.bs b/index.bs index d5a97d79..691fb551 100644 --- a/index.bs +++ b/index.bs @@ -131,7 +131,8 @@ session=] can contain multiple [=WebTransport streams=]. ## WebTransport session ## {#webtransport-session} -A WebTransport session is a session of WebTransport over HTTP/3. +A WebTransport session is a session of WebTransport over an HTTP/3 +or HTTP/2 underlying [=connection=]. There may be multiple [=WebTransport sessions=] on one [=connection=], when pooling is enabled. A [=WebTransport session=] has the following capabilities defined in [[!WEB-TRANSPORT-HTTP3]]: @@ -601,7 +602,7 @@ defined in [[!WEB-TRANSPORT-HTTP3]]. interface WebTransport { constructor(USVString url, optional WebTransportOptions options = {}); - Promise<WebTransportStats> getStats(); + Promise<WebTransportConnectionStats> getStats(); readonly attribute Promise<undefined> ready; readonly attribute WebTransportReliabilityMode reliability; readonly attribute WebTransportCongestionControl congestionControl; @@ -983,10 +984,10 @@ these steps. 1. Let |transport| be [=this=]. 1. Let |p| be a new promise. 1. Run the following steps [=in parallel=]: - 1. Gather the stats from the underlying QUIC connection, including stats on datagrams. + 1. Gather the stats from the [=underlying connection=], including stats on datagrams. 1. Wait for the stats to be ready. 1. [=Queue a network task=] with |transport| to run the following steps: - 1. Let |stats| be a [=new=] {{WebTransportStats}} object representing the gathered stats. + 1. Let |stats| be a [=new=] {{WebTransportConnectionStats}} object representing the gathered stats. 1. [=Resolve=] |p| with |stats|. 1. Return |p|. @@ -1310,18 +1311,18 @@ The dictionary SHALL have the following attributes: Note: This is sender-side data prioritization which does not guarantee reception order. -## `WebTransportStats` Dictionary ## {#web-transport-stats} +## `WebTransportConnectionStats` Dictionary ## {#web-transport-stats} -The WebTransportStats dictionary includes information -on HTTP/3 connection stats. +The WebTransportConnectionStats dictionary includes information +on WebTransport-specific stats about the [=WebTransport session=]'s [=underlying connection=]. -Issue: Now that quic-transport has been removed, this section needs to be -revised. Some of those are safe to expose for HTTP/2 and HTTP/3 connections -(like min-RTT), while most would either result in information disclosure -or are impossible to define for pooled connections. +Note: When pooling is used, multiple [=WebTransport sessions=] pooled +on the same [=connection=] all receive the same information, i.e. the information +is disclosed across pooled [=WebTransport sessions | sessions=] holding the +same [[fetch#network-partition-keys|network partition key]]. 
-dictionary WebTransportStats {
+dictionary WebTransportConnectionStats {
   DOMHighResTimeStamp timestamp;
   unsigned long long bytesSent;
   unsigned long long packetsSent;
@@ -1340,36 +1341,36 @@ dictionary WebTransportStats {
 
 The dictionary SHALL have the following attributes:
 
-: timestamp
+: timestamp
 :: The `timestamp` for when the stats are gathered, relative to the
    UNIX epoch (Jan 1, 1970, UTC).
-: bytesSent
-:: The number of bytes sent on the QUIC connection, including retransmissions.
+: bytesSent
+:: The number of bytes sent on the [=underlying connection=], including retransmissions.
    Does not include UDP or any other outer framing.
-: packetsSent
-:: The number of packets sent on the QUIC connection, including those that are determined to have been lost.
-: packetsLost
-:: The number of packets lost on the QUIC connection (does not monotonically increase, because packets that are declared lost can subsequently be received).
-: numOutgoingStreamsCreated
-:: The number of outgoing QUIC streams created on the QUIC connection.
-: numIncomingStreamsCreated
-:: The number of incoming QUIC streams created on the QUIC connection.
-: bytesReceived
-:: The number of total bytes received on the QUIC connection, including
+: packetsSent
+:: The number of packets sent on the [=underlying connection=], including those that are determined to have been lost.
+: packetsLost
+:: The number of packets lost on the [=underlying connection=] (does not monotonically increase, because packets that are declared lost can subsequently be received).
+: numOutgoingStreamsCreated
+:: The number of outgoing QUIC streams created on the [=underlying connection=].
+: numIncomingStreamsCreated
+:: The number of incoming QUIC streams created on the [=underlying connection=].
+: bytesReceived
+:: The number of total bytes received on the [=underlying connection=], including
    duplicate data for streams. Does not include UDP or any other outer framing.
-: packetsReceived
-:: The number of total packets received on the QUIC connection, including
+: packetsReceived
+:: The number of total packets received on the [=underlying connection=], including
    packets that were not processable.
-: smoothedRtt
+: smoothedRtt
 :: The smoothed round-trip time (RTT) currently observed on the connection, as defined
    in [[!RFC9002]] [Section 5.3](https://www.rfc-editor.org/rfc/rfc9002#section-5.3).
-: rttVariation
+: rttVariation
 :: The mean variation in round-trip time samples currently observed on the
    connection, as defined in [[!RFC9002]]
    [Section 5.3](https://www.rfc-editor.org/rfc/rfc9002#section-5.3).
-: minRtt
+: minRtt
 :: The minimum round-trip time observed on the entire connection.
-: estimatedSendRate
+: estimatedSendRate
 :: The estimated rate at which queued data will be sent by the user agent, in bits per second.
    This rate applies to all streams and datagrams that share a [=WebTransport session=]
    and is calculated by the congestion control algorithm (potentially chosen by

From 8f519d273e90646858458f2bc4ba6c2942db71c8 Mon Sep 17 00:00:00 2001
From: Jan-Ivar Bruaroey 
Date: Tue, 26 Sep 2023 14:38:13 -0400
Subject: [PATCH 2/3] Remove redundant wait in async steps + consistent link
 names

---
 index.bs | 10 ++++------
 1 file changed, 4 insertions(+), 6 deletions(-)

diff --git a/index.bs b/index.bs
index 691fb551..2722cfb9 100644
--- a/index.bs
+++ b/index.bs
@@ -985,7 +985,6 @@ these steps.
      1. Let |p| be a new promise.
      1. Run the following steps [=in parallel=]:
          1. Gather the stats from the [=underlying connection=], including stats on datagrams.
-         1. Wait for the stats to be ready.
          1. [=Queue a network task=] with |transport| to run the following steps:
            1. Let |stats| be a [=new=] {{WebTransportConnectionStats}} object representing the gathered stats.
            1. [=Resolve=] |p| with |stats|.
@@ -1129,7 +1128,7 @@ Whenever a [=WebTransport session=] which is associated with a {{WebTransport}}
 
 
 

-Whenever a [=connection=] associated with a {{WebTransport}} |transport| gets a connection error,
+Whenever a {{WebTransport}} |transport|'s [=underlying connection=] gets a connection error,
 run these steps:
 
 1. [=Queue a network task=] with |transport| to run these steps:
@@ -1311,7 +1310,7 @@ The dictionary SHALL have the following attributes:
    Note: This is sender-side data prioritization which does not guarantee
    reception order.
 
-## `WebTransportConnectionStats` Dictionary ##  {#web-transport-stats}
+## `WebTransportConnectionStats` Dictionary ##  {#web-transport-connection-stats}
 
 The WebTransportConnectionStats dictionary includes information
 on WebTransport-specific stats about the [=WebTransport session=]'s [=underlying connection=].
@@ -1713,7 +1712,6 @@ The {{WebTransportReceiveStream}}'s [=transfer steps=] and
      1. Let |p| be a new promise.
      1. Run the following steps [=in parallel=]:
          1. Gather the stats specific to this {{WebTransportReceiveStream}}.
-         1. Wait for the stats to be ready.
          1. [=Queue a network task=] with |transport| to run the following steps:
            1. Let |stats| be a [=new=] {{WebTransportReceiveStreamStats}} object
               representing the gathered stats.
@@ -2340,7 +2338,7 @@ possible.
 Information about the network is available to the server either directly through
 its own networking stack, indirectly through the rate at which data is consumed
 or transmitted by the client, or as part of the statistics provided by the API
-(see [[#web-transport-stats]]).  Consequently, restrictions on information in
+(see [[#web-transport-connection-stats]]).  Consequently, restrictions on information in
 user agents is not the only mechanism that might be needed to manage these
 privacy risks.
 
@@ -2375,7 +2373,7 @@ This might allow sites to increase confidence that activity on different sites
 originates from the same user.
 
 A user agent could limit or degrade access to feedback mechanisms such as
-statistics ([[#web-transport-stats]]) for sites that are inactive or do not have
+statistics ([[#web-transport-connection-stats]]) for sites that are inactive or do not have
 focus ([[html/interaction#focus]]).  As noted, this does not prevent a server
 from making observations about changes in the network.
 

From dc007b19beb6c5bcefb1074275d62f3ce18cbf7e Mon Sep 17 00:00:00 2001
From: Jan-Ivar Bruaroey 
Date: Tue, 26 Sep 2023 14:43:13 -0400
Subject: [PATCH 3/3] s/WebTransport connection/WebTransport session/ in a few
 places more.

---
 index.bs | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/index.bs b/index.bs
index 2722cfb9..ce0d1ec0 100644
--- a/index.bs
+++ b/index.bs
@@ -1186,15 +1186,15 @@ enum WebTransportCongestionControl {
WebTransportOptions is a dictionary of parameters -that determine how WebTransport connection is established and used. +that determine how the [=WebTransport session=] is established and used. : allowPooling -:: When set to true, the WebTransport connection can be pooled, that is, the network connection for - the WebTransport session can be shared with other HTTP/3 sessions. +:: When set to true, the [=WebTransport session=] can be pooled, that is, its [=underlying connection=] + can be shared with other HTTP/3 sessions. : requireUnreliable -:: When set to true, the WebTransport connection cannot be established over HTTP/2 if - an HTTP/3 connection is not possible. +:: When set to true, the [=WebTransport session=] cannot be established over an + HTTP/2 [=connection=] if an HTTP/3 [=connection=] is not possible. : serverCertificateHashes :: This option is only supported for transports using dedicated connections.