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

From: Mike Bishop <[email-masked]>
Date: Fri, 02 Aug 2019 10:38:01 -0700

MikeBishop commented on this pull request.

> @@ -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 resetting the request stream with an error code
+of HTTP_REQUEST_CANCELLED ({{http-error-codes}}).  When the client aborts
+reading a response, it indicates that this response is no longer of interest.
+Implementations SHOULD cancel requests by terminating both directions of a

The terms "clean termination" and "abrupt termination" are given as synonyms for "end the stream" and "reset the stream" in -transport line 361.  I should specify the termination type here.

> -least one unidirectional stream for the HTTP control stream plus the number of
-unidirectional streams required by mandatory extensions (such as QPACK) by
-setting an appropriate value for the QUIC transport parameter
-`initial_max_uni_streams` (three being the minimum value required for the base
-HTTP/3 protocol and QPACK), and SHOULD use a value of 1,024 or greater for the
-QUIC transport parameter `initial_max_stream_data_uni`.
+Endpoints that excessively restrict the number or flow control window of these
+streams will increase the chance that the remote peer reaches the limit early
+and becomes blocked. In particular, implementations should consider that remote
+peers may wish to exercise reserved stream behavior ({{stream-grease}}) with
+some of the unidirectional streams they are permitted to use. To avoid blocking,
+both clients and servers MUST allow the peer to create at least one
+unidirectional stream for the HTTP control stream plus the number of
+unidirectional streams required by mandatory extensions (three being the minimum
+number required for the base HTTP/3 protocol and QPACK), and SHOULD provide at
+least 1,024 bytes of flow control credit to each stream.

Good point.  I personally think they're equivalent, but I believe our consensus was to require it to be in the transport parameters.  I added a phrase to clarify this.

> @@ -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

Already created this list, but didn't adjust this bullet point.  Fixed.

> @@ -1101,6 +1132,41 @@ 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, applications need to be able to:
+
+- open a connection, which begins the exchange described in {{handshake}};
+- enable 0-RTT; and
+- be informed when 0-RTT has been accepted or rejected by a server.

The client needs to know because rejection resets the state of all streams; the client has to know whether to start over.

-- 
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#discussion_r304095084

---

From: Mike Bishop <[email-masked]>
Date: Fri, 02 Aug 2019 10:45:34 -0700

+When implementing the client role, applications need to be able to:
+
+- open a connection, which begins the exchange described in {{handshake}};
+- enable 0-RTT; and
+- be informed when 0-RTT has been accepted or rejected by a server.
+
+When implementing the server role, applications need to be able to:
+
+- 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; and
+- if Early Data is supported, retrieve application-controlled data from the
+  client's resumption ticket and enable rejecting Early Data based on that
+  information.

Added to stream requirements, but now I'm not so sure that's correct.  Early-Data has to be added when the server "forwards a request prior to the completion of the TLS handshake".  That would mean the server really only needs a yes/no about the current state of the connection when the request is being forwarded.  If the handshake has completed, it doesn't matter that the request was originally early -- it's now retroactively validated as a non-replay by the successful handshake.

-- 
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#discussion_r310233324

---

From: Mike Bishop <[email-masked]>
Date: Fri, 02 Aug 2019 10:48:18 -0700

@MikeBishop pushed 1 commit.

a66d991cb88012958ed4f2511ade4a789a5554b3  Early-Data isn't per-stream, it's connection handshake state

-- 
You are receiving this because you are subscribed to this thread.
View it on GitHub:
https://github.com/quicwg/base-drafts/pull/2857/files/ca7b3edfc59210ac3c4cfabf2dc7ffeacb40ce88..a66d991cb88012958ed4f2511ade4a789a5554b3

---

From: Mike Bishop <[email-masked]>
Date: Fri, 02 Aug 2019 10:54:46 -0700

@janaiyengar and @martinthomson, I think this is mergeable from an HTTP standpoint.  Since it's technically a requirements change (requiring that functionality be exposed), it probably needs to be marked for a consensus call when you think it's ready.

-- 
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#issuecomment-517791309

---

From: Martin Thomson <[email-masked]>
Date: Sun, 04 Aug 2019 17:09:11 -0700

martinthomson commented on this pull request.

 -->

It absolutely needs to know about this because 0-RTT rejection implies the need to start over in some cases.  You can't just treat 0-RTT as "lost".

> @@ -638,11 +666,14 @@ Note (*1):
 
 ## Solicited State Transitions
 
-If an endpoint is no longer interested in the data it is receiving on a stream,
-it MAY send a STOP_SENDING frame identifying that stream to prompt closure of
-the stream in the opposite direction.  This typically indicates that the
-receiving application is no longer reading data it receives from the stream, but
-it is not a guarantee that incoming data will be ignored.
+If an application is no longer interested in the data it is receiving on a
+stream, it can abort reading the stream and specify an application error code.
+
+If the stream is in the "Recv or "Size Known" states, the transport SHOULD
+signal this by sending a STOP_SENDING frame identifying that stream to prompt

I think that we can lose a few words and make this a little more readable.
```suggestion
signal this by sending a STOP_SENDING frame to prompt
```

> +- write data, understanding when stream flow control credit
+  ({{data-flow-control}}) has successfully been reserved to send the written
+  data
+- end the stream (clean termination), resulting in a STREAM frame
+  ({{frame-stream}}) with the FIN bit set; and
+- reset the stream (abrupt termination), resulting in a RESET_STREAM frame
+  ({{frame-reset-stream}}), even if the stream was already ended.
+
+On the receiving part of a stream, application protocols need to be able to:
+
+- read data
+- abort reading of the stream and request closure, possibly resulting in a
+  STOP_SENDING frame ({{frame-stop-sending}})
+
+Applications also need to be informed of state changes on streams, including
+when the peer has initiated, reset, or aborted reading on a stream; when new

List construction here implies that you can "reset reading on a stream" or that you can observe "initiation of reading on a stream".  You probably need to say "when the peer has opened or reset a stream; when a peer aborts reading a stream; when new ..."

-- 
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-263174739

---

From: ianswett <[email-masked]>
Date: Tue, 06 Aug 2019 14:35:24 -0700

ianswett commented on this pull request.

Agreed, I think it's only yes/no about the current state of the connection.

-- 
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#discussion_r311285561

---

From: ianswett <[email-masked]>
Date: Tue, 06 Aug 2019 14:36:13 -0700

-->

Good point.  I still think the client needs to know when 1-RTT data can be sent, because it may want to send some data in 0-RTT but not other data.

-- 
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#discussion_r311285873

---

From: ianswett <[email-masked]>
Date: Tue, 06 Aug 2019 14:37:15 -0700

+- 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; and
+- if Early Data is supported, retrieve application-controlled data from the
+  client's resumption ticket and enable rejecting Early Data based on that
+  information.
+
+In either role, applications need to be able to:
+
+- configure minimum values for the initial number of permitted streams of each
+  type, as communicated in the transport parameters ({{transport-parameters}});
+- control resource allocation of various types, including flow control and the
+  number of permitted streams of each type;
+- identify whether the handshake has completed successfully or is still ongoing

I think it'd be nice to clarify that a reason for this bullet is to know it can send data in 1-RTT.

-- 
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-271629149

---

From: ianswett <[email-masked]>
Date: Tue, 06 Aug 2019 14:37:31 -0700

ianswett approved this pull request.

Some small suggestions, but looks good overall.

-- 
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-271629254

---

From: Mike Bishop <[email-masked]>
Date: Tue, 06 Aug 2019 15:19:14 -0700

a9aaa49933cb3fda7d341fd60d3f5c7d480d8777  More feedback

-- 
You are receiving this because you are subscribed to this thread.
View it on GitHub:
https://github.com/quicwg/base-drafts/pull/2857/files/a66d991cb88012958ed4f2511ade4a789a5554b3..a9aaa49933cb3fda7d341fd60d3f5c7d480d8777

---

From: Martin Thomson <[email-masked]>
Date: Thu, 15 Aug 2019 18:22:05 -0700

Merged #2857 into master.

-- 
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#event-2561078026