Re: [quicwg/base-drafts] Alternative packet format presentation (#3573)

[Lucas Pardue <[e-mail]>]

@LPardue requested changes on this pull request.

Overall I like this. The terser presentation allows you to define the full H3 frame, which I really like. Strictly, those figures now present  the whole frame so I've made the suggestion to drop the `Payload` qualifier.

Also see comment about the 0 or more SETTINGS parameters, which needs a fixup.

> @@ -1229,11 +1220,11 @@ frame is received on a control stream, the recipient MUST respond with a
 connection error ({{errors}}) of type H3_FRAME_UNEXPECTED.
 
 ~~~~~~~~~~ drawing
- 0                   1                   2                   3
- 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
-|                         Payload (*)                         ...
-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+DATA Frame {
+  Type (i) = 0x0,
+  Length (i),
+  Data (..),
+}
 ~~~~~~~~~~
 {: #fig-data title="DATA Frame Payload"}

```suggestion
{: #fig-data title="DATA Frame"}
```

> @@ -1243,11 +1234,11 @@ The HEADERS frame (type=0x1) is used to carry an HTTP field section, encoded
 using QPACK. See [QPACK] for more details.
 
 ~~~~~~~~~~  drawing
- 0                   1                   2                   3
- 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
-|                   Encoded Field Section (*)                 ...
-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+HEADERS Frame {
+  Type (i) = 0x1,
+  Length (i),
+  Encoded Field Section (..),
+}
 ~~~~~~~~~~
 {: #fig-headers title="HEADERS Frame Payload"}

```suggestion
{: #fig-headers title="HEADERS Frame"}
```

> @@ -1284,11 +1275,11 @@ frame on a stream other than the control stream MUST be treated as a connection
 error of type H3_FRAME_UNEXPECTED.
 
 ~~~~~~~~~~  drawing
- 0                   1                   2                   3
- 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
-|                          Push ID (i)                        ...
-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+CANCEL_PUSH Frame {
+  Type (i) = 0x3,
+  Length (i),
+  Push ID (..),
+}
 ~~~~~~~~~~
 {: #fig-cancel-push title="CANCEL_PUSH Frame Payload"}

```suggestion
{: #fig-cancel-push title="CANCEL_PUSH Frame"}
```

> +SETTINGS Frame {
+  Type (i) = 0x4,
+  Length (i),
+  Identifier (i),
+  Value (i),
+}

This is wrong, sorry. The text discusses that the frame contains 0 or more parameters and the old drawing presents the format of the parameter, not the frame. I think what you want to do is present  the pair of (Identifier, Value) with cardinality, and then update the fig title to sat "SETTINGS Frame".

> @@ -1436,13 +1426,12 @@ The PUSH_PROMISE frame (type=0x5) is used to carry a promised request header
 field section from server to client on a request stream, as in HTTP/2.
 
 ~~~~~~~~~~  drawing
- 0                   1                   2                   3
- 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
-|                          Push ID (i)                        ...
-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
-|                   Encoded Field Section (*)                 ...
-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+PUSH_PROMISE Frame {
+  Type (i) = 0x5,
+  Length (i),
+  Push ID (i),
+  Encoded Field Section (..),
+}
 ~~~~~~~~~~
 {: #fig-push-promise title="PUSH_PROMISE Frame Payload"}

```suggestion
{: #fig-push-promise title="PUSH_PROMISE Frame"}
```

> @@ -1496,11 +1485,11 @@ requests and pushes.  This enables administrative actions, like server
 maintenance.  GOAWAY by itself does not close a connection.
 
 ~~~~~~~~~~  drawing
- 0                   1                   2                   3
- 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
-|                  Stream ID/Push ID (i)                      ...
-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+GOAWAY Frame {
+  Type (i) = 0x7,
+  Length (i),
+  Stream ID/Push ID (..),
+}
 ~~~~~~~~~~
 {: #fig-goaway title="GOAWAY Frame Payload"}

```suggestion
{: #fig-goaway title="GOAWAY Frame"}
```

-- 
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/3573#pullrequestreview-394000888