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

Commentary: This updates the definition of a TAPS connection to allow a TAPS implementation to do connection pooling and multi - streaming . It removes the limitation from a TAPS connection to relate to exactly one underlying transport connection and hints that underlying transport connections my be created automatically . This is one result of the discussion around PR . 
 All comments should be addressed – ready for merge 
 Thanks for the changes ! LGTM . 
 That seems OK , can we fix : / It can also represent a pool of transport protocol instance/ to be /instances/ or whatever the plural is of a transport protocol instance ?   The arch definition of connection should add a sentence to say that there may be multiple flows ( MPTCP , MPQUIC , or even connection pooling ) below the abstraction . This was assumed but not stated . 
 May be fixed by PR 
 Solved by 
 LGTM modulo the small fixes pointed out by
Paragraph (version B):
the ability to automatically assign messages and connections to
underlaying transport connections to utilize multi-streaming and
pooled connections.
Paragraph (version A):
Connection: A Connection object represents an active transport
protocol instance that can send and/or receive Messages between
local and remote systems.  It holds state pertaining to the
underlying transport protocol instance and any ongoing data
transfer.  This represents, for example, an active connection in a
connection-oriented protocol such as TCP, or a fully-specified
5-tuple for a connectionless protocol such as UDP.
Paragraph (version B):
Connection: A Connection object represents one or more active
transport protocol instances that can send and/or receive Messages
between local and remote systems.  It holds state pertaining to
the underlying transport protocol instances and any ongoing data
transfers.  This represents, for example, an active connection in
a connection-oriented protocol such as TCP, or a fully-specified
5-tuple for a connectionless protocol such as UDP.  It can also
represent a pool of transport protocol instance, e.g., a set of
TCP and QUIC connections to equivalent endpoints, or a stream of a
multi-streaming transport protocol instance.
Draft: draft-ietf-taps-interface

Commentary: This closes issue 
 Were n't we supposed to stop making PRs and issues until March 5 ? See  's email to the TAPS list 
 sorry – I did not read list mails since yesterday morning . 
 Yes , let 's hold off on these until we move repos ! 
 We discussed the use of a " Default " preference level that restores the system default in . In addition , we should check whether we really need to fix the default values for all Selection Properties in the API document or can make some of them to be " Implementation Specific " . 
 Closed by PR 
 Looks good to me .
Paragraph (version B):
In addition, the pseudo-level "Default" can be used to reset the
property to the default level used by the implementation.  This level
will never show up when queuing the value of a preference - the
effective preference must be returned instead.
Draft: draft-ietf-taps-interface

Commentary: This implements the consensus on Transport Property Names from the Januar ' 19 Interim and the mailing list discussion about an IANA Registry for Property names . This also 
 Most nits addressed - ready to merge 
 The API suggest object , action , and event names . It should suggest property names as well . Add " code " names for each of the Selection , ( Generic ) Connection , and Message properties in the respective subsections . 
 do you still want to do this or should I do it as first preparation for the registry / property names PR ? 
 thanks for doing this ! I have lots of little nits , most of which are pretty firmly in bikeshed territory and should probably be discussed in a larger group in person . Approving so we can get the next rev out tomorrow .
Paragraph (version A):
Integer: can take positive or negative numeric values; range and
representation is implementation-dependent.
Paragraph (version B):
Allow different components of a TAPS implementation to pass
Transport Properties, e.g., between a language frontend and a
policy manager.
Paragraph (version B):
Make code of different TAPS implementations look similar.
Paragraph (version B):
Transport Property Names are hierarchically organized in the form
[<Namespace>.]<PropertyName>.
Paragraph (version B):
The Namespace part is empty for well known, generic properties,
i.e., for properties defined by an RFC which are not protocol
specific.
Paragraph (version B):
Protocol Specific Properties must use the protocol acronym as
Namespace, e.g., "tcp" for TCP specific Transport Properties.  For
IETF protocols, property names under these namespaces should be
defined in an RFC.
Paragraph (version B):
Vendor or implementation specific properties must use a a string
identifying the vendor or implementation as Namespace.
Paragraph (version B):
Integer: can take positive or negative numeric integer values;
range and representation is implementation-dependent.
Paragraph (version B):
Numeric: can take positive or negative numeric values; range and
representation is implementation-dependent.
Paragraph (version B):
Implementations may use other representations for Transport
Property Names, e.g., by providing constants or static singleton
objects, but should provide a straight-forward mapping between
their representation and the property names specified here.
Paragraph (version A):
This document has no Actions for IANA.
Paragraph (version B):
This document has no Actions for IANA.  Later versions of this
document may create IANA registries for generic transport property
names and transport property namespaces (see property-names).
Draft: draft-ietf-taps-interface

Commentary: thanks !
Paragraph (version A):
A Received event indicates the delivery of a complete Message.  It
contains two objects, the received bytes as messageData, and the
metadata and properties of the received Message as messageContext.
See {#receive-context} for details about the received context.
Paragraph (version B):
A Received event indicates the delivery of a complete Message.  It
contains two objects, the received bytes as messageData, and the
metadata and properties of the received Message as messageContext.
See receive-context for details about the received context.
Paragraph (version A):
a boolean (default true) which controls whether the "Timeout for
aborting Connection" (see {#conn-timeout}) may be changed based on
a UTO option received from the remote peer.  This boolean becomes
false when "Timeout for aborting Connection" (see {#conn-timeout})
is used.
Paragraph (version B):
a boolean (default true) which controls whether the "Timeout for
aborting Connection" (see conn-timeout) may be changed based on a
UTO option received from the remote peer.  This boolean becomes
false when "Timeout for aborting Connection" (see conn-timeout) is
used.
Draft: draft-ietf-taps-interface

Commentary: Even though all the languages we want to support do n't have convenient syntax for optional parameters to functions / methods , it would be nice to note that we intend for some parameters to not be mandatory on every call . 
 Looks good ! This approach certainly clarifies things . LGTM except for the paragraph that I commented on ; I 'd just delete that . Fine withe mit ( with some minor knit )
Paragraph (version B):
An Action takes a set of Parameters; an Event contains a set of
Parameters.  Action parameters whose names are suffixed with a
question mark are optional.
Paragraph (version B):
where messageData is the data object to send.  The optional
messageContext parameter supports per-message properties and is
described in message-props.  The optional endOfMessage parameter
supports partial sending and is described in send-partial.
Paragraph (version A):
For application-layer protocols where the Connection initiator also
sends the first message, the InitiateWithSend() action combines
Connection initiation with a first Message sent.
Draft: draft-ietf-taps-interface

Commentary: … and Lifetime . 
 Thanks all done
Paragraph (version A):
Lifetime specifies how long a particular Message can wait to be sent
to the remote endpoint before it is irrelevant and no longer needs to
be (re-)transmitted.  When a Message's Lifetime is infinite, it must
be transmitted reliably.  The type and units of Lifetime are
implementation-specific.
Paragraph (version B):
Lifetime specifies how long a particular Message can wait to be sent
to the remote endpoint before it is irrelevant and no longer needs to
be (re-)transmitted.  This is a hint to the transport system - it is
not guaranteed that a Message will not be sent when its Lifetime has
expired.
Paragraph (version B):
Setting a Message's Lifetime to infinite indicates that the
application does not wish to apply a time constraint on it, but it
does not express a need for reliable delivery; reliability is
adjustable per Message via the "Reliable Data Transfer (Message)"
property (see msg-reliable-message).  The type and units of Lifetime
are implementation-specific.
Paragraph (version A):
This property specifies that a message should be sent in such a way
that the transport protocol ensures all data is received on the other
side without corruption.  Changing the 'Reliable Data Transfer'
property on Messages is only possible if the Connection supports
reliability.  When this is not the case, changing it will generate an
error.
Paragraph (version B):
When true, this property specifies that a message should be sent in
such a way that the transport protocol ensures all data is received
on the other side without corruption.  Changing the 'Reliable Data
Transfer' property on Messages is only possible if the Connection
supports reliability.  When this is not the case, changing it will
generate an error.  Disabling this property indicates that the
transport system may disable retransmissions or other reliability
mechanisms for this particular Message, but such disabling is not
guaranteed.
Draft: draft-ietf-taps-arch

Commentary: As discussed at the January interim last week 
 This definition is exactly right , IMO.Exactly right .
Paragraph (version A):
Connection Properties: The Connection Properties are used to
configure protocol-specific options and control per-connection
behavior of the Transport System.  For example, a protocol-
specific property on the connection can express that if UDP is
used, the implementation ought to use checksums.  Note that the
presence of such a property does not require that a specific
protocol will be used.  In general, these properties do not
explicitly determine the selection of paths or protocols, but MAY
be used in this way by an implementation during connection
establishment.
Paragraph (version B):
Connection Properties: The Connection Properties are used to
configure protocol-specific options and control per-connection
behavior of the Transport System.  For example, a protocol-
specific Connection Property can express that if UDP is used, the
implementation ought to use checksums.  Note that the presence of
such a property does not require that a specific protocol will be
used.  In general, these properties do not explicitly determine
the selection of paths or protocols, but MAY be used in this way
by an implementation during connection establishment.  Connection
Properties SHOULD be specified on a Preconnection prior to
Connection establishment, but MAY be modified later.  Changes made
to Connection Properties after establishment take effect on a
best-effort basis.
Draft: draft-ietf-taps-arch

Commentary: I guess here is not nessecarily a notification required in sychronuous communication 
 Merged in master to avoid conflict , and tweaked working to remove " some times " , which felt a bit too colloquial in tone .
Paragraph (version A):
Originally, sockets presented a blocking interface for establishing
connections and transferring data.  However, most modern applications
interact with the network asynchronously.  When sockets are presented
as an asynchronous interface, they generally use 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 application
then waits for a notification to indicate when it can try again.
Paragraph (version B):
Originally, sockets presented a blocking interface for establishing
connections and transferring data.  However, most modern applications
interact with the network asynchronously.  When sockets are presented
as an asynchronous interface, they generally use 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 application
then waits and can try again later.
Draft: draft-ietf-taps-interface

Commentary: section 6.3 ( Rendezvous ) has the following line : PreconnectionBinding : = Preconnection . Resolve ( ) If i read the text correctly , I 'd propose to change this to Preconnection<:= Preconnection . Resolve ( ) 
 Agreed , not sure what a is ... 
 Agreed ; the text would need to change to compensate as well . is the on an array of preconnections ? I do n't think we have a notation for this yet ( are event params ) , but we probably should . 
 Agree with the change . are new objects derived from the initial by a process like ICE . E.g. , once the resolve call has done a STUN exchange to find the external address of a NAT you 're behind , you 'll get back an object that represents that external address . 
 lgtm
Paragraph (version A):
The Resolve() call returns a list of Preconnection Objects, that
represent the concrete addresses, local and server reflexive, on
which a Rendezvous() for the Preconnection will listen for incoming
Connections.  This list can be passed to a peer via a signalling
protocol, such as SIP RFC3261 or WebRTC RFC7478, to configure the
remote.
Paragraph (version B):
The Resolve() call returns a list of Preconnection Objects, that
represent the concrete addresses, local and server reflexive, on
which a Rendezvous() for the Preconnection will listen for incoming
Connections.  These resolved Preconnections will share all other
Properties with the Preconnection from which they are derived, though
some Properties may be made more-specific by the resolution process.
This list can be passed to a peer via a signalling protocol, such as
SIP RFC3261 or WebRTC RFC7478, to configure the remote.
Draft: draft-ietf-taps-interface

Commentary: 1 tiny fix suggested to make the text a little clearer ( because the default " complete message " delivery may need a de - framer , or the whole Connection may function as a message ) , and pointed at a possible error when delivering partial data ( it 's already written elsewhere , but the suggestion makes a sentence more correct , I believe ) . 
 Looks good , thanks ! 
 lgtm
Paragraph (version A):
The application can set a minIncompleteLength value to indicates the
smallest partial Message data size in bytes that should be delivered
in response to this Receive.  By default, this value is infinite,
which means that only complete Messages should be delivered.  If this
value is set to some smaller value, the associated receive event will
be triggered only when at least that many bytes are available, or the
Message is complete with fewer bytes, or the system needs to free up
memory.  Applications should always check the length of the data
delivered to the receive event and not assume it will be as long as
minIncompleteLength in the case of shorter complete Messages or
memory issues.
Paragraph (version B):
The application can set a minIncompleteLength value to indicates the
smallest partial Message data size in bytes that should be delivered
in response to this Receive.  By default, this value is infinite,
which means that only complete Messages should be delivered (see
receive-partial and receive-framing for more information on how this
is accomplished).  If this value is set to some smaller value, the
associated receive event will be triggered only when at least that
many bytes are available, or the Message is complete with fewer
bytes, or the system needs to free up memory.  Applications should
always check the length of the data delivered to the receive event
and not assume it will be as long as minIncompleteLength in the case
of shorter complete Messages or memory issues.
Paragraph (version A):
Multiple invocations of ReceivedPartial deliver data for the same
Message by passing the same messageContext, until the endOfMessage
flag is delivered.  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.
Draft: draft-ietf-taps-interface

Commentary: as I started reviewing issues in advance of the interim , I saw that was already mostly fixed , but I made a few editorial changes to the language there .
Paragraph (version A):
Multiple endpoint identifiers can be specified for each Local
Endpoint and RemoteEndoint.  For example, a Local Endpoint could be
configured with two interface names, or a Remote Endpoint could be
specified via both IPv4 and IPv6 addresses.  These multiple
identifiers refer to the same transport endpoint.
Paragraph (version A):
The transport services API will resolve names internally, when the
Initiate(), Listen(), or Rendezvous() method is called establish a
Connection.  The API does not need the application to resolve names,
and premature name resolution can damage performance by limiting the
scope for alternate path discovery during Connection establishment.
The Resolve() method is, however, provided to resolve a Local
Endpoint or a Remote Endpoint in cases where this is required, for
example with some Network Address Translator (NAT) traversal
protocols (see rendezvous).
Paragraph (version B):
Multiple endpoint identifiers can be specified for each Local
Endpoint and Remote Endpoint.  For example, a Local Endpoint could be
configured with two interface names, or a Remote Endpoint could be
specified via both IPv4 and IPv6 addresses.  These multiple
identifiers refer to the same transport endpoint.
Paragraph (version B):
The transport services API resolves names internally, when the
Initiate(), Listen(), or Rendezvous() method is called 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 Resolve() action on Preconnection can be used by the application
to force early binding when required, for example with some Network
Address Translator (NAT) traversal protocols (see rendezvous).
Draft: draft-ietf-taps-interface

Commentary: And add an early data   . 
 I 'll dig up relevant discussions from the TLS WG . 
 See , e.g. : 
 Looks like a good candidate for a read - only recv property … 
 Are n't all receives read - only ? 
 Looks good - minor nits noted in lgtmMuch better I think !
Paragraph (version A):
As with sending, the type of the Message to be passed is dependent on
the implementation, and on the constraints on the Protocol Stacks
implied by the Connection's transport parameters.  The Message may
also contain metadata from protocols in the Protocol Stack; which
metadata is available is Protocol Stack dependent.  In particular,
when this information is available, the value of the Explicit
Congestion Notification (ECN) field is contained in such metadata.
This information can be used for logging and debugging purposes, and
for building applications which need access to information about the
transport internals for their own operation.
Paragraph (version B):
As with sending, the type of the Message to be passed is dependent on
the implementation, and on the constraints on the Protocol Stacks
implied by the Connection's transport parameters.
Paragraph (version B):
When available, Message metadata carries the value of the Explicit
Congestion Notification (ECN) field.  This information can be used
for logging and debugging purposes, and for building applications
which need access to information about the transport internals for
their own operation.
Paragraph (version B):
In some cases it may be valuable to know whether data was read as
part of early data streams.  This is useful if applications need to
treat early data separately, e.g., if early data has different
security properties than data sent after connection establishment.
In the case of TLS 1.3, client early data can be replayed maliciously
(see I-D.ietf-tls-tls13).  Thus, receivers may wish to perform
additional checks for early data to ensure it is idempotent or not
replayed.  If TLS 1.3 is available and the recipient Message was sent
as part of early data, the corresponding metadata carries a flag
indicating as such.  If early data is enabled, applications should
check this metadata field for Messages received during connection
establishment and respond accordingly.
Draft: draft-ietf-taps-interface

Commentary: Make sure all the examples in the API and interface drafts use constants agnostic to argument type and syntax . From   : On 2 May 2018 , at 03:07 ,   < : 
 will fix this when it lands 
 Addressed by . 
 Security properties should be synchronized with ( the next rev of ) 
 Addressed by . 
 lgtm
Paragraph (version A):
Session cache: Used to tune cache capacity, lifetime, re-use, and
eviction policies, e.g., LRU or FIFO.
Paragraph (version A):
Pre-shared keying material: Used to install pre-shared keying
material established out-of-band.  Each pre-shared keying material
is associated with some identity that typically identifies its use
or has some protocol-specific meaning to the Remote Endpoint.
Paragraph (version B):
Most security parameters, e.g., TLS ciphersuites, local identity and
private key, etc., may be configured statically.  Others are
dynamically configured during connection establishment.  Thus, we
partition security parameters and callbacks based on their place in
the lifetime of connection establishment.  Similar to transport
parameters, both parameters and callbacks are inherited during
cloning (see groups).
Paragraph (version B):
Session cache management: Used to tune cache capacity, lifetime,
re-use, and eviction policies, e.g., LRU or FIFO.  Constants and
policies for these interfaces are implementation-specific.
Paragraph (version B):
Pre-Shared Key import: Used to install pre-shared keying material
established out-of-band.  Each pre-shared keying material is
associated with some identity that typically identifies its use or
has some protocol-specific meaning to the Remote Endpoint.
Paragraph (version A):
Like transport parameters, security parameters are inherited during
cloning (see groups).