jiebi/TextFlow huggingface dataset:
Original text:
Connection-oriented transport protocols), or when the first Message has been received from the Remote Endpoint (for Connectionless protocols), causing a new Connection to be created.  The resulting <del> Connection is contained within the ConnectionReceived event, and is </del>  ready to use as soon as it is passed to the application via the event.  A ListenError occurs either when the Properties of the Preconnection cannot be fulfilled for listening, when the Local Endpoint (or Remote Endpoint, if specified) cannot be resolved, or when the application is prohibited from listening by policy. <del> A Stopped event occurs after the Listener has stopped listening. </del>  6.3.

Reviewer comments:
This implements what we discussed on
There should be a way to put back pressure or limits on the number of inbound connections for a listener. The two approaches are: To have a one-to-one callback for listen -> received connect To have a way to set a numeric limit of new inbound connections My preference is (2). (1) has an issue of being very impractical for servers that don't know how many connections they'll receive, and may require them to call a thousand times without any other activity. (2) is more similar to how calling on sockets work.
+1 on variant 2 - indeed it's common and known to people from sockets, and just seems like the easier and more efficient solution (albeit maybe less "beautiful", in a way).
+1 on variant 2 as well.
Do variant 2.
I believe that PR fully addresses this; hence I'm closing it.
lgtm, thanks!This is surely useful as-is. Considering the recent discussion on the list (dynamic per-IP rejection possibilities), I'm not sure it's rich enough... but it's certainly a good starting point. I'm also not sure how much of what's been discussed really should be a part of the spec.

Revised text:
Connection-oriented transport protocols), or when the first Message has been received from the Remote Endpoint (for Connectionless protocols), causing a new Connection to be created.  The resulting  <ins> Connection is contained within the ConnectionReceived Event, and is </ins> ready to use as soon as it is passed to the application via the event. <ins> If the caller wants to rate-limit the number of inbound Connections that will be delivered, it can set a cap using SetNewConnectionLimit().  This mechanism allows a server to protect itself from being drained of resources.  Each time a new Connection is delivered by the ConnectionReceived Event, the value is automatically decremented.  Once the value reaches zero, no further Connections will be delivered until the caller sets the limit to a higher value.  By default, this value is Infinite.  The caller is also able to reset the value to Infinite at any point. </ins> A ListenError occurs either when the Properties of the Preconnection cannot be fulfilled for listening, when the Local Endpoint (or Remote Endpoint, if specified) cannot be resolved, or when the application is prohibited from listening by policy.  <ins> A Stopped Event occurs after the Listener has stopped listening. </ins> 6.3.
Original text:
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.

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

Revised text:
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.
Original text:
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

Reviewer comments:
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!

Revised text:
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
Original text:
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.

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

Revised text:
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.
Original text:
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.

Reviewer comments:
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.

Revised text:
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.
Original text:
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

Reviewer comments:
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

Revised text:
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
Original text:
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

Reviewer comments:
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!

Revised text:
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
Original text:
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.

Reviewer comments:
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?

Revised text:
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.
Original text:
msg-lifetime <del> Integer </del>  infinite

Reviewer comments:
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.

Revised text:
msg-lifetime  <ins> Numeric </ins> infinite
Original text:
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.

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

Revised text:
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.
Original text:
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.

Reviewer comments:
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.

Revised text:
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.
Original text:
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:

Reviewer comments:
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!

Revised text:
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:
Original text:
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:

Reviewer comments:
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

Revised text:
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:
Original text:
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:

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

Revised text:
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: