Draft: draft-ietf-taps-interface

Commentary: This PR should close Issue and . Change summary : Unify terminology : all ( Selection / Protocol / Message)-(Preferences / Properties / Parameters ) become Properties Adjusted Section 5.2 Adjusted Section 7.1 Adjusted Section 9 Add proper Property Types Describe how Preferences from Preconnections are reflected on Connections ( selection results ) Text on Property Classification Added " Control Properties " to catch transport system state like " Final " or notifications Added description of Intents ( to classify " Capacity Profile " ) Move all Properties to a single section ( Section 12 ) Unify Property Formatting Merge some message / connection properties Fix property types There are some  left in the text – mostly already existing inconsistencies that have become obvious due to the new structure / formatting . 
 this is a monster PR and will take a while even to review . As it stands , I do n't anticipate it landing before Montreal . Alternately , we could just land it as is in order to stop blocking , and file a flurry of issues on anything we find wrong with it ( I have a few already , in a pending review ... ) 
 ( Other reviewers : I suggest just looking at the document in its entirety with this PR here : https://taps- -- I 'm finding it much easier to read it that way than trying to navigate the giant diff on the MD ) 
 Sorry for the giant PR – we already tried to split it up in more or less useful commits , but tracking text moves is always tedious . I would be in favour of landing it and ripping the Properties apart afterwards . No matter what the consensus of the WG will finally be , in this form it should be much easier to discuss the problems and inconsistencies regarding properties than in the previous structure . I also see the categories and data types rather as something to start discussing than something I will fight for in every detail . 
 no problem , I do n't think there was any other way to do this ; just trying to figure out how to make best use of our time on this in Montreal . 
 ( I will say that seeing the properties expressed like this was much more useful to me than the Venn diagram in understanding the arrangement of things , and halfway through my review I think it needs a bit of tweaking , on which more later . ) 
 Thanks for this stab at cleaning up the terminology . Some high level comments from a quick read through . There are still a number of places using " parameter " which I find confusing . Two examples : Sec . 4 . " A Preconnection represents a set of parameters and constraints on the selection and configuration of paths and protocols to establish a Connection with a remote endpoint . " ; Sec . 5 " The pre - establishment phase allows applications to specify parameters for the Connections they ’re about to make " . Are those just mistakes or there is some intended distinction ? I thought they should all be properties now ? I see the benefit of having all the properties together in Section 12 , but this has also caused some other problems for the structure . The preceding sections use several of the concepts and properties from section 12 , some of those parts are now hard to interpret without the information . Not sure how to best solve this problem . I do not see any useful benefit from separating out control properties and intents . " Final " can for example equally well be a message property . I would just stick to Selection , Protocol and Message Properties to make things simpler and less confusing . 
 Thank you for your high - level feedback I just did another pass through the document to fix left - over parameters , so I hope your first issue is addressed now . Security Parameters still are Parameters to not divert from TLS terminology . To your second issue , I agree that a little more cross - references and explanation int he might be needed for better readability , but in my opinion , moving the vast amount of properties to Section 12 really improved readability of most parts of the document and makes the general idea of the API clearer . As many Protocol Properties apply to connections as well as messages , we find the term " Message Properties " misleading for classification of properties . The new terminology is really orthogonal : Everything is a Transport Property Transport properties can be applied to different objects Preconnections ( Connection Properties ) Connections ( also Connection Properties ) Messages ( Message Properties ) Transport properties can be classified by what and how they Effect things Selection Properties ( effect the selection process ) Protocol Properties ( effect protocols selected ) Control Properties ( effect the transport system / protocol state machine ) Intents ( may effect anything after being interoreted by the transport system ) 
 Hi , Thank you very much for this PR ! I have now also given this a close read ; my first reaction is that this structural re - working was much needed and does indeed clean things up nicely . While I understand the concern of about things being harder to read with all these forward references , I also agree with 's answer that this move was worth it and made it all clearer . I do n't understand this concern of ... as I ca n't see this PR stating that Message properties are protocol properties . Generally I 'd also be in favor of landing this and then fine - tuning it , either way I think it 's a better basis for the document structure , better get this in earlier than later . 
 reading comment , IMO we should converge very soon on " land this for -01 and fix it later " versus " hold for post - Montreal " . My 2c : I think the structural changes to the document are correct . I 'm less sure of the organization of properties ( sharing and concern ) but these are details . I have a few picky questions I would like to see addressed before merging though ( in the review ) . IMO we can land , submit  , discuss in the WG meeting , and fix for a -02 after Montreal . On this : I 'm possibly misreading the classification , and possibly not expressing myself very well . I 'll try to draw a picture to say what I mean soon . 
 on making a fast decision : please come have a look and chime in on " land and fix " versus " hold for fix " 
 I think landing this now is fine to allow other parts to progress after restructuring . I think we will find out if we in the end can push all information about the Transport Properties to one section , or if some parts need to be introduced earlier , but I agree it is good to have it all there for the discussion . If we land it for Montreal I would like us to simplify the structure of the properties before Montreal though . As also pointed out by it is better to start simple and then add additional classes if really needed . So I am very much in favor of having just two classes to start with : Selection and one more ( Protocol or Configuration ) . 
 I would prefer to discuss the classification of Transport Properties in Montreal – the work has been done in one way and classes can be easily merged if we agree that we need fewer classes , but have to be split up again if we are able to convince you that we need more . 
 The reason I think it is better to simplify first is that it seems all that have read it so far have had difficulties in understanding the separation between the classes . As it is not a difficult fix , I think it is better to simplify things before pushing it to the wg as other readers will likely have similar difficulties . We should also try to align the terminology in the other drafts which will be simpler with less constructs . We also have several outstanding pull requests that need to be merged . Having seen the new structure for the Send section in Tommy 's branch I think the send parameters should probably stay in that section . That would remove the message properties . 
 I still need to do my thorough pass on the PR , but my thoughts regarding schedule : I 'm in favor of landing this as part of -01 I disagree with some of the changes made to the sending of parameters section . I 'd like to land first , and then see how it merges into this PR overall . Many of the properties around sending have to do with scheduling a particular message , which I do n't necessarily believe belong in the generic list of properties , or at least need a separate section . 
 1 ) simplification vs. keeping the classification as - is : I 'd also like to insist on simplifying because a ) I do n't see it as hugely complicated to re - insert the properties into more categories again if we must , and b ) at least I , and it seems some more people , are going to disagree with the classification anyway . So what 's the point of first keeping it , then having us re - iterate that we do n't like it , and then having to change it later ? Starting simple is always good . 2 ) regarding PR , I read it carefully once more now , and I also agree that some message properties do n't need to be pulled out because they strictly only appear there . I see only 2 1/2 exceptions : the first two are " capacity profile " and " niceness " , for which it may be better to keep it as in this PR and simply refer forward to it in the sending section ( or vice versa ! ! Maybe even better ? ) . The 1/2 is the " corruption protection length " , which naturally fits together with " control checksum coverage on sending or receiving " ( ) but is split apart in . I do n't think this is a big issue though , and maybe better to keep them separate . ( ) Side note , I dislike the naming conflict between these two ; would n't " checksum coverage " be clearer than " corruption protection length " ? 
 I tend to think that this is PR an overall improvement , although there are details I 'd question . I 'd agree to land it , then iterate . 
 I 've just been discussing with for a while - I think a good way forward is to first land , then land this but without deleting stuff in the sending section . This will give us duplicate text - and then we start to look at these duplicates one by one . says that they found several inconsistencies , but on the other hand , it seems that has improved some text in . Sure we could just compare the branches but I think we should keep things from diverging more at this point , and first pull these two PR 's in one by one . ( I 'm only suggesting but hoping for to actually pull the trigger because I 'm afraid to mess something up - I 've never manually merged a PR ... ) 
 Thanks for all the comments so far . Regarding classification , I agree with making it simpler for now , and then discuss in Montreal . This would mean going back to Selection Properties , Protocol Properties , and Message Properties for now , which is also in line with the other drafts . I will move the classification for Control Properties and Intents to the Appendix for now , so we can still see these definitions , modify them , and move them back up if we decide we want them . After we decide on the classification we want , we can also discuss about in which category the individual Properties belong . About I 'd be okay with landing it and then adjusting this PR , but I 'm still not entirely sure about getting rid of the explicit MessageProperties ... 
 I agree to land PR ASAP and re - merge your changes to this one . I think we will need all " Control Properties " at least listed in Section 12 . This makes keeping related properties much easier . I agree to move the ones important to control flow , e.g. , final , back to Section 7 and only list / cross - reference them in Section 12 . Will do so after merging PR . 
 Looking at the document , it seems like it will be easier to discuss the classification when having it all in one place , so I did not move them to the Appendix , but instead labeled them as " TODO : Discuss " . 
 and – I totally agree that we need to simplify things . and I do not agree on the current classification --- but we agree that we a need for discussion about how to structure Properties . I see this classification rather as a basis for discussion in Montreal than as a final thingy I want to push . Therefore , I would like to have the proposed classification in -01 point will add the rationale behind it to this PR . After discussion for Montreal , I am pretty sure that we will have a totally different classification ( different from -00 and this proposal for -01 ) . 
 Now that landed , I merged the changes , changing all " parameters " to " properties " in line with this PR . After this initial merge , we now duplicate the following Properties in Section 7.3 and Section 12.3 : Lifetime is exactly the same , just adds Classification , Type , and Applicability in 12.3 Niceness , in Section 12.3 , can not only apply on a Message but also on a Connection relative to other Connections ( in the same group ) . Ordered has been slightly reworded in Section 12.3 in an attempt to make it more clear Idempotent is basically similar , just the start of the sentence has been slightly modified Final has been slightly reworded in Section 12.3 in an attempt to make it more clear Corruption protection length is exactly the same , just adds Classification , Type , and Applicability Transmission Profile from 7.3 basically became per - Message Capacity Profile in 12.3 , and has more levels in 12.3 Now we could move all Properties to 12.3 while forward - referencing them in 7.3 , merging the ones that are the same , and splitting Niceness and Capacity Profile into per - Connection and per - Message again . Alternatively , we could keep the duplicates for now and discuss further after landing this , but I would prefer to have the Properties all in one place . 
 I like this shorter list of 2 categories - selection looks like it is special , and then the stack needs configured .  
 I marked the Properties in 7.3 as " TODO : De - duplicate " . With this , and I think that this PR is ready to land . We are planning to prepare slides for Montréal summarizing the current status and the discussion points . 
 In my opinion , this PR should now address all changes requested or clearly mark them as discussion points . Slides for the Properties classification discussions in Montreal are ready . Can we land it ? 
 Thanks for the changes ! I ’m fine with landing this now , and look forward to the discussion it will create . Having this concrete set of items is a great framing to hold the conversation around . 
 In Section 9 – " Setting and Querying of Connection Properties " – the properties of an established connection and path are heavily underspecified . Should be fixed along with . 
 I 'm working on this issue within our pull request for , using the terminology as simplified there . For Section 9 , I 'm proposing the following : An application can query Connection Properties on a connection . Connection Properties include the status of the connection and whether it is possible to send and to receive data on it . ( One of them might not be possible , e.g. , in a unidirectional connection . ) Additionally , Connection Properties include the Connection 's Transport Properties . Transport Properties include Selection Properties , so the application can know which Protocol Selection Properties had been specified , and which ones are actually supported by the protocol that has been chosen . For Establishing connections ( i.e. , we are not done racing yet , the final protocols have not been selected yet ) , the application gets the Selection Properties that had been specified on the Preconnection earlier . For Established , Closing , or Closed connections ( i.e. , the protocols have been selected ) , the application learns whether the Selection Properties are actually provided by the selected protocols . For example , if the application specified earlier , " Control Checksum Coverage : Prefer " , now it will get " Control checksum coverage : True " , indicating that on this connection it can indeed control the checksum coverage . Transport Properties also include Protocol Properties (  and Specific ) . These Protocol Properties can still be modified by the application . Basically , Protocol Properties are the only thing that the application can still set , everything else it can only query at this point . Finally , the application can query properties of the path . Not sure how well we have to specify them , probably this part will be implementation - specific just like , e.g. , the Interface Instance or Type . Does everyone agree , or is there anything to discuss here ? For me this is not a big change , it 's just putting what was already there in terms of . The only thing I 'm wondering if whether the Protocol Selection Properties of the finally chosen protocols are still " Selection Properties " , as the selection is already done . That 's why they were called " Transport Features " before , but now I want less terms and they 're almost the same thing ... 
 OK - so I commented on these things before - but in these things I think I agree . I 'd personally prefer to keep the features as attributes implemented in the transport ( etc ) and the properties as the things requested . Indeed this begs the question about what to call the resulting transport when you selected properties and now get a transport . I think still calling them ( for consistency ) properties seems really good to me . :-) . 
 I 'll give my " ok " so at least I 'm not blocking this any further . As for the classification , I sincerely hope that we 'll not have more than the three that has mentioned , this seems just right ... but let 's see :) I 'm in favor of duplicates because the wording is not exactly equivalent . told me that you have found several inconsistencies ; has improved the wording here and there a little . I think we should compare the descriptions of the message properties one by one - removing the duplicates can then be a separate PR . It might be easiest to just mark them as DUPLICATE - TO BE FIXED or something like that .
Paragraph (version A):
This specification treats Events and errors similarly.  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):
This specification treats Events and errors similarly.  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
Properties.
Paragraph (version A):
The Transport Services Interface is the basic common abstract
application programming interface to the Transport Services
Architecture defined in I-D.ietf-taps-arch.  An application primarily
interacts with this interface through two Objects, Preconnections and
Connections.  A Preconnection represents a set of parameters and
constraints on the selection and configuration of paths and protocols
to establish a Connection with a remote endpoint.  A Connection
represents a transport Protocol Stack on which data can be sent to
and received from a remote endpoint.  Connections can be created from
Preconnections in three ways: by initiating the Preconnection (i.e.,
actively opening, as in a client), through listening on the
Preconnection (i.e., passively opening, as in a server), or
rendezvousing on the Preconnection (i.e. peer to peer establishment).
Paragraph (version B):
The Transport Services Interface is the basic common abstract
application programming interface to the Transport Services
Architecture defined in I-D.ietf-taps-arch.  An application primarily
interacts with this interface through two Objects, Preconnections and
Connections.  A Preconnection represents a set of properties and
constraints on the selection and configuration of paths and protocols
to establish a Connection with a remote endpoint.  A Connection
represents a transport Protocol Stack on which data can be sent to
and/or received from a remote endpoint (i.e., depending on the kind
of transport, connections can be bi-directional or unidirectional).
Connections can be created from Preconnections in three ways: by
initiating the Preconnection (i.e., actively opening, as in a
client), through listening on the Preconnection (i.e., passively
opening, as in a server), or rendezvousing on the Preconnection (i.e.
peer to peer establishment).
Paragraph (version A):
The pre-establishment phase allows applications to specify parameters
for the Connections they're about to make, or to query the API about
potential connections they could make.
Paragraph (version B):
The pre-establishment phase allows applications to specify properties
for the Connections they're about to make, or to query the API about
potential connections they could make.
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 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
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 A):
All Transport Parameters are organized within a single namespace
shared with Send Parameters (see send-params).  These transport
parameters take values of parameter-specific types.
Paragraph (version A):
Note that it is possible for a set of specified transport parameters
to be internally inconsistent, or to be inconsistent with the later
use of the API by the application.  Application developers can 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 any detected errors in configuration
as early as possible, to help ensure these inconsistencies are caught
early in the development process.
Paragraph (version B):
A Preconnection Object holds properties reflecting the application's
requirements and preferences for the transport.  These include
Selection Properties (Protocol and Path Selection Properties), as
well as Generic and Specific Protocol Properties for configuration of
the detailed operation of the selected Protocol Stacks.
Paragraph (version A):
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):
All transport parameters used in the pre-establishment phase are
collected in a TransportParameters Object that is passed to the
Preconnection Object.
Paragraph (version A):
The Individual parameters are then added to the TransportParameters
Object.  While Protocol Properties use the "add" call, Transport
Preferences use special calls for the levels defined in transport-
params.
Paragraph (version A):
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):
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):
This property specifies whether the application wishes to use a
transport protocol that that provides mechanisms to help ensure that
all data is received and without corruption on the other side.  This
also entails being notified when a Connection is closed or aborted.
This property applies to Connections and Connection Groups.  This is
a strict requirement.  The default is to enable Reliable Data
Transfer.
Paragraph (version A):
This property specifies whether the application wishes to use a
transport protocol that provides mechanisms to ensure that data is
received by the application on the other end in the same order as it
was sent.  This property applies to Connections and Connection
Groups.  This is a strict requirement.  The default is to preserve
data ordering.
Paragraph (version A):
This 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 A):
This 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 A):
This property specifies that the application would prefer multiple
Connections within a Connection Group to be provided by streams of a
single underlying transport connection where possible.  This is not a
strict requirement.  The default is to not have this option.
Paragraph (version A):
This property applies to Connections and Connection Groups.  The
default is to have this option.
Paragraph (version A):
This 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 A):
Session cache: Used to tune cache capacity, lifetime, re-use, and
eviction policies, e.g., LRU or FIFO.
Paragraph (version B):
All Transport Properties used in the pre-establishment phase are
collected in a TransportProperties Object that is passed to the
Preconnection Object.
Paragraph (version B):
The Individual properties are then added to the TransportProperties
Object.
Paragraph (version B):
transport-props provides a list of Transport Properties.
Paragraph (version B):
A Connection gets its Transport Properties either by being explicitly
configured via a Preconnection, or by inheriting them from an
antecedent via cloning; see groups for more.
Paragraph (version B):
Most security parameters, e.g., TLS ciphersuites, local identity and
private key, etc., may be configured statically.  Others are
dynamically configured during connection establishment.  Thus, we
partition security parameters and callbacks based on their place in
the lifetime of connection establishment.  Similar to Transport
Properties, both parameters and callbacks are inherited during
cloning (see groups).
Paragraph (version B):
Pre-Shared Key import: 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 Remote Endpoint.
Paragraph (version A):
Before a Connection can be used for data transfer, it must be
established.  Establishment ends the pre-establishment phase; all
transport and cryptographic parameter specification must be complete
before establishment, as these parameters will be used to select
candidate Paths and Protocol Stacks for the Connection.
Establishment may be active, using the Initiate() Action; passive,
using the Listen() Action; or simultaneous for peer-to-peer, using
the Rendezvous() Action.  These Actions are described in the
subsections below.
Paragraph (version B):
Before a Connection can be used for data transfer, it must be
established.  Establishment ends the pre-establishment phase; all
transport properties and cryptographic parameter specification must
be complete before establishment, as these will be used to select
candidate Paths and Protocol Stacks for the Connection.
Establishment may be active, using the Initiate() Action; passive,
using the Listen() Action; or simultaneous for peer-to-peer, using
the Rendezvous() Action.  These Actions are described in the
subsections below.
Paragraph (version A):
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 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 properties
necessary for candidate selection.  After calling Initiate, no
further properties may be added to the Preconnection.  The Initiate()
call consumes the Preconnection and creates a Connection Object.  A
Preconnection can only be initiated once.
Paragraph (version A):
An InitiateError occurs either when the set of transport and
cryptographic parameters cannot be fulfilled on a Connection for
initiation (e.g. the set of available Paths and/or Protocol Stacks
meeting the constraints is empty) or reconciled with the local and/or
remote endpoints; when the remote specifier cannot be resolved; or
when no transport-layer connection can be established to the remote
endpoint (e.g. because the remote endpoint is not accepting
connections, or the application is prohibited from opening a
Connection by the operating system).
Paragraph (version B):
An InitiateError occurs either when the set of transport properties
and cryptographic parameters cannot be fulfilled on a Connection for
initiation (e.g. the set of available Paths and/or Protocol Stacks
meeting the constraints is empty) or reconciled with the local and/or
remote endpoints; when the remote specifier cannot be resolved; or
when no transport-layer connection can be established to the remote
endpoint (e.g. because the remote endpoint is not accepting
connections, or the application is prohibited from opening a
Connection by the operating system).
Paragraph (version A):
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 A):
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 A):
The Rendezvous() Action consumes the Preconnection.  Once
Rendezvous() 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 Preconnection Object must be specified with both a Local Endpoint
and a Remote Endpoint, and also the transport properties 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 Rendezvous() Action consumes the Preconnection.  Once
Rendezvous() has been called, no further properties may be added to
the Preconnection, and no subsequent establishment call may be made
on the Preconnection.
Paragraph (version A):
are given about capacity allocation and each implementation is free
to implement exact capacity allocation as it sees fit.
Paragraph (version A):
If Send is called on a Connection which has not yet been established,
an Initiate Action will be implicitly performed simultaneously with
the Send.  Used together with the Idempotent property (see send-
idempotent), this can be used to send data during establishment for
0-RTT session resumption on Protocol Stacks that support it.
Paragraph (version A):
Like all Actions in this interface, the Send Action is asynchronous.
Paragraph (version B):
are given about the way capacity is shared.  Each implementation is
free to implement a way it shares capacity that it sees fit.
Paragraph (version B):
The interpretation of a Message to be sent is dependent on the
implementation, and on the constraints on the Protocol Stacks implied
by the Connection's transport properties.  For example, a Message may
be a single datagram for UDP Connections; or an HTTP Request for HTTP
Connections.
Paragraph (version B):
Like all Actions in this interface, the Send Action is asynchronous.
There are several events that can be delivered in response to Sending
a Message.
Paragraph (version B):
Note that if partial Sends are used (send-partial), there will still
be exactly one Send Event delivered for each call to Send.  For
example, if a Message expired while two requests to Send data for
that Message are outstanding, there will be two Expired events
delivered.
Paragraph (version A):
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 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 Properties.  The Sent Event contains an
implementation-specific reference to the Message to which it applies.
Paragraph (version A):
A SendError occurs when a Message could not be sent due to an error
condition: an attempt to send a Message which is too large for the
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 A):
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 A):
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 A):
The Send Parameters share a single namespace with the Transport
Parameters (see transport-params).  This allows the specification of
Protocol Properties that can be overridden on a per-Message basis.
Paragraph (version A):
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 B):
A SendError occurs when a Message could not be sent due to an error
condition: an attempt to send a Message which is too large for the
system and Protocol Stack to handle, some failure of the underlying
Protocol Stack, or a set of Message Properties not consistent with
the Connection's transport properties.  The SendError contains an
implementation-specific reference to the Message to which it applies.
Paragraph (version B):
Applications may need to annotate the Messages they send with extra
information to control how data is scheduled and processed by the
transport protocols in the Connection.  A MessageContext object
contains parameters for sending Messages, and can be passed to the
Send Action.  Some of these parameters are properties as defined in
transport-props.  Note that these properties are per-Message, not
per-Send if partial Messages are sent (send-partial).  All data
blocks associated with a single Message share properties.  For
example, it would not make sense to have the beginning of a Message
expire, but allow the end of a Message to still be sent.
Paragraph (version B):
The simpler form of Send that does not take any MessageContext is
equivalent to passing a default MessageContext with not values added.
Paragraph (version B):
Message Properties share a single namespace with Transport Properties
(see transport-props).  This allows the specification of per-
Connection Protocol Properties that can be overridden on a per-
Message basis.
Paragraph (version B):
If an application wants to override Message Properties for a specific
message, it can acquire an empty messageContext Object and add all
desired Message Properties to that Object.  It can then reuse the
same messageContext Object for sending multiple Messages with the
same properties.
Paragraph (version B):
Message Properties may be inconsistent with the properties of the
Protocol Stacks underlying the Connection on which a given Message is
sent.  For example, a Connection must provide reliability to allow
setting an infinitie value for the lifetime property of a Message.
Sending a Message with Message Properties inconsistent with the
Selection Properties of the Connection yields an error.
Paragraph (version A):
Note that this inversion of normal schemes for expressing priority
has a convenient property: priority increases as both Niceness and
Lifetime decrease.
Paragraph (version B):
Note that a Final Message must always be sorted to the end of a list
of Messages.  The Final property overrides Niceness and any other
property that would re-order Messages.  If another Message is sent
after a Message marked as Final has already been sent on a
Connection, the new Message will report an error.
Paragraph (version B):
It is not always possible for an application to send all data
associated with a Message in a single Send Action.  The Message data
may be too large for the application to hold in memory at one time,
or the length of the Message may be unknown or unbounded.
Paragraph (version B):
Partial Message sending is supported by passing an endOfMessage
boolean parameter to the Send Action.  This value is always true by
default, and the simpler forms of send are equivalent to passing true
for endOfMessage.
Paragraph (version B):
The following example sends a Message in two separate calls to Send.
Paragraph (version A):
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 A):
Receive takes 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):
Receive also takes an optional maxLength argument, the maximum size
(in bytes of data) Message the application is currently prepared to
receive.  The default value for maxLength is infinite.  If an
incoming Message is larger than the minimum of this size and the
maximum Message size on receive for the Connection's Protocol Stack,
it will be received as a partial Message.  Note that maxLength does
not guarantee that the application will receive that many bytes if
they are available; the interface may return partial Messages smaller
than maxLength according to implementation constraints.
Paragraph (version A):
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):
Receive takes two parameters to specify the length of data that an
application is willing to receive, both of which are optional and
have default values if not specified.
Paragraph (version B):
By default, Receive will try to deliver complete Messages in a single
event (receive-complete).
Paragraph (version B):
Each call to Receive will be paired with a single Receive Event,
which can be a success or an error.  This allows an application to
provide backpressure to the transport stack when it is temporarily
not ready to receive messages.
Paragraph (version A):
Note that in the absence of message boundary preservation and without
deframing, the entire Connection is represented as one large message
of indeterminate length.
Paragraph (version B):
The ReceiveError event passes an optional associated messageContext.
This may indicate that a Message that was being partially received
previously, but had not completed, encountered and error and will not
be completed.
Paragraph (version B):
In some cases it may be valuable to know whether data was read as
part of early data streams.  This is useful if applications need to
treat early data separately, e.g., if early data has different
security properties than data sent after connection establishment.
In the case of TLS 1.3, client early data can be replayed maliciously
(see I-D.ietf-tls-tls13).  Thus, receivers may wish to perform
additional checks for early data to ensure it is idempotent or not
replayed.  If TLS 1.3 is available and the recipient Message was sent
as part of early data, the corresponding metadata carries a flag
indicating as such.  If early data is enabled, applications should
check this metadata field for Messages received during connection
establishment and respond accordingly.
Paragraph (version B):
Any calls to Receive once the Final Message has been delivered will
result in errors.
Paragraph (version A):
At any point, the application can set and query the properties of a
Connection.  Depending on the phase the Connection is in, the
Connection properties will include different information.
Paragraph (version A):
Transport Features of the protocols that conform to the Required
and Prohibited Transport Preferences, which might be selected by
the transport system during Establishment.  These features
correspond to the properties given in transport-params and can
only be queried.
Paragraph (version A):
Transport Features of the Protocol Stacks that were selected and
instantiated, once the Connection has been established.  These
features correspond to the properties given in transport-params
and can only be queried.  Instead of preference levels, these
features have boolean values indicating whether or not they were
selected.  Note that these transport features may not fully
reflect the specified parameters given in the pre-establishment
phase.  For example, a certain Protocol Selection Property that an
application specified as Preferred may not actually be present in
the chosen Protocol Stack Instances because none of the currently
available transport protocols had this feature.
Paragraph (version A):
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):
Path Properties of the path(s) in use, once the Connection has
been established.  These properties can be derived from the local
provisioning domain, measurements by the Protocol Stack, or other
sources.  They can only be queried.
Paragraph (version A):
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 A):
Note that Protocol Properties are also set during pre-establishment,
as transport parameters, to preconfigure Protocol Stacks during
establishment.
Paragraph (version A):
Relative niceness: This numeric property is similar to the
Niceness send property (see send-niceness), a non-negative integer
representing the relative inverse priority of this Connection
relative to other Connections in the same Connection Group.  It
has no effect on Connections not part of a Connection Group.  As
noted in groups, this property is not entangled when Connections
are cloned.
Paragraph (version A):
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 A):
Retransmission threshold before excessive retransmission
notification: This numeric property specifies after how many
retransmissions to inform the application about "Excessive
Retransmissions".
Paragraph (version A):
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):
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 A):
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 A):
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 A):
Maximum Message size on send: This numeric property represents the
maximum Message size that can be sent.  This property is read-
only.
Paragraph (version A):
Maximum Message size on receive: This numeric property represents
the maximum Message size that can be received.  This property is
read-only.
Paragraph (version B):
At any point, the application can query Connection Properties.  It
can also set per-connection Protocol Properties.
Paragraph (version B):
Whether the connection can be used to send data.  A connection can
not be used for sending if the connection was created with the
Selection Property "Unidirectional Receive" or if a Message marked
as "Final" was sent over this connection, see send-final.
Paragraph (version B):
Whether the connection can be used to receive data.  A connection
can not be used for reading if the connection was created with the
Selection Property "Unidirectional: Send" or if a Message marked
as "Final" was received, see receiving-final-messages.  The latter
is only supported by certain transport protocols, e.g., by TCP as
half-closed connection.
Paragraph (version B):
For Connections that are Establishing: Transport Properties that
the application specified on the Preconnection, see connection-
props.  Selection Properties of a Connection can only be queried,
not set.
Paragraph (version B):
For Connections that are Established, Closing, or Closed (TODO:
double-check if closed belongs here): Transport Properties of the
actual protocols that were selected and instantiated.  These
features correspond to the properties given in transport-props and
include Selection Properties and Protocol Properties.
Paragraph (version B):
Selection Properties indicate whether or not the Connection has
or offers a certain Selection Property.  Note that the actually
instantiated protocol stack may not match all Protocol
Selection Properties that the application specified on the
Preconnection.  For example, a certain Protocol Selection
Property that an application specified as Preferred may not
actually be present in the chosen protocol stack because none
of the currently available transport protocols had this
feature.  Selection Properties of a Connection can only be
queried.
Paragraph (version B):
Protocol Properties of the protocol stack in use (see protocol-
props below).  These can be queried and set.  Certain specific
Procotol Properties may be read-only, on a protocol- and
property-specific basis.
Paragraph (version B):
For Connections that are Established, properties of the path(s) in
use.  These properties can be derived from the local provisioning
domain RFC7556, measurements by the Protocol Stack, or other
sources.  They can only be queried.
Paragraph (version B):
Sent<> events will occur on a Connection in the order in which the
Messages were sent (i.e., delivered to the kernel or to the
network interface, depending on implementation).
Paragraph (version B):
Transport Properties allow an application to control and introspect
most aspects of the transport system and transport protocols.
Paragraph (version B):
By how they influence the transport system, which leads to a
classification into "Selection Properties", "Protocol Properties",
"Control Properties" and "Intents".
Paragraph (version B):
By the object they can be applied to: Preconnections, see
connection-props, Connections, see introspection, and Messages,
see message-props.
Paragraph (version B):
Because some properties can be applied or queried on multiple
objects, all Transport Properties are organized within a single
namespace.
Paragraph (version B):
Note that it is possible for a set of specified Transport Properties
to be internally inconsistent, or to be inconsistent with the later
use of the API by the application.  Application developers can reduce
inconsistency by only using the most stringent preference levels when
failure to meet the property would break the application's
functionality.  For example, it can set the Selection Property
"Reliable Data Transfer", which is a core assumption of many
application protocols, as Required.  Implementations of this
interface should also raise any detected errors in configuration as
early as possible, to help ensure that inconsistencies are caught
early in the development process.
Paragraph (version B):
Each Transport Property takes a value of a property-specific type.
Paragraph (version B):
A boolean is a data type that can be either "true" or "false".
Boolean transport properties should only be used for properties that
can not be used in an optional way or to query the state of the
transport implementation.  For optional features, especially in
Selection Properties, the usage of the Preference type (see
transport-props-preference) is preferred.
Paragraph (version B):
Enumeration types are used for transport properties that can take one
value out of a limited set of choices.  The representation is
implementation dependent.
Paragraph (version B):
Integer types are used to represent integer numbers.  The
representation is implementation dependent.
Paragraph (version B):
When used on a Connection, this type becomes a (read-only) Boolean
representing whether the selected transport supports the requested
feature.
Paragraph (version B):
This section is subject to WG discussion on IETF-102.
Paragraph (version B):
Whether properties have a clearly defined behavior that is likely
to be invariant across implementations and environments (Protocol
Properties and Control Properties) or whether the properties are
interpreted by the transport system to provide a best effort
service that matches the applications needs as well as possible
(Intents).
Paragraph (version B):
in I-D.ietf-taps-interface-00, we had a classification into
Connection Properties and Message Properties, whereby Connection
Properties where itself were sub-classified in Protocol-Selection,
Path-Selection and Protocol properties.
Paragraph (version B):
The classification in this version of the draft emphasizes the way
the property affects the transport system and protocols.  It
treats the aspect of whether properties are used on a connection,
preconnection or message as an orthogonal dimension of
classification.
Paragraph (version B):
The "Message Properties" from I-D.ietf-taps-interface-00 therefore
have been split into "Protocol Properties" - emphasizing that they
affect the protocol configurations - and "Control Properties" -
emphasizing that they control the local transport system itself.
Paragraph (version B):
Selection Properties influence protocol and path selection.  Their
value usually is or includes a Preference that constrains (in case of
Require or Prohibit) or influences (Prefer, Ignore, Avoid) the
selection of transport protocols and paths used.
Paragraph (version B):
Protocol Selection Properties can only be set on Preconnections, see
connection-props.  Path Selection Properties are usually used on
Preconnections, but might also be used on messages to assist per-
message path selection for multipath aware protocols.
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.  Generic properties will
be passed to the selected candidate Protocol Stack(s) to configure
them before candidate Connection establishment.  The default settings
of these properties will vary based on the specific protocols being
used and the system's configuration.
Paragraph (version B):
Most Protocol Properties can be set on a Preconnection during pre-
establishment to preconfigure Protocol Stacks during establishment.
Paragraph (version B):
Note that many protocol properties have a corresponding selection
property which asks for a protocol providing a specific transport
feature that is controlled by the protocol property.
Paragraph (version B):
Control properties manage the local transport system behavior or
request state changes in the local transport system.  Depending on
the protocols used, setting these properties might also influence the
protocol state machine.  See send-final for an example.
Paragraph (version B):
Intents are hints to the transport system that do not directly map to
a single protocol/transport feature or behavior of the transport
system, but express a presumed application behavior or generic
application needs.
Paragraph (version B):
The application can expect the transport system to take appropriate
actions involving protocol selection, path selection and, setting of
protocol flags.  For example, if an application sets the "Capacity
Profile" to "bulk" on a Preconnection, this will likely influence
path selection, DSCP flags in the IP header as well as niceness for
multi-streaming connections.  When using Intents, the application
must not expect consistent behavior across different environments,
implementations or versions of the same implementation.
Paragraph (version B):
See final.
Paragraph (version B):
This property specifies whether the application wishes to use a
transport protocol that ensures that all data is received on the
other side without corruption.  This also entails being notified when
a Connection is closed or aborted.  The default is to enable Reliable
Data Transfer.
Paragraph (version B):
This 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.  The default
is to not have this option.
Paragraph (version B):
This property specifies that a message should be sent in such a way
that the transport protocol ensures all data is received on the other
side without corruption.  Changing the 'Reliable Data Transfer'
property on Messages is only possible if the transport protocol
supports partial reliability (see prop-partially-reliable).
Therefore, for protocols that always transfer data reliably, this
property is always true and for protocols that always transfer data
unreliably, this flag is always false.  Changing it may generate an
error.
Paragraph (version B):
This property specifies whether the application wishes to use a
transport protocol that ensures that data is received by the
application on the other end in the same order as it was sent.  The
default is to preserve data ordering.
Paragraph (version B):
This property specifies that a Message should be delivered to the
other side after the previous Message which was passed to the same
Connection via the Send Action.  It us used for protocols that
support preservation of data ordering, see prop-ordering, but allow
out-of-order delivery for certain messages.
Paragraph (version B):
This 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.  The default is to not have this option.
Paragraph (version B):
This property specifies that a Message is safe to send to the remote
endpoint more than once for a single Send Action.  It is used to mark
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):
The application can query the maximum size of a message that can be
sent idempotent, see size-idempotent.
Paragraph (version B):
This property specifies that the application would prefer multiple
Connections within a Connection Group to be provided by streams of a
single underlying transport connection where possible.  The default
is to not have this option.
Paragraph (version B):
The default is to have this option.
Paragraph (version B):
This property specifies whether the application considers it useful
to enable, disable, or configure a checksum when sending a Message,
or configure whether to require a checksum or not when receiving.
The default is full checksum coverage without the option to configure
it, and requiring a checksum when receiving.
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 the 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):
Interface types should not be treated as a proxy for properties of
interfaces such as metered or unmetered network access.  If an
application needs to prohibit metered interfaces, this should be
specified via Provisioning Domain attributes prop-pvd or another
specific property.
Paragraph (version B):
Similar to interface instances and types prop-interface, this
property allows the application to control path selection by
selecting which specific Provisioning Domains or categories of
Provisioning Domains it wants to "Require", "Prohibit", "Prefer", or
"Avoid".  Provisioning Domains define consistent sets of network
properties that may be more specific than network interfaces RFC7556.
Paragraph (version B):
Categories or types of PvDs are also defined to be implementation-
and system-specific.  These may be useful to identify a service that
is provided by a PvD.  For example, if an application wants to use a
PvD that provides a Voice-Over-IP service on a Cellular network, it
can use the relevant PvD type to require some PvD that provides this
service, without needing to look up a particular instance.  While
this does restrict path selection, it is more broad than requiring
specific PvD instances or interface instances, and should be
preferred over those options.
Paragraph (version B):
This property specifies whether the application would like the
Connection to be congestion controlled or not.  Note that if a
Connection is not congestion controlled, an application using such a
Connection should itself perform congestion control in accordance
with RFC2914.  Also note that reliability is usually combined with
congestion control in protocol implementations, rendering "reliable
but not congestion controlled" a request that is unlikely to succeed.
The default is that the Connection is congestion controlled.
Paragraph (version B):
This property is a numeric (non-negative) value that represents an
unbounded hierarchy of priorities.  It can specify the priority of a
Message, relative to other Messages sent over the same Connection
and/or Connection Group (see groups), or the priority of a
Connection, relative to other Connections in the same Connection
Group.
Paragraph (version B):
As noted in groups, when set on a Connection, this property is not
entangled when Connections are cloned.
Paragraph (version B):
This 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):
This 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):
This 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):
This property represents the maximum Message size that can be sent.
This property is read-only.
Paragraph (version B):
This numeric property represents the maximum Message size that can be
received.  This property is read-only.
Paragraph (version B):
TODO: Maybe move some of the above properties here.
Paragraph (version B):
TODO: Move appendix-non-consensus here.