jiebi/ids-paragraph-commentary-corpus huggingface dataset:
Draft: draft-ietf-taps-impl

Commentary: Section 10 of impl draft : " Below , primitives in the style of " CATEGORY.[SUBCATEGORY].PRIMITIVENAME.PROTOCOL " ( e.g. , " CONNECT.SCTP " ) refer to the primitives with the same name in section 4 of [ RFC8303 ] . " I know it 's specified like this in RFC8303 but PRIMITIVENAME does not seem to be explained or used . Maybe I did n't look careful enough but to be honest I also did n't find the use of this nomenclature from RFC8303 very helpful ... 
 Just to answer the comment of usefulness of this nomenclature : this allows back - tracking to the relevant spec . , which ( I believe ) is valuable for people implementing a TAPS system . In the example of CONNECT.SCTP , RFC 8303 describes this as consisting of : Interleaving ' ( optional ) , followed by ' Associate ' Initialize and Associate are obvious ; naturally , they come from RFC 4960 . Considering to use ' Enable / Disable Interleaving ' ( which is very important for a TAPS system - to implement priorities between streams ) is perhaps less obvious , and the text points back at RFC 8260 .
Paragraph (version A):
Below, primitives in the style of
"CATEGORY.[SUBCATEGORY].PRIMITIVENAME.PROTOCOL" (e.g.,
"CONNECT.SCTP") refer to the primitives with the same name in section
4 of RFC8303.  For further implementation details, the description of
these primitives in RFC8303 points to section 3, which refers back to
the specifications for each protocol.  This back-tracking method
applies to all elements of I-D.ietf-taps-minset (see appendix D of I-
D.ietf-taps-interface): they are listed in appendix A of I-D.ietf-
taps-minset with an implementation hint in the same style, pointing
back to section 4 of RFC8303.
Paragraph (version B):
Below, terms in capitals with a dot (e.g., "CONNECT.SCTP") refer to
the primitives with the same name in section 4 of RFC8303.  For
further implementation details, the description of these primitives
in RFC8303 points to section 3 of RFC8303 and section 3 of RFC8304,
which refers back to the relevant specifications for each protocol.
This back-tracking method applies to all elements of I-D.ietf-taps-
minset (see appendix D of I-D.ietf-taps-interface): they are listed
in appendix A of I-D.ietf-taps-minset with an implementation hint in
the same style, pointing back to section 4 of RFC8303.
Draft: draft-ietf-taps-impl

Commentary: I would further recommend to move this section into 4 somewhere as this section is more about connection establishment than sending messages 
 LGTM
Paragraph (version A):
If the application has 0-RTT data to send in any protocol handshakes,
it needs to provide this data before the handshakes have begun.  When
racing, this means that the data should be provided before the
process of connection establishment has begun.  If the application
wants to send 0-RTT data, it must indicate this to the implementation
by setting the "Safely Replayable" send parameter to true when
sending the data.  In general, 0-RTT data may be replayed (for
example, if a TCP SYN contains data, and the SYN is retransmitted,
the data will be retransmitted as well), but racing means that
different leaf nodes have the opportunity to send the same data
independently.  If data is truly safely replayable, this should be
permissible.
Paragraph (version B):
If the application has 0-RTT data to send in any protocol handshakes,
it needs to provide this data before the handshakes have begun.  When
racing, this means that the data should be provided before the
process of connection establishment has begun.  If the application
wants to send 0-RTT data, it must indicate this to the implementation
by setting the "Safely Replayable" send parameter to true when
sending the data.  In general, 0-RTT data may be replayed (for
example, if a TCP SYN contains data, and the SYN is retransmitted,
the data will be retransmitted as well but may be considered as a new
connection instead of a retransmission).  Also, when racing
connections, different leaf nodes have the opportunity to send the
same data independently.  If data is truly safely replayable, this
should be permissible.
Paragraph (version A):
0-RTT handshakes often rely on previous state, such as TCP Fast Open
cookies, previously established TLS tickets, or out-of-band
distributed pre-shared keys (PSKs).  Implementations should be aware
of security concerns around using these tokens across multiple
addresses or paths when racing.  In the case of TLS, any given ticket
or PSK should only be used on one leaf node.  If implementations have
multiple tickets available from a previous connection, each leaf node
attempt must use a different ticket.  In effect, each leaf node will
send the same early application data, yet encoded (encrypted)
differently on the wire.
Paragraph (version B):
0-RTT handshakes often rely on previous state, such as TCP Fast Open
cookies, previously established TLS tickets, or out-of-band
distributed pre-shared keys (PSKs).  Implementations should be aware
of security concerns around using these tokens across multiple
addresses or paths when racing.  In the case of TLS, any given ticket
or PSK should only be used on one leaf node, since servers will
likely reject duplicate tickets in order to prevent replays (see
section-8.1 RFC8446).  If implementations have multiple tickets
available from a previous connection, each leaf node attempt can use
a different ticket.  In effect, each leaf node will send the same
early application data, yet encoded (encrypted) differently on the
wire.
Draft: draft-ietf-taps-impl

Commentary: and spell out ICE . 
 I also updated a later reference and references for STUN and TURN in this same PR now .
Paragraph (version A):
Both Local and Remote Endpoint Candidates must be discovered during
connection establishment.  To support ICE, or similar protocols, that
involve out-of-band indirect signalling to exchange candidates with
the Remote Endpoint, it's important to be able to query the set of
candidate Local Endpoints, and give the protocol stack a set of
candidate Remote Endpoints, before it attempts to establish
connections.
Paragraph (version B):
Both Local and Remote Endpoint Candidates must be discovered during
connection establishment.  To support Interactive Connectivity
Establishment (ICE) RFC8445, or similar protocols, that involve out-
of-band indirect signalling to exchange candidates with the Remote
Endpoint, it's important to be able to query the set of candidate
Local Endpoints, and give the protocol stack a set of candidate
Remote Endpoints, before it attempts to establish connections.
Paragraph (version A):
If NAT traversal is required, the process of gathering Local
Endpoints becomes broadly equivalent to the ICE candidate gathering
phase RFC5245.  The endpoint determines its server reflexive Local
Endpoints (i.e., the translated address of a local, on the other side
of a NAT) and relayed locals (e.g., via a TURN server or other
relay), for each interface and network protocol.  These are added to
the set of candidate Local Endpoints for this connection.
Paragraph (version A):
Gathering Local Endpoints is primarily a local operation, although it
might involve exchanges with a STUN server to derive server reflexive
locals, or with a TURN server or other relay to derive relayed
locals.  It does not involve communication with the Remote Endpoint.
Paragraph (version B):
If NAT traversal is required, the process of gathering Local
Endpoints becomes broadly equivalent to the ICE candidate gathering
phase (see Section 5.1.1. of RFC8445).  The endpoint determines its
server reflexive Local Endpoints (i.e., the translated address of a
local, on the other side of a NAT, e.g via a STUN sever RFC5389) and
relayed locals (e.g., via a TURN server RFC5766 or other relay), for
each interface and network protocol.  These are added to the set of
candidate Local Endpoints for this connection.
Paragraph (version B):
Gathering Local Endpoints is primarily a local operation, although it
might involve exchanges with a STUN server to derive server reflexive
locals, or with a TURN server or other relay to derive relayed
locals.  However, it does not involve communication with the Remote
Endpoint.
Draft: draft-ietf-taps-impl

Commentary: You can not have references in the abstract . Initially I only wanted to remove that reference but then I also took the opportunity to rewrite the abstract a bit to not only talk about the architecture but an TAPS system and the interface that this guide helps with its implementation . 
 LGTM ( I fixed a tiny nit directly with a commit)Thanks looks good .
Paragraph (version A):
The Transport Services architecture I-D.ietf-taps-arch defines a
system that allows applications to use transport networking protocols
flexibly.  This document serves as a guide to implementation on how
to build such a system.
Paragraph (version B):
The Transport Services (TAPS) system enables applications to use
transport protocols flexibly for network communication and defines a
protocol-independent TAPS Application Programming Interface (API)
that is based on an asynchronous, event-driven interaction pattern.
This document serves as a guide to implementation on how to build
such a system.
Draft: draft-ietf-taps-arch

Commentary: Addresses 
 I wondering if we should to talk a bit more about authentication in the the arch doc . The API doc has the concept of security parameters , however there is no discussion about this in the arch document . Also , just double - checking : private keys and certificates / identify can be set as a security parameter of a pre - connection . However , is that really a connection parameter or rather a local endpoint property ? 
 To match the API , add Security Properties to Section 4.1.2 . 
 Try to associate with the endpoint ? 
 Add to figure 4 too 
 I think ?
Paragraph (version B):
Security Parameters: Security Parameters define an application's
requirements for authentication and encryption on a Connection.
They are used by Transport Security protocols (such as those
described in I-D.ietf-taps-transport-security) to establish secure
Connections.  Examples of parameters that can be set include local
identities, private keys, supported cryptographic algorithms, and
requirements for validating trust of remote identities.  Security
Parameters are primarily associated with a Preconnection object,
but properties related to identities can be associated directly
with Endpoints.
Draft: draft-ietf-taps-arch

Commentary: arch doc sec 4.1.4 : " When receiving Messages , Message Properties can contain information about the received Message , such as  generated at the receiver and information signalled by the remote endpoint . " Maybe provide an example here ... ? 
 Suggestion : ECN , which is information given from UDP in the form of such metadata . 
 QUIC stream identifier example works 
 Final message is in API , just use that 
 LGTM modulo one nit - but see if you agree with my suggestion . If you do n't , I 'm ok with this anyway .
Paragraph (version B):
For example, a Message can be marked with a Message Property
indicating that it is the final message on a connection if the
peer sent a TCP FIN.
Draft: draft-ietf-taps-interface

Commentary: Following the discussion in , explain why TCP UTO is included as a Protocol - Specific Property , while other properties are not . Also , some minor consistency fixes . 
 Thanks for doing this!Thanks
Paragraph (version A):
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.
Paragraph (version A):
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).
Paragraph (version B):
These properties specify 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.
Paragraph (version B):
These TCP-specific properties are included here because the feature
"Suggest timeout to the peer" is part of the minimal set of transport
services I-D.ietf-taps-minset, where this feature was categorized as
"functional".  This means that when an implementation offers this
feature, it has to expose an interface to it to the application.
Otherwise, the implementation might violate assumptions by the
application, which could cause the application to fail.
Paragraph (version B):
All of the below properties 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).
Draft: draft-ietf-taps-interface

Commentary: Added defaults for interface and PvD following . Also , I caught one leftover " recommended default " . 
 We require implementations to have default but we do n't provide any recommendation for interface and PvD. 
 For Interface , this would the default be to set "  " on all available interfaces , right ? This indicates that the application has no preferences of its own , so the implementation can apply some default system policy . Also , if the application specified some local endpoint , this might constrain the actual interfaces used ( related to ) . If we try to phrase this as ( Preference , Enumeration ) , it reads a bit weird though : ( " Ignore " , " Cellular " ) and ( " Ignore " , "  " ) , for example . So perhaps we should just write text saying that the default is to set no application preference . 
 I think text is fine as well but we need to say something . 
 Thanks !
Paragraph (version A):
This property specifies whether the application would like the
Connection to be congestion controlled or not.  Note that if a
Connection is not congestion controlled, an application using such a
Connection should itself perform congestion control in accordance
with RFC2914.  Also note that reliability is usually combined with
congestion control in protocol implementations, rendering "reliable
but not congestion controlled" a request that is unlikely to succeed.
The recommended default is to Require that the Connection is
congestion controlled.
Paragraph (version B):
This property specifies whether the application would like the
Connection to be congestion controlled or not.  Note that if a
Connection is not congestion controlled, an application using such a
Connection should itself perform congestion control in accordance
with RFC2914.  Also note that reliability is usually combined with
congestion control in protocol implementations, rendering "reliable
but not congestion controlled" a request that is unlikely to succeed.
The default is to Require that the Connection is congestion
controlled.
Paragraph (version B):
The default is to not set a preference for any interface.
Paragraph (version B):
The default is to not set a preference for any PvD.
Draft: draft-ietf-taps-interface

Commentary: Following the suggestion in , made Local Address Preference a Set(Preference , Enumeration ) , so an application can now also Require or Prohibit stable addresses . Added a sentence warning that , e.g. , preferring stable AND temporary addresses does not make sense - but there are less obvious ways to produce a conflicting set of Selection Properties , too , and we know how to deal with them . 
 Interim discussion : let 's use prohibit / avoid / prefer / require temporary addresses . Default connections to prefer temporary . Default listeners to avoid temporary . 
 Note that it fails without temporary addresses if you require temporary ; which makes IPv4 fail . 
  this as discussed in the interim . Please take another look . 
 Looks good to me – But I am unsure whether we should replace the temporary address with a stable address with Preference . Rational : For IPv6 with outgoing connections , temporary is default anyway , so requiring the special case instead of avoid / prohibit the default looks much more straight forward . 
 I 've read this a few times but I 'm still not sure : What alternative solution are you proposing here ? 
 I am proposing to  the whole name and meaning of the property – instead of requesting a temporary address , request a stable address . 
 Thanks for clarifying . I think this Property is straightforward enough as is , no need to invert . 
 For Local Address Preference we only have the option to prefer stable or temporary . However , I guess we would also need a way to e.g. specify that stable is required , no ? 
 Is this addressed by PR ? 
 I do n't think so . 
 lgtm
Paragraph (version B):
Avoid for Listeners and Rendezvous Connections.  Prefer for other
Connections.
Paragraph (version B):
This property allows the application to express a preference for the
use of temporary local addresses, sometimes called "privacy"
addresses RFC4941.  Temporary addresses are generally used to prevent
linking connections over time when a stable address, sometimes called
"permanent" address, is not needed.  Note that if an application
Requires the use of temporary addresses, the resulting Connection
cannot use IPv4, as temporary addresses do not exist in IPv4.
Draft: draft-ietf-taps-arch

Commentary:  . 4 is n't fully consistent with sec . 12 in the API document . A few things that stood out to me : InitiateWithSend ( ) is missing . I can see that this is n't trying to cover everything , but randomly leaving some things out makes it all a bit confusing IMO ... " Connection Received " reads as if it should really be the " ConnectionReceived < " event in the API doc . So I would put these events there and use the " < " to indicate them . Same with " Closed " ... this is actually an event , so why not write it as such , with the " < " ? RendezvousDone is missing ... should we include all events or not ? Of course that would then also require adding Sent , Received , ... maybe it would be better to indicate that events are events , but put a statement somewhere saying that not all events are shown . In the same vein , I would replace " Connection Ready " with " Ready < " " Conn. Finished " reads as if it might be an event , but this event does n't exist ... I would just remove this 
 I 've InitiateWithSend ( ) , and removed  Finished ; you 're right , these are confusing . This diagram does not use the API draft 's event notation , and I 'm not sure it makes sense to introduce it here -- it would require a bit more expository text only to make a diagram that is an attempt to provide a high - level view provide a ... less high - level view . ( The expository text now says " ... some actions ... have been omitted for brevity and simplicity " and I think that 's the right approach . ) 
 Agreed ! 
 lgtm
Paragraph (version A):
The diagram below provides a high-level view of the actions and
events during the lifetime of a Connection object.  Note that some
actions are alternatives (e.g., whether to initiate a connection or
to listen for incoming connections), while others are optional (e.g.,
setting Connection and Message Properties in Pre-Establishment) or
have been omitted for brevity.
Paragraph (version B):
The diagram below provides a high-level view of the actions and
events during the lifetime of a Connection object.  Note that some
actions are alternatives (e.g., whether to initiate a connection or
to listen for incoming connections), while others are optional (e.g.,
setting Connection and Message Properties in Pre-Establishment) or
have been omitted for brevity and simplicity.
Draft: draft-ietf-taps-arch

Commentary: This is fully editorial : I 'm not sure if the term " Connection Group " is introduced in the right section . There might be no perfect fit but maybe section 2.2 is a bit better ? Also I note that the terms " Connection Group " and " Path " do not not show up in any of the figures ... 
 Make this a new subsection , i.e. 4.1.7 . 
 Works - Thank you !
Paragraph (version B):
A Connection Group is a set of Connections that share properties and
caches.  For multiplexing transport protocols, only Connections
within the same Connection Group are allowed to be multiplexed
together.  An application can explicitly define Connection Groups to
control caching boundaries, as discussed in groups.
Paragraph (version A):
Connection Group: A set of Connections that share properties and
caches.  For multiplexing transport protocols, only Connections
within the same Connection Group are allowed to be multiplexed
together.  An application can explicitly define Connection Groups
to control caching boundaries, as discussed in groups.
Draft: draft-ietf-taps-impl

Commentary: this should 
 Right there was a typo : Replacing the last 2 sentences , the last sentence ought to be : " Endpoints should avoid IP fragmentation ( { { ! RFC8304 } } ) and when used with transports running over IP version 4 the Do n't Fragment bit will be set . " These are two separate issues that a stack implementor has to decide to do : ( 1 ) Decide if the endpoint will fragment ; ( 2 ) decide if the path can fragment the fragments . In some OS this will be bundled together , in other OS they will not . 
 Discussed on the interim call . The name probably could be much better . We also want to model in the text the atomicity property of UDP transfers . 
 This text is broken : section 5.1 / o Singular Transmission : when this is true , the application requests to avoid transport - layer segmentation or network - layer fragmentation . Some transports implement network - layer fragmentation avoidance ( Path MTU Discovery ) without exposing this functionality to the application ; in this case , only transport- layer segmentation should be avoided , by fitting the message into a single transport - layer segment or otherwise failing . Otherwise , network - layer fragmentation should be avoided -- e.g. by requesting the IP Do n't Fragment bit to be set in case of UDP(-Lite ) and IPv4 ( SET_DF in [ RFC8304 ] ) . / we need to rewrite 
 Waiting to see exactly how DPLPMTUD finishes WGLC ... will be ready for text in Jan. 
 Reads much better except the last broken sentence
Paragraph (version A):
Singular Transmission: when this is true, the application requests
to avoid transport-layer segmentation or network-layer
fragmentation.  Some transports implement network-layer
fragmentation avoidance (Path MTU Discovery) without exposing this
functionality to the application; in this case, only transport-
layer segmentation should be avoided, by fitting the message into
a single transport-layer segment or otherwise failing.  Otherwise,
network-layer fragmentation should be avoided--e.g. by requesting
the IP Don't Fragment bit to be set in case of UDP(-Lite) and IPv4
(SET_DF in RFC8304).
Paragraph (version B):
Singular Transmission: When set, this property limits the message
size to the Maximum Message Size Before Fragmentation or
Segmentation (see Section 10.1.7 of I-D.ietf-taps-interface).
Messages larger than this size generate an error.  Setting this
avoids transport-layer segmentation or network-layer
fragmentation.  When used with transports running over IP version
4 the Don't Fragment bit will be set to avoid on-path IP
fragmentation (RFC8304).