jiebi/TextFlow huggingface dataset:
Original text:
Explicit support for multistreaming and multipath transport protocols, and the grouping of related Connections into Connection <del> Groups through cloning of Connections.  This allows applications to take full advantage of new transport protocols supporting these features. </del>  3.

Reviewer comments:
The concept of cloning is used in the overview without introduction. I've suggested an earlier discussion of it in the architecture document, which would help, but even in this document, there should be an introduction or forward reference.

Revised text:
Explicit support for multistreaming and multipath transport protocols, and the grouping of related Connections into Connection  <ins> Groups through "cloning" of Connections (see groups).  This function allows applications to take full advantage of new transport protocols supporting these features. </ins> 3.
Original text:
Transport Properties are referred to by property names.  For the purposes of this document, these names are alphanumeric strings in <del> which words may be separated by hyphens.  These names serve two purposes: </del>  Allowing different components of a TAPS implementation to pass Transport Properties, e.g., between a language frontend and a

Reviewer comments:
Note that this PR does not say only the following characters are allowed... it just lists some that are allowed.
At the discussion of Transport Property Names at 4.1, I think you need to be more specific than "alphanumeric". Explicitly list what characters are allowed.
Since we've overspecified already: [A-Za-z0-9_]
Or go back to underspecifying: say they're human-readable textual labels that have namespaces, and don't specify the syntax of exactly how that namespacing works.

Revised text:
Transport Properties are referred to by property names.  For the purposes of this document, these names are alphanumeric strings in  <ins> which words may be separated by hyphens.  Specifically, the following characters are allowed: lowercase letters "a-z", uppercase letters "A-Z", digits "0-9", the hyphen "-", and the underscore "_".  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
Original text:
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>  The Transport Services API also delivers events regarding the lifetime of a connection and changes in the available network links,

Reviewer comments:
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.

Revised text:
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  <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,
Original text:
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>  access to the minimal set of features offered by transport protocols RFC8923.

Reviewer comments:
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.

Revised text:
Any functionality that is common across multiple transport protocols SHOULD be made accessible through a unified set of Transport Services  <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.
Original text:
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>  The application can set and query Connection Properties on a per- Connection basis.  Connection Properties that are not read-only can

Reviewer comments:
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.

Revised text:
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  <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
Original text:
match all Protocol Selection Properties that the application specified on the Preconnection. <del> For Connections that are Established: Information concerning the </del>  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

Reviewer comments:
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.

Revised text:
match all Protocol Selection Properties that the application specified on the Preconnection.  <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
Original text:
6.2.7. <del> FullChecksumSend </del>  Preference 6.2.8. <del> FullChecksumRecv </del>  Preference

Reviewer comments:
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.

Revised text:
6.2.7.  <ins> fullChecksumSend </ins> Preference 6.2.8.  <ins> fullChecksumRecv </ins> Preference
Original text:
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>  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>  The Message Properties could be inconsistent with the properties of the Protocol Stacks underlying the Connection on which a given

Reviewer comments:
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...

Revised text:
Parameters.  Action and Event parameters whose names are suffixed with a question mark are optional.  <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  <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
Original text:
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>  Remote Endpoint: The Remote Endpoint represents the application's identifier for a peer that can participate in a transport

Reviewer comments:
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.

Revised text:
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.  <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
Original text:
Hostname (string): <del> Port (a 16-bit integer) or a Service (string) that maps to a port: </del>  IP address (IPv4 or IPv6 address):

Reviewer comments:
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.

Revised text:
Hostname (string):  <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):
Original text:
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>  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>  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.

Reviewer comments:
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.

Revised text:
Message Properties can be set and queried using the Message Context:  <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.  <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.
Original text:
3.2. The Captive Portal API data structures are specified in JavaScript <del> Object Notation (JSON) RFC7159. </del>  The following keys are defined at the top-level of the JSON structure returned by the API server: 5. <del> TBD: None </del>  6.

Reviewer comments:
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.

Revised text:
3.2. The Captive Portal API data structures are specified in JavaScript  <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.  <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.
Original text:
"https://example.org/captive-portal/api/X54PD"  3.2. The Captive Portal API data structures are specified in JavaScript

Reviewer comments:
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.

Revised text:
"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
Original text:
5. <del> TBD: Provide complete security requirements and analysis. </del>  5.1.

Reviewer comments:
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!

Revised text:
5.  <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.