jiebi/CodeConvo huggingface dataset:
Change:
Even though all the languages we want to support don'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)

Discussion:
An Object sends an Event: An Action takes a set of Parameters; an Event contains a set of <del> Parameters: </del> <ins> Parameters.  Action parameters whose names are suffixed with a question mark are optional. </ins> Actions associated with no Object are Actions on the abstract interface itself; they are equivalent to Actions on a per-application

Messages for streaming large data is also supported (see send- partial). <ins> Messages are sent on a Connection using the Send action: 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. </ins> 7.1. The most basic form of sending on a connection involves enqueuing a

For application-layer protocols where the Connection initiator also sends the first message, the InitiateWithSend() action combines <del> Connection initiation with a first Message sent. Without a message context (as in send-basic): With a message context (as in message-props): </del> <ins> Connection initiation with a first Message sent: </ins> Whenever possible, a messageContext should be provided to declare the message passed to InitiateWithSend as idempotent.  This allows the
Change:
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? Gorry
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 NAME

Discussion:
particular, this can avoid (re-)sending data that relies on a previous transmission that was never received. <ins> the ability to automatically assign messages and connections to underlaying transport connections to utilize multi-streaming and pooled connections. </ins> Allowing applications to interact with messages is backwards- compatible with existings protocols and APIs, as it does not change the wire format of any protocol.  Instead, it gives the protocol

Properties (datatransfer).  Message Properties can also be specified during data transfer to affect specific Messages. <del> 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. </del> <ins> 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. </ins> Listener: A Listener object accepts incoming transport protocol connections from remote systems and generates corresponding
Change:
This came up in a dinner among some of us yesterday: all UDP messages should be understood as being idempotent, because UDP doesn'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

Discussion:
path, the transport system will try the path first, ignoring the preference. <del> Both Selection and Connection Properties can be added to a Preconnection to configure the selection process, and to further configure the eventually selected protocol stack(s).  They are collected into a TransportProperties object to be passed into a Preconnection object: </del> <ins> Selection, and Connection Properties, as well as defaults for Message Properties, can be added to a Preconnection to configure the selection process, and to further configure the eventually selected protocol stack(s).  They are collected into a TransportProperties object to be passed into a Preconnection object: </ins> Individual properties are then added to the TransportProperties Object:

retransmission of the 0-RTT data may cause the remote application to receive the Message multiple times. <ins> 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. </ins> 7.3.5. Boolean
Change:
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: To have a one-to-one callback for listen -> received connect To 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 don'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.

Discussion:
Connection-oriented transport protocols), or when the first Message has been received from the Remote Endpoint (for Connectionless protocols), causing a new Connection to be created.  The resulting <del> Connection is contained within the ConnectionReceived event, and is </del> <ins> Connection is contained within the ConnectionReceived Event, and is </ins> ready to use as soon as it is passed to the application via the event. <ins> 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. </ins> A ListenError occurs either when the Properties of the Preconnection cannot be fulfilled for listening, when the Local Endpoint (or Remote Endpoint, if specified) cannot be resolved, or when the application is prohibited from listening by policy. <del> A Stopped event occurs after the Listener has stopped listening. </del> <ins> A Stopped Event occurs after the Listener has stopped listening. </ins> 6.3.
Change:
Complete
Thanks Tommy! I think this looks good The meaning of Interactive is a bit fuzzy, but not sure if we can solve that.

Discussion:
multipath <del> 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. </del> <ins> Enumeration This property specifies whether an application wants to take advantage of transferring data across multiple paths between the same end hosts.  Using multiple paths allows connections to migrate between interfaces as availability and performance properties change. Possible values are: The connection will not attempt using multiple paths once established The connection should attempt to migrate between different paths upon interface availability changes The connection should attempt to use multiple paths in response to loss or delay upon individual paths The connection should attempt to use multiple paths in parallel in order to maximize bandwidth The default is Disabled.  The other enumeration values are all interpreted as preferences. </ins> 5.2.14.
Change:
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!

Discussion:
5.2.12. <ins> local-address-preference Enumeration This property specifies whether Listeners and Connections should prefer the use of temporary addresses when possible.  This is generally used to prevent linking connections over time when a stable address is not needed.  Possible values are: Prefer the use of stable (sometimes called "permanent") local addresses Prefer the use of temporary (sometimes called "privacy") addresses Prefer the use of stable local addresses for Listeners and Rendezvous Connections, and prefer the use of temporary addresses for other Connections. 5.2.13. </ins> multipath This property specifies whether an application considers it useful to

jitter, which may be problematic for delay-sensitive applications. The recommended default is to Ignore this option. <del> 5.2.13. </del> <ins> 5.2.14. </ins> direction

specifying unidirectional communication may cause a transport stack that supports bidirectional communication to be selected. <del> 5.2.14. </del> <ins> 5.2.15. </ins> Name: :retransmit-notify

be informed in case sent data was retransmitted more often than a certain threshold.  The default is to Ignore this option. <del> 5.2.15. </del> <ins> 5.2.16. </ins> Name: :soft-error-notify
Change:
Address
meh okay if we must. :P nah this is great, already merged it.Fine - works

Discussion:
Listen: The action of marking a Listener as willing to accept incoming Connections.  The Listener will then create Connection <del> objects as incoming connections are accepted (events). </del> <ins> 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. </ins> Rendezvous: The action of establishing a peer-to-peer connection with a Remote Endpoint.  It simultaneously attempts to initiate a

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 <del> Endpoint, occurs during the Rendezvous call.  If successful, the rendezvous call returns a Connection object to represent the established peer-to-peer connection. </del> <ins> 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. </ins> 4.1.4.
Change:
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" cannot 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 NAME 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: Application calls Receive(maxLength=10) Application calls Receive(maxLength=20) Message with length 20 arrives Message with length 10 arrives Application get received callback for message with length 10 Application 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.

Discussion:
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 <del> to implementation constraints. </del> <ins> 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. </ins> 8.2.
Change:
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

Discussion:
TCP and UDP in the kernel send and receive data over the available network layer interfaces. <del> 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. </del> <ins> 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. 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. </ins> The Transport Services API I-D.ietf-taps-interface defines the mechanism for an application to create network connections and
Change:
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!

Discussion:
containing these properties can be passed to the Send Action.  For other uses of the message context, see msg-ctx. <del> Note that message properties are per-Message, not per-Send if partial </del> <ins> Note that Message Properties are per-Message, not per-Send if partial </ins> Messages are sent (send-partial).  All data blocks associated with a single Message share properties specified in the Message Contexts. For example, it would not make sense to have the beginning of a

This enumerated property specifies the application's preferred tradeoffs for sending this Message; it is a per-Message override of <del> the Capacity Profile protocol and path selection property (see prop- cap-profile). The following values are valid for Transmission Profile: No special optimizations of the tradeoff between delay, delay variation, and bandwidth efficiency should be made when sending this message. 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. [TODO: This is inconsistent with {prop-cap-profile}} - needs to be fixed] </del> <ins> the Capacity Profile connection property (see prop-cap-profile). </ins> 7.4.9.

MessageContext object can be passed to the Send action and is retuned by each Send and Receive related events. <del> Message properties can be set and queried using the Message Context: </del> <ins> Message Properties can be set and queried using the Message Context: </ins> To get or set Message Properties, the optional scope parameter is left empty, for framing meta-data, the framer is passed.

all Connections are defined in the subsections below. Note that many protocol properties have a corresponding selection <del> property, which prefers protocols providing a specific transport feature that controlled by that protocol property.  [EDITOR'S NOTE: todo: add these cross-references up to selection-props] </del> <ins> property, which prefers protocols providing a supporting transport feature. </ins> 11.1.1.
Change:
Completes
Close: The way this is written suggests that the API doesn'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!

Discussion:
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 <del> the remote system if the transport protocol allows this. </del> <ins> the remote system if the transport protocol allows this.  (Note that this is distinct from the concept of "half-closing" a bidirectional connection, such as when a FIN is sent in one direction of a TCP connection.  Indicating the end of a stream in the Transport Services architecture is possible using Message Properties when sending.) </ins> Abort: The action the application takes on a Connection to indicate a Close and also indicate that the transport system
Change:
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?

Discussion:
Rendezvous: The action of establishing a peer-to-peer connection with a Remote Endpoint.  It simultaneously attempts to initiate a <del> 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. </del> <ins> 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. </ins> 4.1.4.
Change:
Example code updates: this is to try to avoid people stumbling over, e.g., "send" being part of the "main code". I believe it's a little cleaner with these added comments.Lifetime Message property: mentioned -1 as a special value for infinite, else it's a bit odd to only use "infinite" for an integervery minor text fix about corruption protection length Message property
Okay, so I think I addressed NAME comments here, and agreed with NAME that we could adjust things further later on if needed - so now I'll just merge this one, seems safe to do to me.
These two message properties are interconnected and therefore have a dependency. I would rather prefer to only have one property. Lifetime already has one "special" value (infinity) to indicate reliable transmission. We could also declare 0 as special to indicate unreliable transmission (only transmit once and never retransmit). Also should we rather use -1 for reliable? And also do this for other properties that currently have meaning for infinite? Or would it be more correct to say max instead of infinite? And more more question on lifetime: Do we need an event that indicates to the application that transmission was aborted due to lifetime expiry?
No. Here's a quote from the description of lifetime: " Setting a Message's Lifetime to infinite indicates that the application does not wish to apply a time constraint on the transmission of the Message, but it does not express a need for reliable delivery; reliability is adjustable per Message via the "Reliable Data Transfer (Message)" property (see Section 7.4.7). " Consider an unreliable, congestion controlled transport (e.g. QUIC with datagrams). Specifying a "lifetime" means that, once the lifetime has expired, the Message can be deleted from the send buffer. Setting "lifetime" to infinite means that the Message will never just be deleted from the send buffer. This does not at all guarantee that the Message will be retransmitted in case it was lost. The mistake is the mix of "integer" and "infinite". The latter is okay for type "numeric". I have already fixed this in PR (which is still open). That's the Expired Event, see section 7.3.2.
Can we close this issue?
Interim: Agreed with NAME closing.

Discussion:
msg-lifetime <del> Integer </del> <ins> Numeric </ins> infinite