draft-ietf-taps-interface-02.txt   draft-ietf-taps-interface-03.txt 
TAPS Working Group B. Trammell, Ed. TAPS Working Group B. Trammell, Ed.
Internet-Draft ETH Zurich Internet-Draft Google
Intended status: Standards Track M. Welzl, Ed. Intended status: Standards Track M. Welzl, Ed.
Expires: April 25, 2019 University of Oslo Expires: September 12, 2019 University of Oslo
T. Enghardt T. Enghardt
TU Berlin TU Berlin
G. Fairhurst G. Fairhurst
University of Aberdeen University of Aberdeen
M. Kuehlewind M. Kuehlewind
ETH Zurich ETH Zurich
C. Perkins C. Perkins
University of Glasgow University of Glasgow
P. Tiesel P. Tiesel
TU Berlin TU Berlin
C. Wood C. Wood
Apple Inc. Apple Inc.
October 22, 2018 March 11, 2019
An Abstract Application Layer Interface to Transport Services An Abstract Application Layer Interface to Transport Services
draft-ietf-taps-interface-02 draft-ietf-taps-interface-03
Abstract Abstract
This document describes an abstract programming interface to the This document describes an abstract programming interface to the
transport layer, following the Transport Services Architecture. It transport layer, following the Transport Services Architecture. It
supports the asynchronous, atomic transmission of messages over supports the asynchronous, atomic transmission of messages over
transport protocols and network paths dynamically selected at transport protocols and network paths dynamically selected at
runtime. It is intended to replace the traditional BSD sockets API runtime. It is intended to replace the traditional BSD sockets API
as the lowest common denominator interface to the transport layer, in as the lowest common denominator interface to the transport layer, in
an environment where endpoints have multiple interfaces and potential an environment where endpoints have multiple interfaces and potential
skipping to change at page 2, line 4 skipping to change at page 2, line 4
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at https://datatracker.ietf.org/drafts/current/. Drafts is at https://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
This Internet-Draft will expire on April 25, 2019. This Internet-Draft will expire on September 12, 2019.
Copyright Notice Copyright Notice
Copyright (c) 2018 IETF Trust and the persons identified as the Copyright (c) 2019 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(https://trustee.ietf.org/license-info) in effect on the date of (https://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License. described in the Simplified BSD License.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4
2. Terminology and Notation . . . . . . . . . . . . . . . . . . 5 2. Terminology and Notation . . . . . . . . . . . . . . . . . . 5
3. Interface Design Principles . . . . . . . . . . . . . . . . . 6 3. Interface Design Principles . . . . . . . . . . . . . . . . . 6
4. API Summary . . . . . . . . . . . . . . . . . . . . . . . . . 7 4. API Summary . . . . . . . . . . . . . . . . . . . . . . . . . 7
4.1. Transport Properties . . . . . . . . . . . . . . . . . . 7 4.1. Usage Examples . . . . . . . . . . . . . . . . . . . . . 7
4.2. Scope of the Interface Definition . . . . . . . . . . . . 8 4.1.1. Server Example . . . . . . . . . . . . . . . . . . . 8
5. Pre-Establishment Phase . . . . . . . . . . . . . . . . . . . 9 4.1.2. Client Example . . . . . . . . . . . . . . . . . . . 9
5.1. Specifying Endpoints . . . . . . . . . . . . . . . . . . 9 4.1.3. Peer Example . . . . . . . . . . . . . . . . . . . . 10
5.2. Specifying Transport Properties . . . . . . . . . . . . . 11 4.2. Transport Properties . . . . . . . . . . . . . . . . . . 11
5.2.1. Reliable Data Transfer (Connection) . . . . . . . . . 13 4.2.1. Transport Property Names . . . . . . . . . . . . . . 12
5.2.2. Configure per-Message reliability . . . . . . . . . . 13 4.2.2. Transport Property Types . . . . . . . . . . . . . . 13
5.2.3. Preservation of data ordering . . . . . . . . . . . . 13 4.3. Scope of the Interface Definition . . . . . . . . . . . . 13
5.2.4. Use 0-RTT session establishment with an idempotent 5. Pre-Establishment Phase . . . . . . . . . . . . . . . . . . . 14
Message . . . . . . . . . . . . . . . . . . . . . . . 13 5.1. Specifying Endpoints . . . . . . . . . . . . . . . . . . 14
5.2.5. Multistream Connections in Group . . . . . . . . . . 13 5.2. Specifying Transport Properties . . . . . . . . . . . . . 16
5.2.6. Control checksum coverage on sending or receiving . . 13 5.2.1. Reliable Data Transfer (Connection) . . . . . . . . . 18
5.2.7. Congestion control . . . . . . . . . . . . . . . . . 14 5.2.2. Preservation of Message Boundaries . . . . . . . . . 18
5.2.8. Interface Instance or Type . . . . . . . . . . . . . 14 5.2.3. Configure per-Message reliability . . . . . . . . . . 18
5.2.9. Provisioning Domain Instance or Type . . . . . . . . 15 5.2.4. Preservation of data ordering . . . . . . . . . . . . 18
5.3. Specifying Security Parameters and Callbacks . . . . . . 15 5.2.5. Use 0-RTT session establishment with an idempotent
5.3.1. Pre-Connection Parameters . . . . . . . . . . . . . . 16 Message . . . . . . . . . . . . . . . . . . . . . . . 19
5.3.2. Connection Establishment Callbacks . . . . . . . . . 17 5.2.6. Multistream Connections in Group . . . . . . . . . . 19
6. Establishing Connections . . . . . . . . . . . . . . . . . . 17 5.2.7. Control checksum coverage on sending . . . . . . . . 19
6.1. Active Open: Initiate . . . . . . . . . . . . . . . . . . 17 5.2.8. Control checksum coverage on receiving . . . . . . . 19
6.2. Passive Open: Listen . . . . . . . . . . . . . . . . . . 18 5.2.9. Congestion control . . . . . . . . . . . . . . . . . 19
6.3. Peer-to-Peer Establishment: Rendezvous . . . . . . . . . 19 5.2.10. Interface Instance or Type . . . . . . . . . . . . . 20
6.4. Connection Groups . . . . . . . . . . . . . . . . . . . . 21 5.2.11. Provisioning Domain Instance or Type . . . . . . . . 21
7. Sending Data . . . . . . . . . . . . . . . . . . . . . . . . 22 5.2.12. Parallel Use of Multiple Paths . . . . . . . . . . . 21
7.1. Basic Sending . . . . . . . . . . . . . . . . . . . . . . 22 5.2.13. Direction of communication . . . . . . . . . . . . . 22
7.2. Send Events . . . . . . . . . . . . . . . . . . . . . . . 22 5.2.14. Notification of excessive retransmissions . . . . . . 22
7.2.1. Sent . . . . . . . . . . . . . . . . . . . . . . . . 23 5.2.15. Notification of ICMP soft error message arrival . . . 22
7.2.2. Expired . . . . . . . . . . . . . . . . . . . . . . . 23 5.3. Specifying Security Parameters and Callbacks . . . . . . 22
7.2.3. SendError . . . . . . . . . . . . . . . . . . . . . . 23 5.3.1. Pre-Connection Parameters . . . . . . . . . . . . . . 23
7.3. Message Properties . . . . . . . . . . . . . . . . . . . 24 5.3.2. Connection Establishment Callbacks . . . . . . . . . 24
7.3.1. Lifetime . . . . . . . . . . . . . . . . . . . . . . 24 6. Establishing Connections . . . . . . . . . . . . . . . . . . 24
7.3.2. Niceness . . . . . . . . . . . . . . . . . . . . . . 25 6.1. Active Open: Initiate . . . . . . . . . . . . . . . . . . 24
7.3.3. Ordered . . . . . . . . . . . . . . . . . . . . . . . 25 6.2. Passive Open: Listen . . . . . . . . . . . . . . . . . . 26
7.3.4. Idempotent . . . . . . . . . . . . . . . . . . . . . 25 6.3. Peer-to-Peer Establishment: Rendezvous . . . . . . . . . 27
7.3.5. Final . . . . . . . . . . . . . . . . . . . . . . . . 25 6.4. Connection Groups . . . . . . . . . . . . . . . . . . . . 28
7.3.6. Corruption Protection Length . . . . . . . . . . . . 26 7. Sending Data . . . . . . . . . . . . . . . . . . . . . . . . 29
7.3.7. Reliable Data Transfer (Message) . . . . . . . . . . 26 7.1. Basic Sending . . . . . . . . . . . . . . . . . . . . . . 29
7.3.8. Transmission Profile . . . . . . . . . . . . . . . . 26 7.2. Send Events . . . . . . . . . . . . . . . . . . . . . . . 30
7.3.9. Singular Transmission . . . . . . . . . . . . . . . . 27 7.2.1. Sent . . . . . . . . . . . . . . . . . . . . . . . . 30
7.4. Partial Sends . . . . . . . . . . . . . . . . . . . . . . 27 7.2.2. Expired . . . . . . . . . . . . . . . . . . . . . . . 30
7.5. Batching Sends . . . . . . . . . . . . . . . . . . . . . 28 7.2.3. SendError . . . . . . . . . . . . . . . . . . . . . . 31
7.6. Send on Active Open: InitiateWithIdempotentSend . . . . . 28 7.3. Message Properties . . . . . . . . . . . . . . . . . . . 31
7.7. Sender-side Framing . . . . . . . . . . . . . . . . . . . 29 7.3.1. Lifetime . . . . . . . . . . . . . . . . . . . . . . 32
8. Receiving Data . . . . . . . . . . . . . . . . . . . . . . . 29 7.3.2. Priority . . . . . . . . . . . . . . . . . . . . . . 32
8.1. Enqueuing Receives . . . . . . . . . . . . . . . . . . . 30 7.3.3. Ordered . . . . . . . . . . . . . . . . . . . . . . . 33
8.2. Receive Events . . . . . . . . . . . . . . . . . . . . . 30 7.3.4. Idempotent . . . . . . . . . . . . . . . . . . . . . 33
8.2.1. Received . . . . . . . . . . . . . . . . . . . . . . 30 7.3.5. Final . . . . . . . . . . . . . . . . . . . . . . . . 33
8.2.2. ReceivedPartial . . . . . . . . . . . . . . . . . . . 31 7.3.6. Corruption Protection Length . . . . . . . . . . . . 34
8.2.3. ReceiveError . . . . . . . . . . . . . . . . . . . . 32 7.3.7. Reliable Data Transfer (Message) . . . . . . . . . . 34
8.3. Message Receive Context . . . . . . . . . . . . . . . . . 32 7.3.8. Message Capacity Profile Override . . . . . . . . . . 34
8.3.1. ECN . . . . . . . . . . . . . . . . . . . . . . . . . 32 7.3.9. Singular Transmission . . . . . . . . . . . . . . . . 35
8.3.2. Early Data . . . . . . . . . . . . . . . . . . . . . 32 7.4. Partial Sends . . . . . . . . . . . . . . . . . . . . . . 35
8.3.3. Receiving Final Messages . . . . . . . . . . . . . . 33 7.5. Batching Sends . . . . . . . . . . . . . . . . . . . . . 36
8.4. Receiver-side De-framing over Stream Protocols . . . . . 33 7.6. Send on Active Open: InitiateWithSend . . . . . . . . . . 36
9. Managing Connections . . . . . . . . . . . . . . . . . . . . 34 7.7. Sender-side Framing . . . . . . . . . . . . . . . . . . . 37
9.1. Generic Connection Properties . . . . . . . . . . . . . . 35 8. Receiving Data . . . . . . . . . . . . . . . . . . . . . . . 37
9.1.1. Notification of excessive retransmissions . . . . . . 35 8.1. Enqueuing Receives . . . . . . . . . . . . . . . . . . . 37
9.1.2. Retransmission threshold before excessive 8.2. Receive Events . . . . . . . . . . . . . . . . . . . . . 38
retransmission notification . . . . . . . . . . . . . 36 8.2.1. Received . . . . . . . . . . . . . . . . . . . . . . 38
9.1.3. Notification of ICMP soft error message arrival . . . 36 8.2.2. ReceivedPartial . . . . . . . . . . . . . . . . . . . 39
9.1.4. Required minimum coverage of the checksum for 8.2.3. ReceiveError . . . . . . . . . . . . . . . . . . . . 39
receiving . . . . . . . . . . . . . . . . . . . . . . 36 8.3. Message Receive Context . . . . . . . . . . . . . . . . . 40
9.1.5. Niceness (Connection) . . . . . . . . . . . . . . . . 36 8.3.1. ECN . . . . . . . . . . . . . . . . . . . . . . . . . 40
9.1.6. Timeout for aborting Connection . . . . . . . . . . . 37 8.3.2. Early Data . . . . . . . . . . . . . . . . . . . . . 40
9.1.7. Connection group transmission scheduler . . . . . . . 37 8.3.3. Receiving Final Messages . . . . . . . . . . . . . . 40
9.1.8. Maximum message size concurrent with Connection 8.4. Receiver-side De-framing over Stream Protocols . . . . . 41
establishment . . . . . . . . . . . . . . . . . . . . 37 9. Managing Connections . . . . . . . . . . . . . . . . . . . . 41
9.1.9. Maximum Message size before fragmentation or 9.1. Generic Connection Properties . . . . . . . . . . . . . . 43
segmentation . . . . . . . . . . . . . . . . . . . . 37 9.1.1. Retransmission threshold before excessive
9.1.10. Maximum Message size on send . . . . . . . . . . . . 37 retransmission notification . . . . . . . . . . . . . 43
9.1.11. Maximum Message size on receive . . . . . . . . . . . 37 9.1.2. Required minimum coverage of the Corruption
9.1.12. Capacity Profile . . . . . . . . . . . . . . . . . . 38 Protection for receiving . . . . . . . . . . . . . . 43
9.2. Soft Errors . . . . . . . . . . . . . . . . . . . . . . . 39 9.1.3. Priority (Connection) . . . . . . . . . . . . . . . . 44
9.1.4. Timeout for aborting Connection . . . . . . . . . . . 44
10. Connection Termination . . . . . . . . . . . . . . . . . . . 39 9.1.5. Connection group transmission scheduler . . . . . . . 44
11. Connection State and Ordering of Operations and Events . . . 40 9.1.6. Maximum message size concurrent with Connection
12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 41 establishment . . . . . . . . . . . . . . . . . . . . 44
13. Security Considerations . . . . . . . . . . . . . . . . . . . 41 9.1.7. Maximum Message size before fragmentation or
14. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 41 segmentation . . . . . . . . . . . . . . . . . . . . 44
15. References . . . . . . . . . . . . . . . . . . . . . . . . . 42 9.1.8. Maximum Message size on send . . . . . . . . . . . . 45
15.1. Normative References . . . . . . . . . . . . . . . . . . 42 9.1.9. Maximum Message size on receive . . . . . . . . . . . 45
15.2. Informative References . . . . . . . . . . . . . . . . . 43 9.1.10. Capacity Profile . . . . . . . . . . . . . . . . . . 45
Appendix A. Additional Properties . . . . . . . . . . . . . . . 44 9.1.11. Bounds on Send or Receive Rate . . . . . . . . . . . 47
A.1. Experimental Transport Properties . . . . . . . . . . . . 45 9.1.12. TCP-specific Property: User Timeout . . . . . . . . . 47
A.1.1. Direction of communication . . . . . . . . . . . . . 45 9.2. Soft Errors . . . . . . . . . . . . . . . . . . . . . . . 47
A.1.2. Suggest a timeout to the Remote Endpoint . . . . . . 45 9.3. Excessive retransmissions . . . . . . . . . . . . . . . . 48
A.1.3. Abort timeout to suggest to the Remote Endpoint . . . 46 10. Connection Termination . . . . . . . . . . . . . . . . . . . 48
A.1.4. Traffic Category . . . . . . . . . . . . . . . . . . 46 11. Connection State and Ordering of Operations and Events . . . 48
A.1.5. Size to be Sent or Received . . . . . . . . . . . . . 46 12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 50
A.1.6. Duration . . . . . . . . . . . . . . . . . . . . . . 47 13. Security Considerations . . . . . . . . . . . . . . . . . . . 50
A.1.7. Send or Receive Bit-rate . . . . . . . . . . . . . . 47 14. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 50
A.1.8. Cost Preferences . . . . . . . . . . . . . . . . . . 47 15. References . . . . . . . . . . . . . . . . . . . . . . . . . 50
Appendix B. Sample API definition in Go . . . . . . . . . . . . 48 15.1. Normative References . . . . . . . . . . . . . . . . . . 50
15.2. Informative References . . . . . . . . . . . . . . . . . 51
Appendix A. Additional Properties . . . . . . . . . . . . . . . 53
A.1. Experimental Transport Properties . . . . . . . . . . . . 53
A.1.1. Cost Preferences . . . . . . . . . . . . . . . . . . 53
Appendix B. Sample API definition in Go . . . . . . . . . . . . 54
Appendix C. Relationship to the Minimal Set of Transport Appendix C. Relationship to the Minimal Set of Transport
Services for End Systems . . . . . . . . . . . . . . 48 Services for End Systems . . . . . . . . . . . . . . 54
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 51 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 58
1. Introduction 1. Introduction
The BSD Unix Sockets API's SOCK_STREAM abstraction, by bringing The BSD Unix Sockets API's SOCK_STREAM abstraction, by bringing
network sockets into the UNIX programming model, allowing anyone who network sockets into the UNIX programming model, allowing anyone who
knew how to write programs that dealt with sequential-access files to knew how to write programs that dealt with sequential-access files to
also write network applications, was a revolution in simplicity. The also write network applications, was a revolution in simplicity. The
simplicity of this API is a key reason the Internet won the protocol simplicity of this API is a key reason the Internet won the protocol
wars of the 1980s. SOCK_STREAM is tied to the Transmission Control wars of the 1980s. SOCK_STREAM is tied to the Transmission Control
Protocol (TCP), specified in 1981 [RFC0793]. TCP has scaled Protocol (TCP), specified in 1981 [RFC0793]. TCP has scaled
skipping to change at page 5, line 34 skipping to change at page 5, line 40
o An Action is performed on an Object: o An Action is performed on an Object:
Object.Action() Object.Action()
o An Object sends an Event: o An Object sends an Event:
Object -> Event<> Object -> Event<>
o An Action takes a set of Parameters; an Event contains a set of o An Action takes a set of Parameters; an Event contains a set of
Parameters: Parameters. Action parameters whose names are suffixed with a
question mark are optional.
Action(parameter, parameter, ...) / Event<parameter, parameter, ...> Action(param0, param1?, ...) / Event<param0, param1, ...>
Actions associated with no Object are Actions on the abstract Actions associated with no Object are Actions on the abstract
interface itself; they are equivalent to Actions on a per-application interface itself; they are equivalent to Actions on a per-application
global context. global context.
How these abstract concepts map into concrete implementations of this How these abstract concepts map into concrete implementations of this
API in a given language on a given platform is largely dependent on API in a given language on a given platform is largely dependent on
the features of the language and the platform. Actions could be the features of the language and the platform. Actions could be
implemented as functions or method calls, for instance, and Events implemented as functions or method calls, for instance, and Events
could be implemented via callbacks, communicating sequential could be implemented via callbacks, communicating sequential
skipping to change at page 7, line 40 skipping to change at page 7, line 48
application support through a deframing callback which finds message application support through a deframing callback which finds message
boundaries in a stream. Messages are received asynchronously through boundaries in a stream. Messages are received asynchronously through
a callback registered by the application. Errors and other a callback registered by the application. Errors and other
notifications also happen asynchronously on the Connection. notifications also happen asynchronously on the Connection.
Section 5, Section 6, Section 7, Section 8, and Section 10 describe Section 5, Section 6, Section 7, Section 8, and Section 10 describe
the details of application interaction with Objects through Actions the details of application interaction with Objects through Actions
and Events in each phase of a Connection, following the phases and Events in each phase of a Connection, following the phases
described in [I-D.ietf-taps-arch]. described in [I-D.ietf-taps-arch].
4.1. Transport Properties 4.1. Usage Examples
The following usage examples illustrate how an application might use
a Transport Services Interface to:
o Act as a server, by listening for incoming connections, receiving
requests, and sending responses, see Section 4.1.1.
o Act as a client, by connecting to a remote endpoint using
Initiate, sending requests, and receiving responses, see
Section 4.1.2.
o Act as a peer, by connecting to a remote endpoint using Rendezvous
while simultaneously waiting for incoming Connections, sending
Messages, and receiving Messages, see Section 4.1.3.
The examples in this section presume that a transport protocol is
available between the endpoints which provides Reliable Data
Transfer, Preservation of data ordering, and Preservation of Message
Boundaries. In this case, the application can choose to receive only
complete messages.
If none of the available transport protocols provides Preservation of
Message Boundaries, but there is a transport protocol which provides
a reliable ordered octet stream, an application may receive this
octet stream as partial Messages and transform it into application-
layer Messages. Alternatively, an application may provide a
Deframer, which is a function that transforms an octet stream into a
sequence of Messages, see Section 8.4.
4.1.1. Server Example
This is an example of how an application might listen for incoming
Connections using the Transport Services Interface, receive a
request, and send a response.
LocalSpecifier := NewLocalEndpoint()
LocalSpecifier.WithInterface("any")
LocalSpecifier.WithService("https")
TransportProperties := NewTransportProperties()
TransportProperties.Require(preserve-msg-boundaries)
// Reliable Data Transfer and Preserve Order are Required by default
SecurityParameters := NewSecurityParameters()
SecurityParameters.AddIdentity(identity)
SecurityParameters.AddPrivateKey(privateKey, publicKey)
// Specifying a remote endpoint is optional when using Listen()
Preconnection := NewPreconnection(LocalSpecifier,
None,
TransportProperties,
SecurityParameters)
Preconnection.Listen()
Preconnection -> ConnectionReceived<Connection>
// Only receive complete messages
Connection.Receive()
Connection -> Received(messageDataRequest, messageContext)
Connection.Send(messageDataResponse)
Connection.Close()
// Stop listening for incoming Connections
Preconnection.Stop()
4.1.2. Client Example
This is an example of how an application might connect to a remote
application using the Transport Services Interface, send a request,
and receive a response.
RemoteSpecifier := NewRemoteEndpoint()
RemoteSpecifier.WithHostname("example.com")
RemoteSpecifier.WithService("https")
TransportProperties := NewTransportProperties()
TransportProperties.Require(preserve-msg-boundaries)
// Reliable Data Transfer and Preserve Order are Required by default
SecurityParameters := NewSecurityParameters()
TrustCallback := New Callback({
// Verify identity of the remote endpoint, return the result
})
SecurityParameters.SetTrustVerificationCallback(TrustCallback)
// Specifying a local endpoint is optional when using Initiate()
Preconnection := NewPreconnection(None,
RemoteSpecifier,
TransportPreperties,
SecurityParameters)
Connection := Preconnection.Initiate()
Connection -> Ready<>
Connection.Send(messageDataRequest)
// Only receive complete messages
Connection.Receive()
Connection -> Received(messageDataResponse, messageContext)
Connection.Close()
4.1.3. Peer Example
This is an example of how an application might establish a connection
with a peer using Rendezvous(), send a Message, and receive a
Message.
LocalSpecifier := NewLocalEndpoint()
LocalSpecifier.WithPort(9876)
RemoteSpecifier := NewRemoteEndpoint()
RemoteSpecifier.WithHostname("example.com")
RemoteSpecifier.WithPort(9877)
TransportProperties := NewTransportProperties()
TransportProperties.Require(preserve-msg-boundaries)
// Reliable Data Transfer and Preserve Order are Required by default
SecurityParameters := NewSecurityParameters()
SecurityParameters.AddIdentity(identity)
SecurityParameters.AddPrivateKey(privateKey, publicKey)
TrustCallback := New Callback({
// Verify identity of the remote endpoint, return the result
})
SecurityParameters.SetTrustVerificationCallback(trustCallback)
// Both local and remote endpoint must be specified
Preconnection := NewPreconnection(LocalSpecifier,
RemoteSpecifier,
TransportPreperties,
SecurityParameters)
Preconnection.Rendezvous()
Preconnection -> RendezvousDone<Connection>
Connection.Send(messageDataRequest)
// Only receive complete messages
Connection.Receive()
Connection -> Received(messageDataResponse, messageContext)
Connection.Close()
4.2. Transport Properties
Each application using the Transport Services Interface declares its Each application using the Transport Services Interface declares its
preferences for how the transport service should operate using preferences for how the transport service should operate using
properties at each stage of the lifetime of a connection. During properties at each stage of the lifetime of a connection. During
pre-establishment, Selection Properties Section 5.2 are used to pre-establishment, Selection Properties (see Section 5.2) are used to
specify which paths and protocol stacks can be used and are preferred specify which paths and protocol stacks can be used and are preferred
by the application, and Connection Properties Section 9.1 can be used by the application, and Connection Properties (see Section 9.1) can
to fine-tune the eventually established connection. These Connection be used to influence decisions made during establishment and to fine-
Properties can also be used to monitor and fine-tune established tune the eventually established connection. These Connection
connections. The behavior of the selected protocol stack(s) when Properties can also be used later, to monitor and fine-tune
sending Messages is controlled by Message Properties Section 7.3. established connections. The behavior of the selected protocol
stack(s) when sending Messages is controlled by Message Properties
(see Section 7.3).
Collectively, Selection, Connection, and Message Properties can be Collectively, Selection, Connection, and Message Properties can be
referred to as Transport Properties. All Transport Properties, referred to as Transport Properties. All Transport Properties,
regardless of the phase in which they are used, are organized within regardless of the phase in which they are used, are organized within
a single namespace. This enables setting them as defaults in earlier a single namespace. This enables setting them as defaults in earlier
stages and querying them in later stages: - Connection Properties can stages and querying them in later stages: - Connection Properties can
be set on Preconnections - Message Properties can be set on be set on Preconnections - Message Properties can be set on
Preconnections and Connections - The effect of Selection Properties Preconnections and Connections - The effect of Selection Properties
can be queried on Connections and Messages can be queried on Connections and Messages
Note that Configuring Connection Properties and Message Properties on
Preconnections is preferred over setting them later. Connection
Properties specified early on may be used as additional input to the
selection process. Also note that Protocol Specific Properties, see
Section 4.2.1, should not be used as an input to the selection
process.
4.2.1. Transport Property Names
Transport Properties are referred to by property names. These names
are lower-case strings whereby words are separated by hyphens. These
names serve two purposes:
o Allow different components of a TAPS implementation to pass
Transport Properties, e.g., between a language frontend and a
policy manager.
o Make code of different TAPS implementations look similar.
Transport Property Names are hierarchically organized in the form
[<Namespace>.]<PropertyName>.
o The Namespace part is empty for well known, generic properties,
i.e., for properties defined by an RFC which are not protocol
specific.
o Protocol Specific Properties must use the protocol acronym as
Namespace, e.g., "tcp" for TCP specific Transport Properties. For
IETF protocols, property names under these namespaces should be
defined in an RFC.
o Vendor or implementation specific properties must use a a string
identifying the vendor or implementation as Namespace.
4.2.2. Transport Property Types
Transport Properties can have one of a set of data types: Transport Properties can have one of a set of data types:
o Boolean: can take the values "true" and "false"; representation is o Boolean: can take the values "true" and "false"; representation is
implementation-dependent. implementation-dependent.
o Integer: can take positive or negative numeric values; range and o Integer: can take positive or negative numeric integer values;
range and representation is implementation-dependent.
o Numeric: can take positive or negative numeric values; range and
representation is implementation-dependent. representation is implementation-dependent.
o Enumeration: can take one value of a finite set of values, o Enumeration: can take one value of a finite set of values,
dependent on the property itself. The representation is dependent on the property itself. The representation is
implementation dependent; however, implementations MUST provide a implementation dependent; however, implementations MUST provide a
method for the application to determine the entire set of possible method for the application to determine the entire set of possible
values for each property. values for each property.
o Preference: can take one of five values (Prohibit, Avoid, Ignore, o Preference: can take one of five values (Prohibit, Avoid, Ignore,
Prefer, Require) for the level of preference of a given property Prefer, Require) for the level of preference of a given property
during protocol selection; see Section 5.2. during protocol selection; see Section 5.2.
4.2. Scope of the Interface Definition 4.3. Scope of the Interface Definition
This document defines a language- and platform-independent interface This document defines a language- and platform-independent interface
to a Transport Services system. Given the wide variety of languages to a Transport Services system. Given the wide variety of languages
and language conventions used to write applications that use the and language conventions used to write applications that use the
transport layer to connect to other applications over the Internet, transport layer to connect to other applications over the Internet,
this independence makes this interface necessarily abstract. While this independence makes this interface necessarily abstract. While
there is no interoperability benefit to tightly defining how the there is no interoperability benefit to tightly defining how the
interface be presented to application programmers in diverse interface be presented to application programmers in diverse
platforms, maintaining the "shape" of the abstract interface across platforms, maintaining the "shape" of the abstract interface across
these platforms reduces the effort for programmers who learn the these platforms reduces the effort for programmers who learn the
skipping to change at page 9, line 12 skipping to change at page 14, line 7
names for substantially equivalent objects for networking by names for substantially equivalent objects for networking by
convention. convention.
o Implementations of this interface SHOULD implement each Selection o Implementations of this interface SHOULD implement each Selection
Property, Connection Property, and Message Context Property Property, Connection Property, and Message Context Property
specified in this document, exclusive of appendices, even if said specified in this document, exclusive of appendices, even if said
implementation is a non-operation, e.g. because transport implementation is a non-operation, e.g. because transport
protocols implementing a given Property are not available on the protocols implementing a given Property are not available on the
platform. platform.
o Implementations may use other representations for Transport
Property Names, e.g., by providing constants or static singleton
objects, but should provide a straight-forward mapping between
their representation and the property names specified here.
5. Pre-Establishment Phase 5. Pre-Establishment Phase
The pre-establishment phase allows applications to specify properties The pre-establishment phase allows applications to specify properties
for the Connections they are about to make, or to query the API about for the Connections they are about to make, or to query the API about
potential connections they could make. potential connections they could make.
A Preconnection Object represents a potential Connection. It has A Preconnection Object represents a potential Connection. It has
state that describes properties of a Connection that might exist in state that describes properties of a Connection that might exist in
the future. This state comprises Local Endpoint and Remote Endpoint the future. This state comprises Local Endpoint and Remote Endpoint
Objects that denote the endpoints of the potential Connection (see Objects that denote the endpoints of the potential Connection (see
skipping to change at page 11, line 22 skipping to change at page 16, line 22
The protocol(s) and path(s) selected as candidates during The protocol(s) and path(s) selected as candidates during
establishment are determined and configured using these properties. establishment are determined and configured using these properties.
Since there could be paths over which some transport protocols are Since there could be paths over which some transport protocols are
unable to operate, or remote endpoints that support only specific unable to operate, or remote endpoints that support only specific
network addresses or transports, transport protocol selection is network addresses or transports, transport protocol selection is
necessarily tied to path selection. This may involve choosing necessarily tied to path selection. This may involve choosing
between multiple local interfaces that are connected to different between multiple local interfaces that are connected to different
access networks. access networks.
Selection properties are represented as preferences, which can have Most Selection Properties are represented as preferences, which can
one of five preference levels: have one of five preference levels:
+------------+------------------------------------------------------+ +------------+------------------------------------------------------+
| Preference | Effect | | Preference | Effect |
+------------+------------------------------------------------------+ +------------+------------------------------------------------------+
| Require | Select only protocols/paths providing the property, | | Require | Select only protocols/paths providing the property, |
| | fail otherwise | | | fail otherwise |
| | | | | |
| Prefer | Prefer protocols/paths providing the property, | | Prefer | Prefer protocols/paths providing the property, |
| | proceed otherwise | | | proceed otherwise |
| | | | | |
| Ignore | Cancel any system default preference for this | | Ignore | No preference |
| | property |
| | | | | |
| Avoid | Prefer protocols/paths not providing the property, | | Avoid | Prefer protocols/paths not providing the property, |
| | proceed otherwise | | | proceed otherwise |
| | | | | |
| Prohibit | Select only protocols/paths not providing the | | Prohibit | Select only protocols/paths not providing the |
| | property, fail otherwise | | | property, fail otherwise |
+------------+------------------------------------------------------+ +------------+------------------------------------------------------+
In addition, the pseudo-level "Default" can be used to reset the
property to the default level used by the implementation. This level
will never show up when queuing the value of a preference - the
effective preference must be returned instead.
Internally, the transport system will first exclude all protocols and Internally, the transport system will first exclude all protocols and
paths that match a Prohibit, then exclude all protocols and paths paths that match a Prohibit, then exclude all protocols and paths
that do not match a Require, then sort candidates according to that do not match a Require, then sort candidates according to
Preferred properties, and then use Avoided properties as a Preferred properties, and then use Avoided properties as a
tiebreaker. Selection Properties which select paths take preference tiebreaker. Selection Properties which select paths take preference
over those which select protocols. For example, if an application over those which select protocols. For example, if an application
indicates a preference for a specific path by specifying an indicates a preference for a specific path by specifying an
interface, but also a preference for a protocol not available on this interface, but also a preference for a protocol not available on this
path, the transport system will try the path first, ignoring the path, the transport system will try the path first, ignoring the
preference. preference.
skipping to change at page 12, line 30 skipping to change at page 17, line 33
Selection Properties can be added to a TransportProperties object Selection Properties can be added to a TransportProperties object
using special actions for each preference level i.e, using special actions for each preference level i.e,
"TransportProperties.Add(some_property, avoid)" is equivalent to "TransportProperties.Add(some_property, avoid)" is equivalent to
"TransportProperties.Avoid(some_property)": "TransportProperties.Avoid(some_property)":
TransportProperties.Require(property) TransportProperties.Require(property)
TransportProperties.Prefer(property) TransportProperties.Prefer(property)
TransportProperties.Ignore(property) TransportProperties.Ignore(property)
TransportProperties.Avoid(property) TransportProperties.Avoid(property)
TransportProperties.Prohibit(property) TransportProperties.Prohibit(property)
TransportProperties.Default(property)
For an existing Connection, the Transport Properties can be queried For an existing Connection, the Transport Properties can be queried
any time by using the following call on the Connection Object: any time by using the following call on the Connection Object:
TransportProperties := Connection.GetTransportProperties() TransportProperties := Connection.GetTransportProperties()
A Connection gets its Transport Properties either by being explicitly A Connection gets its Transport Properties either by being explicitly
configured via a Preconnection, by configuration after establishment, configured via a Preconnection, by configuration after establishment,
or by inheriting them from an antecedent via cloning; see Section 6.4 or by inheriting them from an antecedent via cloning; see Section 6.4
for more. for more.
skipping to change at page 13, line 10 skipping to change at page 18, line 15
other properties. other properties.
An implementation of this interface must provide sensible defaults An implementation of this interface must provide sensible defaults
for Selection Properties. The recommended defaults given for each for Selection Properties. The recommended defaults given for each
property below represent a configuration that can be implemented over property below represent a configuration that can be implemented over
TCP. An alternate set of default Protocol Selection Properties would TCP. An alternate set of default Protocol Selection Properties would
represent a configuration that can be implemented over UDP. represent a configuration that can be implemented over UDP.
5.2.1. Reliable Data Transfer (Connection) 5.2.1. Reliable Data Transfer (Connection)
Name: reliability
This property specifies whether the application needs to use a This property specifies whether the application needs to use a
transport protocol that ensures that all data is received on the transport protocol that ensures that all data is received on the
other side without corruption. This also entails being notified when other side without corruption. This also entails being notified when
a Connection is closed or aborted. The recommended default is to a Connection is closed or aborted. The recommended default is to
enable Reliable Data Transfer. Require Reliable Data Transfer.
5.2.2. Configure per-Message reliability 5.2.2. Preservation of Message Boundaries
Name: preserve-msg-boundaries
This property specifies whether the application needs or prefers to
use a transport protocol that preserves message boundaries. The
recommended default is to Prefer Preservation of Message Boundaries.
5.2.3. Configure per-Message reliability
Name: per-msg-reliability
This property specifies whether an application considers it useful to This property specifies whether an application considers it useful to
indicate its reliability requirements on a per-Message basis. This indicate its reliability requirements on a per-Message basis. This
property applies to Connections and Connection Groups. The property applies to Connections and Connection Groups. The
recommended default is to not have this option. recommended default is to Ignore this option.
5.2.3. Preservation of data ordering 5.2.4. Preservation of data ordering
Name: preserve-order
This property specifies whether the application wishes to use a This property specifies whether the application wishes to use a
transport protocol that can ensure that data is received by the transport protocol that can ensure that data is received by the
application on the other end in the same order as it was sent. The application on the other end in the same order as it was sent. The
recommended default is to preserve data ordering. recommended default is to Require Preservation of data ordering.
5.2.4. Use 0-RTT session establishment with an idempotent Message 5.2.5. Use 0-RTT session establishment with an idempotent Message
Name: zero-rtt-msg
This property specifies whether an application would like to supply a This property specifies whether an application would like to supply a
Message to the transport protocol before Connection establishment, Message to the transport protocol before Connection establishment,
which will then be reliably transferred to the other side before or which will then be reliably transferred to the other side before or
during Connection establishment, potentially multiple times. See during Connection establishment, potentially multiple times. See
also Section 7.3.4. The recommended default is to not have this also Section 7.3.4. The recommended default is to Prefer this
option. option.
5.2.5. Multistream Connections in Group 5.2.6. Multistream Connections in Group
Name: multistreaming
This property specifies that the application would prefer multiple This property specifies that the application would prefer multiple
Connections within a Connection Group to be provided by streams of a Connections within a Connection Group to be provided by streams of a
single underlying transport connection where possible. The single underlying transport connection where possible. The
recommended default is to not have this option. recommended default is to Prefer have this option.
5.2.6. Control checksum coverage on sending or receiving 5.2.7. Control checksum coverage on sending
Name: per-msg-checksum-len-send
This property specifies whether the application considers it useful This property specifies whether the application considers it useful
to enable, disable, or configure a checksum when sending a Message, to enable, disable, or configure a checksum when sending a Message.
or configure whether to require a checksum or not when receiving. The recommended default is to Ignore this option.
The recommended default is full checksum coverage without the option 5.2.8. Control checksum coverage on receiving
to configure it, and requiring a checksum when receiving.
5.2.7. Congestion control Name: per-msg-checksum-len-recv
This property specifies whether the application considers it useful
configure whether to require a checksum or not when receiving. The
recommended default is to Ignore this option.
5.2.9. Congestion control
Name: congestion-control
This property specifies whether the application would like the This property specifies whether the application would like the
Connection to be congestion controlled or not. Note that if a Connection to be congestion controlled or not. Note that if a
Connection is not congestion controlled, an application using such a Connection is not congestion controlled, an application using such a
Connection should itself perform congestion control in accordance Connection should itself perform congestion control in accordance
with [RFC2914]. Also note that reliability is usually combined with with [RFC2914]. Also note that reliability is usually combined with
congestion control in protocol implementations, rendering "reliable congestion control in protocol implementations, rendering "reliable
but not congestion controlled" a request that is unlikely to succeed. but not congestion controlled" a request that is unlikely to succeed.
The recommended default is that the Connection is congestion
controlled.
5.2.8. Interface Instance or Type The recommended default is to Require that the Connection is
congestion controlled.
5.2.10. Interface Instance or Type
Name: interface
Type: Set (Preference, Enumeration)
This property allows the application to select which specific network This property allows the application to select which specific network
interfaces or categories of interfaces it wants to "Require", interfaces or categories of interfaces it wants to "Require",
"Prohibit", "Prefer", or "Avoid". "Prohibit", "Prefer", or "Avoid".
In contrast to other Selection Properties, this property is tuple of In contrast to other Selection Properties, this property is a tuple
an (Enumerated) interface identifier and a preference, and can either of an (Enumerated) interface identifier and a preference, and can
be implemented directly as such, or for making one preference either be implemented directly as such, or for making one preference
available for each interface and interface type available on the available for each interface and interface type available on the
system. system.
Note that marking a specific interface as "Required" strictly limits Note that marking a specific interface as "Required" strictly limits
path selection to a single interface, and leads to less flexible and path selection to a single interface, and leads to less flexible and
resilient connection establishment. resilient connection establishment.
The set of valid interface types is implementation- and system- The set of valid interface types is implementation- and system-
specific. For example, on a mobile device, there may be "Wi-Fi" and specific. For example, on a mobile device, there may be "Wi-Fi" and
"Cellular" interface types available; whereas on a desktop computer, "Cellular" interface types available; whereas on a desktop computer,
skipping to change at page 15, line 8 skipping to change at page 20, line 48
interface type as "Required" limits path selection to a small set of interface type as "Required" limits path selection to a small set of
interfaces, and leads to less flexible and resilient connection interfaces, and leads to less flexible and resilient connection
establishment. establishment.
The set of interface types is expected to change over time as new The set of interface types is expected to change over time as new
access technologies become available. access technologies become available.
Interface types should not be treated as a proxy for properties of Interface types should not be treated as a proxy for properties of
interfaces such as metered or unmetered network access. If an interfaces such as metered or unmetered network access. If an
application needs to prohibit metered interfaces, this should be application needs to prohibit metered interfaces, this should be
specified via Provisioning Domain attributes (see Section 5.2.9) or specified via Provisioning Domain attributes (see Section 5.2.11) or
another specific property. another specific property.
5.2.9. Provisioning Domain Instance or Type 5.2.11. Provisioning Domain Instance or Type
Similar to interface instances and types (see Section 5.2.8), this Name: pvd
Type: Set (Preference, Enumeration)
Similar to interface instances and types (see Section 5.2.10), this
property allows the application to control path selection by property allows the application to control path selection by
selecting which specific Provisioning Domains or categories of selecting which specific Provisioning Domains or categories of
Provisioning Domains it wants to "Require", "Prohibit", "Prefer", or Provisioning Domains it wants to "Require", "Prohibit", "Prefer", or
"Avoid". Provisioning Domains define consistent sets of network "Avoid". Provisioning Domains define consistent sets of network
properties that may be more specific than network interfaces properties that may be more specific than network interfaces
[RFC7556]. [RFC7556].
As with interface instances and types, this property is tuple of an As with interface instances and types, this property is a tuple of an
(Enumerated) PvD identifier and a preference, and can either be (Enumerated) PvD identifier and a preference, and can either be
implemented directly as such, or for making one preference available implemented directly as such, or for making one preference available
for each interface and interface type available on the system. for each interface and interface type available on the system.
The identification of a specific Provisioning Domain (PvD) is defined The identification of a specific Provisioning Domain (PvD) is defined
to be implementation- and system-specific, since there is not a to be implementation- and system-specific, since there is not a
portable standard format for a PvD identitfier. For example, this portable standard format for a PvD identitfier. For example, this
identifier may be a string name or an integer. As with requiring identifier may be a string name or an integer. As with requiring
specific interfaces, requiring a specific PvD strictly limits path specific interfaces, requiring a specific PvD strictly limits path
selection. selection.
skipping to change at page 15, line 43 skipping to change at page 21, line 41
Categories or types of PvDs are also defined to be implementation- Categories or types of PvDs are also defined to be implementation-
and system-specific. These may be useful to identify a service that and system-specific. These may be useful to identify a service that
is provided by a PvD. For example, if an application wants to use a is provided by a PvD. For example, if an application wants to use a
PvD that provides a Voice-Over-IP service on a Cellular network, it PvD that provides a Voice-Over-IP service on a Cellular network, it
can use the relevant PvD type to require some PvD that provides this can use the relevant PvD type to require some PvD that provides this
service, without needing to look up a particular instance. While service, without needing to look up a particular instance. While
this does restrict path selection, it is broader than requiring this does restrict path selection, it is broader than requiring
specific PvD instances or interface instances, and should be specific PvD instances or interface instances, and should be
preferred over these options. preferred over these options.
5.2.12. Parallel Use of Multiple Paths
Name: multipath
This property specifies whether an application considers it useful to
transfer data across multiple paths between the same end hosts.
Generally, in most cases, this will improve performance (e.g.,
achieve greater throughput). One possible side-effect is increased
jitter, which may be problematic for delay-sensitive applications.
The recommended default is to Prefer this option.
5.2.13. Direction of communication
Name: direction
Type: Enumeration
This property specifies whether an application wants to use the
connection for sending and/or receiving data. Possible values are:
Bidirectional (default): The connection must support sending and
receiving data
Unidirectional send: The connection must support sending data
Unidirectional receive: The connection must support receiving data
In case a unidirectional connection is requested, but unidirectional
connections are not supported by the transport protocol, the system
should fall back to bidirectional transport.
5.2.14. Notification of excessive retransmissions
Name: :retransmit-notify
This property specifies whether an application considers it useful to
be informed in case sent data was retransmitted more often than a
certain threshold. The recommended default is to Ignore this option.
5.2.15. Notification of ICMP soft error message arrival
Name: :soft-error-notify
This property specifies whether an application considers it useful to
be informed when an ICMP error message arrives that does not force
termination of a connection. When set to true, received ICMP errors
will be available as SoftErrors. Note that even if a protocol
supporting this property is selected, not all ICMP errors will
necessarily be delivered, so applications cannot rely on receiving
them. The recommended default is to Ignore this option.
5.3. Specifying Security Parameters and Callbacks 5.3. Specifying Security Parameters and Callbacks
Most security parameters, e.g., TLS ciphersuites, local identity and Most security parameters, e.g., TLS ciphersuites, local identity and
private key, etc., may be configured statically. Others are private key, etc., may be configured statically. Others are
dynamically configured during connection establishment. Thus, we dynamically configured during connection establishment. Thus, we
partition security parameters and callbacks based on their place in partition security parameters and callbacks based on their place in
the lifetime of connection establishment. Similar to Transport the lifetime of connection establishment. Similar to Transport
Properties, both parameters and callbacks are inherited during Properties, both parameters and callbacks are inherited during
cloning (see Section 6.4). cloning (see Section 6.4).
skipping to change at page 17, line 49 skipping to change at page 24, line 51
the Rendezvous() Action. These Actions are described in the the Rendezvous() Action. These Actions are described in the
subsections below. subsections below.
6.1. Active Open: Initiate 6.1. Active Open: Initiate
Active open is the Action of establishing a Connection to a Remote Active open is the Action of establishing a Connection to a Remote
Endpoint presumed to be listening for incoming Connection requests. Endpoint presumed to be listening for incoming Connection requests.
Active open is used by clients in client-server interactions. Active Active open is used by clients in client-server interactions. Active
open is supported by this interface through the Initiate Action: open is supported by this interface through the Initiate Action:
Connection := Preconnection.Initiate() Connection := Preconnection.Initiate(timeout?)
The timeout parameter specifies how long to wait before aborting
Before calling Initiate, the caller must have populated a Active open. Before calling Initiate, the caller must have populated
Preconnection Object with a Remote Endpoint specifier, optionally a a Preconnection Object with a Remote Endpoint specifier, optionally a
Local Endpoint specifier (if not specified, the system will attempt Local Endpoint specifier (if not specified, the system will attempt
to determine a suitable Local Endpoint), as well as all properties to determine a suitable Local Endpoint), as well as all properties
necessary for candidate selection. necessary for candidate selection.
The Initiate() Action consumes the Preconnection. Once Initiate() The Initiate() Action consumes the Preconnection. Once Initiate()
has been called, no further properties may be added to the has been called, no further properties may be added to the
Preconnection, and no subsequent establishment call may be made on Preconnection, and no subsequent establishment call may be made on
the Preconnection. the Preconnection.
Once Initiate is called, the candidate Protocol Stack(s) may cause Once Initiate is called, the candidate Protocol Stack(s) may cause
skipping to change at page 18, line 41 skipping to change at page 25, line 44
Connection -> InitiateError<> Connection -> InitiateError<>
An InitiateError occurs either when the set of transport properties An InitiateError occurs either when the set of transport properties
and security parameters cannot be fulfilled on a Connection for and security parameters cannot be fulfilled on a Connection for
initiation (e.g. the set of available Paths and/or Protocol Stacks initiation (e.g. the set of available Paths and/or Protocol Stacks
meeting the constraints is empty) or reconciled with the local and/or meeting the constraints is empty) or reconciled with the local and/or
remote endpoints; when the remote specifier cannot be resolved; or remote endpoints; when the remote specifier cannot be resolved; or
when no transport-layer connection can be established to the remote when no transport-layer connection can be established to the remote
endpoint (e.g. because the remote endpoint is not accepting endpoint (e.g. because the remote endpoint is not accepting
connections, or the application is prohibited from opening a connections, the application is prohibited from opening a Connection
Connection by the operating system). by the operating system, or the establishment attempt has timed out
for any other reason).
See also Section 7.6 to combine Connection establishment and See also Section 7.6 to combine Connection establishment and
transmission of the first message in a single action. transmission of the first message in a single action.
6.2. Passive Open: Listen 6.2. Passive Open: Listen
Passive open is the Action of waiting for Connections from remote Passive open is the Action of waiting for Connections from remote
endpoints, commonly used by servers in client-server interactions. endpoints, commonly used by servers in client-server interactions.
Passive open is supported by this interface through the Listen Passive open is supported by this interface through the Listen
Action: Action:
Preconnection.Listen() Preconnection.Listen()
Before calling Listen, the caller must have initialized the Before calling Listen, the caller must have initialized the
Preconnection during the pre-establishment phase with a Local Preconnection during the pre-establishment phase with a Local
Endpoint specifier, as well as all properties necessary for Protocol Endpoint specifier, as well as all properties necessary for Protocol
Stack selection. A Remote Endpoint may optionally be specified, to Stack selection. A Remote Endpoint may optionally be specified, to
constrain what Connections are accepted. The Listen() Action constrain what Connections are accepted. The Listen() Action
skipping to change at page 21, line 27 skipping to change at page 28, line 33
parent Connection on which Clone was called, and the resulting cloned parent Connection on which Clone was called, and the resulting cloned
Connection. These connections are "entangled" with each other, and Connection. These connections are "entangled" with each other, and
become part of a Connection Group. Calling Clone on any of these two become part of a Connection Group. Calling Clone on any of these two
Connections adds a third Connection to the Connection Group, and so Connections adds a third Connection to the Connection Group, and so
on. Connections in a Connection Group share all Protocol Properties on. Connections in a Connection Group share all Protocol Properties
that are not applicable to a Message. that are not applicable to a Message.
Changing one of these Protocol Properties on one Connection in the Changing one of these Protocol Properties on one Connection in the
group changes it for all others. Per-Message Protocol Properties, group changes it for all others. Per-Message Protocol Properties,
however, are not entangled. For example, changing "Timeout for however, are not entangled. For example, changing "Timeout for
aborting Connection" (see Section 9.1.6) on one Connection in a group aborting Connection" (see Section 9.1.4) on one Connection in a group
will automatically change this Protocol Property for all Connections will automatically change this Protocol Property for all Connections
in the group in the same way. However, changing "Lifetime" (see in the group in the same way. However, changing "Lifetime" (see
Section 7.3.1) of a Message will only affect a single Message on a Section 7.3.1) of a Message will only affect a single Message on a
single Connection, entangled or not. single Connection, entangled or not.
If the underlying protocol supports multi-streaming, it is natural to If the underlying protocol supports multi-streaming, it is natural to
use this functionality to implement Clone. In that case, entangled use this functionality to implement Clone. In that case, entangled
Connections are multiplexed together, giving them similar treatment Connections are multiplexed together, giving them similar treatment
not only inside endpoints but also across the end-to-end Internet not only inside endpoints but also across the end-to-end Internet
path. path.
If the underlying Protocol Stack does not support cloning, or cannot If the underlying Protocol Stack does not support cloning, or cannot
create a new stream on the given Connection, then attempts to clone a create a new stream on the given Connection, then attempts to clone a
connection will result in a CloneError: connection will result in a CloneError:
Connection -> CloneError<> Connection -> CloneError<>
The Protocol Property "Niceness" operates on entangled Connections as The Protocol Property "Priority" operates on entangled Connections as
in Section 7.3.2: when allocating available network capacity among in Section 7.3.2: when allocating available network capacity among
Connections in a Connection Group, sends on Connections with higher Connections in a Connection Group, sends on Connections with higher
Niceness values will be prioritized over sends on Connections with Priority values will be prioritized over sends on Connections with
lower Niceness values. An ideal transport system implementation lower Priority values. An ideal transport system implementation
would assign each Connection the capacity share (M-N) x C / M, where would assign each Connection the capacity share (M-N) x C / M, where
N is the Connection's Niceness value, M is the maximum Niceness value N is the Connection's Priority value, M is the maximum Priority value
used by all Connections in the group and C is the total available used by all Connections in the group and C is the total available
capacity. However, the Niceness setting is purely advisory, and no capacity. However, the Priority setting is purely advisory, and no
guarantees are given about the way capacity is shared. Each guarantees are given about the way capacity is shared. Each
implementation is free to implement a way to share capacity that it implementation is free to implement a way to share capacity that it
sees fit. sees fit.
7. Sending Data 7. Sending Data
Once a Connection has been established, it can be used for sending Once a Connection has been established, it can be used for sending
data. Data is sent in terms of Messages, which allow the application data. Data is sent in terms of Messages, which allow the application
to communicate the boundaries of the data being transferred. By to communicate the boundaries of the data being transferred. By
default, Send enqueues a complete Message, and takes optional per- default, Send enqueues a complete Message, and takes optional per-
Message properties (see Section 7.1). All Send actions are Message properties (see Section 7.1). All Send actions are
asynchronous, and deliver events (see Section 7.2). Sending partial asynchronous, and deliver events (see Section 7.2). Sending partial
Messages for streaming large data is also supported (see Messages for streaming large data is also supported (see
Section 7.4). Section 7.4).
Messages are sent on a Connection using the Send action:
Connection.Send(messageData, messageContext?, endOfMessage?)
where messageData is the data object to send. The optional
messageContext parameter supports per-message properties and is
described in Section 7.3. The optional endOfMessage parameter
supports partial sending and is described in Section 7.4.
7.1. Basic Sending 7.1. Basic Sending
The most basic form of sending on a connection involves enqueuing a The most basic form of sending on a connection involves enqueuing a
single Data block as a complete Message, with default Message single Data block as a complete Message, with default Message
Properties. Message data is created as an array of octets, and the Properties. Message data is created as an array of octets, and the
resulting object contains both the byte array and the length of the resulting object contains both the byte array and the length of the
array. array.
messageData := "hello".octets() messageData := "hello".octets()
Connection.Send(messageData) Connection.Send(messageData)
skipping to change at page 24, line 46 skipping to change at page 32, line 13
Protocol Stacks underlying the Connection on which a given Message is Protocol Stacks underlying the Connection on which a given Message is
sent. For example, a Connection must provide reliability to allow sent. For example, a Connection must provide reliability to allow
setting an infinitie value for the lifetime property of a Message. setting an infinitie value for the lifetime property of a Message.
Sending a Message with Message Properties inconsistent with the Sending a Message with Message Properties inconsistent with the
Selection Properties of the Connection yields an error. Selection Properties of the Connection yields an error.
The following Message Properties are supported: The following Message Properties are supported:
7.3.1. Lifetime 7.3.1. Lifetime
Name: msg-lifetime
Type: Integer Type: Integer
Lifetime specifies how long a particular Message can wait to be sent Lifetime specifies how long a particular Message can wait to be sent
to the remote endpoint before it is irrelevant and no longer needs to to the remote endpoint before it is irrelevant and no longer needs to
be (re-)transmitted. When a Message's Lifetime is infinite, it must be (re-)transmitted. This is a hint to the transport system - it is
be transmitted reliably. The type and units of Lifetime are not guaranteed that a Message will not be sent when its Lifetime has
implementation-specific. expired.
7.3.2. Niceness Setting a Message's Lifetime to infinite indicates that the
application does not wish to apply a time constraint on the
transmission of the Message, but it does not express a need for
reliable delivery; reliability is adjustable per Message via the
"Reliable Data Transfer (Message)" property (see Section 7.3.7). The
type and units of Lifetime are implementation-specific.
7.3.2. Priority
Name: msg-prio
Type: Integer (non-negative) Type: Integer (non-negative)
This property represents an unbounded hierarchy of priorities. It This property represents a hierarchy of priorities. It can specify
can specify the priority of a Message, relative to other Messages the priority of a Message, relative to other Messages sent over the
sent over the same Connection. same Connection.
A Message with Niceness 0 will yield to a Message with Niceness 1, A Message with Priority 0 will yield to a Message with Priority 1,
which will yield to a Message with Niceness 2, and so on. Niceness which will yield to a Message with Priority 2, and so on. Priorities
may be used as a sender-side scheduling construct only, or be used to may be used as a sender-side scheduling construct only, or be used to
specify priorities on the wire for Protocol Stacks supporting specify priorities on the wire for Protocol Stacks supporting
prioritization. prioritization.
Note that this property is not a per-message override of the Note that this property is not a per-message override of the
connection Niceness - see Section 9.1.5. Both Niceness properties connection Priority - see Section 9.1.3. Both Priority properties
may interact, but can be used independently and be realized by may interact, but can be used independently and be realized by
different mechanisms. different mechanisms.
7.3.3. Ordered 7.3.3. Ordered
Name: msg-ordered
Type: Boolean Type: Boolean
If true, it specifies that the receiver-side transport protocol stack If true, it specifies that the receiver-side transport protocol stack
only deliver the Message to the receiving application after the only deliver the Message to the receiving application after the
previous ordered Message which was passed to the same Connection via previous ordered Message which was passed to the same Connection via
the Send Action, when such a Message exists. If false, the Message the Send Action, when such a Message exists. If false, the Message
may be delivered to the receiving application out of order. This may be delivered to the receiving application out of order. This
property is used for protocols that support preservation of data property is used for protocols that support preservation of data
ordering, see Section 5.2.3, but allow out-of-order delivery for ordering, see Section 5.2.4, but allow out-of-order delivery for
certain messages. certain messages.
7.3.4. Idempotent 7.3.4. Idempotent
Name: idempotent
Type: Boolean Type: Boolean
If true, it specifies that a Message is safe to send to the remote If true, it specifies that a Message is safe to send to the remote
endpoint more than once for a single Send Action. It is used to mark endpoint more than once for a single Send Action. It is used to mark
data safe for certain 0-RTT establishment techniques, where data safe for certain 0-RTT establishment techniques, where
retransmission of the 0-RTT data may cause the remote application to retransmission of the 0-RTT data may cause the remote application to
receive the Message multiple times. receive the Message multiple times.
7.3.5. Final 7.3.5. Final
Type: Boolean Type: Boolean
Name: final
If true, this Message is the last one that the application will send If true, this Message is the last one that the application will send
on a Connection. This allows underlying protocols to indicate to the on a Connection. This allows underlying protocols to indicate to the
Remote Endpoint that the Connection has been effectively closed in Remote Endpoint that the Connection has been effectively closed in
the sending direction. For example, TCP-based Connections can send a the sending direction. For example, TCP-based Connections can send a
FIN once a Message marked as Final has been completely sent, FIN once a Message marked as Final has been completely sent,
indicated by marking endOfMessage. Protocols that do not support indicated by marking endOfMessage. Protocols that do not support
signalling the end of a Connection in a given direction will ignore signalling the end of a Connection in a given direction will ignore
this property. this property.
Note that a Final Message must always be sorted to the end of a list Note that a Final Message must always be sorted to the end of a list
of Messages. The Final property overrides Niceness and any other of Messages. The Final property overrides Priority and any other
property that would re-order Messages. If another Message is sent property that would re-order Messages. If another Message is sent
after a Message marked as Final has already been sent on a after a Message marked as Final has already been sent on a
Connection, the Send Action for the new Message will cause a Connection, the Send Action for the new Message will cause a
SendError Event. SendError Event.
7.3.6. Corruption Protection Length 7.3.6. Corruption Protection Length
Name: msg-checksum-len
Type: Integer (non-negative with -1 as special value) Type: Integer (non-negative with -1 as special value)
This property specifies the length of the section of the Message, This property specifies the length of the section of the Message,
starting from byte 0, that the application requires to be delivered starting from byte 0, that the application requires to be delivered
without corruption due to lower layer errors. It is used to specify without corruption due to lower layer errors. It is used to specify
options for simple integrity protection via checksums. By default, options for simple integrity protection via checksums. By default,
the entire Message is protected by a checksum. A value of 0 means the entire Message is protected by a checksum. A value of 0 means
that no checksum is required, and a special value (e.g. -1) can be that no checksum is required, and a special value (e.g. -1) can be
used to indicate the default. Only full coverage is guaranteed, any used to indicate the default. Only full coverage is guaranteed, any
other requests are advisory. other requests are advisory.
7.3.7. Reliable Data Transfer (Message) 7.3.7. Reliable Data Transfer (Message)
Name: msg-reliable
Type: Boolean Type: Boolean
This property specifies that a message should be sent in such a way When true, this property specifies that a message should be sent in
that the transport protocol ensures all data is received on the other such a way that the transport protocol ensures all data is received
side without corruption. Changing the 'Reliable Data Transfer' on the other side without corruption. Changing the 'Reliable Data
property on Messages is only possible if the Connection supports Transfer' property on Messages is only possible for Connections that
reliability. When this is not the case, changing it will generate an were established with the Selection Property 'Reliable Data Transfer
error. (Connection)' enabled. When this is not the case, changing it will
generate an error. Disabling this property indicates that the
transport system may disable retransmissions or other reliability
mechanisms for this particular Message, but such disabling is not
guaranteed.
7.3.8. Transmission Profile 7.3.8. Message Capacity Profile Override
Name: msg-capacity-profile
Type: Enumeration Type: Enumeration
This enumerated property specifies the application's preferred This enumerated property specifies the application's preferred
tradeoffs for sending this Message; it is a per-Message override of tradeoffs for sending this Message; it is a per-Message override of
the Capacity Profile protocol and path selection property (see the Capacity Profile protocol and path selection property (see
Section 9.1.12). Section 9.1.10).
The following values are valid for Transmission Profile: The following values are valid for Transmission Profile:
Default: No special optimizations of the tradeoff between delay, Default: No special optimizations of the tradeoff between delay,
delay variation, and bandwidth efficiency should be made when delay variation, and bandwidth efficiency should be made when
sending this message. sending this message.
Low Latency: Response time (latency) should be optimized at the Low Latency: Response time (latency) should be optimized at the
expense of efficiently using the available capacity when sending expense of efficiently using the available capacity when sending
this message. This can be used by the system to disable the this message. This can be used by the system to disable the
coalescing of multiple small Messages into larger packets (Nagle's coalescing of multiple small Messages into larger packets (Nagle's
algorithm); to prefer immediate acknowledgment from the peer algorithm); to prefer immediate acknowledgment from the peer
endpoint when supported by the underlying transport; to signal a endpoint when supported by the underlying transport; to signal a
preference for lower-latency, higher-loss treatment; and so on. preference for lower-latency, higher-loss treatment; and so on.
[TODO: This is inconsistent with {prop-cap-profile}} - needs to be [TODO: This is inconsistent with {prop-cap-profile}} - needs to be
fixed] fixed]
7.3.9. Singular Transmission 7.3.9. Singular Transmission
Name: singular-transmission
Type: Boolean Type: Boolean
This property specifies that a message should be sent and received as This property specifies that a message should be sent and received as
a single packet without transport-layer segmentation or network-layer a single packet without transport-layer segmentation or network-layer
fragmentation. Attempts to send a message with this property set fragmentation. Attempts to send a message with this property set
with a size greater to the transport's current estimate of its with a size greater to the transport's current estimate of its
maximum transmission segment size will result in a "SendError". When maximum transmission segment size will result in a "SendError". When
used with transports supporting this functionality and running over used with transports supporting this functionality and running over
IP version 4, the Don't Fragment bit will be set. IP version 4, the Don't Fragment bit will be set.
skipping to change at page 28, line 36 skipping to change at page 36, line 36
together. This provides a hint to the system that the sending of together. This provides a hint to the system that the sending of
these Messages should be coalesced when possible, and that sending these Messages should be coalesced when possible, and that sending
any of the batched Messages may be delayed until the last Message in any of the batched Messages may be delayed until the last Message in
the batch is enqueued. the batch is enqueued.
Connection.Batch( Connection.Batch(
Connection.Send(messageData) Connection.Send(messageData)
Connection.Send(messageData) Connection.Send(messageData)
) )
7.6. Send on Active Open: InitiateWithIdempotentSend 7.6. Send on Active Open: InitiateWithSend
For application-layer protocols where the Connection initiator also For application-layer protocols where the Connection initiator also
sends the first message, the InitiateWithIdempotentSend() action sends the first message, the InitiateWithSend() action combines
combines Connection initiation with a first Message sent, provided Connection initiation with a first Message sent:
that message is idempotent.
Without a message context (as in Section 7.1):
Connection := Preconnection.InitiateWithIdempotentSend(messageData)
With a message context (as in Section 7.3):
Connection := Preconnection.InitiateWithIdempotentSend(messageData, messageContext) Connection := Preconnection.InitiateWithSend(messageData, messageContext?, timeout?)
The message passed to InitiateWithIdempotentSend() is, as suggested Whenever possible, a messageContext should be provided to declare the
by the name, considered to be idempotent (see Section 7.3.4) message passed to InitiateWithSend as idempotent. This allows the
regardless of declared message properties or defaults. If protocol transport system to make use of 0-RTT establishment in case this is
stacks supporting 0-RTT establishment with idempotent data are supported by the available protocol stacks. When the selected
available on the Preconnection, then 0-RTT establishment may be used stack(s) do not support transmitting data upon connection
with the given message when establishing candidate connections. For establishment, InitiateWithSend is identical to Initiate() followed
a non-idemponent initial message, or when the selected stack(s) do by Send().
not support 0-RTT establishment, InitiateWithIdempotentSend is
identical to Initiate() followed by Send().
Neither partial sends nor send batching are supported by Neither partial sends nor send batching are supported by
InitiateWithIdempotentSend(). InitiateWithSend().
The Events that may be sent after InitiateWithIdempotentSend() are The Events that may be sent after InitiateWithSend() are equivalent
equivalent to those that would be sent by an invocation of Initate() to those that would be sent by an invocation of Initate() followed
followed immediately by an invocation of Send(), with the caveat that immediately by an invocation of Send(), with the caveat that a send
a send failure that occurs because the Connection could not be failure that occurs because the Connection could not be established
established will not result in a SendError separate from the will not result in a SendError separate from the InitiateError
InitiateError signaling the failure of Connection establishment. signaling the failure of Connection establishment.
7.7. Sender-side Framing 7.7. Sender-side Framing
Sender-side framing allows a caller to provide the interface with a Sender-side framing allows a caller to provide the interface with a
function that takes a Message of an appropriate application-layer function that takes a Message of an appropriate application-layer
type and returns an array of octets, the on-the-wire representation type and returns an array of octets, the on-the-wire representation
of the Message to be handed down to the Protocol Stack. It consists of the Message to be handed down to the Protocol Stack. It consists
of a Framer Object with a single Action, Frame. Since the Framer of a Framer Object with a single Action, Frame. Since the Framer
depends on the protocol used at the application layer, it is bound to depends on the protocol used at the application layer, it is bound to
the Preconnection during the pre-establishment phase: the Preconnection during the pre-establishment phase:
skipping to change at page 30, line 11 skipping to change at page 37, line 51
As with sending, the type of the Message to be passed is dependent on As with sending, the type of the Message to be passed is dependent on
the implementation, and on the constraints on the Protocol Stacks the implementation, and on the constraints on the Protocol Stacks
implied by the Connection's transport parameters. implied by the Connection's transport parameters.
8.1. Enqueuing Receives 8.1. Enqueuing Receives
Receive takes two parameters to specify the length of data that an Receive takes two parameters to specify the length of data that an
application is willing to receive, both of which are optional and application is willing to receive, both of which are optional and
have default values if not specified. have default values if not specified.
Connection.Receive(minIncompleteLength, maxLength) Connection.Receive(minIncompleteLength?, maxLength?)
By default, Receive will try to deliver complete Messages in a single By default, Receive will try to deliver complete Messages in a single
event (Section 8.2.1). event (Section 8.2.1).
The application can set a minIncompleteLength value to indicates the The application can set a minIncompleteLength value to indicates the
smallest partial Message data size in bytes that should be delivered smallest partial Message data size in bytes that should be delivered
in response to this Receive. By default, this value is infinite, in response to this Receive. By default, this value is infinite,
which means that only complete Messages should be delivered (see which means that only complete Messages should be delivered (see
Section 8.2.2 and Section 8.4 for more information on how this is Section 8.2.2 and Section 8.4 for more information on how this is
accomplished). If this value is set to some smaller value, the accomplished). If this value is set to some smaller value, the
associated receive event will be triggered only when at least that associated receive event will be triggered only when at least that
skipping to change at page 31, line 4 skipping to change at page 38, line 42
8.2. Receive Events 8.2. Receive Events
Each call to Receive will be paired with a single Receive Event, 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 which can be a success or an error. This allows an application to
provide backpressure to the transport stack when it is temporarily provide backpressure to the transport stack when it is temporarily
not ready to receive messages. not ready to receive messages.
8.2.1. Received 8.2.1. Received
Connection -> Received<messageData, messageContext> Connection -> Received<messageData, messageContext>
A Received event indicates the delivery of a complete Message. It A Received event indicates the delivery of a complete Message. It
contains two objects, the received bytes as messageData, and the contains two objects, the received bytes as messageData, and the
metadata and properties of the received Message as messageContext. metadata and properties of the received Message as messageContext.
See {#receive-context} for details about the received context. See Section 8.3 for details about the received context.
The messageData object provides access to the bytes that were The messageData object provides access to the bytes that were
received for this Message, along with the length of the byte array. received for this Message, along with the length of the byte array.
See Section 8.4 for handling Message framing in situations where the See Section 8.4 for handling Message framing in situations where the
Protocol Stack provides octet-stream transport only. Protocol Stack provides octet-stream transport only.
8.2.2. ReceivedPartial 8.2.2. ReceivedPartial
Connection -> ReceivedPartial<messageData, messageContext, endOfMessage> Connection -> ReceivedPartial<messageData, messageContext, endOfMessage>
skipping to change at page 32, line 41 skipping to change at page 40, line 31
which need access to information about the transport internals for which need access to information about the transport internals for
their own operation. their own operation.
8.3.2. Early Data 8.3.2. Early Data
In some cases it may be valuable to know whether data was read as In some cases it may be valuable to know whether data was read as
part of early data transfer (before connection establishment has part of early data transfer (before connection establishment has
finished). This is useful if applications need to treat early data finished). This is useful if applications need to treat early data
separately, e.g., if early data has different security properties separately, e.g., if early data has different security properties
than data sent after connection establishment. In the case of TLS than data sent after connection establishment. In the case of TLS
1.3, client early data can be replayed maliciously (see 1.3, client early data can be replayed maliciously (see [RFC8446]).
[I-D.ietf-tls-tls13]). Thus, receivers may wish to perform Thus, receivers may wish to perform additional checks for early data
additional checks for early data to ensure it is idempotent or not to ensure it is idempotent or not replayed. If TLS 1.3 is available
replayed. If TLS 1.3 is available and the recipient Message was sent and the recipient Message was sent as part of early data, the
as part of early data, the corresponding metadata carries a flag corresponding metadata carries a flag indicating as such. If early
indicating as such. If early data is enabled, applications should data is enabled, applications should check this metadata field for
check this metadata field for Messages received during connection Messages received during connection establishment and respond
establishment and respond accordingly. accordingly.
8.3.3. Receiving Final Messages 8.3.3. Receiving Final Messages
The Received Message Context can indicate whether or not this Message The Received Message Context can indicate whether or not this Message
is the Final Message on a Connection. For any Message that is marked 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 as Final, the application can assume that there will be no more
Messages received on the Connection once the Message has been Messages received on the Connection once the Message has been
completely delivered. This corresponds to the Final property that completely delivered. This corresponds to the Final property that
may be marked on a sent Message Section 7.3.5. may be marked on a sent Message Section 7.3.5.
skipping to change at page 34, line 7 skipping to change at page 41, line 39
interface with a function that takes an octet stream, as provided by interface with a function that takes an octet stream, as provided by
the underlying Protocol Stack, reads and returns a single Message of the underlying Protocol Stack, reads and returns a single Message of
an appropriate type for the application and platform, and leaves the an appropriate type for the application and platform, and leaves the
octet stream at the start of the next Message to deframe. It octet stream at the start of the next Message to deframe. It
consists of a Deframer Object with a single Action, Deframe. Since consists of a Deframer Object with a single Action, Deframe. Since
the Deframer depends on the protocol used at the application layer, the Deframer depends on the protocol used at the application layer,
it is bound to the Preconnection during the pre-establishment phase: it is bound to the Preconnection during the pre-establishment phase:
Preconnection.DeframeWith(Deframer) Preconnection.DeframeWith(Deframer)
{messageData} := Deframer.Deframe(OctetStream, ...) {messageData} := Deframer.Deframe(OctetStream)
9. Managing Connections 9. Managing Connections
After establishment, connections can be configured and queried using During pre-establishment and after establishment, connections can be
Connection Properties, and asynchronous information may be available configured and queried using Connection Properties, and asynchronous
about the state of the connection via Soft Errors. information may be available about the state of the connection via
Soft Errors.
Connection Properties represent the configuration and state of the Connection Properties represent the configuration and state of the
selected Protocol Stack(s) backing a Connection. These Connection selected Protocol Stack(s) backing a Connection. These Connection
Properties may be Generic, applying regardless of transport protocol, Properties may be Generic, applying regardless of transport protocol,
or Specific, applicable to a single implementation of a single or Specific, applicable to a single implementation of a single
transport protocol stack. Generic Connection Properties are defined transport protocol stack. Generic Connection Properties are defined
in Section 9.1 below. Specific Protocol Properties are defined in a in Section 9.1 below. Specific Protocol Properties are defined in a
transport- and implementation-specific way, and must not be assumed transport- and implementation-specific way, and must not be assumed
to apply across different protocols. Attempts to set Specific to apply across different protocols. Attempts to set Specific
Protocol Properties on a protocol stack not containing that specific Protocol Properties on a protocol stack not containing that specific
protocol are simply ignored, and do not raise an error; however, too protocol are simply ignored, and do not raise an error; however, too
much reliance by an application on Specific Protocol Properties may much reliance by an application on Specific Protocol Properties may
significantly reduce the flexibility of a transport services significantly reduce the flexibility of a transport services
implementation. implementation.
The application can set and query Connection Properties on a per- The application can set and query Connection Properties on a per-
Connection basis. Connection Properties that are not read-only can Connection basis. Connection Properties that are not read-only can
be set during pre-establishment (see Section 5.2), as well as on be set during pre-establishment (see Section 5.2), as well as on
connections directly using the SetProperty action: ~~~ connections directly using the SetProperty action:
Connection.SetProperty(property, value) ~~~
At any point, the application can query Connection Properties. ~~~ Connection.SetProperty(property, value)
ConnectionProperties := Connection.GetProperties() ~~~
At any point, the application can query Connection Properties.
ConnectionProperties := Connection.GetProperties()
Depending on the status of the connection, the queried Connection Depending on the status of the connection, the queried Connection
Properties will include different information: Properties will include different information:
o The connection state, which can be one of the following: o The connection state, which can be one of the following:
Establishing, Established, Closing, or Closed. Establishing, Established, Closing, or Closed.
o Whether the connection can be used to send data. A connection can o Whether the connection can be used to send data. A connection can
not be used for sending if the connection was created with the not be used for sending if the connection was created with the
Selection Property "Direction of Communication" set to Selection Property "Direction of Communication" set to
skipping to change at page 35, line 39 skipping to change at page 43, line 26
9.1. Generic Connection Properties 9.1. Generic Connection Properties
The Connection Properties defined as independent, and available on The Connection Properties defined as independent, and available on
all Connections are defined in the subsections below. all Connections are defined in the subsections below.
Note that many protocol properties have a corresponding selection Note that many protocol properties have a corresponding selection
property, which prefers protocols providing a specific transport property, which prefers protocols providing a specific transport
feature that controlled by that protocol property. [EDITOR'S NOTE: feature that controlled by that protocol property. [EDITOR'S NOTE:
todo: add these cross-references up to Section 5.2] todo: add these cross-references up to Section 5.2]
9.1.1. Notification of excessive retransmissions 9.1.1. Retransmission threshold before excessive retransmission
Type: Boolean
This property specifies whether an application considers it useful to
be informed in case sent data was retransmitted more often than a
certain threshold. When set to true, the effect is twofold: The
application may receive events in case excessive retransmissions. In
addition, the transport system considers this as a preference to use
transports stacks that can provide this notification. This is not a
strict requirement. If set to false, no notification of excessive
retransmissions will be sent and this transport feature is ignored
for protocol selection.
The recommended default is to have this option.
9.1.2. Retransmission threshold before excessive retransmission
notification notification
Name: retransmit-notify-threshold
Type: Integer Type: Integer
This property specifies after how many retransmissions to inform the This property specifies after how many retransmissions to inform the
application about "Excessive Retransmissions". application about "Excessive Retransmissions".
9.1.3. Notification of ICMP soft error message arrival 9.1.2. Required minimum coverage of the Corruption Protection for
receiving
Type: Boolean
This property specifies whether an application considers it useful to
be informed when an ICMP error message arrives that does not force
termination of a connection. When set to true, received ICMP errors
will be available as SoftErrors. Note that even if a protocol
supporting this property is selected, not all ICMP errors will
necessarily be delivered, so applications cannot rely on receiving
them. Setting this option also implies a preference to prefer
transports stacks that can provide this notification. If not set, no
events will be sent for ICMP soft error message and this transport
feature is ignored for protocol selection.
This property applies to Connections and Connection Groups. The
recommended default is not to have this option.
9.1.4. Required minimum coverage of the checksum for receiving Name: recv-checksum-len
Type: Integer Type: Integer
This property specifies the part of the received data that needs to This property specifies the part of the received data that needs to
be covered by a checksum. It is given in Bytes. A value of 0 means be covered by a checksum. It is given in Bytes. A value of 0 means
that no checksum is required, and a special value (e.g., -1) that no checksum is required, and a special value (e.g., -1)
indicates full checksum coverage. indicates full checksum coverage.
9.1.5. Niceness (Connection) 9.1.3. Priority (Connection)
Name: conn-prio
Type: Integer Type: Integer
This Property is a non-negative integer representing the relative This Property is a non-negative integer representing the relative
inverse priority of this Connection relative to other Connections in inverse priority of this Connection relative to other Connections in
the same Connection Group. It has no effect on Connections not part the same Connection Group. It has no effect on Connections not part
of a Connection Group. As noted in Section 6.4, this property is not of a Connection Group. As noted in Section 6.4, this property is not
entangled when Connections are cloned. entangled when Connections are cloned.
9.1.6. Timeout for aborting Connection 9.1.4. Timeout for aborting Connection
Type: Integer Name: conn-timeout
This property specifies how long to wait before aborting a Connection Type: Numeric
during establishment, or before deciding that a Connection has failed
after establishment. It is given in seconds.
9.1.7. Connection group transmission scheduler This property specifies how long to wait before deciding that a
Connection has failed when trying to reliably deliver data to the
destination. Adjusting this Property will only take effect when the
underlying stack supports reliability.
Type: Enum 9.1.5. Connection group transmission scheduler
Name: conn-scheduler
Type: Enumeration
This property specifies which scheduler should be used among This property specifies which scheduler should be used among
Connections within a Connection Group, see Section 6.4. The set of Connections within a Connection Group, see Section 6.4. The set of
schedulers can be taken from [I-D.ietf-tsvwg-sctp-ndata]. schedulers can be taken from [I-D.ietf-tsvwg-sctp-ndata].
9.1.8. Maximum message size concurrent with Connection establishment 9.1.6. Maximum message size concurrent with Connection establishment
Name: zero-rtt-msg-max-len
Type: Integer (read only) Type: Integer (read only)
This property represents the maximum Message size that can be sent This property represents the maximum Message size that can be sent
before or during Connection establishment, see also Section 7.3.4. before or during Connection establishment, see also Section 7.3.4.
It is given in Bytes. It is given in Bytes.
9.1.9. Maximum Message size before fragmentation or segmentation 9.1.7. Maximum Message size before fragmentation or segmentation
Type: Integer (read only) Name: singular-transmission-msg-max-len
Type: Integer (read only)
This property, if applicable, represents the maximum Message size This property, if applicable, represents the maximum Message size
that can be sent without incurring network-layer fragmentation or that can be sent without incurring network-layer fragmentation or
transport layer segmentation at the sender. transport layer segmentation at the sender.
9.1.10. Maximum Message size on send 9.1.8. Maximum Message size on send
Name: send-msg-max-len
Type: Integer (read only) Type: Integer (read only)
This property represents the maximum Message size that can be sent. This property represents the maximum Message size that can be sent.
9.1.11. Maximum Message size on receive 9.1.9. Maximum Message size on receive
Name: recv-msg-max-len
Type: Integer (read only) Type: Integer (read only)
This numeric property represents the maximum Message size that can be This numeric property represents the maximum Message size that can be
received. received.
9.1.12. Capacity Profile 9.1.10. Capacity Profile
Name: conn-capacity-profile
This property specifies the desired network treatment for traffic This property specifies the desired network treatment for traffic
sent by the application and the tradeoffs the application is prepared sent by the application and the tradeoffs the application is prepared
to make in path and protocol selection to receive that desired to make in path and protocol selection to receive that desired
treatment. When the capacity profile is set to a value other than treatment. When the capacity profile is set to a value other than
Default, the transport system should select paths and profiles to Default, the transport system should select paths and profiles to
optimize for the capacity profile specified. The following values optimize for the capacity profile specified. The following values
are valid for the Capacity Profile: are valid for the Capacity Profile:
Default: The application makes no representation about its expected Default: The application makes no representation about its expected
skipping to change at page 39, line 34 skipping to change at page 47, line 9
that map the requested capacity profile onto per-connection DSCP that map the requested capacity profile onto per-connection DSCP
signaling without multiplexing SHOULD assign a DSCP Assured signaling without multiplexing SHOULD assign a DSCP Assured
Forwarding (AF11,AF12,AF13,AF14) [RFC2597] PHB per section 4.8 of Forwarding (AF11,AF12,AF13,AF14) [RFC2597] PHB per section 4.8 of
[RFC4594]. When the Connection is multiplexed, the guidelines in [RFC4594]. When the Connection is multiplexed, the guidelines in
section 6 of [RFC7657] apply. section 6 of [RFC7657] apply.
The Capacity Profile for a selected protocol stack may be modified on The Capacity Profile for a selected protocol stack may be modified on
a per-Message basis using the Transmission Profile Message Property; a per-Message basis using the Transmission Profile Message Property;
see Section 7.3.8. see Section 7.3.8.
9.1.11. Bounds on Send or Receive Rate
Name: max-send-rate / max-recv-rate
Type: Integer (positive)
This property specifies an upper-bound rate that a transfer is not
expected to exceed (even if flow control and congestion control allow
higher rates), and/or a lower-bound rate below which the application
does not deem a data transfer useful. It is given in bits per
second.
9.1.12. TCP-specific Property: User Timeout
This property specifies, for the case TCP becomes the chosen
transport protocol:
Advertised User Timeout (name: tcp.user-timeout-value, type:
Integer):
a time value to be advertised via the User Timeout Option (UTO)
for the TCP at the remote endpoint to adapt its own "Timeout for
aborting Connection" (see Section 9.1.4) value accordingly
User Timeout Enabled (name: tcp.user-timeout, type: Boolean): a bool
ean (default false) to control whether the UTO option is enabled
for a connection. This applies to both sending and receiving.
Changeable (name: tcp.user-timeout-recv, type: Boolean): a boolean
(default true) which controls whether the "Timeout for aborting
Connection" (see Section 9.1.4) may be changed based on a UTO
option received from the remote peer. This boolean becomes false
when "Timeout for aborting Connection" (see Section 9.1.4) is
used.
All of the above parameters are optional (e.g., it is possible to
specify "User Timeout Enabled" as true, but not specify an Advertised
User Timeout value; in this case, the TCP default will be used).
9.2. Soft Errors 9.2. Soft Errors
Asynchronous introspection is also possible, via the SoftError Event. Asynchronous introspection is also possible, via the SoftError Event.
This event informing the application about the receipt of an ICMP This event informs the application about the receipt of an ICMP error
error message related to the Connection. This will only happen if message related to the Connection. This will only happen if the
the underlying protocol stack supports access to soft errors; underlying protocol stack supports access to soft errors; however,
however, even if the underlying stack supports it, there is no even if the underlying stack supports it, there is no guarantee that
guarantee that a soft error will be signaled. a soft error will be signaled.
Connection -> SoftError<> Connection -> SoftError<>
9.3. Excessive retransmissions
This event notifies the application of excessive retransmissions,
based on a configured threshold (see Section 9.1.1). This will only
happen if the underlying protocol stack supports reliability and,
with it, such notifications.
Connection -> ExcessiveRetransmission<>
10. Connection Termination 10. Connection Termination
Close terminates a Connection after satisfying all the requirements Close terminates a Connection after satisfying all the requirements
that were specified regarding the delivery of Messages that the that were specified regarding the delivery of Messages that the
application has already given to the transport system. For example, application has already given to the transport system. For example,
if reliable delivery was requested for a Message handed over before if reliable delivery was requested for a Message handed over before
calling Close, the transport system will ensure that this Message is calling Close, the transport system will ensure that this Message is
indeed delivered. If the Remote Endpoint still has data to send, it indeed delivered. If the Remote Endpoint still has data to send, it
cannot be received after this call. cannot be received after this call.
skipping to change at page 40, line 19 skipping to change at page 48, line 40
The Closed Event can inform the application that the Remote Endpoint The Closed Event can inform the application that the Remote Endpoint
has closed the Connection; however, there is no guarantee that a has closed the Connection; however, there is no guarantee that a
remote Close will indeed be signaled. remote Close will indeed be signaled.
Connection -> Closed<> Connection -> Closed<>
Abort terminates a Connection without delivering remaining data: Abort terminates a Connection without delivering remaining data:
Connection.Abort() Connection.Abort()
A ConnectionError can inform the application that the other side has A ConnectionError informs the application that data to could not be
aborted the Connection; however, there is no guarantee that an Abort delivered after a timeout, or the other side has aborted the
will indeed be signaled. Connection; however, there is no guarantee that an Abort will indeed
be signaled.
Connection -> ConnectionError<> Connection -> ConnectionError<>
11. Connection State and Ordering of Operations and Events 11. Connection State and Ordering of Operations and Events
As this interface is designed to be independent of an As this interface is designed to be independent of an
implementation's concurrency model, the details of how exactly implementation's concurrency model, the details of how exactly
actions are handled, and on which threads/callbacks events are actions are handled, and on which threads/callbacks events are
dispatched, are implementation dependent. dispatched, are implementation dependent.
Each transition of connection state is associated with one of more Each transition of connection state is associated with one of more
events: events:
o Ready<> occurs when a Connection created with Initiate() or o Ready<> occurs when a Connection created with Initiate() or
InitiateWithIdempotentData() transitions to Established state. InitiateWithSend() transitions to Established state.
o ConnectionReceived<> occurs when a Connection created with o ConnectionReceived<> occurs when a Connection created with
Listen() transitions to Established state. Listen() transitions to Established state.
o RendezvousDone<> occurs when a Connection created with o RendezvousDone<> occurs when a Connection created with
Rendezvous() transitions to Established state. Rendezvous() transitions to Established state.
o Closed<> occurs when a Connection transitions to Closed state o Closed<> occurs when a Connection transitions to Closed state
without error. without error.
skipping to change at page 41, line 33 skipping to change at page 50, line 9
on a Connection while other events on the Connection are still on a Connection while other events on the Connection are still
locally outstanding (i.e., known to the interface and waiting to locally outstanding (i.e., known to the interface and waiting to
be dealt with by the application). ConnectionError<> may occur be dealt with by the application). ConnectionError<> may occur
after Closed<>, but the interface must gracefully handle all cases after Closed<>, but the interface must gracefully handle all cases
where application ignores these errors. where application ignores these errors.
12. IANA Considerations 12. IANA Considerations
RFC-EDITOR: Please remove this section before publication. RFC-EDITOR: Please remove this section before publication.
This document has no Actions for IANA. 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.2.1).
13. Security Considerations 13. Security Considerations
This document describes a generic API for interacting with a This document describes a generic API for interacting with a
transport services (TAPS) system. Part of this API includes transport services (TAPS) system. Part of this API includes
configuration details for transport security protocols, as discussed configuration details for transport security protocols, as discussed
in Section 5.3. It does not recommend use (or disuse) of specific in Section 5.3. It does not recommend use (or disuse) of specific
algorithms or protocols. Any API-compatible transport security algorithms or protocols. Any API-compatible transport security
protocol should work in a TAPS system. protocol should work in a TAPS system.
skipping to change at page 42, line 21 skipping to change at page 50, line 48
and Jason Lee for initial work on the Post Sockets interface, from and Jason Lee for initial work on the Post Sockets interface, from
which this work has evolved. which this work has evolved.
15. References 15. References
15.1. Normative References 15.1. Normative References
[I-D.ietf-taps-arch] [I-D.ietf-taps-arch]
Pauly, T., Trammell, B., Brunstrom, A., Fairhurst, G., Pauly, T., Trammell, B., Brunstrom, A., Fairhurst, G.,
Perkins, C., Tiesel, P., and C. Wood, "An Architecture for Perkins, C., Tiesel, P., and C. Wood, "An Architecture for
Transport Services", draft-ietf-taps-arch-01 (work in Transport Services", draft-ietf-taps-arch-02 (work in
progress), July 2018. progress), October 2018.
[I-D.ietf-taps-minset]
Welzl, M. and S. Gjessing, "A Minimal Set of Transport
Services for End Systems", draft-ietf-taps-minset-11 (work
in progress), September 2018.
[I-D.ietf-tls-tls13]
Rescorla, E., "The Transport Layer Security (TLS) Protocol
Version 1.3", draft-ietf-tls-tls13-28 (work in progress),
March 2018.
[I-D.ietf-tsvwg-rtcweb-qos] [I-D.ietf-tsvwg-rtcweb-qos]
Jones, P., Dhesikan, S., Jennings, C., and D. Druta, "DSCP Jones, P., Dhesikan, S., Jennings, C., and D. Druta, "DSCP
Packet Markings for WebRTC QoS", draft-ietf-tsvwg-rtcweb- Packet Markings for WebRTC QoS", draft-ietf-tsvwg-rtcweb-
qos-18 (work in progress), August 2016. qos-18 (work in progress), August 2016.
[I-D.ietf-tsvwg-sctp-ndata] [I-D.ietf-tsvwg-sctp-ndata]
Stewart, R., Tuexen, M., Loreto, S., and R. Seggelmann, Stewart, R., Tuexen, M., Loreto, S., and R. Seggelmann,
"Stream Schedulers and User Message Interleaving for the "Stream Schedulers and User Message Interleaving for the
Stream Control Transmission Protocol", draft-ietf-tsvwg- Stream Control Transmission Protocol", draft-ietf-tsvwg-
skipping to change at page 43, line 5 skipping to change at page 51, line 25
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997, DOI 10.17487/RFC2119, March 1997,
<https://www.rfc-editor.org/info/rfc2119>. <https://www.rfc-editor.org/info/rfc2119>.
[RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
May 2017, <https://www.rfc-editor.org/info/rfc8174>. May 2017, <https://www.rfc-editor.org/info/rfc8174>.
[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/info/rfc8446>.
15.2. Informative References 15.2. Informative References
[I-D.ietf-taps-minset]
Welzl, M. and S. Gjessing, "A Minimal Set of Transport
Services for End Systems", draft-ietf-taps-minset-11 (work
in progress), September 2018.
[I-D.ietf-taps-transport-security] [I-D.ietf-taps-transport-security]
Pauly, T., Perkins, C., Rose, K., and C. Wood, "A Survey Wood, C., Enghardt, T., Pauly, T., Perkins, C., and K.
of Transport Security Protocols", draft-ietf-taps- Rose, "A Survey of Transport Security Protocols", draft-
transport-security-02 (work in progress), June 2018. ietf-taps-transport-security-06 (work in progress), March
2019.
[LE-PHB] Bless, R., "A Lower Effort Per-Hop Behavior (LE PHB)", [LE-PHB] Bless, R., "A Lower Effort Per-Hop Behavior (LE PHB) for
draft-ietf-tsvwg-le-phb-06 (work in progress), October Differentiated Services", draft-ietf-tsvwg-le-phb-10 (work
2018. in progress), March 2019.
[RFC0793] Postel, J., "Transmission Control Protocol", STD 7, [RFC0793] Postel, J., "Transmission Control Protocol", STD 7,
RFC 793, DOI 10.17487/RFC0793, September 1981, RFC 793, DOI 10.17487/RFC0793, September 1981,
<https://www.rfc-editor.org/info/rfc793>. <https://www.rfc-editor.org/info/rfc793>.
[RFC2474] Nichols, K., Blake, S., Baker, F., and D. Black, [RFC2474] Nichols, K., Blake, S., Baker, F., and D. Black,
"Definition of the Differentiated Services Field (DS "Definition of the Differentiated Services Field (DS
Field) in the IPv4 and IPv6 Headers", RFC 2474, Field) in the IPv4 and IPv6 Headers", RFC 2474,
DOI 10.17487/RFC2474, December 1998, DOI 10.17487/RFC2474, December 1998,
<https://www.rfc-editor.org/info/rfc2474>. <https://www.rfc-editor.org/info/rfc2474>.
skipping to change at page 45, line 14 skipping to change at page 53, line 48
final document, but are presented here to support discussion within final document, but are presented here to support discussion within
the TAPS working group as to whether they should be added to a future the TAPS working group as to whether they should be added to a future
revision of the base specification. revision of the base specification.
A.1. Experimental Transport Properties A.1. Experimental Transport Properties
The following Transport Properties might be made available in The following Transport Properties might be made available in
addition to those specified in Section 5.2, Section 9.1, and addition to those specified in Section 5.2, Section 9.1, and
Section 7.3. Section 7.3.
A.1.1. Direction of communication A.1.1. Cost Preferences
Classification: Selection Property, Control Property [TODO: Discuss]
Type: Enumeration
Applicability: Preconnection, Connection (read only)
This property specifies whether an application wants to use the
connection for sending and/or receiving data. Possible values are:
Bidirectional (default): The connection must support sending and
receiving data
unidirectional send: The connection must support sending data.
unidirectional receive: The connection must support receiving data
In case a unidirectional connection is requested, but unidirectional
connections are not supported by the transport protocol, the system
should fall back to bidirectional transport.
A.1.2. Suggest a timeout to the Remote Endpoint
Classification: Selection Property
Type: Preference
Applicability: Preconnection
This property specifies whether an application considers it useful to
propose a timeout until the Connection is assumed to be lost. The
default is to have this option.
[EDITOR'S NOTE: For discussion of this option, see
https://github.com/taps-api/drafts/issues/109]
A.1.3. Abort timeout to suggest to the Remote Endpoint
Classification: Protocol Property
Type: Integer
Applicability: Preconnection, Connection
This numeric property specifies the timeout to propose to the Remote
Endpoint. It is given in seconds.
[EDITOR'S NOTE: For discussion of this property, see
https://github.com/taps-api/drafts/issues/109]
A.1.4. Traffic Category
Classification: Intent
Type: Enumeration
Applicability: Preconnection
This property specifies what the application expects the dominating
traffic pattern to be. Possible values are:
Query: Single request / response style workload, latency bound
Control: Long lasting low bandwidth control channel, not bandwidth
bound
Stream: Stream of data with steady data rate
Bulk: Bulk transfer of large Messages, presumably bandwidth bound
The default is to not assume any particular traffic pattern. Most
categories suggest the use of other intents to further describe the
traffic pattern anticipated, e.g., the bulk category suggesting the
use of the Message Size intents or the stream category suggesting the
Stream Bitrate and Duration intents.
A.1.5. Size to be Sent or Received
Classification: Intent
Type: Integer
Applicability: Preconnection, Message
This property specifies how many bytes the application expects to
send (Size to be Sent) or how many bytes the application expects to
receive in response (Size to be Received).
A.1.6. Duration
Classification: Intent
Type: Integer
Applicability: Preconnection
This Intent specifies what the application expects the lifetime of a
Connection to be. It is given in milliseconds.
A.1.7. Send or Receive Bit-rate
Classification: Intent
Type: Integer
Applicability: Preconnection, Message
This Intent specifies what the application expects the bit-rate of a
transfer to be. It is given in Bytes per second.
On a Message, this property specifies at what bitrate the application
wishes the Message to be sent. A transport system supporting this
feature will not exceed the requested Send Bitrate even if flow-
control and congestion control allow higher bitrates. This helps to
avoid a bursty traffic pattern on busy streaming video servers.
A.1.8. Cost Preferences [EDITOR'S NOTE: At IETF 103, opinions were that this property should
stay, but it was also said that this is maybe not "on the right
level". If / when moving it to the main text, note that this is
meant to be applicable to a Preconnection or a Message.]
Classification: Intent Name: cost-preferences
Type: Enumeration Type: Enumeration
Applicability: Preconnection, Message
This property describes what an application prefers regarding This property describes what an application prefers regarding
monetary costs, e.g., whether it considers it acceptable to utilize monetary costs, e.g., whether it considers it acceptable to utilize
limited data volume. It provides hints to the transport system on limited data volume. It provides hints to the transport system on
how to handle trade-offs between cost and performance or reliability. how to handle trade-offs between cost and performance or reliability.
Possible values are: Possible values are:
No Expense: Avoid transports associated with monetary cost No Expense: Avoid transports associated with monetary cost
Optimize Cost: Prefer inexpensive transports and accept service Optimize Cost: Prefer inexpensive transports and accept service
degradation degradation
Balance Cost: Use system policy to balance cost and other criteria Balance Cost: Use system policy to balance cost and other criteria
Ignore Cost: Ignore cost, choose transport solely based on other Ignore Cost: Ignore cost, choose transport solely based on other
criteria criteria
The default is "Balance Cost". The default is "Balance Cost".
skipping to change at page 48, line 42 skipping to change at page 55, line 10
available that 1) require interaction with the application, and 2) do available that 1) require interaction with the application, and 2) do
not get in the way of a possible implementation over TCP or, with not get in the way of a possible implementation over TCP or, with
limitations, UDP. The following text explains how this minimal set limitations, UDP. The following text explains how this minimal set
is reflected in the present API. For brevity, this uses the list in is reflected in the present API. For brevity, this uses the list in
Section 4.1 of [I-D.ietf-taps-minset], updated according to the Section 4.1 of [I-D.ietf-taps-minset], updated according to the
discussion in Section 5 of [I-D.ietf-taps-minset]. discussion in Section 5 of [I-D.ietf-taps-minset].
[EDITOR'S NOTE: This is early text. In the future, this section will [EDITOR'S NOTE: This is early text. In the future, this section will
contain backward references, which we currently avoid because things contain backward references, which we currently avoid because things
are still being moved around and names / categories etc. are are still being moved around and names / categories etc. are
changing. Also, clearly, the intention is for the full minset to be changing.]
reflected by the API at some point.]
o Connect: o Connect:
"Initiate" Action. "Initiate" Action.
o Listen: o Listen:
"Listen" Action. "Listen" Action.
o Specify number of attempts and/or timeout for the first o Specify number of attempts and/or timeout for the first
establishment message: establishment message:
TODO. "Timeout for aborting Connection Establishment" Property, using a
time value.
o Disable MPTCP: o Disable MPTCP:
TODO. "Parallel Use of Multiple Paths" Property.
o Hand over a message to reliably transfer (possibly multiple times) o Hand over a message to reliably transfer (possibly multiple times)
before connection establishment: before connection establishment:
"InitiateWithIdempotentSend" Action. "InitiateWithSend" Action.
o Hand over a message to reliably transfer during connection o Hand over a message to reliably transfer during connection
establishment: establishment:
TODO. "InitiateWithSend" Action.
o Change timeout for aborting connection (using retransmit limit or o Change timeout for aborting connection (using retransmit limit or
time value): time value):
"Timeout for aborting Connection" property, using a time value in "Timeout for aborting Connection" property, using a time value.
seconds.
o Timeout event when data could not be delivered for too long: o Timeout event when data could not be delivered for too long:
TODO: this should probably be covered by the "ConnectionError" "ConnectionError" Event.
Event, but the text above it currently reads: "...can inform the
application that the other side has aborted the Connection". In
this case, it is the local side.
o Suggest timeout to the peer: o Suggest timeout to the peer:
"Suggest a timeout to the Remote Endpoint" and "Abort timeout to TCP-specific Property: User Timeout.
suggest to the Remote Endpoint" Selection property. [EDITOR'S
NOTE: For discussion of this option, see https://github.com/taps-
api/drafts/issues/109].
o Notification of Excessive Retransmissions (early warning below o Notification of Excessive Retransmissions (early warning below
abortion threshold): abortion threshold):
"Notification of excessive retransmissions" property. "Notification of excessive retransmissions" property.
o Notification of ICMP error message arrival: o Notification of ICMP error message arrival:
"Notification of ICMP soft error message arrival" property. "Notification of ICMP soft error message arrival" property.
o Choose a scheduler to operate between streams of an association: o Choose a scheduler to operate between streams of an association:
"Connection group transmission scheduler" property. "Connection group transmission scheduler" property.
o Configure priority or weight for a scheduler: o Configure priority or weight for a scheduler:
"Niceness (Connection)" property. "Priority (Connection)" property.
o "Specify checksum coverage used by the sender" and "Disable o "Specify checksum coverage used by the sender" and "Disable
checksum when sending": checksum when sending":
"Corruption Protection Length" property (value 0 to disable). "Corruption Protection Length" property (value 0 to disable).
o "Specify minimum checksum coverage required by receiver" and o "Specify minimum checksum coverage required by receiver" and
"Disable checksum requirement when receiving": "Disable checksum requirement when receiving":
"Required minimum coverage of the checksum for receiving" property "Required minimum coverage of the checksum for receiving" property
(value 0 to disable). (value 0 to disable).
skipping to change at page 51, line 44 skipping to change at page 58, line 4
"ReceivedPartial" Event. "ReceivedPartial" Event.
o Notification of send failures: o Notification of send failures:
"Expired" and "SendError" Events. "Expired" and "SendError" Events.
o Notification that the stack has no more user data to send: o Notification that the stack has no more user data to send:
Applications can obtain this information via the "Sent" Event. Applications can obtain this information via the "Sent" Event.
o Notification to a receiver that a partial message delivery has o Notification to a receiver that a partial message delivery has
been aborted: been aborted:
"ReceiveError" Event. "ReceiveError" Event.
Authors' Addresses Authors' Addresses
Brian Trammell (editor) Brian Trammell (editor)
ETH Zurich Google
Gloriastrasse 35 Gustav-Gull-Platz 1
8092 Zurich 8004 Zurich
Switzerland Switzerland
Email: ietf@trammell.ch Email: ietf@trammell.ch
Michael Welzl (editor) Michael Welzl (editor)
University of Oslo University of Oslo
PO Box 1080 Blindern PO Box 1080 Blindern
0316 Oslo 0316 Oslo
Norway Norway
 End of changes. 129 change blocks. 
436 lines changed or deleted 687 lines changed or added

This html diff was produced by rfcdiff 1.45. The latest version is available from http://tools.ietf.org/tools/rfcdiff/