From c6a783b891a06b2e673484de3893e525c0a10495 Mon Sep 17 00:00:00 2001 From: Alan Frindell Date: Fri, 11 Sep 2020 12:29:43 -0700 Subject: [PATCH 1/4] QPACK: add examples Feedback welcome Fixes: #1454 --- draft-ietf-quic-qpack.md | 122 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 122 insertions(+) diff --git a/draft-ietf-quic-qpack.md b/draft-ietf-quic-qpack.md index c2f35e3d81..95d21a9bc7 100644 --- a/draft-ietf-quic-qpack.md +++ b/draft-ietf-quic-qpack.md @@ -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 +current size. Each entry is shown with the Absolute Index of the entry (Abs), +the current number of outstanding encoded field sections with references to that +entry (Ref), along with the name and value. Entries above the 'acknowledged' +line have been acknowledged by the decoder. + +## Literal Field Line With Name Reference + +~~~ +Data | Interpretation + | Encoder's Dynamic Table + +Stream: 0 +0000 | Required Insert Count = 0, Base = 0 +510b 2f69 6e64 6578 | :path=/index.html +2e68 746d 6c + + Abs Ref Name Value + ^-- acknowledged --^ + Size=0 +~~~ + +## 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 + + Abs Ref Name Value + ^-- acknowledged --^ + 1 1 :authority www.ietf.org + Size=54 + +Stream: Decoder +84 | Section Acknowledgement (stream=4) + + Abs Ref Name Value + 1 0 :authority www.ietf.org + ^-- acknowledged --^ + Size=54 +~~~ + +## Speculative Insert + +~~~ +Stream: Encoder +4a63 7573 746f 6d2d | Insert without name reference +6b65 790c 6375 7374 | (custom-key=custom-value) +6f6d 2d76 616c 7565 | + + Abs Ref Name Value + 1 0 :authority www.ietf.org + ^-- acknowledged --^ + 2 0 custom-key custom-value + Size=108 + +Stream: Decoder +01 | Insert count increment (1) + + Abs Ref Name Value + 1 0 :authority www.ietf.org + 2 0 custom-key custom-value + ^-- acknowledged --^ + Size=108 + +~~~ + +## Duplicate Instruction + +~~~ +Stream: Encoder +01 | Duplicate (relative index=1) + + Abs Ref Name Value + 1 0 :authority www.ietf.org + 2 0 custom-key custom-value + ^-- acknowledged --^ + 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 + +~~~ +Stream: Encoder +810d 6375 7374 6f6d | Insert with dynamic table name reference +2d76 616c 7565 32 | (custom-key=custom-value2) + + Abs Ref Name Value + 2 0 custom-key custom-value + ^-- acknowledged --^ + 3 1 :authority www.ietf.org + 4 0 custom-key custom-value2 + Size=163 +~~~ + # Sample One Pass Encoding Algorithm Pseudo-code for single pass encoding, excluding handling of duplicates, From 74f957fc86cfbcd90708c7e3da98d2734dfee695 Mon Sep 17 00:00:00 2001 From: Alan Frindell Date: Fri, 11 Sep 2020 16:32:12 -0700 Subject: [PATCH 2/4] Review feedback * Fixed typos * Added more context around what the examples are doing * Added a Stream Cancellation example * Added more detail for field line representations --- draft-ietf-quic-qpack.md | 73 +++++++++++++++++++++++++++++++--------- 1 file changed, 57 insertions(+), 16 deletions(-) diff --git a/draft-ietf-quic-qpack.md b/draft-ietf-quic-qpack.md index 95d21a9bc7..120bd1ce0e 100644 --- a/draft-ietf-quic-qpack.md +++ b/draft-ietf-quic-qpack.md @@ -1555,7 +1555,12 @@ the smallest number of bytes. # 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 +decoder. The exchanges are designed to exercise most QPACK instructions, and +highlight potentially common patterns and their impact on dynamic table state. +The encoder sends three encoded field sections containing one field line each, +as wells as two speculative inserts that are not referenced. + +The state of the encoder's dynamic table is shown, along with its current size. Each entry is shown with the Absolute Index of the entry (Abs), the current number of outstanding encoded field sections with references to that entry (Ref), along with the name and value. Entries above the 'acknowledged' @@ -1563,14 +1568,17 @@ line have been acknowledged by the decoder. ## Literal Field Line With Name Reference +The encoder sends an encoded field section containing a literal representation +of a field with a static name reference. + ~~~ Data | Interpretation | Encoder's Dynamic Table Stream: 0 0000 | Required Insert Count = 0, Base = 0 -510b 2f69 6e64 6578 | :path=/index.html -2e68 746d 6c +510b 2f69 6e64 6578 | Literal Field Line with Name Reference +2e68 746d 6c | (:path=/index.html) Abs Ref Name Value ^-- acknowledged --^ @@ -1579,10 +1587,15 @@ Stream: 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 Table Capacity=170 -01c0 0c77 7777 2e69 | Insert with static name reference +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 @@ -1592,7 +1605,9 @@ Stream: Encoder Stream: 4 0280 | Required Insert Count = 1, Base = 0 -10 | Indexed field line with post-base index +10 | Indexed Field Line With Post-Base Index + | Absolute Index=1 + | (:authority=www.ietf.org) Abs Ref Name Value ^-- acknowledged --^ @@ -1610,10 +1625,14 @@ Stream: Decoder ## Speculative Insert +The encoder inserts a header into the dynamic table without a name reference. +The decoder acknowledges receipt of the entry. The encoder does not send +any encoded field sections. + ~~~ Stream: Encoder -4a63 7573 746f 6d2d | Insert without name reference -6b65 790c 6375 7374 | (custom-key=custom-value) +4a63 7573 746f 6d2d | Insert Without Name Reference +6b65 790c 6375 7374 | (custom-key=custom-value) 6f6d 2d76 616c 7565 | Abs Ref Name Value @@ -1623,7 +1642,7 @@ Stream: Encoder Size=108 Stream: Decoder -01 | Insert count increment (1) +01 | Insert Count Increment (1) Abs Ref Name Value 1 0 :authority www.ietf.org @@ -1633,11 +1652,16 @@ Stream: Decoder ~~~ -## Duplicate Instruction +## Duplicate Instruction, Stream Cancellation + +The encoder duplicates an existing entry in the dynamic table, then sends an +encoded field section referencing the duplicated entry. The decoder notifies +the encoder that the encoded field section was not processed by sending a stream +cancellation. ~~~ Stream: Encoder -01 | Duplicate (relative index=1) +01 | Duplicate (Relative Index=1) Abs Ref Name Value 1 0 :authority www.ietf.org @@ -1648,7 +1672,9 @@ Stream: Encoder Stream: 8 0400 | Required Insert Count = 3, Base = 3 -80 | Indexed field line +80 | Indexed Field Line + | Absolute Index=3 + | (:authority=www.ietf.org) Abs Ref Name Value 1 0 :authority www.ietf.org @@ -1656,19 +1682,34 @@ Stream: 8 ^-- acknowledged --^ 3 1 :authority www.ietf.org Size=162 + +Stream: Decoder +48 | Stream Cancellation (Stream=8) + + Abs Ref Name Value + 1 0 :authority www.ietf.org + 2 0 custom-key custom-value + ^-- acknowledged --^ + 3 0 :authority www.ietf.org + Size=162 + ~~~ -## Dyanmic Table Insert causes eviction +## Dynamic Table Insert, Eviction + +The encoder inserts another header into the dynamic table, which evicts the +oldest entry. The encoder does not send any encoded field sections. ~~~ Stream: Encoder -810d 6375 7374 6f6d | Insert with dynamic table name reference -2d76 616c 7565 32 | (custom-key=custom-value2) +810d 6375 7374 6f6d | Insert With Name Reference (dynamic table) +2d76 616c 7565 32 | Absolute Index=2 + | (custom-key=custom-value2) Abs Ref Name Value 2 0 custom-key custom-value ^-- acknowledged --^ - 3 1 :authority www.ietf.org + 3 0 :authority www.ietf.org 4 0 custom-key custom-value2 Size=163 ~~~ From 3717732ea3e0473fe6847868e2bd7d3ba53acb0e Mon Sep 17 00:00:00 2001 From: Alan Frindell Date: Fri, 18 Sep 2020 17:13:37 -0700 Subject: [PATCH 3/4] Martin's feedback * Fixed some typos * Added absolute index calculations * Added one more entry to the dynamic table to allow for non-zero index --- draft-ietf-quic-qpack.md | 102 ++++++++++++++++++++++++--------------- 1 file changed, 62 insertions(+), 40 deletions(-) diff --git a/draft-ietf-quic-qpack.md b/draft-ietf-quic-qpack.md index 120bd1ce0e..f4a7ae5534 100644 --- a/draft-ietf-quic-qpack.md +++ b/draft-ietf-quic-qpack.md @@ -1578,7 +1578,8 @@ Data | Interpretation 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) +2e68 746d 6c | Static Table, Index=1 + | (:path=/index.html) Abs Ref Name Value ^-- acknowledged --^ @@ -1590,37 +1591,48 @@ Stream: 0 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. +field section, which implicitly acknowledges all dynamic table insertions up to +the Required Insert Count. ~~~ 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) +3fb801 | Set Dynamic Table Capacity=215 +c00c 7777 772e 6965 | Insert With Name Reference +7466 2e6f 7267 | Static Table, Index=0 + | (:authority=www.ietf.org) +c10b 2f73 7461 6e64 | Insert With Name Reference +617 26473 2f | Static Table, Index=1 + | (:path=/standards/) Abs Ref Name Value ^-- acknowledged --^ 1 0 :authority www.ietf.org - Size=54 + 2 0 :path /standards/ + Size=102 Stream: 4 -0280 | Required Insert Count = 1, Base = 0 +0381 | Required Insert Count = 2, Base = 0 10 | Indexed Field Line With Post-Base Index - | Absolute Index=1 + | Absolute Index = Base(0) + Index(0) + 1 = 1 | (:authority=www.ietf.org) +11 | Indexed Field Line With Post-Base Index + | Absolute Index = Base(0) + Index(1) + 1 = 2 + | (:path=/standards/) Abs Ref Name Value ^-- acknowledged --^ 1 1 :authority www.ietf.org - Size=54 + 2 1 :path /standards/ + Size=102 Stream: Decoder 84 | Section Acknowledgement (stream=4) Abs Ref Name Value 1 0 :authority www.ietf.org + 2 0 :path /standards/ ^-- acknowledged --^ - Size=54 + Size=102 ~~~ ## Speculative Insert @@ -1637,61 +1649,70 @@ Stream: Encoder Abs Ref Name Value 1 0 :authority www.ietf.org + 2 0 :path /standards/ ^-- acknowledged --^ - 2 0 custom-key custom-value - Size=108 + 3 0 custom-key custom-value + Size=156 Stream: Decoder 01 | Insert Count Increment (1) Abs Ref Name Value 1 0 :authority www.ietf.org - 2 0 custom-key custom-value + 2 0 :path /standards/ + 3 0 custom-key custom-value ^-- acknowledged --^ - Size=108 + Size=156 ~~~ ## Duplicate Instruction, Stream Cancellation The encoder duplicates an existing entry in the dynamic table, then sends an -encoded field section referencing the duplicated entry. The decoder notifies -the encoder that the encoded field section was not processed by sending a stream -cancellation. +encoded field section referencing the dynamic table entries including the +duplicated entry. The decoder notifies the encoder that the encoded field +section was not processed by sending a stream cancellation. ~~~ Stream: Encoder -01 | Duplicate (Relative Index=1) +02 | Duplicate (Relative Index=2) Abs Ref Name Value 1 0 :authority www.ietf.org - 2 0 custom-key custom-value + 2 0 :path /standards/ + 3 0 custom-key custom-value ^-- acknowledged --^ - 3 0 :authority www.ietf.org - Size=162 + 4 0 :authority www.ietf.org + Size=210 Stream: 8 -0400 | Required Insert Count = 3, Base = 3 -80 | Indexed Field Line - | Absolute Index=3 - | (:authority=www.ietf.org) +0500 | Required Insert Count = 4, Base = 4 +80 | Indexed Field Line, Dynamic Table + | Absolute Index = Base(4) - Index(0) = 4 + | (:authority=www.ietf.org) +c1 | Indexed Field Line, Static Table Index = 1 + | (:path=/) +81 | Indexed Field Line, Dynamic Table + | Absolute Index = Base(4) - Index(1) = 3 + | (custom-key=custom-value) Abs Ref Name Value 1 0 :authority www.ietf.org - 2 0 custom-key custom-value + 2 0 :path /standards/ + 3 1 custom-key custom-value ^-- acknowledged --^ - 3 1 :authority www.ietf.org - Size=162 + 4 1 :authority www.ietf.org + Size=210 Stream: Decoder -48 | Stream Cancellation (Stream=8) - +48 | Stream Cancellation (Stream=8) Abs Ref Name Value 1 0 :authority www.ietf.org - 2 0 custom-key custom-value + 2 0 :path /standards/ + 3 0 custom-key custom-value ^-- acknowledged --^ - 3 0 :authority www.ietf.org - Size=162 + 4 0 :authority www.ietf.org + Size=210 ~~~ @@ -1702,16 +1723,17 @@ oldest entry. The encoder does not send any encoded field sections. ~~~ Stream: Encoder -810d 6375 7374 6f6d | Insert With Name Reference (dynamic table) -2d76 616c 7565 32 | Absolute Index=2 - | (custom-key=custom-value2) +810d 6375 7374 6f6d | Insert With Name Reference +2d76 616c 7565 32 | Dynamic Table, Absolute Index=2 + | (custom-key=custom-value2) Abs Ref Name Value - 2 0 custom-key custom-value + 2 0 :path /standards/ + 3 0 custom-key custom-value ^-- acknowledged --^ - 3 0 :authority www.ietf.org - 4 0 custom-key custom-value2 - Size=163 + 4 0 :authority www.ietf.org + 5 0 custom-key custom-value2 + Size=211 ~~~ # Sample One Pass Encoding Algorithm From a32f7724763a95457bda4a0ad7f1170153bd16b0 Mon Sep 17 00:00:00 2001 From: Alan Frindell Date: Tue, 22 Sep 2020 16:03:51 -0700 Subject: [PATCH 4/4] Change authority and path to match HPACK www.ietf.org -> www.example.com /standards -> /sample/path --- draft-ietf-quic-qpack.md | 141 ++++++++++++++++++++------------------- 1 file changed, 71 insertions(+), 70 deletions(-) diff --git a/draft-ietf-quic-qpack.md b/draft-ietf-quic-qpack.md index f4a7ae5534..564d03aafb 100644 --- a/draft-ietf-quic-qpack.md +++ b/draft-ietf-quic-qpack.md @@ -1573,7 +1573,7 @@ of a field with a static name reference. ~~~ Data | Interpretation - | Encoder's Dynamic Table + | Encoder's Dynamic Table Stream: 0 0000 | Required Insert Count = 0, Base = 0 @@ -1581,9 +1581,9 @@ Stream: 0 2e68 746d 6c | Static Table, Index=1 | (:path=/index.html) - Abs Ref Name Value - ^-- acknowledged --^ - Size=0 + Abs Ref Name Value + ^-- acknowledged --^ + Size=0 ~~~ ## Dynamic Table @@ -1596,43 +1596,43 @@ the Required Insert Count. ~~~ Stream: Encoder -3fb801 | Set Dynamic Table Capacity=215 -c00c 7777 772e 6965 | Insert With Name Reference -7466 2e6f 7267 | Static Table, Index=0 - | (:authority=www.ietf.org) -c10b 2f73 7461 6e64 | Insert With Name Reference -617 26473 2f | Static Table, Index=1 - | (:path=/standards/) - - Abs Ref Name Value - ^-- acknowledged --^ - 1 0 :authority www.ietf.org - 2 0 :path /standards/ - Size=102 +3fbd01 | Set Dynamic Table Capacity=220 +c00f 7777 772e 6578 | Insert With Name Reference +616d 706c 652e 636f | Static Table, Index=0 +6d | (:authority=www.example.com) +c10c 2f73 616d 706c | Insert With Name Reference +652f 7061 7468 | Static Table, Index=1 + | (:path=/sample/path) + + Abs Ref Name Value + ^-- acknowledged --^ + 1 0 :authority www.example.com + 2 0 :path /sample/path + Size=106 Stream: 4 0381 | Required Insert Count = 2, Base = 0 10 | Indexed Field Line With Post-Base Index | Absolute Index = Base(0) + Index(0) + 1 = 1 - | (:authority=www.ietf.org) + | (:authority=www.example.com) 11 | Indexed Field Line With Post-Base Index | Absolute Index = Base(0) + Index(1) + 1 = 2 - | (:path=/standards/) + | (:path=/sample/path) - Abs Ref Name Value - ^-- acknowledged --^ - 1 1 :authority www.ietf.org - 2 1 :path /standards/ - Size=102 + Abs Ref Name Value + ^-- acknowledged --^ + 1 1 :authority www.example.com + 2 1 :path /sample/path + Size=106 Stream: Decoder 84 | Section Acknowledgement (stream=4) - Abs Ref Name Value - 1 0 :authority www.ietf.org - 2 0 :path /standards/ - ^-- acknowledged --^ - Size=102 + Abs Ref Name Value + 1 0 :authority www.example.com + 2 0 :path /sample/path + ^-- acknowledged --^ + Size=106 ~~~ ## Speculative Insert @@ -1647,22 +1647,22 @@ Stream: Encoder 6b65 790c 6375 7374 | (custom-key=custom-value) 6f6d 2d76 616c 7565 | - Abs Ref Name Value - 1 0 :authority www.ietf.org - 2 0 :path /standards/ - ^-- acknowledged --^ - 3 0 custom-key custom-value - Size=156 + Abs Ref Name Value + 1 0 :authority www.example.com + 2 0 :path /sample/path + ^-- acknowledged --^ + 3 0 custom-key custom-value + Size=160 Stream: Decoder 01 | Insert Count Increment (1) - Abs Ref Name Value - 1 0 :authority www.ietf.org - 2 0 :path /standards/ - 3 0 custom-key custom-value - ^-- acknowledged --^ - Size=156 + Abs Ref Name Value + 1 0 :authority www.example.com + 2 0 :path /sample/path + 3 0 custom-key custom-value + ^-- acknowledged --^ + Size=160 ~~~ @@ -1677,42 +1677,43 @@ section was not processed by sending a stream cancellation. Stream: Encoder 02 | Duplicate (Relative Index=2) - Abs Ref Name Value - 1 0 :authority www.ietf.org - 2 0 :path /standards/ - 3 0 custom-key custom-value - ^-- acknowledged --^ - 4 0 :authority www.ietf.org - Size=210 + Abs Ref Name Value + 1 0 :authority www.example.com + 2 0 :path /sample/path + 3 0 custom-key custom-value + ^-- acknowledged --^ + 4 0 :authority www.example.com + Size=217 Stream: 8 0500 | Required Insert Count = 4, Base = 4 80 | Indexed Field Line, Dynamic Table | Absolute Index = Base(4) - Index(0) = 4 - | (:authority=www.ietf.org) + | (:authority=www.example.com) c1 | Indexed Field Line, Static Table Index = 1 | (:path=/) 81 | Indexed Field Line, Dynamic Table | Absolute Index = Base(4) - Index(1) = 3 | (custom-key=custom-value) - Abs Ref Name Value - 1 0 :authority www.ietf.org - 2 0 :path /standards/ - 3 1 custom-key custom-value - ^-- acknowledged --^ - 4 1 :authority www.ietf.org - Size=210 + Abs Ref Name Value + 1 0 :authority www.example.com + 2 0 :path /sample/path + 3 1 custom-key custom-value + ^-- acknowledged --^ + 4 1 :authority www.example.com + Size=217 Stream: Decoder 48 | Stream Cancellation (Stream=8) - Abs Ref Name Value - 1 0 :authority www.ietf.org - 2 0 :path /standards/ - 3 0 custom-key custom-value - ^-- acknowledged --^ - 4 0 :authority www.ietf.org - Size=210 + + Abs Ref Name Value + 1 0 :authority www.example.com + 2 0 :path /sample/path + 3 0 custom-key custom-value + ^-- acknowledged --^ + 4 0 :authority www.example.com + Size=215 ~~~ @@ -1727,13 +1728,13 @@ Stream: Encoder 2d76 616c 7565 32 | Dynamic Table, Absolute Index=2 | (custom-key=custom-value2) - Abs Ref Name Value - 2 0 :path /standards/ - 3 0 custom-key custom-value - ^-- acknowledged --^ - 4 0 :authority www.ietf.org - 5 0 custom-key custom-value2 - Size=211 + Abs Ref Name Value + 2 0 :path /sample/path + 3 0 custom-key custom-value + ^-- acknowledged --^ + 4 0 :authority www.example.com + 5 0 custom-key custom-value2 + Size=215 ~~~ # Sample One Pass Encoding Algorithm