Draft: draft-ietf-masque-h3-datagram

Commentary: After spending some time on CONNECT - IP , I realized that the current design wo n't work well . The primary motivation for including contexts and formatting in this document ( as opposed to in the individual drafts ) is that it allows to build a layer that can handle extensions without round trip negotiations : in particular it means clients can start using an extension format immediately without waiting for the HTTP response . For that to work , the server needs to drop unknown formats , so we need a single format enum as opposed to a list of them - that way the entire context is ignored instead of accepting the context but ignoring the extension that might have changed the encoding . . 
 The document currently has a lot of tools , but there are different ways of thinking about how you could use them and why they 're in the protocol . I feel like readability would improve dramatically if the document started with an overview that described one or two hypothetical flows . Not fully fleshed out protocols -- just an example of declaring a context associated to a request , request headers that inform the context , context extensions that inform it , exchanging datagrams , and closing the context . The document makes reference to a few possible applications ; maybe one of these could be drawn a little bit larger ? 
 For this request , what do you feel is missing from the examples in appendix A ? The reason I ask is that including those specific examples is n't great for the final version of this draft , the CONNECT - UDP spec is the canoncical source of the sequence and it depends on this document . If there was a way to describe an example workflow in a more abstract sense , that addresses the gaps you 're suggesting , then that would be a great candidate to keep in the document all the way through . 
 Those are somewhat helpful , except that they 're not referenced from the text . Besides the cross - reference , the thing that 's missing is a little bit of prose explaining why each element is sent at that point . Are they identifying the protocol being used in that context ? Are they carrying configuration for that protocol ? The examples could perhaps be generalized by describing " an extension that carries supplemental metadata about the request , " " an application carrying data referenced by the request , " etc . 
 Sent to the WG mailing list . I and my co - authors on have had some discussion around how one actually can and should be using the context - ID registration mechanism . This as we are actually need it to realize some of the functionality in our CONNECT - IP solution . We have found several ways that appear to practically work from an CONNECT - IP application perspective . A ) Statically define that in the context of CONNECT - IP the application will map certain formats to certain ContextID , and simply send registrations without any extension headers . B ) Define a Context Extension that is intended to provide format identifiers for the CONNECT - IP method different formats . C ) Use values or parameters in HTTP headers related to the format to carry the identifiers . D ) Combine A and B , so that we have a set of initially statically defined mappings , and then use Context Extension for any future extensions . In our discussion we see that C appears to have some potential for failure modes if an HTTP intermediary does things with the headers . A ) is very straight forward for an application initially but can run into trouble when needing to be extended but HTTP level negotiation of the general functionality should resolve those . B ) appears to have some overhead from an application perspective as each application needs to define its own Context Extension to carry identifiers . Is it really intended that each HTTP application that needs to convey some identifier for its Context ID format to carry across the HTTP Datagram capsule . Would there be a point in defining a Context Extension that carries format identifier for what one like to use this context ID . D ) appears to be simple initially , but leads to the extension mechanism having code paths that would not be exercised by default So this was basically to start a discussion to see if we can get a bit more clearer guidance towards the HTTP application writers that will attempt to use HTTP Datagram on how to actually use Context IDs . I noted that the Connect - UDP method was no help as example yet . 
 Thanks for writing this up Using your nomenclature , the draft is currently written with the intent of using ( B ) . That allows maximal extensibility while ensuring that the extension codepath is well used . The overhead of registering a 62bit integer seems negligible to me - since each application needs to define its payload format somewhere , defining its negotiation format and registering an integer alongside seems easy . Can you think of any use cases that are not well served by ( B ) ? 
 Thanks for clarifying your thoughts on what you had intended . And I do n't think there are any question if will serve the application . However , as there where no actually defined usage yet we where a bit uncertain of the intention here . I would note that each standardized application registering its own extension , will cause another IANA registry for the format values . But it clearly have a benefit from being a forensic perspective , as each application will be ID by its extension type , and then its value . 
 Can you clarify your note ? The document currently sets up the " HTTP Context Extension Types " IANA registry . What other IANA registry did you have in mind ? Formats do n't need a registry . To make an analogy , we have an IANA registry for UDP port numbers but no IANA registry for the format of UDP payloads , as those are defined by specifications not registries . 
 So , lets take CONNECT - IP as an example . It will define and register a Context Extension Type for Connect - IP context IDs . In our current draft for Connect - IP we currently have 4 different formats that will need to be expressed by context ID registrations . We also have the ideas of at least one more to carry ECN . So the current specification will define what the first 4 values do . Then if we define the ECN one as a separate specification as additional extensions of CONNECT - IP formats . Thus we are in a situation where we need additional context - IDs identifiers , then the right thing to ensure that the format to value mapping is well managed is to create a new IANA registry for CONNECT - IP Context Extension Format to value mapping . 
 I 'm not sure I follow . You can have solve this by registering two Context Extension Types : one for the draft - kuehlewind - masque - connect - ip format which has the four values from that draft one for ECN which has four values Not - ECT / ECT(0)/ECT(1)/CE and then you compose the results ( by which I mean you can send multiple extensions in one REGISTERDATAGRAMCONTEXT capsule ) . I do n't see how a separate registry helps ?
When an endpoint registers a datagram context (or the lack of
contexts), it communicates the format (i.e., the semantics and
encoding) of datagrams sent using this context.  This is
acccomplished by sending a Datagram Format Type as part of the
registration capsule, see register-capsule and register-no-context-
capsule.  This type identifier is registered with IANA (see iana-
format-types) and allows applications that use HTTP Datagrams to
indicate what the content of datagrams are.  Registration capsules
carry a Datagram Format Additional Data field which allows sending
some additional information that would impact the format of
datagrams.
For example, a protocol which proxies IP packets can define a
Datagram Format Type which represents an IP packet.  The
corresponding Datagram Format Additional Data field would be empty.
An extension to such a protocol that wishes to compress IP addresses
could define a distinct Datagram Format Type and exchange two IP
addresses via the Datagram Format Additional Data field.  Then any
datagrams with that type would contain the IP packet with addresses
elided.
A variable-length integer that defines the semantics and encoding
of the HTTP Datagram Payload field of datagrams with this context
ID, see datagram-formats.
This field carries additional information that impact the format
of datagrams with this context ID, see datagram-formats.
A variable-length integer that defines the semantics and encoding
of the HTTP Datagram Payload field of datagrams, see datagram-
formats.
This field carries additional information that impact the format
of datagrams, see datagram-formats.
The close code allows an endpoint to provide additional
information as to why a datagram context was closed.  The codes
are defined in close-codes.
This is meant for debugging purposes.  It consists of a human-
readable string encoded in UTF-8.
Note that this close is unilateral and bidirectional: the sender of
the frame unilaterally informs its peer of the closure.  Endpoints
can use CLOSE_DATAGRAM_CONTEXT capsules to close a context that was
initially registered by either themselves, or by their peer.
Endpoints MAY use the CLOSE_DATAGRAM_CONTEXT capsule to immediately
reject a context that was just registered using a
REGISTER_DATAGRAM_CONTEXT capsule if they find its Context Extensions
field to be unacceptable.
Note that this close is unilateral and bidirectional: the sender of
the frame unilaterally informs its peer of the closure.  Endpoints
can use CLOSE_DATAGRAM_CONTEXT capsules to close a context that was
initially registered by either themselves, or by their peer.
Endpoints MAY use the CLOSE_DATAGRAM_CONTEXT capsule to immediately
reject a context that was just registered using a
REGISTER_DATAGRAM_CONTEXT capsule if they find its Datagram Format
Type field to be unacceptable.
All CLOSE_DATAGRAM_CONTEXT capsules MUST contain a CLOSE_CODE context
extension, see close-code.  If an endpoint receives a
CLOSE_DATAGRAM_CONTEXT capsule without a CLOSE_CODE context
extension, the endpoint MUST abruptly terminate the corresponding
stream with a stream error of type H3_GENERAL_PROTOCOL_ERROR.
This specification defines the close codes below.  Their numeric
values are in iana-close-codes.
This indicates that the sender does not know how to interpret the
datagram format type associated with this context.  The endpoint
that had originally registered this context MUST NOT try to
register another context with the same datagram format type on
this stream.
This indicates that the sender has rejected the context
registration based on its local policy.  The endpoint that had
originally registered this context MUST NOT try to register
another context with the same datagram format type and datagram
format data on this stream.
Context Extension Types are registered with IANA, see iana-ext-types.
The Context Extension Length field contains the length of the Context
Extension Value field in bytes.  The semantics of the Context
Extension Value field are defined by the corresponding Context
Extension Type.
This indicates that the sender has rejected the context
registration based on its local policy.  The endpoint that had
originally registered this context MUST NOT try to register
another context with the same context extensions on this stream.
The DETAILS context extension type (see iana-ext-types for the value
of the context extension type) allows an endpoint to provide
additional details to context capsules.  It is meant for debugging
purposes.  Its Context Extension Value field consists of a human-
readable string encoded in UTF-8.
A name or label for the context extension type.
The value of the Context Extension Type field (see context-ext) is
a 62bit integer.
A name or label for the datagram format type.
The value of the Datagram Format Type field (see datagram-formats)
is a 62bit integer.
Context extension types with a value of the form 41 * N + 17 for
integer values of N are reserved to exercise the requirement that
unknown context extension types be ignored.  These extensions have no
semantics and can carry arbitrary values.  These values MUST NOT be
assigned by IANA and MUST NOT appear in the listing of assigned
values.
The value of the CLOSE_CODE Context Extension Value field (see
close-code) is a 62bit integer.
This registry is initially empty.
Datagram format types with a value of the form 41 * N + 17 for
integer values of N are reserved to exercise the requirement that
unknown datagram format types be ignored.  These format types have no
semantics and can carry arbitrary values.  These values MUST NOT be
assigned by IANA and MUST NOT appear in the listing of assigned
values.
The value of the Close Code field (see close-capsule) is a 62bit
integer.