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.
val empty : t
empty
is the empty collection of header fields.
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"
.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"
.to_list t
is the association list of header fields contained in t
in transmission order.
to_rev_list t
is the association list of header fields contained in t
in reverse transmission order.
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
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
.
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.
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" ]
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.
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.
mem t name
is true
iff t
includes a header field with a name that is equal to name
.
get t name
returns the last header from t
with name name
, or None
if no such header is present.
get t name
returns the last header from t
with name name
, or raises Not_found
if no such header is present.
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.
val to_string : t -> string
val pp_hum : Format.formatter -> t -> unit