Adding an Extensible Object Header

draft-ietf-moq-transport.md

@@ -984,6 +984,21 @@ client MUST set the PATH parameter to the `path-abempty` portion of the
 URI; if `query` is present, the client MUST concatenate `?`, followed by
 the `query` portion of the URI to the parameter.
 
+#### REQUESTED-EXTENSION parameter {#requested-extensions}
+
+The REQUESTED-EXTENSION parameter (key 0x02) allows the client to request
+the server to acknowledge support for  multiple Extension Header types
+{{object-extensions}} which are required for operation. The value is a
+concatenation of varints, each describing an integer extension header type.
+This parameter is optional. If this parameter is present in the
+CLIENT_SETUP message, then the server MUST respond with a
+REQUESTED-EXTENSION parameter in its SERVER_SETUP message. This parameter
+MUST list the subset of those extensions previously requested by the client
+which the server supports. If the server does not support any of the
+requested extensions, then it MUST respond with a parameter value length of 0.
+The client can then choose to continue or disconnect the session, at its
+discretion.
+
 ## GOAWAY {#message-goaway}
 The server sends a `GOAWAY` message to initiate session migration
 ({{session-migration}}) with an optional URI.
@@ -1511,6 +1526,12 @@ MUST be sent according to its `Object Forwarding Preference`, described below.
 * Object Status: As enumeration used to indicate missing
 objects or mark the end of a group or track. See {{object-status}} below.
 
+* Object Extension Count: The number of Object Extensions present. A value of 0
+  indicates that no Object Extension Headers are present.
+
+* Object Extensions : an optional concatenation of Object Extension Headers. See
+  {{object-extensions}} below.
+
 * Object Payload: An opaque payload intended for an End Subscriber and SHOULD
 NOT be processed by a relay. Only present when 'Object Status' is Normal (0x0).
 
@@ -1557,6 +1578,62 @@ are sent on a new stream. This is to avoid the status message being lost
 in cases such as a relay dropping a group and reseting the stream the
 group is being sent on.
 
+#### Object Extension {#object-extensions}
+An Object Extension is a concatenation of optional Extension Headers. These
+headers are visible to relays. Extension headers MUST be forwarded and
+MUST NOT be modified by relays. The purpose of Extension Headers is to
+allow the transmission of application-specific data as well as future
+evolution of the transport protocol. Object Extensions are serialized as
+defined below:
+
+~~~
+Object Extension {
+  Extension Header (..) ...
+}
+
+Extension Header {
+  Header Type (i),
+  Header Length (i),
+  Header Value (..)
+}
+~~~
+{: #object-extension-format title="Object Extension Header Format"}
+
+* Header type: an unsigned integer, encoded as a varint and registered in the
+  IANA table 'MOQ Extension Headers'. See {{iana}}.
+
+##### Extension Header type 0 {#extension-header-zero}
+
+This specification defines a utility extension header. The value of this header
+is itself a name-value pair.
+
+
+| Type |                         Value                        |
+| ---- | ---------------------------------------------------- |
+| 0x0  | Header Value  - see {{extension-header-zero-format}} |
+
+
+~~~
+Header Value {
+  Name Length (i),
+  Name Value (..)
+  Payload (..)
+}
+~~~
+{: #extension-header-zero-format title="Extension header 0 value format"}
+
+* Name Length: the size of the name value in bytes.
+* Name Value: a string encoded using ISO-8859-1. This name is application-defined
+  and is not IANA registered.
+* Payload: the contents of the header. The combined size of the name and payload
+  contents MUST NOT exceed 10240 bytes.
+
+### Object Message Formats
+
+Every Track has a single 'Object Forwarding Preference' and the Original
+Publisher MUST NOT mix different forwarding preferences within a single track.
+If a subscriber receives different forwarding preferences for a track, it
+SHOULD close the session with an error of 'Protocol Violation'.
 
 ## Object Stream
 
@@ -1577,6 +1654,8 @@ OBJECT_STREAM Message {
   Group ID (i),
   Object ID (i),
   Publisher Priority (8),
+  Extension Count (i),
+  [Extension headers (...)],
   Object Payload Length (i),
   [Object Status (i)],
   Object Payload (..),
@@ -1613,6 +1692,8 @@ OBJECT_DATAGRAM Message {
   Group ID (i),
   Object ID (i),
   Publisher Priority (8),
+  Extension Count (i),
+  [Extension headers (...)],
   Object Payload Length (i),
   [Object Status (i)],
   Object Payload (..),
@@ -1771,6 +1852,38 @@ OBJECT_STREAM {
 }
 ~~~
 
+Sending a group on one stream, with the first object containing an
+Extension Header.
+
+~~~
+Stream = 2
+
+STREAM_HEADER_GROUP {
+  Subscribe ID = 2
+  Track Alias = 2
+  Group ID = 0
+  Publisher Priority = 0
+}
+{
+  Object ID = 0
+  Extension Count  = 1
+    { Type = 0
+      Length = 21
+        { Name length = 15
+          Name value = "example-traceID"
+          Payload = "123456"
+        }
+    }
+  Object Payload Length = 4
+  Payload = "abcd"
+}
+{
+  Object ID = 1
+  Object Payload Length = 4
+  Payload = "efgh"
+}
+
+~~~
 
 
 # Security Considerations {#security}
@@ -1806,6 +1919,10 @@ TODO: fill out currently missing registries:
 * Subscribe Error codes
 * Announce Error codes
 * Message types
+* MOQ Extension headers - we wish to reserve extension types 0-127 for
+  standards utilization where space is a premium, 128 - 16383 for
+  standards utilization where space is less of a concern, and 16384 and
+  above for first-come-first-served non-standardization usage.
 
 TODO: register the URI scheme and the ALPN