Module H2.Headers

Header Fields

Each header field consists of a lowercase field name and a field value. Per the HTTP/2 specification, header field names must be converted to lowercase prior to their encoding in HTTP/2 (see RFC7540§8.1.2 for more details). h2 does not convert field names to lowercase; it is therefore the responsibility of the caller of the functions contained in this module to use lowercase names for header fields.

The order in which header fields with differing field names are received is not significant, except for pseudo-header fields, which must appear in header blocks before regular fields (see RFC7540§8.1.2.1 for more details).

A sender MUST NOT generate multiple header fields with the same field name in a message unless either the entire field value for that header field is defined as a comma-separated list or the header field is a well-known exception, e.g., Set-Cookie.

A recipient MAY combine multiple header fields with the same field name into one "field-name: field-value" pair, without changing the semantics of the message, by appending each subsequent field value to the combined field value in order, separated by a comma. The order in which header fields with the same field name are received is therefore significant to the interpretation of the combined field value; a proxy MUST NOT change the order of these field values when forwarding a message.

Note. Unless otherwise specified, all operations preserve header field order and all reference to equality on names is assumed to be case-insensitive.

See RFC7230§3.2 for more details.

type t

The type of a group of header fields.

type name = string

The type of a lowercase header name.

type value = string

The type of a header value.

Constructor

val empty : t

empty is the empty collection of header fields.

val of_list : (name * value) list -> t

of_list assoc is a collection of header fields defined by the association list assoc. of_list assumes the order of header fields in assoc is the intended transmission order. The following equations should hold:

  • to_list (of_list lst) = lst
  • get (of_list [("k", "v1"); ("k", "v2")]) "k" = Some "v2".
val of_rev_list : (name * value) list -> t

of_list assoc is a collection of header fields defined by the association list assoc. of_list assumes the order of header fields in assoc is the reverse of the intended trasmission order. The following equations should hold:

  • to_list (of_rev_list lst) = List.rev lst
  • get (of_rev_list [("k", "v1"); ("k", "v2")]) "k" = Some "v1".
val to_list : t -> (name * value) list

to_list t is the association list of header fields contained in t in transmission order.

val to_rev_list : t -> (name * value) list

to_rev_list t is the association list of header fields contained in t in reverse transmission order.

val add : t -> ?⁠sensitive:bool -> name -> value -> t

add t ?sensitive name value is a collection of header fields that is the same as t except with (name, value) added at the end of the trasmission order. Additionally, sensitive specifies whether this header field should not be compressed by HPACK and instead encoded as a never-indexed literal (see RFC7541§7.1.3 for more details).

The following equations should hold:

  • get (add t name value) name = Some value
val add_unless_exists : t -> ?⁠sensitive:bool -> name -> value -> t

add_unless_exists t ?sensitive name value is a collection of header fields that is the same as t if t already inclues name, and otherwise is equivalent to add t ?sensitive name value.

val add_list : t -> (name * value) list -> t

add_list t assoc is a collection of header fields that is the same as t except with all the header fields in assoc added to the end of the transmission order, in reverse order.

val add_multi : t -> (name * value list) list -> t

add_multi t assoc is the same as

add_list
  t
  (List.concat_map assoc ~f:(fun (name, values) ->
       List.map values ~f:(fun value -> name, value)))

but is implemented more efficiently. For example,

add_multi t [ "name1", [ "x", "y" ]; "name2", [ "p", "q" ] ]
= add_list [ "name1", "x"; "name1", "y"; "name2", "p"; "name2", "q" ]
val remove : t -> name -> t

remove t name is a collection of header fields that contains all the header fields of t except those that have a header-field name that are equal to name. If t contains multiple header fields whose name is name, they will all be removed.

val replace : t -> ?⁠sensitive:bool -> name -> value -> t

replace t ?sensitive name value is a collection of header fields that is the same as t except with all header fields with a name equal to name removed and replaced with a single header field whose name is name and whose value is value. This new header field will appear in the transmission order where the first occurrence of a header field with a name matching name was found.

If no header field with a name equal to name is present in t, then the result is simply t, unchanged.

Destructors

val mem : t -> name -> bool

mem t name is true iff t includes a header field with a name that is equal to name.

val get : t -> name -> value option

get t name returns the last header from t with name name, or None if no such header is present.

val get_exn : t -> name -> value

get t name returns the last header from t with name name, or raises if no such header is present.

val get_multi : t -> name -> value list

get_multi t name is the list of header values in t whose names are equal to name. The returned list is in transmission order.

Iteration

val iter : f:(name -> value -> unit) -> t -> unit
val fold : f:(name -> value -> 'a -> 'a) -> init:'a -> t -> 'a

Utilities

val to_string : t -> string
val pp_hum : Stdlib.Format.formatter -> t -> unit