Draft: draft-trammell-taps-interface

Commentary: Fixes all outstanding London API issues except and 
 In issue , we discussed that " Immediate Acknowledgement " ( from SCTP ) is a bit too protocol - specific and could maybe be called " low latency " , allowing the stack to automatically turn this on " under the hood " . I think the only use case for this is when an application executes tight control over the send buffer , and wants to be able to change what it hands over to the transport system at the last minute - then , it is probably good to know ASAP when a particular Message has really arrived at the receiver . This would be an application that requires low latency . The API currently has another send parameter called " immediate " . This would turn off the Nagle algorithm , for example - it represents a wish to send stuff fast , possibly at the cost of wasting capacity ( more header overhead , or other things ) . I do n't think that an application that needs " immediate " would always also need " immediate acknowledgement " or vice versa - these seem to be two different things . Should we have two boolean send parameters for these two types of requests ? " Prefer low latency " ( to trade against capacity ) and " ACK ASAP " ? 
 I 'd suggest that when you say " the only use case for this is " , you 're starying to make me think this is a very specific application use . The immediate stuff in SCTP was a very specific use . I 'm quite OK with believing other use - cases exist , what I 'd question is whether this specific feature needs to be in a generic API ? 
 In SCTP , there were SCTP - internal reasons AND there was the app reason : I now wonder whether this is something that COULD somehow be handled internally in the transport system , or if we need to expose a flag to enable this kind of thing . I 'll follow up with emails . 
 TL;DR : I thought more about this . I started to write an email , and writing made me think deeper and understand better . I conclude that , whether to get ACKs back immediately or not is also just a matter of trading latency against overhead , and indeed one " low latency " bit is enough . Actually we do n't need an extra bit because this is already covered by the message property " Immediate " ( which is about , e.g. , disabling Nagle - but the point is that these things go together : lower latency at the cost of overhead ) . Below , I describe the background for my conclusion . It would be good if someone could check it for potential logical errors .  once described Apple 's model of buffer control to me as follows : I consider TCPNOTSENTLOWAT to be an implementation detail of the sockets API , and not really the right model here . The backpressure we have is based on the asynchronous callback . Nothing is blocking . If the application wants to slow down the generation of its content based on back pressure from the stack , it should wait to generate another send based on the callback to the previous send being fired . However , you may enqueue multiple sends back to back , since the data may already be generated . This gives all of the capabilities of back pressure , without blocking , or forcing it . I think this approach is just right . What this does n't discuss , however , is how to configure the low water mark of TCP - and I think an efficient implementation of a transport system would statically configure it as low as possible , such that most buffering happens inside the transport system , not in TCP , and the application does get maximum control over it via the Sent callbacks . Now , turn to SCTP as a model . ACK - immediately just means that , in case of reliable transfer , SCTP can delete stuff from its own retransmit buffer faster ( In SCTP , and only SCTP , this directly concerns the application because SCTP 's " sender dry event " concerns both unsent and unacknowledged data ) . So if the transport system would want to keep SCTP 's send buffer small , it could turn on " ACK - immediately " , at the cost of overhead ( more ACKs on the backward path ) , but because " sender dry " is n't what we should expose to the application ( BECAUSE it mixes the unsent and unack'ed data buffer , and because it fires when it 's too late anyway - the buffer really is at 0 ) , we also should n't expose control over ACK - immediately . 
 This is on the list to resolve for  ( which may or may not be intentional ) . I think the action here is to replace the Immediate Acknowledg(e)ment send property with an Low Latency send property with more or less the same semantics as the Immediate send property ( which I thought was still there , but appears to have been removed ... ? oops , someone ! ) . An open question is whether or not we also need a protocol selection property for low latency , which ( 1 ) verifies that the underlying protocol actually supports control over Nagle - like functionality and ( 2 ) can be used to set Low Latency by default . Any takers ( I could probably take a crack at this tomorrow ... 
 I 'm not sure I like the name " Immediate " as a send property very much ( because it conveys a meaning that we ca n't guarantee ) , but other than that I think you 're right - we just need to convey " low latency " somehow and remove the " immediate ack " stuff . I do n't think we need a protocol selection property for it . 
 +1 to " Immediate " not being the right name . Ah , okay , I see what happened . The Immediate send property was subsumed into the ( terribly named ) Instantaneous Capacity Profile , and Low Latency in the protocol selection properties was subsumed into Capacity Profile . If we keep   , then , the only action here is to remove Immediate Acknowledgement , and note that such functionality is implied by the Low Latency capacity profile . I 'm leaning toward doing that for this issue , then starting a new issue for an ( ietf-01 ) decision on what to do about Capacity Profile ... is that good ? 
 It seems this has converged a long time ago ... I 'll remove the property about this from section A.1.3 . That it 's still there is just an oversight , I believe . 
 The architecture draft has a number of design principles listed ( the ones discussed in Cambridge ) . The API draft has a another set of design principles listed . When reading both drafts as I just did , this is quite confusing . Do we need design principles in the API draft or they should all move to the architecture draft ? Some of the design principles in the API draft are perhaps more detailed which could be an argument to keep them in the API draft , but then I think we should at least make sure to include all design principles from the architecture draft that applies to the API also in the API draft . Right now we have only one of them which is strange . 
 IMO the principles in the Architecture document are primary . The list in API as it stands is largely inherited from Post Sockets . Though the list of principles in the API is more detailed ( and I think we need more detailed principles for the API ) , it should refer back more concretely to the arch principles . I 'll do this in my early - week edit pass . 
 Agreed . So , can we leave the architecture list as - is , and maybe re - name the section in the API ? 
 Open to suggestions for naming ( I would have just called it " Interface Design Principles " ) ... API section will have to expand a little from its current bullet - list to base itself on arch principles . 
 During my final editorial review pre-00 , I 'll take everything we 're still discussing into a new   , with some text along the lines " an advantage of this framework is it has extension points for properties and preferences beyond those in the proposed standard interface ; here are some potential properties and preferences that we have some design and implementation experience with that may prove useful , and may be to the core interface in future revisions of this document . " 
 So far , tracking the discussion in , I propose the following : Everything in section 5.2.3 goes into   , except : Traffic Category which gets lifted up into Transport Preferences ( and possibly renamed Capacity Profile by reference to Minset ) , with additional language that ( 1 ) the only useful preference level is Prefer and ( 2 ) in addition to being used to select transports , it can also be used to configure selected transports for e.g. DSCP marking . The Immediate boolean send property gets removed to the appendix in favor of disabling Nagle via Traffic Category . ( I might have more to propose after sweeping these ) 
 ( On rewriting   as a path / protocol preference , it 's not clear to me what the stack is supposed do with any of these other than the interactive / default / bulk classes . I 'm leaving Stream / Constant Rate but I 'm not sure what to say about it . We can fix this post-00 ) 
 We are currently writing the implementation part for all Intents – text for that will appear in the intents - implementation branch in the next days 
 I think we ended up with a confusion due to renaming : I thought that the thing that is based on the minset " capacity profile " is " timeliness " , not " traffic category " . And why remove Immediate ? Actually : an app needs a way to say that we require low latency , even at the cost of more overhead . That can be Nagle - like Message bundling , or other things ( e.g. see issue ) . Because this request may ( as in the case of Message bundling ) be necessary for a message , I think it would be good to keep " Immediate".removing this from the minset capacity profile , it only covers table 1 in draft - ietf - tsvwg - rtcweb - qos-18 . I think we want applications to be able to choose cells in this table , somehow . I do n't know how to do this most cleanly ; for version -00 , maybe we could simply point at this draft and say that the " Traffic Category " would choose cells in this table ? Or some such solution ... 
 aaaah right . yep that makes more sense . because capacity profile " Interactive " does this for you on a per connection basis ? 
  . Controlling bundling is a per - message thing in SCTP , whereas TCP 's Nagle is time - based . We could argue whether this should be kept per message or not ... I 'm not 100 % sure that binding this to a message is indeed important to anyone . = I 'm fine with your decision . Let 's only have this per message once we 've convinced ourselves that doing this per - message really matters . 
 More issues in the current text : Section 5.2.1 Transport Preferences : If you agree with my conclusion in issue , then the item " Request not to delay acknowledgment of Content " should be removed here . Section 5.2.2 . Protocol Properties : This text : " Set timeout for aborting Connection establishment : This numeric property specifies how long to wait before aborting a Connection attempt . It is given in seconds . " should be : " Set timeout for aborting Connection : This numeric property specifies how long to wait before aborting a Connection ( including a Connection attempt ) . It is given in seconds . " This is important because section 9 points back at this section , stating that these Properties can be configured later . So to have a configurable Connection timeout , this text must be about the Connection , not just the Connection attempt . The timeout of the Connection attempt itself is also discussed in minset ; I removed it as a separately configurable thing even in minset because this is really just about when to configure the timeout . Because an app can change it later , it can control both the establishment timeout and the connection timeout with this single Property . 
 all of the timeout stuff here is IMO underspecified -- transport protocols have various timeouts in various states , and stuffing them all behind one generic parameter seems optimistic . I 'd thought that " Establishment Timeout " was sufficiently specified to leave it in , but if you now say that we need to replace establishment with ... what , RTO timeout ? heartbeat timeout ? , then that seems underspecified to me now too . I was just debating whether to sweep all the timeout stuff into Appendix A pending a resolution . 
 RTO timeout , the application should n't care about . Heartbeat timeout , the application should n't care about ( at least when I 'm thinking of SCTP heartbeats ... depends on your use case I guess ) . The application should only care about a Connection timeout , and then there are two phases here : 1 ) establishment , 2 ) being connected ... and we can distinguish between these two via the time of using the call . What else is really missing ? 
 so I 'm not clear what the " being connected " timeout is -- is this an idle timeout , i.e. an assumption that the other side has dropped state so we should too ? 
 actually , with respect to § 9 , the following : is , IMO , not something we have consensus on . At least , I do n't thing we should limit the  and Specific Protocol Properties to only those which are safe to change after establishment . I 'd keep this " establishment " timeout , then remove it from the set of settable properties . 
 ( Indeed , I think we should fix this by removing " can be set " here , and noting that certain specific properties may be settable after establishment but only on a Protocol Stack and Property specific basis ) 
 First , about the " being connected " timeout : this is not an idle timeout . In case of TCP , it 's the User Timeout - which is typically more than the RTO ; it 's TCP re - trying and re - trying ... until this timeout expires . Hence , in TCP , at least according to the RFC , you can only change it when you send something ( or with " open " ) . In SCTP , heartbeats are used to check for this timeout , so you can change it at any time . The way I described this in RFC 8303 / pass 2 ( section 4.1 ) , it can be issued at any time and will only take effect for TCP upon the next " send " call . 
 About § 9 , this whole current structure is currently messy - I think a clean approach would be to separate ALL Connection properties out from the current structure and not make them a part of Pre - Establishment , and then , in Pre - Establishment , say that the following ones ( with a list ) can be changed on Pre - Establishment . Or maybe say that " as many as possible should be set on pre - establishment " . However , it 's a fact that most can be changed later . So this : seems very wrong to me . You CAN change the minimum checksum requirement of an ongoing connection . You CAN change the scheduler . Why would you want to take all this functionality away ? I also do n't know what " settable on a Protocol Stack and Property specific basis " means -- e.g. , you can change the checksum requirement and if the transport system uses TCP , nothing happens . That 's the normal fallback logic from minset . 
 The list in 5.2.2 contains one item that really can only be queried : " Maximum Content Size Before Connection Establishment " . So it has to be taken out of this list and written separately . Else , the list seems to completely cover the list from minset , except that " capacity profile " is missing . Also , later , on an ongoing connection , it should be possible to query : o The maximum message size that may be sent without fragmentation , in bytes ( or " not available " ) o The maximum transport message size that can be sent , in bytes ( or " not available " ) o The maximum transport message size that can be received , in bytes ( or " not available " ) 
 Someone has written this paragraph in 5.2.2 which I also do n't agree with : In order to specify Specific Protocol Properties , the application can attach a set of options to the Preconnection object , associated with a specific protocol . For example , the application could specify a set of TCP Options to use if and only if TCP is selected by the system , including options such as the Maximum Segment Size ( MSS ) , and options around   . Such properties should not be assumed to apply across different protocols , but must be possible to specify if required by the application . This invites protocol - dependent implementations ... I can see that some folks may want to support such things , but at least in a PS document we should n't say " must be possible to specify if required by the application " : what exactly must be possible to specify ? All possible TCP options ? Also , " options around   " is a vague statement , what exactly is this even about ? 
 I 'm pretty sure I wrote that text , and that is both aligned with the architecture document , and absolutely critical to have Specific Protocol Properties . Protocol specific options are designed in such a way that they do n't necessarily restrict the choice of protocol selection , but when a protocol is selected , we use the correct options around a given protocol . If you do n't offer that capability , I assure you that many / most applications will choose not to use the API , since it would strictly offer fewer protocol features than sockets . We 're not enumerating the options here — so effectively , it is left as an exercise to the reader to fill out the list . But the importance of telling them where to put the options , and not just saying " must be possible to specify " , is that the options need to be communicated as " if you use [ TCP ] , then set option [ TCP - MSS ] " , not just marking [ TCP - MSS ] on the top level of the properties , and constraining the protocol selection to TCP only . For the examples , I was choosing some arbitrary socket options . The one I was referring to with ack stretching is TCP_SENDMOREACKS , which is a pretty specific TCP - socket - API behavior that we 're not planning on carrying into generic protocol options . Feel free to choose another one . 
 So I 've currently written Capacity Profile as a Transport Preference , not a Protocol Parameter , since a particular capacity profile may also be used in path and/or protocol selection . 
 I think this was ( on actually reading the whole thread , what said ) -- and yes , I thought you might disagree with it . : smile : ISTM the reality of the situation is you will always need an out to specifically configure the details of certain parts of the stack , especially on the server side where these things might actually matter . The only question is whether we acknowledge this reality in the architecture and API and create a bin for them , or ignore this reality and have every implementation hack their specific protocol properties in anyway . 
 agreed , and I think your proposed remedy ( to split protocol properties out of pre - establishment , possibly up into § 9 ) and to refer forward to them from there is the right way to go . My queue of pending edits is pretty deep so I might leave this one for you ( to do though . 
 1 ) About 's paragraph , I see that point and ok , I 'm convinced - we do n't want to end up with " clean but lame " . But we should at least not say " must be possible to specify " . About the examples , I think we should not have the ACK stretching thing because it 's not related to standards . Finding examples is hard - because if I think it 's something an application should care about , I would have written it as such in minset and we 'd be discussing it in a different context here already :-) Maybe we really should n't have any examples . Let me propose an update for this text : In order to specify Specific Protocol Properties , Transport System implementations MAY offer applications to attach a set of options to the Preconnection object , associated with a specific protocol . For example , an application could specify a set of TCP Options to use if and only if TCP is selected by the system . Such properties MUST NOT be assumed to apply across different protocols . 2 ) - about " Capacity Profile as a Transport Preference " , okay , but how do you then change the DSCP on a Connection ? 3 ) - regarding the messy structure related to § 9 and the bit you want to leave to me : ACK ! But I 'm keeping my hands off right now , of course . Maybe I can do this tonight , when you 're done with your pass ? ! 
 I think I fixed § 9 , no worries . That is a very good question ... So one of the keys to fixing the messy structure of § 9 is the observation that the set of Protocol Properties we enumerate in the current § 5.2.2 ca n't really productively be used in protocol or path selection -- basically , allowing you to specify these in preconnection allows you to tweak them before turning up any candidates . Capacity Profile is weird , in that it is potentially useful in protocol and path selection as well as in scheduling afterward . I 'm not sure how to do later DSCP manipulation , other than via Send Properties . 
 ... following up ,   is also a send property ( as Timeliness ) ; we can simply leave it there and refer back to the transport parameter . 
 This text /Implementations of this interface must provide some way for the application to indicate that it is temporarily not ready to receive new Content . Since the mechanisms of event handling are implementation - platform specific , this document does not specify the exact nature of this interface./ I believe this is actually an example of a function that is provided by an APP . I really suggest we should avoid providing “ hooks ” for APP signalling in the transport . That ’s been proposed in many transport systems in the past … and it often ends up messy . I ’d advocate telling the APP to implement the function itself ! Backpressure ( flow control ) is a classic example of what can be hard to realise , X.25 , ATM , and more recently HTTP all tried and failed to make this a deadlock - free useful function ! I suggest we discuss this or remove it from the draft . 
 I agree that this text should be removed . The application should not indicate that it is not able to receive content — that seems to imply sort of blocking semantics . The way I prefer to think of it is simply that , in order to provide natural back pressure between the stack and the app , the act of Receiving is a " pull " model , rather than a " push " model . The application pulls up data from the stack to receive as necessary , by scheduling a callback to receive content in . The stack does not simply deliver content into a recurring callback over and over ( which eliminates back pressure ) . While the act of scheduling the receive callback ( to " pull " ) does indicate that the application is no longer unable to receive , this is a difference from explicitly indicating when it is not able to receive . 
 So this implies making the Receive < event special , in that you need to re - register for it each time ... Okay , I buy that , will make this change in my omnibus edit pass ( hopefully tomorrow , running out of time a bit ... ) 
 I think it 's no less special than a callback event for Send completion . For Sending , you get a Send Complete event for that particular Send . It wo n't fire magically , it 's one - to - one with each call to Send ( ) . Each call to Receive can / should be decorated with constraints on the read — only read up to this much , or make sure you read a complete message / chunk / frame . So , the completion for the receive matches what was requested . For our implementation , there is a callback block that can be different for each invocation of Receive ( ) in case it needs to go to a different codepath . Essentially , any event needs to have a contract of how it can repeat . For memory management reasons , it 's important to know that there is a one - to - one call - to - callback correspondence if you want to allocate something in the call , and free it in the callback ; or that an event can fire any number of times , which requires different handling .
Paragraph (version A):
As a first step to realizing this design, TAPS-ARCH describes a high-
level architecture for transport services.  This document builds a
modern abstract programming interface atop this architecture,
deriving specific path and protocol selection properties and
supported transport features from the analysis provided in RFC8095
and TAPS-MINSET.
Paragraph (version B):
As a first step to realizing this design, TAPS-ARCH describes a high-
level architecture for transport services.  This document builds a
modern abstract programming interface atop this architecture,
deriving specific path and protocol selection properties and
supported transport features from the analysis provided in RFC8095
and I-D.ietf-taps-minset.
Paragraph (version A):
How these abstract concepts map into concrete implementations of this
API in a given language on a given platform is largely dependent on
the features of the language and the platform.  Actions could be
implemented as functions or method calls, for instance, and Events
could be implemented via callback passing or other asynchronous
calling conventions.
Paragraph (version A):
We begin with a set of initial design principles for the abstract
interface to realize.
Paragraph (version A):
Transport protocol stack independence in line with the Transport
Services Architecture TAPS-ARCH, allowing applications to be
written in terms of the semantics best for the application's own
design, separate from the protocol(s) used on the wire to achieve
them.  This enables applications written to a single API to make
use of transport protocols in terms of the features they provide.
Paragraph (version A):
Explicit support for multistreaming and multipath transport
protocols.
Paragraph (version A):
Explicit support for security properties as first-order transport
features, and for long-term caching of cryptographic identities
and parameters for associations among endpoints.
Paragraph (version A):
Atomic transmission of content, using application-assisted framing
and deframing where the underlying transport does not provide
these.
Paragraph (version A):
Asynchronous connection establishment, transmission, and
reception, allowing most application interactions with the
transport layer to be event-driven.
Paragraph (version B):
How these abstract concepts map into concrete implementations of this
API in a given language on a given platform is largely dependent on
the features of the language and the platform.  Actions could be
implemented as functions or method calls, for instance, and Events
could be implemented via callback passing or other asynchronous
calling conventions.  The method for registering callbacks and
handlers is left as an implementation detail, with the caveat that
the interface for receiving Messages must require the application to
invoke the Connection.Receive() action once per Message to be
received (see receiving).
Paragraph (version B):
This specification treats events and errors similarly, as errors,
just as any other events, may occur asynchronously in network
applications.  However, it is recommended that implementations of
this interface also return errors immediately, according to the error
handling idioms of the implementation platform, for errors which can
be immediately detected, such as inconsistency in transport
parameters.
Paragraph (version B):
Atomic transmission of data, using application-assisted framing
and deframing where the underlying transport does not provide
these.
Paragraph (version A):
The LocalEndpoint MUST be specified if the Preconnection is used to
Listen() for incoming connections, but is OPTIONAL if it is used to
Initiate() connections.  The RemoteEndpoint MUST be specified in the
Preconnection is used to Initiate() connections, but is OPTIONAL if
it is used to Listen() for incoming connections.
Paragraph (version A):
The transport services API uses the LocalEndpoint and RemoteEndpoint
types to refer to the endpoints of a transport connection.  Subtypes
of these represent various different types of endpoint identifiers,
such as IP addresses, DNS names, and interface names, as well as port
numbers and service names.
Paragraph (version A):
Multiple endpoint identifiers can be specified for each LocalEndpoint
and RemoteEndoint.  For example, a LocalEndpoint could be configured
with two interface names, or a RemoteEndpoint could be specified via
both IPv4 and IPv6 addresses.  The multiple identifiers refer to the
same endpoint.
Paragraph (version A):
The transport services API will resolve names internally, when the
Initiate(), Listen(), or Rendezvous() method is called establish a
connection.  The API does not need the application to resolve names,
and premature name resolution can damage performance by limiting the
scope for alternate path discovery during connection establishment.
The Resolve() method is, however, provided to resolve a LocalEndpoint
or a RemoteEndpoint in cases where this is required, for example with
some NAT traversal protocols (see rendezvous).
Paragraph (version B):
The Local Endpoint MUST be specified if the Preconnection is used to
Listen() for incoming connections, but is OPTIONAL if it is used to
Initiate() connections.  The Remote Endpoint MUST be specified in the
Preconnection is used to Initiate() connections, but is OPTIONAL if
it is used to Listen() for incoming connections.
Paragraph (version B):
The transport services API uses the Local Endpoint and Remote
Endpoint types to refer to the endpoints of a transport connection.
Subtypes of these represent various different types of endpoint
identifiers, such as IP addresses, DNS names, and interface names, as
well as port numbers and service names.
Paragraph (version B):
Multiple endpoint identifiers can be specified for each Local
Endpoint and RemoteEndoint.  For example, a Local Endpoint could be
configured with two interface names, or a Remote Endpoint could be
specified via both IPv4 and IPv6 addresses.  The multiple identifiers
refer to the same endpoint.
Paragraph (version B):
The transport services API will resolve names internally, when the
Initiate(), Listen(), or Rendezvous() method is called establish a
connection.  The API does not need the application to resolve names,
and premature name resolution can damage performance by limiting the
scope for alternate path discovery during connection establishment.
The Resolve() method is, however, provided to resolve a Local
Endpoint or a Remote Endpoint in cases where this is required, for
example with some NAT traversal protocols (see rendezvous).
Paragraph (version A):
A Preconnection object holds parameters reflecting the application's
requirements and preferences for the transport.  These include
Transport Preferences (towards protocol selection and path selection)
as well as Application Intents (hints to the transport system what to
optimize for) and Protocol Properties (to configure transport
protocols).
Paragraph (version A):
All Transport Parameters are organized within a single name space,
that is shared with Send Parameters (see send-params).  While
Application Intents and Protocol Properties take parameter specific
values, Transport Preferences use one of five fixed levels (see
transport-prefs).
Paragraph (version A):
Some parameters express strict requirements that the application
relies on, while others are hints of what transport features would be
helpful for the application.  For example, if an application asks for
reliable data transfer, choosing a transport protocol such as UDP,
which does not have this feature, will break the application's
functionality.  On the other hand, the option to not require
checksums when receiving an individual Content can help optimize for
low latency, but if not present, it will most likely not break the
fundamental assumptions of the application.  Moreover, there can be
conflicts between parameters set by the application: If multiple
features are requested which are offered by different protocols, it
may not be possible to satisfy all requirements.  Consequently, a
transport system must prioritize Transport Parameters and consider
the relevant trade-offs, see also TAPS-MINSET.
Paragraph (version A):
Default preference levels and possible combinations of Transport
Parameters and preference levels are specified in appendix-
preferences.
Paragraph (version A):
Transport Preferences drive protocol selection and path selection on
connection establishment.  Since there could be paths over which some
transport protocols are unable to operate, or remote endpoints that
support only specific network addresses or transports, transport
protocol selection is necessarily tied to path selection.  This may
involve choosing between multiple local interfaces that are connected
to different access networks.
Paragraph (version A):
The Transport Preferences form part of the information used to create
a Preconnection object.  As such, they can be configured during the
pre-establishment phase, but cannot be changed once a Connection has
been established.
Paragraph (version A):
There need to be sensible defaults for the Transport Preferences as
well as Protocol Selection Properties.  The defaults given in the
following section represent a configuration that can be implemented
over TCP.  An alternate set of default Protocol Selection Properties
would represent a configuration that can be implemented over UDP.
Paragraph (version B):
A Preconnection object holds parameters reflecting the application's
requirements and preferences for the transport.  These include
protocol and path selection parameters, as well as Generic and
Specific Protocol Properties for configuration of the detailed
operation of the selected Protocol Stacks.
Paragraph (version B):
All Transport Parameters are organized within a single namespace
shared with Send Parameters (see send-params).  All transport
parameters take paremeter-specific values.  Protocol and Path
Selection properties additionally take one of five preference levels,
though not all preference levels make sense with all such properties.
Note that it is possible for a set of specified transport parameters
to be internally inconsistent, or for preferences to be inconsistent
with the later use of the API by the application.  Application
developers should reduce inconsistency by only using the most
stringent preference levels when failure to meet a preference would
break the application's functionality (e.g.  the Reliable Data
Transfer preference, which is a core assumption of many application
protocols).  Implementations of this interface should also raise
errors in configuration as early as possible, to help ensure these
inconsistencies are caught early in the development process.
Paragraph (version B):
The protocol(s) and path(s) selected as candidates during connection
establishment are determined by a set of properties.  Since there
could be paths over which some transport protocols are unable to
operate, or remote endpoints that support only specific network
addresses or transports, transport protocol selection is necessarily
tied to path selection.  This may involve choosing between multiple
local interfaces that are connected to different access networks.
Paragraph (version B):
An implementation of this interface must provide sensible defaults
for protocol and path selection properties.  The defaults given for
each property below represent a configuration that can be implemented
over TCP.  An alternate set of default Protocol Selection Properties
would represent a configuration that can be implemented over UDP.
Paragraph (version A):
Configure reliability for individual Content: This boolean
property specifies whether an application considers it useful to
indicate its reliability requirements on a per-Content basis.
This property applies to connections and connection groups.  This
is not a strict requirement.  The default is to not have this
option.
Paragraph (version A):
Request not to delay acknowledgment of Content: This boolean
property specifies whether an application considers it useful to
request for Content that its acknowledgment be sent out as early
as possible instead of potentially being bundled with other
acknowledgments.  This property applies to connections and
connection groups.  This is not a strict requirement.  The default
is to not have this option.
Paragraph (version A):
Use 0-RTT session establishment with idempotent Content: This
boolean property specifies whether an application would like to
supply a Content to the transport protocol before Connection
establishment, which will then be reliably transferred to the
other side before or during connection establishment, potentially
multiple times.  See also send-idempotent.  This is a strict
requirement.  The default is to not have this option.
Paragraph (version A):
Use Connection Groups with priorities: This boolean property
specifies whether an application considers it useful to create
Connection Groups and explicitly prioritize between Connections
within a Connection Group.  This is not a strict requirement.  The
default is to not have this option.
Paragraph (version A):
Suggest a timeout to the RemoteEndpoint: This boolean property
specifies whether an application considers it useful to propose a
timeout until the connection is assumed to be lost.  This property
applies to Connections and Connection Groups.  This is not a
strict requirement.  The default is to have this option.
Paragraph (version B):
Configure reliability on a per-Message basis: This boolean
property specifies whether an application considers it useful to
indicate its reliability requirements on a per-Message basis.
This property applies to connections and connection groups.  This
is not a strict requirement.  The default is to not have this
option.
Paragraph (version B):
Use 0-RTT session establishment with an idempotent Message: This
boolean property specifies whether an application would like to
supply a Message to the transport protocol before Connection
establishment, which will then be reliably transferred to the
other side before or during connection establishment, potentially
multiple times.  See also send-idempotent.  This is a strict
requirement.  The default is to not have this option.
Paragraph (version B):
Efficient use of Connection Groups: This boolean property
specifies whether an application considers it useful to create
Connection Groups, e.g. to explicitly prioritize between
Connections within a Connection Group.  This property will tend to
select multistreaming transport protocols, which can multiplex
Connections into a Connection Group over a single flow.  This is
not a strict requirement.  The default is to not have this option.
Paragraph (version B):
Suggest a timeout to the Remote Endpoint: This boolean property
specifies whether an application considers it useful to propose a
timeout until the connection is assumed to be lost.  This property
applies to Connections and Connection Groups.  This is not a
strict requirement.  The default is to have this option.
Paragraph (version A):
Control checksum coverage on sending or receiving: This boolean
property specifies whether the application considers it useful to
enable / disable / configure a checksum when sending Content, or
decide whether to require a checksum or not when receiving
Content.  This property applies to Connections and Connection
Groups.  This is not a strict requirement, as it signifies a
reduction in reliability.  The default is full checksum coverage
without being able to change it, and requiring a checksum when
receiving.
Paragraph (version A):
Interface Type to prefer: This property specifies which kind of
access network interface, e.g., WiFi, Ethernet, or LTE, to prefer
over others for this connection, in case they are available.  This
is not a strict requirement.  The default is to use the default
interface configured in the system policy.
Paragraph (version A):
Interface Type to prohibit: This property specifies which kind of
access network interface, e.g., WiFi, Ethernet, or LTE, to not use
for this connection.  This is a strict requirement and connection
establishment will fail if no other interface is available.  The
default is to not prohibit any particular interface.
Paragraph (version A):
Set timeout to suggest to the RemoteEndpoint: This numeric
property specifies the timeout to propose to the RemoteEndpoint.
It is given in seconds.
Paragraph (version A):
Set retransmissions before "Excessive Retransmissions": This
numeric property specifies after how many retransmissions to
inform the application about "Excessive Retransmissions".
Paragraph (version A):
Set required minimum coverage of the checksum for receiving: This
numeric property specifies the part of the received data that
needs to be covered by a checksum.  It is given in Bytes.  A value
of 0 means that no checksum is required, and a special value
(e.g., -1) indicates full checksum coverage.
Paragraph (version A):
Set scheduler for connections in a group: This property specifies
which scheduler should be used among Connections within a
Connection Group.  It applies to connection groups.  For now we
suggest the schedulers defined in I-D.ietf-tsvwg-sctp-ndata.
Paragraph (version A):
Maximum Content Size Before Connection Establishment: This numeric
property represents the maximum Content size that can be sent
before or during Connection establishment, see also send-
idempotent.  It is given in Bytes.
Paragraph (version A):
Application Intents are a group of properties expressing what an
application wants to achieve, knows, assumes or prefers regarding its
communication.  They are not strict requirements.  In particular,
they should not be used to express any Quality of Service
expectations that an application might have.  Instead, an application
should express its intentions and its expected traffic
characteristics in order to help the transport system make decisions
that best match it, but on a best-effort basis.  Even though
Application Intents do not represent Quality of Service requirements,
a transport system may use them to determine a DSCP value, e.g.
similar to Table 1 in I-D.ietf-tsvwg-rtcweb-qos.
Paragraph (version A):
Application Intents can influence protocol selection, protocol
configuration, path selection, and endpoint selection.  For example,
setting the "Timeliness" Intent to "Interactive" may lead the
transport system to disable the Nagle algorithm for a connection,
while setting the "Timeliness" to "Background" may lead it to setting
the DSCP value to "scavenger".  If the "Size to be Sent" Intent is
set on individual Content, it may influence path selection, e.g.,
when the TAPS system schedules big Content over an interface with
higher bandwidth, and small Content over an interface with lower
latency.
Paragraph (version A):
Specifying Application Intents is not mandatory.  An application can
specify any combination of Application Intents.  If specified,
Application Intents are defined as parameters passed to the
Preconnection object, and may influence the Connection established
from that Preconnection.  If a Connection is cloned to form a
Connection Group, and associated Application Intents are cloned along
with the other transport parameters.  Some Intents have also
corresponding Content Properties, similar to the properties in send-
params.
Paragraph (version A):
This Intent specifies what the application expect the dominating
traffic pattern to be.
Paragraph (version A):
The default is to not assume any particular traffic pattern.  Most
categories suggest the use of other intents to further describe the
traffic pattern anticipated, e.g., the bulk category suggesting the
use of the Message Size intents or the stream category suggesting the
Stream Bitrate and Duration intents.
Paragraph (version A):
This Intent specifies what the application expects the size of a
transfer to be.  It is a numeric property and given in Bytes.
Paragraph (version A):
This Intent specifies what the application expects the lifetime of a
transfer to be.  It is a numeric property and given in milliseconds.
Paragraph (version A):
This Intent specifies what the application expects the bit-rate of a
transfer to be.  It is a numeric property and given in Bytes per
second.
Paragraph (version A):
This Intent specifies what delay characteristics the applications
prefers.  It provides hints for the transport system whether to
optimize for low latency or other criteria.  Note that setting this
Intents does not imply any guarantees on whether an application's
requirements can actually be satisfied.
Paragraph (version A):
This Intent describes what an application prefers regarding monetary
costs, e.g., whether it considers it acceptable to utilize limited
data volume.  It provides hints to the transport system on how to
handle trade-offs between cost and performance or reliability.  This
Intent can also apply to individual Content.
Paragraph (version A):
The default is "Balance Cost".
Paragraph (version B):
Control checksum coverage on sending or receiving: This boolean
property specifies whether the application considers it useful to
enable / disable / configure a checksum when sending data, or
decide whether to require a checksum or not when receiving data.
This property applies to Connections and Connection Groups.  This
is not a strict requirement, as it signifies a reduction in
reliability.  The default is full checksum coverage without being
able to change it, and requiring a checksum when receiving.
Paragraph (version B):
Interface Type: This enumerated property specifies which kind of
access network interface, e.g., WiFi, Ethernet, or LTE, to prefer
over others for this connection, in case they are available.  In
general, Interface Types should be used only with the "prefer" and
"prohibit" preference level.  Specifically, using the "require"
preference level for Interface Type may limit path selection in a
way that is detrimental to connectivity.  The default is to use
the default interface configured in the system policy.
Paragraph (version B):
The application makes no representation about its expected
capacity profile.  No special optimizations of the tradeoff
between delay, delay variation, and bandwidth efficiency should
be made when selecting and configuring stacks.
Paragraph (version B):
The application is interactive.  Response time (latency) should
be optimized at the expense of bandwidth efficiency and delay
variation.  This can be used by the system to disable the
coalescing of multiple small Messages into larger packets
(Nagle's algorithm), to prefer lower-latency paths, signal a
preference for lower-latency, higher-loss treatment, and so on.
Paragraph (version B):
The application expects to send/receive data at a constant rate
after connection establishment.  Delay and delay variation
should be optimized at the expense of bandwidth efficiency.
Paragraph (version B):
The application is not interactive.  It expects to send/receive
a large amount of data, without any urgency.  This can be used
to select protocol stacks with scavenger transmission control,
to signal a preference for less-than-best-effort treatment, and
so on.
Paragraph (version B):
In addition to protocol and path selection properties, the transport
parameters may also contain Generic and/or Specific Protocol
Properties (see protocol-props).  These properties will be passed to
the selected candidate Protocol Stack(s) to configure them before
candidate connection establishment.
Paragraph (version A):
Connections can be cloned at any time, before or after establishment.
A cloned connection and its parent are entangled: they share the same
TransportParameters object, changing any parameter for one of them
also changes the parameter for the other, connecting one of them also
connects the other, etc.  Cloning connections during pre-
establishment is encouraged, as it informs the transport system about
the intent to form Connection Groups.
Paragraph (version A):
Note that priority assignment ((see also groups for more details) is
not shared among cloned connections.  Therefore, the priority
assignment MUST NOT be realized using the connection level
TransportParameters object.
Paragraph (version B):
A Connection gets its Transport Parameters either by being explicitly
configured via a Preconnection, or by inheriting them from an
antecedent via cloning; see groups for more.
Paragraph (version A):
Pre-shared keying material: Used to install pre-shared keying
material established out-of-band.  Each pre-shared keying material
is associated with some identity that typically identifies its use
or has some protocol-specific meaning to the RemoteEndpoint.
Paragraph (version A):
Trust verification callback: Invoked when a RemoteEndpoint's trust
must be validated before the handshake protocol can proceed.
Paragraph (version B):
Trust verification callback: Invoked when a Remote Endpoint's
trust must be validated before the handshake protocol can proceed.
Paragraph (version A):
Before calling Initiate, the caller must have populated a
Preconnection object with a RemoteEndpoint specifier, optionally a
LocalEndpoint specifier (if not specified, the system will attempt to
determine a suitable LocalEndpoint), as well as all parameters
necessary for candidate selection.  After calling Initiate, no
further parameters may be bound to the Connection.  The Initiate()
call consumes the Preconnection and creates a Connection object.  A
Preconnection can only be initiated once.
Paragraph (version B):
Before calling Initiate, the caller must have populated a
Preconnection object with a Remote Endpoint specifier, optionally a
Local Endpoint specifier (if not specified, the system will attempt
to determine a suitable Local Endpoint), as well as all parameters
necessary for candidate selection.  After calling Initiate, no
further parameters may be bound to the Connection.  The Initiate()
call consumes the Preconnection and creates a Connection object.  A
Preconnection can only be initiated once.
Paragraph (version A):
Once Initiate is called, the candidate Protocol Stack(s) may cause
one or more candidate transport-layer connections to be created to
the specified remote endpoint.  The caller may immediately begin
sending Content on the Connection (see sending) after calling
Initate(); note that any idempotent data sent while the Connection is
being established may be sent multiple times or on multiple
candidates.
Paragraph (version A):
Before calling Listen, the caller must have initialized the
Preconnection during the pre-establishment phase with a LocalEndpoint
specifier, as well as all parameters necessary for Protocol Stack
selection.  A RemoteEndpoint may optionally be specified, to
constrain what connections are accepted.  The Listen() action
consumes the Preconnection.  Once Listen() has been called, no
further parameters may be bound to the Preconnection, and no
subsequent establishment call may be made on the Preconnection.
Paragraph (version A):
The ConnectionReceived event occurs when a RemoteEndpoint has
established a transport-layer connection to this Preconnection (for
connection-oriented transport protocols), or when the first Content
has been received from the RemoteEndpoint (for connectionless
protocols), causing a new Connection to be created.  The resulting
Connection is contained within the ConnectionReceived event, and is
ready to use as soon as it is passed to the application via the
event.
Paragraph (version A):
A ListenError occurs either when the Preconnection cannot be
fulfilled for listening, when the LocalEndpoint (or RemoteEndpoint,
if specified) cannot be resolved, or when the application is
prohibited from listening by policy.
Paragraph (version B):
Before calling Listen, the caller must have initialized the
Preconnection during the pre-establishment phase with a Local
Endpoint specifier, as well as all parameters necessary for Protocol
Stack selection.  A Remote Endpoint may optionally be specified, to
constrain what connections are accepted.  The Listen() action
consumes the Preconnection.  Once Listen() has been called, no
further parameters may be bound to the Preconnection, and no
subsequent establishment call may be made on the Preconnection.
Paragraph (version B):
The ConnectionReceived event occurs when a Remote Endpoint has
established a transport-layer connection to this Preconnection (for
connection-oriented transport protocols), or when the first Message
has been received from the Remote Endpoint (for connectionless
protocols), causing a new Connection to be created.  The resulting
Connection is contained within the ConnectionReceived event, and is
ready to use as soon as it is passed to the application via the
event.
Paragraph (version A):
The Preconnection object must be specified with both a LocalEndpoint
and a RemoteEndpoint, and also the transport and security parameters
needed for protocol stack selection.  The Rendezvous() action causes
the Preconnection to listen on the LocalEndpoint for an incoming
connection from the RemoteEndpoint, while simultaneously trying to
establish a connection from the LocalEndpoint to the RemoteEndpoint.
This corresponds to a TCP simultaneous open, for example.
Paragraph (version A):
The RendezvousDone<> event occurs when a connection is established
with the RemoteEndpoint.  For connection-oriented transports, this
occurs when the transport-layer connection is established; for
connectionless transports, it occurs when the first Content is
received from the RemoteEndpoint.  The resulting Connection is
contained within the RendezvousDone<> event, and is ready to use as
soon as it is passed to the application via the event.
Paragraph (version A):
An RendezvousError occurs either when the Preconnection cannot be
fulfilled for listening, when the LocalEndpoint or RemoteEndpoint
cannot be resolved, when no transport-layer connection can be
established to the RemoteEndpoint, or when the application is
prohibited from rendezvous by policy.
Paragraph (version B):
The Preconnection object must be specified with both a Local Endpoint
and a Remote Endpoint, and also the transport and security parameters
needed for protocol stack selection.  The Rendezvous() action causes
the Preconnection to listen on the Local Endpoint for an incoming
connection from the Remote Endpoint, while simultaneously trying to
establish a connection from the Local Endpoint to the Remote
Endpoint.  This corresponds to a TCP simultaneous open, for example.
Paragraph (version B):
The RendezvousDone<> event occurs when a connection is established
with the Remote Endpoint.  For connection-oriented transports, this
occurs when the transport-layer connection is established; for
connectionless transports, it occurs when the first Message is
received from the Remote Endpoint.  The resulting Connection is
contained within the RendezvousDone<> event, and is ready to use as
soon as it is passed to the application via the event.
Paragraph (version B):
An RendezvousError occurs either when the Preconnection cannot be
fulfilled for listening, when the Local Endpoint or Remote Endpoint
cannot be resolved, when no transport-layer connection can be
established to the Remote Endpoint, or when the application is
prohibited from rendezvous by policy.
Paragraph (version A):
Connection Groups should be created (i.e., the Clone action should be
used) as early as possible, ideally already during the Pre-
Establishment phase, in order to aid the Transport System in choosing
and configuring the right protocols (see also transport-params).
Paragraph (version A):
The type of the Content to be passed is dependent on the
implementation, and on the constraints on the Protocol Stacks implied
by the Connection's transport parameters.  It may itself contain an
array of octets to be transmitted in the transport protocol payload,
or be transformable to an array of octets by a sender-side framer
(see send-framing).
Paragraph (version B):
Connection Groups should be created by cloning as as early as
possible in order to aid the Transport System in choosing and
configuring the right protocols (see also transport-params).
Paragraph (version B):
Messages may be arbitrarily large; however, there may be system and
Protocol Stack dependent limits on the size of a data object which
can be transmitted atomically.  For that reason, the Message object
passed to the Send action may also be a partial Message, either
representing the whole data object and information about the range of
bytes to send from it, or an object referring back to the larger
whole Message.  The details of partial Message sending are
implementation-dependent.
Paragraph (version A):
The Sent event occurs when a previous Send action has completed,
i.e., when the data derived from the Content has been passed down or
through the underlying Protocol Stack and is no longer the
responsibility of the implementation of this interface.  The exact
disposition of Content when the Sent event occurs is specific to the
implementation and the constraints on the Protocol Stacks implied by
the Connection's transport parameters.  The Sent event contains an
implementation-specific reference to the Content to which it applies.
Paragraph (version B):
The Sent event occurs when a previous Send action has completed,
i.e., when the data derived from the Message has been passed down or
through the underlying Protocol Stack and is no longer the
responsibility of the implementation of this interface.  The exact
disposition of the Message when the Sent event occurs is specific to
the implementation and the constraints on the Protocol Stacks implied
by the Connection's transport parameters.  The Sent event contains an
implementation-specific reference to the Message to which it applies.
Paragraph (version A):
The Expired event occurs when a previous Send action expired before
completion; i.e. when the data derived from the Content was not sent
before its Lifetime (see send-lifetime) expired.  This is separate
from SendError, as it is an expected behavior for partially reliable
transports.  The Expired event contains an implementation-specific
reference to the Content to which it applies.
Paragraph (version A):
A SendError occurs when Content could not be sent due to an error
condition: some failure of the underlying Protocol Stack, or a set of
send parameters not consistent with the Connection's transport
parameters.  The SendError contains an implementation-specific
reference to the Content to which it applies.
Paragraph (version A):
The Send action takes per-Content send parameters which control how
the contents will be sent down to the underlying Protocol Stack and
transmitted.
Paragraph (version A):
If Send Parameters should be overridden for a specific content, an
empty sent parameter Object can be acquired and all desired Send
Parameters can be added to that object.  A sendParameters object can
be reused for sending multiple contents with the same properties.
Paragraph (version A):
The Send Parameters are organized in _Content Properties_ and
_Application Intents_.  The Send Parameters share a single namespace
with the Transport Parameters (see transport-params).  This allows to
specify Protocol Properties and that can be overridden on a per
content basis or Application Intents that apply to a specific
content.  See appendix-specify-query-params for an overview.
Paragraph (version A):
Lifetime specifies how long a particular Content can wait to be sent
to the remote endpoint before it is irrelevant and no longer needs to
be (re-)transmitted.  When a Content's Lifetime is infinite, it must
be transmitted reliably.  The type and units of Lifetime are
implementation-specific.
Paragraph (version A):
Niceness represents an unbounded hierarchy of priorities of Content,
relative to other Content sent over the same Connection and/or
Connection Group (see groups).  It is most naturally represented as a
non-negative integer.  Content with Niceness 0 will yield to Content
with Niceness 1, which will yield to Content with Niceness 2, and so
on.  Niceness may be used as a sender-side scheduling construct only,
or be used to specify priorities on the wire for Protocol Stacks
supporting prioritization.
Paragraph (version B):
The Expired event occurs when a previous Send action expired before
completion; i.e. when the Message was not sent before its Lifetime
(see send-lifetime) expired.  This is separate from SendError, as it
is an expected behavior for partially reliable transports.  The
Expired event contains an implementation-specific reference to the
Message to which it applies.
Paragraph (version B):
A SendError occurs when a Message could not be sent due to an error
condition: an attempt to send a non-partial Message which is too
large for the system and Protocol Stack to handle, some failure of
the underlying Protocol Stack, or a set of send parameters not
consistent with the Connection's transport parameters.  The SendError
contains an implementation-specific reference to the Message to which
it applies.
Paragraph (version B):
The Send action takes per-Message send parameters which control how
the contents will be sent down to the underlying Protocol Stack and
transmitted.
Paragraph (version B):
If Send Parameters should be overridden for a specific Message, an
empty sent parameter Object can be acquired and all desired Send
Parameters can be added to that object.  A sendParameters object can
be reused for sending multiple contents with the same properties.
Paragraph (version B):
The Send Parameters are organized in _Message Properties_ and
_Application Intents_.  The Send Parameters share a single namespace
with the Transport Parameters (see transport-params).  This allows to
specify Protocol Properties and that can be overridden on a per-
Message basis or Application Intents that apply to a specific
Message.  See appendix-specify-query-params for an overview.
Paragraph (version B):
Send Parameters may be inconsistent with the properties of the
Protocol Stacks underlying the Connection on which a given Message is
sent.  For example, infinite Lifetime is not possible on a Message
over a Connection not providing reliability.  Sending a Message with
Send Properties inconsistent with the Transport Preferences on the
connection yields an error.
Paragraph (version A):
Ordered is a boolean property.  If true, this Content should be
delivered after the last Content passed to the same Connection via
the Send action; if false, this Content may be delivered out of
order.
Paragraph (version A):
Immediate is a boolean property.  If true, the caller prefers
immediacy to efficient capacity usage for this Content.  For example,
this means that the Content should not be bundled with other Content
into the same transmission by the underlying Protocol Stack.
Paragraph (version A):
Idempotent is a boolean property.  If true, the application-layer
entity in the Content is safe to send to the remote endpoint more
than once for a single Send action.  It is used to mark data safe for
certain 0-RTT establishment techniques, where retransmission of the
0-RTT data may cause the remote application to receive the Content
multiple times.
Paragraph (version A):
This numeric property specifies the length of the section of content,
starting from byte 0, that the application assumes will be received
without corruption due to lower layer errors.  It is used to specify
options for simple integrity protection via checksums.  By default,
the entire Content is protected by checksum.  A value of 0 means that
no checksum is required, and a special value (e.g. -1) can be used to
indicate the default.  Only full coverage is guaranteed, any other
requests are advisory.
Paragraph (version A):
This boolean property specifies, if true, that an application wants
this Content to be acknowledged immediately by the receiver.  In case
of reliable transmission, this informs the transport protocol on the
sender side faster that it can remove the Content from its buffer;
therefore this property can be useful for latency-critical
applications that maintain tight control over the send buffer (see
sending).
Paragraph (version A):
This numeric property in Bytes per second specifies at what bitrate
the application wishes the content to be sent.  A transport
supporting this feature will not exceed the requested Send Bitrate
even if flow-control and congestion control allow higher bitrates.
This helps to avid bursty traffic pattern on busy video streaming
servers.
Paragraph (version A):
This specifies what delay characteristics the applications prefers
for the given content.  It provides hints for the transport system
whether to optimize for low latency or other criteria and set the
DSCP flags for packets used to transmit the content.
Paragraph (version A):
As with sending, the type of the Content to be passed is dependent on
the implementation, and on the constraints on the Protocol Stacks
implied by the Connection's transport parameters.  The Content may
also contain metadata from protocols in the Protocol Stack; which
metadata is available is Protocol Stack dependent.  In particular,
when this information is available, the value of the Explicit
Congestion Notification (ECN) field is contained in such metadata.
This information can be used for logging and debugging purposes, and
for building applications which need access to information about the
transport internals for their own operation.
Paragraph (version B):
Ordered is a boolean property.  If true, this Message should be
delivered after the last Message passed to the same Connection via
the Send action; if false, this Message may be delivered out of
order.
Paragraph (version B):
Idempotent is a boolean property.  If true, the application-layer
entity in the Message is safe to send to the remote endpoint more
than once for a single Send action.  It is used to mark data safe for
certain 0-RTT establishment techniques, where retransmission of the
0-RTT data may cause the remote application to receive the Message
multiple times.
Paragraph (version B):
This numeric property specifies the length of the section of the
Message, starting from byte 0, that the application assumes will be
received without corruption due to lower layer errors.  It is used to
specify options for simple integrity protection via checksums.  By
default, the entire Message is protected by checksum.  A value of 0
means that no checksum is required, and a special value (e.g. -1) can
be used to indicate the default.  Only full coverage is guaranteed,
any other requests are advisory.
Paragraph (version B):
This boolean property specifies, if true, that an application wants
this Message to be acknowledged immediately by the receiver.  In case
of reliable transmission, this informs the transport protocol on the
sender side faster that it can remove the Message from its buffer;
therefore this property can be useful for latency-critical
applications that maintain tight control over the send buffer (see
sending).
Paragraph (version B):
This enumerated property specifies the application's preferred
tradeoffs for sending this Message; it is a per-Message override of
the Capacity Profile protocol and path selection property (see
transport-params).
Paragraph (version B):
No special optimizations of the tradeoff between delay, delay
variation, and bandwidth efficiency should be made when sending
this message.
Paragraph (version B):
Response time (latency) should be optimized at the expense of
bandwidth efficiency and delay variation when sending this
message.  This can be used by the system to disable the coalescing
of multiple small Messages into larger packets (Nagle's
algorithm), to signal a preference for lower-latency, higher-loss
treatment, and so on.
Paragraph (version B):
Delay and delay variation should be optimized at the expense of
bandwidth efficiency.
Paragraph (version B):
Once a Connection is established, Messages may be received on it.
The application can indicate that it is ready to receive Messages by
calling Receive() on the connection.
Paragraph (version B):
Receive takes a single object, a ReceiveHandler which can handle the
Received event and the ReceiveError error.  Each call to Receive will
result in at most one Received event being sent to the handler,
though implementations may provide convenience functions to indicate
readiness to receive a larger but finite number of Messages with a
single call.  This allows an application to provide backpressure to
the transport stack when it is temporarily not ready to receive
messages.
Paragraph (version A):
The Content object must provide some method to retrieve an octet
array containing application data, corresponding to a single message
within the underlying Protocol Stack's framing.  See receive-framing
for handling framing in situations where the Protocol Stack provides
octet-stream transport only.
Paragraph (version B):
The Message object must provide some method to retrieve an octet
array containing application data, corresponding to a single message
within the underlying Protocol Stack's framing.  See receive-framing
for handling framing in situations where the Protocol Stack provides
octet-stream transport only.
Paragraph (version B):
In this case, the Message object passed to Received contains an
indication that the object received is partial, the byte offset of
the data in the partial Message within the full Message, an
indication whether this is the last (highest-offset) partial Message
in the full Message, and an optional reference to the full Message it
belongs to.
Paragraph (version B):
Note that in the degenerate case - no message boundary preservation
and no deframing - the entire connection is represented as one large
message of indeterminate length.
Paragraph (version A):
Implementations of this interface must provide some way for the
application to indicate that it is temporarily not ready to receive
new Content.  Since the mechanisms of event handling are
implementation-platform specific, this document does not specify the
exact nature of this interface.
Paragraph (version A):
The Receive event is intended to be fired once per application-layer
Content sent by the remote endpoint; i.e., it is a desired property
of this interface that a Send at one end of a Connection maps to
exactly one Receive on the other end.  This is possible with Protocol
Stacks that provide message boundary preservation, but is not the
case over Protocol Stacks that provide a simple octet stream
transport.
Paragraph (version B):
The Receive event is intended to be fired once per application-layer
Message sent by the remote endpoint; i.e., it is a desired property
of this interface that a Send at one end of a Connection maps to
exactly one Receive on the other end.  This is possible with Protocol
Stacks that provide message boundary preservation, but is not the
case over Protocol Stacks that provide a simple octet stream
transport.
Paragraph (version A):
For preserving message boundaries over stream transports, this
interface provides receiver-side de-framing.  This facility is based
on the observation that, since many of our current application
protocols evolved over TCP, which does not provide message boundary
preservation, and since many of these protocols require message
boundaries to function, each application layer protocol has defined
its own framing.  A Deframer allows an application to push this de-
framing down into the interface, in order to transform an octet
stream into a sequence of Content.
Paragraph (version B):
The status of the Connection, which can be one of the following:
Establishing, Established, Closing, or Closed.
Paragraph (version A):
Protocol Properties of the protocols in use, once the Connection
has been established.  These properties correspond to the
properties given protocol-props and can be set and queried.
Paragraph (version B):
Protocol Properties of the Protocol Stack in use (see protocol-
props below).  These can be set or queried.  Certain specific
procotol queries may be read-only, on a protocol and property
specific basis.
Paragraph (version A):
Close terminates a Connection after satisfying all the requirements
that were specified regarding the delivery of Content that the
application has already given to the transport system.  For example,
if reliable delivery was requested for Content handed over before
calling Close, the transport system will ensure that such Content is
indeed delivered.  If the RemoteEndpoint still has data to send, it
cannot be received after this call.
Paragraph (version A):
The Closed event can inform the application that the RemoteEndpoint
has closed the Connection; however, there is no guarantee that a
remote close will be signaled.
Paragraph (version B):
Protocol Properties represent the configuration of the selected
Protocol Stacks backing a connection.  Some properties apply
generically across multiple transport protocols, while other
properties only apply to specific protocols.  The default settings of
these properties will vary based on the specific protocols being used
and the system's configuration.
Paragraph (version B):
Note that Protocol Properties are also set during pre-establishment,
as transport parameters, to preconfigure Protocol Stacks during
establishment.
Paragraph (version B):
Timeout for aborting Connection: This numeric property specifies
how long to wait before aborting a Connection during
establishment, or before deciding that a connection has failed
after establishment.  It is given in seconds.
Paragraph (version B):
Abort timeout to suggest to the Remote Endpoint: This numeric
property specifies the timeout to propose to the Remote Endpoint.
It is given in seconds.
Paragraph (version B):
Retransmission threshold before excessive retransmission
notification: This numeric property specifies after how many
retransmissions to inform the application about "Excessive
Retransmissions".
Paragraph (version B):
Required minimum coverage of the checksum for receiving: This
numeric property specifies the part of the received data that
needs to be covered by a checksum.  It is given in Bytes.  A value
of 0 means that no checksum is required, and a special value
(e.g., -1) indicates full checksum coverage.
Paragraph (version B):
Connection group transmission scheduler: This enumerated property
specifies which scheduler should be used among Connections within
a Connection Group.  It applies to connection groups; the set of
schedulers can be taken from I-D.ietf-tsvwg-sctp-ndata.
Paragraph (version B):
Maximum message size concurrent with connection establishment:
This numeric property represents the maximum Message size that can
be sent before or during Connection establishment, see also send-
idempotent.  It is given in Bytes.  This property is read-only.
Paragraph (version B):
Maximum Message size before fragmentation or segmentation: This
numeric property, if applicable, represents the maximum Message
size that can be sent without incurring network-layer
fragmentation and/or transport layer segmentation at the sender.
This property is read-only.
Paragraph (version B):
Maximum non-partial Message size on send: This numeric property
represents the maximum Message size that can be sent as a non-
partial Message.  This property is read-only.
Paragraph (version B):
Maximum non-partial Message size on receive: This numeric property
represents the maximum Message size that can be received as a non-
partial Message.  This property is read-only.
Paragraph (version B):
In order to specify Specific Protocol Properties, Transport System
implementations may offer applications to attach a set of options to
the Preconnection object, associated with a specific protocol.  For
example, an application could specify a set of TCP Options to use if
and only if TCP is selected by the system.  Such properties must not
be assumed to apply across different protocols.  Attempts to set
specific protocol properties on a protocol stack not containing that
specific protocol are simply ignored, and do not raise an error..
Paragraph (version B):
Close terminates a Connection after satisfying all the requirements
that were specified regarding the delivery of Messages that the
application has already given to the transport system.  For example,
if reliable delivery was requested for a Message handed over before
calling Close, the transport system will ensure that this Message is
indeed delivered.  If the Remote Endpoint still has data to send, it
cannot be received after this call.
Paragraph (version B):
The Closed event can inform the application that the Remote Endpoint
has closed the Connection; however, there is no guarantee that a
remote close will be signaled.