diff --git a/CHANGES.md b/CHANGES.md index adbd144..5ba8586 100644 --- a/CHANGES.md +++ b/CHANGES.md @@ -1,3 +1,8 @@ +## v4.3.1 2025-06-15 +- remove check for duplicate cookies, navigator may send duplicate cookies and break the server +- allow max-age of 0L and -1L as it is a standard way to expire a cookie +- expiring a cookie should not remove domain and path + ## v4.3 2023-01-17 - add `expire` functionality (#8 @craff) - make http-cookie more lean by removing `fmt` dependency. diff --git a/docs/http-cookie/Http_cookie/index.html b/docs/http-cookie/Http_cookie/index.html index 56b662e..d32d977 100644 --- a/docs/http-cookie/Http_cookie/index.html +++ b/docs/http-cookie/Http_cookie/index.html @@ -1,5 +1,5 @@ -Http_cookie (http-cookie.Http_cookie)

Module Http_cookie

A comprehensive and standards compliant HTTP cookies library for ocaml.

HTTP cookie is serialized as follows:

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 : +Http_cookie (http-cookie.Http_cookie)

Module Http_cookie

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 @@ -30,5 +30,4 @@ ?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.

+ (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.

diff --git a/docs/http-cookie/index.html b/docs/http-cookie/index.html index 4d83c9a..cf3aa03 100644 --- a/docs/http-cookie/index.html +++ b/docs/http-cookie/index.html @@ -1,2 +1,2 @@ -index (http-cookie.index)

http-cookie index

The entry point of this library is the module: Http_cookie.

+index (http-cookie.index)

http-cookie index

The entry point of this library is the module: Http_cookie.

diff --git a/docs/index.html b/docs/index.html index 461966a..3c845c8 100644 --- a/docs/index.html +++ b/docs/index.html @@ -11,7 +11,7 @@

OCaml package documentation

    -
  1. http-cookie 4.3.0
    2. +
  2. http-cookie 4.3.1
diff --git a/dune-project b/dune-project index c52f352..11b7ce5 100644 --- a/dune-project +++ b/dune-project @@ -2,7 +2,7 @@ (name http-cookie) -(version 4.3.0) +(version 4.3.1) (using mdx 0.3) diff --git a/http-cookie.opam b/http-cookie.opam index e060c63..e75ed95 100644 --- a/http-cookie.opam +++ b/http-cookie.opam @@ -1,6 +1,6 @@ # This file is generated by dune, edit dune-project instead opam-version: "2.0" -version: "4.3.0" +version: "4.3.1" synopsis: "HTTP cookie library for OCaml" description: """ A comprehensive and strict standards compliant HTTP cookies library for ocaml. diff --git a/lib/http_cookie.mli b/lib/http_cookie.mli index 5468b96..d3c784c 100644 --- a/lib/http_cookie.mli +++ b/lib/http_cookie.mli @@ -137,7 +137,7 @@ val to_set_cookie : t -> string Example of a string returned by the function, {v -SID=31d4d96e407aad42; Path=/; Secure; HttpOnly; Expires=Sun, 06 Nov 1994 08:49:37 GMT + SID=31d4d96e407aad42; Path=/; Secure; HttpOnly; Expires=Sun, 06 Nov 1994 08:49:37 GMT v} *) val of_set_cookie : string -> (t, string) result