10.3.  The mapping of a TLS stream abstraction into the application is equivalent to the contract provided by TCP (see tcp), and builds upon many of the actions of TCP connections. Implementations do not need to wait to receive "close_notify" before delivering the "Closed" event. <del> 10.4. </del>  DTLS follows the same behavior as TLS (tls), with the notable exception of not inheriting behavior directly from TCP.  Differences received DTLS datagram.  If a "close_notify" is received, a Message will be delivered that is marked as Final. <del> 10.5. </del>  HTTP requests and responses map naturally into Messages, since they are delineated chunks of data with metadata that can be sent over a support multiplexing.  For HTTP/2, for example, closing the connection only closes a specific stream. <del> 10.6. </del>  QUIC provides a multi-streaming interface to an encrypted transport. Each stream can be viewed as equivalent to a TLS stream over TCP, so Connection objects represent a single QUIC stream on a QUIC connection. <del> 10.7. </del>  Similar to QUIC (quic), HTTP/2 provides a multi-streaming interface. This will generally use HTTP as the unit of Messages over the Connection objects represent a single HTTP/2 stream on a HTTP/2 connection. <del> 10.8. </del>  Connectedness: Connected

URL After some discussion with Max and Theresa, we believe the interface draft does not need any changes. This adds a UDP Multicast Receive protocol-specific section to outline the specific considerations for a UDP multicast receive connection.
Of course it's fantastic if we can keep things as simple as that! URL I must be missing something. E.g., from this PR: So this means that I can create a connection but never use a Send on it. Actually, I can't even use Initiate. Fine... but where in the process do I learn (or, rather, specify and then expect) that this is the case?
You need to specify a selection property requesting a unidirectional/receive connection, therefore you are aware of it when the connection is ready.
Sure, that's how I'd also do it - but that selection property doesn't exist AFAICT. So, that's the required change to the API then.
The way we are doing it is that we check if the address of the local endpoint is a mc group address. So thats where the distinction between unicast and multicast is made. If that is the case we also require the transport properties to include that the direction is unidirection receive.
Ah, sure. That makes the most sense. Still, that's also not written in the API document. I'm just saying this should be there.
Well, there is a Connection Property called "Direction of communication" (Section 5.2.13 in the API draft). Maybe this should be a Selection Property instead? Because those you have to specify before the Connection gets established. Also, do you think it's worth adding to that section that it's not supported to call Send() on a unidirectional receive Connection or Receive() on a unidirectional send Connection? Initiate() being unsupported is probably not something that applies to all unidirectional receive Connections, even though I haven't thought about use cases other than multicast yet.
Yes and yes. "Direction of communication" should be a selection property, as it's unlikely to make sense as something to change later. Also, just because that exists, there's no relationship to multicast in the text - the word "multicast" doesn't exist in the API draft right now. I'm thinking that somewhere, almost literally the statement from NAME above should be added. Something like this: If the address of the local endpoint is a multicast group address: The "Direction of communication" selection property must be set to unidirectional receive. Initiate, Send, ... (list them all here) are not supported. (whatever else should be said.)
Oh, I just realized that "Direction of communication" already is a Selection Property, so we don't need to change anything there. But yes, it probably makes sense to add a paragraph on multicast to the "Specifying Endpoints" section 5.1 in the API draft.
We did not make it a selection property, because it is not of Preference type it should be queryable and probably may change to bidi after establishment if the underlaying protocol is bi-directional it my be settable from bidi to recv to half-close connections. Yes, this is one of the properties where our categories do not work so great.
NAME - that's ok, then we leave the property type as it is.
I think this is the mapping that works best for multicast. Just to give a bit of context: First, we tried to fit multicast into Initiate() because the multicast receiver actively joins a group. However, this doesn't work for Any-source Multicast, as Initiate() requires a remote endpoint. Re-reading our definitions in the architecture draft for Listener, Connection, and so on, I think we don't need to change them, as they are already generic enough for multicast to fit in there. In the Implementation draft, at the beginning of Section 2 it says that a listener is "a passive waiting object". Here, "passive waiting" sounds a bit off to me if a listener can actively join a multicast group. So maybe we want to change that to just say that a listener is "an object that can receive incoming connections".I think this is fine besides a little nit.

10.3. <ins> Connectedness: Unconnected Data Unit: Datagram API mappings for Receiving Multicast UDP are as follows: Established UDP Multicast Receive connections represent a pair of specific IP addresses and ports.  The "unidirectional receive" transport property is required, and the local endpoint must be configured with a group IP address and a port. Calling "Initiate" on a UDP Multicast Receive Connection causes an immediate InitiateError.  This is an unsupported operation. Calling "InitiateWithSend" on a UDP Multicast Receive Connection causes an immediate InitiateError.  This is an unsupported operation. A UDP Multicast Receive Connection is ready once the system has received traffic for the appropriate group and port. UDP Multicast Receive Connections generate an InitiateError if Initiate is called. Once in use, UDP throws "soft errors" (ERROR.UDP(-Lite)) upon receiving ICMP notifications indicating failures in the network. LISTEN.UDP.  Calling "Listen" for UDP Multicast Receive binds a local port, prepares it to receive inbound UDP datagrams from peers, and issues a multicast host join.  If a remote endpoint with an address is supplied, the join is Source-specific Multicast, and the path selection is based on the route to the remote endpoint.  If a remote endpoint is not supplied, the join is Any-source Multicast, and the path selection is based on the outbound route to the group supplied in the local endpoint. UDP Multicast Receive Listeners will deliver new connections once they have received traffic from a new Remote Endpoint. Calling "Clone" on a UDP Multicast Receive Connection creates a new Connection with equivalent parameters.  The two Connections are otherwise independent. SEND.UDP(-Lite).  Calling "Send" on a UDP Multicast Receive connection causes an immediate SendError.  This is an unsupported operation. RECEIVE.UDP(-Lite).  The Receive operation in a UDP Multicast Receive connection only delivers complete Messages to "Received", each of which represents a single datagram received in a UDP packet.  Upon receiving a UDP datagram, the ECN flag from the IP header can be obtained (GET_ECN.UDP(-Lite)). Calling "Close" on a UDP Multicast Receive Connection (ABORT.UDP(- Lite)) releases the local port reservation and leaves the group. Calling "Abort" on a UDP Multicast Receive Connection (ABORT.UDP(- Lite)) is identical to calling "Close". 10.4. </ins> The mapping of a TLS stream abstraction into the application is equivalent to the contract provided by TCP (see tcp), and builds upon many of the actions of TCP connections. Implementations do not need to wait to receive "close_notify" before delivering the "Closed" event.  <ins> 10.5. </ins> DTLS follows the same behavior as TLS (tls), with the notable exception of not inheriting behavior directly from TCP.  Differences received DTLS datagram.  If a "close_notify" is received, a Message will be delivered that is marked as Final.  <ins> 10.6. </ins> HTTP requests and responses map naturally into Messages, since they are delineated chunks of data with metadata that can be sent over a support multiplexing.  For HTTP/2, for example, closing the connection only closes a specific stream.  <ins> 10.7. </ins> QUIC provides a multi-streaming interface to an encrypted transport. Each stream can be viewed as equivalent to a TLS stream over TCP, so Connection objects represent a single QUIC stream on a QUIC connection.  <ins> 10.8. </ins> Similar to QUIC (quic), HTTP/2 provides a multi-streaming interface. This will generally use HTTP as the unit of Messages over the Connection objects represent a single HTTP/2 stream on a HTTP/2 connection.  <ins> 10.9. </ins> Connectedness: Connected


multipath <del> This property specifies whether an application considers it useful to transfer data across multiple paths between the same end hosts. Generally, in most cases, this will improve performance (e.g., achieve greater throughput).  One possible side-effect is increased jitter, which may be problematic for delay-sensitive applications. The recommended default is to Ignore this option. </del>  5.2.14.

Complete
Thanks Tommy! I think this looks good The meaning of Interactive is a bit fuzzy, but not sure if we can solve that.

multipath  <ins> Enumeration This property specifies whether an application wants to take advantage of transferring data across multiple paths between the same end hosts.  Using multiple paths allows connections to migrate between interfaces as availability and performance properties change. Possible values are: The connection will not attempt using multiple paths once established The connection should attempt to migrate between different paths upon interface availability changes The connection should attempt to use multiple paths in response to loss or delay upon individual paths The connection should attempt to use multiple paths in parallel in order to maximize bandwidth The default is Disabled.  The other enumeration values are all interpreted as preferences. </ins> 5.2.14.


5.2.12.  multipath This property specifies whether an application considers it useful to jitter, which may be problematic for delay-sensitive applications. The recommended default is to Ignore this option. <del> 5.2.13. </del>  direction specifying unidirectional communication may cause a transport stack that supports bidirectional communication to be selected. <del> 5.2.14. </del>  Name: :retransmit-notify be informed in case sent data was retransmitted more often than a certain threshold.  The default is to Ignore this option. <del> 5.2.15. </del>  Name: :soft-error-notify

Address
API should allow a preconnection property to specify if a private (IPv6) address is preferred. Outbound connections should prefer this. Listeners should avoid this.
Thank you! I was really missing this one .LGTM!

5.2.12. <ins> local-address-preference Enumeration This property specifies whether Listeners and Connections should prefer the use of temporary addresses when possible.  This is generally used to prevent linking connections over time when a stable address is not needed.  Possible values are: Prefer the use of stable (sometimes called "permanent") local addresses Prefer the use of temporary (sometimes called "privacy") addresses Prefer the use of stable local addresses for Listeners and Rendezvous Connections, and prefer the use of temporary addresses for other Connections. 5.2.13. </ins> multipath This property specifies whether an application considers it useful to jitter, which may be problematic for delay-sensitive applications. The recommended default is to Ignore this option.  <ins> 5.2.14. </ins> direction specifying unidirectional communication may cause a transport stack that supports bidirectional communication to be selected.  <ins> 5.2.15. </ins> Name: :retransmit-notify be informed in case sent data was retransmitted more often than a certain threshold.  The default is to Ignore this option.  <ins> 5.2.16. </ins> Name: :soft-error-notify


Listen: The action of marking a Listener as willing to accept incoming Connections.  The Listener will then create Connection <del> objects as incoming connections are accepted (events). </del>  Rendezvous: The action of establishing a peer-to-peer connection with a Remote Endpoint.  It simultaneously attempts to initiate a connection from that endpoint.  This corresponds, for example, to a TCP simultaneous open RFC0793.  The process of identifying options for the connection, such as resolution of the Remote <del> Endpoint, occurs during the Rendezvous call.  If successful, the rendezvous call returns a Connection object to represent the established peer-to-peer connection. </del>  4.1.4.

Address
meh okay if we must. :P nah this is great, already merged it.Fine - works

Listen: The action of marking a Listener as willing to accept incoming Connections.  The Listener will then create Connection  <ins> objects as incoming connections are accepted (events).  Listeners by default register with multiple paths and local endpoints, unless constrained by Selection Properties.  Connections can be accepted on any of the available paths or endpoints. </ins> Rendezvous: The action of establishing a peer-to-peer connection with a Remote Endpoint.  It simultaneously attempts to initiate a connection from that endpoint.  This corresponds, for example, to a TCP simultaneous open RFC0793.  The process of identifying options for the connection, such as resolution of the Remote  <ins> Endpoint, occurs during the Rendezvous call.  As with Listeners, the set of local paths and endpoints is contrained by Selection Properties.  If successful, the Rendezvous call returns a Connection object to represent the established peer-to-peer connection. </ins> 4.1.4.


Note that maxLength does not guarantee that the application will receive that many bytes if they are available; the interface may return ReceivedPartial events with less data than maxLength according <del> to implementation constraints. </del>  8.2.

It should be made more clear in what order queued receives are considered, i.e. what happens if an application calls Receive(minIncompleteLength=20), then calls Receive(minIncompleteLength=1). What now happens if e.g. 10 bytes of data arrive? Will the second receive only be considered after the first has been fulfilled?
It would seem natural to me that enqueuing is what it is - i.e., saying once "I can receive blocks of at least 20 bytes" cannot be undone. So, if the sequence is: 1) Receive(minIncompleteLength=20) 2) Receive(minIncompleteLength=1) 3) 10 bytes arrive ... then the first Receive call should be the one that matters, and the 10 bytes would have to wait until another 10 bytes arrive before the second Receive call can be processed. I think that NAME should add a clarifying sentence because his implementation probably already does it in one way or another.
Perhaps its not such a big issue, but I think this would take the option away from application developers to have an OR option for receives. For example, an application would have no way to say that it wants to receive either something with minIncompleteLength 100 or MaxLength 10. I also think there might be some confusion when it comes to requiring message ordering. For example: Application calls Receive(maxLength=10) Application calls Receive(maxLength=20) Message with length 20 arrives Message with length 10 arrives Application get received callback for message with length 10 Application get received callback for message with length 20 For the application it now seems that the message with length 10 arrived before the one with length 20 even though that is not the case.

Note that maxLength does not guarantee that the application will receive that many bytes if they are available; the interface may return ReceivedPartial events with less data than maxLength according  <ins> to implementation constraints.  Note also that maxLength and minIncompleteLength are intended only to manage buffering, and are not interpreted as a reciever preference for message reordering. </ins> 8.2.


potential connection.  It has state that describes parameters of a Connection that might exist in the future: the Local Endpoint from which that Connection will be established, the Remote Endpoint <del> (preestablishment) to which it will connect, and Selection Properties (preestablishment) that influence the paths and protocols a Connection will use.  A Preconnection can be fully specified such that it represents a single possible Connection, or it can be partially specified such that it represents a family of possible Connections.  The Local Endpoint (preestablishment) MUST be specified if the Preconnection is used to Listen for incoming </del>  connections.  The Local Endpoint is OPTIONAL if it is used to Initiate connections.  The Remote Endpoint MUST be specified in the Preconnection that is used to Initiate connections.  The be specified if a peer-to-peer Rendezvous is to occur based on the Preconnection. <del> Transport Properties: Transport Properties can be specified as part of a Preconnection to allow the application to configure the Transport System and express their requirements, prohibitions, and preferences.  There are three kinds of Transport Properties: </del>  <del> Selection Properties (preestablishment) </del>  <del> Connection Properties (preestablishment) </del>  <del> and Message Properties (datatransfer); note that Message Properties can also be specified during data transfer to affect specific Messages. </del>  Connection: A Connection object represents one or more active transport protocol instances that can send and/or receive Messages

I propose this diff instead—just indent Transport Properties where it is, as a sub-part of Preconnection:
Tried that… looks strange:
eh... it looks a little odd but it is technically more correct.
So the whole point of this text is to introduce the term Transport Properties I think. Otherwise we could have just removed it as the three kinds are described in detail in later sections. Perhaps we can just insert this as running text at the end of the Preconnection description instead to make it look less awkward. Something like: Selection Properties (Section 4.1.2) can only be specified as part of a Preconnection. Connection Properties (Section 4.1.2) may also be specified as part of a Preconnection, but may also be changed on the Connection. Together with Message Properties (Section 4.1.4), which can also be specified during data transfer to affect specific Messages, they are the three kinds of Transport Properties that an application can specify to configure the Transport System and express its requirements, prohibitions, and preferences.
I double-checked with the interface: there. transport properties are also an object that is passed to the preconnection and that can retrieved from a connection. Therefore, I made it a Connection Object and slightly rephrased the text. Does this work better?
This is very similar to where we started I think, so did not help much for me unfortunately. I still do not think it fits as a Connection Object on the same level as the rest. What did you think about my suggestion to introduce it in running text as part of the description of the Preconnection?
NAME I thought about your suggestion, but my problem with that is that Transport Properties are actually: An actual Object in the API Also used for introspecting and manipulating Connections Therefore, putting them into the Preconnection seems wrong to me.
In 4.1.1 Connection Objects we have Transport Properties as one of the bullets. But Transport Properties are not Connection Objects so this text does not really belong in this section. I suggest to move it to the next section on Pre-Esatblishment where we also describe Selection/Connection Properties or Change the name of Section 4.1.1.
Agreed, this rearrangement is not great, but I don't like any of the alternatives either.

potential connection.  It has state that describes parameters of a Connection that might exist in the future: the Local Endpoint from which that Connection will be established, the Remote Endpoint  <ins> (preestablishment) to which it will connect, and Transport Properties that influence the paths and protocols a Connection will use.  A Preconnection can be fully specified such that it represents a single possible Connection, or it can be partially specified such that it represents a family of possible Connections.  The Local Endpoint (preestablishment) MUST be specified if the Preconnection is used to Listen for incoming </ins> connections.  The Local Endpoint is OPTIONAL if it is used to Initiate connections.  The Remote Endpoint MUST be specified in the Preconnection that is used to Initiate connections.  The be specified if a peer-to-peer Rendezvous is to occur based on the Preconnection.  <ins> Transport Properties: Transport Properties allow the application to express their requirements, prohibitions, and preferences and configure the Transport System.  There are three kinds of Transport Properties: </ins>  <ins> Selection Properties (preestablishment) that can only be specified on a Preconnection. </ins>  <ins> Connection Properties (preestablishment) that may be changed on the Connection. </ins>  <ins> Message Properties (datatransfer) that can also be specified during data transfer to affect specific Messages. </ins> Connection: A Connection object represents one or more active transport protocol instances that can send and/or receive Messages


required to send and receive that data, and how the application is notified of the status of its data transfer. <del> Event Handling (events) defines the set of properties about which an application can receive notifications during the lifetime of transport objects.  Events MAY also provide opportunities for the </del>  application to interact with the underlying transport by querying state or updating maintenance options. that specific protocols encode and communicate to the Remote Endpoint.  Message Properties MAY be set on a Preconnection to define default properties for sending.  When receiving Messages, <del> Message Properties can contain per-protocol properties for properties that are sent between the endpoints. </del>  Send: The action to transmit a Message or partial Message over a Connection to the remote system.  The interface to Send MAY include Message Properties specific to how the Message content is <del> to be sent.  The status of the Send operation can be delivered </del>  back to the sending application in an event (events). Receive: An action that indicates that the application is ready to 4.1.5. <del> This section provides the top-level categories of events that can be delivered to an application.  This list is not exhaustive. </del>  Connection Ready: Signals to an application that a given Connection is ready to send and/or receive Messages.  If the heuristics of a Transport Services system. Protocol Selection: Protocol Selection represents the act of <del> choosing one or more sets of protocol options that are available to use based on the Transport Properties provided by the application, and the heuristics or policies within the Transport Services system. </del>  4.2.2. differ based on a selection from the available Paths.  Since different Paths will have distinct configurations for local addresses and DNS servers, attempts across different Paths will <del> perform separate DNS resolution stepss, which can lead to further </del>  racing of the resolved Remote Endpoints. Remote Endpoint Racing: Remote Endpoint Racing is the act of races between two different Protocol Stacks, both MUST use the same security protocols and options. <del> Clients need to ensure that security APIs are used appropriately.  In cases where clients use an interface to provide sensitive keying material, e.g., access to private keys or copies of pre-shared keys (PSKs), key use needs to be validated.  For example, clients ought not to use PSK material created for the Encapsulating Security Protocol (ESP, part of IPsec) RFC4303 with QUIC, and clients ought not to use private keys intended for server authentication as a keys for client authentication. </del>  Moreover, Transport Services systems MUST NOT automatically fall back from secure protocols to insecure protocols, or to weaker versions of <del> secure protocols.  For example, if a client requests TLS, but the desired version of TLS is not available, its connection will fail. Clients are thus responsible for implementing security protocol fallback or version fallback by creating multiple Transport Services Connections, if so desired. </del>

Having read -05, I have some more comments, mostly editorial. Opening an issue in case there's anything to discuss. Otherwise I might just do a PR against -arch if that's fine with the authors. In Section 4.1.1: "Event Handling (Section 4.1.5) defines the set of properties about which an application can receive notifications during the lifetime of transport objects." Set of properties? Section 4.1.5 do not refer to specific properties (as in: Transport Properties), but just lists what kinds of events exist. So I suggest changing text in Section 4.1.1 to say something like: "Event Handling (Section 4.1.5) defines categories of notifications which an application can receive during the lifetime of transport objects." In Section 4.1.4: "When receiving Messages, Message Properties can contain per-protocol properties for properties that are sent between the endpoints." Why is this constrained to properties that are sent between endpoints? Couldn't an implementation also set Message Properties that were not signaled? Also, what does "per-protocol" mean here? Also, too many "properties" in this sentence. I suggest changing this to something like: "When receiving Messages, Message Properties can contain information about the received message, such as signalled by the other endpoint." Still Section 4.1.4: "The status of the Send operation can be delivered back to the sending application in an event" Can be? I thought this always happens? The API draft in Section 7.3 says that for each Send(), the application gets exactly one event? So I think here this should be phrased as "is delivered" or even MUST. Section 4.1.5: "This section provides the top-level categories of events events that can be delivered to an application." Top-level categories? Are there more levels of categories? Maybe just say "categories"? Also, duplicate word: "events events". Section 4.2.1: "Protocol Selection: […] choosing one or more sets of protocol options" I don't think protocol options is the right word. Isn't this about racing protocol stacks? Below we use "protocol options" to mean something else, so here we should just say "choosing between multiple protocol stacks". "separate DNS resolution stepss" (typo) Section 6: "Clients need to ensure that security APIs are used appropriately." Who or what is a client? An application? Or the transport system itself? I think it's an application. "Clients" is not used elsewhere in the text. So this section should replace "clients" with "applications".
All suggestions here are good, please send a PR. I'd rephrase the following: "When receiving Messages, Message Properties can contain information about the received message, such as signalled by the other endpoint." to "When receiving Messages, Message Properties can contain information about the received message, such as metadata generated at the receiver and information signalled by the remote endpoint" ("such as" needs a noun, and I'd like to be more explicit here)

required to send and receive that data, and how the application is notified of the status of its data transfer.  <ins> Event Handling (events) defines categories of notifications which an application can receive during the lifetime of transport objects.  Events MAY also provide opportunities for the </ins> application to interact with the underlying transport by querying state or updating maintenance options. that specific protocols encode and communicate to the Remote Endpoint.  Message Properties MAY be set on a Preconnection to define default properties for sending.  When receiving Messages,  <ins> Message Properties can contain information about the received Message, such as metadata generated at the receiver and information signalled by the remote endpoint. </ins> Send: The action to transmit a Message or partial Message over a Connection to the remote system.  The interface to Send MAY include Message Properties specific to how the Message content is  <ins> to be sent.  The status of the Send operation MUST be delivered </ins> back to the sending application in an event (events). Receive: An action that indicates that the application is ready to 4.1.5.  <ins> This section provides the categories of events that can be delivered to an application.  This list is not exhaustive. </ins> Connection Ready: Signals to an application that a given Connection is ready to send and/or receive Messages.  If the heuristics of a Transport Services system. Protocol Selection: Protocol Selection represents the act of  <ins> choosing one or more sets of protocol stacks that are available to use based on the Transport Properties provided by the application, and the heuristics or policies within the Transport Services system. </ins> 4.2.2. differ based on a selection from the available Paths.  Since different Paths will have distinct configurations for local addresses and DNS servers, attempts across different Paths will  <ins> perform separate DNS resolution steps, which can lead to further </ins> racing of the resolved Remote Endpoints. Remote Endpoint Racing: Remote Endpoint Racing is the act of races between two different Protocol Stacks, both MUST use the same security protocols and options.  <ins> Applications need to ensure that they use security APIs appropriately.  In cases where applications use an interface to provide sensitive keying material, e.g., access to private keys or copies of pre-shared keys (PSKs), key use needs to be validated.  For example, applications ought not to use PSK material created for the Encapsulating Security Protocol (ESP, part of IPsec) RFC4303 with QUIC, and applications ought not to use private keys intended for server authentication as a keys for client authentication. </ins> Moreover, Transport Services systems MUST NOT automatically fall back from secure protocols to insecure protocols, or to weaker versions of  <ins> secure protocols.  For example, if an application requests TLS, but the desired version of TLS is not available, its connection will fail.  Applications are thus responsible for implementing security protocol fallback or version fallback by creating multiple Transport Services Connections, if so desired. </ins>


Abstract <del> This document provides an overview of the architecture of Transport Services, a model for exposing transport protocol features to applications for network communication.  In contrast to what is provided by most existing Application Programming Interfaces (APIs), Transport Services is based on an asynchronous, event-driven interaction pattern; it uses messages for representing data transfer to applications; and it assumes an implementation that can use multiple IP addresses, multiple protocols, and multiple paths, and provide multiple application streams.  This document further defines the common set of terminology and concepts to be used in definitions of Transport Services APIs and implementations. </del>  1. One of the key insights to come from identifying the minimal set of features provided by transport protocols I-D.ietf-taps-minset was that features either require application interaction and guidance <del> (referred to as Functional or Optimizing Features), or else can be handled automatically by a system implementing Transport Services (referred to as Automatable Features).  Among the Functional and Optimizing Features, some were common across all or nearly all transport protocols, while others could be seen as features that, if specified, would only be useful with a subset of protocols, but would not harm the functionality of other protocols.  For example, some protocols can deliver messages faster for applications that do not require messages to arrive in the order in which they were sent. However, this functionality needs to be explicitly allowed by the application, since reordering messages would be undesirable in many cases. </del>  1.2. It is important to note that neither the Transport Services API I- D.ietf-taps-interface nor the Implementation document I-D.ietf-taps- impl define new protocols or protocol capabilities that affect what <del> is communicated across the network.  The Transport Services system MUST be deployable on one side only.  A Transport Services system acting as a connection initiator can communicate with any existing system that implements the transport protocol(s) selected by the Transport Services system.  Similarly, a Transport Services system acting as a listener can receive connections for any protocol that is supported by the system, from existing initiators. </del>  4. Remote Endpoint: The Remote Endpoint represents the application's identifier for a peer that can participate in a transport <del> connection.  For example, the combination of a DNS name for the </del>  peer and a service name/port. Local Endpoint: The Local Endpoint represents the application's <del> identifier for itself that it uses for transport connections.  For </del>  example, a local IP address and port. Selection Properties: The Selection Properties consist of the Connection Properties: The Connection Properties are used to configure protocol-specific options and control per-connection <del> behavior of the Transport System.  For example, a protocol- specific Connection Property can express that if UDP is used, the </del>  implementation ought to use checksums.  Note that the presence of such a property does not require that a specific protocol will be used.  In general, these properties do not explicitly determine spans of bytes, those spans of bytes are considered independent Messages.  Boundaries of a Message might or might not be understood or transmitted by transport protocols.  Specifically, <del> what one application considers to be two Messages sent on a </del>  stream-based transport can be treated as a single Message by the <del> application on the other side. </del>  Message Properties: Message Properties can be used to annotate specific Messages.  These properties might only apply to how

Note that Security Considerations and Acknowledgments changes are newline-rewrap only.

Abstract  <ins> This document proposal an architecture for exposing transport protocol features to applications for network communication, the Transport Services architecture.  In contrast to what is provided by most existing Application Programming Interfaces (APIs), Transport Services is based on an asynchronous, event-driven interaction pattern; it uses messages for representing data transfer to applications; and it assumes an implementation that can use multiple IP addresses, multiple protocols, and multiple paths, and provide multiple application streams.  This document further defines common terminology and concepts to be used in definitions of Transport Services APIs and implementations. </ins> 1. One of the key insights to come from identifying the minimal set of features provided by transport protocols I-D.ietf-taps-minset was that features either require application interaction and guidance  <ins> (referred to in that document as Functional or Optimizing Features), or else can be handled automatically by a system implementing Transport Services (referred to as Automatable Features).  Among the Functional and Optimizing Features, some were common across all or nearly all transport protocols, while others could be seen as features that, if specified, would only be useful with a subset of protocols, but would not harm the functionality of other protocols. For example, some protocols can deliver messages faster for applications that do not require messages to arrive in the order in which they were sent.  However, this functionality needs to be explicitly allowed by the application, since reordering messages would be undesirable in many cases. </ins> 1.2. It is important to note that neither the Transport Services API I- D.ietf-taps-interface nor the Implementation document I-D.ietf-taps- impl define new protocols or protocol capabilities that affect what  <ins> is communicated across the network: this implies that a Transport Services system MUST be deployable on only one side of a connection. A Transport Services system acting as a connection initiator can communicate with any existing system that implements the transport protocol(s) selected by the Transport Services system.  Similarly, a Transport Services system acting as a listener can receive connections for any protocol that is supported by the system, from existing initiators. </ins> 4. Remote Endpoint: The Remote Endpoint represents the application's identifier for a peer that can participate in a transport  <ins> connection; for example, the combination of a DNS name for the </ins> peer and a service name/port. Local Endpoint: The Local Endpoint represents the application's  <ins> identifier for itself that it uses for transport connections; for </ins> example, a local IP address and port. Selection Properties: The Selection Properties consist of the Connection Properties: The Connection Properties are used to configure protocol-specific options and control per-connection  <ins> behavior of the Transport System; for example, a protocol-specific Connection Property can express that if UDP is used, the </ins> implementation ought to use checksums.  Note that the presence of such a property does not require that a specific protocol will be used.  In general, these properties do not explicitly determine spans of bytes, those spans of bytes are considered independent Messages.  Boundaries of a Message might or might not be understood or transmitted by transport protocols.  Specifically,  <ins> what one application considers to be multiple Messages sent on a </ins> stream-based transport can be treated as a single Message by the  <ins> application on the other side, and vice versa. </ins> Message Properties: Message Properties can be used to annotate specific Messages.  These properties might only apply to how


TCP and UDP in the kernel send and receive data over the available network layer interfaces. <del> The Transport Services architecture maintains this general model of interaction, but aims to both modernize the API surface exposed for transport protocols and enrich the capabilities of the transport system implementation. </del>  The Transport Services API I-D.ietf-taps-interface defines the mechanism for an application to create network connections and

This is a lightweight proposal to address .
Especially in section 2, we should make it explicit that resolution is blended with connection establishment in a way that it is not in traditional sockets.
Yip - I like

TCP and UDP in the kernel send and receive data over the available network layer interfaces.  <ins> Sockets are bound directly to transport-layer and network-layer addresses, obtained via a separate resolution step, usually performed by a system-provided stub resolver. The Transport Services architecture evolves this general model of interaction, aiming to both modernize the API surface presented to applications by the transport layer and enrich the capabilities of the transport system implementation.  It combines interfaces for multiple interaction patterns into a unified whole.  By combining name resolution with connection establishment and data transfer in a single API, it allows for more flexible implementations to provide path and transport protocol agility on the application's behalf. </ins> The Transport Services API I-D.ietf-taps-interface defines the mechanism for an application to create network connections and


Other specialized features, however, could be strictly required by an application and thus constrain the set of protocols that can be used. <del> For example, if an application requires encryption of its transport data, only protocol stacks that include a transport security function are eligible to be used.  A Transport Services API MUST allow </del>  applications to define such requirements and constrain the system's options.  Since such options are not part of the core/common features, it will generally be simple for an application to modify

Changed example of a Specialized Feature (non-minset) from "encryption" to "automatic handover or failover", as suggested by Anna in . If anyone has an alternative suggestion how to word this, I'm open. Ideas for alternative solutions include: Go back to the "encryption" example, but do not make "encryption" sound like a generic feature but rather talk about specific security protocols, e.g.: "For example, if an application requires encryption of its transport data, it could select a specific security protocol. In this case, only protocol stacks that include this security protocol are eligible to be used." Find a different example Give up and throw out the example entirely, maybe even changing what a "specialized feature" is Looking for guidance from the authors here :)
The architecture draft has a few parts where it needs to be aligned with how we handle security protocols now. One such part is Section 3.2, "Access to Specialized Features". Right now it says: "Other specialized features, however, could be strictly required by an application and thus constrain the set of protocols that can be used. For example, if an application requires encryption of its transport data, only protocol stacks that include a transport security function are eligible to be used." To me, this sounds like an application could just request "Encryption: Require" and then any security protocol that provides this function could be used. That's not how we think about security protocols anymore. So we need to change that example. I haven't really found another example for a "specialized feature" that might be required - "specialized feature" apparently means "feature not in minset" - so I suggest we stick with the security example, but change the wording. For example, we could just say, "For example, if an application requires encryption of its transport data, it could select a specific security protocol. In this case, only protocol stacks that include this security protocol are eligible to be used." However, then it's not strictly a feature anymore... right? What do the authors think?
It sounds like a new example, unrelated to security, should be chosen for the text.
Yes, I think we need a new example. Could a multuipath example do, requiring handover/failover support (or some suitable option available after resolving that issue).
I fear changing the example will not solve the overall problem. We really need to make a decision how we go ahead with the non-goal statement from the security draft. Ways forward: Automagic security is a non-goal for the security draft, but goal for the triplet (no text changes, but will hunt us on the next review) Work around this limitation by adding profiles for tls/quic-v1 equivalent transports (must be profiles, as we decided explicit protocol selection is not part of the portable API) Get rid of examples from the main text at all and move them to the Appendix as we can not provide relevant examples without using non-portable APIs

Other specialized features, however, could be strictly required by an application and thus constrain the set of protocols that can be used.  <ins> For example, if an application requires support for automatic handover or failover for a Connection, only protocol stacks that provide this feature are eligible to be used, e.g., protocol stacks that include a multipath protocol or a protocol that supports connection migration.  A Transport Services API MUST allow </ins> applications to define such requirements and constrain the system's options.  Since such options are not part of the core/common features, it will generally be simple for an application to modify


parallel (see racing), then they are considered to be "equivalent". Equivalent Protocol Stacks need to meet the following criteria: <del> Both stacks MUST offer the same interface to the application for connection establishment and data transmission.  For example, if one Protocol Stack has UDP as the top-level interface to the application, then it is not equivalent to a Protocol Stack that runs TCP as the top-level interface.  Among other differences, the UDP stack would allow an application to read out message boundaries based on datagrams sent from the remote system, whereas TCP does not preserve message boundaries on its own. </del>  Both stacks MUST offer the transport services that are required by the application.  For example, if an application specifies that it Stack as long as providing this would not conflict with any other application-requested properties. <del> Both stacks MUST offer the same security properties.  The inclusion of transport security protocols I-D.ietf-taps-transport- security in a Protocol Stack adds additional restrictions to Protocol Stack equivalence.  Security features and properties, such as cryptographic algorithms, peer authentication, and identity privacy vary across security protocols, and across versions of security protocols.  Protocol equivalence ought not to be assumed for different protocols or protocol versions, even if they offer similar application configuration options.  To ensure that security protocols are not incorrectly swapped, Transport Services systems SHOULD only automatically generate equivalent Protocol Stacks when the transport security protocols within the stacks are identical.  Specifically, a transport system would consider protocols identical only if they are of the same type and version.  For example, the same version of TLS running over two different transport protocol stacks are considered equivalent, whereas TLS 1.2 and TLS 1.3 RFC8446 are not considered equivalent. </del>  4.2.4.

This addresses two issues related to protocol stack equivalence: TCP and UDP can now be equivalent if the application does not care about message boundaries (see mailing list discussion in July 2019) Security protocol and parameters need to be equivalent, not "features" which implied abstract security features. Basically, equivalent stacks are all stacks that satisfy whatever the application requested. If you want to race different security protocols (like TLS 1.2 and 1.3), your application has to specify that it considers these protocol equivalent. Question to authors: Should the SHOULD in 3. become a MUST?
Regarding the SHOULD, I'd rather leave it as a SHOULD for now, to give some wiggle room to implementations.
Under "Protocol Stack Equivalence", for example, text like needs to change to conform to the rework of the security document. This is related to .
Yes, I think this is part of the "protocol stack equivalence" issue . As is assigned to me, I'll just self-assign this one and close both once this is done.
Fixed by
Per the architecture draft, only protocol stacks that are equivalent can be safely raced. What is the expected behavior if selection properties are set in such a way that the resulting candidate set includes protocol stacks that are not equivalent? Would the selection properties simply be treated as invalid?
To me "equivalent" relates to either candidate would provide the set of functions needed. At the risk I don't answer your question: My take is that one can always define policy and API properties that produce a useless outcome. It's not the job of a TAPS system to validate these (although someone may like to try that as a separate sanity checking tool); in just the same way that someone can write code that doesn't implement an algorithm. The goal is rather that if this specifies "sensible" properties and policy you get the required outcome. You may get no connection or something unexpected if the request is not well-founded.
Right, so if an application chooses to provide properties that allow both TCP and UDP the implementation would race those two which would result in a default win for UDP, is that correct?
I agree, and I'd say the answer to your question is yes. Of course, later you may find that UDP doesn't really work on the path for the given port, and then it would be great to have an open TCP connection available to fall back to.
I guess we should define "equivalent protocol stacks" a little less rigorous in the architecture document. For an application that does not care about message boundaries, and reliable transport and has its own congestion control, protocol stacks with TCP and UDP may indeed be equivalent with respect to the application's requirements. This would require to rewrite 1. of the enumeration in Section 4.2.3 which could use a second look anyway, because it mixes up application requirements in sense of interface behaviour and application protocols that directly depend on specific transport protocols beneath, which is what PR is all about.
See also mailing list discussion in July 2019.
We also need to say here what "equivalence" means for security. Right now, Security Considerations says "As described above in Section 4.2.3, if a Transport Services system races between two different Protocol Stacks, both MUST use the same security protocols and options." I think if we consider equivalence as "you can use whatever stack that satisfies the things that the application requested", this should also apply to security. Now that the application has to explicitly select a security protocol, I think it should also be allowed for the application to say that multiple security protocols are fine. Like, allow applications to say "Use TLS 1.3 if available, but if not, TLS 1.2 is also fine" (instead of failing).
Fixed by
Nice!

parallel (see racing), then they are considered to be "equivalent". Equivalent Protocol Stacks need to meet the following criteria:  <ins> Both stacks MUST offer the interface requested by the application for connection establishment and data transmission.  For example, if an application requires preservation of message boundaries, a Protocol Stack that runs UDP as the top-level interface to the application is not equivalent to a Protocol Stack that runs TCP as the top-level interface.  A UDP stack would allow an application to read out message boundaries based on datagrams sent from the remote system, whereas TCP does not preserve message boundaries on its own, but needs a framing protocol on top to determine message boundaries. </ins> Both stacks MUST offer the transport services that are required by the application.  For example, if an application specifies that it Stack as long as providing this would not conflict with any other application-requested properties.  <ins> Both stacks MUST offer security protocols and parameters as requested by the application I-D.ietf-taps-transport-security. Security features and properties, such as cryptographic algorithms, peer authentication, and identity privacy vary across security protocols, and across versions of security protocols. Protocol equivalence ought not to be assumed for different protocols or protocol versions, even if they offer similar application configuration options.  To ensure that security protocols are not incorrectly swapped, Transport Services systems SHOULD only automatically generate equivalent Protocol Stacks when the transport security protocols within the stacks are identical. Specifically, a transport system would consider protocols identical only if they are of the same type and version.  For example, the same version of TLS running over two different transport protocol stacks are considered equivalent, whereas TLS 1.2 and TLS 1.3 RFC8446 are not considered equivalent.  However, Transport Services systems MAY allow applications to indicate that they consider two different transport protocols equivalent, e.g., to allow fallback to TLS 1.2 if TLS 1.3 is not available. </ins> 4.2.4.


containing these properties can be passed to the Send Action.  For other uses of the message context, see msg-ctx. <del> Note that message properties are per-Message, not per-Send if partial </del>  Messages are sent (send-partial).  All data blocks associated with a single Message share properties specified in the Message Contexts. For example, it would not make sense to have the beginning of a This enumerated property specifies the application's preferred tradeoffs for sending this Message; it is a per-Message override of <del> the Capacity Profile protocol and path selection property (see prop- cap-profile). The following values are valid for Transmission Profile: No special optimizations of the tradeoff between delay, delay variation, and bandwidth efficiency should be made when sending this message. Response time (latency) should be optimized at the expense of efficiently using the available capacity 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 prefer immediate acknowledgment from the peer endpoint when supported by the underlying transport; to signal a preference for lower-latency, higher-loss treatment; and so on. [TODO: This is inconsistent with {prop-cap-profile}} - needs to be fixed] </del>  7.4.9. MessageContext object can be passed to the Send action and is retuned by each Send and Receive related events. <del> Message properties can be set and queried using the Message Context: </del>  To get or set Message Properties, the optional scope parameter is left empty, for framing meta-data, the framer is passed. all Connections are defined in the subsections below. Note that many protocol properties have a corresponding selection <del> property, which prefers protocols providing a specific transport feature that controlled by that protocol property.  [EDITOR'S NOTE: todo: add these cross-references up to selection-props] </del>  11.1.1.

This also addresses two inline [EDITOR's NOTE] items. One was about the per-message override capacity profile being inconsistent with the other one; this was solved by removing details, such that the other one defines the possible choices. Another was about selection vs. connection properties, with broken text. There was no need to add the references as the editor's note says, I thought.
this LGTM, thanks!

containing these properties can be passed to the Send Action.  For other uses of the message context, see msg-ctx.  <ins> Note that Message Properties are per-Message, not per-Send if partial </ins> Messages are sent (send-partial).  All data blocks associated with a single Message share properties specified in the Message Contexts. For example, it would not make sense to have the beginning of a This enumerated property specifies the application's preferred tradeoffs for sending this Message; it is a per-Message override of  <ins> the Capacity Profile connection property (see prop-cap-profile). </ins> 7.4.9. MessageContext object can be passed to the Send action and is retuned by each Send and Receive related events.  <ins> Message Properties can be set and queried using the Message Context: </ins> To get or set Message Properties, the optional scope parameter is left empty, for framing meta-data, the framer is passed. all Connections are defined in the subsections below. Note that many protocol properties have a corresponding selection  <ins> property, which prefers protocols providing a supporting transport feature. </ins> 11.1.1.


Close: The action an application takes on a Connection to indicate that it no longer intends to send data, is no longer willing to receive data, and that the protocol SHOULD signal this state to <del> the remote system if the transport protocol allows this. </del>  Abort: The action the application takes on a Connection to indicate a Close and also indicate that the transport system

Completes
Close: The way this is written suggests that the API doesn't support half closed connections. That may be reasonable, but it's a limitation. If intended, can it be made explicit.
This is perfect IMO!lgtm, thanks!

Close: The action an application takes on a Connection to indicate that it no longer intends to send data, is no longer willing to receive data, and that the protocol SHOULD signal this state to  <ins> the remote system if the transport protocol allows this.  (Note that this is distinct from the concept of "half-closing" a bidirectional connection, such as when a FIN is sent in one direction of a TCP connection.  Indicating the end of a stream in the Transport Services architecture is possible using Message Properties when sending.) </ins> Abort: The action the application takes on a Connection to indicate a Close and also indicate that the transport system


Rendezvous: The action of establishing a peer-to-peer connection with a Remote Endpoint.  It simultaneously attempts to initiate a <del> connection to a Remote Endpoint whilst listening for an incoming connection from that endpoint.  This corresponds, for example, to a TCP simultaneous open RFC0793.  The process of identifying options for the connection, such as resolution of the Remote Endpoint, occurs during the Rendezvous call.  As with Listeners, the set of local paths and endpoints is contrained by Selection Properties.  If successful, the Rendezvous call returns a Connection object to represent the established peer-to-peer connection. </del>  4.1.4.

Generalise the discussion of Rendezvous in arch.
Rendezvous: TCP simultaneous open is one type of rendezvous, but only giving this as an example makes it seems more narrowly scoped that I envisaged. For example, I'd expect Rendezvous could perform an ICE exchange it STUN candidates were passed as Remote Endpoints. Should this description be generalised?

Rendezvous: The action of establishing a peer-to-peer connection with a Remote Endpoint.  It simultaneously attempts to initiate a  <ins> connection to a Remote Endpoint while listening for an incoming connection from that endpoint.  The process of identifying options for the connection, such as resolution of the Remote Endpoint, occurs during the Rendezvous call.  As with Listeners, the set of local paths and endpoints is constrained by Selection Properties. If successful, the Rendezvous call returns a Connection object to represent the established peer-to-peer connection.  The processes by which connections are initiated during a Rendezvous action will depend on the set of Local and Remote Endpoints configured on the Preconnection.  For example, if the Local and Remote Endpoints are TCP host candidates, then a TCP simultaneous open RFC0793 will be performed.  However, if the set of Local Endpoints includes server reflexive candidates, such as those provided by STUN, a Rendezvous action will race candidates in the style of the ICE algorithm RFC8445 to perform NAT binding discovery and initiate a peer-to- peer connection. </ins> 4.1.4.


msg-lifetime <del> Integer </del>  infinite

Example code updates: this is to try to avoid people stumbling over, e.g., "send" being part of the "main code". I believe it's a little cleaner with these added comments.Lifetime Message property: mentioned -1 as a special value for infinite, else it's a bit odd to only use "infinite" for an integervery minor text fix about corruption protection length Message property
Okay, so I think I addressed NAME comments here, and agreed with NAME that we could adjust things further later on if needed - so now I'll just merge this one, seems safe to do to me.
These two message properties are interconnected and therefore have a dependency. I would rather prefer to only have one property. Lifetime already has one "special" value (infinity) to indicate reliable transmission. We could also declare 0 as special to indicate unreliable transmission (only transmit once and never retransmit). Also should we rather use -1 for reliable? And also do this for other properties that currently have meaning for infinite? Or would it be more correct to say max instead of infinite? And more more question on lifetime: Do we need an event that indicates to the application that transmission was aborted due to lifetime expiry?
No. Here's a quote from the description of lifetime: " Setting a Message's Lifetime to infinite indicates that the application does not wish to apply a time constraint on the transmission of the Message, but it does not express a need for reliable delivery; reliability is adjustable per Message via the "Reliable Data Transfer (Message)" property (see Section 7.4.7). " Consider an unreliable, congestion controlled transport (e.g. QUIC with datagrams). Specifying a "lifetime" means that, once the lifetime has expired, the Message can be deleted from the send buffer. Setting "lifetime" to infinite means that the Message will never just be deleted from the send buffer. This does not at all guarantee that the Message will be retransmitted in case it was lost. The mistake is the mix of "integer" and "infinite". The latter is okay for type "numeric". I have already fixed this in PR (which is still open). That's the Expired Event, see section 7.3.2.
Can we close this issue?
Interim: Agreed with NAME closing.

msg-lifetime  <ins> Numeric </ins> infinite


This property, if applicable, represents the maximum Message size that can be sent without incurring network-layer fragmentation or <del> transport layer segmentation at the sender. </del>  11.1.8.

Add a reference to MPS in DPLPMTUD for the Message Size Before Fragmentation property.
LGMT, just replace "models" with something more suitable.

This property, if applicable, represents the maximum Message size that can be sent without incurring network-layer fragmentation or  <ins> transport layer segmentation at the sender.  This property exposes the Maximum Packet Size (MPS) as described in Datagram PLPMTUD I- D.ietf-tsvwg-datagram-plpmtud. </ins> 11.1.8.


Connection.  These connections are "entangled" with each other, and become part of a Connection Group.  Calling Clone on any of these two Connections adds a third Connection to the Connection Group, and so <del> on.  Connections in a Connection Group share all Protocol Properties that are not applicable to a Message. </del>  In addition, incoming entangled Connections can be received by creating a Listener on an existing connection: <del> Changing one of these Protocol Properties on one Connection in the group changes it for all others.  Per-Message Protocol Properties, however, are not entangled.  For example, changing "Timeout for aborting Connection" (see conn-timeout) on one Connection in a group will automatically change this Protocol Property for all Connections in the group in the same way.  However, changing "Lifetime" (see msg- </del>  lifetime) of a Message will only affect a single Message on a single Connection, entangled or not. create a new stream on the given Connection, then attempts to clone a Connection will result in a CloneError: <del> The Protocol Property "Priority" operates on entangled Connections as in msg-priority: when allocating available network capacity among </del>  Connections in a Connection Group, sends on Connections with higher Priority values will be prioritized over sends on Connections with lower Priority values.  An ideal transport system implementation 11.1. <del> The Connection Properties defined as independent, and available on all Connections are defined in the subsections below. </del>  <del> Note that many protocol properties have a corresponding selection property, which prefers protocols providing a supporting transport feature. </del>  11.1.1.

When reading the API draft, I noticed that in some places it was still using the outdated term "Protocol Properties" where it actually means Connection Properties or Message Properties. I replaced the terms in this PR. We do still define "Specific Protocol Properties", so I kept these.

Connection.  These connections are "entangled" with each other, and become part of a Connection Group.  Calling Clone on any of these two Connections adds a third Connection to the Connection Group, and so  <ins> on.  Connections in a Connection Group generally share Connection Properties.  However, there may be exceptions, such as "Priority (Connection)", see conn-priority. </ins> In addition, incoming entangled Connections can be received by creating a Listener on an existing connection:  <ins> Changing one of the Connection Properties on one Connection in the group changes it for all others.  Message Properties, however, are not entangled.  For example, changing "Timeout for aborting Connection" (see conn-timeout) on one Connection in a group will automatically change this Connection Property for all Connections in the group in the same way.  However, changing "Lifetime" (see msg- </ins> lifetime) of a Message will only affect a single Message on a single Connection, entangled or not. create a new stream on the given Connection, then attempts to clone a Connection will result in a CloneError:  <ins> The Connection Property "Priority" operates on entangled Connections as in msg-priority: when allocating available network capacity among </ins> Connections in a Connection Group, sends on Connections with higher Priority values will be prioritized over sends on Connections with lower Priority values.  An ideal transport system implementation 11.1.  <ins> The Connection Properties defined as independent of the chosen protocol stack, and available on all Connections are defined in the subsections below. </ins>  <ins> Note that many Connection Properties have a corresponding Selection Property, which enables applications to express their preference for protocols providing a supporting transport feature. </ins> 11.1.1.


1. <del> The BSD Unix Sockets API's SOCK_STREAM abstraction, by bringing network sockets into the UNIX programming model, allowing anyone who knew how to write programs that dealt with sequential-access files to also write network applications, was a revolution in simplicity.  The simplicity of this API is a key reason the Internet won the protocol wars PROTOCOL-WARS of the 1980s.  SOCK_STREAM is tied to the Transmission Control Protocol (TCP), specified in 1981 RFC0793.  TCP has scaled remarkably well over the past three and a half decades, but its total ubiquity has hidden an uncomfortable fact: the network is not really a file, and stream abstractions are too simplistic for many modern application programming models. In the meantime, the nature of Internet access, and the variety of Internet transport protocols, is evolving.  The challenges that new protocols and access paradigms present to the sockets API and to programming models based on them inspire the design principles of a new approach, which we outline in principles. This document builds a modern abstract programming interface atop the high-level architecture for transport services defined in I-D.ietf- taps-arch.  It derives specific path and protocol selection properties and supported transport features from the analysis provided in RFC8095, I-D.ietf-taps-minset, and I-D.ietf-taps- transport-security.  The design encourages implementations underneath the interface to dynamically choose a transport protocol depending on an application's choices rather than statically binding applications to a protocol at compile time.  We note that transport system implementations SHOULD provide applications a way to override transport selection and instantiate a specific stack, e.g. to support servers wanting to listen to a specific protocol.  This specific transport stack choice is discouraged for general use, as it comes at the cost of reduced portability. </del>  2.

I think the intro currently doesn't fit well the content of the document as any motivation for this work should be in the Arch doc. If we want to retain the text that I deleted we can maybe add it to the Intro or background section in the Arch doc...? Note that the second paragraph I've added is stolen from the intro of the Arch doc.
NAME I can't see how the existing text that NAME proposed to delete could reasonably be merged with the intro text of the architecture doc? and the text that's there now motivates TAPS just as nicely, IMO. I would be inclined to just delete the text and do the update exactly as NAME proposes here.
I agree with NAME , I like the new text much better and I do not think we should add the removed text to arch.
I think the text did its duty and it's time to let go...
I don't have a strong opinion on this, for me it's fine to have some motivation in this document as well. However, if we delete the motivation from this document, let's put it in the -architecture, please - I would really like us to keep this text URL so dies the last text from the original post sockets paper ;( lgtm :)I like this; I think it improves the flow of the text, and I agree that the prior text is too motivational in style for this document. Even stealing a paragraph from the arch draft won't matter, I think.I really like this new intro and would like to have it irrespectively of moving the text as proposed in

1.  <ins> This document specifies a modern abstract programming interface atop the high-level architecture for transport services defined in I- D.ietf-taps-arch.  It supports the asynchronous, atomic transmission of messages over transport protocols and network paths dynamically selected at runtime.  It is intended to replace the traditional BSD sockets API as the lowest common denominator interface to the transport layer, in an environment where endpoints have multiple interfaces and potential transport protocols to select from. As applications adopt this interface, they will benefit from a wide set of transport features that can evolve over time, and ensure that the system providing the interface can optimize its behavior based on the application requirements and network conditions, without requiring changes to the applications.  This flexibility enables faster deployment of new features and protocols.  It can also support applications by offering racing and fallback mechanisms, which otherwise need to be implemented in each application separately. It derives specific path and protocol selection properties and supported transport features from the analysis provided in RFC8095, I-D.ietf-taps-minset, and I-D.ietf-taps-transport-security.  The design encourages implementations underneath the interface to dynamically choose a transport protocol depending on an application's choices rather than statically binding applications to a protocol at compile time.  We note that transport system implementations SHOULD provide applications a way to override transport selection and instantiate a specific stack, e.g. to support servers wanting to listen to a specific protocol.  This specific transport stack choice is discouraged for general use, as it comes at the cost of reduced portability. </ins> 2.


The effect of Selection Properties can be queried on Connections and Messages <del> Note that Configuring Connection Properties and Message Properties on </del>  Preconnections is preferred over setting them later.  Early specification of Connection Properties allows their use as additional <del> input to the selection process.  Protocol Specific Properties, see property-names, should not be used as an input to the selection process. </del>  4.2.1.

The term Protocol Specific Properties is not well introduced. In the Arch doc we have a section about "Specialized Features" and I not added a reference and rephrased the sentence respectively. Do we need to say more than that?
LGTM modulo two nitsLooks good to me, except one nit.

The effect of Selection Properties can be queried on Connections and Messages  <ins> Note that configuring Connection Properties and Message Properties on </ins> Preconnections is preferred over setting them later.  Early specification of Connection Properties allows their use as additional  <ins> input to the selection process.  Protocol Specific Properties, which enable configuration of specialized features of a specific protocol, see Section 3.2 of I-D.ietf-taps-arch, are not used as an input to the selection process but only support configuration if the respective prototocol has been selected. </ins> 4.2.1.


Transport Property Names are hierarchically organized in the form [<Namespace>.]<PropertyName>. <del> The Namespace part is empty for well known, generic properties, i.e., for properties that are not specific to a protocol and are defined in an RFC. </del>  <del> Protocol Specific Properties must use the protocol acronym as </del>  Namespace, e.g., "tcp" for TCP specific Transport Properties.  For <del> IETF protocols, property names under these namespaces should be </del>  defined in an RFC. <del> Vendor or implementation specific properties must use a string </del>  identifying the vendor or implementation as Namespace.  4.2.2. Transport Properties can have one of a set of data types:

It looks like we should use normative language here. We could also use the keywords of the IANA protocol number registry to indicate reserved namespaces for IETF protocols (that can not be used in the vendor or implementation specific namespaces anyway). See URL
Like this?
This is great, thanks!

Transport Property Names are hierarchically organized in the form [<Namespace>.]<PropertyName>.  <ins> The Namespace part MUST be empty for well-known, generic properties, i.e., for properties that are not specific to a protocol and are defined in an RFC. </ins>  <ins> Protocol Specific Properties MUST use the protocol acronym as </ins> Namespace, e.g., "tcp" for TCP specific Transport Properties.  For  <ins> IETF protocols, property names under these namespaces SHOULD be </ins> defined in an RFC.  <ins> Vendor or implementation specific properties MUST use a string </ins> identifying the vendor or implementation as Namespace. <ins> Namespaces for the keywords provided in the IANA protocol numbers registry (see https://www.iana.org/assignments/protocol-numbers/ protocol-numbers.xhtml) are reserved for Protocol Specific Properties and MUST not be used for vendor or implementation specific properties. </ins> 4.2.2. Transport Properties can have one of a set of data types:


5.1. The transport services API uses the Local Endpoint and Remote <del> 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. </del>  Specify a Remote Endpoint using a hostname and service name:

Agree, they're definitely objects. While an implementation might choose to implement different types of endpoint identifiers as subtypes of such objects, we don't want to be that specific here.LGTM

5.1. The transport services API uses the Local Endpoint and Remote  <ins> Endpoint Objects to refer to the endpoints of a transport connection. Actions on these Objects can be used to represent various different types of endpoint identifiers, such as IP addresses, DNS names, and interface names, as well as port numbers and service names. </ins> Specify a Remote Endpoint using a hostname and service name:


path, the transport system will try the path first, ignoring the preference. <del> Selection, and Connection Properties, as well as defaults for Message </del>  Properties, can be added to a Preconnection to configure the <del> selection process, and to further configure the eventually selected </del>  protocol stack(s).  They are collected into a TransportProperties object to be passed into a Preconnection object:

I guess we could actually remove all commas in this sentence but previously there were definitely too many...

path, the transport system will try the path first, ignoring the preference.  <ins> Selection and Connection Properties, as well as defaults for Message </ins> Properties, can be added to a Preconnection to configure the  <ins> selection process and to further configure the eventually selected </ins> protocol stack(s).  They are collected into a TransportProperties object to be passed into a Preconnection object:


other properties. An implementation of this interface must provide sensible defaults <del> for 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. </del>  5.2.1.

I was about to change this must to MUST, however, MUST and "sensible" doesn't work well together, so I proposed this recommendation instead.
I wrote SHOULD because the next sentence explain when you can use other default values, so it seem to me that only SHOULD makes sense. There is a MUST later saying that some default MUST be used.
Ah, ok!
I also like this and agree with the SHOULD. The MUST in the example that follows look odd to me though. I think that should be a MAY (or possibly a SHOULD).
The point about the MUST is that "default values MUST lead to a possible/implemented protocol". Maybe there is a better way to phrase that?
Btw. similar as in Arch I think we have to spread a couple more MUSTs, SHOULDs, and MAYs over the whole doc...
Not convinced that "default values MUST lead to an implemented protocol" is a MUST. If the TAPS default values do not lead to an implemented protocol (i.e. TCP or a protocol with similar functionality is not implemented), maybe you want applications that assume those values to get an error rather than transparently ending up with UDP? Maybe you know that your applications are aware and then you should be allowed to change them, but maybe you want to make sure that applications are aware that they get an unrelaible service and not a reliable service and then you should be allowed to keep the TAPS default values and generate an error.
I agree with NAME but I think this means we need more text explaining this. Any proposals?
Shouldn't this be: MUST provide some default that chooses an implemented protocol SHOULD use the ones we specify here The suggestion is to invert the sentences to clarify.
Or, we say that you can use the TCP defaults and raise an error if TCP isn't implemented.
I think it should be allowed to use the TAPS defaults and raise an error if no protocol that implements the TAPS defaults is available. In case the implementation prefers to do so. But I agree with Aaron that it is a corener case and in that sense perhaps not terribly important what we pick.
After thinking about this a bit more, I think that it is a must requirement that any chosen set of default values MUST NOT lead to an error, because what's otherwise the point about having default values....? However, I think we should add some big warning text that if other defaults are used that most be communicated to the users of this API others they might be really surprised...
I think this has moved in a curious direction. My thoughts are still that this has been edited in the wrong direction. I quite like the SHOULD. Whilst the language is fine, I really do not agree at all with the direction of the "the implementation MUST specify default Protocol Selection Properties that represents a configuration that can be implemented over the preferred protocol, such as UDP." This is not the way I saw TAPS - I expected the exact opposite outcome, i.e.: "the users of such an implementation MUST explicitly specify Properties that result in theimplemented over the preferred protocol, such as UDP."
NAME I lost a bit track here and your proposed text in the last comment doesn't parse fully. Can you make a concrete proposal what to change?
Sure, but this is different to your proposal, it is not clarifying your text: An implementation of this interface must provide sensible defaults for Selection Properties. The default values represent a configuration that can be implemented over TCP. If TCP is not supported by an implementation then an application using the default set of Properties might not succeed. For example, the application might need to be designed to also support a connectionless mode, and explicitly specify a different set of Protocol Selection Properties that result in a usable protocol.
Ready to merge
I approved this too early: I agree with NAME about the change to the second sentence.I agree with this. Previously we had some discussion on whether to make the defaults normative, see IETF 105 notes under "Parameters & Defaults" URL I don't really see a clear consensus in these notes, but I think your suggestion seems reasonable - different defaults for different platforms are possible, but then they have to be stated clearly.

other properties. An implementation of this interface must provide sensible defaults  <ins> for Selection Properties.  The recommended default values for each property below represent a configuration that can be implemented over TCP.  If these default values are used and TCP is not supported by a Transport Services implementation, then an application using the default set of Properties might not succeed in establishing a connection.  Using the same default values for independent Transport Services implementations can be beneficical when application are ported between different implementations, even if this default could lead to a connection failure, as, for example, an application needs to be explicitly designed to support a connectionless mode.  In this case the application can regonize the failure and explicitly specify a different set of Protocol Selection Properties that result in a usable protocol.  If default values other than those recommended below are used, it is recommended to clearly document the differences. </ins> 5.2.1.


may be delivered to the receiving application out of order.  This property is used for protocols that support preservation of data ordering, see prop-ordering, but allow out-of-order delivery for <del> certain messages. </del>  7.4.4.

Just a proposal...
Well, you could do it with streams in SCTP as well so as an example it seems approriate. And good with an example I think.
Yes, we do have actually these kind of examples in many cases in the doc and I just thought when reading one could help here as well.
I don't understand why one would need streams for this in SCTP, but it doesn't matter. As I said I have no strong opinion, I'm fine with adding this example (and I just fixed the nit).
NAME you do not need to, as there are multiple ways to do it in SCTP, but you could.

may be delivered to the receiving application out of order.  This property is used for protocols that support preservation of data ordering, see prop-ordering, but allow out-of-order delivery for  <ins> certain messages, e.g., by multiplexing independent messages onto different streams. </ins> 7.4.4.


10.1. <del> The Connection Properties defined as independent of the chosen protocol stack, and available on all Connections are defined in the subsections below. </del>  Note that many Connection Properties have a corresponding Selection <del> Property, which enables applications to express their preference for </del>  protocols providing a supporting transport feature. 10.1.1.

Comma in the first section was wrong but better to rephrase anyway...
nit

10.1.  <ins> Generic Connection Properties are defined independent of the chosen protocol stack and therefore available on all Connections. </ins> Note that many Connection Properties have a corresponding Selection  <ins> Property which enables applications to express their preference for </ins> protocols providing a supporting transport feature. 10.1.1.


does not deem a data transfer useful.  It is given in bits per second.  The special value -1 indicates that no bound is specified. <del> 10.1.12. </del>  <del> This property specifies, for the case TCP becomes the chosen transport protocol: </del>  <del> a time value (default: the TCP default) to be advertised via the User Timeout Option (UTO) for the TCP at the remote endpoint to adapt its own "Timeout for aborting Connection" (see conn-timeout) value accordingly. </del>  <del> a boolean (default false) to control whether the UTO option is enabled for a connection.  This applies to both sending and receiving. </del>  <del> a boolean (default true) which controls whether the "Timeout for aborting Connection" (see conn-timeout) may be changed based on a UTO option received from the remote peer.  This boolean becomes false when "Timeout for aborting Connection" (see conn-timeout) is used. </del>  <del> All of the above parameters are optional (e.g., it is possible to specify "User Timeout Enabled" as true, but not specify an Advertised User Timeout value; in this case, the TCP default will be used). </del>  <del> 10.2. </del>  Asynchronous introspection is also possible, via the SoftError Event. This event informs the application about the receipt of an ICMP error even if the underlying stack supports it, there is no guarantee that a soft error will be signaled. <del> 10.3. </del>  This event notifies the application of excessive retransmissions, based on a configured threshold (see conn-excss-retransmit).  This

Btw why do we have (only) properties for the TCP UTO?
I didn't get that this is only an example, so yes we should say this more explicitly. Not sure where to put that though. Maybe we can just merge this PR for now and have a separate PR to add this somewhere.
I actually also just added "as an example for a protocol-specific property" in that section but maybe we want to say it somewhere else again...?
It isn't just an example. The reasons it's there go back to minset (if you remove it, you lose this functionality forever), yet there were arguments for this being a special TCP thing only, and being too awkward to include as general functionality - much like there are now arguments that might lead to ECN becoming UDP-specific.
Some more explanations: why is this included? From appendix C, we can see that it relates to "Suggest timeout to the peer" in minset. The argument for including this, in appendix A of the minset draft, is: "Functional because this is closely related to potentially assumed reliable data delivery." Indeed, the last paragraph of section 1 in RFC 5482 gives examples where communication might just fail for applications expecting their connections to stay up. in reality, this doesn't seem to be needed much, and so this is hardly implemented (if at all!).why is it TCP specific? This was discussed in issue : URL The key statement against having this as a general thing is probably this sentence from NAME "If we had a timeout on overall connection establishment, from Initiate() to Ready(), then that's trying to set a timeout not just on TCP, but on DNS, racing, proxies, TLS, and who knows what else."
Okay, let's merge this and then think about how to motivate that we specify UTO. If we do it because it's in minset, that means that implementations have to expose UTO to be TAPS-compliant because TAPS requires that implementations at least expose the features in minset. Also, I think we should say is that there's more Protocol-Specific Properties and we don't specify all of them here, but implementations are free to add their own.

does not deem a data transfer useful.  It is given in bits per second.  The special value -1 indicates that no bound is specified.  <ins> 10.2. </ins>  <ins> These properties specifies configurations for the User Timeout Option (UTO), in case TCP becomes the chosen transport protocol. Implementation is optional and of course only sensible if TCP is implemented in the transport system. </ins>  <ins> All of the below parameters are optional (e.g., it is possible to specify "User Timeout Enabled" as true, but not specify an Advertised User Timeout value; in this case, the TCP default will be used). </ins>  <ins> 10.2.1. </ins>  <ins> tcp.user-timeout-value </ins>  <ins> Integer </ins>  <ins> Default: :the TCP default This time value is advertised via the TCP User Timeout Option (UTO) RFC5482 at the remote endpoint to adapt its own "Timeout for aborting Connection" (see conn-timeout) value accordingly. 10.2.2. tcp.user-timeout Boolean false This property controls whether the UTO option is enabled for a connection.  This applies to both sending and receiving. 10.2.3. tcp.user-timeout-recv Boolean true This property controls whether the "Timeout for aborting Connection" (see conn-timeout) may be changed based on a UTO option received from the remote peer.  This boolean becomes false when "Timeout for aborting Connection" (see conn-timeout) is used. 10.3. </ins> Asynchronous introspection is also possible, via the SoftError Event. This event informs the application about the receipt of an ICMP error even if the underlying stack supports it, there is no guarantee that a soft error will be signaled.  <ins> 10.4. </ins> This event notifies the application of excessive retransmissions, based on a configured threshold (see conn-excss-retransmit).  This


10.3.  Asynchronous introspection is also possible, via the SoftError Event. This event informs the application about the receipt of an ICMP error message related to the Connection.  This will only happen if the even if the underlying stack supports it, there is no guarantee that a soft error will be signaled. <del> 10.4. </del>  This event notifies the application of excessive retransmissions, based on a configured threshold (see conn-excss-retransmit).  This

Btw. does this cover all events? There is an issue where I also ask if we e.g. need an event that sending failed due to lifetime expiry. is there a way to double-check if we considered all needed events? Should we also mention ConnectionErrors here? Maybe we anyway need to say more about error?
These are not all events (just search for the word "event" in the document), and generally they are not all lumped together - e.g. sending related events such as "Sent" appear in the "Sending Data" section - which, in fact, has its own subsection called "Send Events". So, this would be a subsection just related to connection management... but then, you state: "During the lifetime of a connection there are events that can occur when configured." which gives the (wrong) impression that this would be the list of all events that can happen during a connection's lifetime. So, I wouldn't add this subsection heading and not include that statement. Or maybe add the subsection heading (which is ok but doesn't help much - as you see, there are only very few events in there), but remove that statement.
+1 to calling this "connection lifecycle events" or similar (do we refer to a connection lifecycle?)
Changed the heading and fixed the nit. I'm open to have another sentence there if people have proposals. We could even have no text but we usually say something after each heading.
Given the new heading, I'm fine with the sentence as it is - because the context is clear now, it's no longer misleading (i.e., giving the wrong impression that these would be ALL events).

10.3. <ins> During the lifetime of a connection there are events that can occur when configured. 10.3.1. </ins> Asynchronous introspection is also possible, via the SoftError Event. This event informs the application about the receipt of an ICMP error message related to the Connection.  This will only happen if the even if the underlying stack supports it, there is no guarantee that a soft error will be signaled.  <ins> 10.3.2. </ins> This event notifies the application of excessive retransmissions, based on a configured threshold (see conn-excss-retransmit).  This


D.ietf-taps-transport-security. As described above in equivalence, if a Transport Services system <del> races between two different Protocol Stacks, both MUST use the same security protocols and options. </del>  Applications need to ensure that they use security APIs appropriately.  In cases where applications use an interface to Moreover, Transport Services systems MUST NOT automatically fall back from secure protocols to insecure protocols, or to weaker versions of <del> secure protocols.  For example, if an application requests TLS, but the desired version of TLS is not available, its connection will fail.  Applications are thus responsible for implementing security protocol fallback or version fallback by creating multiple Transport Services Connections, if so desired. </del>

Following , Section 4.2.3 of the Architecture document now says that fallback between different security protocol versions might be allowed. The Security Considerations section was out of sync. This PR fixes that.

D.ietf-taps-transport-security. As described above in equivalence, if a Transport Services system  <ins> races between two different Protocol Stacks, both SHOULD use the same security protocols and options.  However, a Transport Services system MAY race different security protocols, e.g., if the application explicitly specifies that it considers them equivalent. </ins> Applications need to ensure that they use security APIs appropriately.  In cases where applications use an interface to Moreover, Transport Services systems MUST NOT automatically fall back from secure protocols to insecure protocols, or to weaker versions of  <ins> secure protocols.  For example, if an application requests a specific version of TLS, but the desired version of TLS is not available, its connection will fail.  Applications are thus responsible for implementing security protocol fallback or version fallback by creating multiple Transport Services Connections, if so desired. Alternatively, a Transport Services system MAY allow applications to specify that fallback to a specific other version of a protocol is allowed. </ins>


model describes how the API model of Transport Services differs from traditional socket-based APIs.  Specifically, it offers asynchronous event-driven interaction, the use of messages for <del> data transfer, and the ability to easily adopt different transport protocols. </del>  design explains the design principles behind the Transport Services API.  These principles are intended to make sure that

Proposed some text for - I think this summarizes the "flexibility" advantage of TAPS that we elaborate on in Section 2.3.
In Section 1.2, Overview, the architecture draft says that TAPS offers "the ability to easily adopt different transport protocols". What does "adopt" mean here? I guess this relates to Section 2.3 (maybe say that explicitly here), but even after reading this Section, I don't quite understand why "adopt". Is the point here that a flexible interface makes it easier to add support for new protocols? Then perhaps we should say this here.
It means that applications don't need to rewrite a ton of code or adopt a new library to access a new transport protocol. In how I read it, "adopt" captures that, but if there's some other text you would like to suggest, that's fine.
For me "adopt" is fine as it should be clear from the rest of the doc. However, if we want to be more clear we could say "make use of different protocols without the need to change the interface" or something...?
Looks good, merged!

model describes how the API model of Transport Services differs from traditional socket-based APIs.  Specifically, it offers asynchronous event-driven interaction, the use of messages for  <ins> data transfer, and the flexibility to use different transport protocols and paths without requiring major changes to the application. </ins> design explains the design principles behind the Transport Services API.  These principles are intended to make sure that