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

Commentary: Generalise the discussion of Rendezvous in arch . 
 Rendezvous : TCP simultaneous open is one type of rendezvous , but only giving this as an example makes it seems more narrowly scoped that I envisaged . For example , I 'd expect Rendezvous could perform an ICE exchange it STUN candidates were passed as Remote Endpoints . Should this description be generalised ?
Paragraph (version A):
Rendezvous: The action of establishing a peer-to-peer connection
with a Remote Endpoint.  It simultaneously attempts to initiate a
connection to a Remote Endpoint whilst listening for an incoming
connection from that endpoint.  This corresponds, for example, to
a TCP simultaneous open RFC0793.  The process of identifying
options for the connection, such as resolution of the Remote
Endpoint, occurs during the Rendezvous call.  As with Listeners,
the set of local paths and endpoints is contrained by Selection
Properties.  If successful, the Rendezvous call returns a
Connection object to represent the established peer-to-peer
connection.
Paragraph (version B):
Rendezvous: The action of establishing a peer-to-peer connection
with a Remote Endpoint.  It simultaneously attempts to initiate a
connection to a Remote Endpoint while listening for an incoming
connection from that endpoint.  The process of identifying options
for the connection, such as resolution of the Remote Endpoint,
occurs during the Rendezvous call.  As with Listeners, the set of
local paths and endpoints is constrained by Selection Properties.
If successful, the Rendezvous call returns a Connection object to
represent the established peer-to-peer connection.  The processes
by which connections are initiated during a Rendezvous action will
depend on the set of Local and Remote Endpoints configured on the
Preconnection.  For example, if the Local and Remote Endpoints are
TCP host candidates, then a TCP simultaneous open RFC0793 will be
performed.  However, if the set of Local Endpoints includes server
reflexive candidates, such as those provided by STUN, a Rendezvous
action will race candidates in the style of the ICE algorithm
RFC8445 to perform NAT binding discovery and initiate a peer-to-
peer connection.
Draft: draft-ietf-taps-arch

Commentary: Completes 
 Close : The way this is written suggests that the API does n't support half closed connections . That may be reasonable , but it 's a limitation . If intended , can it be made explicit . 
 This is perfect IMO!lgtm , thanks !
Paragraph (version A):
Close: The action an application takes on a Connection to indicate
that it no longer intends to send data, is no longer willing to
receive data, and that the protocol SHOULD signal this state to
the remote system if the transport protocol allows this.
Draft: draft-ietf-taps-interface

Commentary: This also addresses two inline [ EDITOR 's NOTE ] items . One was about the per - message override capacity profile being inconsistent with the other one ; this was solved by removing details , such that the other one defines the possible choices . Another was about selection vs. connection properties , with broken text . There was no need to add the references as the editor 's note says , I thought . 
 this LGTM , thanks !
Paragraph (version A):
This enumerated property specifies the application's preferred
tradeoffs for sending this Message; it is a per-Message override of
the Capacity Profile protocol and path selection property (see prop-
cap-profile).
Paragraph (version A):
No special optimizations of the tradeoff between delay, delay
variation, and bandwidth efficiency should be made when sending
this message.
Paragraph (version A):
Response time (latency) should be optimized at the expense of
efficiently using the available capacity when sending this
message.  This can be used by the system to disable the coalescing
of multiple small Messages into larger packets (Nagle's
algorithm); to prefer immediate acknowledgment from the peer
endpoint when supported by the underlying transport; to signal a
preference for lower-latency, higher-loss treatment; and so on.
Paragraph (version B):
This enumerated property specifies the application's preferred
tradeoffs for sending this Message; it is a per-Message override of
the Capacity Profile connection property (see prop-cap-profile).
Paragraph (version B):
Note that many protocol properties have a corresponding selection
property, which prefers protocols providing a supporting transport
feature.
Draft: draft-ietf-taps-arch

Commentary: This is a lightweight proposal to address . 
 Especially in section 2 , we should make it explicit that resolution is blended with connection establishment in a way that it is not in traditional sockets . 
 Yip - I like
Paragraph (version A):
The Transport Services architecture maintains this general model of
interaction, but aims to both modernize the API surface exposed for
transport protocols and enrich the capabilities of the transport
system implementation.
Paragraph (version B):
Sockets are bound directly to transport-layer and network-layer
addresses, obtained via a separate resolution step, usually
performed by a system-provided stub resolver.
Paragraph (version B):
The Transport Services architecture evolves this general model of
interaction, aiming to both modernize the API surface presented to
applications by the transport layer and enrich the capabilities of
the transport system implementation.  It combines interfaces for
multiple interaction patterns into a unified whole.  By combining
name resolution with connection establishment and data transfer in a
single API, it allows for more flexible implementations to provide
path and transport protocol agility on the application's behalf.
Draft: draft-ietf-taps-interface

Commentary: Maybe add the ASN source address ( set source address ) , source filter ( add remote addresses ) ? Maybe also add that for sending , you specify the group as remote and the socket becomes write - only ? Should we require specifying direction ? This would be slightly harder to use , but future proof in case someone implements reliable ASN on TAPS … 
 We need unidirectional connections . You know , for multicast . And ICN . And unidirectional streaming protocols . 
 This is a dup of , which has more discussion 
 I am re - opening this ticket as only dealt with unidirectional streams in unicast context ( with PR ): Current status : The current model for unidirectional streams supports half - closed connections and QUIC style unidirectional streams so far . We do n't know yet whether it is sufficient to have canread / canwrite property on the connection level to model unidirectional connections We do n't have pre - connection methods to create multicast sessions yet 
 there 's a selection property for this , tagged discuss , which we have n't discussed yet . I 'm moving this down to the appendix as part of my restructuring in my work on 
 If help is still wanted here , I 'm maybe up for an attempt or 2 at adding multicast support . Has there been some prior discussion I can review about rough ideas on pre - connection methods for multicast sessions , or should I just try making something up ? 
 lgtm
Paragraph (version B):
Specifying a multicast group address on the Local Endpoint will
indicate to the transport system that the resulting connection will
be used to receive multicast messages.  The Remote Endpoint can be
used to filter by specific senders.  This will restrict the
application to establishing the Preconnection by calling Listen().
The accepted Connections are receive-only.
Paragraph (version B):
Similarly, specifying a multicast group address on the Remote
Endpoint will indicate that the resulting connection will be used to
send multicast messages.
Draft: draft-ietf-taps-interface

Commentary: It should be made more clear in what order queued receives are considered , i.e. what happens if an application calls Receive(minIncompleteLength=20 ) , then calls Receive(minIncompleteLength=1 ) . What now happens if e.g. 10 bytes of data arrive ? Will the second receive only be considered after the first has been fulfilled ? 
 It would seem natural to me that enqueuing is what it is - i.e. , saying once " I can receive blocks of at least 20 bytes " can not be undone . So , if the sequence is : 1 ) Receive(minIncompleteLength=20 ) 2 ) Receive(minIncompleteLength=1 ) 3 ) 10 bytes arrive ... then the first Receive call should be the one that matters , and the 10 bytes would have to wait until another 10 bytes arrive before the second Receive call can be processed . I think that should add a clarifying sentence because his implementation probably already does it in one way or another . 
 Perhaps its not such a big issue , but I think this would take the option away from application developers to have an OR option for receives . For example , an application would have no way to say that it wants to receive either something with minIncompleteLength 100 or MaxLength 10 . I also think there might be some confusion when it comes to requiring message ordering . For example : calls Receive(maxLength=10 ) calls Receive(maxLength=20 ) with length 20 arrives with length 10 arrives get received callback for message with length 10 get received callback for message with length 20 For the application it now seems that the message with length 10 arrived before the one with length 20 even though that is not the case .
Paragraph (version A):
Note that maxLength does not guarantee that the application will
receive that many bytes if they are available; the interface may
return ReceivedPartial events with less data than maxLength according
to implementation constraints.
Paragraph (version B):
Note that maxLength does not guarantee that the application will
receive that many bytes if they are available; the interface may
return ReceivedPartial events with less data than maxLength according
to implementation constraints.  Note also that maxLength and
minIncompleteLength are intended only to manage buffering, and are
not interpreted as a reciever preference for message reordering.
Draft: draft-ietf-taps-arch

Commentary: Address 
 meh okay if we must . :P nah this is great , already merged it . Fine - works
Paragraph (version A):
Listen: The action of marking a Listener as willing to accept
incoming Connections.  The Listener will then create Connection
objects as incoming connections are accepted (events).
Paragraph (version B):
Listen: The action of marking a Listener as willing to accept
incoming Connections.  The Listener will then create Connection
objects as incoming connections are accepted (events).  Listeners
by default register with multiple paths and local endpoints,
unless constrained by Selection Properties.  Connections can be
accepted on any of the available paths or endpoints.
Paragraph (version A):
Rendezvous: The action of establishing a peer-to-peer connection
with a Remote Endpoint.  It simultaneously attempts to initiate a
connection to a Remote Endpoint whilst listening for an incoming
connection from that endpoint.  This corresponds, for example, to
a TCP simultaneous open RFC0793.  The process of identifying
options for the connection, such as resolution of the Remote
Endpoint, occurs during the Rendezvous call.  If successful, the
rendezvous call returns a Connection object to represent the
established peer-to-peer connection.
Paragraph (version B):
Rendezvous: The action of establishing a peer-to-peer connection
with a Remote Endpoint.  It simultaneously attempts to initiate a
connection to a Remote Endpoint whilst listening for an incoming
connection from that endpoint.  This corresponds, for example, to
a TCP simultaneous open RFC0793.  The process of identifying
options for the connection, such as resolution of the Remote
Endpoint, occurs during the Rendezvous call.  As with Listeners,
the set of local paths and endpoints is contrained by Selection
Properties.  If successful, the Rendezvous call returns a
Connection object to represent the established peer-to-peer
connection.
Draft: draft-ietf-taps-interface

Commentary: Address 
 API should allow a preconnection property to specify if a private ( IPv6 ) address is preferred . Outbound connections should prefer this . Listeners should avoid this . 
 Thank you ! I was really missing this one .LGTM !
Paragraph (version B):
Prefer the use of stable local addresses for Listeners and
Rendezvous Connections, and prefer the use of temporary addresses
for other Connections.
Draft: draft-ietf-taps-interface

Commentary: Complete 
 Thanks  ! I think this looks good The meaning of Interactive is a bit fuzzy , but not sure if we can solve that .
Paragraph (version A):
This property specifies whether an application considers it useful to
transfer data across multiple paths between the same end hosts.
Generally, in most cases, this will improve performance (e.g.,
achieve greater throughput).  One possible side-effect is increased
jitter, which may be problematic for delay-sensitive applications.
The recommended default is to Ignore this option.
Paragraph (version B):
The default is Disabled.  The other enumeration values are all
interpreted as preferences.
Draft: draft-ietf-taps-arch

Commentary: Just two small nits , otherwise looks good !
Paragraph (version A):
All interaction with a Transport Services system is expected to be
asynchronous, and use an event-driven model unlike sockets events.
For example, if the application wants to read, its call to read will
not fail, but will deliver an event containing the received data once
it is available.
Paragraph (version B):
In contrast to sockets, all interaction with a Transport Services
system is expected to be asynchronous, and use an event-driven model
(see events).  For example, if the application wants to read, its
call to read will not complete immediately, but will deliver an event
containing the received data once it is available.  Error handling is
also asynchronous; a failure to send results in an asynchronous send
error as an event.
Paragraph (version B):
Separate from events, callbacks are also provided for asynchronous
interactions with the API not directly related to events on the
network or network interfaces.
Paragraph (version A):
Pre-Establishment (preestablishment) encompasses the properties
that an application can pass to describe its intent, requirements,
prohibitions, and preferences for its networking operations.  For
any system that provides generic Transport Services, these
properties SHOULD be defined to apply to multiple transport
protocols.  Properties specified during Pre-Establishment can have
a large impact on the rest of the interface: they modify how
establishment occurs, they influence the expectations around data
transfer, and they determine the set of events that will be
supported.
Paragraph (version B):
Pre-Establishment (preestablishment) encompasses the properties
that an application can pass to describe its intent, requirements,
prohibitions, and preferences for its networking operations.  For
any system that provides generic Transport Services, these
properties SHOULD apply to multiple transport protocols.
Properties specified during Pre-Establishment can have a large
impact on the rest of the interface: they modify how establishment
occurs, they influence the expectations around data transfer, and
they determine the set of events that will be supported.
Draft: draft-ietf-taps-interface

Commentary: Thanks for the fixes !
Paragraph (version A):
Vendor or implementation specific properties must use a a string
identifying the vendor or implementation as Namespace.
Paragraph (version B):
Vendor or implementation specific properties must use a string
identifying the vendor or implementation as Namespace.
Paragraph (version A):
Message Properties: Message Properties can be used to annotate
specific Messages.  These properties might only apply to how
Message is sent (such as how the transport will treat
prioritization and reliability), but can also include properties
that specific protocols encode and communicate to the Remote
Endpoint.  Message Properties MAY be set on a Preconnection to
define defaults properties for sending.  When receiving Messages,
Message Properties can contain per-protocol properties for
properties that are sent between the endpoints.
Paragraph (version B):
Message Properties: Message Properties can be used to annotate
specific Messages.  These properties might only apply to how
Message is sent (such as how the transport will treat
prioritization and reliability), but can also include properties
that specific protocols encode and communicate to the Remote
Endpoint.  Message Properties MAY be set on a Preconnection to
define default properties for sending.  When receiving Messages,
Message Properties can contain per-protocol properties for
properties that are sent between the endpoints.
Paragraph (version A):
This section provides the top-level categories of events events that
can be delivered to an application.  This list is not exhaustive.
Paragraph (version B):
This section provides the top-level categories of events that can be
delivered to an application.  This list is not exhaustive.
Paragraph (version A):
Both stacks MUST offer the transport services that are required by
the application.  For example, if an application specifies that it
requires reliable transmission of data, then a Protocol Stack
using UDP without any reliability layer on top would not be
allowed to replace a Protocol Stack using TCP.  However, if the
application does not require reliability, then a Protocol Stack
that adds reliability could be regarded as an equivalent Protocol
Stack as long providing this would not conflict with any other
application-requested properties.
Paragraph (version B):
Both stacks MUST offer the transport services that are required by
the application.  For example, if an application specifies that it
requires reliable transmission of data, then a Protocol Stack
using UDP without any reliability layer on top would not be
allowed to replace a Protocol Stack using TCP.  However, if the
application does not require reliability, then a Protocol Stack
that adds reliability could be regarded as an equivalent Protocol
Stack as long as providing this would not conflict with any other
application-requested properties.
Draft: draft-ietf-taps-arch

Commentary: Based on discussion with rearrange things to put a proper document overview in the intro , and split out the API Model discussion into its own section outside of the introduction . 
 LGTM ( modulo one nit)Thank you to do this - really improves the structure .
Paragraph (version B):
model describes how the API model of Transport Services differs
from traditional socket-based APIs.  Specifically, it offers
asynchronous event-driven interaction, the use of messages for
data transfer, and the ability to easily adopt different transport
protocols.
Paragraph (version B):
design explains the design principles that guide the Transport
Services API.  These principles are intended to make sure that
transport protocols can continue to be enhanced and evolve without
requiring too many changes by application developers.
Paragraph (version B):
concepts presents the Transport Services architecture diagram and
defines the concepts that are used by both the API and
implementation documents.  The Preconnection allows applications
to configure connection properties, and the Connection represents
an object that can be used to send and receive Messages.
Draft: draft-ietf-taps-interface

Commentary: This implements what we discussed on 
 There should be a way to put back pressure or limits on the number of inbound connections for a listener . The two approaches are : have a one - to - one callback for listen -received connect have a way to set a numeric limit of new inbound connections My preference is ( 2 ) . ( 1 ) has an issue of being very impractical for servers that do n't know how many connections they 'll receive , and may require them to call a thousand times without any other activity . ( 2 ) is more similar to how calling on sockets work . 
 +1 on variant 2 - indeed it 's common and known to people from sockets , and just seems like the easier and more efficient solution ( albeit maybe less " beautiful " , in a way ) . 
 +1 on variant 2 as well . 
 Do variant 2 . 
 I believe that PR fully addresses this ; hence I 'm closing it . 
 lgtm , thanks!This is surely useful as - is . Considering the recent discussion on the list ( dynamic per - IP rejection possibilities ) , I 'm not sure it 's rich enough ... but it 's certainly a good starting point . I 'm also not sure how much of what 's been discussed really should be a part of the spec .
Paragraph (version B):
If the caller wants to rate-limit the number of inbound Connections
that will be delivered, it can set a cap using
SetNewConnectionLimit().  This mechanism allows a server to protect
itself from being drained of resources.  Each time a new Connection
is delivered by the ConnectionReceived Event, the value is
automatically decremented.  Once the value reaches zero, no further
Connections will be delivered until the caller sets the limit to a
higher value.  By default, this value is Infinite.  The caller is
also able to reset the value to Infinite at any point.
Draft: draft-ietf-taps-interface

Commentary: This closes first half of Issue as discussed today 
 Ship it !
Paragraph (version A):
The optional messageContext parameter supports per-message properties
and is described in message-props.  If provided, the Message Context
object returned is identical to the one that was passed.
Paragraph (version A):
The MessageContext returned by Send can be used to identify send
events (see send-events) related to a specific message or to inspect
meta-data related to the message sent.
Paragraph (version B):
The optional messageContext parameter supports per-message properties
and is described in message-props.  It can be used to identify send
events (see send-events) related to a specific message or to inspect
meta-data related to the message sent (see msg-ctx).
Draft: draft-ietf-taps-interface

Commentary: This came up in a dinner among some of us yesterday : all UDP messages should be understood as being idempotent , because UDP does n't protect the receiver against getting duplicates . This is different from unreliable transmission with , e.g. , SCTP ( or , probably , a future such extension of QUIC ? ) , where you can be sure you 're not getting a duplicate . 
 wfm
Paragraph (version B):
Note that for protocols that do not protect against duplicated
messages, e.g., UDP, all messages MUST be marked as Idempotent.  In
order to enable protocol selection to choose such a protocol,
Idempotent MUST be added to the TransportProperties passed to the
Preconnection.  If such a protocol was chosen, disabling Idempotent
on individual messages MUST result in a SendError.