package http-cookie

  1. Overview
  2. Docs
package http-cookie
Legend:
Library
Module
Module type
Parameter
Class
Class type

A comprehensive and standards compliant HTTP cookies library for ocaml.

HTTP cookie is serialized as follows:

  • In a Cookie header in a HTTP request
  • In a Set-Cookie header in a HTTP response.

The library supports consuming and creating HTTP cookie in both requests and responses.

The standards implemented by the library is

  1. RFC 6265 - Cookies.
  2. Section 3.3.1 - HTTP Date
  3. Domain Name
  4. Hosts
  5. IPv4/IPv6 Address
type t

A HTTP cookie.

and date_time

normalized date time value in GMT.

and same_site = [
  1. | `None
  2. | `Lax
  3. | `Strict
]

'Same-site' cookie attribute. Same-site

Pretty Printers

val pp : Stdlib.Format.formatter -> t -> unit
val pp_same_site : Stdlib.Format.formatter -> same_site -> unit
val pp_date_time : Stdlib.Format.formatter -> date_time -> unit

pp_date_time fmt date_time pretty prints date_time in RFC 1123 format.

Example:

Sun, 06 Nov 1994 08:49:37 GMT
val pp_rfc1123 : Stdlib.Format.formatter -> date_time -> unit

Alias of pp_date_time.

Create/Decode/Encode

val date_time : year:int -> month: [ `Jan | `Feb | `Mar | `Apr | `May | `Jun | `Jul | `Aug | `Sep | `Oct | `Nov | `Dec ] -> weekday:[ `Sun | `Mon | `Tue | `Wed | `Thu | `Fri | `Sat ] -> day:int -> hour:int -> minutes:int -> seconds:int -> (date_time, string) Stdlib.result

date_time is Ok dt if all of the given parameters are valid for creating date_time value, otherwise it is Error err where err denotes the error.

val create : ?path:string -> ?domain:string -> ?expires:date_time -> ?max_age:int64 -> ?secure:bool -> ?http_only:bool -> ?same_site:same_site -> ?extension:string -> name:string -> string -> (t, string) Stdlib.result

create ~path ~domain ~expires ~max_age ~secure ~http_only ~same_site ~extension ~name value is Ok cookie if all of the given parameters are valid cookie attribute values. Otherwise it is Error error where error is the description of the error.

of_cookie header parses header - a string value which represents HTTP Cookie header value as defined in https://tools.ietf.org/html/rfc6265#section-4.2. It returns a list of Cookies if it is able to successfully parse s, otherwise it returns Error err.

It is an error to include duplicate cookie names.

Examples

This returns two cookies with cookie names SID and lang.

Http_cookie.of_cookie "SID=31d4d96e407aad42; lang=en-US"

to_cookie c serializes c into a string which can be encoded as value for HTTP Cookie header.

Example of a string returned by the function.

SID=31d4d96e407aad42

to_set_cookie c serializes cookie c into a string which can be encoded as value for HTTP Set-Cookie header.

The datetime format for expires attribute is specified in RFC 2616

Example of a string returned by the function,

SID=31d4d96e407aad42; Path=/; Secure; HttpOnly; Expires=Sun, 06 Nov 1994 08:49:37 GMT

of_set_cookie s is Ok cookie if s can be parsed successfully to create t.

s is the HTTP 'Set-Cookie' header value. The syntax for the value is defined as set-cookie-string in RFC 6265, 4.1

Cookie attributes are defined precisely at RFC 6262

val name : t -> string

name t returns a cookie name.

See cookie-name

val value : t -> string

value t returns a cookie value.

See cookie-value

val path : t -> string option

path t returns cookie path attribute.

See cookie-path

val domain : t -> string option

domain t returns cookie domain attribute.

See cookie-domain

val expires : t -> date_time option

expires t returns a coookie expires attribute.

See cookie-expires

val max_age : t -> int64 option

max_age t returns a cookie max_age attribute.

See max-age and max-age-av

val secure : t -> bool

secure t returns a secure attribute.

See cookie-secure

val http_only : t -> bool

http_only t returns a http_only attribute.

See http-only

val same_site : t -> same_site option

same_site t returns a same_site attribute.

See same-site

val extension : t -> string option

extension t returns a cookie extension value.

See cookie-extension

Compare

val compare : t -> t -> int

compare c1 c2 returns 0 if c1 and c2 are equal, a positive integer if c1 is greater than c2 and a negative integer if c1 is less than c2

val compare_date_time : date_time -> date_time -> int

Updates

val update_value : string -> t -> (t, string) Stdlib.result
val update_name : string -> t -> (t, string) Stdlib.result
val update_path : string option -> t -> (t, string) Stdlib.result
val update_domain : string option -> t -> (t, string) Stdlib.result
val update_expires : date_time option -> t -> t
val update_max_age : int64 option -> t -> (t, string) Stdlib.result
val update_secure : bool -> t -> t
val update_http_only : bool -> t -> t
val update_same_site : same_site option -> t -> t
val update_extension : string option -> t -> (t, string) Stdlib.result
val expire : t -> t

expire c expires cookie c with a Max-Age value of -1L. All other cookie attribute values are removed. Cookies with Max-Age value < 0 are removed by HTTP agents such as web browsers.