Merge pull request #3684 from quicwg/invariant-independent

Invariant independent

draft-ietf-quic-invariants.md

@@ -18,7 +18,7 @@ author:
     org: Mozilla
     email: mt@lowentropy.net
 
-normative:
+informative:
 
   QUIC-TRANSPORT:
     title: "QUIC: A UDP-Based Multiplexed and Secure Transport"
@@ -37,8 +37,6 @@ normative:
         org: Mozilla
         role: editor
 
-informative:
-
   QUIC-TLS:
     title: "Using Transport Layer Security (TLS) to Secure QUIC"
     date: {DATE}
@@ -114,10 +112,53 @@ endpoints use QUIC packets to establish a QUIC connection, which is shared
 protocol state between those endpoints.
 
 
+# Notational Conventions
+
+Packet diagrams in this document use a format defined in {{QUIC-TRANSPORT}} to
+illustrate the order and size of fields.
+
+Complex fields are named and then followed by a list of fields surrounded by a
+pair of matching braces. Each field in this list is separated by commas.
+
+Individual fields include length information, plus indications about fixed
+value, optionality, or repetitions. Individual fields use the following
+notational conventions, with all lengths in bits:
+
+x (A):
+: Indicates that x is A bits long
+
+x (A..B):
+: Indicates that x can be any length from A to B; A can be omitted to indicate
+  a minimum of zero bits and B can be omitted to indicate no set upper limit;
+  values in this format always end on an octet boundary
+
+x (?) = C:
+: Indicates that x has a fixed value of C
+
+x (E) ...:
+: Indicates that x is repeated zero or more times (and that each instance is
+  length E)
+
+{{fig-ex-format}} shows an example structure:
+
+~~~
+Example Structure {
+  One-bit Field (1),
+  7-bit Field with Fixed Value (7) = 61,
+  Arbitrary-Length Field (..),
+  Variable-Length Field (8..24),
+  Repeated Field (8) ...,
+}
+~~~
+{: #fig-ex-format title="Example Format"}
+
+
 # QUIC Packet Headers
 
-A QUIC packet is the content of the UDP datagrams exchanged by QUIC endpoints.
-This document describes the contents of those datagrams.
+QUIC endpoints exchange UDP datagrams that contain one or more QUIC packets.
+This section describes the invariant characteristics of a QUIC packet.  A
+version of QUIC could permit multiple QUIC packets in a single UDP datagram, but
+the invariant properties only describe the first packet in a datagram.
 
 QUIC defines two types of packet header: long and short.  Packets with long
 headers are identified by the most significant bit of the first byte being set;
@@ -136,9 +177,9 @@ Long Header Packet {
   Header Form (1) = 1,
   Version-Specific Bits (7),
   Version (32),
-  DCID Len (8),
+  DCID Length (8),
   Destination Connection ID (0..2040),
-  SCID Len (8),
+  SCID Length (8),
   Source Connection ID (0..2040),
   Version-Specific Data (..),
 }
@@ -152,13 +193,13 @@ The next four bytes include a 32-bit Version field (see {{version}}).
 
 The next byte contains the length in bytes of the Destination Connection ID (see
 {{connection-id}}) field that follows it.  This length is encoded as an 8-bit
-unsigned integer.  The Destination Connection ID field follows the DCID Len
+unsigned integer.  The Destination Connection ID field follows the DCID Length
 field and is between 0 and 255 bytes in length.
 
 The next byte contains the length in bytes of the Source Connection ID field
 that follows it.  This length is encoded as a 8-bit unsigned integer.  The
-Source Connection ID field follows the SCID Len field and is between 0 and 255
-bytes in length.
+Source Connection ID field follows the SCID Length field and is between 0 and
+255 bytes in length.
 
 The remainder of the packet contains version-specific content.
 
@@ -215,6 +256,7 @@ protocol that does not conform to the properties described in this document is
 not QUIC.  Future documents might describe additional properties which apply to
 a specific QUIC version, or to a range of QUIC versions.
 
+
 # Version Negotiation {#version-negotiation}
 
 A QUIC endpoint that receives a packet with a long header and a version it
@@ -232,16 +274,15 @@ Version Negotiation Packet {
   Header Form (1) = 1,
   Unused (7),
   Version (32) = 0,
-  DCID Len (8),
+  DCID Length (8),
   Destination Connection ID (0..2040),
-  SCID Len (8),
+  SCID Length (8),
   Source Connection ID (0..2040),
   Supported Version (32) ...,
 }
 ~~~
 {: #version-negotiation-format title="Version Negotiation Packet"}
 
-
 The Version Negotiation packet contains a list of Supported Version fields, each
 identifying a version that the endpoint sending the packet supports.  The
 Supported Version fields follow the Version field.  A Version Negotiation packet