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

Commentary: My first try to make a PR from the web interface . Maybe this compiles without problems ? 
 Aha , the error appears even when doing it over the web interface . 
 I think I am missing something ... how do endpoints know a route exists ( is present ) ? My thinking from NEAT was that endpoints only knew this was established when there was some " confirmation " from the remote endpoint . Do you mean something else ? 
 this is for UDP , nothing is sent to the other end until the application sends data . it was the same in neat , our open call in neat just returned immediately for UDP . 
 True - for UDP , as you say , you basically know the Interface is up ( and often not much more ) , but the words " established " sounds more like what happened when you get the first packet back ... Maybe I could live with this , but it does n't immediately inspire the right sense ... 
 Yes , " connectivity is established " is not good at all , this is why I said the proposed update made it worse :) Or you mean that " local port reservations has been established " also triggers the wrong idea because of " established " ? How about " ... any necessary state like local port reservations is available / has been allocated . " Or just remove that part all together . 
 In Sec 4.5 of taps - impl : " An implementation should consider such a protocol stack to be established as soon as a local route to the peer endpoint is confirmed . " What does this mean for an unconnected protocol ? That there is an entry in the route table , or that it 's received a packet ? 
 Good catch : This appears to be rough sentence . The term " confirmed " occurs only once , and a " local route " is something quite different to what is intended ! We do talk about establishing connectivity with a remote endpoint ... maybe that might work ?
Paragraph (version A):
While protocols that use an explicit handshake to validate a
Connection to a peer can be used for racing multiple establishment
attempts in parallel, "unconnected" protocols such as raw UDP do not
offer a way to validate the presence of a peer or the usability of a
Connection without application feedback.  An implementation should
consider such a protocol stack to be established as soon as a local
route to the peer endpoint is confirmed.
Paragraph (version B):
While protocols that use an explicit handshake to validate a
Connection to a peer can be used for racing multiple establishment
attempts in parallel, "unconnected" protocols such as raw UDP do not
offer a way to validate the presence of a peer or the usability of a
Connection without application feedback.  An implementation should
consider such a protocol stack to be established as soon as the
Transport Services system has selected a path on which to send data.
Draft: draft-ietf-taps-impl

Commentary: Thanks  ! 
 Looks good to me .
Paragraph (version A):
To avoid allocating resources, it is important that such cases fail
as early as possible, e.g., to endpoint resolution, only to find out
later that there is no protocol that satisfies the requirements.
Paragraph (version B):
To avoid allocating resources, it is important that such cases fail
as early as possible, e.g., prior to endpoint resolution, only to
find out later that there is no protocol that satisfies the
requirements.
Paragraph (version A):
In case of Pooled Connections pooled-connections, the transport
system may add connections over new paths or different protocols to
the pool if permissible based on the multipath policy and Selection
Properties.  In case a previously used path becomes unavailable, the
transport system may disconnect all connections that require this
path, but should not disconnect the pooled connection object exposed
to the application.  The strategy how is implementation-specific, but
should be consistent with the behavior of multipath transports.
Paragraph (version B):
In case of Pooled Connections pooled-connections, the transport
system may add connections over new paths or different protocols to
the pool if permissible based on the multipath policy and Selection
Properties.  In case a previously used path becomes unavailable, the
transport system may disconnect all connections that require this
path, but should not disconnect the pooled connection object exposed
to the application.  The strategy to do so is implementation-
specific, but should be consistent with the behavior of multipath
transports.
Paragraph (version A):
API mappings for MPTCP are identical to TCP.  MPTCP adds support for
multipath properties, such as "Multi-Paths Transport" and "Policy for
using Multi-Path Transports".
Paragraph (version B):
API mappings for MPTCP are identical to TCP.  MPTCP adds support for
multipath properties, such as "Multi-Path Transport" and "Policy for
using Multi-Path Transports".
Draft: draft-ietf-taps-interface

Commentary: In § 5.3.1 . 
 This is missing pseudo - code .
Paragraph (version A):
Session cache management: Used to tune cache capacity, lifetime,
re-use, and eviction policies, e.g., LRU or FIFO.
Paragraph (version B):
Session cache management: Used to tune session cache capacity,
lifetime, and other policies.
Draft: draft-ietf-taps-interface

Commentary: says : But it appears the Connection object is still required to call Send , so what value does this provide ? I.e. , how are you supposed to use replyMessageContext from the example ? 
 I agree - it seems to me now that this really adds no value . What am I missing ? I 'm assigning because he was among the first to propose this ... maybe he can explain 
 Ping :) 
 Interim : We will remove all " reply / replies " from the API doc .
Paragraph (version A):
Message Contexts can also be used to send messages in reply to other
messages, see send-replies for details.
Paragraph (version A):
When a message is sent in response to a message received, the
application can use the Message Context of the received Message to
construct a Message Context for the reply.
Paragraph (version A):
By using the "replyMessageContext", the transport system is informed
that the message to be sent is a response and can map the response to
the same underlying transport connection or the stream from which the
request was received.  The concept of Message Contexts is described
in msg-ctx.
Draft: draft-ietf-taps-interface

Commentary: … and move the group limit connection property to the right place ( it was misplaced ) . Note that section 8.2.7 ( " Priority in TAPS " ) already clarifies that a Connection Priority choice does n't guarantee a certain outcome ; this just adds another sentence in the paragraph describing the Connection property to make it clearer ( less easy to miss ) . 
 Looks ready to merge to me .
Paragraph (version A):
This Property is a non-negative integer representing the relative
inverse priority (i.e., a lower value reflects a higher priority) of
this Connection relative to other Connections in the same Connection
Group.  It has no effect on Connections not part of a Connection
Group.  As noted in groups, this property is not entangled when
Connections are cloned, i.e., changing the Priority on one Connection
in a Connection Group does not change it on the other Connections in
the same Connection Group.  See priority-in-taps.
Paragraph (version B):
This Property is a non-negative integer representing the relative
inverse priority (i.e., a lower value reflects a higher priority) of
this Connection relative to other Connections in the same Connection
Group.  It has no effect on Connections not part of a Connection
Group.  As noted in groups, this property is not entangled when
Connections are cloned, i.e., changing the Priority on one Connection
in a Connection Group does not change it on the other Connections in
the same Connection Group.  No guarantees of a specific behavior
regarding Connection Priority are given; a transport system may
ignore this property.  See priority-in-taps for more details.
Paragraph (version B):
This property controls the number of Connections that can be accepted
from a peer as new members of the Connection's group.  Similar to
SetNewConnectionLimit(), this limits the number of ConnectionReceived
Events that will occur, but constrained to the group of the
Connection associated with this property.  For a multi-streaming
transport, this limits the number of allowed streams.
Paragraph (version A):
This property controls the number of Connections that may arrive from
a peer as new members of the Connection's group.  Similar to
SetNewConnectionLimit(), this limits the number of ConnectionReceived
Events that will occur, but constrained to the group of the
Connection associated with this property.  In case of a multi-
streaming transport, this takes the role of a limit on the number of
allowed streams.
Draft: draft-ietf-taps-interface

Commentary: These are the minor typos that did not come through in the merged text .
Paragraph (version A):
This property specifies whether the application would like the
Connection to send keep-alive packets or not.  Note that if a
Connection determines that keep-alive packets are being sent, the
applicaton should itself avoid generating additional keep alive
messages.  Note that when supported, the system will use the default
periodic for generation of the keep alive-packets.  (See also keep-
alive-timeout).
Paragraph (version B):
This property specifies whether the application would like the
Connection to send keep-alive packets or not.  Note that if a
Connection determines that keep-alive packets are being sent, the
applicaton should itself avoid generating additional keep alive
messages.  Note that when supported, the system will use the default
period for generation of the keep alive-packets.  (See also keep-
alive-timeout).
Paragraph (version A):
A transport system can request a protocol that supports sending keep
alive packets keep-alive.  This property specifies the maximum time
an idle connection (one for which no transport packets have been
sent) should wait before the Local Endpoint sends a keep-alive packet
to the Remote Endpoint.  Adjusting this Property will only take
effect when the underlying stack supports sending keep-alive packet.
Guidance on setting this value for datagram transports is provided in
RFC8085.  The special value "Default" means that this timeout will
use the default for the selected transport.  A value greater than
conn-timeout will disable sending of keep-alive packets.
Paragraph (version B):
A transport system can request a protocol that supports sending keep
alive packets keep-alive.  This property specifies the maximum time
an idle connection (one for which no transport packets have been
sent) should wait before the Local Endpoint sends a keep-alive packet
to the Remote Endpoint.  Adjusting this Property will only take
effect when the underlying stack supports sending keep-alive packets.
Guidance on setting this value for datagram transports is provided in
RFC8085.  The special value "Default" means that this timeout will
use the default for the selected transport.  A value greater than the
connection timeout (conn-timeout) will disable the sending of keep-
alive packets.
Draft: draft-ietf-taps-interface

Commentary: says : What happens if a ReceivedPartial event is dispatched on an unreliably connection , but the rest of the message never shows up ? Is it the case that another call to Receive will result in two events being sent : Received ( or ReceivedPartial ) for the new message , and a ReceiveError for the original message ? Or can two messages effectively be interleaved and delivered in whatever order the constituent packets arrive ? 
 Could you elaborate on the error case that 's on your mind ? Because it 's unclear to me - I would say that ordering obviously needs to be preserved within a message , while inter - message ordering is a different issue ( controlled by the msgOrdered Message Parameter ) . How is this not clear from saying that delivering discontiguous partial Messages is not supported ? 
 Let 's say you send the following : M1 M2 M3    where M = M1.M2.M3 is one message and N = N1.N2.N3 is another message . The receiver subsequently gets : M1 N1 N2 N3 My reading of the draft is that the receiver will see ReceivedPartial < M1ReceivedPartial < N1ReceivedPartial < N2Received < N3If M2 and M3 subsequently arrive , it sounds like the receiver will never get ReceivedPartial < M2or Received < M3because " this event does not support delivering discontiguous partial Messages . " But what makes the receiving TAPS logic decide not to wait for  or M3 and to start delivering N ? 
 This is not how I would have interpreted the sentence . It talks about the message itself being discontiguous - so , e.g. , delivering M1 followed by M3 would never happen . I do n't see a reason why a different message could n't be delivered , in pieces or not , after a ReceivedPartial call - every receive call comes with a message context , so the messages can be separated . I can try to make this clearer , maybe by adding an example like yours here to the draft ....
Paragraph (version A):
Multiple invocations of ReceivedPartial deliver data for the same
Message by passing the same MessageContext, until the endOfMessage
flag is delivered or a ReceiveError occurs.  All partial blocks of a
single Message are delivered in order without gaps.  This event does
not support delivering discontiguous partial Messages.
Paragraph (version B):
Multiple invocations of ReceivedPartial deliver data for the same
Message by passing the same MessageContext, until the endOfMessage
flag is delivered or a ReceiveError occurs.  All partial blocks of a
single Message are delivered in order without gaps.  This event does
not support delivering discontiguous partial Messages.  If, for
example, Message A is divided into three pieces (A1, A2, A3) and
Message B is divided into three pieces (B1, B2, B3), the
ReceivedPartial may deliver them in a sequence like this: A1, B1, B2,
A2, A3, B3, because the messageContext allows the application to
identify the pieces as belonging to Message A and B, respectively.
However, a sequence like: A1, A3 will never occur.
Draft: draft-ietf-taps-interface

Commentary: per consensus at the Sep 11 interim . 
 This appears " to do exactly as it says on the tin " , and removes the text . Looks good to me .
Paragraph (version A):
This property specifies whether an application considers it useful to
be informed in case sent data was retransmitted more often than a
certain threshold (see conn-excss-retransmit for configuration of
this threshold).
Paragraph (version A):
This property specifies the number of retransmissions required to
cause the application to be notified of "Excessive Retransmissions".
Paragraph (version A):
This event notifies the application of excessive retransmissions,
based on a configured threshold (see conn-excss-retransmit).  This
will only happen if the underlying protocol stack supports
reliability and, with it, such notifications.
Draft: draft-ietf-taps-interface

Commentary: I would reword this text in § 5.1 : such that the tradeoff is listed in a ( new ) privacy considerations section , leaving the description of the reduced connection setup latency in early binding here as a functional justification . 
 LGTM ( note : accept 1 nit fix before pressing Merge )
Paragraph (version A):
The transport services API resolves names internally, when the
Initiate(), Listen(), or Rendezvous() method is called to establish a
Connection.  The API explicitly does not require the application to
resolve names, though there is a tradeoff between early and late
binding of addresses to names.  Early binding allows the API
implementation to reduce connection setup latency, at the cost of
potentially limited scope for alternate path discovery during
Connection establishment, as well as potential additional information
leakage about application interest when used with a resolution method
(such as DNS without TLS) which does not protect query
confidentiality.
Paragraph (version B):
The transport services API resolves names internally, when the
Initiate(), Listen(), or Rendezvous() method is called to establish a
Connection.  Privacy considerations for the timing of this resolution
are given in privacy-security.
Paragraph (version B):
The interface explicitly does not require the application to resolve
names, though there is a tradeoff between early and late binding of
addresses to names.  Early binding allows the API implementation to
reduce connection setup latency, at the cost of potentially limited
scope for alternate path discovery during Connection establishment,
as well as potential additional information leakage about application
interest when used with a resolution method (such as DNS without TLS)
which does not protect query confidentiality.
Draft: draft-ietf-taps-interface

Commentary: I found the relationship between streams and connections to be extremely murky throughout the draft , and left it not really sure how I would control a streamed transport . Section 6.4 hints suggests that opening additional streams is an alternative implementation of Clone ( ) for transports that can do so . Does this imply that if the peer stream limit does not allow new streams , the transport should open a connection instead ? How does SetNewConnectionLimit ( ) in Sec 6.2 relate to streamed transport -- are there two levels of listener : a stream listener and a connection listener ? How would opening " stream listeners " relate to the maximum number of streams the peer could open ( i.e. do I have to call listen ( ) 8 times to allow the client to open 8 streams ) ? Or are there no stream listeners and these " connections " just sort of appear ? Skimming the -impl draft , I can see there 's some text here but it is not fitting together for me . There are at least three streamed transports and it would be helpful to explain how the API conceptualizes this , perhaps in a new section . 
 To clarify , Listen ( ) is called once and keeps receiving streams within the NewConnectionLimit . The main thing to clarify is how the NewConnectionLimit applies to streams of a multiplexed transport . We could look at having a limit of connections per endpoint in a group from a listener . 
 Add a property to section 7.1 . 
 Also make sure to have an early section being very explicit about the overall interaction model . 
 In section 4.1 , we could add an example for explicit group management via clone , etc . 
  , I will never self - assign an issue again before its discussion :-) but it 's ok ... I 'll do it
Paragraph (version A):
This is an example of how an application might listen for incoming
Connections using the Transport Services Interface, receive a
request, and send a response.
Paragraph (version A):
This is an example of how an application might connect to a remote
application using the Transport Services Interface, send a request,
and receive a response.
Paragraph (version B):
This is an example of how an application might listen for incoming
Connections using the Transport Services Interface, and receive a
request, and send a response.
Paragraph (version B):
This is an example of how an application might open two Connections
to a remote application using the Transport Services Interface, and
send a request as well as receive a response on each of them.
Paragraph (version B):
This property controls the number of Connections that may arrive from
a peer as new members of the Connection's group.  Similar to
SetNewConnectionLimit(), this limits the number of ConnectionReceived
Events that will occur, but constrained to the group of the
Connection associated with this property.  In case of a multi-
streaming transport, this takes the role of a limit on the number of
allowed streams.
Draft: draft-ietf-taps-interface

Commentary: I should have said : I approve this , modulo the changes requested by 
 Thanks for incorporating my suggested changes . I think this can be merged now .
Paragraph (version B):
Tuple: An ordered grouping of multiple value types.  In this this
document, it is written as a list in brackets, e.g.,
"(Enumeration, Preference)" The composition of types and their
order depends on the property and is fixed for the property.  The
actual representation is implementation-dependent.
Paragraph (version B):
Collection: An unordered grouping of one or more values of the
same type.  The actual representation, e.g. as a set or an array,
is implementation-dependent.
Paragraph (version A):
Supported algorithms: Used to restrict what parameters are used by
underlying transport security protocols.  When not specified,
these algorithms should use known and safe defaults for the
system.  Parameters include: ciphersuites, supported groups, and
signature algorithms.
Paragraph (version B):
Supported algorithms: Used to restrict what parameters are used by
underlying transport security protocols.  When not specified,
these algorithms should use known and safe defaults for the
system.  Parameters include: ciphersuites, supported groups, and
signature algorithms.  These parameters take a collection of
supported algorithms as parameter.
Draft: draft-ietf-taps-interface

Commentary: Responds to issue . 
 Interim : to be turned into a single knob 
 Merging because GitHub UX is confusing . to go over these comments again and add a second PR if necessary . 
 sec 7.1.4 It would be helpful to clarify the relevance of control vs application data in the idle timeout -- for various reasons , the connection could stay alive regardless of how active the connection is ( in fact , perhaps " keepalive " is a generally useful notion that can be exposed in the API ? ) 
 The timeout in 7.1.4 should include control data ( like ACKs , etc ) . This should be clarified : " data " in this context is any transport data , not just application data . We can have a simple boolean to enable keepalives as well . 
 Aha , this should have been closed by PR , but " responds to issue " was n't auto - detected by git . Manually closing now .
Paragraph (version B):
This property specifies whether the application would like the
Connection to send keep-alive packets or not.  Note that if a
Connection determines that keep-alive packets are being sent, the
applicaton should itself avoid generating additional keep alive
messages.  Note that when supported, the system will use the default
periodic for generation of the keep alive-packets.  (See also keep-
alive-timeout).
Paragraph (version A):
This property specifies how long to wait before deciding that a
Connection has failed when trying to reliably deliver data to the
destination.  Adjusting this Property will only take effect when the
underlying stack supports reliability.  The special value "Disabled"
means that this timeout is not scheduled to happen.  This can be a
valid choice with unreliable data transfer (e.g., when UDP is the
underlying transport protocol).
Paragraph (version B):
This property specifies how long to wait before deciding that an
active Connection has failed when trying to reliably deliver data to
the Remote Endpoint.  Adjusting this Property will only take effect
when the underlying stack supports reliability.  The special value
"Disabled" means that this timeout is not scheduled to happen.
Paragraph (version B):
A transport system can request a protocol that supports sending keep
alive packets keep-alive.  This property specifies the maximum time
an idle connection (one for which no transport packets have been
sent) should wait before the Local Endpoint sends a keep-alive packet
to the Remote Endpoint.  Adjusting this Property will only take
effect when the underlying stack supports sending keep-alive packet.
Guidance on setting this value for datagram transports is provided in
RFC8085.  The special value "Default" means that this timeout will
use the default for the selected transport.  A value greater than
conn-timeout will disable sending of keep-alive packets.