jiebi/CodeConvo huggingface dataset:
Code change:
Capitalization seems to be a problem for us. We need to make things uniform. At first, I reacted to seeing "connection" as parameters in this PR, because we use the term "Connection" to refer to a TAPS-provided connection (as opposed to a connection of the underlying system), and so, de-capitalizing the term here may look better, but it is also somewhat imprecise. This said, we do the same with other capitalized terms too, here and in the API draft - e.g., "messageContext". Should we generally agree to begin terms with a lowercase letter when they are used as parameters in code examples? I think we have this in most places, though at least the API draft has several counterexamples... e.g., the server example code: Preconnection := NewPreconnection(LocalSpecifier, TransportProperties, SecurityParameters) (..) Listener -> ConnectionReceived
From discussion on
This was a mistake. As I wanted to do this now, I noticed that all occurrences of capitalized terms as parameters are objects that are defined and used elsewhere in the code examples. For example: Preconnection := NewPreconnection(RemoteSpecifier, TransportProperties, SecurityParameters) refers to RemoteSpecifier etc., being objects that are initialized some lines above. Making them appear in lower case everywhere would be awkward, this is then a much more drastic change to our pseudocode. As a result, I think it's fine to leave things as they are, and I suggest to close this issue with no action.
Framers: What is the difference between the Final message property and the separate IsEndOfMessage event argument?
Also there, the term MessageContext could use a definition
and searching "isEndOfMessage" tells me that there is no text describing this parameter. Regarding the question, the difference should be clear: seems self-explanatory, whereas indicates that the Message carrying it is the last one of the Connection. So, this is End of the Message vs. End of the Connection.
Sounds like this needs a reference to the API doc, and change IsEndOfMessage to endOfMessage to match the API.
Probably fix with
I think this looks ok (and thanks for doing this!), but see also my comment about making things uniform wrt. capitalization: if we merge this PR, we should also do one that does the same with the API draft.Thanks LGTM! Although I noticed another nit that can perhaps be fixed in the same PR even if not directly related to the parameter names. Regarding the capitalization I think we can merge this PR and then have a separate issue for the capitalization as we will need to fix this either way.

Related discussion:
text: 6.2. Message Framers generate an event whenever a Connection sends a new <del> Message. </del> <ins> Message.  The parameters to the event align with the Send call in the API (Section 9.2 of I-D.ietf-taps-interface). </ins> Upon receiving this event, a framer implementation is responsible for performing any necessary transformations and sending the resulting
Code change:
Capitalization seems to be a problem for us. We need to make things uniform. At first, I reacted to seeing "connection" as parameters in this PR, because we use the term "Connection" to refer to a TAPS-provided connection (as opposed to a connection of the underlying system), and so, de-capitalizing the term here may look better, but it is also somewhat imprecise. This said, we do the same with other capitalized terms too, here and in the API draft - e.g., "messageContext". Should we generally agree to begin terms with a lowercase letter when they are used as parameters in code examples? I think we have this in most places, though at least the API draft has several counterexamples... e.g., the server example code: Preconnection := NewPreconnection(LocalSpecifier, TransportProperties, SecurityParameters) (..) Listener -> ConnectionReceived
From discussion on
This was a mistake. As I wanted to do this now, I noticed that all occurrences of capitalized terms as parameters are objects that are defined and used elsewhere in the code examples. For example: Preconnection := NewPreconnection(RemoteSpecifier, TransportProperties, SecurityParameters) refers to RemoteSpecifier etc., being objects that are initialized some lines above. Making them appear in lower case everywhere would be awkward, this is then a much more drastic change to our pseudocode. As a result, I think it's fine to leave things as they are, and I suggest to close this issue with no action.
Framers: What is the difference between the Final message property and the separate IsEndOfMessage event argument?
Also there, the term MessageContext could use a definition
and searching "isEndOfMessage" tells me that there is no text describing this parameter. Regarding the question, the difference should be clear: seems self-explanatory, whereas indicates that the Message carrying it is the last one of the Connection. So, this is End of the Message vs. End of the Connection.
Sounds like this needs a reference to the API doc, and change IsEndOfMessage to endOfMessage to match the API.
Probably fix with
I think this looks ok (and thanks for doing this!), but see also my comment about making things uniform wrt. capitalization: if we merge this PR, we should also do one that does the same with the API draft.Thanks LGTM! Although I noticed another nit that can perhaps be fixed in the same PR even if not directly related to the parameter names. Regarding the capitalization I think we can merge this PR and then have a separate issue for the capitalization as we will need to fix this either way.

Related discussion:
text: In order to parse a received flow of data into Messages, the Message Framer notifies the framer implementation whenever new data is <del> available to parse. </del> <ins> available to parse.  The parameters to the the events and calls for receiving data with a framer align with the Receive call in the API (Section 9.3 of I-D.ietf-taps-interface). </ins> Upon receiving this event, the framer implementation can inspect the inbound data.  The data is parsed from a particular cursor
Code change:
We don't have "Protocol Properties" - two occurrences in -interface should really refer to "protocol-specific Properties", and two occurrences in -impl should really refer to properties.
URL Are Protocol Specific Properties and Protocol Properties same or different? Also note that we are first time defining the Protocol Properties in the interface document ( described along with Connection Properties) and not introduced in the architecture document. I think we should be clear about what we are defining where and describing where. I would suggest use of cross reference rather describing everything again and again, which might create confusion and inconsistency.
Oh, this seems like a mistake (great catch, thanks!) - "Protocol Properties" don't exist, I think we only have "protocol-specific Properties".
I caught this when reading the implementation doc. So it should be fixed there as well.

Related discussion:
text: Protocol-specific Properties MUST use the protocol acronym as the Namespace (e.g., a "tcp" Connection could support a TCP-specific <del> Transport Property, such as the user timeout value, in a protocol- specific property called "tcp.userTimeoutValue" (see tcp-uto). </del> <ins> Transport Property, such as the user timeout value, in a Protocol- specific Property called "tcp.userTimeoutValue" (see tcp-uto). </ins> Vendor or implementation specific properties MUST use a string identifying the vendor or implementation as the Namespace.
Code change:
We don't have "Protocol Properties" - two occurrences in -interface should really refer to "protocol-specific Properties", and two occurrences in -impl should really refer to properties.
URL Are Protocol Specific Properties and Protocol Properties same or different? Also note that we are first time defining the Protocol Properties in the interface document ( described along with Connection Properties) and not introduced in the architecture document. I think we should be clear about what we are defining where and describing where. I would suggest use of cross reference rather describing everything again and again, which might create confusion and inconsistency.
Oh, this seems like a mistake (great catch, thanks!) - "Protocol Properties" don't exist, I think we only have "protocol-specific Properties".
I caught this when reading the implementation doc. So it should be fixed there as well.

Related discussion:
text: 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) are reserved for protocol-specific </del> <ins> numbers/protocol-numbers.xhtml) are reserved for Protocol-specific </ins> Properties and MUST NOT be used for vendor or implementation-specific properties.  Avoid using any of the terms listed as keywords in the protocol numbers registry as any part of a vendor- or implementation-
Code change:
We don't have "Protocol Properties" - two occurrences in -interface should really refer to "protocol-specific Properties", and two occurrences in -impl should really refer to properties.
URL Are Protocol Specific Properties and Protocol Properties same or different? Also note that we are first time defining the Protocol Properties in the interface document ( described along with Connection Properties) and not introduced in the architecture document. I think we should be clear about what we are defining where and describing where. I would suggest use of cross reference rather describing everything again and again, which might create confusion and inconsistency.
Oh, this seems like a mistake (great catch, thanks!) - "Protocol Properties" don't exist, I think we only have "protocol-specific Properties".
I caught this when reading the implementation doc. So it should be fixed there as well.

Related discussion:
text: The optional "connectionProperties" parameter allows passing Transport Properties that control the behavior of the underlying <del> stream or connection to be created, e.g., protocol-specific properties to request specific stream IDs for SCTP or QUIC. </del> <ins> stream or connection to be created, e.g., Protocol-specific Properties to request specific stream IDs for SCTP or QUIC. </ins> Message Properties set on a Connection also apply only to that Connection.
Code change:
We don't have "Protocol Properties" - two occurrences in -interface should really refer to "protocol-specific Properties", and two occurrences in -impl should really refer to properties.
URL Are Protocol Specific Properties and Protocol Properties same or different? Also note that we are first time defining the Protocol Properties in the interface document ( described along with Connection Properties) and not introduced in the architecture document. I think we should be clear about what we are defining where and describing where. I would suggest use of cross reference rather describing everything again and again, which might create confusion and inconsistency.
Oh, this seems like a mistake (great catch, thanks!) - "Protocol Properties" don't exist, I think we only have "protocol-specific Properties".
I caught this when reading the implementation doc. So it should be fixed there as well.

Related discussion:
text: Protocol-specific Properties are defined in a transport- and implementation-specific way to permit more specialized protocol features to be used.  Too much reliance by an application on <del> protocol-specific Properties can significantly reduce the flexibility </del> <ins> Protocol-specific Properties can significantly reduce the flexibility </ins> of a transport services implementation to make appropriate selection and configuration choices.  Therefore, it is RECOMMENDED that <del> Protocol Properties are used for properties common across different protocols and that Protocol-specific Properties are only used where specific protocols or properties are necessary. </del> <ins> Protocol-specific Properties are used for properties common across different protocols and that Protocol-specific Properties are only used where specific protocols or properties are necessary. </ins> The application can set and query Connection Properties on a per- Connection basis.  Connection Properties that are not read-only can
Code change:
We don't have "Protocol Properties" - two occurrences in -interface should really refer to "protocol-specific Properties", and two occurrences in -impl should really refer to properties.
URL Are Protocol Specific Properties and Protocol Properties same or different? Also note that we are first time defining the Protocol Properties in the interface document ( described along with Connection Properties) and not introduced in the architecture document. I think we should be clear about what we are defining where and describing where. I would suggest use of cross reference rather describing everything again and again, which might create confusion and inconsistency.
Oh, this seems like a mistake (great catch, thanks!) - "Protocol Properties" don't exist, I think we only have "protocol-specific Properties".
I caught this when reading the implementation doc. So it should be fixed there as well.

Related discussion:
text: Message Properties can be set and queried using the Message Context: <del> These Message Properties may be generic properties or protocol- </del> <ins> These Message Properties may be generic properties or Protocol- </ins> specific Properties. For MessageContexts returned by send Events (see send-events) and
Code change:
We don't have "Protocol Properties" - two occurrences in -interface should really refer to "protocol-specific Properties", and two occurrences in -impl should really refer to properties.
URL Are Protocol Specific Properties and Protocol Properties same or different? Also note that we are first time defining the Protocol Properties in the interface document ( described along with Connection Properties) and not introduced in the architecture document. I think we should be clear about what we are defining where and describing where. I would suggest use of cross reference rather describing everything again and again, which might create confusion and inconsistency.
Oh, this seems like a mistake (great catch, thanks!) - "Protocol Properties" don't exist, I think we only have "protocol-specific Properties".
I caught this when reading the implementation doc. So it should be fixed there as well.

Related discussion:
text: In the following cases, failure should be detected during pre- establishment: <del> A request by an application for Protocol Properties that cannot be </del> <ins> A request by an application for properties that cannot be </ins> satisfied by any of the available protocols.  For example, if an application requires "perMsgReliability", but no such feature is available in any protocol on the host running the transport system this should result in an error, e.g., when SCTP is not supported by the operating system. <del> A request by an application for Protocol Properties that are in conflict with each other, i.e., the required and prohibited properties cannot be satisfied by the same protocol.  For example, if an application prohibits "reliability" but then requires </del> <ins> A request by an application for properties that are in conflict with each other, i.e., the required and prohibited properties cannot be satisfied by the same protocol.  For example, if an application prohibits "reliability" but then requires </ins> "perMsgReliability", this mismatch should result in an error. To avoid allocating resources that are not finally needed, it is
Code change:
We don't have "Protocol Properties" - two occurrences in -interface should really refer to "protocol-specific Properties", and two occurrences in -impl should really refer to properties.
URL Are Protocol Specific Properties and Protocol Properties same or different? Also note that we are first time defining the Protocol Properties in the interface document ( described along with Connection Properties) and not introduced in the architecture document. I think we should be clear about what we are defining where and describing where. I would suggest use of cross reference rather describing everything again and again, which might create confusion and inconsistency.
Oh, this seems like a mistake (great catch, thanks!) - "Protocol Properties" don't exist, I think we only have "protocol-specific Properties".
I caught this when reading the implementation doc. So it should be fixed there as well.

Related discussion:
text: implementation should store the properties in storage common to all protocols, and notify all protocol instances in the Protocol Stack whenever the properties have been modified by the application.  For <del> protocol-specfic properties, such as the User Timeout that applies to TCP, the Transport Services implementation only needs to update the relevant protocol instance. </del> <ins> Protocol-specific Properties, such as the User Timeout that applies to TCP, the Transport Services implementation only needs to update the relevant protocol instance. </ins> If an error is encountered in setting a property (for example, if the application tries to set a TCP-specific property on a Connection that
Code change:
URL Assuming there would be more protocols in the future and the minset functionalities will expand via extension or amendments. It would important to indicate if this architecture should is also extensible or it only supports on the minimum set referred. Definitely we haven't seen the future yet, but it would be important to express if we have considered such expansion of minimum functionalities.
To me, the current spec is based on minset that describes the common functions. So, the addition I would expect here is to say that there can be extensions and protocol-specific features.
I expect that if a common feature is added to the minset, then the architecture and API surface would also be extended to match.
LGTM modulo a nit

Related discussion:
text: SHOULD be made accessible through a unified set of calls using the Transport Services API.  As a baseline, any Transport Services API SHOULD allow access to the minimal set of features offered by <del> transport protocols RFC8923. </del> <ins> transport protocols RFC8923.  If that minimal set is updated or expanded in the future, the Transport Services API ought to be extended to match. </ins> An application can specify constraints and preferences for the protocols, features, and network interfaces it will use via
Code change:
URL Unless there is a description the figure, with directed and non-directed lines it is very hard to interpret the figure. I would recommend to at least add some reading guidance for the lines.
LGTM, thanks!Looks fine.

Related discussion:
text: setting Connection and Message Properties in Pre-Establishment) or have been omitted for brevity and simplicity. <ins> In this diagram, the lifetime of a Connection object is broken into three phases: Pre-Establishment, the Established state, and Termination. Pre-Establishment is based around a Preconnection object, that contains various sub-objects that describe the properties and parameters of desired Connections (Local and Remote Endpoints, Transport Properties, and Security Parameters).  A Preconnection can be used to start listening for inbound connections, in which case a Listener object is created, or can be used to establish a new connection directly using Initiate() (for outbound connections) or Rendezvous() (for peer-to-peer connections). Once a Connection is in the Established state, an application can send and receive Message objects, and receive state updates. Closing or aborting a connection, either locally or from the peer, can terminate a connection. </ins> 4.1.1. Endpoint: An endpoint represents an identifier for one side of a
Code change:
(sorry that it took me so long) This uses some text that is also in the interface draft.
This I would like us to discuss. Well I know we have discussed this before. As I am reading the Interface document after a long while and having read it along with the architecture document, I kind of strongly feel that the architecture document lack of description on framer and the states. These are mentioned and pictured in the architecture document but haven't been clear there. Hence, I kind of feel that we need to move this two sections to architecture document. Please discuss so that I can understand the reasoning of not doing so.
Regarding section 9.1.2, the framer description: I think it's good to be clear and complete in the API document, but I agree that framers should be appropriately described in the architecture document. I have the impression that the text in the -arch document on this matter may indeed be too short, while the text in the -interface document may be too long (although a little bit of repetition surely won't hurt here, it's good for this document to be understandable and clear on its own). Maybe some of it could be moved to -arch, or repeated there? Regarding section 11, Connection states: to me, this is fine as it is. Section 4.1 / figure 4 in the architecture document make state transitions pretty clear - and section 11 / figure 2 are just a more fine-grain look at these states as a way to explain exactly which Events will occur when. This seems needed in the API document, where all other Events and Actions are defined, and I would think that this is at a too detailed / fine-grain level for the architecture document.
NAME after giving it some more thoughts, I think your suggested approach should be fine , meaning we put more description of framer in the architecture document and leave the connection states to the Interface document.
NAME did you want to take a stab at this?
Looks great!

Related discussion:
text: application. Framer: A Framer is a data translation layer that can be added to <del> a Connection to define how application-layer Messages are transmitted over a Protocol Stack.  This is particularly relevant when using a protocol that otherwise presents unstructured streams, such as TCP. </del> <ins> a Connection.  Framers allow extending a Connection's protocol stack to define how to encapsulate or encode outbound Messages, and how to decapsulate or decode inbound data into Messages.  In this way, message boundaries can be preserved when using a Connection object, even with a protocol that otherwise presents unstructured streams, such as TCP.  This is designed based on the fact that many of the current application protocols evolved over TCP, which does not provide message boundary preservation, and since many of these protocols require message boundaries to function, each application layer protocol has defined its own framing.  For example, when an HTTP application sends and receives HTTP messages over a byte-stream transport, it must parse the boundaries of HTTP messages from the stream of bytes. </ins> 4.1.6.
Code change:
Feel free to approve or propose changes to improve this sentence in Arch.
BT: "I’m not convinced of the value of the glossary of terms, as it forwardrefs basically the entire document, and some of the definitions are so generic as to be potentially confusing (e.g. Event), so I think putting these up front reduces the document’s approachability and readability. I understand that some people like these (and other standards orgs make them mandatory, hi ETSI), so I won’t fight it." "Adding a sentence making it clear it’s safe to skip the glossary if you’re going to read the rest of the document would address my approachability concern completely. "

Related discussion:
text: 1.4. This subsection provides a glossary of key terms related to the <del> Transport Services architecture.  It provides a simple description of </del> <ins> Transport Services architecture.  It provides a short description of </ins> key terms that are later defined in this document. Application: An entity that uses the transport layer for end-to-