Subject: [quicwg/base-drafts] Rework lots of error references (#4384)

From: Mike Bishop <[email-masked]>
Date: Tue, 17 Nov 2020 04:14:32 -0800

Fixes #4352.

Expands on error handling discussion and clarifies difference from HTTP status codes which indicate error response.  Also, some editorial consistency fixes:

- The references to errors seem to have missed our switch to use &quot;; see XXXX.&quot; where possible.
- Somewhere along the way, we stopped referring to the error handling section when defining errors.

I&#39;ve done a sweep and believe these are consistent now.

@theri, your review would be appreciated.
You can view, comment on, or merge this pull request online at:

  https://github.com/quicwg/base-drafts/pull/4384

-- Commit Summary --

  * Rework lots of error references

-- File Changes --

    M draft-ietf-quic-http.md (92)

-- Patch Links --

https://github.com/quicwg/base-drafts/pull/4384.patch
https://github.com/quicwg/base-drafts/pull/4384.diff

-- 
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/4384

---

From: Lucas Pardue <[email-masked]>
Date: Tue, 17 Nov 2020 04:49:21 -0800

@LPardue approved this pull request.

-- 
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/4384#pullrequestreview-532326763

---

From: Magnus Westerlund <[email-masked]>
Date: Tue, 17 Nov 2020 06:32:04 -0800

@gloinul approved this pull request.

-- 
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/4384#pullrequestreview-532420052

---

From: ianswett <[email-masked]>
Date: Tue, 17 Nov 2020 10:58:43 -0800

@ianswett approved this pull request.

-- 
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/4384#pullrequestreview-532692424

---

From: Martin Thomson <[email-masked]>
Date: Tue, 17 Nov 2020 16:08:50 -0800

@martinthomson approved this pull request.

-- 
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/4384#pullrequestreview-532914428

---

From: Theresa Enghardt <[email-masked]>
Date: Tue, 17 Nov 2020 21:21:24 -0800

@theri requested changes on this pull request.

Thank you, this is already helpful. I would like the text to be yet a bit more explicit, see my suggestions.

Also, could you add another reference to {{errors}} where you first mention error codes, i.e., after "error code H3_REQUEST_INCOMPLETE" in Section 4.1 (at the bottom of page 12 in -32), please?

> -indicate a problem with the connection or either implementation.  For example, a
-stream can be reset if the requested resource is no longer needed.
+When a stream cannot be completed successfully, QUIC allows the application to
+abruptly terminate (reset) that stream and communicate a reason; see Section 2.4
+of {{QUIC-TRANSPORT}}. This is referred to as a "stream error."  Stream errors
+are distinct from HTTP status codes which indicate error conditions.  Stream
+errors indicate that the sender did not transfer the full request or response,
+while HTTP status codes indicate the result of a request that was successfully
+received.
+
+If an entire connection needs to be terminated, QUIC similarly provides
+mechanisms to communicate a reason; see Section 5.3 of {{QUIC-TRANSPORT}}.  This
+is referred to as a "connection error."
+
+Both stream errors and connection errors have associated error codes; see
+Section 11 of {{QUIC-TRANSPORT}}.  However, they do not necessarily indicate a

They are called error codes here, but refered to as "error of type H3_..." throughout the document.
If "error code" and "error type" are indeed the same concept, please consider unifying your terminology, e.g., changing "error of type H3_..." to "error using error code H3_...".

> @@ -1638,16 +1645,27 @@ H3_FRAME_UNEXPECTED.
 
 # Error Handling {#errors}
 
-QUIC allows the application to abruptly terminate (reset) individual streams or
-the entire connection; see Sections 2.4 and 5.3 of {{QUIC-TRANSPORT}}.  These
-are referred to as "stream errors" or "connection errors" (see Section 11 of
-{{QUIC-TRANSPORT}}) and have associated error codes, but do not necessarily
-indicate a problem with the connection or either implementation.  For example, a
-stream can be reset if the requested resource is no longer needed.
+When a stream cannot be completed successfully, QUIC allows the application to
+abruptly terminate (reset) that stream and communicate a reason; see Section 2.4
+of {{QUIC-TRANSPORT}}. This is referred to as a "stream error."  Stream errors

```suggestion
of {{QUIC-TRANSPORT}}. This is referred to as a "stream error." An HTTP/3 implementation can deciding to close a QUIC stream and communicate the reason using an error code as defined in Section 8.1 of this document. Stream errors
```
I would like the text to be very explicit about where/how the error code comes in, i.e., it is the reason being communicated by the application, which, in this case, is the HTTP/3 implementation.

> -the entire connection; see Sections 2.4 and 5.3 of {{QUIC-TRANSPORT}}.  These
-are referred to as "stream errors" or "connection errors" (see Section 11 of
-{{QUIC-TRANSPORT}}) and have associated error codes, but do not necessarily
-indicate a problem with the connection or either implementation.  For example, a
-stream can be reset if the requested resource is no longer needed.
+When a stream cannot be completed successfully, QUIC allows the application to
+abruptly terminate (reset) that stream and communicate a reason; see Section 2.4
+of {{QUIC-TRANSPORT}}. This is referred to as a "stream error."  Stream errors
+are distinct from HTTP status codes which indicate error conditions.  Stream
+errors indicate that the sender did not transfer the full request or response,
+while HTTP status codes indicate the result of a request that was successfully
+received.
+
+If an entire connection needs to be terminated, QUIC similarly provides
+mechanisms to communicate a reason; see Section 5.3 of {{QUIC-TRANSPORT}}.  This
+is referred to as a "connection error."

```suggestion
is referred to as a "connection error." Similar to stream errors, the HTTP/3 implementation can terminate a QUIC connection and communicate the reason using an error code defined in Section 8.1.
```

-- 
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/4384#pullrequestreview-533105239

---

From: Lucas Pardue <[email-masked]>
Date: Wed, 18 Nov 2020 00:25:37 -0800

@LPardue commented on this pull request.

I think there's a better alternative. In the paragraph that introduces stream errors, state that there can be multiple variants of "reason", described by an error type, which has an associated wire encoding error code. Do the same for the para that introduces connection errors.

Then delete the first sentence of this para and possibly merge it with the next one.

-- 
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/4384#discussion_r525895261

---

From: Mike Bishop <[email-masked]>
Date: Wed, 18 Nov 2020 01:53:35 -0800

@MikeBishop pushed 1 commit.

00096ebbc2c0c431ec5ceaa452a9915a10669e39  Error types and codes

-- 
You are receiving this because you are subscribed to this thread.
View it on GitHub:
https://github.com/quicwg/base-drafts/pull/4384/files/9a246ccefaa96e598bf875ef968c6a4f3a37faa2..00096ebbc2c0c431ec5ceaa452a9915a10669e39

---

From: Mike Bishop <[email-masked]>
Date: Wed, 18 Nov 2020 01:54:07 -0800

@MikeBishop commented on this pull request.

@LPardue, I've taken part of your idea and tried to use it to improve the terminology.  PTAL.

-- 
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/4384#discussion_r525953040

---

From: Theresa Enghardt <[email-masked]>
Date: Wed, 18 Nov 2020 19:05:04 -0800

@theri approved this pull request.

Looks good to me, thanks!

-- 
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/4384#pullrequestreview-534046229

---

From: Jana Iyengar <[email-masked]>
Date: Wed, 18 Nov 2020 19:51:35 -0800

@janaiyengar approved this pull request.

one nit

> @@ -1852,7 +1871,7 @@ they are used unnecessarily or to excess.
 An endpoint that does not monitor this behavior exposes itself to a risk of
 denial-of-service attack.  Implementations SHOULD track the use of these
 features and set limits on their use.  An endpoint MAY treat activity that is
-suspicious as a connection error ({{errors}}) of type H3_EXCESSIVE_LOAD, but
+suspicious as a connection error of type H3_EXCESSIVE_LOAD (see {{errors}}), but

```suggestion
suspicious as a connection error of type H3_EXCESSIVE_LOAD ({{errors}}), but
```

-- 
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/4384#pullrequestreview-534062677

---

From: Lucas Pardue <[email-masked]>
Date: Wed, 18 Nov 2020 21:51:27 -0800

lgtm thank mike

-- 
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/4384#pullrequestreview-534099718

---

From: Mike Bishop <[email-masked]>
Date: Thu, 19 Nov 2020 00:48:01 -0800

123b031ef29c38e97903992032714b744ddcab7e  Update draft-ietf-quic-http.md

-- 
You are receiving this because you are subscribed to this thread.
View it on GitHub:
https://github.com/quicwg/base-drafts/pull/4384/files/00096ebbc2c0c431ec5ceaa452a9915a10669e39..123b031ef29c38e97903992032714b744ddcab7e

---

From: Mike Bishop <[email-masked]>
Date: Tue, 24 Nov 2020 15:09:50 -0800

Merged #4384 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/4384#event-4035190677