HTTP Datagrams and the Capsule Protocol
draft-ietf-masque-h3-datagram-11

[Ballot comment]
# GEN AD review of draft-ietf-masque-h3-datagram-10

CC @larseggert

Thanks to Maria Ines Robles for the General Area Review Team (Gen-ART) review
(https://mailarchive.ietf.org/arch/msg/gen-art/diaocJcywSJa1ENAlJvPf3z2R70).

## Comments

### Inclusive language

Found terminology that should be reviewed for inclusivity; see
https://www.rfc-editor.org/part2/#inclusive_language for background and more
guidance:

* Term `natively`; alternatives might be `built-in`, `fundamental`,
  `ingrained`, `intrinsic`, `original`

## Nits

All comments below are about very minor potential issues that you may choose to
address in some way - or ignore - as you see fit. Some were flagged by
automated tools (via https://github.com/larseggert/ietf-reviewtool), so there
will likely be some false positives. There is no need to let me know what you
did with these suggestions.

### Grammar/style

#### Section 2.1, paragraph 8
```
eived with a value that is neither 0 or 1, the receiver MUST terminate the c
                                    ^^
```
Use "nor" with neither.

#### Section 3.2, paragraph 16
```
ied to be self-consistent. If the receive side of a stream carrying capsules
                                  ^^^^^^^
```
Did you mean the noun "reception" (= the act of receiving) or "receipt" (=
invoice)? Or use "receive-side"?

## Notes

This review is in the ["IETF Comments" Markdown format][ICMF], You can use the
[`ietf-comments` tool][ICT] to automatically convert this review into
individual GitHub issues. Review generated by the [`ietf-reviewtool`][IRT].

[ICMF]: https://github.com/mnot/ietf-comments/blob/main/format.md
[ICT]: https://github.com/mnot/ietf-comments
[IRT]: https://github.com/larseggert/ietf-reviewtool

[Ballot comment]
Why might an implementer not do what the SHOULDs say in Section 3.2?  I guess I'm wondering why, in a new thing, one would give someone a reason to produce an implementation that is intentionally not forward-compatible.  Otherwise, nice work; I like to complain about SHOULD a lot lately, and this document did an above average job of using it.

I believe Sections 5.1 through 5.3 should refer to these registries as sub-registries of the main "Hypertext Transfer Protocol version 3 (HTTP/3)" registry.

Also, I don't think the MUSTs in Section 5.4 are appropriate when describing IANA actions.  I suggest "will not" instead of "MUST NOT".

[Ballot comment]
Why might an implementer not do what the SHOULDs say in Section 3.2?  I guess I'm wondering why, in a new thing, one would give someone a reason to produce an implementation that is intentionally not forward-compatible.  Otherwise, nice work; I like to complain about SHOULD a lot lately, and this document did an above average job of using it.

I believe Sections 5.1 through 5.3 should refer to these registries as sub-registries of the main "Hypertext Transfer Protocol version 3 (HTTP/3)" registry.

Also, I don't think the MUSTs in Section 5.4 are appropriate when describing IANA actions.  I would suggest "will not" instead of "MUST NOT".

[Ballot comment]
Thanks for working on this specification.

I have some questions and one suggestion, and I believe addressing them will improve the document.

- Section 2 : should it be HTTP/1.x instead of HTTP/1 :-)?
- Section 2 : it says

          "value MUST be treated as an HTTP/3 connection error of type H3_DATAGRAM_ERROR (0x33)"
     
    does this mean request stream MUST be aborted as it was also written in the section?

- Section 3 in general : I think we can be specific that "intermediaries" are HTTP intermediaries as defined in HTTP semantic , as it is done in the draft-masque-connect-udp?

[Ballot comment]
# Éric Vyncke, INT AD, comments for draft-ietf-masque-h3-datagram-10
CC @evyncke

Thank you for the work put into this document. It is short, easy to read, and will be useful.

Please find below some non-blocking COMMENT points (but replies would be appreciated even if only for my own education).

Special thanks to Chris Wood for the shepherd's detailed write-up including the WG consensus and the justification of the intended status.

I hope that this helps to improve the document,

Regards,

-éric

## COMMENTS

### Abstract

s/This document describes HTTP Datagrams/This document specifies HTTP Datagrams and the Capsule Protocol/ ?

### Section 1
For consistency with other reasons, should a reference be added to `unreliable version of the CONNECT method` ?

### Section 2
```
  HTTP extensions can
  override these requirements by defining a negotiation mechanism and
  semantics for HTTP Datagrams.
```
s/can/MAY/ ? (but I am not a native English speaker) I also noticed that 'MAY' is used at the end of section 2.1.

### Section 2.2

I wonder whether this small section is useful. The text should rather go into the intro of section 3.

### Section 3.4

While I am not too familiar with HTTP & QUIC, I wonder when reading `Endpoints indicate that the Capsule Protocol is in use on a data stream by sending a Capsule-Protocol header field with a true value.` Until now, the Capsule Header is not yet defined even less how to send a true value (or did I misread part of the I-D)

### Section 3.5
```
Since QUIC DATAGRAM frames are required to fit within a QUIC packet,
  implementations that reencode DATAGRAM capsules into QUIC DATAGRAM
  frames might be tempted to accumulate the entire capsule before
  reencoding it.  This can cause flow control problems; see
  Section 3.2.
```
The problem is clear, but what is the recommendation for implementers ?

## Notes

This review is in the ["IETF Comments" Markdown format][ICMF], You can use the
[`ietf-comments` tool][ICT] to automatically convert this review into
individual GitHub issues.

[ICMF]: https://github.com/mnot/ietf-comments/blob/main/format.md
[ICT]: https://github.com/mnot/ietf-comments

[Ballot comment]
Thank you to David Mandelberg for the SECDIR review.

** Section 4.  Consider adding the following clarification:

NEW
HTTP Datagrams and the Capsule Protocol are building blocks for HTTP extensions to define new behaviors or features and do not constitute an independent protocol.  Any extension adopting them will need to perform an appropriate security analysis which considers the impact of these features in the context of a complete protocol.

[Ballot comment]
# Internet AD comments for {draft-ietf-masque-h3-datagram-10}
CC @ekline

## Comments

### S3.2

* Possibly the definition of Capsule Type should mention the IANA registry
  via a short reference ("; see Section 5.4").

* If new 2xx codes are defined in the future, are they required to state
  what their suitability is in scenarios upgrading to Capsule Protocol use?

  If so, is there any additional guidance beyond what one could divine
  from a reading of the 2nd to last paragraph?

  (New 2xx codes seem extremely unlikely, but is such a thing completely
  impossible?)

(Via drafts-lastcall@iana.org): IESG/Authors/WG Chairs:

The IANA Functions Operator has completed its review of draft-ietf-masque-h3-datagram-09. If any part of this review is inaccurate, please let us know.

The IANA Functions Operator understands that, upon approval of this document, there are three actions which we must complete.

First, in the HTTP/3 Settings registry on the Hypertext Transfer Protocol version 3 (HTTP/3) registry page located at:

https://www.iana.org/assignments/http3-parameters/

a new registration is to be made as follows:

Value: 0x33
Setting Name: SETTINGS_H3_DATAGRAM
Default: 0
Status: permanent
Reference: [ RFC-to-be ]
Date: [ TBD-at-Registration ]
Change Controller: IETF
Contact: [HTTP_WG]
Notes:

Second, in the HTTP/3 Error Code registry also on the Hypertext Transfer Protocol version 3 (HTTP/3) registry page located at:

https://www.iana.org/assignments/http3-parameters/

a new registration is to be made as follows:

Value: 0x33
Name: H3_DATAGRAM_ERROR
Description: Datagram or capsule protocol parse error
Status: permanent
Reference: [ RFC-to-be ]
Date: [ TBD-at-Registration ]
Change Controller: IETF
Contact: [HTTP_WG]
Notes:

Third, in the Hypertext Transfer Protocol (HTTP) Field Name Registry located at:

https://www.iana.org/assignments/http-fields/

a new registration will be made as follows:

Field Name: Capsule-Protocol
Template: [none]
Status: permanent
Reference: [ RFC-to-be ]
Comments: [none]

As this document requests registrations in an Expert Review (see RFC 8126) registry, we will initiate the required Expert Review via a separate request. This review must be completed before the document's IANA state can be changed to "IANA OK."

The IANA Functions Operator understands that these are the only actions required to be completed upon approval of this document.

Note:  The actions requested in this document will not be completed until the document has been approved for publication as an RFC. This message is meant only to confirm the list of actions that will be performed.

For definitions of IANA review states, please see:

https://datatracker.ietf.org/help/state/draft/iana-review

Thank you,

Michelle Thangtamsatid
IANA Services Specialist

The following Last Call announcement was sent out (ends 2022-06-08):

From: The IESG
To: IETF-Announce
CC: caw@heapingbits.net, draft-ietf-masque-h3-datagram@ietf.org, martin.h.duke@gmail.com, masque-chairs@ietf.org, masque@ietf.org
Reply-To: last-call@ietf.org
Sender:
Subject: Last Call:  (HTTP Datagrams and the Capsule Protocol) to Proposed Standard


The IESG has received a request from the Multiplexed Application Substrate
over QUIC Encryption WG (masque) to consider the following document: - 'HTTP
Datagrams and the Capsule Protocol'
  as Proposed Standard

The IESG plans to make a decision in the next few weeks, and solicits final
comments on this action. Please send substantive comments to the
last-call@ietf.org mailing lists by 2022-06-08. Exceptionally, comments may
be sent to iesg@ietf.org instead. In either case, please retain the beginning
of the Subject line to allow automated sorting.

Abstract


  This document describes HTTP Datagrams, a convention for conveying
  multiplexed, potentially unreliable datagrams inside an HTTP
  connection.

  In HTTP/3, HTTP Datagrams can be conveyed natively using the QUIC
  DATAGRAM extension.  When the QUIC DATAGRAM frame is unavailable or
  undesirable, they can be sent using the Capsule Protocol, a more
  general convention for conveying data in HTTP connections.

  HTTP Datagrams and the Capsule Protocol are intended for use by HTTP
  extensions, not applications.




The file can be obtained via
https://datatracker.ietf.org/doc/draft-ietf-masque-h3-datagram/



No IPR declarations have been submitted directly on this I-D.

# Document Shepherd Writeup

1. Does the working group (WG) consensus represent the strong concurrence of a few individuals, with others being silent, or did it reach broad agreement?

This document reached broad agreement across the group.

2. Was there controversy about particular points, or were there decisions where the consensus was particularly rough?

There was some initial controversy around the role of HTTP intermediaries in the protocol (are they explicit? what role do they play? what are they allowed to do or not do with messages sent up or downstream?), though these concerns were resolved as a byproduct of a Design Team that worked on the document.

3. Has anyone threatened an appeal or otherwise indicated extreme discontent? If so, please summarize the areas of conflict in separate email messages to the responsible Area Director. (It should be in a separate email because this questionnaire is publicly available.)

No.

4. For protocol documents, are there existing implementations of the contents of the document? Have a significant number of potential implementers indicated plans to implement? Are any existing implementations reported somewhere, either in the document itself (as RFC 7942 recommends) or elsewhere (where)?

Yes, there are several interoperable implementations of the document. Some of them are open source [1,2] whereas others are closed source. Other implementations can be provided upon request.

[1] https://github.com/google/quiche
[2] https://github.com/facebookincubator/mvfst

5. Does this document need review from other IETF working groups or external organizations? Have those reviews occurred?

This document is relevant to the QUIC and WebTransport WGs, and both WGs were included on the WGLC thread, so we believe this review has occurred.

6. Describe how the document meets any required formal expert review criteria, such as the MIB Doctor, YANG Doctor, media type, and URI type reviews.

N/A

7. If the document contains a YANG module, has the final version of the module been checked with any of the recommended validation tools for syntax and formatting validation? If there are any resulting errors or warnings, what is the justification for not fixing them at this time? Does the YANG module comply with the Network Management Datastore Architecture (NMDA) as specified in RFC 8342?

N/A

8. Describe reviews and automated checks performed to validate sections of the final version of the document written in a formal language, such as XML code, BNF rules, MIB definitions, CBOR's CDDL, etc.

Wire format details (such as that used to describe the Capsule structure) have been validated by multiple people.

9. Based on the shepherd's review of the document, is it their opinion that this document is needed, clearly written, complete, correctly designed, and ready to be handed off to the responsible Area Director?

Yes, this document is needed, clearly written, complete, correctly designated, and ready to be handed off to the responsible AD.

10. Several IETF Areas have assembled lists of common issues that their reviewers encounter. Do any such issues remain that would merit specific attention from subsequent reviews?

No.

11. What type of RFC publication is being requested on the IETF stream (Best Current Practice, Proposed Standard, Internet Standard, Informational, Experimental, or Historic)? Why is this the proper type of RFC? Do all Datatracker state attributes correctly reflect this intent?

Proposed Standard to match backing standards like RFC 9000. The Datatracker state attributes correctly reflect this intent.

12. Has the interested community confirmed that any and all appropriate IPR disclosures required by BCP 78 and BCP 79 have been filed? If not, explain why. If yes, summarize any discussion and conclusion regarding the intellectual property rights (IPR) disclosures, including links to relevant emails.

Yes. The authors confirmed that they are not aware of any IPR related to this draft.

13. Has each Author or Contributor confirmed their willingness to be listed as such? If the number of Authors/Editors on the front page is greater than 5, please provide a justification.

Yes. Each author is willing to be listed as such.

14. Identify any remaining I-D nits in this document. (See the idnits tool and the checkbox items found in Guidelines to Authors of Internet-Drafts). Simply running the idnits tool is not enough; please review the entire guidelines document.

There are some id-nits issues remaining but they are due to non-ASCII characters in names, so they can be resolved by the RPC.

15. Should any informative references be normative or vice-versa?

No.

16. List any normative references that are not freely available to anyone. Did the community have sufficient access to review any such normative references?

N/A

17. Are there any normative downward references (see RFC 3967, BCP 97)? If so, list them.

No.

18. Are there normative references to documents that are not ready for advancement or are otherwise in an unclear state? If they exist, what is the plan for their completion?

Yes:

- draft-ietf-httpbis-semantics-19
- draft-ietf-httpbis-messaging-19
- draft-ietf-httpbis-http2bis-07
- draft-ietf-quic-http-34

All documents are moving ahead in the process and we don't expect them to be significant blockers.

19. Will publication of this document change the status of any existing RFCs? If so, does the Datatracker metadata correctly reflect this and are those RFCs listed on the title page, in the abstract, and discussed in the introduction? If not, explain why and point to the part of the document where the relationship of this document to these other RFCs is discussed.

No.

20. Describe the document shepherd's review of the IANA considerations section, especially with regard to its consistency with the body of the document. Confirm that all aspects of the document requiring IANA assignments are associated with the appropriate reservations in IANA registries. Confirm that any referenced IANA registries have been clearly identified. Confirm that each newly created IANA registry specifies its initial contents, allocations procedures, and a reasonable name (see RFC 8126).

The IANA considerations of the document are complete, clear, and correct. The new registry for Capsule types is clearly explained, has a well-defined allocation procedure, and is named reasonably.

21. List any new IANA registries that require Designated Expert Review for future allocations. Are the instructions to the Designated Expert clear? Please include suggestions of designated experts, if appropriate.

The new Capsule type registry will support provisional and permanent allocations, as per Section 22.1 of RFC9000. Provisional registries require Expert Review. We recommend David Schinazi and Lucas Pardue as the Designated Experts. Permanent registries, in contrast, require Prequire Specification Required.

# Document Shepherd Writeup

1. Does the working group (WG) consensus represent the strong concurrence of a few individuals, with others being silent, or did it reach broad agreement?

This document reached broad agreement across the group.

2. Was there controversy about particular points, or were there decisions where the consensus was particularly rough?

There was some initial controversy around the role of HTTP intermediaries in the protocol (are they explicit? what role do they play? what are they allowed to do or not do with messages sent up or downstream?), though these concerns were resolved as a byproduct of a Design Team that worked on the document.

3. Has anyone threatened an appeal or otherwise indicated extreme discontent? If so, please summarize the areas of conflict in separate email messages to the responsible Area Director. (It should be in a separate email because this questionnaire is publicly available.)

No.

4. For protocol documents, are there existing implementations of the contents of the document? Have a significant number of potential implementers indicated plans to implement? Are any existing implementations reported somewhere, either in the document itself (as RFC 7942 recommends) or elsewhere (where)?

Yes, there are several interoperable implementations of the document. Some of them are open source [1,2] whereas others are closed source. Other implementations can be provided upon request.

[1] https://github.com/google/quiche
[2] https://github.com/facebookincubator/mvfst

5. Does this document need review from other IETF working groups or external organizations? Have those reviews occurred?

This document is relevant to the QUIC and WebTransport WGs, and both WGs were included on the WGLC thread, so we believe this review has occurred.

6. Describe how the document meets any required formal expert review criteria, such as the MIB Doctor, YANG Doctor, media type, and URI type reviews.

N/A

7. If the document contains a YANG module, has the final version of the module been checked with any of the recommended validation tools for syntax and formatting validation? If there are any resulting errors or warnings, what is the justification for not fixing them at this time? Does the YANG module comply with the Network Management Datastore Architecture (NMDA) as specified in RFC 8342?

N/A

8. Describe reviews and automated checks performed to validate sections of the final version of the document written in a formal language, such as XML code, BNF rules, MIB definitions, CBOR's CDDL, etc.

Wire format details (such as that used to describe the Capsule structure) have been validated by multiple people.

9. Based on the shepherd's review of the document, is it their opinion that this document is needed, clearly written, complete, correctly designed, and ready to be handed off to the responsible Area Director?

Yes, this document is needed, clearly written, complete, correctly designated, and ready to be handed off to the responsible AD.

10. Several IETF Areas have assembled lists of common issues that their reviewers encounter. Do any such issues remain that would merit specific attention from subsequent reviews?

No.

11. What type of RFC publication is being requested on the IETF stream (Best Current Practice, Proposed Standard, Internet Standard, Informational, Experimental, or Historic)? Why is this the proper type of RFC? Do all Datatracker state attributes correctly reflect this intent?

Proposed Standard to match backing standards like RFC 9000. The Datatracker state attributes correctly reflect this intent.

12. Has the interested community confirmed that any and all appropriate IPR disclosures required by BCP 78 and BCP 79 have been filed? If not, explain why. If yes, summarize any discussion and conclusion regarding the intellectual property rights (IPR) disclosures, including links to relevant emails.

Yes. The authors confirmed that they are not aware of any IPR related to this draft.

13. Has each Author or Contributor confirmed their willingness to be listed as such? If the number of Authors/Editors on the front page is greater than 5, please provide a justification.

Yes. Each author is willing to be listed as such.

14. Identify any remaining I-D nits in this document. (See the idnits tool and the checkbox items found in Guidelines to Authors of Internet-Drafts). Simply running the idnits tool is not enough; please review the entire guidelines document.

There are some id-nits issues remaining but they are due to non-ASCII characters in names, so they can be resolved by the RPC.

15. Should any informative references be normative or vice-versa?

No.

16. List any normative references that are not freely available to anyone. Did the community have sufficient access to review any such normative references?

N/A

17. Are there any normative downward references (see RFC 3967, BCP 97)? If so, list them.

No.

18. Are there normative references to documents that are not ready for advancement or are otherwise in an unclear state? If they exist, what is the plan for their completion?

Yes:

- draft-ietf-httpbis-semantics-19
- draft-ietf-httpbis-messaging-19
- draft-ietf-httpbis-http2bis-07
- draft-ietf-quic-http-34

All documents are moving ahead in the process and we don't expect them to be significant blockers.

19. Will publication of this document change the status of any existing RFCs? If so, does the Datatracker metadata correctly reflect this and are those RFCs listed on the title page, in the abstract, and discussed in the introduction? If not, explain why and point to the part of the document where the relationship of this document to these other RFCs is discussed.

No.

20. Describe the document shepherd's review of the IANA considerations section, especially with regard to its consistency with the body of the document. Confirm that all aspects of the document requiring IANA assignments are associated with the appropriate reservations in IANA registries. Confirm that any referenced IANA registries have been clearly identified. Confirm that each newly created IANA registry specifies its initial contents, allocations procedures, and a reasonable name (see RFC 8126).

The IANA considerations of the document are complete, clear, and correct. The new registry for Capsule types is clearly explained, has a well-defined allocation procedure, and is named reasonably.

21. List any new IANA registries that require Designated Expert Review for future allocations. Are the instructions to the Designated Expert clear? Please include suggestions of designated experts, if appropriate.

The new Capsule type registry will support provisional and permanent allocations, as per Section 22.1 of RFC9000. Provisional registries require Expert Review. We recommend David Schinazi and Lucas Pardue as the Designated Experts. Permanent registries, in contrast, require Prequire Specification Required.