APIs To Expose SCONEPRO Metadata to Applications
draft-eddy-sconepro-api-01

SCONEPRO                                                         W. Eddy
Internet-Draft                                                 A. Tiwari
Intended status: Informational                               A. Frindell
Expires: 4 November 2024                                            Meta
                                                              3 May 2024

            APIs To Expose SCONEPRO Metadata to Applications
                       draft-eddy-sconepro-api-01

Abstract

   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 https://datatracker.ietf.org/drafts/current/.

   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.

Copyright Notice

   Copyright (c) 2024 IETF Trust and the persons identified as the
   document authors.  All rights reserved.

Eddy, et al.             Expires 4 November 2024                [Page 1]
Internet-Draft                SCONEPRO APIs                     May 2024

   This document is subject to BCP 78 and the IETF Trust's Legal
   Provisions Relating to IETF Documents (https://trustee.ietf.org/
   license-info) in effect on the date of publication of this document.
   Please review these documents carefully, as they describe your rights
   and restrictions with respect to this document.  Code Components
   extracted from this document must include Revised BSD License text as
   described in Section 4.e of the Trust Legal Provisions and are
   provided without warranty as described in the Revised BSD License.

Table of Contents

   1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   2
   2.  Conventions and Definitions . . . . . . . . . . . . . . . . .   3
   3.  Application Stack Designs . . . . . . . . . . . . . . . . . .   3
   4.  Potential QUIC API Inclusion  . . . . . . . . . . . . . . . .   4
   5.  Potential Browser API Extensions  . . . . . . . . . . . . . .   4
     5.1.  Potential WebTrans API Extension  . . . . . . . . . . . .   5
     5.2.  Content of Metadata . . . . . . . . . . . . . . . . . . .   6
   6.  Potential MoQ API Extension . . . . . . . . . . . . . . . . .   8
   7.  Security Considerations . . . . . . . . . . . . . . . . . . .   9
   8.  IANA Considerations . . . . . . . . . . . . . . . . . . . . .   9
   9.  References  . . . . . . . . . . . . . . . . . . . . . . . . .   9
     9.1.  Normative References  . . . . . . . . . . . . . . . . . .   9
     9.2.  Informative References  . . . . . . . . . . . . . . . . .   9
   Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . .  10
   Authors' Addresses  . . . . . . . . . . . . . . . . . . . . . . .  10

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.

Eddy, et al.             Expires 4 November 2024                [Page 2]
Internet-Draft                SCONEPRO APIs                     May 2024

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.

Eddy, et al.             Expires 4 November 2024                [Page 3]
Internet-Draft                SCONEPRO APIs                     May 2024

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

                                 Table 1

   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:

   *  WebTransport using QUIC

Eddy, et al.             Expires 4 November 2024                [Page 4]
Internet-Draft                SCONEPRO APIs                     May 2024

   *  Any Javascript HTTP requests that directly or indirectly use
      HTTP/3.

   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

Eddy, et al.             Expires 4 November 2024                [Page 5]
Internet-Draft                SCONEPRO APIs                     May 2024

   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.

Eddy, et al.             Expires 4 November 2024                [Page 6]
Internet-Draft                SCONEPRO APIs                     May 2024

   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:

   +============+==========+==========================================+
   | CTA Data   | Units    | CTA Description                          |
   +============+==========+==========================================+
   | Measured   | Integer  | The throughput between client and        |
   | Throughput | kilobits | server, as measured by the client and    |
   |            | per      | MUST be rounded to the nearest 100 kbps. |
   |            | second   | This value, however derived, SHOULD be   |
   |            | (kbps)   | 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  | Integer  | The requested maximum throughput that    |
   | maximum    | kbps     | the client considers sufficient for      |
   | throughput |          | 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 ...                        |
   +------------+----------+------------------------------------------+

                                 Table 2

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

Eddy, et al.             Expires 4 November 2024                [Page 7]
Internet-Draft                SCONEPRO APIs                     May 2024

    +===========+=========+===========================================+
    | CTA Data  | Units   | CTA Description                           |
    +===========+=========+===========================================+
    | Max       | Integer | The maximum bitrate value that the player |
    | suggested | kbps    | SHOULD play in its Adaptive Bit Rate      |
    | bitrate   |         | (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.              |
    +-----------+---------+-------------------------------------------+

                                  Table 3

   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.

Eddy, et al.             Expires 4 November 2024                [Page 8]
Internet-Draft                SCONEPRO APIs                     May 2024

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

   [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
              Requirement Levels", BCP 14, RFC 2119,
              DOI 10.17487/RFC2119, March 1997,
              <https://www.rfc-editor.org/rfc/rfc2119>.

   [RFC8174]  Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
              2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
              May 2017, <https://www.rfc-editor.org/rfc/rfc8174>.

   [RFC9000]  Iyengar, J., Ed. and M. Thomson, Ed., "QUIC: A UDP-Based
              Multiplexed and Secure Transport", RFC 9000,
              DOI 10.17487/RFC9000, May 2021,
              <https://www.rfc-editor.org/rfc/rfc9000>.

9.2.  Informative References

   [CTA-5004] CTA, "Web Application Video Ecosystem - Common Media
              Client Data", September 2020.

   [CTA-5006] CTA, "Common Media Server Data", November 2022.

   [I-D.brw-sconepro-rate-policy-discovery]
              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, 7 April 2024,
              <https://datatracker.ietf.org/doc/html/draft-brw-sconepro-
              rate-policy-discovery-01>.

Eddy, et al.             Expires 4 November 2024                [Page 9]
Internet-Draft                SCONEPRO APIs                     May 2024

   [I-D.ihlar-masque-sconepro-mediabitrate]
              Ihlar, M. and M. Kühlewind, "MASQUE extension for
              signaling media bitrate", Work in Progress, Internet-
              Draft, draft-ihlar-masque-sconepro-mediabitrate-00, 9
              February 2024, <https://datatracker.ietf.org/doc/html/
              draft-ihlar-masque-sconepro-mediabitrate-00>.

   [I-D.joras-sadcdn-video-optimization-requirements]
              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, 5 January 2024,
              <https://datatracker.ietf.org/doc/html/draft-joras-sadcdn-
              video-optimization-requirements-00>.

   [I-D.rwbr-sconepro-flow-metadata]
              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, 26 April 2024,
              <https://datatracker.ietf.org/doc/html/draft-rwbr-
              sconepro-flow-metadata-01>.

Acknowledgments

   This document represents collaboration and inputs from others,
   including:

   *  Anoop Tomar

   *  Matt Joras

   *  Bryan Tan

Authors' Addresses

   Wesley Eddy
   Meta
   Email: wesleyeddy@meta.com

   Abhishek Tiwari
   Meta
   Email: atiwari@meta.com

   Alan Frindell
   Meta

Eddy, et al.             Expires 4 November 2024               [Page 10]
Internet-Draft                SCONEPRO APIs                     May 2024

   Email: afrind@meta.com

Eddy, et al.             Expires 4 November 2024               [Page 11]