Skip to content

Commit

Permalink
Remove normative API requirements
Browse files Browse the repository at this point in the history
I don't think normative SHOULD's are useful for describing API
considerations. This also clarifies the datagram/stream acknowledgement
mappings.

Additionally, I removed the API write functions section. I think
resetting streams is a core feature of QUIC and it shouldn't be
necessary to be listed explicitly. And congestion control configuration
is not something that needs an API at runtime. The updates to the
congestion control section in #134 should also make this more clear.
  • Loading branch information
mengelbart committed Oct 11, 2023
1 parent 0821d79 commit b7803be
Showing 1 changed file with 26 additions and 48 deletions.
74 changes: 26 additions & 48 deletions draft-ietf-avtcore-rtp-over-quic.md
Original file line number Diff line number Diff line change
Expand Up @@ -1133,60 +1133,38 @@ met by the QUIC connection.
# API Considerations {#api-considerations}

The mapping described in the previous sections poses some interface requirements
on the QUIC implementation. Although a basic mapping should work without any of
these requirements most of the optimizations regarding rate adaptation and
RTCP mapping require certain functionalities to be exposed to the application.
The following to sections contain a list of information that is required by an
application to implement different optimizations ({{quic-api-read}}) and
functions that a QUIC implementation SHOULD expose to an application
({{quic-api-write}}).
for the QUIC implementation. Although RoQ works without these requirements, some
optimizations regarding rate adaptation and RTCP mapping require certain
functionalities to be exposed to the application.

Each item in the following list can be considered individually. Any exposed
information or function can be used by RoQ regardless of whether the
other items are available. Thus, RoQ does not depend on the
availability of all of the listed features but can apply different optimizations
depending on the functionality exposed by the QUIC implementation.
information or function can be used by RoQ regardless of whether the other items
are available. Thus, RoQ does not depend on the availability of all of the
listed features but can apply different optimizations depending on the
functionality exposed by the QUIC implementation.

## Information to be exported from QUIC {#quic-api-read}

This section provides a list of items that an application might want to export
from an underlying QUIC implementation. It is thus RECOMMENDED that a QUIC
implementation exports the listed items to the application.

* *Maximum Datagram Size*: The maximum datagram size that the QUIC connection
can transmit.
* *Maximum Datagram Size*: The maximum datagram size the QUIC connection can
transmit.
* *Datagram Acknowledgment and Loss*: {{Section 5.2 of !RFC9221}} allows QUIC
implementations to notify the application that a QUIC Datagram was
acknowledged or that it believes a datagram was lost. The exposed information
SHOULD include enough information to allow the application to maintain a
mapping between the datagram that was acknowledged/lost and the RTP packet
that was sent in that datagram.
* *Stream States*: The QUIC implementation SHOULD expose to a sender, how much
of the data that was sent on a stream was successfully delivered and how much
data is still outstanding to be sent or retransmitted.
acknowledged or that it believes a datagram was lost. Given the datagram
acknowledgments and losses, the application can deduce which RTP packets
arrived at the receiver and which were lost (see also {{roc-d}}).
* *Stream States*: The stream states include which parts of the data sent on a
stream were successfully delivered and which are still outstanding to be sent
or retransmitted. If an application keeps track of the RTP packets sent on a
stream, their respective sizes, and in which order they were transmitted, it
can infer which RTP packets were acknowledged according to the definition in
{{roc-s}}.
* *Arrival timestamps*: If the QUIC connection uses a timestamp extension like
{{I-D.draft-smith-quic-receive-ts}} or {{I-D.draft-huitema-quic-ts}}, the
arrival timestamps or one-way delays SHOULD be exposed to the application.
* *Bandwidth Estimation*: If congestion control is done at the transport layer
in the QUIC implementation, the QUIC implementation SHOULD expose an
estimation of the currently available bandwidth to the application. Exposing
the bandwidth estimation avoids the implementation of an additional bandwidth
estimation algorithm in the application.
* *ECN*: If ECN marks are available, they SHOULD be exposed to the application.

## Functions to be exposed by QUIC {#quic-api-write}

This sections lists functions that a QUIC implementation SHOULD expose to an
application to implement different features of the mapping described in the
previous sections of this document.

* *Cancel Streams*: To allow an application to cancel (re)transmission of
packets that are no longer needed, the QUIC implementation MUST expose a way
to cancel the corresponding QUIC streams.
* *Configure Congestion Controller*: If congestion control is to be implemented
at the QUIC connection layer as described in {{cc-quic-layer}}, the QUIC
implementation SHOULD expose an API to allow the application to configure the
specifics of the congestion controller.
{{?I-D.draft-smith-quic-receive-ts}} or {{?I-D.draft-huitema-quic-ts}}, the
arrival timestamps or one-way delays can support the application as described
in {{rtcp-mapping}} and {{congestion-control}}.
* *Bandwidth Estimation*: If a bandwidth estimation is available in the QUIC
implementation, exposing it avoids the implementation of an additional
bandwidth estimation algorithm in the application.
* *ECN*: If ECN marks are available, they can support the bandwidth estimation
of the application if necessary.

# Discussion

Expand Down

0 comments on commit b7803be

Please sign in to comment.