- OCaml 100%
nox-cookie #
Warning. This is a work-in-progress experimental fork of ocaml-cookeio. Do not use it in production; use ocaml-cookeio instead.
Parse, validate and store HTTP cookies in OCaml, following RFC 6265.
An HTTP client that keeps a session stores the cookies a server sets, sends
back only those whose domain, path and Secure flag match each request, and
forgets them when they expire. The Set-Cookie headers a server emits must
be ones browsers accept. nox-cookie does both. It parses and writes Cookie and
Set-Cookie headers with every attribute, including SameSite from the RFC
6265bis draft and the Partitioned attribute of CHIPS (Cookies Having
Independent Partitioned State). A browser stores a Partitioned third-party
cookie separately for each top-level site that embeds it, so the cookie
cannot follow a user from one site to another. The parser rejects a Domain
attribute that is a public suffix such as co.uk. The jar applies the
matching and ordering rules of RFC 6265 Section 5.4. A jar can be saved and
loaded in the Mozilla cookie file format.
nox-cookie is a fork of Anil Madhavapeddy's
ocaml-cookeio.
RFC-TODO.md lists where it still departs from RFC 6265: the jar
enforces no storage limit and evicts no cookie.
Packages #
nox-cookie(moduleCookie) parses, validates and writes cookies and theCookieandSet-Cookieheaders.nox-cookie.jar(moduleCookie_jar) stores cookies with domain and path matching, tracks the cookies a server still has to send (the delta), and reads and writes Mozilla cookie files. It uses Eio for the clock and files.
Install #
opam install nox-cookie
If opam cannot find the package, add the overlay repository first:
opam repo add samoht https://tangled.org/gazagnaire.org/opam-overlay.git
opam update
opam install nox-cookie
Usage #
Parsing Headers #
Cookie.of_set_cookie_header takes the request host, the request path and
whether the request used HTTPS. A cookie with no Path attribute takes the
default-path of the request path (RFC 6265 Section 5.1.4):
# let now () = Ptime.epoch
val now : unit -> Ptime.t = <fun>
# let cookie =
Cookie.of_set_cookie_header ~now ~domain:"example.com"
~path:"/docs/index.html" ~is_secure:true
"session=abc123; Secure; HttpOnly; SameSite=Strict"
|> Result.get_ok
val cookie : Cookie.t = <abstr>
# Cookie.path cookie
- : string = "/docs"
# Cookie.set_cookie_header cookie
- : string = "session=abc123; Path=/docs; Secure; HttpOnly; SameSite=Strict"
A Secure cookie received over plain HTTP is refused:
# Cookie.of_set_cookie_header ~now ~domain:"example.com" ~path:"/"
~is_secure:false "session=abc123; Secure"
|> Result.map Cookie.name
- : (string, string) result =
Error "Secure cookie received over an insecure connection"
Cookie.of_request_header parses the Cookie header a server receives:
# Cookie.of_request_header ~now ~domain:"example.com" ~path:"/"
"session=abc123; theme=dark"
|> Result.map (List.map Cookie.name)
- : (string list, string) result = Ok ["session"; "theme"]
Serializing Headers #
let render_request (cookies : Cookie.t list) = Cookie.request_header cookies
let render_response (cookie : Cookie.t) = Cookie.set_cookie_header cookie
Creating Cookies #
let session_cookie ~now =
Cookie.v ~domain:"example.com" ~path:"/" ~name:"session" ~value:"abc123"
~secure:true ~http_only:true ~same_site:`Strict ~creation_time:(now ())
~last_access:(now ()) ()
Cookie Jar #
let api_cookies ~clock (cookie : Cookie.t) =
let jar = Cookie_jar.v () in
Cookie_jar.add_cookie jar cookie;
let matching =
Cookie_jar.cookies jar ~clock ~domain:"example.com" ~path:"/api"
~is_secure:true
in
Cookie.request_header matching
Delta Tracking #
let log_pending (jar : Cookie_jar.t) =
Cookie_jar.delta jar
|> List.iter (fun c -> Fmt.pr "%s@." (Cookie.set_cookie_header c))
Persistence #
A jar is saved in, and loaded from, the Mozilla cookie file format:
let save_jar ~path (jar : Cookie_jar.t) = Cookie_jar.save path jar
let load_jar ~clock ~path = Cookie_jar.load ~clock path
Validation #
Cookie.Validate checks names, values and attributes against the syntax
RFC 6265 Section 4.1 requires of a server:
# Cookie.Validate.cookie_name "session";;
- : (string, string) result = Ok "session"
# Cookie.Validate.cookie_value "abc;123";;
- : (string, string) result =
Error
"Cookie value \"abc;123\" contains invalid characters: semicolon (0x3B). RFC 6265 cookie values may only contain printable ASCII excluding double-quote, comma, semicolon, and backslash"
# Cookie.Validate.domain_value "example.com";;
- : (string, string) result = Ok "example.com"
License #
ISC. See LICENSE.md.