jiebi/TextFlow huggingface dataset:
Original text:
Once a Preconnection has been used to create an outbound Connection or a Listener, the implementation should ensure that the copy of the <del> properties held by the Connection or Listener is not affected when the application makes changes to a Preconnection object.  This may involve the implementation performing a deep-copy, copying the object with all the objects that it references. </del>  Once the Connection is established, Transport Services implementation maps actions and events to the details of the chosen Protocol Stack.

Reviewer comments:
Preconnections are mutable, until they are not. The second paragraph of section 2 states "bundles of properties an application can both read and write", which seems to conflict with this. Para should lead with the fact of mutable mutability over the preconnection lifecycle, not "is mutable".
The Connection/Listener makes a deep copy that is now immutable, but the original object is still mutable.

Revised text:
Once a Preconnection has been used to create an outbound Connection or a Listener, the implementation should ensure that the copy of the  <ins> properties held by the Connection or Listener cannot be mutated by the application making changes to the original Preconnection object. This may involve the implementation performing a deep-copy, copying the object with all the objects that it references. </ins> Once the Connection is established, Transport Services implementation maps actions and events to the details of the chosen Protocol Stack.
Original text:
hostnames.  Each of these hostnames might resolve to one or more addresses, which would create multiple layers of branching.  4.1.1.2. If a client has multiple network paths available to it, e.g., a

Reviewer comments:
In the impl draft, I'm supposed to build a tree based on, in order (1) "path": AFAICT this means "interface". The -api draft provides in interface preference framework in 4.2.11. (BTW if it really means interface maybe we should say 'interface'). (2) Protocol: almost all of 4.2 in -api explains how to express this. (with an assist in -impl 4.1.3 explaining how to handle PREFER vs. AVOID) (3) "derived endpoint" I gather this is basically multiple addresses coming back from remote endpoint resolution. But where is the construct in -api that allows applications to express a preference here?
I'm not sure we want to add anything to the API here. There are existing preferences that can bias towards IPv6, such as preferring or requiring . I think we can just detail that in the implementation draft.
Thanks, LGTM!

Revised text:
hostnames.  Each of these hostnames might resolve to one or more addresses, which would create multiple layers of branching. <ins> Applications can influence which derived endpoints are allowed and preferred via Selection Properties set on the Preconnection.  For example, setting a preference for "useTemporaryLocalAddress" would prefer the use of IPv6 over IPv4, and requiring "useTemporaryLocalAddress" would eliminate IPv4 options, since IPv4 does not support temporary addresses. </ins> 4.1.1.2. If a client has multiple network paths available to it, e.g., a
Original text:
they are equivalent to Actions on a per-application global context. Events are sent to the application or application-supplied code (e.g. <del> framers, see framing) for processing; the details of event processing are platform- and implementation-specific. </del>  We also make use of the following basic types: an asynchronous interface using the Socket API generally uses a try- and-fail model.  If the application wants to read, but data has not yet been received from the peer, the call to read will fail.  The <del> application then waits and can try again later.  In contrast to the Socket API, all interaction using the Transport Services API is expected to be asynchronous and use an event-driven model (see events).  For example, an application first issues a call to receive new data from the connection.  When delivered data becomes available, this data is delivered to the application using asynchronous events that contain the data.  Error handling is also asynchronous; a failure to send data results in an asynchronous error event. </del>  This API also delivers events regarding the lifetime of a connection and changes in the available network links, which were not previously

Reviewer comments:
in architecture.
Per slide 14 in Thorben Krüger's presentation at IETF 113: URL, clarify that the API is defined in terms of events to be general, not because you have to implement an event system if you're going to implement TAPS.
LGTM

Revised text:
they are equivalent to Actions on a per-application global context. Events are sent to the application or application-supplied code (e.g.  <ins> framers, see framing) for processing; the details of event interfaces are platform- and implementation-specific, and may be implemented using other forms of asynchronous processing, as idiomatic for the implementing platform. </ins> We also make use of the following basic types: an asynchronous interface using the Socket API generally uses a try- and-fail model.  If the application wants to read, but data has not yet been received from the peer, the call to read will fail.  The  <ins> application then waits and can try again later. In contrast to the Socket API, all interaction using the Transport Services API is expected to be asynchronous.  The API is defined around an event-driven model (see events) in order to model this asynchronous interaction, though other forms of asynchronous communication may be available to applications depending on the platform implementing the interface. For example, an application first issues a call to receive new data from the connection.  When delivered data becomes available, this data is delivered to the application using asynchronous events that contain the data.  Error handling is also asynchronous; a failure to send data results in an asynchronous error event. </ins> This API also delivers events regarding the lifetime of a connection and changes in the available network links, which were not previously
Original text:
the ability to associate deadlines with messages, for applications that care about timing; <del> the ability control reliability, which messages to retransmit when there is packet loss, and how best to make use of the data that arrived; </del>  the ability to automatically assign messages and connections to underlying transport connections to utilize multi-streaming and and System-implementation concepts, which are intended to be <del> internally used by aTransport Services implementation. </del>  The following diagram summarizes the top-level concepts in the architecture and how they relate to one another.

Reviewer comments:
This pull requests fixes two minor typos in draft-ietf-taps-URL that I noticed during detailed reading of the draft.

Revised text:
the ability to associate deadlines with messages, for applications that care about timing;  <ins> the ability to control reliability, which messages to retransmit when there is packet loss, and how best to make use of the data that arrived; </ins> the ability to automatically assign messages and connections to underlying transport connections to utilize multi-streaming and and System-implementation concepts, which are intended to be  <ins> internally used by a Transport Services implementation. </ins> The following diagram summarizes the top-level concepts in the architecture and how they relate to one another.
Original text:
endpoint, path (labeled here by interface), and protocol.  The above example can now be written more succinctly as: <del> When an implementation views this aggregate set of connection attempts as a single connection establishment, it only will use one of the leaf nodes to transfer data.  Thus, when a single leaf node becomes ready to use, then the entire connection attempt is ready to use by the application.  Another way to represent this is that every leaf node updates the state of its parent node when it becomes ready, until the trunk node of the tree is ready, which then notifies the application that the connection as a whole is ready to use. </del>  A connection establishment tree may be degenerate, and only have a single leaf node, such as a connection attempt to an IP address over

Reviewer comments:
Raising this issue as part of my review of the the Implementation Draft. Quoting from Section 4.1 "Structuring Candidates as a Tree" ~ Feedback: While it is understood that "connection attempt" is here used to refer to a given node in the tree, rather than the actual (stateful) process of attempting to connect to the given endpoint (using the given parameters), it does not make for easy reading. Similarly, it is possible to grasp how an "aggregate set" can be "viewed" as "a single connection establishment", but the language could be clearer here as well. Couldn't an "attempt" that has succeeded and is "ready to use" be referred to differently? Couldn't "candidate" or "option" be substituted for "attempt" to improve readability? Proposal:
Seems quite close to me
Yes, I like this proposed text.

Revised text:
endpoint, path (labeled here by interface), and protocol.  The above example can now be written more succinctly as:  <ins> When an implementation is asked to establish a single connection, only one of the leaf nodes in the candidate set is needed to transfer data.  Thus, once a single leaf node becomes ready to use, then the connection establishment tree is considered ready.  One way to implement this is by having every leaf node update the state of its parent node when it becomes ready, until the trunk node of the tree is ready, which then notifies the application that the connection as a whole is ready to use. </ins> A connection establishment tree may be degenerate, and only have a single leaf node, such as a connection attempt to an IP address over
Original text:
This only takes effect when the transport uses a network layer that supports this functionality.  When it does take effect, setting this property to true will cause the sender to avoid network-layer source <del> frgementation.  When using IPv4, this will result in the Don't </del>  Fragment bit being set in the IP header. Attempts to send a message with this property that result in a size provide segmentation of messages larger than the maximum size permitted by the network layer, and also to avoid network-layer source fragmentation of messages.  When running over IPv4, setting <del> this property to true can result in a sending endpount setting the </del>  Don't Fragment bit in the IPv4 header of packets generated by the <del> transport layer.  An attempt to send a message that results in a size greater than the transport's current estimate of its maximum packet size (singularTransmissionMsgMaxLen) will result in a SendError. This only takes effect when the transport and network layer support this functionality. </del>  9.2.

Reviewer comments:
This seems otherwise inconsistent: for the noFragmentation property, we say that, in case of IPv4, setting this will result in setting the "Don't Fragment" bit. the noSegmentation property is described as avoiding fragmentation AND avoiding segmentation. So logically, this should also result in setting the "Don't Fragment" bit in case of IPv4. Generally, I'm not sure how an implementer should interpret the "can" here, in contrast with the "will" in the "Don't Fragment" case above... the textual difference seems to hint that this could be implemented differently, but then, how?

Revised text:
This only takes effect when the transport uses a network layer that supports this functionality.  When it does take effect, setting this property to true will cause the sender to avoid network-layer source  <ins> fragmentation.  When using IPv4, this will result in the Don't </ins> Fragment bit being set in the IP header. Attempts to send a message with this property that result in a size provide segmentation of messages larger than the maximum size permitted by the network layer, and also to avoid network-layer source fragmentation of messages.  When running over IPv4, setting  <ins> this property to true will result in a sending endpount setting the </ins> Don't Fragment bit in the IPv4 header of packets generated by the  <ins> transport layer. An attempt to send a message that results in a size greater than the transport's current estimate of its maximum packet size ("singularTransmissionMsgMaxLen") will result in a "SendError".  This only takes effect when the transport and network layer support this functionality. </ins> 9.2.
Original text:
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 binds a local port and prepares it to receive inbound UDP datagrams from peers.

Reviewer comments:
First cut at new text
UDP, ConnectionError: Would those soft errors contain additional information about the ICMP error code, and can an application expect to find the (partial) original datagram in the error?
This is a good question! - on the one hand, the additional info can be valuable - for example to validate an ICMP message, as suggested for validating ICMP for a DPLPMTUD probe - but on the other hand, this info is often not provided by existing APIs.
I figure that a practical thing to state would be that the information is provided if it is accessible on a platform. Having text that describes this as matter of implementation quality would help TAPS implementers push for (eg. MSG_ERRQUEUE style) provisions in their platforms.
If the system makes this information available, we could mention that you could pass it up.
See a proposal in
The pointer to the PR with the specific proposal to address this issue got a "thumbs up" from the NAME who wrote the review. So, this PR should have closed this issue. Doing it manually.

Revised text:
Once in use, UDP throws "soft errors" (ERROR.UDP(-Lite)) upon receiving ICMP notifications indicating failures in the network. <ins> Additional information can also be provided when this is available to the system (e.g.  ICMP error code and quoted packet header). </ins> LISTEN.UDP.  Calling "Listen" for UDP binds a local port and prepares it to receive inbound UDP datagrams from peers.
Original text:
the main Connection implementation that delivers events to the custom framer implementation whenever data is ready to be parsed or framed.  The Transport Services implementation needs to ensure that all of the events and actions taken on a Message Framer are synchronized to ensure consistent behavior.  For example, some of the actions defined

Reviewer comments:
Framers: The paragraphs in Defining Message Framers and later might be formal language or pseudocode, I can't tell. It might help if the introduction stated something around names and signatures of signals and functions being expressed in pseudocode, and that identifiers in implementations are expected to be similar to those but following the conventions of the language
We should reference section 1.1 of the API document which defines the notation used.

Revised text:
the main Connection implementation that delivers events to the custom framer implementation whenever data is ready to be parsed or framed. <ins> The API examples in this section use the notation conventions for the Transport Services API defined in Section 1.1 of I-D.ietf-taps- interface. </ins> The Transport Services implementation needs to ensure that all of the events and actions taken on a Message Framer are synchronized to ensure consistent behavior.  For example, some of the actions defined
Original text:
Calling "AbortGroup" on a UDP Connection (ABORT.UDP(-Lite)) is identical to calling "Close" on this Connection and on all <del> Connections in the same ConnectionGroup.  ## UDP-Lite </del>  Connectedness: Connectionless UDP-Lite, such as "msgChecksumLen", "fullChecksumSend", "recvChecksumLen", and "fullChecksumRecv". <del> 10.4. </del>  Connectedness: Connectionless A UDP Multicast Receive Connection is ready once the system has received traffic for the appropriate group and port. <del> 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. </del>  LISTEN.UDP.  Calling "Listen" for UDP Multicast Receive binds a local port, prepares it to receive inbound UDP datagrams from (ABORT.UDP(-Lite)) is identical to calling "Close" on this Connection and on all Connections in the same ConnectionGroup. <del> 10.5. </del>  Connectedness: Connected

Reviewer comments:
(More out of curiosity, with no expectation that this would find its way into the text unless you think I've hit a bug): In UDP Multicast Receive, which kind of ICMP notifications can come in there that would constitute a ConnectionError -- given that this transport does not send (and would thus usually not trigger any)?
Section 10.4 for multicast receive mentions ICMP errors. You could have errors on initiate for joining a multicast group, etc, but it likely doesn't make sense to have ICMP errors mentioned here.
Suggest we can close this issue.
LGTMSeems like we do not loose anything by removing this. The change WFM.

Revised text:
Calling "AbortGroup" on a UDP Connection (ABORT.UDP(-Lite)) is identical to calling "Close" on this Connection and on all  <ins> Connections in the same ConnectionGroup. 10.4. </ins> Connectedness: Connectionless UDP-Lite, such as "msgChecksumLen", "fullChecksumSend", "recvChecksumLen", and "fullChecksumRecv".  <ins> 10.5. </ins> Connectedness: Connectionless A UDP Multicast Receive Connection is ready once the system has received traffic for the appropriate group and port.  <ins> UDP Multicast Receive Connections generate an InitiateError indicating that joining a multicast group failed if Initiate is called. </ins> LISTEN.UDP.  Calling "Listen" for UDP Multicast Receive binds a local port, prepares it to receive inbound UDP datagrams from (ABORT.UDP(-Lite)) is identical to calling "Close" on this Connection and on all Connections in the same ConnectionGroup.  <ins> 10.6. </ins> Connectedness: Connected
Original text:
resolution, when support mechanisms such as TURN or ICE are used to establish connectivity, if protocols or paths are raised, or if a path fails and fallback or re-establishment is supported in the <del> Transport Services system. </del>  Applications should also take care to not assume that all data received using the Transport Services API is always complete or well-

Reviewer comments:
"In effect, each leaf node will send the same early application data, yet encoded (encrypted) differently on the wire.": There has been a warning on the privacy implications of using the same token on different paths; doesn't sending an identical 0-RTT message racingly on multiple transports cause similar correlation issues?
This may be better to put in the privacy and security considerations section of the API document, particularly that doing cleartext 0-RTT data that races can be recognized on the path (as opposed to being in TLS which fixes this).
Similarly, connection racing overall can let a server observe that a client has multiple addresses and what they are, etc.
LGTM; note that I left a tiny comment.

Revised text:
resolution, when support mechanisms such as TURN or ICE are used to establish connectivity, if protocols or paths are raised, or if a path fails and fallback or re-establishment is supported in the  <ins> Transport Services system.  Applications should take special care when using 0-RTT session resumption (see prop-0rtt), as early data sent across multiple paths during connection establishment may reveal information that can be used to correlate endpoints on these paths. </ins> Applications should also take care to not assume that all data received using the Transport Services API is always complete or well-
Original text:
use of temporary addresses, the resulting Connection cannot use IPv4, because temporary addresses do not exist in IPv4.  Second, temporary local addresses might involve trading off privacy for performance. <del> For instance, temporary addresses can interfere with resumption mechanisms that some protocols rely on to reduce initial latency. </del>  6.2.14.

Reviewer comments:
Adding this issue from Fernando via the TAPS list: The terminology employed in this subsection seems a bit confusing, or at least deviates from what we normally use in v6-circles. I suggest taking a look at RFC7721 -- certainly not flawless, but it was 6man's shot to try to agree on terminology. For example, I don't think we use "permanent" and "stable" interchangeably. e.g. the "Local" in "useTemporaryLocalAddress" might be misleading to some. -- e.g. could be interpreted as related with link-locals or ULAs. Aside, I believe there's much more to dig regarding address properties. e.g., we have given it a shot at: URL e.g., the choice of ipv6 addresses has more than one dimension... and there are tradeoffs involved, which IMHO deserve discussion. And aside from the regular address systems normally configure, if one were to specify an API one would probably want to provide a mechanism for apps to be able to request sole/single-use addresses (.e.g., one address per app or container).
"Local" has a meaning in the TAPS context, I don't think we need to change it for universalization with the full set of IPv6 terminology. There's also not much point in going all the way down the rabbithole for this particular property, given that we don't do so for any other -- this document is meant as a universal interface to networking for the future, not an unbounded treatise on the future of networking. That said, the linked draft does seem to address the issues here and it's fairly alive, so no harm in adding an informative reference to it.
I agree with the comments of NAME and NAME

Revised text:
use of temporary addresses, the resulting Connection cannot use IPv4, because temporary addresses do not exist in IPv4.  Second, temporary local addresses might involve trading off privacy for performance.  <ins> For instance, temporary addresses (e.g., RFC8981) can interfere with resumption mechanisms that some protocols rely on to reduce initial latency. </ins> 6.2.14.
Original text:
system objects that may be temporarily unavailable. Separate from events, callbacks are also provided for asynchronous <del> interactions with the Transport Services API, which are not directly </del>  related to events on the network or network interfaces. 2.2.

Reviewer comments:
Clarified one use of word "API" comes just after discussion of the socket API. Tried to fix specialised features to say they define additional requirements. Minor changes to wording, with no intended changes to substance.
LGTM but I made one very small comment

Revised text:
system objects that may be temporarily unavailable. Separate from events, callbacks are also provided for asynchronous  <ins> interactions with the Transport Services API that are not directly </ins> related to events on the network or network interfaces. 2.2.