jiebi/CodeConvo huggingface dataset:
Change:
Be clear that the API is asynchronous (not the whole arch); and reword the read example to also be asynchronous.
In section 2.1 "its call to read will not complete immediately" is easy to misread. The call to read does in fact return immediately. Any read data is returned asynchronously. Please rework this sentence.

Discussion:
asynchronous interface using sockets generally uses a try-and-fail model.  If the application wants to read, but data has not yet been received from the peer, the call to read will fail.  The application <del> then waits and can try again later. In contrast to sockets, all interaction using the Transport Services API is expected to be asynchronous, and use an event-driven model (see events).  For example, an application first completes a call to receive new data from the connection.  When delivered data becomes available, this data is delivered to the application using asynchronous events that contain the data.  Error handling is also asynchronous; a failure to send results in an asynchronous send error as an event. </del> <ins> then waits and can try again later.  In contrast to sockets, all interaction using the Transport Services API is expected to be asynchronous and use an event-driven model (see events).  For example, an application first issues a call to receive new data from the connection.  When delivered data becomes available, this data is delivered to the application using asynchronous events that contain the data.  Error handling is also asynchronous; a failure to send data results in an asynchronous error event. </ins> The Transport Services API also delivers events regarding the lifetime of a connection and changes in the available network links,
Change:
Trying to with a hint upfront that connections can be UDP, TCP or any other transport protocol instance... and then later explain about a connection that can remain an abstraction at the end points for a UDP example.
The last bullet in the Overview is out of place - the others are an overview of the document, but this one is a description of a concept.

Discussion:
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 <del> to configure Connection Properties, and the Connection represents an object that can be used to send and receive Messages. </del> <ins> to configure Connection Properties. </ins> <del> A Connection is an abstraction that represents the communication. If the transport services interface selects a protocol such as TCP for the communication, a Connection will correspond to an underlying protocol connection.  If however a protocol such as UDP is selected, the Connection remains an abstraction at the end points. </del> <ins> concepts also presents how an abstract Connection is used to select a transport protocol instance such as TCP, UDP, or another transport.  The Connection represents an object that can be used to send and receive Messages. </ins> 1.3.

Connection: A Connection object represents one or more active transport protocol instances that can send and/or receive Messages <del> 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 instances, e.g., a set of TCP and QUIC connections to equivalent endpoints, or a stream of a multi-streaming transport protocol instance.  Connections can be created from a Preconnection or by a Listener. </del> <ins> between local and remote systems.  It is an abstraction that represents the communication.  The Connection object holds state pertaining to the underlying transport protocol instances and any ongoing data transfers.  For example, an active Connection can represent a connection-oriented protocol such as TCP, or can represent a fully-specified 5-tuple for a connectionless protocol such as UDP, where the Connection remains an abstraction at the end points.  It can also represent a pool of transport protocol instances, e.g., a set of TCP and QUIC connections to equivalent endpoints, or a stream of a multi-streaming transport protocol instance.  Connections can be created from a Preconnection or by a Listener. </ins> Listener: A Listener object accepts incoming transport protocol connections from remote systems and generates corresponding
Change:
Quote from the API draft: "The present API covers all elements of this section except Notification of Excessive Retransmissions (early warning below abortion threshold)." So... shouldn't this MUST be a SHOULD?
Michael will merge this after finishing the PR that updates -interface minset appendix.

Discussion:
Any functionality that is common across multiple transport protocols SHOULD be made accessible through a unified set of Transport Services <del> API calls.  As a baseline, any Transport Services API MUST allow </del> <ins> API calls.  As a baseline, any Transport Services API SHOULD allow </ins> access to the minimal set of features offered by transport protocols RFC8923.
Change:
Be firm, but avoid MUST NOT apply across different protocols TO ADDRESS
This was discussed at the Interim and final text approved by MW.
In section 8's third paragraph, the MUST NOT is not a good use of 2119/8174. Are you trying to say protocol specific property names must not be reused across different protocols?
I note that the current text was: "Protocol Specific Properties are defined in a transport- and implementation-specific way, and MUST NOT apply across different protocols. Too much reliance by an application on Protocol Specific Properties can significantly reduce the flexibility of a transport services implementation."
Decision: avoid this language, say "architecture expects that ... "
Say this is important but only recommend.

Discussion:
Specific Properties can significantly reduce the flexibility of a transport services implementation to make appropriate selection and configuration choices.  Therefore, it is RECOMMENDED that Protocol <del> Properties are normnally used for properties common across different protocols and that Protocol Specific Properties are only used where specific protocols or properties are necessary. </del> <ins> 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
Change:
Rewording the path information with respect to PVD to reflect Info concerning the path(s) used by the Protocol Stack.
Addressed MW comments in this PR
At the last bullet before section 8.1, are you RFC7556 being pointed to as an example way one might derive properties? If so, adjust the language to make it clear that its an example.
I was thinking this was a useful example: a system that is configured to receive and process MPVD information, as described in RFC7556, can utilise this to inform the system policy that is later used by a transport system implementation, e.g. to provide additional information about paths when performing candidate gathering.
Gorry will write a PR for review.

Discussion:
match all Protocol Selection Properties that the application specified on the Preconnection. <del> For Connections that are Established: Information concerning the </del> <ins> For Connections that are Established: information concerning the </ins> path(s) used by the Protocol Stack.  This can be derived from local PVD information, measurements by the Protocol Stack, or other sources.  For example, a TAPS system that is configured to
Change:
As discussed at the last interim, but cleaning up the references to use the real property names too.
Yes, because it's just a quote of the minset RFC's name :) can't change that anymore
Works for me. I'm not hugely sold on "end systems" given my recent experience with the word "system" in arch - but it likely is quite OK here.

Discussion:
6.2.7. <del> FullChecksumSend </del> <ins> fullChecksumSend </ins> Preference

6.2.8. <del> FullChecksumRecv </del> <ins> fullChecksumRecv </ins> Preference
Change:
There are several places where the document says "Changes to a after func() has been called do not have any connection on existing s". This feels like an opportunity for more clarity about what a really is. The document uses the word Object, and maybe there's an assumption that there's a shared understanding of what the properties of an Object are. Being explicit with something like "An Object is a collection of properties that implementations of the API read and use..." to avoid the "here's a chunk of memory that can get passed into the API that it can operate on, and expect the caller to see the effects of the operation" interpretation. I think what the current text is trying to say is that the user of the API should assume the implementation of the API made its own private copy of the Object at the point of the given func() call and that it will not see any changes to the copy the user has at any later point. But then there's some text that looks like "Once a has been used with a func(), it is invalid to modify any of its properties." So...

Discussion:
Parameters.  Action and Event parameters whose names are suffixed with a question mark are optional. <del> Actions associated with no Object are Actions on the API; they are equivalent to Actions on a per-application global context. </del> <ins> Objects that are passed as parameters to Actions use call-by-value behavior.  Actions associated with no Object are Actions on the API; they are equivalent to Actions on a per-application global context. </ins> Events are sent to the application or application-supplied code (e.g. framers, see framing) for processing; the details of event processing

same properties. Properties can be added to a MessageContext object only before the <del> context is used for sending.  Once a messageContext has been used with a Send call, it is invalid to modify any of its properties. </del> <ins> context is used for sending.  Once a MessageContext has been used with a Send call, further modifications to the MessageContext object do not have any effect on this Send call. </ins> The Message Properties could be inconsistent with the properties of the Protocol Stacks underlying the Connection on which a given
Change:
This is the only place multicast considerations might fit in -arch. We don't discuss anycast at all, and I think it's largely orthogonal to transport (indeed, people seem to be running stateful/connection-oriented transports to anycast endpoints just fine in the Internet, even though it "doesn't work" :) )
Consider an explicit discussion of multicast/anycast considerations in this document.

Discussion:
transport connection.  Endpoints can be Local Endpoints or Remote Endpoints, and respectively represent an identity that the application uses for the source or destination of a connection. <del> An Endpoint can be specified at various levels of abstraction, and an Endpoint at a higher level of abstraction (such as a hostname) can be resolved to more concrete identities (such as IP addresses). </del> <ins> An Endpoint can be specified at various levels of abstraction.  An Endpoint at a higher level of abstraction (such as a hostname) can be resolved to more concrete identities (such as IP addresses). An endpoint may also represent a multicast group, in which case it selects a multicast transport for communication. </ins> Remote Endpoint: The Remote Endpoint represents the application's identifier for a peer that can participate in a transport
Change:
Would there be any benefit of having something like "WithServiceName" to qualify a specifier for use with NAPTR/SRV? Or is the thinking that the resolution of the thing handed down through WithHostname is restricted to A/AAAA?
yes, probably.
We do have this for mDNS services in Network.framework, and internally have tested with SRV. These are useful indeed.
Actually, doesn't WithService do this? Should we clarify that this can use SRV as opposed to just looking up in /etc/services.
Interim: Yes, this is a nice solution. Let's mention how to use withService for SRV types in the text.

Discussion:
Hostname (string): <del> Port (a 16-bit integer) or a Service (string) that maps to a port: </del> <ins> Port (a 16-bit integer): Service (an identifier that maps to a port; either a the name of a well-known service, or a DNS SRV service name to be resolved): </ins> IP address (IPv4 or IPv6 address):
Change:
The other option is to tell people to prepend the name of the framer to the property name.
Is the "scope" used for message contexts (9.1.1) ever anything but a framer? If not, could this section just say framer?
We believe that it is the same; if so, "scope" should probably indeed be named "framer". Tommy, could you please check?
I find this a little strange: given that we do have optional parameters, what's the benefit of first introducing the "add" and "get" calls as if the "framer" parameter didn't exist, and then later changing that? It would seem more consistent to me to introduce it where you had the scope parameter before, called "framer", and use a forward reference to say that framers will be explained later.

Discussion:
Message Properties can be set and queried using the Message Context: <del> To get or set Message Properties, the optional scope parameter is left empty.  To get or set meta-data for a Framer, the application has to pass a reference to this Framer as the scope parameter. </del> <ins> These Message Properties may be generic properties or Protocol Specific Properties. </ins> For MessageContexts returned by send Events (see send-events) and receive Events (see receive-events), the application can query

9.1.2.2. <del> When sending Messages, applications can add Framer-specific key/value pairs to a MessageContext (msg-ctx).  This mechanism can be used, for example, to set the type of a Message for a TLV format.  The namespace of values is custom for each unique Message Framer. </del> <ins> When sending Messages, applications can add Framer-specific properties to a MessageContext (msg-ctx).  In order to set these properties, the "add" and "get" actions on the MessageContext.  To avoid naming conflicts, the property names SHOULD be prefixed with a namespace referencing the framer implementation or the protocol it implements as described in property-names. This mechanism can be used, for example, to set the type of a Message for a TLV format.  The namespace of values is custom for each unique Message Framer. </ins> When an application receives a MessageContext in a Receive event, it can also look to see if a value was set by a specific Message Framer.
Change:
Satisfied
application/json is fine in the general sense, but if you want to ever do things like versioning, then a media type is important. Crib from if you want a recent example.
Discussed in London, consensus to use a new media type.
I am ok with the added text.

Discussion:
3.2. The Captive Portal API data structures are specified in JavaScript <del> Object Notation (JSON) RFC7159. </del> <ins> Object Notation (JSON) RFC7159.  Requests and responses for the Captive Portal API use the "application/captive+json" media type. Clients SHOULD include this media type as an Accept header in their GET requests, and servers MUST mark this media type as their Content- Type header in responses. </ins> The following keys are defined at the top-level of the JSON structure returned by the API server:

5. <del> TBD: None </del> <ins> This document registers the media type for Captive Portal API JSON text, "application/captive+json". application captive+json None None Encoding considerations are identical to those specified for the "application/json" media type. See This document specifies format of conforming messages and the interpretation thereof. This document This media type is intended to be used by servers presenting the Captive Portal API, and clients connecting to such captive networks. None See Authors' Addresses section. COMMON None CAPPORT IETF WG IETF </ins> 6.
Change:
Addresses , with the decisions made at the last IETF meeting
Added text based on Martin's suggestions
As David Bird pointed out, we should describe the model we assume for API server authentication. Then we need to describe the requirements on this. An important point here is that CRL or OCSP checking are likely to fail for a captive UE. A recommendation for servers to use OCSP stapling is likely necessary (whitelisting CRL or OCSP servers is probably workable, but OCSP stapling is a far superior solution).
This needs to mention AIA chasing as well. Some client implementations do that (others think that it's a crazy idea, but that's not a debate we need to enter into here).looks good.

Discussion:
"https://example.org/captive-portal/api/X54PD" <ins> 3.1.1. The purpose of accessing the Captive Portal API over an HTTPS connection is twofold: first, the encrypted connection protects the integrity and confidentiality of the API exhange from other parties on the local network; and second, it provides the client of the API an opportunity to authenticate the server that is hosting the API. This authentication is aimed at allowing a user to be reasonably confident that the entity providing the Captive Portal API has a valid certificate for the hostname in the URI (such as "example.com").  The hostname of the API SHOULD be displayed to the user in order to indicate the entity which is providing the API service. Clients performing revocation checking will need some means of accessing revocation information for certificates presented by the API server.  Online Certificate Status Protocol RFC6960 (OCSP) stapling, using the TLS Certificate Status Request extension RFC6066 SHOULD be used.  OCSP stapling allows a client to perform revocation checks without initiating new connections.  To allow for other forms of revocation checking, a captive network could permit connections to OCSP responders or Certificate Revocation Lists (CRLs) that are referenced by certificates provided by the API server. Certificates with missing intermediate certificates that rely on clients validating the certificate chain using the URI specified in the Authority Information Access (AIA) extension RFC5280 SHOULD NOT be used by the Captive Portal API server.  If the certificates do require the use of AIA, the captive network will need to allow client access to the host specified in the URI. If the client is unable to validate the certificate presented by the API server, it MUST NOT proceed with any of the behavior for API interaction described in this document.  The client will proceed to interact with the captive network as if the API capabilities were not present.  It may still be possible for the user to access the network by being redirected to a web portal. </ins> 3.2. The Captive Portal API data structures are specified in JavaScript
Change:
Adding a security considerations section to describe the security benefits that are added, along with the concern about trusting any hostnames even after authentication. I'd like to get some form of this in soon, and then rev the document before the IETF 105 cutoff.
thanks for starting this. looks like a good text to start with. Should we also propose something to the privacy section ?
We have a bit in the privacy section already, so I was going to leave it for now. If you have suggested text, let me know and I’ll add it!

Discussion:
5. <del> TBD: Provide complete security requirements and analysis. </del> <ins> One of the goals of this protocol is to improve the security of the communication between client hosts and Captive Portal systems. Client traffic is protected from passive listeners on the local network by requiring TLS-encrypted connections between the client and the Captive Portal API server, as described in api-details.  All communication between the clients and the API server MUST be encrypted. In addition to encrypting communications between clients and Captive Portal systems, this protocol requires a basic level of authentication from the API server, as described in server-auth. Specifically, the API server MUST present a valid certificate on which the client can perform revocation checks.  This allows the client to ensure that the API server has authority for a hostname that can be presented to a user. It is important to note that while the server authentication checks can validate a specific hostname, it is certainly possible for the API server to present a valid certificate for a hostname that uses non-standard characters or is otherwise designed to trick the user into believing that its hostname is some other, more trustworthy, name.  This is a danger of any scenario in which a hostname is not typed in by a user. </ins> 5.1.
Change:
Completes
As discussed in the IETF hackathon/informal meeting, the consensus is to change expire-date (an absolute iso datetime) to seconds-remaining integer (named after bytes-remaining)
This was already done!
thanks, missed that
The draft currently specifies a deadline as an absolute time. Experience with implementation showed that time remaining (in seconds) was easier to implement and less subject to the vagaries of clock differences.

Discussion:
it wishes to share with the user (e.g., store info, maps, flight status, or entertainment). <del> "expire-date" (optional, string formatted as RFC3339 datetime): indicates the date and time after which the client will be in a </del> <ins> "seconds-remaining" (optional, integer): indicates the number of seconds remaining, after which the client will be placed into a </ins> captive state.  The API server SHOULD include this value if the client is not captive (i.e. captive=false) and SHOULD omit this value for captive clients.
Change:
Self-approved
Thanks, this does a good job bridging the gap between what we say in the body of the document and what is available in external references.

Discussion:
and 'ietf-tcg-algs.yang' ref-ietf-tcg-algs with prefix 'taa'. Additionally, references are made to RFC8032, RFC8017, RFC6933, TPM1.2-Commands, TPM2.0-Arch, TPM2.0-Structures, TPM2.0-Key, <del> TPM1.2-Structures, bios-log, ima-log, BIOS-Log-Event-Type and netequip-boot-log. </del> <ins> TPM1.2-Structures, bios-log, ima-log, BIOS-Log-Event-Type, as well as ima and netequip-boot-log. </ins> 2.1.1.1.

UEFI event logs. 'ima': Indicates that the device supports the retrieval of event <del> logs from the Linux Integrity Measurement Architecture (IMA). </del> <ins> logs from the Linux Integrity Measurement Architecture (IMA ima- log).  Also see ima. </ins> 'netequip_boot': Indicates that the device supports the retrieval <del> of netequip boot event logs. </del> <ins> of netequip boot event logs.  See ima and netequip-boot-log. </ins> 2.1.1.2.

10118-3, ISO-IEC-14888-3, ISO-IEC-15946-1, ISO-IEC-18033-3, IEEE-Std- 1363-2000, IEEE-Std-1363a-2004, NIST-PUB-FIPS-202, NIST-SP800-38C, NIST-SP800-38D, NIST-SP800-38F, NIST-SP800-56A, NIST-SP800-108, bios- <del> log, ima-log, and netequip-boot-log exist within the YANG Model. </del> <ins> log, ima-log, as well as ima and netequip-boot-log exist within the YANG Model. </ins> 2.1.2.1.