Subject: [quicwg/base-drafts] QPACK: add examples (#4093)

From: afrind <[email-masked]>
Date: Fri, 11 Sep 2020 12:31:37 -0700

Feedback welcome

Fixes: #1454
You can view, comment on, or merge this pull request online at:

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

-- Commit Summary --

  * QPACK: add examples

-- File Changes --

    M draft-ietf-quic-qpack.md (122)

-- Patch Links --

https://github.com/quicwg/base-drafts/pull/4093.patch
https://github.com/quicwg/base-drafts/pull/4093.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/4093

---

From: Bence Béky <[email-masked]>
Date: Fri, 11 Sep 2020 12:59:43 -0700

@bencebeky commented on this pull request.

Thanks for working on this!

> @@ -1551,6 +1551,128 @@ the smallest number of bytes.
 | 97    | x-frame-options                  | deny                                                        |
 | 98    | x-frame-options                  | sameorigin                                                  |
 
+
+# Encoding and Decoding Examples
+
+The following examples represent a series of exchanges between an encoder and a
+decoder.  The state of the encoder's dyanmic table is shown, along with its

s/dyanmic/dynamic/

> +                                 3   0  :authority  www.ietf.org
+                                Size=162
+
+Stream: 8
+0400               | Required Insert Count = 3, Base = 3
+80                 | Indexed field line
+
+                                Abs Ref Name        Value
+                                 1   0  :authority  www.ietf.org
+                                 2   0  custom-key  custom-value
+                                ^-- acknowledged --^
+                                 3   1  :authority  www.ietf.org
+                                Size=162
+~~~
+
+## Dyanmic Table Insert causes eviction

s/dyanmic/dynamic/

> +## Dynamic Table
+
+~~~
+Stream: Encoder
+3f8b                | Set Table Capacity=170
+01c0 0c77 7777 2e69 | Insert with static name  reference
+6574 662e 6f72 67   |  (:authortiy=www.ietf.org)
+
+                                Abs Ref Name        Value
+                                ^-- acknowledged --^
+                                 1   0  :authority  www.ietf.org
+                                Size=54
+
+Stream: 4
+0280                | Required Insert Count = 1, Base = 0
+10                  | Indexed field line with post-base index

Here and below for Stream 8: in addition to naming the representation type, consider writing out the encoded header name and value for clarity.

-- 
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/4093#pullrequestreview-487081566

---

From: Robin Marx <[email-masked]>
Date: Fri, 11 Sep 2020 13:16:13 -0700

@rmarx commented on this pull request.

+

It would be good to give a high-level description of what exactly this series of exchanges shows/is intended to show up-front. 

-- 
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/4093#pullrequestreview-487097043

---

From: afrind <[email-masked]>
Date: Fri, 11 Sep 2020 16:34:42 -0700

@afrind pushed 1 commit.

74f957fc86cfbcd90708c7e3da98d2734dfee695  Review feedback

-- 
You are receiving this because you are subscribed to this thread.
View it on GitHub:
https://github.com/quicwg/base-drafts/pull/4093/files/c6a783b891a06b2e673484de3893e525c0a10495..74f957fc86cfbcd90708c7e3da98d2734dfee695

---

From: Martin Thomson <[email-masked]>
Date: Sun, 13 Sep 2020 22:46:48 -0700

@martinthomson commented on this pull request.

It looks like there is a small error (just with attribution, not the encoding), but this covers most of the important cases.  It's a shame that the indices are so small, because I don't think that this provides enough information for someone to understand how references to the dynamic table work.  All references in examples have an encoded index of 0.

> +510b 2f69 6e64 6578 | Literal Field Line with Name Reference
+2e68 746d 6c        |  (:path=/index.html)

It might help if you include the numeric values included in each of these descriptions.  In this case, it's (static table 1).

> +                                ^-- acknowledged --^
+                                Size=0
+~~~
+
+## Dynamic Table
+
+The encoder sets the dynamic table capacity, inserts a header with a dynamic
+name reference, then sends a potentially blocking, encoded field section
+referencing this new entry.  The decoder acknowledges processing the encoded
+field section.
+
+~~~
+Stream: Encoder
+3f8b                | Set Dynamic Table Capacity=170
+01c0 0c77 7777 2e69 | Insert With Name Reference (static table)
+6574 662e 6f72 67   |  (:authortiy=www.ietf.org)

```suggestion
7466 2e6f 7267      |  (:authority=www.ietf.org)
```

+                                Abs Ref Name        Value
+                                ^-- acknowledged --^
+                                Size=0
+~~~
+
+## Dynamic Table
+
+The encoder sets the dynamic table capacity, inserts a header with a dynamic
+name reference, then sends a potentially blocking, encoded field section
+referencing this new entry.  The decoder acknowledges processing the encoded
+field section.
+
+~~~
+Stream: Encoder
+3f8b                | Set Dynamic Table Capacity=170

I read this as extending to the next byte.

```suggestion
3f8b01              | Set Dynamic Table Capacity=170
```

> +                                Abs Ref Name        Value
+                                ^-- acknowledged --^
+                                Size=0
+~~~
+
+## Dynamic Table
+
+The encoder sets the dynamic table capacity, inserts a header with a dynamic
+name reference, then sends a potentially blocking, encoded field section
+referencing this new entry.  The decoder acknowledges processing the encoded
+field section.
+
+~~~
+Stream: Encoder
+3f8b                | Set Dynamic Table Capacity=170
+01c0 0c77 7777 2e69 | Insert With Name Reference (static table)

```suggestion
c00c 7777 772e 6965 | Insert With Name Reference (static table 0)
```

> +Stream: 0
+0000                | Required Insert Count = 0, Base = 0
+510b 2f69 6e64 6578 | Literal Field Line with Name Reference
+2e68 746d 6c        |  (:path=/index.html)
+
+                                Abs Ref Name        Value
+                                ^-- acknowledged --^
+                                Size=0
+~~~
+
+## Dynamic Table
+
+The encoder sets the dynamic table capacity, inserts a header with a dynamic
+name reference, then sends a potentially blocking, encoded field section
+referencing this new entry.  The decoder acknowledges processing the encoded
+field section.

```suggestion
field section, which transitively acknowledges the encoder instructions up to the Required Insert Count.
```

Or something like that.

+~~~
+Stream: Encoder
+3f8b                | Set Dynamic Table Capacity=170
+01c0 0c77 7777 2e69 | Insert With Name Reference (static table)
+6574 662e 6f72 67   |  (:authortiy=www.ietf.org)
+
+                                Abs Ref Name        Value
+                                ^-- acknowledged --^
+                                 1   0  :authority  www.ietf.org
+                                Size=54
+
+Stream: 4
+0280                | Required Insert Count = 1, Base = 0
+10                  | Indexed Field Line With Post-Base Index
+                    |  Absolute Index=1

This one is useful to break down (RIC + delta_base + 0 = 1).  Shame that we have such small numbers involved here.

-- 
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/4093#pullrequestreview-487423724

---

From: afrind <[email-masked]>
Date: Mon, 14 Sep 2020 08:58:02 -0700

@martinthomson:  I can add a few more dynamic table entries to the examples to get indexes > 0 -- do you think 1-2 is good, or do you think it needs to be another order of magnitude?

-- 
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/4093#issuecomment-692151383

---

From: Martin Thomson <[email-masked]>
Date: Mon, 14 Sep 2020 17:01:43 -0700

At most 2.  The great thing about the current example is that it is small and easy to fit in your head.  If you can reference the existing entries, that might help, but you don't have quite enough to work with.  Maybe you can use :path to keep things neat.

-- 
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/4093#issuecomment-692380460

---

From: afrind <[email-masked]>
Date: Fri, 18 Sep 2020 17:15:25 -0700

@afrind pushed 1 commit.

3717732ea3e0473fe6847868e2bd7d3ba53acb0e  Martin's feedback

-- 
You are receiving this because you are subscribed to this thread.
View it on GitHub:
https://github.com/quicwg/base-drafts/pull/4093/files/74f957fc86cfbcd90708c7e3da98d2734dfee695..3717732ea3e0473fe6847868e2bd7d3ba53acb0e

---

From: afrind <[email-masked]>
Date: Tue, 22 Sep 2020 16:05:13 -0700

@afrind pushed 1 commit.

a32f7724763a95457bda4a0ad7f1170153bd16b0  Change authority and path to match HPACK

-- 
You are receiving this because you are subscribed to this thread.
View it on GitHub:
https://github.com/quicwg/base-drafts/pull/4093/files/3717732ea3e0473fe6847868e2bd7d3ba53acb0e..a32f7724763a95457bda4a0ad7f1170153bd16b0

---

From: Martin Thomson <[email-masked]>
Date: Tue, 22 Sep 2020 18:37:13 -0700

@martinthomson approved this pull request.

This is excellent.  Thanks for adding the one extra reference and the www.example.com.

I didn't check the examples carefully, but I checked a couple and those line up neatly.

-- 
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/4093#pullrequestreview-493970828

---

From: afrind <[email-masked]>
Date: Wed, 23 Sep 2020 13:04:07 -0700

Merged #4093 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/4093#event-3799915320