An Abstract Application Layer Interface to Transport Services
draft-ietf-taps-interface-16

9.3.1.  Enqueuing Receives

   Receive takes two parameters to specify the length of data that an
   application is willing to receive, both of which are optional and
   have default values if not specified.

   Connection.Receive(minIncompleteLength?, maxLength?)

   By default, Receive will try to deliver complete Messages in a single
   event (Section 9.3.2.1).

   The application can set a minIncompleteLength value to indicate the
   smallest partial Message data size in bytes that should be delivered
   in response to this Receive.  By default, this value is infinite,
   which means that only complete Messages should be delivered (see
   Section 9.3.2.2 and Section 9.1.2 for more information on how this is
   accomplished).  If this value is set to some smaller value, the
   associated receive event will be triggered only when at least that
   many bytes are available, or the Message is complete with fewer
   bytes, or the system needs to free up memory.  Applications should
   always check the length of the data delivered to the receive event
   and not assume it will be as long as minIncompleteLength in the case
   of shorter complete Messages or memory issues.

   The maxLength argument indicates the maximum size of a Message in
   bytes that the application is currently prepared to receive.  The
   default value for maxLength is infinite.  If an incoming Message is
   larger than the minimum of this size and the maximum Message size on
   receive for the Connection's Protocol Stack, it will be delivered via
   ReceivedPartial events (Section 9.3.2.2).

   Note that maxLength does not guarantee that the application will
   receive that many bytes if they are available; the Transport Services
   API could return ReceivedPartial events with less data than maxLength
   according to implementation constraints.  Note also that maxLength
   and minIncompleteLength are intended only to manage buffering, and
   are not interpreted as a receiver preference for message reordering.

9.3.2.  Receive Events

   Each call to Receive will be paired with a single Receive Event,
   which can be a success or an error.  This allows an application to
   provide backpressure to the transport stack when it is temporarily
   not ready to receive messages.

Trammell, et al.          Expires 5 March 2023                 [Page 69]
Internet-Draft               TAPS Interface               September 2022

   The Transport Services API should allow the application to correlate
   which call to Receive resulted in a particular Receive Event.  The
   manner in which this correlation is indicated is implementation-
   specific.

9.3.2.1.  Received

   Connection -> Received<messageData, messageContext>

   A Received event indicates the delivery of a complete Message.  It
   contains two objects, the received bytes as messageData, and the
   metadata and properties of the received Message as messageContext.

   The messageData object provides access to the bytes that were
   received for this Message, along with the length of the byte array.
   The messageContext is provided to enable retrieving metadata about
   the message and referring to the message.  The messageContext object
   ist described in Section 9.1.1.

   See Section 9.1.2 for handling Message framing in situations where
   the Protocol Stack only provides a byte-stream transport.

9.3.2.2.  ReceivedPartial

Connection -> ReceivedPartial<messageData, messageContext, endOfMessage>

   If a complete Message cannot be delivered in one event, one part of
   the Message can be delivered with a ReceivedPartial event.  To
   continue to receive more of the same Message, the application must
   invoke Receive again.

   Multiple invocations of ReceivedPartial deliver data for the same
   Message by passing the same MessageContext, until the endOfMessage
   flag is delivered or a ReceiveError occurs.  All partial blocks of a
   single Message are delivered in order without gaps.  This event does
   not support delivering discontiguous partial Messages.  If, for
   example, Message A is divided into three pieces (A1, A2, A3) and
   Message B is divided into three pieces (B1, B2, B3), and
   preserveOrder is not Required, the ReceivedPartial may deliver them
   in a sequence like this: A1, B1, B2, A2, A3, B3, because the
   messageContext allows the application to identify the pieces as
   belonging to Message A and B, respectively.  However, a sequence
   like: A1, A3 will never occur.

   If the minIncompleteLength in the Receive request was set to be
   infinite (indicating a request to receive only complete Messages),
   the ReceivedPartial event may still be delivered if one of the
   following conditions is true:

Trammell, et al.          Expires 5 March 2023                 [Page 70]
Internet-Draft               TAPS Interface               September 2022

   *  the underlying Protocol Stack supports message boundary
      preservation, and the size of the Message is larger than the
      buffers available for a single message;

   *  the underlying Protocol Stack does not support message boundary
      preservation, and the Message Framer (see Section 9.1.2) cannot
      determine the end of the message using the buffer space it has
      available; or

   *  the underlying Protocol Stack does not support message boundary
      preservation, and no Message Framer was supplied by the
      application

   Note that in the absence of message boundary preservation or a
   Message Framer, all bytes received on the Connection will be
   represented as one large Message of indeterminate length.

   In the following example, an application only wants to receive up to
   1000 bytes at a time from a Connection.  If a 1500-byte message
   arrives, it would receive the message in two separate ReceivedPartial
   events.

Connection.Receive(1, 1000)

// Receive first 1000 bytes, message is incomplete
Connection -> ReceivedPartial<messageData(1000 bytes), messageContext, false>

Connection.Receive(1, 1000)

// Receive last 500 bytes, message is now complete
Connection -> ReceivedPartial<messageData(500 bytes), messageContext, true>

9.3.2.3.  ReceiveError

   Connection -> ReceiveError<messageContext, reason?>

   A ReceiveError occurs when data is received by the underlying
   Protocol Stack that cannot be fully retrieved or parsed, and when it
   is useful for the application to be notified of such errors.  For
   example, a ReceiveError can indicate that a Message (identified via
   the MessageContext) that was being partially received previously, but
   had not completed, encountered an error and will not be completed.
   This can be useful for an application, which may want to use this
   error as a hint to remove previously received Message parts from
   memory.  As another example, if an incoming Message does not fulfill
   the recvChecksumLen property (see Section 8.1.1), an application can
   use this error as a hint to inform the peer application to adjust the
   msgChecksumLen property (see Section 9.1.3.6).

Trammell, et al.          Expires 5 March 2023                 [Page 71]
Internet-Draft               TAPS Interface               September 2022

   In contrast, internal protocol reception errors (e.g., loss causing
   retransmissions in TCP) are not signalled by this Event.  Conditions
   that irrevocably lead to the termination of the Connection are
   signaled using ConnectionError (see Section 10).

9.3.3.  Receive Message Properties

   Each Message Context may contain metadata from protocols in the
   Protocol Stack; which metadata is available is Protocol Stack
   dependent.  These are exposed through additional read-only Message
   Properties that can be queried from the MessageContext object (see
   Section 9.1.1) passed by the receive event.  The following metadata
   values are supported:

9.3.3.1.  UDP(-Lite)-specific Property: ECN

   When available, Message metadata carries the value of the Explicit
   Congestion Notification (ECN) field.  This information can be used
   for logging and debugging, and for building applications that need
   access to information about the transport internals for their own
   operation.  This property is specific to UDP and UDP-Lite because
   these protocols do not implement congestion control, and hence expose
   this functionality to the application (see [RFC8293], following the
   guidance in [RFC8085])

9.3.3.2.  Early Data

   In some cases it can be valuable to know whether data was read as
   part of early data transfer (before connection establishment has
   finished).  This is useful if applications need to treat early data
   separately, e.g., if early data has different security properties
   than data sent after connection establishment.  In the case of TLS
   1.3, client early data can be replayed maliciously (see [RFC8446]).
   Thus, receivers might wish to perform additional checks for early
   data to ensure it is safely replayable.  If TLS 1.3 is available and
   the recipient Message was sent as part of early data, the
   corresponding metadata carries a flag indicating as such.  If early
   data is enabled, applications should check this metadata field for
   Messages received during connection establishment and respond
   accordingly.

Trammell, et al.          Expires 5 March 2023                 [Page 72]
Internet-Draft               TAPS Interface               September 2022

9.3.3.3.  Receiving Final Messages

   The Message Context can indicate whether or not this Message is the
   Final Message on a Connection.  For any Message that is marked as
   Final, the application can assume that there will be no more Messages
   received on the Connection once the Message has been completely
   delivered.  This corresponds to the final property that may be marked
   on a sent Message, see Section 9.1.3.5.

   Some transport protocols and peers do not support signaling of the
   final property.  Applications therefore should not rely on receiving
   a Message marked Final to know that the sending endpoint is done
   sending on a connection.

   Any calls to Receive once the Final Message has been delivered will
   result in errors.

10.  Connection Termination

   A Connection can be terminated i) by the Local Endpoint (i.e., the
   application calls the Close, CloseGroup, Abort or AbortGroup Action),
   ii) by the Remote Endpoint (i.e., the remote application calls the
   Close, CloseGroup, Abort or AbortGroup Action), or iii) because of an
   error (e.g., a timeout).  A local call of the Close Action will cause
   the Connection to either send a Closed Event or a ConnectionError
   Event, and a local call of the CloseGroup Action will cause all of
   the Connections in the group to either send a Closed Event or a
   ConnectionError Event.  A local call of the Abort Action will cause
   the Connection to send a ConnectionError Event, indicating local
   Abort as a reason, and a local call of the AbortGroup Action will
   cause all of the Connections in the group to send a ConnectionError
   Event, indicating local Abort as a reason.

   Remote Action calls map to Events similar to local calls (e.g., a
   remote Close causes the Connection to either send a Closed Event or a
   ConnectionError Event), but, different from local Action calls, it is
   not guaranteed that such Events will indeed be invoked.  When an
   application needs to free resources associated with a Connection, it
   should therefore not rely on the invocation of such Events due to
   termination calls from the Remote Endpoint, but instead use the local
   termination Actions.

   Close terminates a Connection after satisfying all the requirements
   that were specified regarding the delivery of Messages that the
   application has already given to the Transport Services system.  Upon
   successfully satisfying all these requirements, the Connection will
   send the Closed Event.  For example, if reliable delivery was
   requested for a Message handed over before calling Close, the Closed

Trammell, et al.          Expires 5 March 2023                 [Page 73]
Internet-Draft               TAPS Interface               September 2022

   Event will signify that this Message has indeed been delivered.  This
   Action does not affect any other Connection in the same Connection
   Group.

   Connection.Close()

   The Closed Event informs the application that a Close Action has
   successfully completed, or that the Remote Endpoint has closed the
   Connection.  There is no guarantee that a remote Close will be
   signaled.

   Connection -> Closed<>

   Abort terminates a Connection without delivering any remaining
   Messages.  This action does not affect any other Connection that is
   entangled with this one in a Connection Group.  When the Abort Action
   has finished, the Connection will send a ConnectionError Event,
   indicating local Abort as a reason.

   Connection.Abort()

   CloseGroup gracefully terminates a Connection and any other
   Connections in the same Connection Group.  For example, all of the
   Connections in a group might be streams of a single session for a
   multistreaming protocol; closing the entire group will close the
   underlying session.  See also Section 7.4.  All Connections in the
   group will send a Closed Event when the CloseGroup Action was
   successful.  As with Close, any Messages remaining to be processed on
   a Connection will be handled prior to closing.

   Connection.CloseGroup()

   AbortGroup terminates a Connection and any other Connections that are
   in the same Connection Group without delivering any remaining
   Messages.  When the AbortGroup Action has finished, all Connections
   in the group will send a ConnectionError Event, indicating local
   Abort as a reason.

   Connection.AbortGroup()

   A ConnectionError informs the application that: 1) data could not be
   delivered to the peer after a timeout, or 2) the Connection has been
   aborted (e.g., because the peer has called Abort).  There is no
   guarantee that an Abort from the peer will be signaled.

   Connection -> ConnectionError<reason?>

Trammell, et al.          Expires 5 March 2023                 [Page 74]
Internet-Draft               TAPS Interface               September 2022

11.  Connection State and Ordering of Operations and Events

   This Transport Services API is designed to be independent of an
   implementation's concurrency model.  The details of how exactly
   actions are handled, and how events are dispatched, are
   implementation dependent.

   Each transition of connection state is associated with one of more
   events:

   *  Ready<> occurs when a Connection created with Initiate() or
      InitiateWithSend() transitions to Established state.

   *  ConnectionReceived<> occurs when a Connection created with
      Listen() transitions to Established state.

   *  RendezvousDone<> occurs when a Connection created with
      Rendezvous() transitions to Established state.

   *  Closed<> occurs when a Connection transitions to Closed state
      without error.

   *  EstablishmentError<> occurs when a Connection created with
      Initiate() transitions from Establishing state to Closed state due
      to an error.

   *  ConnectionError<> occurs when a Connection transitions to Closed
      state due to an error in all other circumstances.

   The following diagram shows the possible states of a Connection and
   the events that occur upon a transition from one state to another.

                 (*)                               (**)
   Establishing -----> Established -----> Closing ------> Closed
        |                                                   ^
        |                                                   |
        +---------------------------------------------------+
                     EstablishmentError<>

   (*) Ready<>, ConnectionReceived<>, RendezvousDone<>
   (**) Closed<>, ConnectionError<>

                     Figure 2: Connection State Diagram

   The Transport Services API provides the following guarantees about
   the ordering of operations:

Trammell, et al.          Expires 5 March 2023                 [Page 75]
Internet-Draft               TAPS Interface               September 2022

   *  Sent<> events will occur on a Connection in the order in which the
      Messages were sent (i.e., delivered to the kernel or to the
      network interface, depending on implementation).

   *  Received<> will never occur on a Connection before it is
      Established; i.e. before a Ready<> event on that Connection, or a
      ConnectionReceived<> or RendezvousDone<> containing that
      Connection.

   *  No events will occur on a Connection after it is Closed; i.e.,
      after a Closed<> event, an EstablishmentError<> or
      ConnectionError<> will not occur on that connection.  To ensure
      this ordering, Closed<> will not occur on a Connection while other
      events on the Connection are still locally outstanding (i.e.,
      known to the Transport Services API and waiting to be dealt with
      by the application).

12.  IANA Considerations

   RFC-EDITOR: Please remove this section before publication.

   This document has no Actions for IANA.  Later versions of this
   document may create IANA registries for generic transport property
   names and transport property namespaces (see Section 4.1).

13.  Privacy and Security Considerations

   This document describes a generic API for interacting with a
   Transport Services system.  Part of this API includes configuration
   details for transport security protocols, as discussed in
   Section 6.3.  It does not recommend use (or disuse) of specific
   algorithms or protocols.  Any API-compatible transport security
   protocol ought to work in a Transport Services system.  Security
   considerations for these protocols are discussed in the respective
   specifications.

   The described API is used to exchange information between an
   application and the Transport Services system.  While it is not
   necessarily expected that both systems are implemented by the same
   authority, it is expected that the Transport Services system
   implementation is either provided as a library that is selected by
   the application from a trusted party, or that it is part of the
   operating system that the application also relies on for other tasks.

   In either case, the Transport Services API is an internal interface
   that is used to change information locally between two systems.
   However, as the Transport Services system is responsible for network
   communication, it is in the position to potentially share any

Trammell, et al.          Expires 5 March 2023                 [Page 76]
Internet-Draft               TAPS Interface               September 2022

   information provided by the application with the network or another
   communication peer.  Most of the information provided over the
   Transport Services API are useful to configure and select protocols
   and paths and are not necessarily privacy sensitive.  Still, some
   information could be privacy sensitive because it might reveal usage
   characteristics and habits of the user of an application.

   Of course any communication over a network reveals usage
   characteristics, because all packets, as well as their timing and
   size, are part of the network-visible wire image [RFC8546].  However,
   the selection of a protocol and its configuration also impacts which
   information is visible, potentially in clear text, and which other
   entities can access it.  In most cases, information provided for
   protocol and path selection should not directly translate to
   information that can be observed by network devices on the path.
   However, there might be specific configuration information that is
   intended for path exposure, e.g., a DiffServ codepoint setting, that
   is either provided directly by the application or indirectly
   configured for a traffic profile.

   Applications should be aware that communication attempts can lead to
   more than one connection establishment.  This is the case, for
   example, when the Transport Services system also executes name
   resolution, when support mechanisms such as TURN or ICE are used to
   establish connectivity, if protocols or paths are raised, or if a
   path fails and fallback or re-establishment is supported in the
   Transport Services system.

   Applications should also take care to not assume that all data
   received using the Transport Services API is always complete or well-
   formed.  Specifically, messages that are received partially
   Section 9.3.2.2 could be a source of truncation attacks if
   applications do not distinguish between partial messages and complete
   messages.

   The Transport Services API explicitly does not require the
   application to resolve names, though there is a tradeoff between
   early and late binding of addresses to names.  Early binding allows
   the API implementation to reduce connection setup latency, at the
   cost of potentially limited scope for alternate path discovery during
   Connection establishment, as well as potential additional information
   leakage about application interest when used with a resolution method
   (such as DNS without TLS) which does not protect query
   confidentiality.

   These communication activities are not different from what is used
   today.  However, the goal of a Transport Services system is to
   support such mechanisms as a generic service within the transport

Trammell, et al.          Expires 5 March 2023                 [Page 77]
Internet-Draft               TAPS Interface               September 2022

   layer.  This enables applications to more dynamically benefit from
   innovations and new protocols in the transport, although it reduces
   transparency of the underlying communication actions to the
   application itself.  The Transport Services API is designed such that
   protocol and path selection can be limited to a small and controlled
   set if required by the application for functional or security
   purposes.  Further, a Transport Services system should provide an
   interface to poll information about which protocol and path is
   currently in use as well as provide logging about the communication
   events of each connection.

14.  Acknowledgements

   This work has received funding from the European Union's Horizon 2020
   research and innovation programme under grant agreements No. 644334
   (NEAT) and No. 688421 (MAMI).

   This work has been supported by Leibniz Prize project funds of DFG -
   German Research Foundation: Gottfried Wilhelm Leibniz-Preis 2011 (FKZ
   FE 570/4-1).

   This work has been supported by the UK Engineering and Physical
   Sciences Research Council under grant EP/R04144X/1.

   This work has been supported by the Research Council of Norway under
   its "Toppforsk" programme through the "OCARINA" project.

   Thanks to Stuart Cheshire, Josh Graessley, David Schinazi, and Eric
   Kinnear for their implementation and design efforts, including Happy
   Eyeballs, that heavily influenced this work.  Thanks to Laurent Chuat
   and Jason Lee for initial work on the Post Sockets interface, from
   which this work has evolved.  Thanks to Maximilian Franke for asking
   good questions based on implementation experience and for
   contributing text, e.g., on multicast.

15.  References

15.1.  Normative References

   [I-D.ietf-taps-arch]
              Pauly, T., Trammell, B., Brunstrom, A., Fairhurst, G., and
              C. Perkins, "An Architecture for Transport Services", Work
              in Progress, Internet-Draft, draft-ietf-taps-arch-13, 27
              June 2022, <https://datatracker.ietf.org/doc/html/draft-
              ietf-taps-arch-13>.

Trammell, et al.          Expires 5 March 2023                 [Page 78]
Internet-Draft               TAPS Interface               September 2022

   [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>.

   [RFC2914]  Floyd, S., "Congestion Control Principles", BCP 41,
              RFC 2914, DOI 10.17487/RFC2914, September 2000,
              <https://www.rfc-editor.org/rfc/rfc2914>.

   [RFC8084]  Fairhurst, G., "Network Transport Circuit Breakers",
              BCP 208, RFC 8084, DOI 10.17487/RFC8084, March 2017,
              <https://www.rfc-editor.org/rfc/rfc8084>.

   [RFC8085]  Eggert, L., Fairhurst, G., and G. Shepherd, "UDP Usage
              Guidelines", BCP 145, RFC 8085, DOI 10.17487/RFC8085,
              March 2017, <https://www.rfc-editor.org/rfc/rfc8085>.

   [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>.

   [RFC8303]  Welzl, M., Tuexen, M., and N. Khademi, "On the Usage of
              Transport Features Provided by IETF Transport Protocols",
              RFC 8303, DOI 10.17487/RFC8303, February 2018,
              <https://www.rfc-editor.org/rfc/rfc8303>.

   [RFC8446]  Rescorla, E., "The Transport Layer Security (TLS) Protocol
              Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018,
              <https://www.rfc-editor.org/rfc/rfc8446>.

   [RFC8981]  Gont, F., Krishnan, S., Narten, T., and R. Draves,
              "Temporary Address Extensions for Stateless Address
              Autoconfiguration in IPv6", RFC 8981,
              DOI 10.17487/RFC8981, February 2021,
              <https://www.rfc-editor.org/rfc/rfc8981>.

15.2.  Informative References

   [I-D.ietf-httpbis-priority]
              Oku, K. and L. Pardue, "Extensible Prioritization Scheme
              for HTTP", Work in Progress, Internet-Draft, draft-ietf-
              httpbis-priority-12, 17 January 2022,
              <https://datatracker.ietf.org/doc/html/draft-ietf-httpbis-
              priority-12>.

   [I-D.ietf-taps-impl]
              Brunstrom, A., Pauly, T., Enghardt, T., Tiesel, P. S., and
              M. Welzl, "Implementing Interfaces to Transport Services",

Trammell, et al.          Expires 5 March 2023                 [Page 79]
Internet-Draft               TAPS Interface               September 2022

              Work in Progress, Internet-Draft, draft-ietf-taps-impl-12,
              7 March 2022, <https://datatracker.ietf.org/doc/html/
              draft-ietf-taps-impl-12>.

   [RFC2474]  Nichols, K., Blake, S., Baker, F., and D. Black,
              "Definition of the Differentiated Services Field (DS
              Field) in the IPv4 and IPv6 Headers", RFC 2474,
              DOI 10.17487/RFC2474, December 1998,
              <https://www.rfc-editor.org/rfc/rfc2474>.

   [RFC2597]  Heinanen, J., Baker, F., Weiss, W., and J. Wroclawski,
              "Assured Forwarding PHB Group", RFC 2597,
              DOI 10.17487/RFC2597, June 1999,
              <https://www.rfc-editor.org/rfc/rfc2597>.

   [RFC3246]  Davie, B., Charny, A., Bennet, J.C.R., Benson, K., Le
              Boudec, J.Y., Courtney, W., Davari, S., Firoiu, V., and D.
              Stiliadis, "An Expedited Forwarding PHB (Per-Hop
              Behavior)", RFC 3246, DOI 10.17487/RFC3246, March 2002,
              <https://www.rfc-editor.org/rfc/rfc3246>.

   [RFC3261]  Rosenberg, J., Schulzrinne, H., Camarillo, G., Johnston,
              A., Peterson, J., Sparks, R., Handley, M., and E.
              Schooler, "SIP: Session Initiation Protocol", RFC 3261,
              DOI 10.17487/RFC3261, June 2002,
              <https://www.rfc-editor.org/rfc/rfc3261>.

   [RFC3376]  Cain, B., Deering, S., Kouvelas, I., Fenner, B., and A.
              Thyagarajan, "Internet Group Management Protocol, Version
              3", RFC 3376, DOI 10.17487/RFC3376, October 2002,
              <https://www.rfc-editor.org/rfc/rfc3376>.

   [RFC4594]  Babiarz, J., Chan, K., and F. Baker, "Configuration
              Guidelines for DiffServ Service Classes", RFC 4594,
              DOI 10.17487/RFC4594, August 2006,
              <https://www.rfc-editor.org/rfc/rfc4594>.

   [RFC4604]  Holbrook, H., Cain, B., and B. Haberman, "Using Internet
              Group Management Protocol Version 3 (IGMPv3) and Multicast
              Listener Discovery Protocol Version 2 (MLDv2) for Source-
              Specific Multicast", RFC 4604, DOI 10.17487/RFC4604,
              August 2006, <https://www.rfc-editor.org/rfc/rfc4604>.

   [RFC5245]  Rosenberg, J., "Interactive Connectivity Establishment
              (ICE): A Protocol for Network Address Translator (NAT)
              Traversal for Offer/Answer Protocols", RFC 5245,
              DOI 10.17487/RFC5245, April 2010,
              <https://www.rfc-editor.org/rfc/rfc5245>.

Trammell, et al.          Expires 5 March 2023                 [Page 80]
Internet-Draft               TAPS Interface               September 2022

   [RFC5280]  Cooper, D., Santesson, S., Farrell, S., Boeyen, S.,
              Housley, R., and W. Polk, "Internet X.509 Public Key
              Infrastructure Certificate and Certificate Revocation List
              (CRL) Profile", RFC 5280, DOI 10.17487/RFC5280, May 2008,
              <https://www.rfc-editor.org/rfc/rfc5280>.

   [RFC5482]  Eggert, L. and F. Gont, "TCP User Timeout Option",
              RFC 5482, DOI 10.17487/RFC5482, March 2009,
              <https://www.rfc-editor.org/rfc/rfc5482>.

   [RFC5865]  Baker, F., Polk, J., and M. Dolly, "A Differentiated
              Services Code Point (DSCP) for Capacity-Admitted Traffic",
              RFC 5865, DOI 10.17487/RFC5865, May 2010,
              <https://www.rfc-editor.org/rfc/rfc5865>.

   [RFC7478]  Holmberg, C., Hakansson, S., and G. Eriksson, "Web Real-
              Time Communication Use Cases and Requirements", RFC 7478,
              DOI 10.17487/RFC7478, March 2015,
              <https://www.rfc-editor.org/rfc/rfc7478>.

   [RFC7556]  Anipko, D., Ed., "Multiple Provisioning Domain
              Architecture", RFC 7556, DOI 10.17487/RFC7556, June 2015,
              <https://www.rfc-editor.org/rfc/rfc7556>.

   [RFC7657]  Black, D., Ed. and P. Jones, "Differentiated Services
              (Diffserv) and Real-Time Communication", RFC 7657,
              DOI 10.17487/RFC7657, November 2015,
              <https://www.rfc-editor.org/rfc/rfc7657>.

   [RFC8095]  Fairhurst, G., Ed., Trammell, B., Ed., and M. Kuehlewind,
              Ed., "Services Provided by IETF Transport Protocols and
              Congestion Control Mechanisms", RFC 8095,
              DOI 10.17487/RFC8095, March 2017,
              <https://www.rfc-editor.org/rfc/rfc8095>.

   [RFC8229]  Pauly, T., Touati, S., and R. Mantha, "TCP Encapsulation
              of IKE and IPsec Packets", RFC 8229, DOI 10.17487/RFC8229,
              August 2017, <https://www.rfc-editor.org/rfc/rfc8229>.

   [RFC8260]  Stewart, R., Tuexen, M., Loreto, S., and R. Seggelmann,
              "Stream Schedulers and User Message Interleaving for the
              Stream Control Transmission Protocol", RFC 8260,
              DOI 10.17487/RFC8260, November 2017,
              <https://www.rfc-editor.org/rfc/rfc8260>.

Trammell, et al.          Expires 5 March 2023                 [Page 81]
Internet-Draft               TAPS Interface               September 2022

   [RFC8293]  Ghanwani, A., Dunbar, L., McBride, M., Bannai, V., and R.
              Krishnan, "A Framework for Multicast in Network
              Virtualization over Layer 3", RFC 8293,
              DOI 10.17487/RFC8293, January 2018,
              <https://www.rfc-editor.org/rfc/rfc8293>.

   [RFC8445]  Keranen, A., Holmberg, C., and J. Rosenberg, "Interactive
              Connectivity Establishment (ICE): A Protocol for Network
              Address Translator (NAT) Traversal", RFC 8445,
              DOI 10.17487/RFC8445, July 2018,
              <https://www.rfc-editor.org/rfc/rfc8445>.

   [RFC8489]  Petit-Huguenin, M., Salgueiro, G., Rosenberg, J., Wing,
              D., Mahy, R., and P. Matthews, "Session Traversal
              Utilities for NAT (STUN)", RFC 8489, DOI 10.17487/RFC8489,
              February 2020, <https://www.rfc-editor.org/rfc/rfc8489>.

   [RFC8546]  Trammell, B. and M. Kuehlewind, "The Wire Image of a
              Network Protocol", RFC 8546, DOI 10.17487/RFC8546, April
              2019, <https://www.rfc-editor.org/rfc/rfc8546>.

   [RFC8622]  Bless, R., "A Lower-Effort Per-Hop Behavior (LE PHB) for
              Differentiated Services", RFC 8622, DOI 10.17487/RFC8622,
              June 2019, <https://www.rfc-editor.org/rfc/rfc8622>.

   [RFC8656]  Reddy, T., Ed., Johnston, A., Ed., Matthews, P., and J.
              Rosenberg, "Traversal Using Relays around NAT (TURN):
              Relay Extensions to Session Traversal Utilities for NAT
              (STUN)", RFC 8656, DOI 10.17487/RFC8656, February 2020,
              <https://www.rfc-editor.org/rfc/rfc8656>.

   [RFC8699]  Islam, S., Welzl, M., and S. Gjessing, "Coupled Congestion
              Control for RTP Media", RFC 8699, DOI 10.17487/RFC8699,
              January 2020, <https://www.rfc-editor.org/rfc/rfc8699>.

   [RFC8838]  Ivov, E., Uberti, J., and P. Saint-Andre, "Trickle ICE:
              Incremental Provisioning of Candidates for the Interactive
              Connectivity Establishment (ICE) Protocol", RFC 8838,
              DOI 10.17487/RFC8838, January 2021,
              <https://www.rfc-editor.org/rfc/rfc8838>.

   [RFC8899]  Fairhurst, G., Jones, T., Tüxen, M., Rüngeler, I., and T.
              Völker, "Packetization Layer Path MTU Discovery for
              Datagram Transports", RFC 8899, DOI 10.17487/RFC8899,
              September 2020, <https://www.rfc-editor.org/rfc/rfc8899>.

Trammell, et al.          Expires 5 March 2023                 [Page 82]
Internet-Draft               TAPS Interface               September 2022

   [RFC8922]  Enghardt, T., Pauly, T., Perkins, C., Rose, K., and C.
              Wood, "A Survey of the Interaction between Security
              Protocols and Transport Services", RFC 8922,
              DOI 10.17487/RFC8922, October 2020,
              <https://www.rfc-editor.org/rfc/rfc8922>.

   [RFC8923]  Welzl, M. and S. Gjessing, "A Minimal Set of Transport
              Services for End Systems", RFC 8923, DOI 10.17487/RFC8923,
              October 2020, <https://www.rfc-editor.org/rfc/rfc8923>.

   [TCP-COUPLING]
              Islam, S., Welzl, M., Hiorth, K., Hayes, D., Armitage, G.,
              and S. Gjessing, "ctrlTCP: Reducing Latency through
              Coupled, Heterogeneous Multi-Flow TCP Congestion Control",
              IEEE INFOCOM Global Internet Symposium (GI) workshop (GI
              2018) , 2018.

Appendix A.  Implementation Mapping

   The way the concepts from this abstract API map into concrete APIs in
   a given language on a given platform largely depends on the features
   and norms of the language and the platform.  Actions could be
   implemented as functions or method calls, for instance, and Events
   could be implemented via event queues, handler functions or classes,
   communicating sequential processes, or other asynchronous calling
   conventions.

A.1.  Types

   The basic types mentioned in Section 1.1 typically have natural
   correspondences in practical programming languages, perhaps
   constrained by implementation-specific limitations.  For example:

   *  An Integer can typically be represented in C by an int or long,
      subject to the underlying platform's ranges for each.

   *  In C, a Tuple may be represented as a struct with one member for
      each of the value types in the ordered grouping.  In Python, by
      contrast, a Tuple may be represented natively as a tuple, a
      sequence of dynamically-typed elements.

   *  A Collection may be represented as a std::set in C++ or as a set
      in Python.  In C, it may be represented as an array or as a
      higher-level data structure with appropriate accessors defined.

   The objects described in Section 1.1 can similarly be represented in
   different ways depending on which programming language is used.
   Objects like Preconnections, Connections, and Listeners can be long-

Trammell, et al.          Expires 5 March 2023                 [Page 83]
Internet-Draft               TAPS Interface               September 2022

   lived, and benefit from using object-oriented constructs.  Note that
   in C, these objects may need to provide a way to release or free
   their underlying memory when the application is done using them.  For
   example, since a Preconnection can be used to initiate multiple
   Connections, it is the responsibility of the application to clean up
   the Preconnection memory if necessary.

A.2.  Events and Errors

   This specification treats Events and Errors similarly.  Errors, just
   as any other Events, may occur asynchronously in network
   applications.  However, implementations of this API may report Errors
   synchronously, according to the error handling idioms of the
   implementation platform, where they can be immediately detected, such
   as by generating an exception when attempting to initiate a
   connection with inconsistent Transport Properties.  An error can
   provide an optional reason to the application with further details
   about why the error occurred.

A.3.  Time Duration

   Time duration types are implementation-specific.  For instance, it
   could be a number of seconds, number of milliseconds, or a struct
   timeval in C or a user-defined Duration class in C++.

Appendix B.  Convenience Functions

B.1.  Adding Preference Properties

   TransportProperties will frequently need to set Selection Properties
   of type Preference, therefore implementations can provide special
   actions for adding each preference level i.e,
   TransportProperties.Set(some_property, avoid) is equivalent
   toTransportProperties.Avoid(some_property)`:

   TransportProperties.Require(property)
   TransportProperties.Prefer(property)
   TransportProperties.Ignore(property)
   TransportProperties.Avoid(property)
   TransportProperties.Prohibit(property)

B.2.  Transport Property Profiles

   To ease the use of the Transport Services API, implementations can
   provide a mechanism to create Transport Property objects (see
   Section 6.2) that are pre-configured with frequently used sets of
   properties; the following are in common use in current applications:

Trammell, et al.          Expires 5 March 2023                 [Page 84]
Internet-Draft               TAPS Interface               September 2022

B.2.1.  reliable-inorder-stream

   This profile provides reliable, in-order transport service with
   congestion control.  TCP is an example of a protocol that provides
   this service.  It should consist of the following properties:

                    +=======================+=========+
                    | Property              | Value   |
                    +=======================+=========+
                    | reliability           | require |
                    +-----------------------+---------+
                    | preserveOrder         | require |
                    +-----------------------+---------+
                    | congestionControl     | require |
                    +-----------------------+---------+
                    | preserveMsgBoundaries | ignore  |
                    +-----------------------+---------+

                         Table 2: reliable-inorder-
                             stream preferences

B.2.2.  reliable-message

   This profile provides message-preserving, reliable, in-order
   transport service with congestion control.  SCTP is an example of a
   protocol that provides this service.  It should consist of the
   following properties:

                    +=======================+=========+
                    | Property              | Value   |
                    +=======================+=========+
                    | reliability           | require |
                    +-----------------------+---------+
                    | preserveOrder         | require |
                    +-----------------------+---------+
                    | congestionControl     | require |
                    +-----------------------+---------+
                    | preserveMsgBoundaries | require |
                    +-----------------------+---------+

                         Table 3: reliable-message
                                preferences

B.2.3.  unreliable-datagram

   This profile provides a datagram transport service without any
   reliability guarantee.  An example of a protocol that provides this
   service is UDP.  It consists of the following properties:

Trammell, et al.          Expires 5 March 2023                 [Page 85]
Internet-Draft               TAPS Interface               September 2022

                    +=======================+=========+
                    | Property              | Value   |
                    +=======================+=========+
                    | reliability           | avoid   |
                    +-----------------------+---------+
                    | preserveOrder         | avoid   |
                    +-----------------------+---------+
                    | congestionControl     | ignore  |
                    +-----------------------+---------+
                    | preserveMsgBoundaries | require |
                    +-----------------------+---------+
                    | safelyReplayable      | true    |
                    +-----------------------+---------+

                        Table 4: unreliable-datagram
                                preferences

   Applications that choose this Transport Property Profile would avoid
   the additional latency that could be introduced by retransmission or
   reordering in a transport protocol.

   Applications that choose this Transport Property Profile to reduce
   latency should also consider setting an appropriate Capacity Profile
   Property, see Section 8.1.6 and might benefit from controlling
   checksum coverage, see Section 6.2.7 and Section 6.2.8.

Appendix C.  Relationship to the Minimal Set of Transport Services for
             End Systems

   [RFC8923] identifies a minimal set of transport services that end
   systems should offer.  These services make all non-security-related
   transport features of TCP, MPTCP, UDP, UDP-Lite, SCTP and LEDBAT
   available that 1) require interaction with the application, and 2) do
   not get in the way of a possible implementation over TCP (or, with
   limitations, UDP).  The following text explains how this minimal set
   is reflected in the present API.  For brevity, it is based on the
   list in Section 4.1 of [RFC8923], updated according to the discussion
   in Section 5 of [RFC8923].  The present API covers all elements of
   this section.  This list is a subset of the transport features in
   Appendix A of [RFC8923], which refers to the primitives in "pass 2"
   (Section 4) of [RFC8303] for further details on the implementation
   with TCP, MPTCP, UDP, UDP-Lite, SCTP and LEDBAT.

   *  Connect: Initiate Action (Section 7.1).

   *  Listen: Listen Action (Section 7.2).

Trammell, et al.          Expires 5 March 2023                 [Page 86]
Internet-Draft               TAPS Interface               September 2022

   *  Specify number of attempts and/or timeout for the first
      establishment message: timeout parameter of Initiate (Section 7.1)
      or InitiateWithSend Action (Section 9.2.5).

   *  Disable MPTCP: multipath property (Section 6.2.14).

   *  Hand over a message to reliably transfer (possibly multiple times)
      before connection establishment: InitiateWithSend Action
      (Section 9.2.5).

   *  Change timeout for aborting connection (using retransmit limit or
      time value): connTimeout property, using a time value
      (Section 8.1.3).

   *  Timeout event when data could not be delivered for too long:
      ConnectionError Event (Section 10).

   *  Suggest timeout to the peer: See "TCP-specific Properties: User
      Timeout Option (UTO)" (Section 8.2).

   *  Notification of ICMP error message arrival: softErrorNotify
      (Section 6.2.17) and SoftError Event (Section 8.3.1).

   *  Choose a scheduler to operate between streams of an association:
      connScheduler property (Section 8.1.5).

   *  Configure priority or weight for a scheduler: connPriority
      property (Section 8.1.2).

   *  "Specify checksum coverage used by the sender" and "Disable
      checksum when sending": msgChecksumLen property (Section 9.1.3.6)
      and fullChecksumSend property (Section 6.2.7).

   *  "Specify minimum checksum coverage required by receiver" and
      "Disable checksum requirement when receiving": recvChecksumLen
      property (Section 8.1.1) and fullChecksumRecv property
      (Section 6.2.8).

   *  "Specify DF field": noFragmentation property (Section 9.1.3.9).

   *  Get max. transport-message size that may be sent using a non-
      fragmented IP packet from the configured interface:
      singularTransmissionMsgMaxLen property (Section 8.1.11.2).

   *  Get max. transport-message size that may be received from the
      configured interface: recvMsgMaxLen property (Section 8.1.11.4).

Trammell, et al.          Expires 5 March 2023                 [Page 87]
Internet-Draft               TAPS Interface               September 2022

   *  Obtain ECN field: This is a read-only Message Property of the
      MessageContext object (see "UDP(-Lite)-specific Property: ECN"
      Section 9.3.3.1).

   *  "Specify DSCP field", "Disable Nagle algorithm", "Enable and
      configure a Low Extra Delay Background Transfer": as suggested in
      Section 5.5 of [RFC8923], these transport features are
      collectively offered via the connCapacityProfile property
      (Section 8.1.6).  Per-Message control ("Request not to bundle
      messages") is offered via the msgCapacityProfile property
      (Section 9.1.3.8).

   *  Close after reliably delivering all remaining data, causing an
      event informing the application on the other side: this is offered
      by the Close Action with slightly changed semantics in line with
      the discussion in Section 5.2 of [RFC8923] (Section 10).

   *  "Abort without delivering remaining data, causing an event
      informing the application on the other side" and "Abort without
      delivering remaining data, not causing an event informing the
      application on the other side": this is offered by the Abort
      action without promising that this is signaled to the other side.
      If it is, a ConnectionError Event will be invoked at the peer
      (Section 10).

   *  "Reliably transfer data, with congestion control", "Reliably
      transfer a message, with congestion control" and "Unreliably
      transfer a message": data is transferred via the Send action
      (Section 9.2).  Reliability is controlled via the reliability
      (Section 6.2.1) property and the msgReliable Message Property
      (Section 9.1.3.7).  Transmitting data as a message or without
      delimiters is controlled via Message Framers (Section 9.1.2).  The
      choice of congestion control is provided via the congestionControl
      property (Section 6.2.9).

   *  Configurable Message Reliability: the msgLifetime Message Property
      implements a time-based way to configure message reliability
      (Section 9.1.3.1).

   *  "Ordered message delivery (potentially slower than unordered)" and
      "Unordered message delivery (potentially faster than ordered)":
      these two transport features are controlled via the Message
      Property msgOrdered (Section 9.1.3.3).

Trammell, et al.          Expires 5 March 2023                 [Page 88]
Internet-Draft               TAPS Interface               September 2022

   *  Request not to delay the acknowledgement (SACK) of a message:
      should the protocol support it, this is one of the transport
      features the Transport Services system can apply when an
      application uses the connCapacityProfile Property (Section 8.1.6)
      or the msgCapacityProfile Message Property (Section 9.1.3.8) with
      value Low Latency/Interactive.

   *  Receive data (with no message delimiting): Receive Action
      (Section 9.3) and Received Event (Section 9.3.2.1).

   *  Receive a message: Receive Action (Section 9.3) and Received Event
      (Section 9.3.2.1), using Message Framers (Section 9.1.2).

   *  Information about partial message arrival: Receive Action
      (Section 9.3) and ReceivedPartial Event (Section 9.3.2.2).

   *  Notification of send failures: Expired Event (Section 9.2.2.2) and
      SendError Event (Section 9.2.2.3).

   *  Notification that the stack has no more user data to send:
      applications can obtain this information via the Sent Event
      (Section 9.2.2.1).

   *  Notification to a receiver that a partial message delivery has
      been aborted: ReceiveError Event (Section 9.3.2.3).

   *  Notification of Excessive Retransmissions (early warning below
      abortion threshold): SoftError Event (Section 8.3.1).

Authors' Addresses

   Brian Trammell (editor)
   Google Switzerland GmbH
   Gustav-Gull-Platz 1
   CH- 8004 Zurich
   Switzerland
   Email: ietf@trammell.ch

   Michael Welzl (editor)
   University of Oslo
   PO Box 1080 Blindern
   0316  Oslo
   Norway
   Email: michawe@ifi.uio.no

Trammell, et al.          Expires 5 March 2023                 [Page 89]
Internet-Draft               TAPS Interface               September 2022

   Theresa Enghardt
   Netflix
   121 Albright Way
   Los Gatos, CA 95032,
   United States of America
   Email: ietf@tenghardt.net

   Godred Fairhurst
   University of Aberdeen
   Fraser Noble Building
   Aberdeen, AB24 3UE
   Email: gorry@erg.abdn.ac.uk
   URI:   http://www.erg.abdn.ac.uk/

   Mirja Kuehlewind
   Ericsson
   Ericsson-Allee 1
   Herzogenrath
   Germany
   Email: mirja.kuehlewind@ericsson.com

   Colin Perkins
   University of Glasgow
   School of Computing Science
   Glasgow  G12 8QQ
   United Kingdom
   Email: csp@csperkins.org

   Philipp S. Tiesel
   SAP SE
   Konrad-Zuse-Ring 10
   14469 Potsdam
   Germany
   Email: philipp@tiesel.net

   Tommy Pauly
   Apple Inc.
   One Apple Park Way
   Cupertino, California 95014,
   United States of America
   Email: tpauly@apple.com

Trammell, et al.          Expires 5 March 2023                 [Page 90]