Binary Representation of HTTP Messages

A message that has a known length at the time of construction uses the format shown in Figure 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.¶

Response messages that contain informational status codes result in a different structure; see Section 3.5.1.¶

Fields in the header and trailer sections consist of a length-prefixed name and length-prefixed value. Both name and value are sequences of bytes that cannot be zero length.¶

The format allows for the message to be truncated before any of the length prefixes that precede the field sections or content. This reduces the overall message size. A message that is truncated at any other point is invalid; see Section 4.¶

The variable-length integer encoding means that there is a limit of 2^62-1 bytes for each field section and the message content.¶

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.¶

Response messages that contain informational status codes result in a different structure; see Section 3.5.1.¶

Indeterminate-length messages can be truncated in a similar way as known-length messages. Truncation occurs after the control data, or after the Content Terminator field that ends a field section or sequence of content chunks. A message that is truncated at any other point is invalid; see Section 4.¶

Indeterminate-length messages use the same encoding for field lines as known-length messages; see Section 3.6.¶

• A value of 0 describes a request of known length.
• A value of 1 describes a response of known length.
• A value of 2 describes a request of indeterminate length.
• A value of 3 describes a response of indeterminate length.

Other values cause the message to be invalid; see Section 4.¶

The control data for a request message includes four values that correspond to the values of the :method, :scheme, :authority, and :path pseudo-header fields described in HTTP/2 (Section 8.3.1 of [H2]). These fields are encoded, each with a length prefix, in the order listed.¶

The rules in Section 8.3 of [H2] for constructing pseudo-header fields apply to the construction of these values. However, where the :authority pseudo-header field might be omitted in HTTP/2, a zero-length value is encoded instead.¶

The format of request control data is shown in Figure 3.¶

The control data for a request message includes a single field that corresponds to the :status pseudo-header field in HTTP/2; see Section 8.3.2 of [H2]. This field is encoded as a single variable length integer, not a decimal string.¶

The format of final response control data is shown in Figure 4.¶

Header and trailer sections consist of zero or more field lines; see Section 5 of [HTTP]. The format of a field section depends on whether the message is known- or intermediate-length.¶

Each field line includes a name and a value. Both the name and value are length-prefixed sequences of bytes. The field name length is at least one byte. The format of a field line is shown in Figure 6.¶

For field names, byte values that are not permitted in an HTTP field name cause the message to be invalid; see Section 5.1 of [HTTP] for a definition of what is valid and Section 4 for handling of invalid messages.¶

Field names and values MUST be constructed and validated according to the rules of Section 8.2.1 of [H2]. A recipient MUST treat a message that contains field values that would cause an HTTP/2 message to be malformed (Section 8.1.1 of [H2]) as invalid; see Section 4.¶

The same field name can be repeated in multiple field lines; see Section 5.2 of [HTTP] for the semantics of repeated field names and rules for combining values.¶

Like HTTP/2, this format has an exception for the combination of multiple instances of the Cookie field. Instances of fields with the ASCII-encoded value of cookie are combined using a semicolon octet (0x3b) rather than a comma; see Section 8.2.3 of [H2].¶

This format provides fixed locations for content that would be carried in HTTP/2 pseudo-fields. Therefore, there is no need to include field lines containing a name of :method, :scheme, :authority, :path, or :status. Fields that contain one of these names cause the message to be invalid; see Section 4. Pseudo-fields that are defined by protocol extensions MAY be included. Field lines containing pseudo-fields MUST precede other field lines; a message that contains a pseudo-field after any other field is invalid; see Section 4.¶

The content of messages is a sequence of bytes of any length. Though a known-length message has a limit, this limit is large enough that it is unlikely to be a practical limitation. There is no limit to the size of content in an indeterminate length message.¶

Omitting content by truncating a message is only possible if the content is zero-length.¶

Messages can be padded with any number of zero-valued bytes. Non-zero padding bytes cause a message to be invalid (see Section 4). Unlike other parts of a message, a processor MAY decide not to validate the value of padding bytes.¶

Padding is compatible with truncation of empty parts of the messages. Zero-valued bytes will be interpreted as zero-length part, which is semantically equivalent to the part being absent.¶

The example HTTP/1.1 message in Figure 7 shows the content of a message/http.¶

Valid HTTP/1.1 messages require lines terminated with CRLF (the two bytes 0x0a and 0x0d). For simplicity and consistency, the content of these examples is limited to text, which also uses CRLF for line endings.¶

This can be expressed as a binary message (type message/bhttp) using a known-length encoding as shown in hexadecimal in Figure 8. Figure 8 view includes some of the text alongside to show that most of the content is not modified.¶

This example shows that the Host header field is not replicated in the :authority field, as is required for ensuring that the request is reproduced accurately; see Section 8.3.1 of [H2].¶

The same message can be truncated with no effect on interpretation. In this case, the last two bytes - corresponding to content and a trailer section - can each be removed without altering the semantics of the message.¶

The same message, encoded using an indefinite-length encoding is shown in Figure 9. As the content of this message is empty, the difference in formats is negligible.¶

This indefinite-length encoding contains 10 bytes of padding. As two additional bytes can be truncated in the same way as the known-length example, anything up to 12 bytes can be removed from this message without affecting its meaning.¶

Response messages can contain interim (1xx) status codes as the message in Figure 10 shows. Figure 10 includes examples of informational status codes defined in [RFC2518] and [RFC8297].¶

As this is a longer example, only the indefinite-length encoding is shown in Figure 11. Note here that the specific text used in the reason phrase is not retained by this encoding.¶

A response that uses the chunked encoding (see Section 7.1 of [MESSAGING]) as shown for Figure 12 can be encoded using indefinite-length encoding, which minimizes buffering needed to translate into the binary format. However, chunk boundaries do not need to be retained and any chunk extensions cannot be conveyed using the binary format; see Section 6.¶

Figure 13 shows this message using the known-length coding. Note that the transfer-encoding header field is removed.¶