OCaml HTTP cookie handling library with support for Eio-based storage jars
anil.recoil.org
1# Cookeio - HTTP Cookie Management for OCaml
2
3Cookeio is an OCaml library for managing HTTP cookies.
4
5## Overview
6
7HTTP cookies are a mechanism for maintaining client-side state in web
8applications. Originally specified to allow "server side connections to store
9and retrieve information on the client side," cookies enable persistent storage
10of user preferences, session data, shopping cart contents, and authentication
11tokens.
12
13This library provides a complete cookie jar implementation following
14established standards while integrating with OCaml's for efficient asynchronous
15operations.
16
17## Cookie Attributes
18
19The library supports all standard HTTP cookie attributes:
20
21- **Domain**: Controls which domains can access the cookie using tail matching
22- **Path**: Defines URL subsets where the cookie is valid
23- **Secure**: Restricts transmission to HTTPS connections only
24- **HttpOnly**: Prevents JavaScript access to the cookie
25- **Expires**: Sets cookie lifetime (session cookies when omitted)
26- **SameSite**: Controls cross-site request behavior (`Strict`, `Lax`, or `None`)
27
28## Usage
29
30```ocaml
31(* Create a new cookie jar *)
32let jar = Cookeio.create () in
33
34(* Parse a Set-Cookie header *)
35let cookie = Cookeio.parse_set_cookie
36 ~domain:"example.com"
37 ~path:"/"
38 "session=abc123; Secure; HttpOnly; SameSite=Strict" in
39
40(* Add cookie to jar *)
41Option.iter (Cookeio.add_cookie jar) cookie;
42
43(* Get cookies for a request *)
44let cookies = Cookeio.get_cookies jar
45 ~domain:"example.com"
46 ~path:"/api"
47 ~is_secure:true in
48
49(* Generate Cookie header *)
50let header = Cookeio.make_cookie_header cookies
51```
52
53## Storage and Persistence
54
55Cookies can be persisted to disk in Mozilla format for compatibility with other
56tools:
57
58```ocaml
59(* Save cookies to file *)
60Cookeio.save (Eio.Path.of_string "cookies.txt") jar;
61
62(* Load cookies from file *)
63let jar = Cookeio.load (Eio.Path.of_string "cookies.txt")
64```