Package io.github.mahmoudimus.http3

Class Http3Headers

java.lang.Object
io.github.mahmoudimus.http3.Http3Headers
public final class Http3Headers extends Object
HTTP semantics of HTTP/3 field sections (RFC 9114 §4.2, §4.3): validating decoded field lists into RequestHeaders and ResponseHeaders. The rules are those of HTTP/2 (RFC 9113 §8.2, §8.3), plus extended CONNECT (RFC 9220).

A request or response that breaks these rules is malformed, which is a stream error of type H3_MESSAGE_ERROR (RFC 9114 §4.1.2); the validators throw exactly that. They check:

  • names: not empty, no upper-case letters, no octets 0x00-0x20 or 0x7f-0xff, and no colon except as the first character of a pseudo-header;
  • values: no NUL, CR or LF, and no leading or trailing space or tab;
  • no connection-specific fields (CONNECTION_SPECIFIC), and te only with the value trailers;
  • pseudo-headers: only the defined ones for the message kind, each at most once, all before the regular fields, and the required ones present; none in trailers;
  • CONNECT: only :method and :authority, unless :protocol makes it an extended CONNECT, which needs :scheme, :path and :authority too;
  • content-length: digits only, and every value the same.

  • Field Details

    • CONNECTION_SPECIFIC

      public static final Set<String> CONNECTION_SPECIFIC
      Fields that are specific to an HTTP/1 connection and must not appear in HTTP/3 (RFC 9114 §4.2).

  • Method Details

    • toRequest

      public static RequestHeaders toRequest(long streamId, List<HeaderField> fields) throws Http3Exception
      Validates a decoded request header section, accepting extended CONNECT (the caller rejects it if it did not send SETTINGS_ENABLE_CONNECT_PROTOCOL; see toRequest(long, List, boolean)).
      Parameters:
      streamId - the stream, for errors
      fields - the decoded section
      Returns:
      the request
      Throws:
      Http3Exception - a stream error H3_MESSAGE_ERROR if it is malformed

    • toRequest

      public static RequestHeaders toRequest(long streamId, List<HeaderField> fields, boolean extendedConnect) throws Http3Exception
      Validates a decoded request header section.
      Parameters:
      streamId - the stream, for errors
      fields - the decoded section
      extendedConnect - whether this endpoint sent SETTINGS_ENABLE_CONNECT_PROTOCOL = 1, which allows :protocol (RFC 9220 §3)
      Returns:
      the request
      Throws:
      Http3Exception - a stream error H3_MESSAGE_ERROR if it is malformed

    • toResponse

      public static ResponseHeaders toResponse(long streamId, List<HeaderField> fields) throws Http3Exception
      Validates a decoded response header section (final or 1xx).
      Parameters:
      streamId - the stream, for errors
      fields - the decoded section
      Returns:
      the response
      Throws:
      Http3Exception - a stream error H3_MESSAGE_ERROR if it is malformed

    • validateTrailers

      public static List<HeaderField> validateTrailers(long streamId, List<HeaderField> fields) throws Http3Exception
      Validates a trailer section: regular fields only.
      Parameters:
      streamId - the stream, for errors
      fields - the decoded section
      Returns:
      the fields
      Throws:
      Http3Exception - a stream error H3_MESSAGE_ERROR if it is malformed

    • checkContentLength

      public static void checkContentLength(long streamId, long declared, long received, boolean endStream) throws Http3Exception
      Checks DATA received against a declared content-length (RFC 9114 §4.1.2). Call it after each DATA frame with the running total of content octets. Skip it where the content is empty whatever the field says: responses to HEAD, and 204 and 304 responses.
      Parameters:
      streamId - the stream, for errors
      declared - the content length, or -1 if none was declared (then nothing is checked)
      received - the content octets received so far
      endStream - whether the stream has ended
      Throws:
      Http3Exception - a stream error H3_MESSAGE_ERROR if the content does not match