draft-ietf-taps-interface-04.txt   draft-ietf-taps-interface-05.txt 
TAPS Working Group B. Trammell, Ed. TAPS Working Group B. Trammell, Ed.
Internet-Draft Google Internet-Draft Google
Intended status: Standards Track M. Welzl, Ed. Intended status: Standards Track M. Welzl, Ed.
Expires: January 9, 2020 University of Oslo Expires: May 7, 2020 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
T. Pauly T. Pauly
Apple Inc. Apple Inc.
July 08, 2019 November 04, 2019
An Abstract Application Layer Interface to Transport Services An Abstract Application Layer Interface to Transport Services
draft-ietf-taps-interface-04 draft-ietf-taps-interface-05
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 January 9, 2020. This Internet-Draft will expire on May 7, 2020.
Copyright Notice Copyright Notice
Copyright (c) 2019 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
skipping to change at page 2, line 36 skipping to change at page 2, line 36
4. API Summary . . . . . . . . . . . . . . . . . . . . . . . . . 7 4. API Summary . . . . . . . . . . . . . . . . . . . . . . . . . 7
4.1. Usage Examples . . . . . . . . . . . . . . . . . . . . . 8 4.1. Usage Examples . . . . . . . . . . . . . . . . . . . . . 8
4.1.1. Server Example . . . . . . . . . . . . . . . . . . . 8 4.1.1. Server Example . . . . . . . . . . . . . . . . . . . 8
4.1.2. Client Example . . . . . . . . . . . . . . . . . . . 9 4.1.2. Client Example . . . . . . . . . . . . . . . . . . . 9
4.1.3. Peer Example . . . . . . . . . . . . . . . . . . . . 10 4.1.3. Peer Example . . . . . . . . . . . . . . . . . . . . 10
4.2. Transport Properties . . . . . . . . . . . . . . . . . . 11 4.2. Transport Properties . . . . . . . . . . . . . . . . . . 11
4.2.1. Transport Property Names . . . . . . . . . . . . . . 12 4.2.1. Transport Property Names . . . . . . . . . . . . . . 12
4.2.2. Transport Property Types . . . . . . . . . . . . . . 13 4.2.2. Transport Property Types . . . . . . . . . . . . . . 13
4.3. Scope of the Interface Definition . . . . . . . . . . . . 13 4.3. Scope of the Interface Definition . . . . . . . . . . . . 13
5. Pre-Establishment Phase . . . . . . . . . . . . . . . . . . . 14 5. Pre-Establishment Phase . . . . . . . . . . . . . . . . . . . 14
5.1. Specifying Endpoints . . . . . . . . . . . . . . . . . . 14 5.1. Specifying Endpoints . . . . . . . . . . . . . . . . . . 15
5.2. Specifying Transport Properties . . . . . . . . . . . . . 16 5.2. Specifying Transport Properties . . . . . . . . . . . . . 16
5.2.1. Reliable Data Transfer (Connection) . . . . . . . . . 18 5.2.1. Reliable Data Transfer (Connection) . . . . . . . . . 18
5.2.2. Preservation of Message Boundaries . . . . . . . . . 18 5.2.2. Preservation of Message Boundaries . . . . . . . . . 18
5.2.3. Configure Per-Message Reliability . . . . . . . . . . 18 5.2.3. Configure Per-Message Reliability . . . . . . . . . . 18
5.2.4. Preservation of Data Ordering . . . . . . . . . . . . 18 5.2.4. Preservation of Data Ordering . . . . . . . . . . . . 18
5.2.5. Use 0-RTT Session Establishment with an Idempotent 5.2.5. Use 0-RTT Session Establishment with an Idempotent
Message . . . . . . . . . . . . . . . . . . . . . . . 19 Message . . . . . . . . . . . . . . . . . . . . . . . 19
5.2.6. Multistream Connections in Group . . . . . . . . . . 19 5.2.6. Multistream Connections in Group . . . . . . . . . . 19
5.2.7. Full Checksum Coverage on Sending . . . . . . . . . . 19 5.2.7. Full Checksum Coverage on Sending . . . . . . . . . . 19
5.2.8. Full Checksum Coverage on Receiving . . . . . . . . . 19 5.2.8. Full Checksum Coverage on Receiving . . . . . . . . . 19
skipping to change at page 3, line 15 skipping to change at page 3, line 15
5.2.15. Notification of ICMP soft error message arrival . . . 22 5.2.15. Notification of ICMP soft error message arrival . . . 22
5.3. Specifying Security Parameters and Callbacks . . . . . . 22 5.3. Specifying Security Parameters and Callbacks . . . . . . 22
5.3.1. Pre-Connection Parameters . . . . . . . . . . . . . . 23 5.3.1. Pre-Connection Parameters . . . . . . . . . . . . . . 23
5.3.2. Connection Establishment Callbacks . . . . . . . . . 24 5.3.2. Connection Establishment Callbacks . . . . . . . . . 24
6. Establishing Connections . . . . . . . . . . . . . . . . . . 24 6. Establishing Connections . . . . . . . . . . . . . . . . . . 24
6.1. Active Open: Initiate . . . . . . . . . . . . . . . . . . 24 6.1. Active Open: Initiate . . . . . . . . . . . . . . . . . . 24
6.2. Passive Open: Listen . . . . . . . . . . . . . . . . . . 26 6.2. Passive Open: Listen . . . . . . . . . . . . . . . . . . 26
6.3. Peer-to-Peer Establishment: Rendezvous . . . . . . . . . 27 6.3. Peer-to-Peer Establishment: Rendezvous . . . . . . . . . 27
6.4. Connection Groups . . . . . . . . . . . . . . . . . . . . 28 6.4. Connection Groups . . . . . . . . . . . . . . . . . . . . 28
7. Sending Data . . . . . . . . . . . . . . . . . . . . . . . . 29 7. Sending Data . . . . . . . . . . . . . . . . . . . . . . . . 29
7.1. Basic Sending . . . . . . . . . . . . . . . . . . . . . . 29 7.1. Basic Sending . . . . . . . . . . . . . . . . . . . . . . 30
7.2. Sending Replies . . . . . . . . . . . . . . . . . . . . . 30 7.2. Sending Replies . . . . . . . . . . . . . . . . . . . . . 30
7.3. Send Events . . . . . . . . . . . . . . . . . . . . . . . 30 7.3. Send Events . . . . . . . . . . . . . . . . . . . . . . . 31
7.3.1. Sent . . . . . . . . . . . . . . . . . . . . . . . . 31 7.3.1. Sent . . . . . . . . . . . . . . . . . . . . . . . . 31
7.3.2. Expired . . . . . . . . . . . . . . . . . . . . . . . 31 7.3.2. Expired . . . . . . . . . . . . . . . . . . . . . . . 31
7.3.3. SendError . . . . . . . . . . . . . . . . . . . . . . 31 7.3.3. SendError . . . . . . . . . . . . . . . . . . . . . . 32
7.4. Message Properties . . . . . . . . . . . . . . . . . . . 31 7.4. Message Properties . . . . . . . . . . . . . . . . . . . 32
7.4.1. Lifetime . . . . . . . . . . . . . . . . . . . . . . 32 7.4.1. Lifetime . . . . . . . . . . . . . . . . . . . . . . 33
7.4.2. Priority . . . . . . . . . . . . . . . . . . . . . . 33 7.4.2. Priority . . . . . . . . . . . . . . . . . . . . . . 33
7.4.3. Ordered . . . . . . . . . . . . . . . . . . . . . . . 33 7.4.3. Ordered . . . . . . . . . . . . . . . . . . . . . . . 34
7.4.4. Idempotent . . . . . . . . . . . . . . . . . . . . . 34 7.4.4. Idempotent . . . . . . . . . . . . . . . . . . . . . 34
7.4.5. Final . . . . . . . . . . . . . . . . . . . . . . . . 34 7.4.5. Final . . . . . . . . . . . . . . . . . . . . . . . . 34
7.4.6. Corruption Protection Length . . . . . . . . . . . . 35 7.4.6. Corruption Protection Length . . . . . . . . . . . . 35
7.4.7. Reliable Data Transfer (Message) . . . . . . . . . . 35 7.4.7. Reliable Data Transfer (Message) . . . . . . . . . . 35
7.4.8. Message Capacity Profile Override . . . . . . . . . . 35 7.4.8. Message Capacity Profile Override . . . . . . . . . . 36
7.4.9. Singular Transmission . . . . . . . . . . . . . . . . 36 7.4.9. Singular Transmission . . . . . . . . . . . . . . . . 36
7.5. Partial Sends . . . . . . . . . . . . . . . . . . . . . . 36 7.5. Partial Sends . . . . . . . . . . . . . . . . . . . . . . 37
7.6. Batching Sends . . . . . . . . . . . . . . . . . . . . . 37 7.6. Batching Sends . . . . . . . . . . . . . . . . . . . . . 37
7.7. Send on Active Open: InitiateWithSend . . . . . . . . . . 37 7.7. Send on Active Open: InitiateWithSend . . . . . . . . . . 38
8. Receiving Data . . . . . . . . . . . . . . . . . . . . . . . 38 8. Receiving Data . . . . . . . . . . . . . . . . . . . . . . . 38
8.1. Enqueuing Receives . . . . . . . . . . . . . . . . . . . 38 8.1. Enqueuing Receives . . . . . . . . . . . . . . . . . . . 38
8.2. Receive Events . . . . . . . . . . . . . . . . . . . . . 39 8.2. Receive Events . . . . . . . . . . . . . . . . . . . . . 39
8.2.1. Received . . . . . . . . . . . . . . . . . . . . . . 39 8.2.1. Received . . . . . . . . . . . . . . . . . . . . . . 39
8.2.2. ReceivedPartial . . . . . . . . . . . . . . . . . . . 39 8.2.2. ReceivedPartial . . . . . . . . . . . . . . . . . . . 40
8.2.3. ReceiveError . . . . . . . . . . . . . . . . . . . . 40 8.2.3. ReceiveError . . . . . . . . . . . . . . . . . . . . 40
8.3. Receive Message Properties . . . . . . . . . . . . . . . 40 8.3. Receive Message Properties . . . . . . . . . . . . . . . 41
8.3.1. ECN . . . . . . . . . . . . . . . . . . . . . . . . . 41 8.3.1. ECN . . . . . . . . . . . . . . . . . . . . . . . . . 41
8.3.2. Early Data . . . . . . . . . . . . . . . . . . . . . 41 8.3.2. Early Data . . . . . . . . . . . . . . . . . . . . . 41
8.3.3. Receiving Final Messages . . . . . . . . . . . . . . 41 8.3.3. Receiving Final Messages . . . . . . . . . . . . . . 41
9. Message Contexts . . . . . . . . . . . . . . . . . . . . . . 41 9. Message Contexts . . . . . . . . . . . . . . . . . . . . . . 42
10. Message Framers . . . . . . . . . . . . . . . . . . . . . . . 42 10. Message Framers . . . . . . . . . . . . . . . . . . . . . . . 42
10.1. Defining Message Framers . . . . . . . . . . . . . . . . 43 10.1. Adding Message Framers to Connections . . . . . . . . . 43
10.2. Adding Message Framers to Connections . . . . . . . . . 43 10.2. Framing Meta-Data . . . . . . . . . . . . . . . . . . . 43
10.3. Framing Meta-Data . . . . . . . . . . . . . . . . . . . 43 11. Managing Connections . . . . . . . . . . . . . . . . . . . . 44
10.4. Message Framer Lifetime . . . . . . . . . . . . . . . . 44 11.1. Generic Connection Properties . . . . . . . . . . . . . 45
10.5. Sender-side Message Framing . . . . . . . . . . . . . . 44
10.6. Receiver-side Message Framing . . . . . . . . . . . . . 45
11. Managing Connections . . . . . . . . . . . . . . . . . . . . 46
11.1. Generic Connection Properties . . . . . . . . . . . . . 47
11.1.1. Retransmission Threshold Before Excessive 11.1.1. Retransmission Threshold Before Excessive
Retransmission Notification . . . . . . . . . . . . 47 Retransmission Notification . . . . . . . . . . . . 46
11.1.2. Required Minimum Corruption Protection Coverage for 11.1.2. Required Minimum Corruption Protection Coverage for
Receiving . . . . . . . . . . . . . . . . . . . . . 48 Receiving . . . . . . . . . . . . . . . . . . . . . 46
11.1.3. Priority (Connection) . . . . . . . . . . . . . . . 48 11.1.3. Priority (Connection) . . . . . . . . . . . . . . . 46
11.1.4. Timeout for Aborting Connection . . . . . . . . . . 48 11.1.4. Timeout for Aborting Connection . . . . . . . . . . 46
11.1.5. Connection Group Transmission Scheduler . . . . . . 49 11.1.5. Connection Group Transmission Scheduler . . . . . . 47
11.1.6. Maximum Message Size Concurrent with Connection 11.1.6. Maximum Message Size Concurrent with Connection
Establishment . . . . . . . . . . . . . . . . . . . 49 Establishment . . . . . . . . . . . . . . . . . . . 47
11.1.7. Maximum Message Size Before Fragmentation or 11.1.7. Maximum Message Size Before Fragmentation or
Segmentation . . . . . . . . . . . . . . . . . . . . 49 Segmentation . . . . . . . . . . . . . . . . . . . . 47
11.1.8. Maximum Message Size on Send . . . . . . . . . . . . 49 11.1.8. Maximum Message Size on Send . . . . . . . . . . . . 47
11.1.9. Maximum Message Size on Receive . . . . . . . . . . 49 11.1.9. Maximum Message Size on Receive . . . . . . . . . . 48
11.1.10. Capacity Profile . . . . . . . . . . . . . . . . . . 50 11.1.10. Capacity Profile . . . . . . . . . . . . . . . . . . 48
11.1.11. Bounds on Send or Receive Rate . . . . . . . . . . . 51 11.1.11. Bounds on Send or Receive Rate . . . . . . . . . . . 49
11.1.12. TCP-specific Property: User Timeout . . . . . . . . 52 11.1.12. TCP-specific Property: User Timeout . . . . . . . . 50
11.2. Soft Errors . . . . . . . . . . . . . . . . . . . . . . 52 11.2. Soft Errors . . . . . . . . . . . . . . . . . . . . . . 50
11.3. Excessive retransmissions . . . . . . . . . . . . . . . 52 11.3. Excessive retransmissions . . . . . . . . . . . . . . . 51
12. Connection Termination . . . . . . . . . . . . . . . . . . . 53 12. Connection Termination . . . . . . . . . . . . . . . . . . . 51
13. Connection State and Ordering of Operations and Events . . . 53 13. Connection State and Ordering of Operations and Events . . . 51
14. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 54 14. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 52
15. Security Considerations . . . . . . . . . . . . . . . . . . . 54 15. Security Considerations . . . . . . . . . . . . . . . . . . . 53
16. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 55 16. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 53
17. References . . . . . . . . . . . . . . . . . . . . . . . . . 55 17. References . . . . . . . . . . . . . . . . . . . . . . . . . 53
17.1. Normative References . . . . . . . . . . . . . . . . . . 55 17.1. Normative References . . . . . . . . . . . . . . . . . . 53
17.2. Informative References . . . . . . . . . . . . . . . . . 56 17.2. Informative References . . . . . . . . . . . . . . . . . 54
Appendix A. Additional Properties . . . . . . . . . . . . . . . 57 Appendix A. Convenience Functions . . . . . . . . . . . . . . . 56
A.1. Experimental Transport Properties . . . . . . . . . . . . 58 A.1. Adding Preference Properties . . . . . . . . . . . . . . 56
A.1.1. Cost Preferences . . . . . . . . . . . . . . . . . . 58 A.2. Transport Property Profiles . . . . . . . . . . . . . . . 56
Appendix B. Sample API definition in Go . . . . . . . . . . . . 59 A.2.1. reliable-inorder-stream . . . . . . . . . . . . . . . 57
Appendix C. Relationship to the Minimal Set of Transport A.2.2. reliable-message . . . . . . . . . . . . . . . . . . 57
A.2.3. unreliable-datagram . . . . . . . . . . . . . . . . . 57
Appendix B. Additional Properties . . . . . . . . . . . . . . . 58
B.1. Experimental Transport Properties . . . . . . . . . . . . 58
B.1.1. Cost Preferences . . . . . . . . . . . . . . . . . . 59
Appendix C. Sample API definition in Go . . . . . . . . . . . . 59
Appendix D. Relationship to the Minimal Set of Transport
Services for End Systems . . . . . . . . . . . . . . 59 Services for End Systems . . . . . . . . . . . . . . 59
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 62 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 62
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 [PROTOCOL-WARS] of the 1980s. SOCK_STREAM is tied to the
Protocol (TCP), specified in 1981 [RFC0793]. TCP has scaled Transmission Control Protocol (TCP), specified in 1981 [RFC0793].
remarkably well over the past three and a half decades, but its total TCP has scaled remarkably well over the past three and a half
ubiquity has hidden an uncomfortable fact: the network is not really decades, but its total ubiquity has hidden an uncomfortable fact: the
a file, and stream abstractions are too simplistic for many modern network is not really a file, and stream abstractions are too
application programming models. simplistic for many modern application programming models.
In the meantime, the nature of Internet access, and the variety of In the meantime, the nature of Internet access, and the variety of
Internet transport protocols, is evolving. The challenges that new Internet transport protocols, is evolving. The challenges that new
protocols and access paradigms present to the sockets API and to protocols and access paradigms present to the sockets API and to
programming models based on them inspire the design principles of a programming models based on them inspire the design principles of a
new approach, which we outline in Section 3. new approach, which we outline in Section 3.
As a first step to realizing this design, [I-D.ietf-taps-arch] This document builds a modern abstract programming interface atop the
describes a high-level architecture for transport services. This high-level architecture for transport services defined in
document builds a modern abstract programming interface atop this [I-D.ietf-taps-arch]. It derives specific path and protocol
architecture, deriving specific path and protocol selection selection properties and supported transport features from the
properties and supported transport features from the analysis analysis provided in [RFC8095], [I-D.ietf-taps-minset], and
provided in [RFC8095], [I-D.ietf-taps-minset], and
[I-D.ietf-taps-transport-security]. [I-D.ietf-taps-transport-security].
2. Terminology and Notation 2. Terminology and Notation
This API is described in terms of Objects, which an application can This API is described in terms of Objects, which an application can
interact with; Actions the application can perform on these Objects; interact with; Actions the application can perform on these Objects;
Events, which an Object can send to an application asynchronously; Events, which an Object can send to an application asynchronously;
and Parameters associated with these Actions and Events. and Parameters associated with these Actions and Events.
The following notations, which can be combined, are used in this The following notations, which can be combined, are used in this
skipping to change at page 5, line 48 skipping to change at page 5, line 48
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. Action parameters whose names are suffixed with a Parameters. Action and Event parameters whose names are suffixed
question mark are optional. with a question mark are optional.
Action(param0, param1?, ...) / Event<param0, param1, ...> 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
processes, or other asynchronous calling conventions. The method for processes, or other asynchronous calling conventions. The method for
dispatching and handling Events is left as an implementation detail, dispatching and handling Events is an implementation detail, with the
with the caveat that the interface for receiving Messages must caveat that the interface for receiving Messages must require the
require the application to invoke the Connection.Receive() Action application to invoke the Connection.Receive() Action once per
once per Message to be received (see Section 8). Message to be received (see Section 8).
This specification treats Events and errors similarly. Errors, just This specification treats Events and errors similarly. Errors, just
as any other Events, may occur asynchronously in network as any other Events, may occur asynchronously in network
applications. However, it is recommended that implementations of applications. However, it is recommended that implementations of
this interface also return errors immediately, according to the error this interface also return errors immediately, according to the error
handling idioms of the implementation platform, for errors which can handling idioms of the implementation platform, for errors that can
be immediately detected, such as inconsistency in Transport be immediately detected, such as inconsistency in Transport
Properties. Properties. Errors can provide an optional reason to give the
application further details as to why the error occured.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
"OPTIONAL" in this document are to be interpreted as described in BCP "OPTIONAL" in this document are to be interpreted as described in BCP
14 [RFC2119] [RFC8174] when, and only when, they appear in all 14 [RFC2119] [RFC8174] when, and only when, they appear in all
capitals, as shown here. capitals, as shown here.
3. Interface Design Principles 3. Interface Design Principles
The design of the interface specified in this document is based on a The design of the interface specified in this document is based on a
skipping to change at page 6, line 49 skipping to change at page 7, line 5
o A single interface to a variety of transport protocols to be used o A single interface to a variety of transport protocols to be used
in a variety of application design patterns, independent of the in a variety of application design patterns, independent of the
properties of the application and the Protocol Stacks that will be properties of the application and the Protocol Stacks that will be
used at runtime, such that all common specialized features of used at runtime, such that all common specialized features of
these protocol stacks are made available to the application as these protocol stacks are made available to the application as
necessary in a transport-independent way, to enable applications necessary in a transport-independent way, to enable applications
written to a single API to make use of transport protocols in written to a single API to make use of transport protocols in
terms of the features they provide; terms of the features they provide;
o Message- as opposed to stream-orientation, using application- o Message-orientation, as opposed to stream-orientation, using
assisted framing and deframing where the underlying transport does application-assisted framing and deframing where the underlying
not provide these; transport does not provide these;
o Asynchronous Connection establishment, transmission, and o Asynchronous Connection establishment, transmission, and
reception, allowing concurrent operations during establishment and reception, allowing concurrent operations during establishment and
supporting event-driven application interactions with the supporting event-driven application interactions with the
transport layer, in line with developments in modern platforms and transport layer, in line with developments in modern platforms and
programming languages; programming languages;
o Explicit support for security properties as first-order transport o Explicit support for security properties as first-order transport
features, and for long-term caching of cryptographic identities features, and for long-term caching of cryptographic identities
and parameters for associations among endpoints; and and parameters for associations among endpoints; and
skipping to change at page 7, line 25 skipping to change at page 7, line 29
o Explicit support for multistreaming and multipath transport o Explicit support for multistreaming and multipath transport
protocols, and the grouping of related Connections into Connection protocols, and the grouping of related Connections into Connection
Groups through cloning of Connections, to allow applications to Groups through cloning of Connections, to allow applications to
take full advantage of new transport protocols supporting these take full advantage of new transport protocols supporting these
features. features.
4. API Summary 4. API Summary
The Transport Services Interface is the basic common abstract The Transport Services Interface is the basic common abstract
application programming interface to the Transport Services application programming interface to the Transport Services
Architecture defined in [I-D.ietf-taps-arch]. Architecture defined in the TAPS Architecture [I-D.ietf-taps-arch].
An application primarily interacts with this interface through two An application primarily interacts with this interface through two
Objects, Preconnections and Connections. A Preconnection represents Objects: Preconnections and Connections. A Preconnection represents
a set of properties and constraints on the selection and a set of properties and constraints on the selection and
configuration of paths and protocols to establish a Connection with a configuration of paths and protocols to establish a Connection with a
remote endpoint. A Connection represents a transport Protocol Stack remote Endpoint. A Connection represents a transport Protocol Stack
on which data can be sent to and/or received from a remote endpoint on which data can be sent to and/or received from a remote Endpoint
(i.e., depending on the kind of transport, connections can be bi- (i.e., depending on the kind of transport, connections can be bi-
directional or unidirectional). Connections can be created from directional or unidirectional). Connections can be created from
Preconnections in three ways: by initiating the Preconnection (i.e., Preconnections in three ways: by initiating the Preconnection (i.e.,
actively opening, as in a client), through listening on the actively opening, as in a client), through listening on the
Preconnection (i.e., passively opening, as in a server), or Preconnection (i.e., passively opening, as in a server), or
rendezvousing on the Preconnection (i.e. peer to peer rendezvousing on the Preconnection (i.e. peer to peer
establishment). establishment).
Once a Connection is established, data can be sent on it in the form Once a Connection is established, data can be sent on it in the form
of Messages. The interface supports the preservation of message of Messages. The interface supports the preservation of message
skipping to change at page 8, line 22 skipping to change at page 8, line 27
o Act as a client, by connecting to a remote endpoint using o Act as a client, by connecting to a remote endpoint using
Initiate, sending requests, and receiving responses, see Initiate, sending requests, and receiving responses, see
Section 4.1.2. Section 4.1.2.
o Act as a peer, by connecting to a remote endpoint using Rendezvous o Act as a peer, by connecting to a remote endpoint using Rendezvous
while simultaneously waiting for incoming Connections, sending while simultaneously waiting for incoming Connections, sending
Messages, and receiving Messages, see Section 4.1.3. Messages, and receiving Messages, see Section 4.1.3.
The examples in this section presume that a transport protocol is The examples in this section presume that a transport protocol is
available between the endpoints which provides Reliable Data available between the endpoints that provides Reliable Data Transfer,
Transfer, Preservation of data ordering, and Preservation of Message Preservation of data ordering, and Preservation of Message
Boundaries. In this case, the application can choose to receive only Boundaries. In this case, the application can choose to receive only
complete messages. complete messages.
If none of the available transport protocols provides Preservation of If none of the available transport protocols provides Preservation of
Message Boundaries, but there is a transport protocol which provides Message Boundaries, but there is a transport protocol that provides a
a reliable ordered byte stream, an application may receive this byte reliable ordered byte stream, an application may receive this byte
stream as partial Messages and transform it into application-layer stream as partial Messages and transform it into application-layer
Messages. Alternatively, an application may provide a Message Messages. Alternatively, an application may provide a Message
Framer, which can transform a byte stream into a sequence of Messages Framer, which can transform a byte stream into a sequence of Messages
(Section 10.6). (Section 10).
4.1.1. Server Example 4.1.1. Server Example
This is an example of how an application might listen for incoming This is an example of how an application might listen for incoming
Connections using the Transport Services Interface, receive a Connections using the Transport Services Interface, receive a
request, and send a response. request, and send a response.
LocalSpecifier := NewLocalEndpoint() LocalSpecifier := NewLocalEndpoint()
LocalSpecifier.WithInterface("any") LocalSpecifier.WithInterface("any")
LocalSpecifier.WithService("https") LocalSpecifier.WithService("https")
skipping to change at page 11, line 48 skipping to change at page 11, line 48
Connection.Receive() Connection.Receive()
Connection -> Received(messageDataResponse, messageContext) Connection -> Received(messageDataResponse, messageContext)
Connection.Close() Connection.Close()
4.2. Transport Properties 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 using
pre-establishment, Selection Properties (see Section 5.2) are used to Transport Properties, as defined in [I-D.ietf-taps-arch].
specify which paths and protocol stacks can be used and are preferred
by the application, and Connection Properties (see Section 11.1) can
be used to influence decisions made during establishment and to fine-
tune the eventually established connection. These Connection
Properties can also be used later, to monitor and fine-tune
established connections. The behavior of the selected protocol
stack(s) when sending Messages is controlled by Message Properties
(see Section 7.4).
Collectively, Selection, Connection, and Message Properties can be Transport Properties are divided into Selection, Connection, and
referred to as Transport Properties. All Transport Properties, Message Properties. During pre-establishment, Selection Properties
regardless of the phase in which they are used, are organized within (see Section 5.2) are used to specify which paths and protocol stacks
a single namespace. This enables setting them as defaults in earlier can be used and are preferred by the application, and Connection
stages and querying them in later stages: - Connection Properties can Properties (see Section 11.1) can be used to influence decisions made
be set on Preconnections - Message Properties can be set on during establishment and to fine-tune the eventually established
Preconnections and Connections - The effect of Selection Properties connection. These Connection Properties can also be used later, to
can be queried on Connections and Messages monitor and fine-tune established connections. The behavior of the
selected protocol stack(s) when sending Messages is controlled by
Message Properties (see Section 7.4).
All Transport Properties, regardless of the phase in which they are
used, are organized within a single namespace. This enables setting
them as defaults in earlier stages and querying them in later stages:
o Connection Properties can be set on Preconnections
o Message Properties can be set on Preconnections and Connections
o The effect of Selection Properties can be queried on Connections
and Messages
Note that Configuring Connection Properties and Message Properties on Note that Configuring Connection Properties and Message Properties on
Preconnections is preferred over setting them later. Connection Preconnections is preferred over setting them later. Early
Properties specified early on may be used as additional input to the specification of Connection Properties allows their use as additional
selection process. Also note that Protocol Specific Properties, see input to the selection process. Protocol Specific Properties, see
Section 4.2.1, should not be used as an input to the selection Section 4.2.1, should not be used as an input to the selection
process. process.
4.2.1. Transport Property Names 4.2.1. Transport Property Names
Transport Properties are referred to by property names. These names Transport Properties are referred to by property names. These names
are lower-case strings whereby words are separated by hyphens. These are lower-case strings whereby words are separated by hyphens. These
names serve two purposes: names serve two purposes:
o Allow different components of a TAPS implementation to pass o Allow different components of a TAPS implementation to pass
Transport Properties, e.g., between a language frontend and a Transport Properties, e.g., between a language frontend and a
policy manager, or as a representation of properties retrieved policy manager, or as a representation of properties retrieved
from a file or other storage. from a file or other storage.
o Make code of different TAPS implementations look similar. o Make code of different TAPS implementations look similar.
Transport Property Names are hierarchically organized in the form Transport Property Names are hierarchically organized in the form
[<Namespace>.]<PropertyName>. [<Namespace>.]<PropertyName>.
o The Namespace part is empty for well known, generic properties, o The Namespace part is empty for well known, generic properties,
i.e., for properties defined by an RFC which are not protocol i.e., for properties that are not specific to a protocol and are
specific. defined in an RFC.
o Protocol Specific Properties must use the protocol acronym as o Protocol Specific Properties must use the protocol acronym as
Namespace, e.g., "tcp" for TCP specific Transport Properties. For Namespace, e.g., "tcp" for TCP specific Transport Properties. For
IETF protocols, property names under these namespaces SHOULD be IETF protocols, property names under these namespaces should be
defined in an RFC. defined in an RFC.
o Vendor or implementation specific properties must use a a string o Vendor or implementation specific properties must use a a string
identifying the vendor or implementation as Namespace. identifying the vendor or implementation as Namespace.
4.2.2. Transport Property Types 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
skipping to change at page 13, line 37 skipping to change at page 13, line 42
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.3. 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.
there is no interoperability benefit to tightly defining how the
interface be presented to application programmers in diverse There is no interoperability benefit in tightly defining how the
platforms, maintaining the "shape" of the abstract interface across interface is presented to application programmers across diverse
these platforms reduces the effort for programmers who learn the platforms. However, maintaining the "shape" of the abstract
transport services interface to apply their knowledge in multiple interface across these platforms reduces the effort for programmers
platforms. We therefore make the following recommendations: who learn the transport services interface to then apply their
knowledge across multiple platforms.
We therefore make the following recommendations:
o Actions, Events, and Errors in implementations of this interface o Actions, Events, and Errors in implementations of this interface
SHOULD carry the names given for them in the document, subject to SHOULD use the names given for them in the document, subject to
capitalization and punctuation conventions in the language of the capitalization, punctuation, and other typographic conventions in
implementation, unless the implementation itself uses different the language of the implementation, unless the implementation
names for substantially equivalent objects for networking by itself uses different names for substantially equivalent objects
convention. for networking by 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. Each
implementation is a non-operation, e.g. because transport interface SHOULD be implemented even when this will always result
protocols implementing a given Property are not available on the in no operation, e.g. there is no action when the API specifies a
platform. Property that is not available in a transport protocol implemented
on a specific platform.
o Implementations may use other representations for Transport o Implementations may use other representations for Transport
Property Names, e.g., by providing constants or static singleton Property Names, e.g., by providing constants, but should provide a
objects, but should provide a straight-forward mapping between straight-forward mapping between their representation and the
their representation and the property names specified here. 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
Section 5.1), the Selection Properties (see Section 5.2), any Section 5.1), the Selection Properties (see Section 5.2), any
preconfigured Connection Properties (Section 11.1), and the security preconfigured Connection Properties (Section 11.1), and the security
parameters (see Section 5.3): parameters (see Section 5.3):
Preconnection := NewPreconnection(LocalEndpoint, Preconnection := NewPreconnection(LocalEndpoint,
skipping to change at page 16, line 52 skipping to change at page 17, line 11
In addition, the pseudo-level "Default" can be used to reset the In addition, the pseudo-level "Default" can be used to reset the
property to the default level used by the implementation. This level property to the default level used by the implementation. This level
will never show up when queuing the value of a preference - the will never show up when queuing the value of a preference - the
effective preference must be returned instead. 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 that select paths take preference
over those which select protocols. For example, if an application over those that 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.
Selection, and Connection Properties, as well as defaults for Message Selection, and Connection Properties, as well as defaults for Message
Properties, can be added to a Preconnection to configure the Properties, can be added to a Preconnection to configure the
selection process, and to further configure the eventually selected selection process, and to further configure the eventually selected
protocol stack(s). They are collected into a TransportProperties protocol stack(s). They are collected into a TransportProperties
object to be passed into a Preconnection object: object to be passed into a Preconnection object:
TransportProperties := NewTransportProperties() TransportProperties := NewTransportProperties()
Individual properties are then added to the TransportProperties Individual properties are then added to the TransportProperties
Object: Object:
TransportProperties.Add(property, value) TransportProperties.Add(property, value)
Selection Properties can be added to a TransportProperties object As preference typed selection properties may be used quite
using special actions for each preference level i.e, frequently, implementations should provide additional convenience
"TransportProperties.Add(some_property, avoid)" is equivalent to functions as outlined in Appendix A.1. In addition, implementations
"TransportProperties.Avoid(some_property)": should provide a mechanism to create TransportProperties objects that
are preconfigured for common use cases as outlined in Appendix A.2.
TransportProperties.Require(property)
TransportProperties.Prefer(property)
TransportProperties.Ignore(property)
TransportProperties.Avoid(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 18, line 8 skipping to change at page 18, line 9
Section 11.1 provides a list of Connection Properties, while Section 11.1 provides a list of Connection Properties, while
Selection Properties are listed in the subsections below. Note that Selection Properties are listed in the subsections below. Note that
many properties are only considered during establishment, and can not many properties are only considered during establishment, and can not
be changed after a Connection is established; however, they can be be changed after a Connection is established; however, they can be
queried. Querying a Selection Property after establishment yields queried. Querying a Selection Property after establishment yields
the value Required for properties of the selected protocol and path, the value Required for properties of the selected protocol and path,
Avoid for properties avoided during selection, and Ignore for all Avoid for properties avoided during selection, and Ignore for all
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 defaults given for each property below
property below represent a configuration that can be implemented over represent a configuration that can be implemented over TCP. An
TCP. An alternate set of default Protocol Selection Properties would 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 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 default is to Require
Require Reliable Data Transfer. Reliable Data Transfer.
5.2.2. Preservation of Message Boundaries 5.2.2. Preservation of Message Boundaries
Name: preserve-msg-boundaries Name: preserve-msg-boundaries
This property specifies whether the application needs or prefers to This property specifies whether the application needs or prefers to
use a transport protocol that preserves message boundaries. The use a transport protocol that preserves message boundaries. The
recommended default is to Prefer Preservation of Message Boundaries. default is to Prefer Preservation of Message Boundaries.
5.2.3. Configure Per-Message Reliability 5.2.3. Configure Per-Message Reliability
Name: per-msg-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 default
recommended default is to Ignore this option. is to Ignore this option.
5.2.4. Preservation of Data Ordering 5.2.4. Preservation of Data Ordering
Name: preserve-order 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 Require Preservation of data ordering. default is to Require Preservation of data ordering.
5.2.5. 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 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 (i.e., during Connection establishment, potentially multiple times (i.e.,
multiple copies of the message data may be passed to the Remote multiple copies of the message data may be passed to the Remote
Endpoint). See also Section 7.4.4. The recommended default is to Endpoint). See also Section 7.4.4. The default is to Ignore this
Ignore this option. Note that disabling this property has no effect option. Note that disabling this property has no effect for
for protocols that are not connection-oriented and do not protect protocols that are not connection-oriented and do not protect against
against duplicated messages, e.g., UDP. duplicated messages, e.g., UDP.
5.2.6. Multistream Connections in Group 5.2.6. Multistream Connections in Group
Name: multistreaming 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 default
recommended default is to Prefer this option. is to Prefer this option.
5.2.7. Full Checksum Coverage on Sending 5.2.7. Full Checksum Coverage on Sending
Name: per-msg-checksum-len-send Name: per-msg-checksum-len-send
This property specifies whether the application desires protection This property specifies whether the application desires protection
against corruption for all data transmitted on this Connection. against corruption for all data transmitted on this Connection.
Disabling this property may enable to control checksum coverage later Disabling this property may enable to control checksum coverage later
(see Section 7.4.6). The recommended default is to Require this (see Section 7.4.6). The default is to Require this option.
option.
5.2.8. Full Checksum Coverage on Receiving 5.2.8. Full Checksum Coverage on Receiving
Name: per-msg-checksum-len-recv Name: per-msg-checksum-len-recv
This property specifies whether the application desires protection This property specifies whether the application desires protection
against corruption for all data received on this Connection. The against corruption for all data received on this Connection. The
recommended default is to Require this option. default is to Require this option.
5.2.9. Congestion control 5.2.9. Congestion control
Name: 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
skipping to change at page 20, line 19 skipping to change at page 20, line 18
congestion controlled. congestion controlled.
5.2.10. Interface Instance or Type 5.2.10. Interface Instance or Type
Name: interface Name: interface
Type: Set (Preference, Enumeration) 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". Note that marking a specific
interface as "Required" strictly limits path selection to a single
interface, and may often lead to less flexible and resilient
connection establishment.
In contrast to other Selection Properties, this property is a tuple In contrast to other Selection Properties, this property is a tuple
of an (Enumerated) interface identifier and a preference, and can of an (Enumerated) interface identifier and a preference, and can
either 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
path selection to a single interface, and leads to less flexible and
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,
there may be "Wi-Fi" and "Wired Ethernet" interface types available. there may be "Wi-Fi" and "Wired Ethernet" interface types available.
Implementations should provide all types that are supported on some An implementation should provide all types that are supported on the
system to all systems, in order to allow applications to write local system to all remote systems, to allow applications to be
generic code. For example, if a single implementation is used on written generically. For example, if a single implementation is used
both mobile devices and desktop devices, it should define the on both mobile devices and desktop devices, it should define the
"Cellular" interface type for both systems, since an application may "Cellular" interface type for both systems, since an application may
want to always "Prohibit Cellular". Note that marking a specific want to always "Prohibit Cellular". Note that marking a specific
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
skipping to change at page 22, line 5 skipping to change at page 21, line 50
5.2.12. Parallel Use of Multiple Paths 5.2.12. Parallel Use of Multiple Paths
Name: multipath Name: multipath
This property specifies whether an application considers it useful to This property specifies whether an application considers it useful to
transfer data across multiple paths between the same end hosts. transfer data across multiple paths between the same end hosts.
Generally, in most cases, this will improve performance (e.g., Generally, in most cases, this will improve performance (e.g.,
achieve greater throughput). One possible side-effect is increased achieve greater throughput). One possible side-effect is increased
jitter, which may be problematic for delay-sensitive applications. jitter, which may be problematic for delay-sensitive applications.
The recommended default is to Prefer this option. The recommended default is to Ignore this option.
5.2.13. Direction of communication 5.2.13. Direction of communication
Name: direction Name: direction
Type: Enumeration Type: Enumeration
This property specifies whether an application wants to use the This property specifies whether an application wants to use the
connection for sending and/or receiving data. Possible values are: connection for sending and/or receiving data. Possible values are:
Bidirectional (default): The connection must support sending and Bidirectional: The connection must support sending and receiving
receiving data data
Unidirectional send: The connection must support sending data Unidirectional send: The connection must support sending data, and
the application cannot use the connection to receive any data
Unidirectional receive: The connection must support receiving data Unidirectional receive: The connection must support receiving data,
and the application cannot use the connection to send any data
In case a unidirectional connection is requested, but unidirectional The default is bidirectional. Since unidirectional communication can
connections are not supported by the transport protocol, the system be supported by transports offering bidirectional communication,
should fall back to bidirectional transport. specifying unidirectional communication may cause a transport stack
that supports bidirectional communication to be selected.
5.2.14. Notification of excessive retransmissions 5.2.14. Notification of excessive retransmissions
Name: :retransmit-notify Name: :retransmit-notify
This property specifies whether an application considers it useful to This property specifies whether an application considers it useful to
be informed in case sent data was retransmitted more often than a be informed in case sent data was retransmitted more often than a
certain threshold. The recommended default is to Ignore this option. certain threshold. The default is to Ignore this option.
5.2.15. Notification of ICMP soft error message arrival 5.2.15. Notification of ICMP soft error message arrival
Name: :soft-error-notify Name: :soft-error-notify
This property specifies whether an application considers it useful to This property specifies whether an application considers it useful to
be informed when an ICMP error message arrives that does not force be informed when an ICMP error message arrives that does not force
termination of a connection. When set to true, received ICMP errors termination of a connection. When set to true, received ICMP errors
will be available as SoftErrors. Note that even if a protocol will be available as SoftErrors. Note that even if a protocol
supporting this property is selected, not all ICMP errors will supporting this property is selected, not all ICMP errors will
necessarily be delivered, so applications cannot rely on receiving necessarily be delivered, so applications cannot rely on receiving
them. The recommended default is to Ignore this option. them. The 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 23, line 34 skipping to change at page 23, line 34
operations and prove one's identity to the Remote Endpoint. operations and prove one's identity to the Remote Endpoint.
(Note, if private keys are not available, e.g., since they are (Note, if private keys are not available, e.g., since they are
stored in hardware security modules (HSMs), handshake callbacks stored in hardware security modules (HSMs), handshake callbacks
must be used. See below for details.) must be used. See below for details.)
SecurityParameters.AddIdentity(identity) SecurityParameters.AddIdentity(identity)
SecurityParameters.AddPrivateKey(privateKey, publicKey) SecurityParameters.AddPrivateKey(privateKey, publicKey)
o Supported algorithms: Used to restrict what parameters are used by o Supported algorithms: Used to restrict what parameters are used by
underlying transport security protocols. When not specified, underlying transport security protocols. When not specified,
these algorithms should default to known and safe defaults for the these algorithms should use known and safe defaults for the
system. Parameters include: ciphersuites, supported groups, and system. Parameters include: ciphersuites, supported groups, and
signature algorithms. signature algorithms.
SecurityParameters.AddSupportedGroup(secp256k1) SecurityParameters.AddSupportedGroup(secp256k1)
SecurityParameters.AddCiphersuite(TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256) SecurityParameters.AddCiphersuite(TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256)
SecurityParameters.AddSignatureAlgorithm(ed25519) SecurityParameters.AddSignatureAlgorithm(ed25519)
o Session cache management: Used to tune cache capacity, lifetime, o Session cache management: Used to tune cache capacity, lifetime,
re-use, and eviction policies, e.g., LRU or FIFO. Constants and re-use, and eviction policies, e.g., LRU or FIFO. Constants and
policies for these interfaces are implementation-specific. policies for these interfaces are implementation-specific.
skipping to change at page 25, line 38 skipping to change at page 25, line 38
is called: is called:
Connection -> Ready<> Connection -> Ready<>
The Ready Event occurs after Initiate has established a transport- The Ready Event occurs after Initiate has established a transport-
layer connection on at least one usable candidate Protocol Stack over layer connection on at least one usable candidate Protocol Stack over
at least one candidate Path. No Receive Events (see Section 8) will at least one candidate Path. No Receive Events (see Section 8) will
occur before the Ready Event for Connections established using occur before the Ready Event for Connections established using
Initiate. Initiate.
Connection -> InitiateError<> Connection -> InitiateError<reason?>
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, the application is prohibited from opening a Connection connections, the application is prohibited from opening a Connection
by the operating system, or the establishment attempt has timed out by the operating system, or the establishment attempt has timed out
for any other reason). for any other reason).
See also Section 7.7 to combine Connection establishment and See also Section 7.7 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 Action Passive open is supported by this interface through the Listen Action
and returns a Listener object: and returns a Listener object:
Listener := Preconnection.Listen() Listener := 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 returns constrain what Connections are accepted. The Listen() Action returns
skipping to change at page 26, line 37 skipping to change at page 26, line 37
After Stop() is called, the Listener can be disposed of. After Stop() is called, the Listener can be disposed of.
Listener -> ConnectionReceived<Connection> Listener -> ConnectionReceived<Connection>
The ConnectionReceived Event occurs when a Remote Endpoint has The ConnectionReceived Event occurs when a Remote Endpoint has
established a transport-layer connection to this Listener (for established a transport-layer connection to this Listener (for
Connection-oriented transport protocols), or when the first Message Connection-oriented transport protocols), or when the first Message
has been received from the Remote Endpoint (for Connectionless has been received from the Remote Endpoint (for Connectionless
protocols), causing a new Connection to be created. The resulting protocols), causing a new Connection to be created. The resulting
Connection is contained within the ConnectionReceived event, and is Connection is contained within the ConnectionReceived Event, and is
ready to use as soon as it is passed to the application via the ready to use as soon as it is passed to the application via the
event. event.
Listener -> ListenError<> Listener.SetNewConnectionLimit(value)
If the caller wants to rate-limit the number of inbound Connections
that will be delivered, it can set a cap using
SetNewConnectionLimit(). This mechanism allows a server to protect
itself from being drained of resources. Each time a new Connection
is delivered by the ConnectionReceived Event, the value is
automatically decremented. Once the value reaches zero, no further
Connections will be delivered until the caller sets the limit to a
higher value. By default, this value is Infinite. The caller is
also able to reset the value to Infinite at any point.
Listener -> ListenError<reason?>
A ListenError occurs either when the Properties of the Preconnection A ListenError occurs either when the Properties of the Preconnection
cannot be fulfilled for listening, when the Local Endpoint (or Remote cannot be fulfilled for listening, when the Local Endpoint (or Remote
Endpoint, if specified) cannot be resolved, or when the application Endpoint, if specified) cannot be resolved, or when the application
is prohibited from listening by policy. is prohibited from listening by policy.
Listener -> Stopped<> Listener -> Stopped<>
A Stopped event occurs after the Listener has stopped listening. A Stopped Event occurs after the Listener has stopped listening.
6.3. Peer-to-Peer Establishment: Rendezvous 6.3. Peer-to-Peer Establishment: Rendezvous
Simultaneous peer-to-peer Connection establishment is supported by Simultaneous peer-to-peer Connection establishment is supported by
the Rendezvous() Action: the Rendezvous() Action:
Preconnection.Rendezvous() Preconnection.Rendezvous()
The Preconnection Object must be specified with both a Local Endpoint The Preconnection Object must be specified with both a Local Endpoint
and a Remote Endpoint, and also the transport properties and security and a Remote Endpoint, and also the transport properties and security
skipping to change at page 27, line 37 skipping to change at page 27, line 48
Preconnection -> RendezvousDone<Connection> Preconnection -> RendezvousDone<Connection>
The RendezvousDone<> Event occurs when a Connection is established The RendezvousDone<> Event occurs when a Connection is established
with the Remote Endpoint. For Connection-oriented transports, this with the Remote Endpoint. For Connection-oriented transports, this
occurs when the transport-layer connection is established; for occurs when the transport-layer connection is established; for
Connectionless transports, it occurs when the first Message is Connectionless transports, it occurs when the first Message is
received from the Remote Endpoint. The resulting Connection is received from the Remote Endpoint. The resulting Connection is
contained within the RendezvousDone<> Event, and is ready to use as contained within the RendezvousDone<> Event, and is ready to use as
soon as it is passed to the application via the Event. soon as it is passed to the application via the Event.
Preconnection -> RendezvousError<messageContext, error> Preconnection -> RendezvousError<messageContext, reason?>
An RendezvousError occurs either when the Preconnection cannot be An RendezvousError occurs either when the Preconnection cannot be
fulfilled for listening, when the Local Endpoint or Remote Endpoint fulfilled for listening, when the Local Endpoint or Remote Endpoint
cannot be resolved, when no transport-layer connection can be cannot be resolved, when no transport-layer connection can be
established to the Remote Endpoint, or when the application is established to the Remote Endpoint, or when the application is
prohibited from rendezvous by policy. prohibited from rendezvous by policy.
When using some NAT traversal protocols, e.g., Interactive When using some NAT traversal protocols, e.g., Interactive
Connectivity Establishment (ICE) [RFC5245], it is expected that the Connectivity Establishment (ICE) [RFC5245], it is expected that the
Local Endpoint will be configured with some method of discovering NAT Local Endpoint will be configured with some method of discovering NAT
skipping to change at page 29, line 5 skipping to change at page 29, line 17
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<reason?>
The Protocol Property "Priority" operates on entangled Connections as The Protocol Property "Priority" operates on entangled Connections as
in Section 7.4.2: when allocating available network capacity among in Section 7.4.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
Priority values will be prioritized over sends on Connections with Priority values will be prioritized over sends on Connections with
lower Priority 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 Priority value, M is the maximum Priority 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 Priority setting is purely advisory, and no capacity. However, the Priority setting is purely advisory, and no
skipping to change at page 29, line 33 skipping to change at page 29, line 45
data. Data is sent as Messages, which allow the application to data. Data is sent as Messages, which allow the application to
communicate the boundaries of the data being transferred. By 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.3). Sending partial asynchronous, and deliver events (see Section 7.3). Sending partial
Messages for streaming large data is also supported (see Messages for streaming large data is also supported (see
Section 7.5). Section 7.5).
Messages are sent on a Connection using the Send action: Messages are sent on a Connection using the Send action:
messageContext := Connection.Send(messageData, messageContext?, endOfMessage?) Connection.Send(messageData, messageContext?, endOfMessage?)
where messageData is the data object to send. where messageData is the data object to send.
The optional messageContext parameter supports per-message properties The optional messageContext parameter supports per-message properties
and is described in Section 7.4. If provided, the Message Context and is described in Section 7.4. It can be used to identify send
object returned is identical to the one that was passed. events (see Section 7.3) related to a specific message or to inspect
meta-data related to the message sent (see Section 9).
The optional endOfMessage parameter supports partial sending and is The optional endOfMessage parameter supports partial sending and is
described in Section 7.5. described in Section 7.5.
The MessageContext returned by Send can be used to identify send
events (see Section 7.3) related to a specific message or to inspect
meta-data related to the message sent.
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 transferred as an array of bytes, and Properties. Message data is transferred as an array of bytes, 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. the array.
messageData := "hello".bytes() messageData := "hello".bytes()
Connection.Send(messageData) Connection.Send(messageData)
skipping to change at page 30, line 44 skipping to change at page 31, line 9
By using the "replyMessageContext", the transport system is informed By using the "replyMessageContext", the transport system is informed
that the message to be sent is a response and can map the response to that the message to be sent is a response and can map the response to
the same underlying transport connection or stream the request was the same underlying transport connection or stream the request was
received from. The concept of Message Contexts is described in received from. The concept of Message Contexts is described in
Section 9. Section 9.
7.3. Send Events 7.3. Send Events
Like all Actions in this interface, the Send Action is asynchronous. Like all Actions in this interface, the Send Action is asynchronous.
There are several Events that can be delivered in response to Sending There are several Events that can be delivered in response to Sending
a Message. a Message. Exactly one Event (Sent, Expired, or SendError) will be
delivered in reponse to each call to Send. These Events can be
implemented as callbacks that allow the specific Event to be
associated with the call to Send.
Note that if partial Sends are used (Section 7.5), there will still Note that if partial Sends are used (Section 7.5), there will still
be exactly one Send Event delivered for each call to Send. For be exactly one Send Event delivered for each call to Send. For
example, if a Message expired while two requests to Send data for example, if a Message expired while two requests to Send data for
that Message are outstanding, there will be two Expired events that Message are outstanding, there will be two Expired events
delivered. delivered.
7.3.1. Sent 7.3.1. Sent
Connection -> Sent<messageContext> Connection -> Sent<messageContext>
skipping to change at page 31, line 39 skipping to change at page 32, line 7
The Expired Event occurs when a previous Send Action expired before The Expired Event occurs when a previous Send Action expired before
completion; i.e. when the Message was not sent before its Lifetime completion; i.e. when the Message was not sent before its Lifetime
(see Section 7.4.1) expired. This is separate from SendError, as it (see Section 7.4.1) expired. This is separate from SendError, as it
is an expected behavior for partially reliable transports. The is an expected behavior for partially reliable transports. The
Expired Event contains an implementation-specific reference to the Expired Event contains an implementation-specific reference to the
Message to which it applies. Message to which it applies.
7.3.3. SendError 7.3.3. SendError
Connection -> SendError<messageContext> Connection -> SendError<messageContext, reason?>
A SendError occurs when a Message could not be sent due to an error A SendError occurs when a Message could not be sent due to an error
condition: an attempt to send a Message which is too large for the condition: an attempt to send a Message which is too large for the
system and Protocol Stack to handle, some failure of the underlying system and Protocol Stack to handle, some failure of the underlying
Protocol Stack, or a set of Message Properties not consistent with Protocol Stack, or a set of Message Properties not consistent with
the Connection's transport properties. The SendError contains an the Connection's transport properties. The SendError contains an
implementation-specific reference to the Message to which it applies. implementation-specific reference to the Message to which it applies.
7.4. Message Properties 7.4. Message Properties
skipping to change at page 32, line 50 skipping to change at page 33, line 20
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.4.1. Lifetime 7.4.1. Lifetime
Name: msg-lifetime Name: msg-lifetime
Type: Integer Type: Integer
Recommended default: infinite Default: infinite
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. This is a hint to the transport system - it is be (re-)transmitted. This is a hint to the transport system - it is
not guaranteed that a Message will not be sent when its Lifetime has not guaranteed that a Message will not be sent when its Lifetime has
expired. expired.
Setting a Message's Lifetime to infinite indicates that the Setting a Message's Lifetime to infinite indicates that the
application does not wish to apply a time constraint on the application does not wish to apply a time constraint on the
transmission of the Message, but it does not express a need for transmission of the Message, but it does not express a need for
reliable delivery; reliability is adjustable per Message via the reliable delivery; reliability is adjustable per Message via the
"Reliable Data Transfer (Message)" property (see Section 7.4.7). The "Reliable Data Transfer (Message)" property (see Section 7.4.7). The
type and units of Lifetime are implementation-specific. type and units of Lifetime are implementation-specific.
7.4.2. Priority 7.4.2. Priority
Name: msg-prio Name: msg-prio
Type: Integer (non-negative) Type: Integer (non-negative)
Recommended default: 100 Default: 100
This property represents a hierarchy of priorities. It can specify This property represents a hierarchy of priorities. It can specify
the priority of a Message, relative to other Messages sent over the the priority of a Message, relative to other Messages sent over the
same Connection. same Connection.
A Message with Priority 0 will yield to a Message with Priority 1, A Message with Priority 0 will yield to a Message with Priority 1,
which will yield to a Message with Priority 2, and so on. Priorities 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.
skipping to change at page 38, line 35 skipping to change at page 39, line 4
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 indicate 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 10.6 for more information on how this is Section 8.2.2 and Section 10 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
many bytes are available, or the Message is complete with fewer many bytes are available, or the Message is complete with fewer
bytes, or the system needs to free up memory. Applications should bytes, or the system needs to free up memory. Applications should
always check the length of the data delivered to the receive event always check the length of the data delivered to the receive event
and not assume it will be as long as minIncompleteLength in the case and not assume it will be as long as minIncompleteLength in the case
of shorter complete Messages or memory issues. of shorter complete Messages or memory issues.
The maxLength argument indicates the maximum size of a Message in The maxLength argument indicates the maximum size of a Message in
bytes the application is currently prepared to receive. The default bytes the application is currently prepared to receive. The default
skipping to change at page 39, line 38 skipping to change at page 40, line 5
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.
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.
The messageContext is provided to enable retrieving metadata about The messageContext is provided to enable retrieving metadata about
the message and referring to the message, e.g., to send replies and the message and referring to the message, e.g., to send replies and
map responses to their requests. See Section 9 for details. map responses to their requests. See Section 9 for details.
See Section 10.6 for handling Message framing in situations where the See Section 10 for handling Message framing in situations where the
Protocol Stack only provides a byte-stream transport. Protocol Stack only provides a byte-stream transport.
8.2.2. ReceivedPartial 8.2.2. ReceivedPartial
Connection -> ReceivedPartial<messageData, messageContext, endOfMessage> Connection -> ReceivedPartial<messageData, messageContext, endOfMessage>
If a complete Message cannot be delivered in one event, one part of If a complete Message cannot be delivered in one event, one part of
the Message may be delivered with a ReceivedPartial event. In order the Message may be delivered with a ReceivedPartial event. In order
to continue to receive more of the same Message, the application must to continue to receive more of the same Message, the application must
invoke Receive again. invoke Receive again.
skipping to change at page 40, line 17 skipping to change at page 40, line 33
If the minIncompleteLength in the Receive request was set to be If the minIncompleteLength in the Receive request was set to be
infinite (indicating a request to receive only complete Messages), infinite (indicating a request to receive only complete Messages),
the ReceivedPartial event may still be delivered if one of the the ReceivedPartial event may still be delivered if one of the
following conditions is true: following conditions is true:
o the underlying Protocol Stack supports message boundary o the underlying Protocol Stack supports message boundary
preservation, and the size of the Message is larger than the preservation, and the size of the Message is larger than the
buffers available for a single message; buffers available for a single message;
o the underlying Protocol Stack does not support message boundary o the underlying Protocol Stack does not support message boundary
preservation, and the Message Framer (see Section 10.6) cannot preservation, and the Message Framer (see Section 10) cannot
determine the end of the message using the buffer space it has determine the end of the message using the buffer space it has
available; or available; or
o the underlying Protocol Stack does not support message boundary o the underlying Protocol Stack does not support message boundary
preservation, and no Message Framer was supplied by the preservation, and no Message Framer was supplied by the
application application
Note that in the absence of message boundary preservation or a Note that in the absence of message boundary preservation or a
Message Framer, all bytes received on the Connection will be Message Framer, all bytes received on the Connection will be
represented as one large Message of indeterminate length. represented as one large Message of indeterminate length.
8.2.3. ReceiveError 8.2.3. ReceiveError
Connection -> ReceiveError<messageContext> Connection -> ReceiveError<messageContext, reason?>
A ReceiveError occurs when data is received by the underlying A ReceiveError occurs when data is received by the underlying
Protocol Stack that cannot be fully retrieved or parsed, or when some Protocol Stack that cannot be fully retrieved or parsed, or when some
other indication is received that reception has failed. Such other indication is received that reception has failed. Such
conditions that irrevocably lead to the termination of the Connection conditions that irrevocably lead to the termination of the Connection
are signaled using ConnectionError instead (see Section 12). are signaled using ConnectionError instead (see Section 12).
The ReceiveError event passes an optional associated MessageContext. The ReceiveError event passes an optional associated MessageContext.
This may indicate that a Message that was being partially received This may indicate that a Message that was being partially received
previously, but had not completed, encountered an error and will not previously, but had not completed, encountered an error and will not
skipping to change at page 41, line 50 skipping to change at page 42, line 19
a Message marked Final to know that the other endpoint is done a Message marked Final to know that the other endpoint is done
sending on a connection. sending on a connection.
Any calls to Receive once the Final Message has been delivered will Any calls to Receive once the Final Message has been delivered will
result in errors. result in errors.
9. Message Contexts 9. Message Contexts
Using the MessageContext object, the application can set and retrieve Using the MessageContext object, the application can set and retrieve
meta-data of the message, including Message Properties (see meta-data of the message, including Message Properties (see
Section 7.4) and framing meta-data (see Section 10.3). Therefore, a Section 7.4) and framing meta-data (see Section 10.2). Therefore, a
MessageContext object can be passed to the Send action and is retuned MessageContext object can be passed to the Send action and is retuned
by each Send and Receive related events. by each Send and Receive related events.
Message properties can be set and queried using the Message Context: Message properties can be set and queried using the Message Context:
MessageContext.add(scope?, parameter, value) MessageContext.add(scope?, parameter, value)
PropertyValue := MessageContext.get(scope?, property) PropertyValue := MessageContext.get(scope?, property)
To get or set Message Properties, the optional scope parameter is To get or set Message Properties, the optional scope parameter is
left empty, for framing meta-data, the framer is passed. left empty, for framing meta-data, the framer is passed.
skipping to change at page 42, line 31 skipping to change at page 42, line 49
as a reply to other messages, see Section 7.2 for details. If the as a reply to other messages, see Section 7.2 for details. If the
message received was send by the remote endpoint as a reply to an message received was send by the remote endpoint as a reply to an
earlier message and the transports provides this information, the earlier message and the transports provides this information, the
MessageContext of the original request can be accessed using the MessageContext of the original request can be accessed using the
Message Context of the reply: Message Context of the reply:
RequestMessageContext := MessageContext.GetOriginalRequest() RequestMessageContext := MessageContext.GetOriginalRequest()
10. Message Framers 10. Message Framers
Message Framers are pieces of code that define simple transformations Although most applications communicate over a network using well-
between application Message data and raw transport protocol data. A formed Messages, the boundaries and metadata of the Messages are
Framer can encapsulate or encode outbound Messages, and decapsulate often not directly communicated by the transport protocol itself.
or decode inbound data into Messages.
Message Framers allow message boundaries to be preserved when using a
Connection object, even when using byte-stream transports. This
facility is designed based on the fact that many of the current
application protocols evolved over TCP, which does not provide
message boundary preservation, and since many of these protocols
require message boundaries to function, each application layer
protocol has defined its own framing.
While many protocols can be represented as Message Framers, for the For example, HTTP applications send and receive HTTP messages over a
purposes of the Transport Services interface these are ways for byte-stream transport, requiring that the boundaries of HTTP messages
applications or application frameworks to define their own Message be parsed out from the stream of bytes.
parsing to be included within a Connection's Protocol Stack. As an
example, TLS can serve the purpose of framing data over TCP, but is
exposed as a protocol natively supported by the Transport Services
interface.
Most Message Framers fall into one of two categories: - Header- Message Framers allow extending a Connection's Protocol Stack to
prefixed record formats, such as a basic Type-Length-Value (TLV) define how to encapsulate or encode outbound Messages, and how to
structure - Delimeter-separated formats, such as HTTP/1.1. decapsulate or decode inbound data into Messages. Message Framers
allow message boundaries to be preserved when using a Connection
object, even when using byte-stream transports. This facility is
designed based on the fact that many of the current application
protocols evolved over TCP, which does not provide message boundary
preservation, and since many of these protocols require message
boundaries to function, each application layer protocol has defined
its own framing.
Note that while Message Framers add the most value when placed above Note that while Message Framers add the most value when placed above
a protocol that otherwise does not preserve message boundaries, they a protocol that otherwise does not preserve message boundaries, they
can also be used with datagram- or message-based protocols. In these can also be used with datagram- or message-based protocols. In these
cases, they add an additional transformation to further encode or cases, they add an additional transformation to further encode or
encapsulate, and can potentially support packing multiple encapsulate, and can potentially support packing multiple
application-layer Messages into individual transport datagrams. application-layer Messages into individual transport datagrams.
10.1. Defining Message Framers The API to implement a Message Framer can vary depending on the
implementation; guidance on implementing Message Framers can be found
A Message Framer is primarily defined by the set of code that handles in [I-D.ietf-taps-impl].
events for a framer implementation, specifically how it handles
inbound and outbound data parsing.
Applications can instantiate a Message Framer upon which they will
receive framing events, or use a Message Framer defined by another
library.
framer := NewMessageFramer()
Message Framer objects will deliver events to code that is written
either as part of the application or a helper library. This piece of
code will be referred to as the "framer implementation".
10.2. Adding Message Framers to Connections 10.1. Adding Message Framers to Connections
The Message Framer object can be added to one or more Preconnections The Message Framer object can be added to one or more Preconnections
to run on top of transport protocols. Multiple Framers may be added. to run on top of transport protocols. Multiple Framers may be added.
If multiple Framers are added, the last one added runs first when If multiple Framers are added, the last one added runs first when
framing outbound messages, and last when parsing inbound data. framing outbound messages, and last when parsing inbound data.
Preconnection.AddFramer(framer) The following example adds a basic HTTP Message Framer to a
Preconnection:
Framers have the ability to also dynamically modify Protocol Stacks, framer := NewHTTPMessageFramer()
as described in Section 10.4. Preconnection.AddFramer(framer)
10.3. Framing Meta-Data 10.2. Framing Meta-Data
When sending Messages, applications can add specific Message values When sending Messages, applications can add specific Message values
to a MessageContext (Section 9) that is intended for a Framer. This to a MessageContext (Section 9) that is intended for a Framer. This
can be used, for example, to set the type of a Message for a TLV can be used, for example, to set the type of a Message for a TLV
format. The namespace of values is custom for each unique Message format. The namespace of values is custom for each unique Message
Framer. Framer.
messageContext := NewMessageContext() messageContext := NewMessageContext()
messageContext.add(framer, key, value) messageContext.add(framer, key, value)
Connection.Send(messageData, messageContext) Connection.Send(messageData, messageContext)
When an application receives a MessageContext in a Receive event, it When an application receives a MessageContext in a Receive event, it
can also look to see if a value was set by a specific Message Framer. can also look to see if a value was set by a specific Message Framer.
messageContext.get(framer, key) -> value messageContext.get(framer, key) -> value
10.4. Message Framer Lifetime For example, if an HTTP Message Framer is used, the values could
correspond to HTTP headers:
When a Connection establishment attempt begins, an event is delivered
to notify the framer implementation that a new Connection is being
created. Similarly, a stop event is delivered when a Connection is
being torn down. The framer implementation can use the Connection
object to look up specific properties of the Connection or the
network being used that may influence how to frame Messages.
MessageFramer -> Start(Connection)
MessageFramer -> Stop(Connection)
When Message Framer generates a "Start" event, the framer
implementation has the opportunity to start writing some data prior
to the Connection delivering its "Ready" event. This allows the
implementation to communicate control data to the remote endpoint
that can be used to parse Messages.
MessageFramer.MakeConnectionReady(Connection)
At any time if the implementation encounters a fatal error, it can
also cause the Connection to fail and provide an error.
MessageFramer.FailConnection(Connection, Error)
Before an implementation marks a Message Framer as ready, it can also
dynamically add a protocol or framer above it in the stack. This
allows protocols like STARTTLS, that need to add TLS conditionally,
to modify the Protocol Stack based on a handshake result.
otherFramer := NewMessageFramer()
MessageFramer.PrependFramer(Connection, otherFramer)
10.5. Sender-side Message Framing
Message Framers generate an event whenever a Connection sends a new
Message.
MessageFramer -> NewSentMessage<Connection, MessageData, MessageContext, IsEndOfMessage>
Upon receiving this event, a framer implementation is responsible for
performing any necessary transformations and sending the resulting
data to the next protocol. Implementations SHOULD ensure that there
is a way to pass the original data through without copying to improve
performance.
MessageFramer.Send(Connection, Data)
To provide an example, a simple protocol that adds a length as a
header would receive the "NewSentMessage" event, create a data
representation of the length of the Message data, and then send a
block of data that is the concatenation of the length header and the
original Message data.
10.6. Receiver-side Message Framing
In order to parse an received flow of data into Messages, the Message
Framer notifies the framer implementation whenever new data is
available to parse.
MessageFramer -> HandleReceivedData<Connection>
Upon receiving this event, the framer implementation can inspect the
inbound data. The data is parsed from a particular cursor
representing the unprocessed data. The application requests a
specific amount of data it needs to have available in order to parse.
If the data is not available, the parse fails.
MessageFramer.Parse(Connection, MinimumIncompleteLength, MaximumLength) -> (Data, MessageContext, IsEndOfMessage)
The framer implementation can directly advance the receive cursor
once it has parsed data to effectively discard data (for example,
discard a header once the content has been parsed).
To deliver a Message to the application, the framer implementation
can either directly deliever data that it has allocated, or deliver a
range of data directly from the underlying transport and
simulatenously advance the receive cursor.
MessageFramer.AdvanceReceiveCursor(Connection, Length)
MessageFramer.DeliverAndAdvanceReceiveCursor(Connection, MessageContext, Length, IsEndOfMessage)
MessageFramer.Deliver(Connection, MessageContext, Data, IsEndOfMessage)
Note that "MessageFramer.DeliverAndAdvanceReceiveCursor" allows the
framer implementation to earmark bytes as part of a Message even
before they are received by the transport. This allows the delivery
of very large Messages without requiring the implementation to
directly inspect all of the bytes.
To provide an example, a simple protocol that parses a length as a httpFramer := NewHTTPMessageFramer()
header value would receive the "HandleReceivedData" event, and call ...
"Parse" with a minimum and maximum set to the length of the header messageContext := NewMessageContext()
field. Once the parse succeeded, it would call messageContext.add(httpFramer, "accept", "text/html")
"AdvanceReceiveCursor" with the length of the header field, and then
call "DeliverAndAdvanceReceiveCursor" with the length of the body
that was parsed from the header, marking the new Message as complete.
11. Managing Connections 11. Managing Connections
During pre-establishment and after establishment, connections can be During pre-establishment and after establishment, connections can be
configured and queried using Connection Properties, and asynchronous configured and queried using Connection Properties, and asynchronous
information may be available about the state of the connection via information may be available about the state of the connection via
Soft Errors. 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
skipping to change at page 53, line 32 skipping to change at page 51, line 41
Abort terminates a Connection without delivering remaining data: Abort terminates a Connection without delivering remaining data:
Connection.Abort() Connection.Abort()
A ConnectionError informs the application that data to could not be A ConnectionError informs the application that data to could not be
delivered after a timeout, or the other side has aborted the delivered after a timeout, or the other side has aborted the
Connection; however, there is no guarantee that an Abort will indeed Connection; however, there is no guarantee that an Abort will indeed
be signaled. be signaled.
Connection -> ConnectionError<> Connection -> ConnectionError<reason?>
13. Connection State and Ordering of Operations and Events 13. 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:
skipping to change at page 55, line 18 skipping to change at page 53, line 27
research and innovation programme under grant agreements No. 644334 research and innovation programme under grant agreements No. 644334
(NEAT) and No. 688421 (MAMI). (NEAT) and No. 688421 (MAMI).
This work has been supported by Leibniz Prize project funds of DFG - This work has been supported by Leibniz Prize project funds of DFG -
German Research Foundation: Gottfried Wilhelm Leibniz-Preis 2011 (FKZ German Research Foundation: Gottfried Wilhelm Leibniz-Preis 2011 (FKZ
FE 570/4-1). FE 570/4-1).
This work has been supported by the UK Engineering and Physical This work has been supported by the UK Engineering and Physical
Sciences Research Council under grant EP/R04144X/1. Sciences Research Council under grant EP/R04144X/1.
This work has been supported by the Research Council of Norway under
its "Toppforsk" programme through the "OCARINA" project.
Thanks to Stuart Cheshire, Josh Graessley, David Schinazi, and Eric Thanks to Stuart Cheshire, Josh Graessley, David Schinazi, and Eric
Kinnear for their implementation and design efforts, including Happy Kinnear for their implementation and design efforts, including Happy
Eyeballs, that heavily influenced this work. Thanks to Laurent Chuat Eyeballs, that heavily influenced this work. Thanks to Laurent Chuat
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.
17. References 17. References
17.1. Normative References 17.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-03 (work in Transport Services", draft-ietf-taps-arch-04 (work in
progress), March 2019. progress), July 2019.
[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.
[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>.
[RFC8303] Welzl, M., Tuexen, M., and N. Khademi, "On the Usage of
Transport Features Provided by IETF Transport Protocols",
RFC 8303, DOI 10.17487/RFC8303, February 2018,
<https://www.rfc-editor.org/info/rfc8303>.
[RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol
Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018,
<https://www.rfc-editor.org/info/rfc8446>. <https://www.rfc-editor.org/info/rfc8446>.
17.2. Informative References 17.2. Informative References
[I-D.ietf-taps-impl]
Brunstrom, A., Pauly, T., Enghardt, T., Grinnemo, K.,
Jones, T., Tiesel, P., Perkins, C., and M. Welzl,
"Implementing Interfaces to Transport Services", draft-
ietf-taps-impl-04 (work in progress), July 2019.
[I-D.ietf-taps-minset] [I-D.ietf-taps-minset]
Welzl, M. and S. Gjessing, "A Minimal Set of Transport Welzl, M. and S. Gjessing, "A Minimal Set of Transport
Services for End Systems", draft-ietf-taps-minset-11 (work Services for End Systems", draft-ietf-taps-minset-11 (work
in progress), September 2018. in progress), September 2018.
[I-D.ietf-taps-transport-security] [I-D.ietf-taps-transport-security]
Wood, C., Enghardt, T., Pauly, T., Perkins, C., and K. Wood, C., Enghardt, T., Pauly, T., Perkins, C., and K.
Rose, "A Survey of Transport Security Protocols", draft- Rose, "A Survey of Transport Security Protocols", draft-
ietf-taps-transport-security-06 (work in progress), March ietf-taps-transport-security-09 (work in progress),
2019. September 2019.
[LE-PHB] Bless, R., "A Lower Effort Per-Hop Behavior (LE PHB) for [LE-PHB] Bless, R., "A Lower Effort Per-Hop Behavior (LE PHB) for
Differentiated Services", draft-ietf-tsvwg-le-phb-10 (work Differentiated Services", draft-ietf-tsvwg-le-phb-10 (work
in progress), March 2019. in progress), March 2019.
[PROTOCOL-WARS]
Computer History Museum, ., "Protocol Wars (Revolution -
The First 2000 Years of Computing)", 2019,
<https://www.computerhistory.org/revolution/
networking/19/376>.
[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 57, line 46 skipping to change at page 56, line 30
Congestion Control Mechanisms", RFC 8095, Congestion Control Mechanisms", RFC 8095,
DOI 10.17487/RFC8095, March 2017, DOI 10.17487/RFC8095, March 2017,
<https://www.rfc-editor.org/info/rfc8095>. <https://www.rfc-editor.org/info/rfc8095>.
[RFC8260] Stewart, R., Tuexen, M., Loreto, S., and R. Seggelmann, [RFC8260] 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", RFC 8260, Stream Control Transmission Protocol", RFC 8260,
DOI 10.17487/RFC8260, November 2017, DOI 10.17487/RFC8260, November 2017,
<https://www.rfc-editor.org/info/rfc8260>. <https://www.rfc-editor.org/info/rfc8260>.
Appendix A. Additional Properties Appendix A. Convenience Functions
A.1. Adding Preference Properties
As Selection Properties of type Preference will be added to a
TransportProperties object quite frequently, implementations should
provide special actions for adding each preference level i.e,
"TransportProperties.Add(some_property, avoid)" is equivalent to
"TransportProperties.Avoid(some_property)":
TransportProperties.Require(property)
TransportProperties.Prefer(property)
TransportProperties.Ignore(property)
TransportProperties.Avoid(property)
TransportProperties.Prohibit(property)
TransportProperties.Default(property)
A.2. Transport Property Profiles
To ease the use of the interface specified by this document,
implementations should provide a mechanism to create Transport
Property objects (see Section 5.2) that are pre-configured with
frequently used sets of properties. Implementations should at least
short-hands to specify the following property profiles:
A.2.1. reliable-inorder-stream
This profile provides reliable, in-order transport service with
congestion control. An example of a protocol that provides this
service is TCP. It should consist of the following properties:
+-------------------------+---------+
| Property | Value |
+-------------------------+---------+
| reliability | require |
| | |
| preserve-order | require |
| | |
| congestion-control | require |
| | |
| preserve-msg-boundaries | ignore |
+-------------------------+---------+
A.2.2. reliable-message
This profile provides message-preserving, reliable, in-order
transport service with congestion control. An example of a protocol
that provides this service is SCTP. It should consist of the
following properties:
+-------------------------+---------+
| Property | Value |
+-------------------------+---------+
| reliability | require |
| | |
| preserve-order | require |
| | |
| congestion-control | require |
| | |
| preserve-msg-boundaries | require |
+-------------------------+---------+
A.2.3. unreliable-datagram
This profile provides unreliable datagram transport service. An
example of a protocol that provides this service is UDP. It should
consist of the following properties:
+-------------------------+---------+
| Property | Value |
+-------------------------+---------+
| reliability | ignore |
| | |
| preserve-order | ignore |
| | |
| congestion-control | ignore |
| | |
| preserve-msg-boundaries | require |
| | |
| idempotent | true |
+-------------------------+---------+
Applications that choose this Transport Property Profile for latency
reasons should also consider setting the Capacity Profile Property,
see Section 11.1.10 accordingly and my benefit from controlling
checksum coverage, see Section 5.2.7 and Section 5.2.8.
Appendix B. Additional Properties
The interface specified by this document represents the minimal The interface specified by this document represents the minimal
common interface to an endpoint in the transport services common interface to an endpoint in the transport services
architecture [I-D.ietf-taps-arch], based upon that architecture and architecture [I-D.ietf-taps-arch], based upon that architecture and
on the minimal set of transport service features elaborated in on the minimal set of transport service features elaborated in
[I-D.ietf-taps-minset]. However, the interface has been designed [I-D.ietf-taps-minset]. However, the interface has been designed
with extension points to allow the implementation of features beyond with extension points to allow the implementation of features beyond
those in the minimal common interface: Protocol Selection Properties, those in the minimal common interface: Protocol Selection Properties,
Path Selection Properties, and Message Properties are open sets. Path Selection Properties, and Message Properties are open sets.
Implementations of the interface are free to extend these sets to Implementations of the interface are free to extend these sets to
skipping to change at page 58, line 19 skipping to change at page 58, line 46
them. them.
This appendix enumerates a few additional properties that could be This appendix enumerates a few additional properties that could be
used to enhance transport protocol and/or path selection, or the used to enhance transport protocol and/or path selection, or the
transmission of messages given a Protocol Stack that implements them. transmission of messages given a Protocol Stack that implements them.
These are not part of the interface, and may be removed from the These are not part of the interface, and may be removed from the
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 B.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 11.1, and addition to those specified in Section 5.2, Section 11.1, and
Section 7.4. Section 7.4.
A.1.1. Cost Preferences B.1.1. Cost Preferences
[EDITOR'S NOTE: At IETF 103, opinions were that this property should [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 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 level". If / when moving it to the main text, note that this is
meant to be applicable to a Preconnection or a Message.] meant to be applicable to a Preconnection or a Message.]
Name: cost-preferences Name: cost-preferences
Type: Enumeration Type: Enumeration
skipping to change at page 59, line 7 skipping to change at page 59, line 35
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".
Appendix B. Sample API definition in Go Appendix C. Sample API definition in Go
This document defines an abstract interface. To illustrate how this This document defines an abstract interface. To illustrate how this
would map concretely into a programming language, an API interface would map concretely into a programming language, an API interface
definition in Go is available online at https://github.com/mami- definition in Go is available online at https://github.com/mami-
project/postsocket. Documentation for this API - an illustration of project/postsocket. Documentation for this API - an illustration of
the documentation an application developer would see for an instance the documentation an application developer would see for an instance
of this interface - is available online at of this interface - is available online at
https://godoc.org/github.com/mami-project/postsocket. This API https://godoc.org/github.com/mami-project/postsocket. This API
definition will be kept largely in sync with the development of this definition will be kept largely in sync with the development of this
abstract interface definition. abstract interface definition.
Appendix C. Relationship to the Minimal Set of Transport Services for Appendix D. Relationship to the Minimal Set of Transport Services for
End Systems End Systems
[I-D.ietf-taps-minset] identifies a minimal set of transport services [I-D.ietf-taps-minset] identifies a minimal set of transport services
that end systems should offer. These services make all transport that end systems should offer. These services make all non-security-
features offered by TCP, MPTCP, UDP, UDP-Lite, SCTP and LEDBAT related transport features of TCP, MPTCP, UDP, UDP-Lite, SCTP and
available that 1) require interaction with the application, and 2) do LEDBAT available that 1) require interaction with the application,
not get in the way of a possible implementation over TCP or, with and 2) do not get in the way of a possible implementation over TCP
limitations, UDP. The following text explains how this minimal set (or, with limitations, UDP). The following text explains how this
is reflected in the present API. For brevity, this uses the list in minimal set is reflected in the present API. For brevity, it is
Section 4.1 of [I-D.ietf-taps-minset], updated according to the based on the list in Section 4.1 of [I-D.ietf-taps-minset], updated
discussion in Section 5 of [I-D.ietf-taps-minset]. according to the discussion in Section 5 of [I-D.ietf-taps-minset].
This list is a subset of the transport features in Appendix A of
[I-D.ietf-taps-minset], which refers to the primitives in "pass 2"
(Section 4) of [RFC8303] for further details on the implementation
with TCP, MPTCP, UDP, UDP-Lite, SCTP and LEDBAT.
[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.] changing.]
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: "timeout" parameter of "Initiate" or
"Timeout for aborting Connection Establishment" Property, using a "InitiateWithSend" Action.
time value.
o Disable MPTCP: o Disable MPTCP: "Parallel Use of Multiple Paths" Property.
"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: "InitiateWithSend" Action.
"InitiateWithSend" Action.
o Hand over a message to reliably transfer during connection
establishment:
"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
"Timeout for aborting Connection" property, using a time value. time value.
o Timeout event when data could not be delivered for too long: o Timeout event when data could not be delivered for too long:
"ConnectionError" Event. "ConnectionError" Event.
o Suggest timeout to the peer: o Suggest timeout to the peer: "TCP-specific Property: User
TCP-specific Property: User Timeout. Timeout".
o Notification of Excessive Retransmissions (early warning below o Notification of Excessive Retransmissions (early warning below
abortion threshold): abortion threshold): "Notification of excessive retransmissions"
"Notification of excessive retransmissions" property. property.
o Notification of ICMP error message arrival: o Notification of ICMP error message arrival: "Notification of ICMP
"Notification of ICMP soft error message arrival" property. 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: "Priority
"Priority (Connection)" property. (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
"Corruption Protection Length" property (value 0 to disable). and "Full Checksum Coverage on Sending" property.
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
"Required minimum coverage of the checksum for receiving" property Corruption Protection Coverage for Receiving" property and "Full
(value 0 to disable). Checksum Coverage on Receiving" property.
o "Specify DF" field and "Request not to bundle messages:" o "Specify DF" field and "Request not to bundle messages:" The
The "Singular Transmission" Message property combines both of "Singular Transmission" Message property combines both of these
these requests, i.e. if a request not to bundle messages is made, requests, i.e. if a request not to bundle messages is made, this
this also turns off DF in case of protocols that allow this (only also turns off DF in case of protocols that allow this (only UDP
UDP and UDP-Lite, which cannot bundle messages anyway). and UDP-Lite, which cannot bundle messages anyway).
o Get max. transport-message size that may be sent using a non- o Get max. transport-message size that may be sent using a non-
fragmented IP packet from the configured interface: fragmented IP packet from the configured interface: "Maximum
"Maximum Message size before fragmentation or segmentation" Message Size Before Fragmentation or Segmentation" property.
property.
o Get max. transport-message size that may be received from the o Get max. transport-message size that may be received from the
configured interface: configured interface: "Maximum Message Size on Receive" property.
"Maximum Message size on receive" property.
o Obtain ECN field: o Obtain ECN field: "ECN" is a defined read-only Message Property of
"ECN" is a defined metadata value as part of the Message Receive the MessageContext object.
Context.
o "Specify DSCP field", "Disable Nagle algorithm", "Enable and o "Specify DSCP field", "Disable Nagle algorithm", "Enable and
configure a 'Low Extra Delay Background Transfer'": configure a 'Low Extra Delay Background Transfer'": As suggested
As suggested in Section 5.5 of [I-D.ietf-taps-minset], these in Section 5.5 of [I-D.ietf-taps-minset], these transport features
transport features are collectively offered via the "Capacity are collectively offered via the "Capacity Profile" property.
profile" property.
o Close after reliably delivering all remaining data, causing an o Close after reliably delivering all remaining data, causing an
event informing the application on the other side: event informing the application on the other side: This is offered
This is offered by the "Close" Action with slightly changed by the "Close" Action with slightly changed semantics in line with
semantics in line with the discussion in Section 5.2 of the discussion in Section 5.2 of [I-D.ietf-taps-minset].
[I-D.ietf-taps-minset].
o "Abort without delivering remaining data, causing an event o "Abort without delivering remaining data, causing an event
informing the application on the other side" and "Abort without informing the application on the other side" and "Abort without
delivering remaining data, not causing an event informing the delivering remaining data, not causing an event informing the
application on the other side": application on the other side": This is offered by the "Abort"
This is offered by the "Abort" action without promising that this action without promising that this is signaled to the other side.
is signaled to the other side. If it is, a "ConnectionError" If it is, a "ConnectionError" Event will fire at the peer.
Event will fire at the peer.
o "Reliably transfer data, with congestion control", "Reliably o "Reliably transfer data, with congestion control", "Reliably
transfer a message, with congestion control" and "Unreliably transfer a message, with congestion control" and "Unreliably
transfer a message": transfer a message": Data is tranferred via the "Send" action.
Reliability is controlled via the "Reliable Data Transfer Reliability is controlled via the "Reliable Data Transfer
(Message)" Message property. Transmitting data without delimiters (Message)" Message property. Transmitting data as a message or
is done by not using a Framer. The choice of congestion control without delimiters is controlled via Message Framers. The choice
is provided via the "Congestion control" property. of congestion control is provided via the "Congestion control"
property.
o Configurable Message Reliability: o Configurable Message Reliability: The "Lifetime" Message Property
The "Lifetime" Message Property implements a time-based way to implements a time-based way to configure message reliability.
configure message reliability.
o "Ordered message delivery (potentially slower than unordered)" and o "Ordered message delivery (potentially slower than unordered)" and
"Unordered message delivery (potentially faster than ordered)": "Unordered message delivery (potentially faster than ordered)":
The two transport features are controlled via the Message property The two transport features are controlled via the Message Property
"Ordered". "Ordered".
o Request not to delay the acknowledgement (SACK) of a message: o Request not to delay the acknowledgement (SACK) of a message:
Should the protocol support it, this is one of the transport Should the protocol support it, this is one of the transport
features the transport system can use when an application uses the features the transport system can use when an application uses the
Capacity Profile Property with value "Low Latency/Interactive". "Capacity Profile" Property with value "Low Latency/Interactive".
o Receive data (with no message delimiting): o Receive data (with no message delimiting): "Received" Event
"Received" Event without using a Message Framer. without using a Message Framer.
o Receive a message: o Receive a message: "Received" Event, using Message Framers.
"Received" Event. Section 5.1 of [I-D.ietf-taps-minset] discusses
how messages can be obtained from a bytestream in case of
implementation over TCP. Here, this is dealt with by Message
Framers.
o Information about partial message arrival: o Information about partial message arrival: "ReceivedPartial"
"ReceivedPartial" Event. 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)
Google Google
Gustav-Gull-Platz 1 Gustav-Gull-Platz 1
8004 Zurich 8004 Zurich
Switzerland Switzerland
Email: ietf@trammell.ch Email: ietf@trammell.ch
 End of changes. 143 change blocks. 
442 lines changed or deleted 444 lines changed or added

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