Internet-Draft SCONEPRO APIs May 2024
Eddy, et al. Expires 4 November 2024 [Page]
Intended Status:
W. Eddy
A. Tiwari
A. Frindell

APIs To Expose SCONEPRO Metadata to Applications


This document describes API considerations to provide applications with SCONEPRO metadata, notifying them of network-supplied information about acceptable network flow rates. Since this information is signalled from the network within the stack below the application, it needs to be made accessible to applications in order for them to pick proper video rates, or to otherwise confine the application behavior within network-defined limits.

Status of This Memo

This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.

Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at

Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."

This Internet-Draft will expire on 4 November 2024.

Table of Contents

1. Introduction

The general problem statement for SCONEPRO is described in the video optimization requirements document [I-D.joras-sadcdn-video-optimization-requirements], including the shaping or throttling that Communication Service Providers (CSPs) perform. While this problem currently has especially large impact on a few large content providers, solutions for SCONEPRO are generally applicable to any applications that use QUIC [RFC9000] and are subject to throttling within CSP networks.

The purpose of this document is only to demonstrate that this is achievable without prescribing a specific solution. It is envisioned that one or more specific API solutions will be defined either through IETF or W3C. At least in its current form, this document is not intended to be published as an RFC.

2. Conventions and Definitions

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.

3. Application Stack Designs

There are a variety of different application stack designs that are relevant. The assumption for SCONEPRO in general is that QUIC is used.

Applications could either use QUIC directly through a linked software library, or applications could be running within a browser, using QUIC indirectly via browser APIs.

The SCONEPRO network rate-limiting information could be discovered by an end-system in several different ways; potential network signaling approaches are described in other documents (e.g. [I-D.ihlar-masque-sconepro-mediabitrate], [I-D.brw-sconepro-rate-policy-discovery], or others). General classes of information signaling include:

  1. Via the QUIC stack, with the information inserted by an on-path SCONEPRO network element.

  2. Via other IP or transport methods below QUIC (e.g. IP extension headers, UDP options, etc.) that might be inserted on the path.

  3. Via the OS, with the information coming in network advertisements separate from the transport connection (e.g. via Router Advertisements or DHCP).

These methods are not necessarily mutually exclusive. For instance, a DHCP option could indicate that certain classes of applications are throttled at a particular rate, while a SCONEPRO on-path mechanism could also provide more explicit per-connection indications of when throttling is active as well.

Table 1
SCONEPRO Solution Type Information Visibility API Definitions
QUIC-based QUIC library or web browser Specific to each QUIC-library, or browser APIs.
IP or UDP-based OS and possibly QUIC library Socket API extension may be needed, e.g. to expose via socket options or other means. For mobile apps using native stacks, OS extensions may be needed.
Other approaches that are not on-path or per-connection OS Per-OS and/or socket API extensions

For solution types that are not QUIC-based, the QUIC implementation could use socket or OS API extensions in order to get the data and convey it up to the applications via its own API. However, QUIC library APIs are not standardized; they differ between common QUIC libraries, and so this document only suggests in a general sense of how the QUIC stack should convey this information to applications.

4. Potential QUIC API Inclusion

While there are no standard QUIC APIs, and there are multiple different styles in use, many QUIC implementations include objects in the API that represent the QUIC connections directly, and allow setting callbacks for connection-related events, or allow direct querying of connection state. SCONEPRO metadata could either be supported as a type of callback event, triggered when the metadata is received, or it could be included within other connection state in a polled or interrogated data structure.

5. Potential Browser API Extensions

For browser applications, there are multiple different browser APIs that might be used; notably including:

In either of these cases, the corresponding W3C API definitions are the proper place for API extensions.

5.1. Potential WebTrans API Extension

WebTransport (WEBTRANS) is anticipated to often be used by SCONEPRO's targeted types of applications in the future, such as browser-based adaptive streaming. The IETF WEBTRANS working group is liasing with W3C as the IETF defines the protocol specification, whereas the W3C defines the API to use it. This case is similar to the IETF RTCWEB and W3C WebRTC WG coordination in the past. The same model of collaboration between IETF and W3C should work for SCONEPRO metadata, and the information provided could be discussed with the WEBTRANS WG in the IETF and notified to the W3C later, either through common participation and/or formal liason statement.

The existing WebTrans API definition from W3C includes a "getStats()" method, that is defned in order to asynchronously gather and report statistics for a WebTransport underlying connection. It returns a WebTransportConnectionStats object that is defined as a dictionary, including a number of items such as:

  • bytesSent

  • packetsSent

  • bytesLost

  • packetsLost

  • bytesReceived

  • packetsReceived

  • smoothedRtt

  • rttVariation

  • minRtt

  • WebTransportDatagramStats datagrams

  • estimatedSendRate

The estimatedSendRate is an unsigned long long, in bits per second, calculated by the congestion control algorithm in the user agent. This would be in the "upstream" direction to a CSP, though, rather than the "downstream" from a CSP, so is not useful to a client application in receiving indication of a downstream throttling rate from the network.

Since other measurements are already included and the WebTransportConnectionStats is a dictionary, it seems natural to extend it to include additional optional fields, such as an allowed media rate, or other types of fields providing the application information that the underlying host or stack have discovered about the presence of throttling or explicit signaling of allowed media rate on a path.

Such extensions might be including at a "MAY" level of conformance statement (rather than "SHALL" as used by all of the currently-defined information elements), as the allowed media rate will not be universally present or even useful for all WebTransport applications. Alternatively, it could be set to a "null" value similar to how the estimatedSendRate is sent when it is unknown by the user agent.

5.2. Content of Metadata

Existing collections of metadata could be appended to the WebTransportConnectionStats, such as (for one specific example), those defined by the CTA-5004 specification [CTA-5004] and CTA-5006 specification [CTA-5006], which standardize JSON objects conveyed by streaming media clients and servers respectively. These CTA specifications are also expected to be usable by intermediaries.

Another example that could be built upon is the proposed flow metadata identifying the DownlinkBitrate [I-D.rwbr-sconepro-flow-metadata].

Several of the use cases defined by CTA-5006 are relevant, including:

  • Provide an estimate of the throughput available between an edge server and a player, such that the player can use that information to enrich its decision about which bitrate to select, especially the initial bitrate decision made at the start of playback.

  • Provide a means for a CDN to instruct all connected players to limit their upper bitrate, in response to an ISP request to reduce congestion on the last-mile network.

  • Allow a CDN to signal to a player a suggested playback bitrate in order to optimize collective QoE.

The "CDN" notion could be replaced with an ISP's on-path throttling device.

As a specific example of metadata for SCONEPRO, CTA-5004 allows clients to indicate multiple types of rate metadata that are related to adaptive coded rate selection in the face of throttling. Which of these options are used depends upon the client, but could be one of:

Table 2
CTA Data Units CTA Description
Measured Throughput Integer kilobits per second (kbps) The throughput between client and server, as measured by the client and MUST be rounded to the nearest 100 kbps. This value, however derived, SHOULD be the value that the client is using to make its next Adaptive Bitrate switching decision. If the client is connected to multiple servers concurrently, it must take care to report only the throughput measured against the receiving server. If the client has multiple concurrent connections to the server, then the intent is that this value communicates the aggregate throughput the client sees across all those connections.
Requested maximum throughput Integer kbps The requested maximum throughput that the client considers sufficient for delivery of the asset. Values MUST be rounded to the nearest 100 kbps. ... Note: This can benefit clients by preventing buffer saturation through over-delivery ...

The CTA-5006 also allows the server to convey a maximum suggested bitrate.

Table 3
CTA Data Units CTA Description
Max suggested bitrate Integer kbps The maximum bitrate value that the player SHOULD play in its Adaptive Bit Rate (ABR) ladder. If the player is playing a bitrate higher than this value, it SHOULD immediately switch to a bitrate lower than or equal to this value.

There are two high-level approaches that might be viable in reusing CTA data types:

  1. Append entire CTA-defined objects as optional components of the WebTransportConnectionStats, e.g. as a "cta5005" object that would be able to fully convey all of the CTA-defined metadata.

  2. Append only selected fields from the CTA specs, reusing the definitions, but only including specific items of interest for SCONEPRO's problem statement, and leaving other CTA-defined metadata to be conveyed through the existing CTA-defined methods.

The API can be agnostic to how the data is conveyed between network or on-path SCONEPRO devices and either clients or servers, but the same API can convey the information to the applications, regardless of how the network signaling works. The semantics of the maxium suggested bitrate from the CTA-5006 match the needed semantics most closely, though since it is for an ABR ladder, it should be described carefully to apply the proper bitrate definition that the throttler is using for "on the wire" packets (including header overhead, etc.) versus the pure media payload stream bitrate.

6. Potential MoQ API Extension

While there is no standard MoQ API, an MoQ session is currently scoped either to a QUIC connection or a WebTransport session, so it should not be difficult to expose information learned by either transport stack to MoQ applications.

7. Security Considerations

General SCONEPRO security considerations are discussed in the other documents covering the problem statement [I-D.joras-sadcdn-video-optimization-requirements] and specific network-to-host signaling methods. This document only exposes the SCONEPRO metadata supplied by the network to applications. There are no additional security considerations raised by this.

8. IANA Considerations

This document has no IANA actions.

9. References

9.1. Normative References

Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, , <>.
Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, , <>.
Iyengar, J., Ed. and M. Thomson, Ed., "QUIC: A UDP-Based Multiplexed and Secure Transport", RFC 9000, DOI 10.17487/RFC9000, , <>.

9.2. Informative References

CTA, "Web Application Video Ecosystem - Common Media Client Data", .
CTA, "Common Media Server Data", .
Boucadair, M., Wing, D., Reddy.K, T., Rajagopalan, S., and G. S. Mishra, "Discovery of Network Rate-Limit Policies (NRLPs)", Work in Progress, Internet-Draft, draft-brw-sconepro-rate-policy-discovery-01, , <>.
Ihlar, M. and M. Kühlewind, "MASQUE extension for signaling media bitrate", Work in Progress, Internet-Draft, draft-ihlar-masque-sconepro-mediabitrate-00, , <>.
Joras, M., Tomar, A., Tiwari, A., and A. Frindell, "SADCDN Video Optimization Requirements", Work in Progress, Internet-Draft, draft-joras-sadcdn-video-optimization-requirements-00, , <>.
Rajagopalan, S., Wing, D., Boucadair, M., and T. Reddy.K, "Flow Metadata for Collaborative Host/Network Signaling", Work in Progress, Internet-Draft, draft-rwbr-sconepro-flow-metadata-01, , <>.


This document represents collaboration and inputs from others, including:

Authors' Addresses

Wesley Eddy
Abhishek Tiwari
Alan Frindell