AD Review of draft-ietf-httpbis-binary-message-03

[Francesca Palombini <[e-mail]>]

# AD Review of draft-ietf-httpbis-binary-message-03

cc @fpalombini

## Comments

Thank you for this short and well written document.

No major comments from me, only a couple of minor requests for clarifications and some nits, which you can address together with any other last call comments. Nothing controversial, feel free to take or leave, however answers are appreciated.

### Clarification on optional informational response field

Section 3.1:
>   That is, a known-length message consists of a framing indicator, a
>   block of control data that is formatted according to the value of the
>   framing indicator, a header section with a length prefix, binary
>   content with a length prefix, and a trailer section with a length
>   prefix.

Section 3.2:
>   That is, an indeterminate length consists of a framing indicator, a
>   block of control data that is formatted according to the value of the
>   framing indicator, a header section that is terminated by a zero
>   value, any number of non-zero-length chunks of binary content, a zero
>   value, and a trailer section that is terminated by a zero value.

At this point in the text I thought this was missing the optional Informational response field, but you say explain that several paragraph later. Maybe clarify here that this is for messages that are not responses containing informational status codes, or move those paragraphs closer together?

### Length prefix

Section 3.1:
>   For a known-length encoding, the length prefix on field sections and
>   content is a variable-length encoding of an integer.  This integer is
>   the number of bytes in the field section or content.

Might be worth clarifying that this integer value does not include the length bytes. My comment comes from the fact that "field section" is the name of the structure containing the length, so "number of bytes in the field section" could be interpreted to include the length bytes itself.

### Normatively reference HTTP/2

Section 3.4:
>   The values of these fields follow the rules in HTTP/2 (Section 8.3.1

Section 3.6:
>   A recipient MUST treat a message that contains field
>   values that would cause an HTTP/2 message to be malformed according
>   to Section 8.2.1 of [HTTP/2] as invalid; see Section 4.

I think HTTP/2 should be a normative reference.

### Add reference for status code

Section 3.5:
>    The control data for a response message consists of the status code.

Please reference RFC-ietf-httpbis-semantics, Section 16.2.1 or Section 15, or the IANA registry: https://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml after "status code".

### "Final" Response Control Data

Section 3.5:
```
      The format of final response control data is shown in Figure 4.

   Final Response Control Data {
     Status Code (i) = 200..599,
   }

              Figure 4: Format of Final Response Control Data
```
I see that the Section 3.5.1 talks about "final status code":
>  associated header section until the final status code is encoded.

and that explains why you called it "final" in section 3.5, but I think you  need to define why "final" is used in the "final response control data" when it first appear (so in Section 3.5), or you can remove "final" in 3.5 and explain that only in 3.5.1.

### information status code

Section 3.5.1:
>   Responses that include information status codes (see Section 15.2 of

>   that precede a final status code.  These convey an information status
>   code and a header block.

Should these be "informational" rather than "information"?

### indeterminate vs indefinite

The document uses "indeterminate length" and "indefinite length" interchangeably. I would suggest either using only one, or adding "indeterminate" when the first "indefinite" appear, i.e. in Section 1:

>   *  an indefinite-length encoding enables efficient generation of

### Media type registration

Please don't forget to send a media type review request to the media-types mailing list.

## Nits

All comments below are about very minor nits that you may choose to address in some way - or ignore - as you see fit. No need for answers.

### Editorial nits

Section 3.1, Figure 1:
>   Known-Length Content {
>     Content Length (i),
>     Content (..)
>   }

Section 3.2, Figure 2:
>   Indeterminate-Length Content Chunk {
>     Chunk Length (i) = 1..,
>     Chunk (..)
>   }

For consistency with the rest of Figure 1, you could add a comma after Content(..) and Chunk (..)

Section 3.2:
>   That is, an indeterminate length consists of a framing indicator, a

Missing word "message"

Section 3.6:
>   whether the message is known- or intermediate-length.

s/intermediate/indeterminate

## 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