idnits 2.17.1 draft-ietf-taps-interface-04.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** There are 6 instances of too long lines in the document, the longest one being 41 characters in excess of 72. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (July 08, 2019) is 1752 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Unused Reference: 'I-D.ietf-tsvwg-rtcweb-qos' is defined on line 2582, but no explicit reference was found in the text == Outdated reference: A later version (-19) exists of draft-ietf-taps-arch-03 == Outdated reference: A later version (-12) exists of draft-ietf-taps-transport-security-06 -- Obsolete informational reference (is this intentional?): RFC 793 (Obsoleted by RFC 9293) -- Obsolete informational reference (is this intentional?): RFC 5245 (Obsoleted by RFC 8445, RFC 8839) Summary: 1 error (**), 0 flaws (~~), 4 warnings (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 TAPS Working Group B. Trammell, Ed. 3 Internet-Draft Google 4 Intended status: Standards Track M. Welzl, Ed. 5 Expires: January 9, 2020 University of Oslo 6 T. Enghardt 7 TU Berlin 8 G. Fairhurst 9 University of Aberdeen 10 M. Kuehlewind 11 ETH Zurich 12 C. Perkins 13 University of Glasgow 14 P. Tiesel 15 TU Berlin 16 C. Wood 17 T. Pauly 18 Apple Inc. 19 July 08, 2019 21 An Abstract Application Layer Interface to Transport Services 22 draft-ietf-taps-interface-04 24 Abstract 26 This document describes an abstract programming interface to the 27 transport layer, following the Transport Services Architecture. It 28 supports the asynchronous, atomic transmission of messages over 29 transport protocols and network paths dynamically selected at 30 runtime. It is intended to replace the traditional BSD sockets API 31 as the lowest common denominator interface to the transport layer, in 32 an environment where endpoints have multiple interfaces and potential 33 transport protocols to select from. 35 Status of This Memo 37 This Internet-Draft is submitted in full conformance with the 38 provisions of BCP 78 and BCP 79. 40 Internet-Drafts are working documents of the Internet Engineering 41 Task Force (IETF). Note that other groups may also distribute 42 working documents as Internet-Drafts. The list of current Internet- 43 Drafts is at https://datatracker.ietf.org/drafts/current/. 45 Internet-Drafts are draft documents valid for a maximum of six months 46 and may be updated, replaced, or obsoleted by other documents at any 47 time. It is inappropriate to use Internet-Drafts as reference 48 material or to cite them other than as "work in progress." 49 This Internet-Draft will expire on January 9, 2020. 51 Copyright Notice 53 Copyright (c) 2019 IETF Trust and the persons identified as the 54 document authors. All rights reserved. 56 This document is subject to BCP 78 and the IETF Trust's Legal 57 Provisions Relating to IETF Documents 58 (https://trustee.ietf.org/license-info) in effect on the date of 59 publication of this document. Please review these documents 60 carefully, as they describe your rights and restrictions with respect 61 to this document. Code Components extracted from this document must 62 include Simplified BSD License text as described in Section 4.e of 63 the Trust Legal Provisions and are provided without warranty as 64 described in the Simplified BSD License. 66 Table of Contents 68 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4 69 2. Terminology and Notation . . . . . . . . . . . . . . . . . . 5 70 3. Interface Design Principles . . . . . . . . . . . . . . . . . 6 71 4. API Summary . . . . . . . . . . . . . . . . . . . . . . . . . 7 72 4.1. Usage Examples . . . . . . . . . . . . . . . . . . . . . 8 73 4.1.1. Server Example . . . . . . . . . . . . . . . . . . . 8 74 4.1.2. Client Example . . . . . . . . . . . . . . . . . . . 9 75 4.1.3. Peer Example . . . . . . . . . . . . . . . . . . . . 10 76 4.2. Transport Properties . . . . . . . . . . . . . . . . . . 11 77 4.2.1. Transport Property Names . . . . . . . . . . . . . . 12 78 4.2.2. Transport Property Types . . . . . . . . . . . . . . 13 79 4.3. Scope of the Interface Definition . . . . . . . . . . . . 13 80 5. Pre-Establishment Phase . . . . . . . . . . . . . . . . . . . 14 81 5.1. Specifying Endpoints . . . . . . . . . . . . . . . . . . 14 82 5.2. Specifying Transport Properties . . . . . . . . . . . . . 16 83 5.2.1. Reliable Data Transfer (Connection) . . . . . . . . . 18 84 5.2.2. Preservation of Message Boundaries . . . . . . . . . 18 85 5.2.3. Configure Per-Message Reliability . . . . . . . . . . 18 86 5.2.4. Preservation of Data Ordering . . . . . . . . . . . . 18 87 5.2.5. Use 0-RTT Session Establishment with an Idempotent 88 Message . . . . . . . . . . . . . . . . . . . . . . . 19 89 5.2.6. Multistream Connections in Group . . . . . . . . . . 19 90 5.2.7. Full Checksum Coverage on Sending . . . . . . . . . . 19 91 5.2.8. Full Checksum Coverage on Receiving . . . . . . . . . 19 92 5.2.9. Congestion control . . . . . . . . . . . . . . . . . 19 93 5.2.10. Interface Instance or Type . . . . . . . . . . . . . 20 94 5.2.11. Provisioning Domain Instance or Type . . . . . . . . 21 95 5.2.12. Parallel Use of Multiple Paths . . . . . . . . . . . 21 96 5.2.13. Direction of communication . . . . . . . . . . . . . 22 97 5.2.14. Notification of excessive retransmissions . . . . . . 22 98 5.2.15. Notification of ICMP soft error message arrival . . . 22 99 5.3. Specifying Security Parameters and Callbacks . . . . . . 22 100 5.3.1. Pre-Connection Parameters . . . . . . . . . . . . . . 23 101 5.3.2. Connection Establishment Callbacks . . . . . . . . . 24 102 6. Establishing Connections . . . . . . . . . . . . . . . . . . 24 103 6.1. Active Open: Initiate . . . . . . . . . . . . . . . . . . 24 104 6.2. Passive Open: Listen . . . . . . . . . . . . . . . . . . 26 105 6.3. Peer-to-Peer Establishment: Rendezvous . . . . . . . . . 27 106 6.4. Connection Groups . . . . . . . . . . . . . . . . . . . . 28 107 7. Sending Data . . . . . . . . . . . . . . . . . . . . . . . . 29 108 7.1. Basic Sending . . . . . . . . . . . . . . . . . . . . . . 29 109 7.2. Sending Replies . . . . . . . . . . . . . . . . . . . . . 30 110 7.3. Send Events . . . . . . . . . . . . . . . . . . . . . . . 30 111 7.3.1. Sent . . . . . . . . . . . . . . . . . . . . . . . . 31 112 7.3.2. Expired . . . . . . . . . . . . . . . . . . . . . . . 31 113 7.3.3. SendError . . . . . . . . . . . . . . . . . . . . . . 31 114 7.4. Message Properties . . . . . . . . . . . . . . . . . . . 31 115 7.4.1. Lifetime . . . . . . . . . . . . . . . . . . . . . . 32 116 7.4.2. Priority . . . . . . . . . . . . . . . . . . . . . . 33 117 7.4.3. Ordered . . . . . . . . . . . . . . . . . . . . . . . 33 118 7.4.4. Idempotent . . . . . . . . . . . . . . . . . . . . . 34 119 7.4.5. Final . . . . . . . . . . . . . . . . . . . . . . . . 34 120 7.4.6. Corruption Protection Length . . . . . . . . . . . . 35 121 7.4.7. Reliable Data Transfer (Message) . . . . . . . . . . 35 122 7.4.8. Message Capacity Profile Override . . . . . . . . . . 35 123 7.4.9. Singular Transmission . . . . . . . . . . . . . . . . 36 124 7.5. Partial Sends . . . . . . . . . . . . . . . . . . . . . . 36 125 7.6. Batching Sends . . . . . . . . . . . . . . . . . . . . . 37 126 7.7. Send on Active Open: InitiateWithSend . . . . . . . . . . 37 127 8. Receiving Data . . . . . . . . . . . . . . . . . . . . . . . 38 128 8.1. Enqueuing Receives . . . . . . . . . . . . . . . . . . . 38 129 8.2. Receive Events . . . . . . . . . . . . . . . . . . . . . 39 130 8.2.1. Received . . . . . . . . . . . . . . . . . . . . . . 39 131 8.2.2. ReceivedPartial . . . . . . . . . . . . . . . . . . . 39 132 8.2.3. ReceiveError . . . . . . . . . . . . . . . . . . . . 40 133 8.3. Receive Message Properties . . . . . . . . . . . . . . . 40 134 8.3.1. ECN . . . . . . . . . . . . . . . . . . . . . . . . . 41 135 8.3.2. Early Data . . . . . . . . . . . . . . . . . . . . . 41 136 8.3.3. Receiving Final Messages . . . . . . . . . . . . . . 41 137 9. Message Contexts . . . . . . . . . . . . . . . . . . . . . . 41 138 10. Message Framers . . . . . . . . . . . . . . . . . . . . . . . 42 139 10.1. Defining Message Framers . . . . . . . . . . . . . . . . 43 140 10.2. Adding Message Framers to Connections . . . . . . . . . 43 141 10.3. Framing Meta-Data . . . . . . . . . . . . . . . . . . . 43 142 10.4. Message Framer Lifetime . . . . . . . . . . . . . . . . 44 143 10.5. Sender-side Message Framing . . . . . . . . . . . . . . 44 144 10.6. Receiver-side Message Framing . . . . . . . . . . . . . 45 146 11. Managing Connections . . . . . . . . . . . . . . . . . . . . 46 147 11.1. Generic Connection Properties . . . . . . . . . . . . . 47 148 11.1.1. Retransmission Threshold Before Excessive 149 Retransmission Notification . . . . . . . . . . . . 47 150 11.1.2. Required Minimum Corruption Protection Coverage for 151 Receiving . . . . . . . . . . . . . . . . . . . . . 48 152 11.1.3. Priority (Connection) . . . . . . . . . . . . . . . 48 153 11.1.4. Timeout for Aborting Connection . . . . . . . . . . 48 154 11.1.5. Connection Group Transmission Scheduler . . . . . . 49 155 11.1.6. Maximum Message Size Concurrent with Connection 156 Establishment . . . . . . . . . . . . . . . . . . . 49 157 11.1.7. Maximum Message Size Before Fragmentation or 158 Segmentation . . . . . . . . . . . . . . . . . . . . 49 159 11.1.8. Maximum Message Size on Send . . . . . . . . . . . . 49 160 11.1.9. Maximum Message Size on Receive . . . . . . . . . . 49 161 11.1.10. Capacity Profile . . . . . . . . . . . . . . . . . . 50 162 11.1.11. Bounds on Send or Receive Rate . . . . . . . . . . . 51 163 11.1.12. TCP-specific Property: User Timeout . . . . . . . . 52 164 11.2. Soft Errors . . . . . . . . . . . . . . . . . . . . . . 52 165 11.3. Excessive retransmissions . . . . . . . . . . . . . . . 52 166 12. Connection Termination . . . . . . . . . . . . . . . . . . . 53 167 13. Connection State and Ordering of Operations and Events . . . 53 168 14. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 54 169 15. Security Considerations . . . . . . . . . . . . . . . . . . . 54 170 16. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 55 171 17. References . . . . . . . . . . . . . . . . . . . . . . . . . 55 172 17.1. Normative References . . . . . . . . . . . . . . . . . . 55 173 17.2. Informative References . . . . . . . . . . . . . . . . . 56 174 Appendix A. Additional Properties . . . . . . . . . . . . . . . 57 175 A.1. Experimental Transport Properties . . . . . . . . . . . . 58 176 A.1.1. Cost Preferences . . . . . . . . . . . . . . . . . . 58 177 Appendix B. Sample API definition in Go . . . . . . . . . . . . 59 178 Appendix C. Relationship to the Minimal Set of Transport 179 Services for End Systems . . . . . . . . . . . . . . 59 180 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 62 182 1. Introduction 184 The BSD Unix Sockets API's SOCK_STREAM abstraction, by bringing 185 network sockets into the UNIX programming model, allowing anyone who 186 knew how to write programs that dealt with sequential-access files to 187 also write network applications, was a revolution in simplicity. The 188 simplicity of this API is a key reason the Internet won the protocol 189 wars of the 1980s. SOCK_STREAM is tied to the Transmission Control 190 Protocol (TCP), specified in 1981 [RFC0793]. TCP has scaled 191 remarkably well over the past three and a half decades, but its total 192 ubiquity has hidden an uncomfortable fact: the network is not really 193 a file, and stream abstractions are too simplistic for many modern 194 application programming models. 196 In the meantime, the nature of Internet access, and the variety of 197 Internet transport protocols, is evolving. The challenges that new 198 protocols and access paradigms present to the sockets API and to 199 programming models based on them inspire the design principles of a 200 new approach, which we outline in Section 3. 202 As a first step to realizing this design, [I-D.ietf-taps-arch] 203 describes a high-level architecture for transport services. This 204 document builds a modern abstract programming interface atop this 205 architecture, deriving specific path and protocol selection 206 properties and supported transport features from the analysis 207 provided in [RFC8095], [I-D.ietf-taps-minset], and 208 [I-D.ietf-taps-transport-security]. 210 2. Terminology and Notation 212 This API is described in terms of Objects, which an application can 213 interact with; Actions the application can perform on these Objects; 214 Events, which an Object can send to an application asynchronously; 215 and Parameters associated with these Actions and Events. 217 The following notations, which can be combined, are used in this 218 document: 220 o An Action creates an Object: 222 Object := Action() 224 o An Action creates an array of Objects: 226 []Object := Action() 228 o An Action is performed on an Object: 230 Object.Action() 232 o An Object sends an Event: 234 Object -> Event<> 236 o An Action takes a set of Parameters; an Event contains a set of 237 Parameters. Action parameters whose names are suffixed with a 238 question mark are optional. 240 Action(param0, param1?, ...) / Event 241 Actions associated with no Object are Actions on the abstract 242 interface itself; they are equivalent to Actions on a per-application 243 global context. 245 How these abstract concepts map into concrete implementations of this 246 API in a given language on a given platform is largely dependent on 247 the features of the language and the platform. Actions could be 248 implemented as functions or method calls, for instance, and Events 249 could be implemented via callbacks, communicating sequential 250 processes, or other asynchronous calling conventions. The method for 251 dispatching and handling Events is left as an implementation detail, 252 with the caveat that the interface for receiving Messages must 253 require the application to invoke the Connection.Receive() Action 254 once per Message to be received (see Section 8). 256 This specification treats Events and errors similarly. Errors, just 257 as any other Events, may occur asynchronously in network 258 applications. However, it is recommended that implementations of 259 this interface also return errors immediately, according to the error 260 handling idioms of the implementation platform, for errors which can 261 be immediately detected, such as inconsistency in Transport 262 Properties. 264 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 265 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 266 "OPTIONAL" in this document are to be interpreted as described in BCP 267 14 [RFC2119] [RFC8174] when, and only when, they appear in all 268 capitals, as shown here. 270 3. Interface Design Principles 272 The design of the interface specified in this document is based on a 273 set of princples, themselves an elaboration on the architectural 274 design principles defined in [I-D.ietf-taps-arch]. The interface 275 defined in this document provides: 277 o A single interface to a variety of transport protocols to be used 278 in a variety of application design patterns, independent of the 279 properties of the application and the Protocol Stacks that will be 280 used at runtime, such that all common specialized features of 281 these protocol stacks are made available to the application as 282 necessary in a transport-independent way, to enable applications 283 written to a single API to make use of transport protocols in 284 terms of the features they provide; 286 o Message- as opposed to stream-orientation, using application- 287 assisted framing and deframing where the underlying transport does 288 not provide these; 290 o Asynchronous Connection establishment, transmission, and 291 reception, allowing concurrent operations during establishment and 292 supporting event-driven application interactions with the 293 transport layer, in line with developments in modern platforms and 294 programming languages; 296 o Explicit support for security properties as first-order transport 297 features, and for long-term caching of cryptographic identities 298 and parameters for associations among endpoints; and 300 o Explicit support for multistreaming and multipath transport 301 protocols, and the grouping of related Connections into Connection 302 Groups through cloning of Connections, to allow applications to 303 take full advantage of new transport protocols supporting these 304 features. 306 4. API Summary 308 The Transport Services Interface is the basic common abstract 309 application programming interface to the Transport Services 310 Architecture defined in [I-D.ietf-taps-arch]. 312 An application primarily interacts with this interface through two 313 Objects, Preconnections and Connections. A Preconnection represents 314 a set of properties and constraints on the selection and 315 configuration of paths and protocols to establish a Connection with a 316 remote endpoint. A Connection represents a transport Protocol Stack 317 on which data can be sent to and/or received from a remote endpoint 318 (i.e., depending on the kind of transport, connections can be bi- 319 directional or unidirectional). Connections can be created from 320 Preconnections in three ways: by initiating the Preconnection (i.e., 321 actively opening, as in a client), through listening on the 322 Preconnection (i.e., passively opening, as in a server), or 323 rendezvousing on the Preconnection (i.e. peer to peer 324 establishment). 326 Once a Connection is established, data can be sent on it in the form 327 of Messages. The interface supports the preservation of message 328 boundaries both via explicit Protocol Stack support, and via 329 application support through a Message Framer which finds message 330 boundaries in a stream. Messages are received asynchronously through 331 a callback registered by the application. Errors and other 332 notifications also happen asynchronously on the Connection. 334 Section 5, Section 6, Section 7, Section 8, and Section 12 describe 335 the details of application interaction with Objects through Actions 336 and Events in each phase of a Connection, following the phases 337 described in [I-D.ietf-taps-arch]. 339 4.1. Usage Examples 341 The following usage examples illustrate how an application might use 342 a Transport Services Interface to: 344 o Act as a server, by listening for incoming connections, receiving 345 requests, and sending responses, see Section 4.1.1. 347 o Act as a client, by connecting to a remote endpoint using 348 Initiate, sending requests, and receiving responses, see 349 Section 4.1.2. 351 o Act as a peer, by connecting to a remote endpoint using Rendezvous 352 while simultaneously waiting for incoming Connections, sending 353 Messages, and receiving Messages, see Section 4.1.3. 355 The examples in this section presume that a transport protocol is 356 available between the endpoints which provides Reliable Data 357 Transfer, Preservation of data ordering, and Preservation of Message 358 Boundaries. In this case, the application can choose to receive only 359 complete messages. 361 If none of the available transport protocols provides Preservation of 362 Message Boundaries, but there is a transport protocol which provides 363 a reliable ordered byte stream, an application may receive this byte 364 stream as partial Messages and transform it into application-layer 365 Messages. Alternatively, an application may provide a Message 366 Framer, which can transform a byte stream into a sequence of Messages 367 (Section 10.6). 369 4.1.1. Server Example 371 This is an example of how an application might listen for incoming 372 Connections using the Transport Services Interface, receive a 373 request, and send a response. 375 LocalSpecifier := NewLocalEndpoint() 376 LocalSpecifier.WithInterface("any") 377 LocalSpecifier.WithService("https") 379 TransportProperties := NewTransportProperties() 380 TransportProperties.Require(preserve-msg-boundaries) 381 // Reliable Data Transfer and Preserve Order are Required by default 383 SecurityParameters := NewSecurityParameters() 384 SecurityParameters.AddIdentity(identity) 385 SecurityParameters.AddPrivateKey(privateKey, publicKey) 387 // Specifying a remote endpoint is optional when using Listen() 388 Preconnection := NewPreconnection(LocalSpecifier, 389 None, 390 TransportProperties, 391 SecurityParameters) 393 Listener := Preconnection.Listen() 395 Listener -> ConnectionReceived 397 // Only receive complete messages 398 Connection.Receive() 400 Connection -> Received(messageDataRequest, messageContext) 402 Connection.Send(messageDataResponse) 404 Connection.Close() 406 // Stop listening for incoming Connections 407 Listener.Stop() 409 4.1.2. Client Example 411 This is an example of how an application might connect to a remote 412 application using the Transport Services Interface, send a request, 413 and receive a response. 415 RemoteSpecifier := NewRemoteEndpoint() 416 RemoteSpecifier.WithHostname("example.com") 417 RemoteSpecifier.WithService("https") 419 TransportProperties := NewTransportProperties() 420 TransportProperties.Require(preserve-msg-boundaries) 421 // Reliable Data Transfer and Preserve Order are Required by default 423 SecurityParameters := NewSecurityParameters() 424 TrustCallback := New Callback({ 425 // Verify identity of the remote endpoint, return the result 426 }) 427 SecurityParameters.SetTrustVerificationCallback(TrustCallback) 429 // Specifying a local endpoint is optional when using Initiate() 430 Preconnection := NewPreconnection(None, 431 RemoteSpecifier, 432 TransportPreperties, 433 SecurityParameters) 435 Connection := Preconnection.Initiate() 437 Connection -> Ready<> 439 Connection.Send(messageDataRequest) 441 // Only receive complete messages 442 Connection.Receive() 444 Connection -> Received(messageDataResponse, messageContext) 446 Connection.Close() 448 4.1.3. Peer Example 450 This is an example of how an application might establish a connection 451 with a peer using Rendezvous(), send a Message, and receive a 452 Message. 454 LocalSpecifier := NewLocalEndpoint() 455 LocalSpecifier.WithPort(9876) 457 RemoteSpecifier := NewRemoteEndpoint() 458 RemoteSpecifier.WithHostname("example.com") 459 RemoteSpecifier.WithPort(9877) 461 TransportProperties := NewTransportProperties() 462 TransportProperties.Require(preserve-msg-boundaries) 463 // Reliable Data Transfer and Preserve Order are Required by default 465 SecurityParameters := NewSecurityParameters() 466 SecurityParameters.AddIdentity(identity) 467 SecurityParameters.AddPrivateKey(privateKey, publicKey) 469 TrustCallback := New Callback({ 470 // Verify identity of the remote endpoint, return the result 471 }) 472 SecurityParameters.SetTrustVerificationCallback(trustCallback) 474 // Both local and remote endpoint must be specified 475 Preconnection := NewPreconnection(LocalSpecifier, 476 RemoteSpecifier, 477 TransportPreperties, 478 SecurityParameters) 480 Preconnection.Rendezvous() 482 Preconnection -> RendezvousDone 484 Connection.Send(messageDataRequest) 486 // Only receive complete messages 487 Connection.Receive() 489 Connection -> Received(messageDataResponse, messageContext) 491 Connection.Close() 493 4.2. Transport Properties 495 Each application using the Transport Services Interface declares its 496 preferences for how the transport service should operate using 497 properties at each stage of the lifetime of a connection. During 498 pre-establishment, Selection Properties (see Section 5.2) are used to 499 specify which paths and protocol stacks can be used and are preferred 500 by the application, and Connection Properties (see Section 11.1) can 501 be used to influence decisions made during establishment and to fine- 502 tune the eventually established connection. These Connection 503 Properties can also be used later, to monitor and fine-tune 504 established connections. The behavior of the selected protocol 505 stack(s) when sending Messages is controlled by Message Properties 506 (see Section 7.4). 508 Collectively, Selection, Connection, and Message Properties can be 509 referred to as Transport Properties. All Transport Properties, 510 regardless of the phase in which they are used, are organized within 511 a single namespace. This enables setting them as defaults in earlier 512 stages and querying them in later stages: - Connection Properties can 513 be set on Preconnections - Message Properties can be set on 514 Preconnections and Connections - The effect of Selection Properties 515 can be queried on Connections and Messages 517 Note that Configuring Connection Properties and Message Properties on 518 Preconnections is preferred over setting them later. Connection 519 Properties specified early on may be used as additional input to the 520 selection process. Also note that Protocol Specific Properties, see 521 Section 4.2.1, should not be used as an input to the selection 522 process. 524 4.2.1. Transport Property Names 526 Transport Properties are referred to by property names. These names 527 are lower-case strings whereby words are separated by hyphens. These 528 names serve two purposes: 530 o Allow different components of a TAPS implementation to pass 531 Transport Properties, e.g., between a language frontend and a 532 policy manager, or as a representation of properties retrieved 533 from a file or other storage. 535 o Make code of different TAPS implementations look similar. 537 Transport Property Names are hierarchically organized in the form 538 [.]. 540 o The Namespace part is empty for well known, generic properties, 541 i.e., for properties defined by an RFC which are not protocol 542 specific. 544 o Protocol Specific Properties must use the protocol acronym as 545 Namespace, e.g., "tcp" for TCP specific Transport Properties. For 546 IETF protocols, property names under these namespaces SHOULD be 547 defined in an RFC. 549 o Vendor or implementation specific properties must use a a string 550 identifying the vendor or implementation as Namespace. 552 4.2.2. Transport Property Types 554 Transport Properties can have one of a set of data types: 556 o Boolean: can take the values "true" and "false"; representation is 557 implementation-dependent. 559 o Integer: can take positive or negative numeric integer values; 560 range and representation is implementation-dependent. 562 o Numeric: can take positive or negative numeric values; range and 563 representation is implementation-dependent. 565 o Enumeration: can take one value of a finite set of values, 566 dependent on the property itself. The representation is 567 implementation dependent; however, implementations MUST provide a 568 method for the application to determine the entire set of possible 569 values for each property. 571 o Preference: can take one of five values (Prohibit, Avoid, Ignore, 572 Prefer, Require) for the level of preference of a given property 573 during protocol selection; see Section 5.2. 575 4.3. Scope of the Interface Definition 577 This document defines a language- and platform-independent interface 578 to a Transport Services system. Given the wide variety of languages 579 and language conventions used to write applications that use the 580 transport layer to connect to other applications over the Internet, 581 this independence makes this interface necessarily abstract. While 582 there is no interoperability benefit to tightly defining how the 583 interface be presented to application programmers in diverse 584 platforms, maintaining the "shape" of the abstract interface across 585 these platforms reduces the effort for programmers who learn the 586 transport services interface to apply their knowledge in multiple 587 platforms. We therefore make the following recommendations: 589 o Actions, Events, and Errors in implementations of this interface 590 SHOULD carry the names given for them in the document, subject to 591 capitalization and punctuation conventions in the language of the 592 implementation, unless the implementation itself uses different 593 names for substantially equivalent objects for networking by 594 convention. 596 o Implementations of this interface SHOULD implement each Selection 597 Property, Connection Property, and Message Context Property 598 specified in this document, exclusive of appendices, even if said 599 implementation is a non-operation, e.g. because transport 600 protocols implementing a given Property are not available on the 601 platform. 603 o Implementations may use other representations for Transport 604 Property Names, e.g., by providing constants or static singleton 605 objects, but should provide a straight-forward mapping between 606 their representation and the property names specified here. 608 5. Pre-Establishment Phase 610 The pre-establishment phase allows applications to specify properties 611 for the Connections they are about to make, or to query the API about 612 potential connections they could make. 614 A Preconnection Object represents a potential Connection. It has 615 state that describes properties of a Connection that might exist in 616 the future. This state comprises Local Endpoint and Remote Endpoint 617 Objects that denote the endpoints of the potential Connection (see 618 Section 5.1), the Selection Properties (see Section 5.2), any 619 preconfigured Connection Properties (Section 11.1), and the security 620 parameters (see Section 5.3): 622 Preconnection := NewPreconnection(LocalEndpoint, 623 RemoteEndpoint, 624 TransportProperties, 625 SecurityParams) 627 The Local Endpoint MUST be specified if the Preconnection is used to 628 Listen() for incoming Connections, but is OPTIONAL if it is used to 629 Initiate() connections. The Remote Endpoint MUST be specified if the 630 Preconnection is used to Initiate() Connections, but is OPTIONAL if 631 it is used to Listen() for incoming Connections. The Local Endpoint 632 and the Remote Endpoint MUST both be specified if a peer-to-peer 633 Rendezvous is to occur based on the Preconnection. 635 Message Framers (see Section 10), if required, should be added to the 636 Preconnection during pre-establishment. 638 5.1. Specifying Endpoints 640 The transport services API uses the Local Endpoint and Remote 641 Endpoint types to refer to the endpoints of a transport connection. 642 Subtypes of these represent various different types of endpoint 643 identifiers, such as IP addresses, DNS names, and interface names, as 644 well as port numbers and service names. 646 RemoteSpecifier := NewRemoteEndpoint() 647 RemoteSpecifier.WithHostname("example.com") 648 RemoteSpecifier.WithService("https") 650 RemoteSpecifier := NewRemoteEndpoint() 651 RemoteSpecifier.WithIPv6Address(2001:db8:4920:e29d:a420:7461:7073:0a) 652 RemoteSpecifier.WithPort(443) 654 RemoteSpecifier := NewRemoteEndpoint() 655 RemoteSpecifier.WithIPv4Address(192.0.2.21) 656 RemoteSpecifier.WithPort(443) 658 LocalSpecifier := NewLocalEndpoint() 659 LocalSpecifier.WithInterface("en0") 660 LocalSpecifier.WithPort(443) 662 LocalSpecifier := NewLocalEndpoint() 663 LocalSpecifier.WithStunServer(address, port, credentials) 665 Implementations may also support additional endpoint representations 666 and provide a single NewEndpoint() call that takes different endpoint 667 representations. 669 Multiple endpoint identifiers can be specified for each Local 670 Endpoint and Remote Endpoint. For example, a Local Endpoint could be 671 configured with two interface names, or a Remote Endpoint could be 672 specified via both IPv4 and IPv6 addresses. These multiple 673 identifiers refer to the same transport endpoint. 675 The transport services API resolves names internally, when the 676 Initiate(), Listen(), or Rendezvous() method is called establish a 677 Connection. The API explicitly does not require the application to 678 resolve names, though there is a tradeoff between early and late 679 binding of addresses to names. Early binding allows the API 680 implementation to reduce connection setup latency, at the cost of 681 potentially limited scope for alternate path discovery during 682 Connection establishment, as well as potential additional information 683 leakage about application interest when used with a resolution method 684 (such as DNS without TLS) which does not protect query 685 confidentiality. 687 The Resolve() action on Preconnection can be used by the application 688 to force early binding when required, for example with some Network 689 Address Translator (NAT) traversal protocols (see Section 6.3). 691 5.2. Specifying Transport Properties 693 A Preconnection Object holds properties reflecting the application's 694 requirements and preferences for the transport. These include 695 Selection Properties for selecting protocol stacks and paths, as well 696 as Connection Properties for configuration of the detailed operation 697 of the selected Protocol Stacks. 699 The protocol(s) and path(s) selected as candidates during 700 establishment are determined and configured using these properties. 701 Since there could be paths over which some transport protocols are 702 unable to operate, or remote endpoints that support only specific 703 network addresses or transports, transport protocol selection is 704 necessarily tied to path selection. This may involve choosing 705 between multiple local interfaces that are connected to different 706 access networks. 708 Most Selection Properties are represented as preferences, which can 709 have one of five preference levels: 711 +------------+------------------------------------------------------+ 712 | Preference | Effect | 713 +------------+------------------------------------------------------+ 714 | Require | Select only protocols/paths providing the property, | 715 | | fail otherwise | 716 | | | 717 | Prefer | Prefer protocols/paths providing the property, | 718 | | proceed otherwise | 719 | | | 720 | Ignore | No preference | 721 | | | 722 | Avoid | Prefer protocols/paths not providing the property, | 723 | | proceed otherwise | 724 | | | 725 | Prohibit | Select only protocols/paths not providing the | 726 | | property, fail otherwise | 727 +------------+------------------------------------------------------+ 729 In addition, the pseudo-level "Default" can be used to reset the 730 property to the default level used by the implementation. This level 731 will never show up when queuing the value of a preference - the 732 effective preference must be returned instead. 734 Internally, the transport system will first exclude all protocols and 735 paths that match a Prohibit, then exclude all protocols and paths 736 that do not match a Require, then sort candidates according to 737 Preferred properties, and then use Avoided properties as a 738 tiebreaker. Selection Properties which select paths take preference 739 over those which select protocols. For example, if an application 740 indicates a preference for a specific path by specifying an 741 interface, but also a preference for a protocol not available on this 742 path, the transport system will try the path first, ignoring the 743 preference. 745 Selection, and Connection Properties, as well as defaults for Message 746 Properties, can be added to a Preconnection to configure the 747 selection process, and to further configure the eventually selected 748 protocol stack(s). They are collected into a TransportProperties 749 object to be passed into a Preconnection object: 751 TransportProperties := NewTransportProperties() 753 Individual properties are then added to the TransportProperties 754 Object: 756 TransportProperties.Add(property, value) 758 Selection Properties can be added to a TransportProperties object 759 using special actions for each preference level i.e, 760 "TransportProperties.Add(some_property, avoid)" is equivalent to 761 "TransportProperties.Avoid(some_property)": 763 TransportProperties.Require(property) 764 TransportProperties.Prefer(property) 765 TransportProperties.Ignore(property) 766 TransportProperties.Avoid(property) 767 TransportProperties.Prohibit(property) 768 TransportProperties.Default(property) 770 For an existing Connection, the Transport Properties can be queried 771 any time by using the following call on the Connection Object: 773 TransportProperties := Connection.GetTransportProperties() 775 A Connection gets its Transport Properties either by being explicitly 776 configured via a Preconnection, by configuration after establishment, 777 or by inheriting them from an antecedent via cloning; see Section 6.4 778 for more. 780 Section 11.1 provides a list of Connection Properties, while 781 Selection Properties are listed in the subsections below. Note that 782 many properties are only considered during establishment, and can not 783 be changed after a Connection is established; however, they can be 784 queried. Querying a Selection Property after establishment yields 785 the value Required for properties of the selected protocol and path, 786 Avoid for properties avoided during selection, and Ignore for all 787 other properties. 789 An implementation of this interface must provide sensible defaults 790 for Selection Properties. The recommended defaults given for each 791 property below represent a configuration that can be implemented over 792 TCP. An alternate set of default Protocol Selection Properties would 793 represent a configuration that can be implemented over UDP. 795 5.2.1. Reliable Data Transfer (Connection) 797 Name: reliability 799 This property specifies whether the application needs to use a 800 transport protocol that ensures that all data is received on the 801 other side without corruption. This also entails being notified when 802 a Connection is closed or aborted. The recommended default is to 803 Require Reliable Data Transfer. 805 5.2.2. Preservation of Message Boundaries 807 Name: preserve-msg-boundaries 809 This property specifies whether the application needs or prefers to 810 use a transport protocol that preserves message boundaries. The 811 recommended default is to Prefer Preservation of Message Boundaries. 813 5.2.3. Configure Per-Message Reliability 815 Name: per-msg-reliability 817 This property specifies whether an application considers it useful to 818 indicate its reliability requirements on a per-Message basis. This 819 property applies to Connections and Connection Groups. The 820 recommended default is to Ignore this option. 822 5.2.4. Preservation of Data Ordering 824 Name: preserve-order 826 This property specifies whether the application wishes to use a 827 transport protocol that can ensure that data is received by the 828 application on the other end in the same order as it was sent. The 829 recommended default is to Require Preservation of data ordering. 831 5.2.5. Use 0-RTT Session Establishment with an Idempotent Message 833 Name: zero-rtt-msg 835 This property specifies whether an application would like to supply a 836 Message to the transport protocol before Connection establishment, 837 which will then be reliably transferred to the other side before or 838 during Connection establishment, potentially multiple times (i.e., 839 multiple copies of the message data may be passed to the Remote 840 Endpoint). See also Section 7.4.4. The recommended default is to 841 Ignore this option. Note that disabling this property has no effect 842 for protocols that are not connection-oriented and do not protect 843 against duplicated messages, e.g., UDP. 845 5.2.6. Multistream Connections in Group 847 Name: multistreaming 849 This property specifies that the application would prefer multiple 850 Connections within a Connection Group to be provided by streams of a 851 single underlying transport connection where possible. The 852 recommended default is to Prefer this option. 854 5.2.7. Full Checksum Coverage on Sending 856 Name: per-msg-checksum-len-send 858 This property specifies whether the application desires protection 859 against corruption for all data transmitted on this Connection. 860 Disabling this property may enable to control checksum coverage later 861 (see Section 7.4.6). The recommended default is to Require this 862 option. 864 5.2.8. Full Checksum Coverage on Receiving 866 Name: per-msg-checksum-len-recv 868 This property specifies whether the application desires protection 869 against corruption for all data received on this Connection. The 870 recommended default is to Require this option. 872 5.2.9. Congestion control 874 Name: congestion-control 876 This property specifies whether the application would like the 877 Connection to be congestion controlled or not. Note that if a 878 Connection is not congestion controlled, an application using such a 879 Connection should itself perform congestion control in accordance 880 with [RFC2914]. Also note that reliability is usually combined with 881 congestion control in protocol implementations, rendering "reliable 882 but not congestion controlled" a request that is unlikely to succeed. 883 The recommended default is to Require that the Connection is 884 congestion controlled. 886 5.2.10. Interface Instance or Type 888 Name: interface 890 Type: Set (Preference, Enumeration) 892 This property allows the application to select which specific network 893 interfaces or categories of interfaces it wants to "Require", 894 "Prohibit", "Prefer", or "Avoid". 896 In contrast to other Selection Properties, this property is a tuple 897 of an (Enumerated) interface identifier and a preference, and can 898 either be implemented directly as such, or for making one preference 899 available for each interface and interface type available on the 900 system. 902 Note that marking a specific interface as "Required" strictly limits 903 path selection to a single interface, and leads to less flexible and 904 resilient connection establishment. 906 The set of valid interface types is implementation- and system- 907 specific. For example, on a mobile device, there may be "Wi-Fi" and 908 "Cellular" interface types available; whereas on a desktop computer, 909 there may be "Wi-Fi" and "Wired Ethernet" interface types available. 910 Implementations should provide all types that are supported on some 911 system to all systems, in order to allow applications to write 912 generic code. For example, if a single implementation is used on 913 both mobile devices and desktop devices, it should define the 914 "Cellular" interface type for both systems, since an application may 915 want to always "Prohibit Cellular". Note that marking a specific 916 interface type as "Required" limits path selection to a small set of 917 interfaces, and leads to less flexible and resilient connection 918 establishment. 920 The set of interface types is expected to change over time as new 921 access technologies become available. 923 Interface types should not be treated as a proxy for properties of 924 interfaces such as metered or unmetered network access. If an 925 application needs to prohibit metered interfaces, this should be 926 specified via Provisioning Domain attributes (see Section 5.2.11) or 927 another specific property. 929 5.2.11. Provisioning Domain Instance or Type 931 Name: pvd 933 Type: Set (Preference, Enumeration) 935 Similar to interface instances and types (see Section 5.2.10), this 936 property allows the application to control path selection by 937 selecting which specific Provisioning Domains or categories of 938 Provisioning Domains it wants to "Require", "Prohibit", "Prefer", or 939 "Avoid". Provisioning Domains define consistent sets of network 940 properties that may be more specific than network interfaces 941 [RFC7556]. 943 As with interface instances and types, this property is a tuple of an 944 (Enumerated) PvD identifier and a preference, and can either be 945 implemented directly as such, or for making one preference available 946 for each interface and interface type available on the system. 948 The identification of a specific Provisioning Domain (PvD) is defined 949 to be implementation- and system-specific, since there is not a 950 portable standard format for a PvD identitfier. For example, this 951 identifier may be a string name or an integer. As with requiring 952 specific interfaces, requiring a specific PvD strictly limits path 953 selection. 955 Categories or types of PvDs are also defined to be implementation- 956 and system-specific. These may be useful to identify a service that 957 is provided by a PvD. For example, if an application wants to use a 958 PvD that provides a Voice-Over-IP service on a Cellular network, it 959 can use the relevant PvD type to require some PvD that provides this 960 service, without needing to look up a particular instance. While 961 this does restrict path selection, it is broader than requiring 962 specific PvD instances or interface instances, and should be 963 preferred over these options. 965 5.2.12. Parallel Use of Multiple Paths 967 Name: multipath 969 This property specifies whether an application considers it useful to 970 transfer data across multiple paths between the same end hosts. 971 Generally, in most cases, this will improve performance (e.g., 972 achieve greater throughput). One possible side-effect is increased 973 jitter, which may be problematic for delay-sensitive applications. 974 The recommended default is to Prefer this option. 976 5.2.13. Direction of communication 978 Name: direction 980 Type: Enumeration 982 This property specifies whether an application wants to use the 983 connection for sending and/or receiving data. Possible values are: 985 Bidirectional (default): The connection must support sending and 986 receiving data 988 Unidirectional send: The connection must support sending data 990 Unidirectional receive: The connection must support receiving data 992 In case a unidirectional connection is requested, but unidirectional 993 connections are not supported by the transport protocol, the system 994 should fall back to bidirectional transport. 996 5.2.14. Notification of excessive retransmissions 998 Name: :retransmit-notify 1000 This property specifies whether an application considers it useful to 1001 be informed in case sent data was retransmitted more often than a 1002 certain threshold. The recommended default is to Ignore this option. 1004 5.2.15. Notification of ICMP soft error message arrival 1006 Name: :soft-error-notify 1008 This property specifies whether an application considers it useful to 1009 be informed when an ICMP error message arrives that does not force 1010 termination of a connection. When set to true, received ICMP errors 1011 will be available as SoftErrors. Note that even if a protocol 1012 supporting this property is selected, not all ICMP errors will 1013 necessarily be delivered, so applications cannot rely on receiving 1014 them. The recommended default is to Ignore this option. 1016 5.3. Specifying Security Parameters and Callbacks 1018 Most security parameters, e.g., TLS ciphersuites, local identity and 1019 private key, etc., may be configured statically. Others are 1020 dynamically configured during connection establishment. Thus, we 1021 partition security parameters and callbacks based on their place in 1022 the lifetime of connection establishment. Similar to Transport 1023 Properties, both parameters and callbacks are inherited during 1024 cloning (see Section 6.4). 1026 5.3.1. Pre-Connection Parameters 1028 Common parameters such as TLS ciphersuites are known to 1029 implementations. Clients should use common safe defaults for these 1030 values whenever possible. However, as discussed in 1031 [I-D.ietf-taps-transport-security], many transport security protocols 1032 require specific security parameters and constraints from the client 1033 at the time of configuration and actively during a handshake. These 1034 configuration parameters are created as follows: 1036 SecurityParameters := NewSecurityParameters() 1038 Security configuration parameters and sample usage follow: 1040 o Local identity and private keys: Used to perform private key 1041 operations and prove one's identity to the Remote Endpoint. 1042 (Note, if private keys are not available, e.g., since they are 1043 stored in hardware security modules (HSMs), handshake callbacks 1044 must be used. See below for details.) 1046 SecurityParameters.AddIdentity(identity) 1047 SecurityParameters.AddPrivateKey(privateKey, publicKey) 1049 o Supported algorithms: Used to restrict what parameters are used by 1050 underlying transport security protocols. When not specified, 1051 these algorithms should default to known and safe defaults for the 1052 system. Parameters include: ciphersuites, supported groups, and 1053 signature algorithms. 1055 SecurityParameters.AddSupportedGroup(secp256k1) 1056 SecurityParameters.AddCiphersuite(TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256) 1057 SecurityParameters.AddSignatureAlgorithm(ed25519) 1059 o Session cache management: Used to tune cache capacity, lifetime, 1060 re-use, and eviction policies, e.g., LRU or FIFO. Constants and 1061 policies for these interfaces are implementation-specific. 1063 SecurityParameters.SetSessionCacheCapacity(MAX_CACHE_ELEMENTS) 1064 SecurityParameters.SetSessionCacheLifetime(SECONDS_PER_DAY) 1065 SecurityParameters.SetSessionCachePolicy(CachePolicyOneTimeUse) 1067 o Pre-Shared Key import: Used to install pre-shared keying material 1068 established out-of-band. Each pre-shared keying material is 1069 associated with some identity that typically identifies its use or 1070 has some protocol-specific meaning to the Remote Endpoint. 1072 SecurityParameters.AddPreSharedKey(key, identity) 1074 5.3.2. Connection Establishment Callbacks 1076 Security decisions, especially pertaining to trust, are not static. 1077 Once configured, parameters may also be supplied during connection 1078 establishment. These are best handled as client-provided callbacks. 1079 Security handshake callbacks that may be invoked during connection 1080 establishment include: 1082 o Trust verification callback: Invoked when a Remote Endpoint's 1083 trust must be validated before the handshake protocol can proceed. 1085 TrustCallback := NewCallback({ 1086 // Handle trust, return the result 1087 }) 1088 SecurityParameters.SetTrustVerificationCallback(trustCallback) 1090 o Identity challenge callback: Invoked when a private key operation 1091 is required, e.g., when local authentication is requested by a 1092 remote. 1094 ChallengeCallback := NewCallback({ 1095 // Handle challenge 1096 }) 1097 SecurityParameters.SetIdentityChallengeCallback(challengeCallback) 1099 6. Establishing Connections 1101 Before a Connection can be used for data transfer, it must be 1102 established. Establishment ends the pre-establishment phase; all 1103 transport properties and cryptographic parameter specification must 1104 be complete before establishment, as these will be used to select 1105 candidate Paths and Protocol Stacks for the Connection. 1106 Establishment may be active, using the Initiate() Action; passive, 1107 using the Listen() Action; or simultaneous for peer-to-peer, using 1108 the Rendezvous() Action. These Actions are described in the 1109 subsections below. 1111 6.1. Active Open: Initiate 1113 Active open is the Action of establishing a Connection to a Remote 1114 Endpoint presumed to be listening for incoming Connection requests. 1115 Active open is used by clients in client-server interactions. Active 1116 open is supported by this interface through the Initiate Action: 1118 Connection := Preconnection.Initiate(timeout?) 1120 The timeout parameter specifies how long to wait before aborting 1121 Active open. Before calling Initiate, the caller must have populated 1122 a Preconnection Object with a Remote Endpoint specifier, optionally a 1123 Local Endpoint specifier (if not specified, the system will attempt 1124 to determine a suitable Local Endpoint), as well as all properties 1125 necessary for candidate selection. 1127 The Initiate() Action consumes the Preconnection. Once Initiate() 1128 has been called, no further properties may be added to the 1129 Preconnection, and no subsequent establishment call may be made on 1130 the Preconnection. 1132 Once Initiate is called, the candidate Protocol Stack(s) may cause 1133 one or more candidate transport-layer connections to be created to 1134 the specified remote endpoint. The caller may immediately begin 1135 sending Messages on the Connection (see Section 7) after calling 1136 Initate(); note that any idempotent data sent while the Connection is 1137 being established may be sent multiple times or on multiple 1138 candidates. 1140 The following Events may be sent by the Connection after Initiate() 1141 is called: 1143 Connection -> Ready<> 1145 The Ready Event occurs after Initiate has established a transport- 1146 layer connection on at least one usable candidate Protocol Stack over 1147 at least one candidate Path. No Receive Events (see Section 8) will 1148 occur before the Ready Event for Connections established using 1149 Initiate. 1151 Connection -> InitiateError<> 1153 An InitiateError occurs either when the set of transport properties 1154 and security parameters cannot be fulfilled on a Connection for 1155 initiation (e.g. the set of available Paths and/or Protocol Stacks 1156 meeting the constraints is empty) or reconciled with the local and/or 1157 remote endpoints; when the remote specifier cannot be resolved; or 1158 when no transport-layer connection can be established to the remote 1159 endpoint (e.g. because the remote endpoint is not accepting 1160 connections, the application is prohibited from opening a Connection 1161 by the operating system, or the establishment attempt has timed out 1162 for any other reason). 1164 See also Section 7.7 to combine Connection establishment and 1165 transmission of the first message in a single action. 1167 6.2. Passive Open: Listen 1169 Passive open is the Action of waiting for Connections from remote 1170 endpoints, commonly used by servers in client-server interactions. 1171 Passive open is supported by this interface through the Listen Action 1172 and returns a Listener object: 1174 Listener := Preconnection.Listen() 1176 Before calling Listen, the caller must have initialized the 1177 Preconnection during the pre-establishment phase with a Local 1178 Endpoint specifier, as well as all properties necessary for Protocol 1179 Stack selection. A Remote Endpoint may optionally be specified, to 1180 constrain what Connections are accepted. The Listen() Action returns 1181 a Listener object. Once Listen() has been called, properties added 1182 to the Preconnection have no effect on the Listener and the 1183 Preconnection can be disposed of or reused. 1185 Listening continues until the global context shuts down, or until the 1186 Stop action is performed on the Listener object: 1188 Listener.Stop() 1190 After Stop() is called, the Listener can be disposed of. 1192 Listener -> ConnectionReceived 1194 The ConnectionReceived Event occurs when a Remote Endpoint has 1195 established a transport-layer connection to this Listener (for 1196 Connection-oriented transport protocols), or when the first Message 1197 has been received from the Remote Endpoint (for Connectionless 1198 protocols), causing a new Connection to be created. The resulting 1199 Connection is contained within the ConnectionReceived event, and is 1200 ready to use as soon as it is passed to the application via the 1201 event. 1203 Listener -> ListenError<> 1205 A ListenError occurs either when the Properties of the Preconnection 1206 cannot be fulfilled for listening, when the Local Endpoint (or Remote 1207 Endpoint, if specified) cannot be resolved, or when the application 1208 is prohibited from listening by policy. 1210 Listener -> Stopped<> 1212 A Stopped event occurs after the Listener has stopped listening. 1214 6.3. Peer-to-Peer Establishment: Rendezvous 1216 Simultaneous peer-to-peer Connection establishment is supported by 1217 the Rendezvous() Action: 1219 Preconnection.Rendezvous() 1221 The Preconnection Object must be specified with both a Local Endpoint 1222 and a Remote Endpoint, and also the transport properties and security 1223 parameters needed for Protocol Stack selection. 1225 The Rendezvous() Action causes the Preconnection to listen on the 1226 Local Endpoint for an incoming Connection from the Remote Endpoint, 1227 while simultaneously trying to establish a Connection from the Local 1228 Endpoint to the Remote Endpoint. This corresponds to a TCP 1229 simultaneous open, for example. 1231 The Rendezvous() Action consumes the Preconnection. Once 1232 Rendezvous() has been called, no further properties may be added to 1233 the Preconnection, and no subsequent establishment call may be made 1234 on the Preconnection. 1236 Preconnection -> RendezvousDone 1238 The RendezvousDone<> Event occurs when a Connection is established 1239 with the Remote Endpoint. For Connection-oriented transports, this 1240 occurs when the transport-layer connection is established; for 1241 Connectionless transports, it occurs when the first Message is 1242 received from the Remote Endpoint. The resulting Connection is 1243 contained within the RendezvousDone<> Event, and is ready to use as 1244 soon as it is passed to the application via the Event. 1246 Preconnection -> RendezvousError 1248 An RendezvousError occurs either when the Preconnection cannot be 1249 fulfilled for listening, when the Local Endpoint or Remote Endpoint 1250 cannot be resolved, when no transport-layer connection can be 1251 established to the Remote Endpoint, or when the application is 1252 prohibited from rendezvous by policy. 1254 When using some NAT traversal protocols, e.g., Interactive 1255 Connectivity Establishment (ICE) [RFC5245], it is expected that the 1256 Local Endpoint will be configured with some method of discovering NAT 1257 bindings, e.g., a Session Traversal Utilities for NAT (STUN) server. 1258 In this case, the Local Endpoint may resolve to a mixture of local 1259 and server reflexive addresses. The Resolve() action on the 1260 Preconnection can be used to discover these bindings: 1262 []Preconnection := Preconnection.Resolve() 1264 The Resolve() call returns a list of Preconnection Objects, that 1265 represent the concrete addresses, local and server reflexive, on 1266 which a Rendezvous() for the Preconnection will listen for incoming 1267 Connections. These resolved Preconnections will share all other 1268 Properties with the Preconnection from which they are derived, though 1269 some Properties may be made more-specific by the resolution process. 1270 This list can be passed to a peer via a signalling protocol, such as 1271 SIP [RFC3261] or WebRTC [RFC7478], to configure the remote. 1273 6.4. Connection Groups 1275 Entangled Connections can be created using the Clone Action: 1277 Connection := Connection.Clone() 1279 Calling Clone on a Connection yields a group of two Connections: the 1280 parent Connection on which Clone was called, and the resulting cloned 1281 Connection. These connections are "entangled" with each other, and 1282 become part of a Connection Group. Calling Clone on any of these two 1283 Connections adds a third Connection to the Connection Group, and so 1284 on. Connections in a Connection Group share all Protocol Properties 1285 that are not applicable to a Message. 1287 In addition, incoming entangled Connections can be received by 1288 creating a Listener on an existing connection: 1290 Listener := Connection.Listen() 1292 Changing one of these Protocol Properties on one Connection in the 1293 group changes it for all others. Per-Message Protocol Properties, 1294 however, are not entangled. For example, changing "Timeout for 1295 aborting Connection" (see Section 11.1.4) on one Connection in a 1296 group will automatically change this Protocol Property for all 1297 Connections in the group in the same way. However, changing 1298 "Lifetime" (see Section 7.4.1) of a Message will only affect a single 1299 Message on a single Connection, entangled or not. 1301 If the underlying protocol supports multi-streaming, it is natural to 1302 use this functionality to implement Clone. In that case, entangled 1303 Connections are multiplexed together, giving them similar treatment 1304 not only inside endpoints but also across the end-to-end Internet 1305 path. 1307 If the underlying Protocol Stack does not support cloning, or cannot 1308 create a new stream on the given Connection, then attempts to clone a 1309 Connection will result in a CloneError: 1311 Connection -> CloneError<> 1313 The Protocol Property "Priority" operates on entangled Connections as 1314 in Section 7.4.2: when allocating available network capacity among 1315 Connections in a Connection Group, sends on Connections with higher 1316 Priority values will be prioritized over sends on Connections with 1317 lower Priority values. An ideal transport system implementation 1318 would assign each Connection the capacity share (M-N) x C / M, where 1319 N is the Connection's Priority value, M is the maximum Priority value 1320 used by all Connections in the group and C is the total available 1321 capacity. However, the Priority setting is purely advisory, and no 1322 guarantees are given about the way capacity is shared. Each 1323 implementation is free to implement a way to share capacity that it 1324 sees fit. 1326 7. Sending Data 1328 Once a Connection has been established, it can be used for sending 1329 data. Data is sent as Messages, which allow the application to 1330 communicate the boundaries of the data being transferred. By 1331 default, Send enqueues a complete Message, and takes optional per- 1332 Message properties (see Section 7.1). All Send actions are 1333 asynchronous, and deliver events (see Section 7.3). Sending partial 1334 Messages for streaming large data is also supported (see 1335 Section 7.5). 1337 Messages are sent on a Connection using the Send action: 1339 messageContext := Connection.Send(messageData, messageContext?, endOfMessage?) 1341 where messageData is the data object to send. 1343 The optional messageContext parameter supports per-message properties 1344 and is described in Section 7.4. If provided, the Message Context 1345 object returned is identical to the one that was passed. 1347 The optional endOfMessage parameter supports partial sending and is 1348 described in Section 7.5. 1350 The MessageContext returned by Send can be used to identify send 1351 events (see Section 7.3) related to a specific message or to inspect 1352 meta-data related to the message sent. 1354 7.1. Basic Sending 1356 The most basic form of sending on a connection involves enqueuing a 1357 single Data block as a complete Message, with default Message 1358 Properties. Message data is transferred as an array of bytes, and 1359 the resulting object contains both the byte array and the length of 1360 the array. 1362 messageData := "hello".bytes() 1363 Connection.Send(messageData) 1365 The interpretation of a Message to be sent is dependent on the 1366 implementation, and on the constraints on the Protocol Stacks implied 1367 by the Connection's transport properties. For example, a Message may 1368 be a single datagram for UDP Connections; or an HTTP Request for HTTP 1369 Connections. 1371 Some transport protocols can deliver arbitrarily sized Messages, but 1372 other protocols constrain the maximum Message size. Applications can 1373 query the Connection Property "Maximum Message size on send" 1374 (Section 11.1.8) to determine the maximum size allowed for a single 1375 Message. If a Message is too large to fit in the Maximum Message 1376 Size for the Connection, the Send will fail with a SendError event 1377 (Section 7.3.3). For example, it is invalid to send a Message over a 1378 UDP connection that is larger than the available datagram sending 1379 size. 1381 7.2. Sending Replies 1383 When a message is sent in response to a message received, the 1384 application may use the Message Context of the received Message to 1385 construct a Message Context for the reply. 1387 replyMessageContext := requestMessageContext.reply() 1389 By using the "replyMessageContext", the transport system is informed 1390 that the message to be sent is a response and can map the response to 1391 the same underlying transport connection or stream the request was 1392 received from. The concept of Message Contexts is described in 1393 Section 9. 1395 7.3. Send Events 1397 Like all Actions in this interface, the Send Action is asynchronous. 1398 There are several Events that can be delivered in response to Sending 1399 a Message. 1401 Note that if partial Sends are used (Section 7.5), there will still 1402 be exactly one Send Event delivered for each call to Send. For 1403 example, if a Message expired while two requests to Send data for 1404 that Message are outstanding, there will be two Expired events 1405 delivered. 1407 7.3.1. Sent 1409 Connection -> Sent 1411 The Sent Event occurs when a previous Send Action has completed, 1412 i.e., when the data derived from the Message has been passed down or 1413 through the underlying Protocol Stack and is no longer the 1414 responsibility of this interface. The exact disposition of the 1415 Message (i.e., whether it has actually been transmitted, moved into a 1416 buffer on the network interface, moved into a kernel buffer, and so 1417 on) when the Sent Event occurs is implementation-specific. The Sent 1418 Event contains an implementation-specific reference to the Message to 1419 which it applies. 1421 Sent Events allow an application to obtain an understanding of the 1422 amount of buffering it creates. That is, if an application calls the 1423 Send Action multiple times without waiting for a Sent Event, it has 1424 created more buffer inside the transport system than an application 1425 that always waits for the Sent Event before calling the next Send 1426 Action. 1428 7.3.2. Expired 1430 Connection -> Expired 1432 The Expired Event occurs when a previous Send Action expired before 1433 completion; i.e. when the Message was not sent before its Lifetime 1434 (see Section 7.4.1) expired. This is separate from SendError, as it 1435 is an expected behavior for partially reliable transports. The 1436 Expired Event contains an implementation-specific reference to the 1437 Message to which it applies. 1439 7.3.3. SendError 1441 Connection -> SendError 1443 A SendError occurs when a Message could not be sent due to an error 1444 condition: an attempt to send a Message which is too large for the 1445 system and Protocol Stack to handle, some failure of the underlying 1446 Protocol Stack, or a set of Message Properties not consistent with 1447 the Connection's transport properties. The SendError contains an 1448 implementation-specific reference to the Message to which it applies. 1450 7.4. Message Properties 1452 Applications may need to annotate the Messages they send with extra 1453 information to control how data is scheduled and processed by the 1454 transport protocols in the Connection. Therefore a message context 1455 containing these properties can be passed to the Send Action. For 1456 other uses of the message context, see Section 9. 1458 Note that message properties are per-Message, not per-Send if partial 1459 Messages are sent (Section 7.5). All data blocks associated with a 1460 single Message share properties specified in the Message Contexts. 1461 For example, it would not make sense to have the beginning of a 1462 Message expire, but allow the end of a Message to still be sent. 1464 A MessageContext object contains metadata for Messages to be sent or 1465 received. 1467 messageData := "hello".bytes() 1468 messageContext := NewMessageContext() 1469 messageContext.add(parameter, value) 1470 Connection.Send(messageData, messageContext) 1472 The simpler form of Send, which does not take any messageContext, is 1473 equivalent to passing a default MessageContext without adding any 1474 Message Properties to it. 1476 If an application wants to override Message Properties for a specific 1477 message, it can acquire an empty MessageContext Object and add all 1478 desired Message Properties to that Object. It can then reuse the 1479 same messageContext Object for sending multiple Messages with the 1480 same properties. 1482 Properties may be added to a MessageContext object only before the 1483 context is used for sending. Once a messageContext has been used 1484 with a Send call, modifying any of its properties is invalid. 1486 Message Properties may be inconsistent with the properties of the 1487 Protocol Stacks underlying the Connection on which a given Message is 1488 sent. For example, a Connection must provide reliability to allow 1489 setting an infinitie value for the lifetime property of a Message. 1490 Sending a Message with Message Properties inconsistent with the 1491 Selection Properties of the Connection yields an error. 1493 The following Message Properties are supported: 1495 7.4.1. Lifetime 1497 Name: msg-lifetime 1499 Type: Integer 1501 Recommended default: infinite 1502 Lifetime specifies how long a particular Message can wait to be sent 1503 to the remote endpoint before it is irrelevant and no longer needs to 1504 be (re-)transmitted. This is a hint to the transport system - it is 1505 not guaranteed that a Message will not be sent when its Lifetime has 1506 expired. 1508 Setting a Message's Lifetime to infinite indicates that the 1509 application does not wish to apply a time constraint on the 1510 transmission of the Message, but it does not express a need for 1511 reliable delivery; reliability is adjustable per Message via the 1512 "Reliable Data Transfer (Message)" property (see Section 7.4.7). The 1513 type and units of Lifetime are implementation-specific. 1515 7.4.2. Priority 1517 Name: msg-prio 1519 Type: Integer (non-negative) 1521 Recommended default: 100 1523 This property represents a hierarchy of priorities. It can specify 1524 the priority of a Message, relative to other Messages sent over the 1525 same Connection. 1527 A Message with Priority 0 will yield to a Message with Priority 1, 1528 which will yield to a Message with Priority 2, and so on. Priorities 1529 may be used as a sender-side scheduling construct only, or be used to 1530 specify priorities on the wire for Protocol Stacks supporting 1531 prioritization. 1533 Note that this property is not a per-message override of the 1534 connection Priority - see Section 11.1.3. Both Priority properties 1535 may interact, but can be used independently and be realized by 1536 different mechanisms. 1538 7.4.3. Ordered 1540 Name: msg-ordered 1542 Type: Boolean 1544 Default: true 1546 If true, it specifies that the receiver-side transport protocol stack 1547 only deliver the Message to the receiving application after the 1548 previous ordered Message which was passed to the same Connection via 1549 the Send Action, when such a Message exists. If false, the Message 1550 may be delivered to the receiving application out of order. This 1551 property is used for protocols that support preservation of data 1552 ordering, see Section 5.2.4, but allow out-of-order delivery for 1553 certain messages. 1555 7.4.4. Idempotent 1557 Name: idempotent 1559 Type: Boolean 1561 Default: false 1563 If true, it specifies that a Message is safe to send to the remote 1564 endpoint more than once for a single Send Action. It is used to mark 1565 data safe for certain 0-RTT establishment techniques, where 1566 retransmission of the 0-RTT data may cause the remote application to 1567 receive the Message multiple times. 1569 Note that for protocols that do not protect against duplicated 1570 messages, e.g., UDP, all messages MUST be marked as Idempotent. In 1571 order to enable protocol selection to choose such a protocol, 1572 Idempotent MUST be added to the TransportProperties passed to the 1573 Preconnection. If such a protocol was chosen, disabling Idempotent 1574 on individual messages MUST result in a SendError. 1576 7.4.5. Final 1578 Type: Boolean 1580 Name: final 1582 Default: false 1584 If true, this Message is the last one that the application will send 1585 on a Connection. This allows underlying protocols to indicate to the 1586 Remote Endpoint that the Connection has been effectively closed in 1587 the sending direction. For example, TCP-based Connections can send a 1588 FIN once a Message marked as Final has been completely sent, 1589 indicated by marking endOfMessage. Protocols that do not support 1590 signalling the end of a Connection in a given direction will ignore 1591 this property. 1593 Note that a Final Message must always be sorted to the end of a list 1594 of Messages. The Final property overrides Priority and any other 1595 property that would re-order Messages. If another Message is sent 1596 after a Message marked as Final has already been sent on a 1597 Connection, the Send Action for the new Message will cause a 1598 SendError Event. 1600 7.4.6. Corruption Protection Length 1602 Name: msg-checksum-len 1604 Type: Integer (non-negative with -1 as special value) 1606 Default: full coverage 1608 This property specifies the minimum length of the section of the 1609 Message, starting from byte 0, that the application requires to be 1610 delivered without corruption due to lower layer errors. It is used 1611 to specify options for simple integrity protection via checksums. A 1612 value of 0 means that no checksum is required, and -1 means that the 1613 entire Message is protected by a checksum. Only full coverage is 1614 guaranteed, any other requests are advisory. 1616 7.4.7. Reliable Data Transfer (Message) 1618 Name: msg-reliable 1620 Type: Boolean 1622 Default: true 1624 When true, this property specifies that a message should be sent in 1625 such a way that the transport protocol ensures all data is received 1626 on the other side without corruption. Changing the 'Reliable Data 1627 Transfer' property on Messages is only possible for Connections that 1628 were established with the Selection Property 'Reliable Data Transfer 1629 (Connection)' enabled. When this is not the case, changing it will 1630 generate an error. Disabling this property indicates that the 1631 transport system may disable retransmissions or other reliability 1632 mechanisms for this particular Message, but such disabling is not 1633 guaranteed. 1635 7.4.8. Message Capacity Profile Override 1637 Name: msg-capacity-profile 1639 Type: Enumeration 1641 This enumerated property specifies the application's preferred 1642 tradeoffs for sending this Message; it is a per-Message override of 1643 the Capacity Profile protocol and path selection property (see 1644 Section 11.1.10). 1646 The following values are valid for Transmission Profile: 1648 Default: No special optimizations of the tradeoff between delay, 1649 delay variation, and bandwidth efficiency should be made when 1650 sending this message. 1652 Low Latency: Response time (latency) should be optimized at the 1653 expense of efficiently using the available capacity when sending 1654 this message. This can be used by the system to disable the 1655 coalescing of multiple small Messages into larger packets (Nagle's 1656 algorithm); to prefer immediate acknowledgment from the peer 1657 endpoint when supported by the underlying transport; to signal a 1658 preference for lower-latency, higher-loss treatment; and so on. 1660 [TODO: This is inconsistent with {prop-cap-profile}} - needs to be 1661 fixed] 1663 7.4.9. Singular Transmission 1665 Name: singular-transmission 1667 Type: Boolean 1669 Default: false 1671 This property specifies that a message should be sent and received as 1672 a single packet without transport-layer segmentation or network-layer 1673 fragmentation. Attempts to send a message with this property set 1674 with a size greater to the transport's current estimate of its 1675 maximum transmission segment size will result in a "SendError". When 1676 used with transports supporting this functionality and running over 1677 IP version 4, the Don't Fragment bit will be set. 1679 7.5. Partial Sends 1681 It is not always possible for an application to send all data 1682 associated with a Message in a single Send Action. The Message data 1683 may be too large for the application to hold in memory at one time, 1684 or the length of the Message may be unknown or unbounded. 1686 Partial Message sending is supported by passing an endOfMessage 1687 boolean parameter to the Send Action. This value is always true by 1688 default, and the simpler forms of Send are equivalent to passing true 1689 for endOfMessage. 1691 The following example sends a Message in two separate calls to Send. 1693 messageContext := NewMessageContext() 1694 messageContext.add(parameter, value) 1696 messageData := "hel".bytes() 1697 endOfMessage := false 1698 Connection.Send(messageData, messageContext, endOfMessage) 1700 messageData := "lo".bytes() 1701 endOfMessage := true 1702 Connection.Send(messageData, messageContext, endOfMessage) 1704 All data sent with the same MessageContext object will be treated as 1705 belonging to the same Message, and will constitute an in-order series 1706 until the endOfMessage is marked. Once the end of the Message is 1707 marked, the MessageContext object may be re-used as a new Message 1708 with identical parameters. 1710 7.6. Batching Sends 1712 To reduce the overhead of sending multiple small Messages on a 1713 Connection, the application may want to batch several Send actions 1714 together. This provides a hint to the system that the sending of 1715 these Messages should be coalesced when possible, and that sending 1716 any of the batched Messages may be delayed until the last Message in 1717 the batch is enqueued. 1719 Connection.Batch( 1720 Connection.Send(messageData) 1721 Connection.Send(messageData) 1722 ) 1724 7.7. Send on Active Open: InitiateWithSend 1726 For application-layer protocols where the Connection initiator also 1727 sends the first message, the InitiateWithSend() action combines 1728 Connection initiation with a first Message sent: 1730 Connection := Preconnection.InitiateWithSend(messageData, messageContext?, timeout?) 1732 Whenever possible, a messageContext should be provided to declare the 1733 message passed to InitiateWithSend as idempotent. This allows the 1734 transport system to make use of 0-RTT establishment in case this is 1735 supported by the available protocol stacks. When the selected 1736 stack(s) do not support transmitting data upon connection 1737 establishment, InitiateWithSend is identical to Initiate() followed 1738 by Send(). 1740 Neither partial sends nor send batching are supported by 1741 InitiateWithSend(). 1743 The Events that may be sent after InitiateWithSend() are equivalent 1744 to those that would be sent by an invocation of Initate() followed 1745 immediately by an invocation of Send(), with the caveat that a send 1746 failure that occurs because the Connection could not be established 1747 will not result in a SendError separate from the InitiateError 1748 signaling the failure of Connection establishment. 1750 8. Receiving Data 1752 Once a Connection is established, it can be used for receiving data. 1753 As with sending, data is received in terms of Messages. Receiving is 1754 an asynchronous operation, in which each call to Receive enqueues a 1755 request to receive new data from the connection. Once data has been 1756 received, or an error is encountered, an event will be delivered to 1757 complete the Receive request (see Section 8.2). 1759 As with sending, the type of the Message to be passed is dependent on 1760 the implementation, and on the constraints on the Protocol Stacks 1761 implied by the Connection's transport parameters. 1763 8.1. Enqueuing Receives 1765 Receive takes two parameters to specify the length of data that an 1766 application is willing to receive, both of which are optional and 1767 have default values if not specified. 1769 Connection.Receive(minIncompleteLength?, maxLength?) 1771 By default, Receive will try to deliver complete Messages in a single 1772 event (Section 8.2.1). 1774 The application can set a minIncompleteLength value to indicates the 1775 smallest partial Message data size in bytes that should be delivered 1776 in response to this Receive. By default, this value is infinite, 1777 which means that only complete Messages should be delivered (see 1778 Section 8.2.2 and Section 10.6 for more information on how this is 1779 accomplished). If this value is set to some smaller value, the 1780 associated receive event will be triggered only when at least that 1781 many bytes are available, or the Message is complete with fewer 1782 bytes, or the system needs to free up memory. Applications should 1783 always check the length of the data delivered to the receive event 1784 and not assume it will be as long as minIncompleteLength in the case 1785 of shorter complete Messages or memory issues. 1787 The maxLength argument indicates the maximum size of a Message in 1788 bytes the application is currently prepared to receive. The default 1789 value for maxLength is infinite. If an incoming Message is larger 1790 than the minimum of this size and the maximum Message size on receive 1791 for the Connection's Protocol Stack, it will be delivered via 1792 ReceivedPartial events (Section 8.2.2). 1794 Note that maxLength does not guarantee that the application will 1795 receive that many bytes if they are available; the interface may 1796 return ReceivedPartial events with less data than maxLength according 1797 to implementation constraints. 1799 8.2. Receive Events 1801 Each call to Receive will be paired with a single Receive Event, 1802 which can be a success or an error. This allows an application to 1803 provide backpressure to the transport stack when it is temporarily 1804 not ready to receive messages. 1806 8.2.1. Received 1808 Connection -> Received 1810 A Received event indicates the delivery of a complete Message. It 1811 contains two objects, the received bytes as messageData, and the 1812 metadata and properties of the received Message as messageContext. 1814 The messageData object provides access to the bytes that were 1815 received for this Message, along with the length of the byte array. 1816 The messageContext is provided to enable retrieving metadata about 1817 the message and referring to the message, e.g., to send replies and 1818 map responses to their requests. See Section 9 for details. 1820 See Section 10.6 for handling Message framing in situations where the 1821 Protocol Stack only provides a byte-stream transport. 1823 8.2.2. ReceivedPartial 1825 Connection -> ReceivedPartial 1827 If a complete Message cannot be delivered in one event, one part of 1828 the Message may be delivered with a ReceivedPartial event. In order 1829 to continue to receive more of the same Message, the application must 1830 invoke Receive again. 1832 Multiple invocations of ReceivedPartial deliver data for the same 1833 Message by passing the same MessageContext, until the endOfMessage 1834 flag is delivered or a ReceiveError occurs. All partial blocks of a 1835 single Message are delivered in order without gaps. This event does 1836 not support delivering discontiguous partial Messages. 1838 If the minIncompleteLength in the Receive request was set to be 1839 infinite (indicating a request to receive only complete Messages), 1840 the ReceivedPartial event may still be delivered if one of the 1841 following conditions is true: 1843 o the underlying Protocol Stack supports message boundary 1844 preservation, and the size of the Message is larger than the 1845 buffers available for a single message; 1847 o the underlying Protocol Stack does not support message boundary 1848 preservation, and the Message Framer (see Section 10.6) cannot 1849 determine the end of the message using the buffer space it has 1850 available; or 1852 o the underlying Protocol Stack does not support message boundary 1853 preservation, and no Message Framer was supplied by the 1854 application 1856 Note that in the absence of message boundary preservation or a 1857 Message Framer, all bytes received on the Connection will be 1858 represented as one large Message of indeterminate length. 1860 8.2.3. ReceiveError 1862 Connection -> ReceiveError 1864 A ReceiveError occurs when data is received by the underlying 1865 Protocol Stack that cannot be fully retrieved or parsed, or when some 1866 other indication is received that reception has failed. Such 1867 conditions that irrevocably lead to the termination of the Connection 1868 are signaled using ConnectionError instead (see Section 12). 1870 The ReceiveError event passes an optional associated MessageContext. 1871 This may indicate that a Message that was being partially received 1872 previously, but had not completed, encountered an error and will not 1873 be completed. 1875 8.3. Receive Message Properties 1877 Each Message Context may contain metadata from protocols in the 1878 Protocol Stack; which metadata is available is Protocol Stack 1879 dependent. These are exposed though additional read-only Message 1880 Properties that can be queried from the MessageContext object (see 1881 Section 9) passed by the receive event. The following metadata 1882 values are supported: 1884 8.3.1. ECN 1886 When available, Message metadata carries the value of the Explicit 1887 Congestion Notification (ECN) field. This information can be used 1888 for logging and debugging purposes, and for building applications 1889 which need access to information about the transport internals for 1890 their own operation. 1892 8.3.2. Early Data 1894 In some cases it may be valuable to know whether data was read as 1895 part of early data transfer (before connection establishment has 1896 finished). This is useful if applications need to treat early data 1897 separately, e.g., if early data has different security properties 1898 than data sent after connection establishment. In the case of TLS 1899 1.3, client early data can be replayed maliciously (see [RFC8446]). 1900 Thus, receivers may wish to perform additional checks for early data 1901 to ensure it is idempotent or not replayed. If TLS 1.3 is available 1902 and the recipient Message was sent as part of early data, the 1903 corresponding metadata carries a flag indicating as such. If early 1904 data is enabled, applications should check this metadata field for 1905 Messages received during connection establishment and respond 1906 accordingly. 1908 8.3.3. Receiving Final Messages 1910 The Message Context can indicate whether or not this Message is the 1911 Final Message on a Connection. For any Message that is marked as 1912 Final, the application can assume that there will be no more Messages 1913 received on the Connection once the Message has been completely 1914 delivered. This corresponds to the Final property that may be marked 1915 on a sent Message Section 7.4.5. 1917 Some transport protocols and peers may not support signaling of the 1918 Final property. Applications therefore should not rely on receiving 1919 a Message marked Final to know that the other endpoint is done 1920 sending on a connection. 1922 Any calls to Receive once the Final Message has been delivered will 1923 result in errors. 1925 9. Message Contexts 1927 Using the MessageContext object, the application can set and retrieve 1928 meta-data of the message, including Message Properties (see 1929 Section 7.4) and framing meta-data (see Section 10.3). Therefore, a 1930 MessageContext object can be passed to the Send action and is retuned 1931 by each Send and Receive related events. 1933 Message properties can be set and queried using the Message Context: 1935 MessageContext.add(scope?, parameter, value) 1936 PropertyValue := MessageContext.get(scope?, property) 1938 To get or set Message Properties, the optional scope parameter is 1939 left empty, for framing meta-data, the framer is passed. 1941 For MessageContexts returned by send events (see Section 7.3) and 1942 receive events (see Section 8.2), the application can query 1943 information about the local and remote endpoint: 1945 RemoteEndpoint := MessageContext.GetRemoteEndpoint() 1946 LocalEndpoint := MessageContext.GetLocalEndpoint() 1948 Message Contexts can also be used to send messages that are flagged 1949 as a reply to other messages, see Section 7.2 for details. If the 1950 message received was send by the remote endpoint as a reply to an 1951 earlier message and the transports provides this information, the 1952 MessageContext of the original request can be accessed using the 1953 Message Context of the reply: 1955 RequestMessageContext := MessageContext.GetOriginalRequest() 1957 10. Message Framers 1959 Message Framers are pieces of code that define simple transformations 1960 between application Message data and raw transport protocol data. A 1961 Framer can encapsulate or encode outbound Messages, and decapsulate 1962 or decode inbound data into Messages. 1964 Message Framers allow message boundaries to be preserved when using a 1965 Connection object, even when using byte-stream transports. This 1966 facility is designed based on the fact that many of the current 1967 application protocols evolved over TCP, which does not provide 1968 message boundary preservation, and since many of these protocols 1969 require message boundaries to function, each application layer 1970 protocol has defined its own framing. 1972 While many protocols can be represented as Message Framers, for the 1973 purposes of the Transport Services interface these are ways for 1974 applications or application frameworks to define their own Message 1975 parsing to be included within a Connection's Protocol Stack. As an 1976 example, TLS can serve the purpose of framing data over TCP, but is 1977 exposed as a protocol natively supported by the Transport Services 1978 interface. 1980 Most Message Framers fall into one of two categories: - Header- 1981 prefixed record formats, such as a basic Type-Length-Value (TLV) 1982 structure - Delimeter-separated formats, such as HTTP/1.1. 1984 Note that while Message Framers add the most value when placed above 1985 a protocol that otherwise does not preserve message boundaries, they 1986 can also be used with datagram- or message-based protocols. In these 1987 cases, they add an additional transformation to further encode or 1988 encapsulate, and can potentially support packing multiple 1989 application-layer Messages into individual transport datagrams. 1991 10.1. Defining Message Framers 1993 A Message Framer is primarily defined by the set of code that handles 1994 events for a framer implementation, specifically how it handles 1995 inbound and outbound data parsing. 1997 Applications can instantiate a Message Framer upon which they will 1998 receive framing events, or use a Message Framer defined by another 1999 library. 2001 framer := NewMessageFramer() 2003 Message Framer objects will deliver events to code that is written 2004 either as part of the application or a helper library. This piece of 2005 code will be referred to as the "framer implementation". 2007 10.2. Adding Message Framers to Connections 2009 The Message Framer object can be added to one or more Preconnections 2010 to run on top of transport protocols. Multiple Framers may be added. 2011 If multiple Framers are added, the last one added runs first when 2012 framing outbound messages, and last when parsing inbound data. 2014 Preconnection.AddFramer(framer) 2016 Framers have the ability to also dynamically modify Protocol Stacks, 2017 as described in Section 10.4. 2019 10.3. Framing Meta-Data 2021 When sending Messages, applications can add specific Message values 2022 to a MessageContext (Section 9) that is intended for a Framer. This 2023 can be used, for example, to set the type of a Message for a TLV 2024 format. The namespace of values is custom for each unique Message 2025 Framer. 2027 messageContext := NewMessageContext() 2028 messageContext.add(framer, key, value) 2029 Connection.Send(messageData, messageContext) 2031 When an application receives a MessageContext in a Receive event, it 2032 can also look to see if a value was set by a specific Message Framer. 2034 messageContext.get(framer, key) -> value 2036 10.4. Message Framer Lifetime 2038 When a Connection establishment attempt begins, an event is delivered 2039 to notify the framer implementation that a new Connection is being 2040 created. Similarly, a stop event is delivered when a Connection is 2041 being torn down. The framer implementation can use the Connection 2042 object to look up specific properties of the Connection or the 2043 network being used that may influence how to frame Messages. 2045 MessageFramer -> Start(Connection) 2046 MessageFramer -> Stop(Connection) 2048 When Message Framer generates a "Start" event, the framer 2049 implementation has the opportunity to start writing some data prior 2050 to the Connection delivering its "Ready" event. This allows the 2051 implementation to communicate control data to the remote endpoint 2052 that can be used to parse Messages. 2054 MessageFramer.MakeConnectionReady(Connection) 2056 At any time if the implementation encounters a fatal error, it can 2057 also cause the Connection to fail and provide an error. 2059 MessageFramer.FailConnection(Connection, Error) 2061 Before an implementation marks a Message Framer as ready, it can also 2062 dynamically add a protocol or framer above it in the stack. This 2063 allows protocols like STARTTLS, that need to add TLS conditionally, 2064 to modify the Protocol Stack based on a handshake result. 2066 otherFramer := NewMessageFramer() 2067 MessageFramer.PrependFramer(Connection, otherFramer) 2069 10.5. Sender-side Message Framing 2071 Message Framers generate an event whenever a Connection sends a new 2072 Message. 2074 MessageFramer -> NewSentMessage 2075 Upon receiving this event, a framer implementation is responsible for 2076 performing any necessary transformations and sending the resulting 2077 data to the next protocol. Implementations SHOULD ensure that there 2078 is a way to pass the original data through without copying to improve 2079 performance. 2081 MessageFramer.Send(Connection, Data) 2083 To provide an example, a simple protocol that adds a length as a 2084 header would receive the "NewSentMessage" event, create a data 2085 representation of the length of the Message data, and then send a 2086 block of data that is the concatenation of the length header and the 2087 original Message data. 2089 10.6. Receiver-side Message Framing 2091 In order to parse an received flow of data into Messages, the Message 2092 Framer notifies the framer implementation whenever new data is 2093 available to parse. 2095 MessageFramer -> HandleReceivedData 2097 Upon receiving this event, the framer implementation can inspect the 2098 inbound data. The data is parsed from a particular cursor 2099 representing the unprocessed data. The application requests a 2100 specific amount of data it needs to have available in order to parse. 2101 If the data is not available, the parse fails. 2103 MessageFramer.Parse(Connection, MinimumIncompleteLength, MaximumLength) -> (Data, MessageContext, IsEndOfMessage) 2105 The framer implementation can directly advance the receive cursor 2106 once it has parsed data to effectively discard data (for example, 2107 discard a header once the content has been parsed). 2109 To deliver a Message to the application, the framer implementation 2110 can either directly deliever data that it has allocated, or deliver a 2111 range of data directly from the underlying transport and 2112 simulatenously advance the receive cursor. 2114 MessageFramer.AdvanceReceiveCursor(Connection, Length) 2115 MessageFramer.DeliverAndAdvanceReceiveCursor(Connection, MessageContext, Length, IsEndOfMessage) 2116 MessageFramer.Deliver(Connection, MessageContext, Data, IsEndOfMessage) 2118 Note that "MessageFramer.DeliverAndAdvanceReceiveCursor" allows the 2119 framer implementation to earmark bytes as part of a Message even 2120 before they are received by the transport. This allows the delivery 2121 of very large Messages without requiring the implementation to 2122 directly inspect all of the bytes. 2124 To provide an example, a simple protocol that parses a length as a 2125 header value would receive the "HandleReceivedData" event, and call 2126 "Parse" with a minimum and maximum set to the length of the header 2127 field. Once the parse succeeded, it would call 2128 "AdvanceReceiveCursor" with the length of the header field, and then 2129 call "DeliverAndAdvanceReceiveCursor" with the length of the body 2130 that was parsed from the header, marking the new Message as complete. 2132 11. Managing Connections 2134 During pre-establishment and after establishment, connections can be 2135 configured and queried using Connection Properties, and asynchronous 2136 information may be available about the state of the connection via 2137 Soft Errors. 2139 Connection Properties represent the configuration and state of the 2140 selected Protocol Stack(s) backing a Connection. These Connection 2141 Properties may be Generic, applying regardless of transport protocol, 2142 or Specific, applicable to a single implementation of a single 2143 transport protocol stack. Generic Connection Properties are defined 2144 in Section 11.1 below. Specific Protocol Properties are defined in a 2145 transport- and implementation-specific way, and must not be assumed 2146 to apply across different protocols. Attempts to set Specific 2147 Protocol Properties on a protocol stack not containing that specific 2148 protocol are simply ignored, and do not raise an error; however, too 2149 much reliance by an application on Specific Protocol Properties may 2150 significantly reduce the flexibility of a transport services 2151 implementation. 2153 The application can set and query Connection Properties on a per- 2154 Connection basis. Connection Properties that are not read-only can 2155 be set during pre-establishment (see Section 5.2), as well as on 2156 connections directly using the SetProperty action: 2158 Connection.SetProperty(property, value) 2160 At any point, the application can query Connection Properties. 2162 ConnectionProperties := Connection.GetProperties() 2164 Depending on the status of the connection, the queried Connection 2165 Properties will include different information: 2167 o The connection state, which can be one of the following: 2168 Establishing, Established, Closing, or Closed. 2170 o Whether the connection can be used to send data. A connection can 2171 not be used for sending if the connection was created with the 2172 Selection Property "Direction of Communication" set to 2173 "unidirectional receive" or if a Message marked as "Final" was 2174 sent over this connection, see Section 7.4.5. 2176 o Whether the connection can be used to receive data. A connection 2177 can not be used for reading if the connection was created with the 2178 Selection Property "Direction of Communication" set to 2179 "unidirectional send" or if a Message marked as "Final" was 2180 received, see Section 8.3.3. The latter is only supported by 2181 certain transport protocols, e.g., by TCP as half-closed 2182 connection. 2184 o For Connections that are Establishing: Transport Properties that 2185 the application specified on the Preconnection, see Section 5.2. 2187 o For Connections that are Established, Closing, or Closed: 2188 Selection (Section 5.2) and Connection Properties (Section 11.1) 2189 of the actual protocols that were selected and instantiated. 2190 Selection Properties indicate whether or not the Connection has or 2191 offers a certain Selection Property. Note that the actually 2192 instantiated protocol stack may not match all Protocol Selection 2193 Properties that the application specified on the Preconnection. 2194 For example, a certain Protocol Selection Property that an 2195 application specified as Preferred may not actually be present in 2196 the chosen protocol stack because none of the currently available 2197 transport protocols had this feature. 2199 o For Connections that are Established, additional properties of the 2200 path(s) in use. These properties can be derived from the local 2201 provisioning domain [RFC7556], measurements by the Protocol Stack, 2202 or other sources. 2204 11.1. Generic Connection Properties 2206 The Connection Properties defined as independent, and available on 2207 all Connections are defined in the subsections below. 2209 Note that many protocol properties have a corresponding selection 2210 property, which prefers protocols providing a specific transport 2211 feature that controlled by that protocol property. [EDITOR'S NOTE: 2212 todo: add these cross-references up to Section 5.2] 2214 11.1.1. Retransmission Threshold Before Excessive Retransmission 2215 Notification 2217 Name: retransmit-notify-threshold 2219 Type: Integer 2220 Default: -1 2222 This property specifies after how many retransmissions to inform the 2223 application about "Excessive Retransmissions". The special value -1 2224 means that this notification is disabled. 2226 11.1.2. Required Minimum Corruption Protection Coverage for Receiving 2228 Name: recv-checksum-len 2230 Type: Integer 2232 Default: -1 2234 This property specifies the part of the received data that needs to 2235 be covered by a checksum. It is given in Bytes. A value of 0 means 2236 that no checksum is required, and the special value -1 indicates full 2237 checksum coverage. 2239 11.1.3. Priority (Connection) 2241 Name: conn-prio 2243 Type: Integer 2245 Default: 100 2247 This Property is a non-negative integer representing the relative 2248 inverse priority of this Connection relative to other Connections in 2249 the same Connection Group. It has no effect on Connections not part 2250 of a Connection Group. As noted in Section 6.4, this property is not 2251 entangled when Connections are cloned. 2253 11.1.4. Timeout for Aborting Connection 2255 Name: conn-timeout 2257 Type: Numeric 2259 Default: -1 2261 This property specifies how long to wait before deciding that a 2262 Connection has failed when trying to reliably deliver data to the 2263 destination. Adjusting this Property will only take effect when the 2264 underlying stack supports reliability. The special value -1 means 2265 that this timeout is not scheduled to happen. 2267 11.1.5. Connection Group Transmission Scheduler 2269 Name: conn-scheduler 2271 Type: Enumeration 2273 Default: Weighted Fair Queueing (see Section 3.6 in [RFC8260]) 2275 This property specifies which scheduler should be used among 2276 Connections within a Connection Group, see Section 6.4. The set of 2277 schedulers can be taken from [RFC8260]. 2279 11.1.6. Maximum Message Size Concurrent with Connection Establishment 2281 Name: zero-rtt-msg-max-len 2283 Type: Integer (read only) 2285 This property represents the maximum Message size that can be sent 2286 before or during Connection establishment, see also Section 7.4.4. 2287 It is given in Bytes. 2289 11.1.7. Maximum Message Size Before Fragmentation or Segmentation 2291 Name: singular-transmission-msg-max-len 2293 Type: Integer (read only) 2295 This property, if applicable, represents the maximum Message size 2296 that can be sent without incurring network-layer fragmentation or 2297 transport layer segmentation at the sender. 2299 11.1.8. Maximum Message Size on Send 2301 Name: send-msg-max-len 2303 Type: Integer (read only) 2305 This property represents the maximum Message size that can be sent. 2307 11.1.9. Maximum Message Size on Receive 2309 Name: recv-msg-max-len 2311 Type: Integer (read only) 2313 This numeric property represents the maximum Message size that can be 2314 received. 2316 11.1.10. Capacity Profile 2318 Name: conn-capacity-profile 2320 This property specifies the desired network treatment for traffic 2321 sent by the application and the tradeoffs the application is prepared 2322 to make in path and protocol selection to receive that desired 2323 treatment. When the capacity profile is set to a value other than 2324 Default, the transport system should select paths and profiles to 2325 optimize for the capacity profile specified. The following values 2326 are valid for the Capacity Profile: 2328 Default: The application makes no representation about its expected 2329 capacity profile. No special optimizations of the tradeoff 2330 between delay, delay variation, and bandwidth efficiency should be 2331 made when selecting and configuring transport protocol stacks. 2332 Transport system implementations that map the requested capacity 2333 profile onto per-connection DSCP signaling without multiplexing 2334 SHOULD assign the DSCP Default Forwarding [RFC2474] PHB; when the 2335 Connection is multiplexed, the guidelines in Section 6 of 2336 [RFC7657] apply. 2338 Scavenger: The application is not interactive. It expects to send 2339 and/or receive data without any urgency. This can, for example, 2340 be used to select protocol stacks with scavenger transmission 2341 control and/or to assign the traffic to a lower-effort service. 2342 Transport system implementations that map the requested capacity 2343 profile onto per-connection DSCP signaling without multiplexing 2344 SHOULD assign the DSCP Less than Best Effort [LE-PHB] PHB; when 2345 the Connection is multiplexed, the guidelines in Section 6 of 2346 [RFC7657] apply. 2348 Low Latency/Interactive: The application is interactive, and prefers 2349 loss to latency. Response time should be optimized at the expense 2350 of bandwidth efficiency and delay variation when sending on this 2351 connection. This can be used by the system to disable the 2352 coalescing of multiple small Messages into larger packets (Nagle's 2353 algorithm); to prefer immediate acknowledgment from the peer 2354 endpoint when supported by the underlying transport; and so on. 2355 Transport system implementations that map the requested capacity 2356 profile onto per-connection DSCP signaling without multiplexing 2357 SHOULD assign the DSCP Expedited Forwarding [RFC3246] PHB; when 2358 the Connection is multiplexed, the guidelines in Section 6 of 2359 [RFC7657] apply. 2361 Low Latency/Non-Interactive: The application prefers loss to latency 2362 but is not interactive. Response time should be optimized at the 2363 expense of bandwidth efficiency and delay variation when sending 2364 on this connection.Transport system implementations that map the 2365 requested capacity profile onto per-connection DSCP signaling 2366 without multiplexing SHOULD assign a DSCP Assured Forwarding 2367 (AF21,AF22,AF23,AF24) [RFC2597] PHB; when the Connection is 2368 multiplexed, the guidelines in Section 6 of [RFC7657] apply. 2370 Constant-Rate Streaming: The application expects to send/receive 2371 data at a constant rate after Connection establishment. Delay and 2372 delay variation should be minimized at the expense of bandwidth 2373 efficiency. This implies that the Connection may fail if the 2374 desired rate cannot be maintained across the Path. A transport 2375 may interpret this capacity profile as preferring a circuit 2376 breaker [RFC8084] to a rate-adaptive congestion controller. 2377 Transport system implementations that map the requested capacity 2378 profile onto per-connection DSCP signaling without multiplexing 2379 SHOULD assign a DSCP Assured Forwarding (AF31,AF32,AF33,AF34) 2380 [RFC2597] PHB; when the Connection is multiplexed, the guidelines 2381 in Section 6 of [RFC7657] apply. 2383 High Throughput Data: The application expects to send/receive data 2384 at the maximum rate allowed by its congestion controller over a 2385 relatively long period of time. Transport system implementations 2386 that map the requested capacity profile onto per-connection DSCP 2387 signaling without multiplexing SHOULD assign a DSCP Assured 2388 Forwarding (AF11,AF12,AF13,AF14) [RFC2597] PHB per Section 4.8 of 2389 [RFC4594]. When the Connection is multiplexed, the guidelines in 2390 Section 6 of [RFC7657] apply. 2392 The Capacity Profile for a selected protocol stack may be modified on 2393 a per-Message basis using the Transmission Profile Message Property; 2394 see Section 7.4.8. 2396 11.1.11. Bounds on Send or Receive Rate 2398 Name: max-send-rate / max-recv-rate 2400 Type: Numeric / Numeric 2402 Default: -1 / -1 (unlimited, for both values) 2404 This property specifies an upper-bound rate that a transfer is not 2405 expected to exceed (even if flow control and congestion control allow 2406 higher rates), and/or a lower-bound rate below which the application 2407 does not deem a data transfer useful. It is given in bits per 2408 second. The special value -1 indicates that no bound is specified. 2410 11.1.12. TCP-specific Property: User Timeout 2412 This property specifies, for the case TCP becomes the chosen 2413 transport protocol: 2415 Advertised User Timeout (name: tcp.user-timeout-value, type: 2416 Integer): 2417 a time value (default: the TCP default) to be advertised via the 2418 User Timeout Option (UTO) for the TCP at the remote endpoint to 2419 adapt its own "Timeout for aborting Connection" (see 2420 Section 11.1.4) value accordingly. 2422 User Timeout Enabled (name: tcp.user-timeout, type: Boolean): a bool 2423 ean (default false) to control whether the UTO option is enabled 2424 for a connection. This applies to both sending and receiving. 2426 Changeable (name: tcp.user-timeout-recv, type: Boolean): a boolean 2427 (default true) which controls whether the "Timeout for aborting 2428 Connection" (see Section 11.1.4) may be changed based on a UTO 2429 option received from the remote peer. This boolean becomes false 2430 when "Timeout for aborting Connection" (see Section 11.1.4) is 2431 used. 2433 All of the above parameters are optional (e.g., it is possible to 2434 specify "User Timeout Enabled" as true, but not specify an Advertised 2435 User Timeout value; in this case, the TCP default will be used). 2437 11.2. Soft Errors 2439 Asynchronous introspection is also possible, via the SoftError Event. 2440 This event informs the application about the receipt of an ICMP error 2441 message related to the Connection. This will only happen if the 2442 underlying protocol stack supports access to soft errors; however, 2443 even if the underlying stack supports it, there is no guarantee that 2444 a soft error will be signaled. 2446 Connection -> SoftError<> 2448 11.3. Excessive retransmissions 2450 This event notifies the application of excessive retransmissions, 2451 based on a configured threshold (see Section 11.1.1). This will only 2452 happen if the underlying protocol stack supports reliability and, 2453 with it, such notifications. 2455 Connection -> ExcessiveRetransmission<> 2457 12. Connection Termination 2459 Close terminates a Connection after satisfying all the requirements 2460 that were specified regarding the delivery of Messages that the 2461 application has already given to the transport system. For example, 2462 if reliable delivery was requested for a Message handed over before 2463 calling Close, the transport system will ensure that this Message is 2464 indeed delivered. If the Remote Endpoint still has data to send, it 2465 cannot be received after this call. 2467 Connection.Close() 2469 The Closed Event can inform the application that the Remote Endpoint 2470 has closed the Connection; however, there is no guarantee that a 2471 remote Close will indeed be signaled. 2473 Connection -> Closed<> 2475 Abort terminates a Connection without delivering remaining data: 2477 Connection.Abort() 2479 A ConnectionError informs the application that data to could not be 2480 delivered after a timeout, or the other side has aborted the 2481 Connection; however, there is no guarantee that an Abort will indeed 2482 be signaled. 2484 Connection -> ConnectionError<> 2486 13. Connection State and Ordering of Operations and Events 2488 As this interface is designed to be independent of an 2489 implementation's concurrency model, the details of how exactly 2490 actions are handled, and on which threads/callbacks events are 2491 dispatched, are implementation dependent. 2493 Each transition of connection state is associated with one of more 2494 events: 2496 o Ready<> occurs when a Connection created with Initiate() or 2497 InitiateWithSend() transitions to Established state. 2499 o ConnectionReceived<> occurs when a Connection created with 2500 Listen() transitions to Established state. 2502 o RendezvousDone<> occurs when a Connection created with 2503 Rendezvous() transitions to Established state. 2505 o Closed<> occurs when a Connection transitions to Closed state 2506 without error. 2508 o InitiateError<> occurs when a Connection created with Initiate() 2509 transitions from Establishing state to Closed state due to an 2510 error. 2512 o ConnectionError<> occurs when a Connection transitions to Closed 2513 state due to an error in all other circumstances. 2515 The interface provides the following guarantees about the ordering of 2516 operations: 2518 o Sent<> events will occur on a Connection in the order in which the 2519 Messages were sent (i.e., delivered to the kernel or to the 2520 network interface, depending on implementation). 2522 o Received<> will never occur on a Connection before it is 2523 Established; i.e. before a Ready<> event on that Connection, or a 2524 ConnectionReceived<> or RendezvousDone<> containing that 2525 Connection. 2527 o No events will occur on a Connection after it is Closed; i.e., 2528 after a Closed<> event, an InitiateError<> or ConnectionError<> on 2529 that connection. To ensure this ordering, Closed<> will not occur 2530 on a Connection while other events on the Connection are still 2531 locally outstanding (i.e., known to the interface and waiting to 2532 be dealt with by the application). ConnectionError<> may occur 2533 after Closed<>, but the interface must gracefully handle all cases 2534 where application ignores these errors. 2536 14. IANA Considerations 2538 RFC-EDITOR: Please remove this section before publication. 2540 This document has no Actions for IANA. Later versions of this 2541 document may create IANA registries for generic transport property 2542 names and transport property namespaces (see Section 4.2.1). 2544 15. Security Considerations 2546 This document describes a generic API for interacting with a 2547 transport services (TAPS) system. Part of this API includes 2548 configuration details for transport security protocols, as discussed 2549 in Section 5.3. It does not recommend use (or disuse) of specific 2550 algorithms or protocols. Any API-compatible transport security 2551 protocol should work in a TAPS system. 2553 16. Acknowledgements 2555 This work has received funding from the European Union's Horizon 2020 2556 research and innovation programme under grant agreements No. 644334 2557 (NEAT) and No. 688421 (MAMI). 2559 This work has been supported by Leibniz Prize project funds of DFG - 2560 German Research Foundation: Gottfried Wilhelm Leibniz-Preis 2011 (FKZ 2561 FE 570/4-1). 2563 This work has been supported by the UK Engineering and Physical 2564 Sciences Research Council under grant EP/R04144X/1. 2566 Thanks to Stuart Cheshire, Josh Graessley, David Schinazi, and Eric 2567 Kinnear for their implementation and design efforts, including Happy 2568 Eyeballs, that heavily influenced this work. Thanks to Laurent Chuat 2569 and Jason Lee for initial work on the Post Sockets interface, from 2570 which this work has evolved. 2572 17. References 2574 17.1. Normative References 2576 [I-D.ietf-taps-arch] 2577 Pauly, T., Trammell, B., Brunstrom, A., Fairhurst, G., 2578 Perkins, C., Tiesel, P., and C. Wood, "An Architecture for 2579 Transport Services", draft-ietf-taps-arch-03 (work in 2580 progress), March 2019. 2582 [I-D.ietf-tsvwg-rtcweb-qos] 2583 Jones, P., Dhesikan, S., Jennings, C., and D. Druta, "DSCP 2584 Packet Markings for WebRTC QoS", draft-ietf-tsvwg-rtcweb- 2585 qos-18 (work in progress), August 2016. 2587 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2588 Requirement Levels", BCP 14, RFC 2119, 2589 DOI 10.17487/RFC2119, March 1997, 2590 . 2592 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2593 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 2594 May 2017, . 2596 [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol 2597 Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, 2598 . 2600 17.2. Informative References 2602 [I-D.ietf-taps-minset] 2603 Welzl, M. and S. Gjessing, "A Minimal Set of Transport 2604 Services for End Systems", draft-ietf-taps-minset-11 (work 2605 in progress), September 2018. 2607 [I-D.ietf-taps-transport-security] 2608 Wood, C., Enghardt, T., Pauly, T., Perkins, C., and K. 2609 Rose, "A Survey of Transport Security Protocols", draft- 2610 ietf-taps-transport-security-06 (work in progress), March 2611 2019. 2613 [LE-PHB] Bless, R., "A Lower Effort Per-Hop Behavior (LE PHB) for 2614 Differentiated Services", draft-ietf-tsvwg-le-phb-10 (work 2615 in progress), March 2019. 2617 [RFC0793] Postel, J., "Transmission Control Protocol", STD 7, 2618 RFC 793, DOI 10.17487/RFC0793, September 1981, 2619 . 2621 [RFC2474] Nichols, K., Blake, S., Baker, F., and D. Black, 2622 "Definition of the Differentiated Services Field (DS 2623 Field) in the IPv4 and IPv6 Headers", RFC 2474, 2624 DOI 10.17487/RFC2474, December 1998, 2625 . 2627 [RFC2597] Heinanen, J., Baker, F., Weiss, W., and J. Wroclawski, 2628 "Assured Forwarding PHB Group", RFC 2597, 2629 DOI 10.17487/RFC2597, June 1999, 2630 . 2632 [RFC2914] Floyd, S., "Congestion Control Principles", BCP 41, 2633 RFC 2914, DOI 10.17487/RFC2914, September 2000, 2634 . 2636 [RFC3246] Davie, B., Charny, A., Bennet, J., Benson, K., Le Boudec, 2637 J., Courtney, W., Davari, S., Firoiu, V., and D. 2638 Stiliadis, "An Expedited Forwarding PHB (Per-Hop 2639 Behavior)", RFC 3246, DOI 10.17487/RFC3246, March 2002, 2640 . 2642 [RFC3261] Rosenberg, J., Schulzrinne, H., Camarillo, G., Johnston, 2643 A., Peterson, J., Sparks, R., Handley, M., and E. 2644 Schooler, "SIP: Session Initiation Protocol", RFC 3261, 2645 DOI 10.17487/RFC3261, June 2002, 2646 . 2648 [RFC4594] Babiarz, J., Chan, K., and F. Baker, "Configuration 2649 Guidelines for DiffServ Service Classes", RFC 4594, 2650 DOI 10.17487/RFC4594, August 2006, 2651 . 2653 [RFC5245] Rosenberg, J., "Interactive Connectivity Establishment 2654 (ICE): A Protocol for Network Address Translator (NAT) 2655 Traversal for Offer/Answer Protocols", RFC 5245, 2656 DOI 10.17487/RFC5245, April 2010, 2657 . 2659 [RFC7478] Holmberg, C., Hakansson, S., and G. Eriksson, "Web Real- 2660 Time Communication Use Cases and Requirements", RFC 7478, 2661 DOI 10.17487/RFC7478, March 2015, 2662 . 2664 [RFC7556] Anipko, D., Ed., "Multiple Provisioning Domain 2665 Architecture", RFC 7556, DOI 10.17487/RFC7556, June 2015, 2666 . 2668 [RFC7657] Black, D., Ed. and P. Jones, "Differentiated Services 2669 (Diffserv) and Real-Time Communication", RFC 7657, 2670 DOI 10.17487/RFC7657, November 2015, 2671 . 2673 [RFC8084] Fairhurst, G., "Network Transport Circuit Breakers", 2674 BCP 208, RFC 8084, DOI 10.17487/RFC8084, March 2017, 2675 . 2677 [RFC8095] Fairhurst, G., Ed., Trammell, B., Ed., and M. Kuehlewind, 2678 Ed., "Services Provided by IETF Transport Protocols and 2679 Congestion Control Mechanisms", RFC 8095, 2680 DOI 10.17487/RFC8095, March 2017, 2681 . 2683 [RFC8260] Stewart, R., Tuexen, M., Loreto, S., and R. Seggelmann, 2684 "Stream Schedulers and User Message Interleaving for the 2685 Stream Control Transmission Protocol", RFC 8260, 2686 DOI 10.17487/RFC8260, November 2017, 2687 . 2689 Appendix A. Additional Properties 2691 The interface specified by this document represents the minimal 2692 common interface to an endpoint in the transport services 2693 architecture [I-D.ietf-taps-arch], based upon that architecture and 2694 on the minimal set of transport service features elaborated in 2695 [I-D.ietf-taps-minset]. However, the interface has been designed 2696 with extension points to allow the implementation of features beyond 2697 those in the minimal common interface: Protocol Selection Properties, 2698 Path Selection Properties, and Message Properties are open sets. 2699 Implementations of the interface are free to extend these sets to 2700 provide additional expressiveness to applications written on top of 2701 them. 2703 This appendix enumerates a few additional properties that could be 2704 used to enhance transport protocol and/or path selection, or the 2705 transmission of messages given a Protocol Stack that implements them. 2706 These are not part of the interface, and may be removed from the 2707 final document, but are presented here to support discussion within 2708 the TAPS working group as to whether they should be added to a future 2709 revision of the base specification. 2711 A.1. Experimental Transport Properties 2713 The following Transport Properties might be made available in 2714 addition to those specified in Section 5.2, Section 11.1, and 2715 Section 7.4. 2717 A.1.1. Cost Preferences 2719 [EDITOR'S NOTE: At IETF 103, opinions were that this property should 2720 stay, but it was also said that this is maybe not "on the right 2721 level". If / when moving it to the main text, note that this is 2722 meant to be applicable to a Preconnection or a Message.] 2724 Name: cost-preferences 2726 Type: Enumeration 2728 This property describes what an application prefers regarding 2729 monetary costs, e.g., whether it considers it acceptable to utilize 2730 limited data volume. It provides hints to the transport system on 2731 how to handle trade-offs between cost and performance or reliability. 2733 Possible values are: 2735 No Expense: Avoid transports associated with monetary cost 2737 Optimize Cost: Prefer inexpensive transports and accept service 2738 degradation 2740 Balance Cost: Use system policy to balance cost and other criteria 2742 Ignore Cost: Ignore cost, choose transport solely based on other 2743 criteria 2745 The default is "Balance Cost". 2747 Appendix B. Sample API definition in Go 2749 This document defines an abstract interface. To illustrate how this 2750 would map concretely into a programming language, an API interface 2751 definition in Go is available online at https://github.com/mami- 2752 project/postsocket. Documentation for this API - an illustration of 2753 the documentation an application developer would see for an instance 2754 of this interface - is available online at 2755 https://godoc.org/github.com/mami-project/postsocket. This API 2756 definition will be kept largely in sync with the development of this 2757 abstract interface definition. 2759 Appendix C. Relationship to the Minimal Set of Transport Services for 2760 End Systems 2762 [I-D.ietf-taps-minset] identifies a minimal set of transport services 2763 that end systems should offer. These services make all transport 2764 features offered by TCP, MPTCP, UDP, UDP-Lite, SCTP and LEDBAT 2765 available that 1) require interaction with the application, and 2) do 2766 not get in the way of a possible implementation over TCP or, with 2767 limitations, UDP. The following text explains how this minimal set 2768 is reflected in the present API. For brevity, this uses the list in 2769 Section 4.1 of [I-D.ietf-taps-minset], updated according to the 2770 discussion in Section 5 of [I-D.ietf-taps-minset]. 2772 [EDITOR'S NOTE: This is early text. In the future, this section will 2773 contain backward references, which we currently avoid because things 2774 are still being moved around and names / categories etc. are 2775 changing.] 2777 o Connect: 2778 "Initiate" Action. 2780 o Listen: 2781 "Listen" Action. 2783 o Specify number of attempts and/or timeout for the first 2784 establishment message: 2785 "Timeout for aborting Connection Establishment" Property, using a 2786 time value. 2788 o Disable MPTCP: 2789 "Parallel Use of Multiple Paths" Property. 2791 o Hand over a message to reliably transfer (possibly multiple times) 2792 before connection establishment: 2794 "InitiateWithSend" Action. 2796 o Hand over a message to reliably transfer during connection 2797 establishment: 2798 "InitiateWithSend" Action. 2800 o Change timeout for aborting connection (using retransmit limit or 2801 time value): 2802 "Timeout for aborting Connection" property, using a time value. 2804 o Timeout event when data could not be delivered for too long: 2805 "ConnectionError" Event. 2807 o Suggest timeout to the peer: 2808 TCP-specific Property: User Timeout. 2810 o Notification of Excessive Retransmissions (early warning below 2811 abortion threshold): 2812 "Notification of excessive retransmissions" property. 2814 o Notification of ICMP error message arrival: 2815 "Notification of ICMP soft error message arrival" property. 2817 o Choose a scheduler to operate between streams of an association: 2818 "Connection group transmission scheduler" property. 2820 o Configure priority or weight for a scheduler: 2821 "Priority (Connection)" property. 2823 o "Specify checksum coverage used by the sender" and "Disable 2824 checksum when sending": 2825 "Corruption Protection Length" property (value 0 to disable). 2827 o "Specify minimum checksum coverage required by receiver" and 2828 "Disable checksum requirement when receiving": 2829 "Required minimum coverage of the checksum for receiving" property 2830 (value 0 to disable). 2832 o "Specify DF" field and "Request not to bundle messages:" 2833 The "Singular Transmission" Message property combines both of 2834 these requests, i.e. if a request not to bundle messages is made, 2835 this also turns off DF in case of protocols that allow this (only 2836 UDP and UDP-Lite, which cannot bundle messages anyway). 2838 o Get max. transport-message size that may be sent using a non- 2839 fragmented IP packet from the configured interface: 2840 "Maximum Message size before fragmentation or segmentation" 2841 property. 2843 o Get max. transport-message size that may be received from the 2844 configured interface: 2845 "Maximum Message size on receive" property. 2847 o Obtain ECN field: 2848 "ECN" is a defined metadata value as part of the Message Receive 2849 Context. 2851 o "Specify DSCP field", "Disable Nagle algorithm", "Enable and 2852 configure a 'Low Extra Delay Background Transfer'": 2853 As suggested in Section 5.5 of [I-D.ietf-taps-minset], these 2854 transport features are collectively offered via the "Capacity 2855 profile" property. 2857 o Close after reliably delivering all remaining data, causing an 2858 event informing the application on the other side: 2859 This is offered by the "Close" Action with slightly changed 2860 semantics in line with the discussion in Section 5.2 of 2861 [I-D.ietf-taps-minset]. 2863 o "Abort without delivering remaining data, causing an event 2864 informing the application on the other side" and "Abort without 2865 delivering remaining data, not causing an event informing the 2866 application on the other side": 2867 This is offered by the "Abort" action without promising that this 2868 is signaled to the other side. If it is, a "ConnectionError" 2869 Event will fire at the peer. 2871 o "Reliably transfer data, with congestion control", "Reliably 2872 transfer a message, with congestion control" and "Unreliably 2873 transfer a message": 2874 Reliability is controlled via the "Reliable Data Transfer 2875 (Message)" Message property. Transmitting data without delimiters 2876 is done by not using a Framer. The choice of congestion control 2877 is provided via the "Congestion control" property. 2879 o Configurable Message Reliability: 2880 The "Lifetime" Message Property implements a time-based way to 2881 configure message reliability. 2883 o "Ordered message delivery (potentially slower than unordered)" and 2884 "Unordered message delivery (potentially faster than ordered)": 2885 The two transport features are controlled via the Message property 2886 "Ordered". 2888 o Request not to delay the acknowledgement (SACK) of a message: 2890 Should the protocol support it, this is one of the transport 2891 features the transport system can use when an application uses the 2892 Capacity Profile Property with value "Low Latency/Interactive". 2894 o Receive data (with no message delimiting): 2895 "Received" Event without using a Message Framer. 2897 o Receive a message: 2898 "Received" Event. Section 5.1 of [I-D.ietf-taps-minset] discusses 2899 how messages can be obtained from a bytestream in case of 2900 implementation over TCP. Here, this is dealt with by Message 2901 Framers. 2903 o Information about partial message arrival: 2904 "ReceivedPartial" Event. 2906 o Notification of send failures: 2907 "Expired" and "SendError" Events. 2909 o Notification that the stack has no more user data to send: 2910 Applications can obtain this information via the "Sent" Event. 2912 o Notification to a receiver that a partial message delivery has 2913 been aborted: 2914 "ReceiveError" Event. 2916 Authors' Addresses 2918 Brian Trammell (editor) 2919 Google 2920 Gustav-Gull-Platz 1 2921 8004 Zurich 2922 Switzerland 2924 Email: ietf@trammell.ch 2926 Michael Welzl (editor) 2927 University of Oslo 2928 PO Box 1080 Blindern 2929 0316 Oslo 2930 Norway 2932 Email: michawe@ifi.uio.no 2933 Theresa Enghardt 2934 TU Berlin 2935 Marchstrasse 23 2936 10587 Berlin 2937 Germany 2939 Email: theresa@inet.tu-berlin.de 2941 Godred Fairhurst 2942 University of Aberdeen 2943 Fraser Noble Building 2944 Aberdeen, AB24 3UE 2945 Scotland 2947 Email: gorry@erg.abdn.ac.uk 2948 URI: http://www.erg.abdn.ac.uk/ 2950 Mirja Kuehlewind 2951 ETH Zurich 2952 Gloriastrasse 35 2953 8092 Zurich 2954 Switzerland 2956 Email: mirja.kuehlewind@tik.ee.ethz.ch 2958 Colin Perkins 2959 University of Glasgow 2960 School of Computing Science 2961 Glasgow G12 8QQ 2962 United Kingdom 2964 Email: csp@csperkins.org 2966 Philipp S. Tiesel 2967 TU Berlin 2968 Einsteinufer 25 2969 10587 Berlin 2970 Germany 2972 Email: philipp@tiesel.net 2973 Chris Wood 2974 Apple Inc. 2975 One Apple Park Way 2976 Cupertino, California 95014 2977 United States of America 2979 Email: cawood@apple.com 2981 Tommy Pauly 2982 Apple Inc. 2983 One Apple Park Way 2984 Cupertino, California 95014 2985 United States of America 2987 Email: tpauly@apple.com