My agentic slop goes here. Not intended for anyone else!
anil.recoil.org
1(** Cookie management library for OCaml
2
3 HTTP cookies are a mechanism that allows "server side
4 connections to store and retrieve information on the client side."
5 Originally designed to enable persistent client-side state for web
6 applications, cookies are essential for storing user preferences, session
7 data, shopping cart contents, and authentication tokens.
8
9 This library provides a complete cookie jar implementation following
10 established web standards while integrating Eio for efficient asynchronous operations.
11
12 {2 Cookie Format and Structure}
13
14 Cookies are set via the Set-Cookie HTTP response header with the basic
15 format: [NAME=VALUE] with optional attributes including:
16 - [expires]: Optional cookie lifetime specification
17 - [domain]: Specifying valid domains using tail matching
18 - [path]: Defining URL subset for cookie validity
19 - [secure]: Transmission over secure channels only
20 - [httponly]: Not accessible to JavaScript
21 - [samesite]: Cross-site request behavior control
22
23 {2 Domain and Path Matching}
24
25 The library implements standard domain and path matching rules:
26 - Domain matching uses "tail matching" (e.g., "acme.com" matches
27 "anvil.acme.com")
28 - Path matching allows subset URL specification for fine-grained control
29 - More specific path mappings are sent first in Cookie headers
30
31 *)
32
33type same_site = [ `Strict | `Lax | `None ]
34(** Cookie same-site policy for controlling cross-site request behavior.
35
36 - [`Strict]: Cookie only sent for same-site requests, providing maximum
37 protection
38 - [`Lax]: Cookie sent for same-site requests and top-level navigation
39 (default for modern browsers)
40 - [`None]: Cookie sent for all cross-site requests (requires [secure] flag)
41*)
42
43type t
44(** HTTP Cookie representation with all standard attributes.
45
46 A cookie represents a name-value pair with associated metadata that controls
47 its scope, security, and lifetime. Cookies with the same [name], [domain],
48 and [path] will overwrite each other when added to a cookie jar. *)
49
50type jar
51(** Cookie jar for storing and managing cookies.
52
53 A cookie jar maintains a collection of cookies with automatic cleanup of
54 expired entries and enforcement of storage limits. It implements the
55 standard browser behavior for cookie storage, including:
56 - Automatic removal of expired cookies
57 - LRU eviction when storage limits are exceeded
58 - Domain and path-based cookie retrieval
59 - Mozilla format persistence for cross-tool compatibility *)
60
61(** {1 Cookie Accessors} *)
62
63val domain : t -> string
64(** Get the domain of a cookie *)
65
66val path : t -> string
67(** Get the path of a cookie *)
68
69val name : t -> string
70(** Get the name of a cookie *)
71
72val value : t -> string
73(** Get the value of a cookie *)
74
75val secure : t -> bool
76(** Check if cookie is secure only *)
77
78val http_only : t -> bool
79(** Check if cookie is HTTP only *)
80
81val expires : t -> Ptime.t option
82(** Get the expiry time of a cookie *)
83
84val same_site : t -> same_site option
85(** Get the same-site policy of a cookie *)
86
87val creation_time : t -> Ptime.t
88(** Get the creation time of a cookie *)
89
90val last_access : t -> Ptime.t
91(** Get the last access time of a cookie *)
92
93val make : domain:string -> path:string -> name:string -> value:string ->
94 ?secure:bool -> ?http_only:bool -> ?expires:Ptime.t ->
95 ?same_site:same_site -> creation_time:Ptime.t -> last_access:Ptime.t ->
96 unit -> t
97(** Create a new cookie with the given attributes *)
98
99(** {1 Cookie Jar Creation and Loading} *)
100
101val create : unit -> jar
102(** Create an empty cookie jar *)
103
104val load : Eio.Fs.dir_ty Eio.Path.t -> jar
105(** Load cookies from Mozilla format file *)
106
107val save : Eio.Fs.dir_ty Eio.Path.t -> jar -> unit
108(** Save cookies to Mozilla format file *)
109
110(** {1 Cookie Jar Management} *)
111
112val add_cookie : jar -> t -> unit
113(** Add a cookie to the jar *)
114
115val get_cookies :
116 jar -> domain:string -> path:string -> is_secure:bool -> t list
117(** Get cookies applicable for a URL *)
118
119val clear : jar -> unit
120(** Clear all cookies *)
121
122val clear_expired : jar -> clock:_ Eio.Time.clock -> unit
123(** Clear expired cookies *)
124
125val clear_session_cookies : jar -> unit
126(** Clear session cookies (those without expiry) *)
127
128val count : jar -> int
129(** Get the number of cookies in the jar *)
130
131val get_all_cookies : jar -> t list
132(** Get all cookies in the jar *)
133
134val is_empty : jar -> bool
135(** Check if the jar is empty *)
136
137(** {1 Cookie Creation and Parsing} *)
138
139val parse_set_cookie : domain:string -> path:string -> string -> t option
140(** Parse Set-Cookie header value into a cookie.
141
142 Parses a Set-Cookie header value following RFC specifications:
143 - Basic format: [NAME=VALUE; attribute1; attribute2=value2]
144 - Supports all standard attributes: [expires], [domain], [path], [secure],
145 [httponly], [samesite]
146 - Returns [None] if parsing fails or cookie is invalid
147 - The [domain] and [path] parameters provide the request context for default
148 values
149
150 Example:
151 [parse_set_cookie ~domain:"example.com" ~path:"/" "session=abc123; Secure;
152 HttpOnly"] *)
153
154val make_cookie_header : t list -> string
155(** Create cookie header value from cookies.
156
157 Formats a list of cookies into a Cookie header value suitable for HTTP
158 requests.
159 - Format: [name1=value1; name2=value2; name3=value3]
160 - Only includes cookie names and values, not attributes
161 - Cookies should already be filtered for the target domain/path
162 - More specific path mappings should be ordered first in the input list
163
164 Example: [make_cookie_header cookies] might return
165 ["session=abc123; theme=dark"] *)
166
167(** {1 Pretty Printing} *)
168
169val pp : Format.formatter -> t -> unit
170(** Pretty print a cookie *)
171
172val pp_jar : Format.formatter -> jar -> unit
173(** Pretty print a cookie jar *)
174
175(** {1 Mozilla Format} *)
176
177val to_mozilla_format : jar -> string
178(** Write cookies in Mozilla format *)
179
180val from_mozilla_format : string -> jar
181(** Parse Mozilla format cookies *)