jiebi/TextFlow huggingface dataset:
Original text:
Selection properties are represented as preferences, which can have one of five preference levels:  Internally, the transport system will first exclude all protocols and paths that match a Prohibit, then exclude all protocols and paths that do not match a Require, then sort candidates according to

Reviewer comments:
This closes issue
Weren't we supposed to stop making PRs and issues until March 5? See Zahed's email to the TAPS list
NAME sorry – I did not read list mails since yesterday morning.
Yes, let's hold off on these until we move repos!
We discussed the use of a "Default" preference level that restores the system default in . In addition, we should check whether we really need to fix the default values for all Selection Properties in the API document or can make some of them to be "Implementation Specific".
Closed by PR
Looks good to me.

Revised text:
Selection properties are represented as preferences, which can have one of five preference levels: <ins> In addition, the pseudo-level "Default" can be used to reset the property to the default level used by the implementation.  This level will never show up when queuing the value of a preference - the effective preference must be returned instead. </ins> Internally, the transport system will first exclude all protocols and paths that match a Prohibit, then exclude all protocols and paths that do not match a Require, then sort candidates according to
Original text:
Message representing the body, and the Headers being provided in Message metadata.  9.6. QUIC provides a multi-streaming interface to an encrypted transport.

Reviewer comments:
Starting to address This is an early review, to check if we like the structure. I'd also like help filling out the SCTP section!
I can also help with SCTP, which I would do in the same style that I suggest above (for TCP, in my example of "Abort") - also later.
We've updated Implementation mapping details for most protocols with , but we didn't tackle SCTP yet.
I'm fine with this being assigned to me. However, it's more than just writing the SCTP text. Here's the relevant part of what I wrote in PR : I don't suggest to delete much of the text that's there but definitely amend it with the RFC reference at least for what's covered in RFC 8303. There's a very direct line from this type of text in RFC 8303 to the original specs, so I do believe that should be helpful. That's (obviously) post-Montreal though!
NAME please send a PR along these lines.
LGTM modulo mwelzl changes.I think this is a good step forward. This said, I think we should describe things focusing on the transport's API call to be made (in line with the spec - that's why we have RFCs 8303 and 8304) rather than protocol internals. E.g., rather than saying that Abort on a TCP connection transmits a RST, I think we should simply say that Abort calls ABORT.TCP [RFC 8303, Section 4.1]. I can take care of these things, later. I'd still like to focus more on the API doc at this time.

Revised text:
Message representing the body, and the Headers being provided in Message metadata. <ins> Connectedness: Multiplexing Connected Data Unit: Message Connection objects represent a flow of HTTP messages between a client and a server, which may be an HTTP/1.1 connection over TCP, or a single stream in an HTTP/2 connection. Calling "Initiate" on an HTTP connection intiates a TCP or TLS connection as a client. Calling "Clone" on an HTTP Connection opens a new stream on an existing HTTP/2 connection when possible.  If the underlying version does not support multiplexed streams, calling "Clone" simply creates a new parallel connection. When an application sends an HTTP Message, it is expected to provide HTTP header values as a MessageContext in a canonical form, along with any associated HTTP message body as the Message data.  The HTTP header values are encoded in the specific version format upon sending. HTTP Connections deliver Messages in which HTTP header values attached to MessageContexts, and HTTP bodies in Message data. Calling "Close" on an HTTP Connection will only close the underlying TLS or TCP connection if the HTTP version does not support multiplexing.  For HTTP/2, for example, closing the connection only closes a specific stream. </ins> 9.6. QUIC provides a multi-streaming interface to an encrypted transport.
Original text:
Closing a single QUIC stream, presented to the application as a Connection, does not imply closing the underlying QUIC connection itself.  Rather, the implementation may choose to close the QUIC <del> connection once all streams have been closed (possibly after some </del>  timeout), or after an individual stream Connection sends an Abort. <del> Messages over a direct QUIC stream should be represented similarly to the TCP stream (one Message per direction, see tcp), unless a framing mapping is used on top of QUIC. </del>  9.7.

Reviewer comments:
Starting to address This is an early review, to check if we like the structure. I'd also like help filling out the SCTP section!
I can also help with SCTP, which I would do in the same style that I suggest above (for TCP, in my example of "Abort") - also later.
We've updated Implementation mapping details for most protocols with , but we didn't tackle SCTP yet.
I'm fine with this being assigned to me. However, it's more than just writing the SCTP text. Here's the relevant part of what I wrote in PR : I don't suggest to delete much of the text that's there but definitely amend it with the RFC reference at least for what's covered in RFC 8303. There's a very direct line from this type of text in RFC 8303 to the original specs, so I do believe that should be helpful. That's (obviously) post-Montreal though!
NAME please send a PR along these lines.
LGTM modulo mwelzl changes.I think this is a good step forward. This said, I think we should describe things focusing on the transport's API call to be made (in line with the spec - that's why we have RFCs 8303 and 8304) rather than protocol internals. E.g., rather than saying that Abort on a TCP connection transmits a RST, I think we should simply say that Abort calls ABORT.TCP [RFC 8303, Section 4.1]. I can take care of these things, later. I'd still like to focus more on the API doc at this time.

Revised text:
Closing a single QUIC stream, presented to the application as a Connection, does not imply closing the underlying QUIC connection itself.  Rather, the implementation may choose to close the QUIC  <ins> connection once all streams have been closed (often after some </ins> timeout), or after an individual stream Connection sends an Abort.  <ins> Connectedness: Multiplexing Connected Data Unit: Stream Connection objects represent a single QUIC stream on a QUIC connection. </ins> 9.7.
Original text:
to force early binding when required, for example with some Network Address Translator (NAT) traversal protocols (see rendezvous).  5.2. A Preconnection Object holds properties reflecting the application's

Reviewer comments:
Maybe add the ASN source address (set source address), source filter (add remote addresses)? Maybe also add that for sending, you specify the group as remote and the socket becomes write-only? Should we require specifying direction? This would be slightly harder to use, but future proof in case someone implements reliable ASN on TAPS…
We need unidirectional connections. You know, for multicast. And ICN. And unidirectional streaming protocols.
This is a dup of , which has more discussion
I am re-opening this ticket as only dealt with unidirectional streams in unicast context (added with PR ): Current status: The current model for unidirectional streams supports half-closed connections and QUIC style unidirectional streams so far. We don't know yet whether it is sufficient to have canread/canwrite property on the connection level to model unidirectional connections We don't have pre-connection methods to create multicast sessions yet
there's a selection property for this, tagged discuss, which we haven't discussed yet. I'm moving this down to the appendix as part of my restructuring in my work on
If help is still wanted here, I'm maybe up for an attempt or 2 at adding multicast support. Has there been some prior discussion I can review about rough ideas on pre-connection methods for multicast sessions, or should I just try making something up?
lgtm

Revised text:
to force early binding when required, for example with some Network Address Translator (NAT) traversal protocols (see rendezvous). <ins> Specifying a multicast group address on the Local Endpoint will indicate to the transport system that the resulting connection will be used to receive multicast messages.  The Remote Endpoint can be used to filter by specific senders.  This will restrict the application to establishing the Preconnection by calling Listen(). The accepted Connections are receive-only. Similarly, specifying a multicast group address on the Remote Endpoint will indicate that the resulting connection will be used to send multicast messages. </ins> 5.2. A Preconnection Object holds properties reflecting the application's
Original text:
Integer (non-negative with -1 as special value) <del> full coverage </del>  This property specifies the minimum length of the section of the Message, starting from byte 0, that the application requires to be

Reviewer comments:
I'm not quite sure what I meant by "Only full coverage is guaranteed, any other requests are advisory". I assume we mean that even if a partial checksum is requested you get full coverage because requesting partial coverage and getting no checksum doesn't seem right...?
Exactly, and you made it clearer. Thanks!

Revised text:
Integer (non-negative with -1 as special value)  <ins> -1 (full coverage) </ins> This property specifies the minimum length of the section of the Message, starting from byte 0, that the application requires to be
Original text:
to specify options for simple integrity protection via checksums.  A value of 0 means that no checksum is required, and -1 means that the entire Message is protected by a checksum.  Only full coverage is <del> guaranteed, any other requests are advisory. </del>  7.4.7.

Reviewer comments:
I'm not quite sure what I meant by "Only full coverage is guaranteed, any other requests are advisory". I assume we mean that even if a partial checksum is requested you get full coverage because requesting partial coverage and getting no checksum doesn't seem right...?
Exactly, and you made it clearer. Thanks!

Revised text:
to specify options for simple integrity protection via checksums.  A value of 0 means that no checksum is required, and -1 means that the entire Message is protected by a checksum.  Only full coverage is  <ins> guaranteed, any other requests are advisory, meaning that full coverage is applied anyway. </ins> 7.4.7.
Original text:
Specify a Local Endpoint using a local interface name and local port:  Specify a Local Endpoint using a STUN server: Specify a Local Endpoint using a Any-Source Multicast group to join

Reviewer comments:
In the "Specifying Endpoints" section, added a reference to the Selection Property that does a similar thing but with more fine-grained control. It wasn't clear to me what is the best place to add this, so I put it right below the first example of specifying an interface name for the Local Endpoint to say that you can also do it differently. If you have better suggestions, please let me know. To the ListenError and RendezvousError, I added text mentioning the "reconcile Endpoints and Properties" pitfall. I think this is probably more general, i.e., there might be more sources of errors than just local interface, so I kept it generic.
For Local Address Preference we only have the option to prefer stable or temporary. However, I guess we would also need a way to e.g. specify that stable is required, no?
Is this addressed by PR ?
I don't think so.
When reading the current API draft, I was wondering the following: If an application wants to specify one or multiple local network interfaces, it can either set the Local Endpoint(s) or it can set the "Interface Instance or Type" Selection Property. I think both ways are valid and should exist, but I'm wondering if we should specify anything on the interaction of these two ways to do a similar thing. For example, should we explicitly mention the Selection Property in Section 5.1 ("Specifying Endpoints"), to make readers aware that there is a "better" way to do this, which allows more flexibility? Also, if an application specifies conflicting things, I guess this leads to an InitiateError, ListenError, or RendezvousError. Our current text already says this for the InitiateError: But should we make this particular issue more explicit here and/or should we add it for the ListenError or RendezvousError?
I think so, yes! Regarding the error in case of a conflict: I think so, yes - to all your questions: make it more explicit, state it in the description of both the ListenError and RendezvousError. Just my 2 cents
Thank you - works for me!

Revised text:
Specify a Local Endpoint using a local interface name and local port: <ins> As an alternative to specifying an interface name for the Local Endpoint, an application can express more fine-grained preferences using the "Interface Instance or Type" Selection Property, see prop- interface.  However, if the application specifies Selection Properties which are inconsistent with the Local Endpoint, this will result in an error once the application attempts to open a Connection. </ins> Specify a Local Endpoint using a STUN server: Specify a Local Endpoint using a Any-Source Multicast group to join
Original text:
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 of the Preconnection cannot be fulfilled for listening, when the Local Endpoint (or Remote Endpoint, if specified) cannot be resolved, or when the application is prohibited from listening by policy. </del>  A Stopped Event occurs after the Listener has stopped listening.

Reviewer comments:
In the "Specifying Endpoints" section, added a reference to the Selection Property that does a similar thing but with more fine-grained control. It wasn't clear to me what is the best place to add this, so I put it right below the first example of specifying an interface name for the Local Endpoint to say that you can also do it differently. If you have better suggestions, please let me know. To the ListenError and RendezvousError, I added text mentioning the "reconcile Endpoints and Properties" pitfall. I think this is probably more general, i.e., there might be more sources of errors than just local interface, so I kept it generic.
For Local Address Preference we only have the option to prefer stable or temporary. However, I guess we would also need a way to e.g. specify that stable is required, no?
Is this addressed by PR ?
I don't think so.
When reading the current API draft, I was wondering the following: If an application wants to specify one or multiple local network interfaces, it can either set the Local Endpoint(s) or it can set the "Interface Instance or Type" Selection Property. I think both ways are valid and should exist, but I'm wondering if we should specify anything on the interaction of these two ways to do a similar thing. For example, should we explicitly mention the Selection Property in Section 5.1 ("Specifying Endpoints"), to make readers aware that there is a "better" way to do this, which allows more flexibility? Also, if an application specifies conflicting things, I guess this leads to an InitiateError, ListenError, or RendezvousError. Our current text already says this for the InitiateError: But should we make this particular issue more explicit here and/or should we add it for the ListenError or RendezvousError?
I think so, yes! Regarding the error in case of a conflict: I think so, yes - to all your questions: make it more explicit, state it in the description of both the ListenError and RendezvousError. Just my 2 cents
Thank you - works for me!

Revised text:
higher value.  By default, this value is Infinite.  The caller is also able to reset the value to Infinite at any point.  <ins> A ListenError occurs either when the Properties and Security 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 specified) cannot be resolved, or when the application is prohibited from listening by policy. </ins> A Stopped Event occurs after the Listener has stopped listening.
Original text:
The Transport Services architecture evolves this general model of interaction, aiming to both modernize the API surface presented to applications by the transport layer and enrich the capabilities of <del> the Transport System implementation.  It combines interfaces for </del>  multiple interaction patterns into a unified whole.  By combining name resolution with connection establishment and data transfer in a single API, it allows for more flexible implementations to provide

Reviewer comments:
Addresses
In the architecture document, I noticed that we sometimes say "Transport Services system" and sometimes "Transport System". Are these the same? Are "Transport Services implementation" and "Transport System implementation" the same, too?
I prefer "Transport Services system" and "Transport Services implementation"
I find it long and clumsy :( Side note: we'll have to rename it everywhere in the API draft too if we go with this.
was this fixed by ?
Yes it was. We already used Transport Services most places so it's not all that different.
Looks good, thanks!

Revised text:
The Transport Services architecture evolves this general model of interaction, aiming to both modernize the API surface presented to applications by the transport layer and enrich the capabilities of  <ins> the Transport Services implementation.  It combines interfaces for </ins> multiple interaction patterns into a unified whole.  By combining name resolution with connection establishment and data transfer in a single API, it allows for more flexible implementations to provide
Original text:
make use of the data that arrived; the ability to manage dependencies between messages, when the <del> Transport System could decide to not deliver a message, either following packet loss or because it has missed a deadline.  In particular, this can avoid (re-)sending data that relies on a </del>  previous transmission that was never received. the ability to automatically assign messages and connections to

Reviewer comments:
Addresses
In the architecture document, I noticed that we sometimes say "Transport Services system" and sometimes "Transport System". Are these the same? Are "Transport Services implementation" and "Transport System implementation" the same, too?
I prefer "Transport Services system" and "Transport Services implementation"
I find it long and clumsy :( Side note: we'll have to rename it everywhere in the API draft too if we go with this.
was this fixed by ?
Yes it was. We already used Transport Services most places so it's not all that different.
Looks good, thanks!

Revised text:
make use of the data that arrived; the ability to manage dependencies between messages, when the  <ins> Transport Services system could decide to not deliver a message, either following packet loss or because it has missed a deadline. In particular, this can avoid (re-)sending data that relies on a </ins> previous transmission that was never received. the ability to automatically assign messages and connections to
Original text:
Transport Properties: Transport Properties allow the application to express their requirements, prohibitions, and preferences and <del> configure the Transport System.  There are three kinds of </del>  Transport Properties: Selection Properties (preestablishment) that can only be

Reviewer comments:
Addresses
In the architecture document, I noticed that we sometimes say "Transport Services system" and sometimes "Transport System". Are these the same? Are "Transport Services implementation" and "Transport System implementation" the same, too?
I prefer "Transport Services system" and "Transport Services implementation"
I find it long and clumsy :( Side note: we'll have to rename it everywhere in the API draft too if we go with this.
was this fixed by ?
Yes it was. We already used Transport Services most places so it's not all that different.
Looks good, thanks!

Revised text:
Transport Properties: Transport Properties allow the application to express their requirements, prohibitions, and preferences and  <ins> configure the Transport Services system.  There are three kinds of </ins> Transport Properties: Selection Properties (preestablishment) that can only be
Original text:
Connection Properties: The Connection Properties are used to configure protocol-specific options and control per-connection <del> behavior of the Transport System; for example, a protocol-specific Connection Property can express that if UDP is used, the implementation ought to use checksums.  Note that the presence of such a property does not require that a specific protocol will be used.  In general, these properties do not explicitly determine the selection of paths or protocols, but can be used in this way by an implementation during connection establishment.  Connection Properties are specified on a Preconnection prior to Connection establishment, and can be modified on the Connection later. Changes made to Connection Properties after Connection establishment take effect on a best-effort basis. </del>  4.1.3.

Reviewer comments:
Addresses
In the architecture document, I noticed that we sometimes say "Transport Services system" and sometimes "Transport System". Are these the same? Are "Transport Services implementation" and "Transport System implementation" the same, too?
I prefer "Transport Services system" and "Transport Services implementation"
I find it long and clumsy :( Side note: we'll have to rename it everywhere in the API draft too if we go with this.
was this fixed by ?
Yes it was. We already used Transport Services most places so it's not all that different.
Looks good, thanks!

Revised text:
Connection Properties: The Connection Properties are used to configure protocol-specific options and control per-connection  <ins> behavior of the Transport Services system; for example, a protocol-specific Connection Property can express that if UDP is used, the implementation ought to use checksums.  Note that the presence of such a property does not require that a specific protocol will be used.  In general, these properties do not explicitly determine the selection of paths or protocols, but can be used in this way by an implementation during connection establishment.  Connection Properties are specified on a Preconnection prior to Connection establishment, and can be modified on the Connection later.  Changes made to Connection Properties after Connection establishment take effect on a best- effort basis. </ins> 4.1.3.