Re: [quicwg/base-drafts] Define terms for application actions (#2857)

[Martin Thomson <[e-mail]>]

martinthomson commented on this pull request.

Thanks for doing this Mike, I have quite a few comments.

> @@ -452,12 +452,12 @@ HTTP_INCOMPLETE_REQUEST.
 
 A server can send a complete response prior to the client sending an entire
 request if the response does not depend on any portion of the request that has
-not been sent and received. When this is true, a server MAY request that the
-client abort transmission of a request without error by triggering a QUIC
-STOP_SENDING frame with error code HTTP_EARLY_RESPONSE, sending a complete
-response, and cleanly closing its stream. Clients MUST NOT discard complete
-responses as a result of having their request terminated abruptly, though
-clients can always discard responses at their discretion for other reasons.
+not been sent and received. When this is true, a server MAY abort reading the
+receiving part of the request stream with error code HTTP_EARLY_RESPONSE, send a

Do you think that we can just say "abort reading the request stream" and drop the  "receiving part of" piece on the basis that "abort reading" can only apply to the receiving part?

> @@ -505,11 +505,11 @@ this limit are not guaranteed to be accepted.
 
 ### Request Cancellation and Rejection {#request-cancellation}
 
-Clients can cancel requests by aborting the stream (QUIC RESET_STREAM and/or
-STOP_SENDING frames, as appropriate) with an error code of
-HTTP_REQUEST_CANCELLED ({{http-error-codes}}).  When the client cancels a
-response, it indicates that this response is no longer of interest.
-Implementations SHOULD cancel requests by aborting both directions of a stream.
+Clients can cancel requests by abruptly terminating the sending part of the

"abruptly terminating" or just "resetting" ?

> @@ -1590,8 +1584,9 @@ the cause of a connection or stream error.
 
 ## HTTP/3 Error Codes {#http-error-codes}
 
-The following error codes are defined for use in QUIC RESET_STREAM frames,
-STOP_SENDING frames, and CONNECTION_CLOSE frames when using HTTP/3.
+The following error codes are defined for use when abruptly terminating the
+sending part of streams, aborting reading of the receiving part of streams, or

As above regarding reference to "parts".

> @@ -1718,8 +1713,8 @@ extension is disabled if the setting is omitted.
 The security considerations of HTTP/3 should be comparable to those of HTTP/2
 with TLS.  Note that where HTTP/2 employs PADDING frames and Padding fields in
 other frames to make a connection more resistant to traffic analysis, HTTP/3 can
-rely on QUIC PADDING frames or employ the reserved frame and stream types
-discussed in {{frame-grease}} and {{stream-grease}}.
+either rely on transport-layer padding or employ the reserved frame and stream
+types discussed in {{frame-grease}} and {{stream-grease}}.

Aside: we should probably have a conversation about the trade-offs with padding.  Transport-layer padding is in some ways superior, like in how it can be granular to a single byte, which reserved streams and frames cannot do.  But PADDING frames at the transport aren't retransmitted when lost, which could lead to some interesting attacks if packets can be suppressed by an attacker.  If retransmissions aren't padded, boom.

> @@ -345,6 +345,31 @@ the relative priority of streams.  When deciding which streams to dedicate
 resources to, the implementation SHOULD use the information provided by the
 application.
 
+## Required Operations on Streams
+
+There are certain operations which an application MUST be able to perform when
+interacting with QUIC streams.  This document does not specify an API, but
+any implementation of this version of QUIC MUST expose the ability to perform
+the operations described in this section on a QUIC stream.
+
+On the sending part of a stream:
+
+- Attempt to write data, understanding when stream flow control credit

List construction here implies continuation of a sentence, but the capital letter doesn't fit and there is no joiner.

I think that you want:

> On the sending part of a stream, application protocols need to be able to:
> * write data, understanding when .... ({{frame-stop-sending}});
> * end the stream, ....; and
> * reset the stream ... was already ended.


> @@ -345,6 +345,31 @@ the relative priority of streams.  When deciding which streams to dedicate
 resources to, the implementation SHOULD use the information provided by the
 application.
 
+## Required Operations on Streams
+
+There are certain operations which an application MUST be able to perform when
+interacting with QUIC streams.  This document does not specify an API, but
+any implementation of this version of QUIC MUST expose the ability to perform
+the operations described in this section on a QUIC stream.
+
+On the sending part of a stream:
+
+- Attempt to write data, understanding when stream flow control credit
+  ({{data-flow-control}}) has successfully been reserved to send the written
+  data or possibly discovering that the stream has been closed because the peer

I think that you might remove this "possibly discovering" clause.  Then add a new separate paragraph after the lists that says that application protocols will want to be informed about stream state changes and events, including when data is available, when the stream ends, is reset, or reading has been aborted by a peer, and when new streams are created by a peer.

As a general rule, I don't like having sections end on a list, so that would help with my little compulsion too.

> @@ -1101,6 +1126,38 @@ suggested structure:
 -->
 
 
+## Required Operations on Connections
+
+There are certain operations which an application MUST be able to perform when
+interacting with the QUIC transport.  This document does not specify an API, but
+any implementation of this version of QUIC MUST expose the ability to perform
+the operations described in this section on a QUIC connection.
+
+When implementing the client role:

Same list construction comment as above.

> @@ -1101,6 +1126,38 @@ suggested structure:
 -->
 
 
+## Required Operations on Connections
+
+There are certain operations which an application MUST be able to perform when
+interacting with the QUIC transport.  This document does not specify an API, but
+any implementation of this version of QUIC MUST expose the ability to perform
+the operations described in this section on a QUIC connection.
+
+When implementing the client role:
+
+- Open a connection, which begins the exchange described in {{handshake}}

Add: to enable 0-RTT, and to be informed when 0-RTT has been either accepted or rejected by a server.

> +interacting with the QUIC transport.  This document does not specify an API, but
+any implementation of this version of QUIC MUST expose the ability to perform
+the operations described in this section on a QUIC connection.
+
+When implementing the client role:
+
+- Open a connection, which begins the exchange described in {{handshake}}
+
+When implementing the server role:
+
+- Listen for incoming connections, which prepares for the exchange described in
+  {{handshake}}
+- If Early Data is supported, embed application-controlled data in the TLS
+  resumption ticket sent to the client
+- If Early Data is supported, retrieve application-controlled data from the
+  client's resumption ticket and approve/veto accepting Early Data

and enable rejection of 0-RTT based on that information

I don't like "veto" much here.  And we don't need to have an active acceptance involved.

> +
+- Open a connection, which begins the exchange described in {{handshake}}
+
+When implementing the server role:
+
+- Listen for incoming connections, which prepares for the exchange described in
+  {{handshake}}
+- If Early Data is supported, embed application-controlled data in the TLS
+  resumption ticket sent to the client
+- If Early Data is supported, retrieve application-controlled data from the
+  client's resumption ticket and approve/veto accepting Early Data
+
+In either role:
+
+- Configure minimum values for the initial number of permitted streams of each
+  type, as communicated in the transport parameters ({{transport-parameters}})

I think that there is a more general point, which basically means controlling resource allocation of all types, including streams and flow control.

The point you are looking at here - setting a minimum on the number of streams - is something HTTP needs, so I would add rather than replace.

> +
+- Listen for incoming connections, which prepares for the exchange described in
+  {{handshake}}
+- If Early Data is supported, embed application-controlled data in the TLS
+  resumption ticket sent to the client
+- If Early Data is supported, retrieve application-controlled data from the
+  client's resumption ticket and approve/veto accepting Early Data
+
+In either role:
+
+- Configure minimum values for the initial number of permitted streams of each
+  type, as communicated in the transport parameters ({{transport-parameters}})
+- Keep a connection from silently closing, either by generating PING frames
+  ({{frame-ping}}) or by requesting that the transport send additional frames
+  before the idle timeout expires ({{idle-timeout}})
+- Cease issuing credit for new streams via MAX_STREAMS frames

See the above point about controlling resource allocation.

-- 
You are receiving this because you are subscribed to this thread.
Reply to this email directly or view it on GitHub:
https://github.com/quicwg/base-drafts/pull/2857#pullrequestreview-255536084