Headers (webs.Webs.Http.Headers)

Header names

module Name : sig ... end

Header names.

Headers

type t

The type for HTTP headers. Maps header names to string values such that for:

Single valued headers, the string is the value.
Multi-valued headers, the string is the values separated by commas ','. Use Headers.values_of_string on the string.
The set_cookie header, must be treated specially since it can be repeated but does not follow the syntax of multi-valued headers. The values are stored in the string separated by '\x00' values. Use Headers.append_set_cookie and Headers.values_of_set_cookie_value to handle the field. Encoders must write the cookies in separate set_cookie headers.

val empty : t

empty has no header definition.

val define : Name.t -> string -> t -> t

define n v headers is headers with n defined to v.

val define_if_some : Name.t -> string option -> t -> t

define_if_some n o headers is headers with n defined to v if o is Some v and headers otherwise.

val define_if_undefined : Name.t -> string -> t -> t

define_if_undefined n v headers is headers with n defined to v if n is not defined in headers.

val undefine : Name.t -> t -> t

undefine n headers is headers with n undefined.

val append_value : Name.t -> string -> t -> t

append_value n v headers appends v to the multi-valued header n in headers.

val append_set_cookie : string -> t -> t

append_set_cookie c headers adds a set_cookie header with value c. This appends to set_cookie, see t.

val override : t -> by:t -> t

override headers ~by are the headers of both headers and by with those of by taking over.

Lookups

val find : ?lowervalue:bool -> Name.t -> t -> string option

find n headers is the value of n in headers (if any). If lowervalue is true (defaults to false) the US-ASCII uppercase letter are mapped on lowercase.

If n is a multi-valued header use values_of_string on the result. If n is set_cookie you must use values_of_set_cookie_value.

val find_or_error : 
  ?lowervalue:bool ->
  Name.t ->
  t ->
  (string, string) Stdlib.result

find_or_error is like find. Except if the header is absent it returns an error message of the form "%s: No such header".

val get : ?lowervalue:bool -> Name.t -> t -> string

get n headers is like find but raises Invalid_argument if n is not defined in headers.

val fold : (Name.t -> string -> 'a -> 'a) -> t -> 'a -> 'a

fold f headers acc folds f over the bindings of headers starting with acc.

Header specific

TODO Try to get rid of this.

val request_body_length : 
  t ->
  ([ `Length of int | `Chunked ], string) Stdlib.result

request_body_length headers determines the message body length of a request (the rules for responses is a bit different) as per HTTP/1.1 specification, by looking at the content_type and transfer_encoding in headers.

val decode_host : Scheme.t -> t -> (string * int, string) Stdlib.result

decode_host scheme headers decodes the host header into a hostname and a port number. If no port number is found in the header one is derived from scheme with Scheme.tcp_port. Errors if the header is missing or on decoding errors.

val for_connector : t -> Body.t -> t

for_connector headers body are the headers of headers prepared for output by a connector that will write a request or response with body body. It performs the logic described in the service responses and client requests conventions.

Header values

val values_of_set_cookie_value : string -> string list

values_of_set_cookie_value v decodes v as stored in by append_set_cookie in the t type to a list of cookies.

val values_of_string : ?sep:char -> string -> string list

values_of_string s splits the string s at ',' (or sep if specified) characters and trims the resulting strings from optional whitespace, and lowercases the result if lowercase is true.

Note that by definition the result is never the empty list, the function returns [""] on "".

val values_to_string : ?sep:char -> string list -> string

values_to_string vs is String.concat "," vs but raise Invalid_argument if vs is []. TODO why ?

val value_is_token : string -> bool

value_is_token s is true iff s in an HTTP a token.

val value_trim_ows : string -> string

value_trim_ows trims starting and ending optional whitespace (OWS).

Converting

val header_of_string : string -> (Name.t * string, string) Stdlib.result

header_of_string s parses a header from string s assumed to be in the form name: value.

Predicates and comparisons

val is_empty : t -> bool

is_empty headers is true iff headers is has no definition.

val mem : Name.t -> t -> bool

mem n headers is true iff n is defined in headers.

val equal : t -> t -> bool

equal tests sets of headers for equality. Header values are tested using binary equality, for multi-valued headers and append_set_cookie order matters.

val compare : t -> t -> int

compare is a total order on headers compatible with equal.