jiebi/CodeConvo huggingface dataset:
Change:
As described in , I removed the condition that requires the application to specify the length upon receiving from this example.
Impl draft section 5.2 Receiving Messages: "if, on the other hand, the top-level protocol only supports a byte-stream and no deframers were supported, the application must specify the minimum number of bytes of Message content it wants to receive (which may be just a single byte) to control the flow of received data." This text says the application MUST specify minIncompleteLength, however, the API draft says that this values is optional. This should be further clarified and more guidance given in case the value is not set.
Having looked at this and the API carefully, my suggestion would be to turn the semicolon preceding this statement into a full stop and remove all of this "if, on the other hand, ...." text in the implementation draft.
WFM.
This was a long text block - I had a few editorial NiTs you may like to address.

Discussion:
application.  This requires the implementation to understand where messages end, either via a supplied deframer or because the top-level protocol in the established Protocol Stack preserves message <del> boundaries; if, on the other hand, the top-level protocol only supports a byte-stream and no deframers were supported, the application must specify the minimum number of bytes of Message content it wants to receive (which may be just a single byte) to control the flow of received data. </del> <ins> boundaries.  If the top-level protocol only supports a byte-stream and no framers were supported, the application can control the flow of received data by specifying the minimum number of bytes of Message content it wants to receive at one time. </ins> If a Connection becomes finished before a requested Receive action can be satisfied, the implementation should deliver any partial
Change:
Resolving Editorial NiTs in section 1
Section 1: This section contains a RFC2119 keyword that precedes the definition! We use the words /abstract programming interface/ and the acronym /API/ but never tie these together. NiTs: /provide applications a way to/provide a way for applications to/ /as it comes at the cost of reduced portability/because it can reduce the portability./ /How these abstract concepts/The way these abstract concepts/ /is largely dependent on/mostly depends on/
A PR for this issue has already been merged.
Looks good to me, thanks for doing this!

Discussion:
1. <del> This document specifies a modern abstract programming interface (API) atop the high-level architecture for transport services defined in I- D.ietf-taps-arch.  It supports the asynchronous, atomic transmission of messages over transport protocols and network paths dynamically selected at runtime.  It is intended to replace the traditional BSD sockets API as the common interface to the transport layer, in environments where endpoints select from multiple interfaces and potential transport protocols. </del> <ins> This document specifies a modern abstract application programming interface (API) atop the high-level architecture for transport services defined in I-D.ietf-taps-arch.  It supports the asynchronous, atomic transmission of messages over transport protocols and network paths dynamically selected at runtime.  It is intended to replace the traditional BSD sockets API as the common interface to the transport layer, in environments where endpoints select from multiple interfaces and potential transport protocols. </ins> As applications adopt this interface, they will benefit from a wide set of transport features that can evolve over time, and ensure that
Change:
Looks fine to me. I wonder if we want to add some text and given some implementation hints. Not sure if that is needed but it could be useful...?
Looks good.
In section 7.1 of API it says: messageData := "hello".bytes() Connection.Send(messageData) For some languages that are dynamic typed (i.e. python) this limits the usability of the API as it adds an unnecessary extra step to each send. To me this seems like it should be an implementation detail and not specified in the API.
What are the options other than raw bytes?
In python you could just pass any type that gets automatically converted inside the API. For example, in our implementation you could just pass a string or integer that gets converted to bytes inside the implementation before sending. Also, if there is a TLV framer, you could just pass a [type,value] tuple without having to go through the message context.
We generally consider this a case for framers. However, I think it's reasonable to assume that any of the objects used in a TAPS implementation should provide some way for the app to get at the underlying bytes (and therefore, at least implicitly, the length). I don't read this text as prohibiting the use of some object that is able.
I agree that this is an implementation detail that's irrelevant to the abstract API. Can we close this issue?
Requiring the data be accessible as a byte array is overly restrictive. Can we just remove "Message data is transferred as an array of bytes, and the resulting object contains both the byte array and the length of the array." and the call?

Discussion:
The most basic form of sending on a connection involves enqueuing a single Data block as a complete Message, with default Message <del> Properties.  Message data is transferred as an array of bytes, and the resulting object contains both the byte array and the length of the array. </del> <ins> Properties. </ins> The interpretation of a Message to be sent is dependent on the implementation, and on the constraints on the Protocol Stacks implied
Change:
Apple does this: URL URL it may be more convenient than what we currently have (or do we have it unspecified? My interpretation of our text would have been to use only one receive handler associated to the Connection). E.g., if an application expects 3 different types of messages to be received in sequence, it can hand over three different receive handlers in Apple's case, and that seems useful. Apple also has a "completion" handler per sent event, handed over as a parameter to "send". Is this necessary? Who needs 3 different "Sent" handlers for 3 different messages - shouldn't the "sent" handler rather be a singular per-Connection thing?
I think this gets into an implementation-specific area. If the language has an easy way to provide a unique completion/closure for a given invocation of Receive(), then I think it is preferable to do this to having a single function. If anything, it may be nice to make a not for Received() and Sent() that they should, if supported by the language, provide this kind of linking between calls and events.
I agree, and I assign this to Tommy since he offered (in an email) to write text. Thanks a lot!

Discussion:
that Message are outstanding, there will be two Expired events delivered. <ins> The interface should allow the application to correlate which Send Action resulted in a particular Send Event.  The manner in which this correlation is indicated is implementation-specific. </ins> 7.3.1. The Sent Event occurs when a previous Send Action has completed,

provide backpressure to the transport stack when it is temporarily not ready to receive messages. <ins> The interface should allow the application to correlate which call to Receive resulted in a particular Receive Event.  The manner in which this correlation is indicated is implementation-specific. </ins> 8.2.1. A Received event indicates the delivery of a complete Message.  It
Change:
batch sending, as currently specified, means that you already have to have all messages ready in the application because you can declare a patch. That means you have to potentially "buffer" some message in the application. Wouldn't it may be better/easier to have a message property that indicates that a certain message should wait (probably up until a maximum time) for the next message and then buffer it in the transport instead?
We can just clarify the text that the batch may be an arbitrarily long-running block of code, and not require knowing up front all of the data.
Could also allow begin batch/end batch. Explain use case around optimizing send performance.

Discussion:
7.7. To reduce the overhead of sending multiple small Messages on a <del> Connection, the application may want to batch several Send actions </del> <ins> Connection, the application may want to batch several Send Actions </ins> together.  This provides a hint to the system that the sending of these Messages should be coalesced when possible, and that sending any of the batched Messages may be delayed until the last Message in the batch is enqueued. <ins> The semantics for starting and ending a batch can be implementation- specific, but need to allow multiple Send Actions to be enqueued. </ins> 7.8. For application-layer protocols where the Connection initiator also
Change:
Clarify how the IANA protocol numbers registry keywords (largely upper-case) textually relate to Transport Property Names. Refine some of the surrounding text.

Discussion:
4.2.1. Transport Properties are referred to by property names.  These names <del> are lower-case strings whereby words are separated by hyphens.  These names serve two purposes: </del> <ins> are lower-case alphanumeric strings in which words may be separated by hyphens.  These names serve two purposes: </ins> <del> Allow different components of a TAPS implementation to pass </del> <ins> Allowing different components of a TAPS implementation to pass </ins> Transport Properties, e.g., between a language frontend and a policy manager, or as a representation of properties retrieved from a file or other storage. <del> Make code of different TAPS implementations look similar. </del> <ins> Making code of different TAPS implementations look similar. </ins> Transport Property Names are hierarchically organized in the form [<Namespace>.]<PropertyName>. <del> The Namespace part MUST be empty for well-known, generic </del> <ins> The Namespace component MUST be empty for well-known, generic </ins> properties, i.e., for properties that are not specific to a protocol and are defined in an RFC.

Vendor or implementation specific properties MUST use a string identifying the vendor or implementation as Namespace. <del> Namespaces for the keywords provided in the IANA protocol numbers registry (see https://www.iana.org/assignments/protocol-numbers/ protocol-numbers.xhtml) are reserved for Protocol Specific Properties and MUST not be used for vendor or implementation specific properties. </del> <ins> Namespaces for each of the keywords provided in the IANA protocol numbers registry (see https://www.iana.org/assignments/protocol- numbers/protocol-numbers.xhtml), translated to lower-case and with characters other than letters, numbers, and hyphens deleted, are reserved for Protocol Specific Properties and MUST not be used for vendor or implementation-specific properties. </ins> 4.2.2.
Change:
Sorry we just merged the multipath part into the API doc but I think there is still an issue about this part: 'Active: : The connection will negotiate the use of multiple paths if the chosen transport supports this. It will actively bring up paths based on the multipath policy ({{multipath-policy}}) selected by the application, as limited by the Interface Instance and Provisioning Domain Instance properties (see {{prop-interface}} and {{prop-pvd}}). Passive: : The connection will support the use of multiple paths if the remote endpoint requests it. The connection will not actively initiate the use of any new paths, but will accept paths initiated by the remote endpoint.' This mixes two things which should be separated: requesting MP support actively (or just do it if requested by the other end) and opening of new subflows when MP support was negotiated successfully. I thought we wanted to take the later out (opening sub flows) and discuss that separately....?
Just created PR to remove the part about opening new subflows. Do we need to further discuss when/how to open subflows or do we leave this as open for now?
Agree that interim (June 19) to not address opening of subflows in the API

Discussion:
if the chosen transport supports using multiple paths. The connection will negotiate the use of multiple paths if the <del> chosen transport supports this.  It will actively bring up paths based on the multipath policy (multipath-policy) selected by the application, as limited by the Interface Instance and Provisioning Domain Instance properties (see prop-interface and prop-pvd). </del> <ins> chosen transport supports this. </ins> The connection will support the use of multiple paths if the <del> remote endpoint requests it.  The connection will not actively initiate the use of any new paths, but will accept paths initiated by the remote endpoint. </del> <ins> remote endpoint requests it. </ins> The policy for using multiple paths is specified using the separate "multipath-policy" property, see multipath-policy below.  To enable
Change:
When I initial read the heading I thought this is again about reliability. May we can call this single-segment or something...?
Well it's a term - I don't like it much. Single segment doesn't mean it's all in one IP packet (it means it's all in one transport segment). We could just say sending as a single IP packet.
Interim: proposing to rename to something more simple like Don't Fragment? We don't have a good name.
Don't Fragment seems good too me - and tidy this sentence: OLD: /Attempts to send a message with this property set with a size greater to the transport's current estimate of its maximum transmission segment size will result in a "SendError"./ NEW: /Setting this property causes a "SendError" when an attempt is made to send a message with a size greater than the transport's current estimate of the maximum packet size./

Discussion:
7.5.9. <del> singularTransmission </del> <ins> noFragmentation </ins> Boolean false This property specifies that a message should be sent and received as <del> a single packet without transport-layer segmentation or network-layer fragmentation, if possible.  Attempts to send a message with this property set with a size greater to the transport's current estimate of its maximum transmission segment size will result in a "SendError".  When used with transports supporting this functionality and running over IP version 4, the Don't Fragment bit will be set. </del> <ins> a single packet network-layer fragmentation, if possible.  Attempts to send a message with this property set with a size greater to the transport's current estimate of its maximum transmission segment size will result in a "SendError".  When used with transports supporting this functionality and running over IP version 4, the Don't Fragment bit will be set. </ins> 7.6.
Change:
This doesn't change the idea of translating keywords from the IANA protocol numbers registry to lower-case; it just removes the requirement for all Transport Property Names to be lower-case. Why? Right now, they're camlCase, and I guess that reads better than changing them all into hardtoreadstrings or using-hyphens-everywhere ...

Discussion:
4.2.1. Transport Properties are referred to by property names.  These names <del> are lower-case alphanumeric strings in which words may be separated by hyphens.  These names serve two purposes: </del> <ins> are alphanumeric strings in which words may be separated by hyphens. These names serve two purposes: </ins> Allowing different components of a TAPS implementation to pass Transport Properties, e.g., between a language frontend and a
Change:
No need to have a different type of Event for initiate, listen and rendezvous.
On a PreConnection, an application uses EITHER Initiate OR Listen OR Rendezvous. Therefore, it seems unnecessary to distinguish between three types of errors. Shouldn't we have a general per-PreConnection "UnfulfilledError" instead of the InitiateError + ListenError + RendezvousError, just to shorten things a bit? An application needs more details (reasons), but it gets them as a parameter anyway when the new "UnfulfilledError" would occur.

Discussion:
occur before the Ready Event for Connections established using Initiate. <del> An InitiateError occurs either when the set of transport properties and security parameters cannot be fulfilled on a Connection for initiation (e.g. the set of available Paths and/or Protocol Stacks meeting the constraints is empty) or reconciled with the local and/or remote Endpoints; when the remote specifier cannot be resolved; or when no transport-layer connection can be established to the remote Endpoint (e.g. because the remote Endpoint is not accepting connections, the application is prohibited from opening a Connection by the operating system, or the establishment attempt has timed out for any other reason). </del> <ins> An EstablishmentError occurs either when the set of transport properties and security parameters cannot be fulfilled on a Connection for initiation (e.g. the set of available Paths and/or Protocol Stacks meeting the constraints is empty) or reconciled with the local and/or remote Endpoints; when the remote specifier cannot be resolved; or when no transport-layer connection can be established to the remote Endpoint (e.g. because the remote Endpoint is not accepting connections, the application is prohibited from opening a Connection by the operating system, or the establishment attempt has timed out for any other reason). </ins> See also initiate-and-send to combine Connection establishment and transmission of the first message in a single action.

higher value.  By default, this value is Infinite.  The caller is also able to reset the value to Infinite at any point. <del> A ListenError occurs either when the Properties and Security </del> <ins> A EstablishmentError occurs either when the Properties and Security </ins> Parameters of the Preconnection cannot be fulfilled for listening or cannot be reconciled with the Local Endpoint (and/or Remote Endpoint, if specified), when the Local Endpoint (or Remote Endpoint, if

contained within the RendezvousDone<> Event, and is ready to use as soon as it is passed to the application via the Event. <del> An RendezvousError occurs either when the Properties and Security </del> <ins> An EstablishmentError occurs either when the Properties and Security </ins> Parameters of the Preconnection cannot be fulfilled for rendezvous or cannot be reconciled with the Local and/or Remote Endpoints, when the Local Endpoint or Remote Endpoint cannot be resolved, when no
Change:
In the implementation draft section 5.1.3 says that there should be an interface for the application to indicate batch sending. Section 7.7 specifies such an interface. Should the section in the implementation draft be updated or removed?
I think it should be removed. Mainly, it points out that batching reduces overhead, which is also stated in the API draft in section 7.7.
Perhaps it is still important for the implementation to know that it needs to support batching sends though? I would suggest adjusting the text so it reads from the implementations perspective. Something like
I agree; this is a nice text proposal. PR replaces the current text with your proposed one.

Discussion:
Since sending a Message may involve a context switch between the application and the transport system, sending patterns that involve multiple small Messages can incur high overhead if each needs to be <del> enqueued separately.  To avoid this, the application should have a way to indicate a batch of Send actions, during which time the implementation will hold off on processing Messages until the batch is complete.  This can also help context switches when enqueuing data in the interface driver if the operation can be batched. </del> <ins> enqueued separately.  To avoid this, the application can indicate a batch of Send actions through the API.  When this is used, the implementation should hold off on processing Messages until the batch is complete. </ins> 5.2.
Change:
Updates PR to remove reference to lower-case in namespaces corresponding to IANA protocol names. Express that strict adherence to the doc's naming convention is not required, but that symbols in different languages should be visually similar.
NAME NAME Last minute PR

Discussion:
4.2.1. <del> Transport Properties are referred to by property names.  These names are alphanumeric strings in which words may be separated by hyphens. These names serve two purposes: </del> <ins> Transport Properties are referred to by property names.  For the purposes of this document, these names are alphanumeric strings in which words may be separated by hyphens.  These names serve two purposes: </ins> Allowing different components of a TAPS implementation to pass Transport Properties, e.g., between a language frontend and a policy manager, or as a representation of properties retrieved from a file or other storage. <del> Making code of different TAPS implementations look similar. </del> <ins> Making code of different TAPS implementations look similar.  While individual programming languages may preclude strict adherence to the aforementioned naming convention (for instance, by prohibiting the use of hyphens in symbols), users interacting with multiple implementations will still benefit from the consistency resulting from the use of visually similar symbols. </ins> Transport Property Names are hierarchically organized in the form [<Namespace>.]<PropertyName>.

Namespaces for each of the keywords provided in the IANA protocol numbers registry (see https://www.iana.org/assignments/protocol- <del> numbers/protocol-numbers.xhtml), translated to lower-case and with characters other than letters, numbers, and hyphens deleted, are reserved for Protocol Specific Properties and MUST not be used for vendor or implementation-specific properties. </del> <ins> numbers/protocol-numbers.xhtml), reformatted where necessary to conform to an implementation's naming conventions, are reserved for Protocol Specific Properties and MUST not be used for vendor or implementation-specific properties. </ins> 4.2.2.