anil.recoil.org
A batteries included HTTP/1.1 client in OCaml
odoc
+2
-2
lib/http_client.ml
+2
-2
lib/http_client.ml
···
5
5
6
6
(** Low-level HTTP/1.1 client over raw TCP connections for connection pooling
7
7
8
-
This module orchestrates {!Http_write} for request serialization and
9
-
{!Http_read} for response parsing, leveraging Eio's Buf_write and Buf_read
8
+
This module orchestrates [Http_write] for request serialization and
9
+
[Http_read] for response parsing, leveraging Eio's Buf_write and Buf_read
10
10
for efficient I/O.
11
11
12
12
Types are imported from domain-specific modules ({!Response_limits},
+27
-16
lib/requests.mli
+27
-16
lib/requests.mli
···
93
93
- {b Simple API}: Intuitive functions for GET, POST, PUT, DELETE, etc.
94
94
- {b Authentication}: Built-in support for Basic, Bearer, Digest, and OAuth
95
95
- {b Streaming}: Upload and download large files efficiently
96
-
- {b Retries}: Automatic retry with exponential backoff
97
-
- {b Timeouts}: Configurable connection and read timeouts
98
-
- {b Cookie Management}: Automatic cookie handling with persistence
96
+
- {b Retries}: Automatic retry with exponential backoff (see {!Retry})
97
+
- {b Timeouts}: Configurable connection and read timeouts (see {!Timeout})
98
+
- {b Cookie Management}: Automatic cookie handling with persistence (see {!Cookeio} and {!Cookeio_jar})
99
99
- {b TLS/SSL}: Secure connections with certificate verification
100
-
- {b Error Handling}: Comprehensive error types and recovery
100
+
- {b Connection Pooling}: Efficient TCP/TLS connection reuse (see {!Conpool})
101
+
- {b Error Handling}: Comprehensive error types and recovery (see {!module:Error})
102
+
103
+
{2 Related Libraries}
104
+
105
+
This library integrates with several companion libraries:
106
+
107
+
{ul
108
+
{- [Conpool] - TCP/IP connection pooling with retry logic and statistics}
109
+
{- [Cookeio] - HTTP cookie parsing and validation per RFC 6265}
110
+
{- [Cookeio_jar] - Cookie jar storage with XDG persistence}
111
+
{- [Xdge] - XDG Base Directory support for cookie persistence paths}}
101
112
102
113
{2 Error Handling}
103
114
···
107
118
108
119
{b Exception-Based Errors:}
109
120
110
-
All request functions may raise exceptions from the {!module:Error} module:
111
-
- {!exception:Error.Timeout}: Request exceeded timeout limit
112
-
- {!exception:Error.ConnectionError}: Network connection failed
113
-
- {!exception:Error.TooManyRedirects}: Exceeded maximum redirect count
114
-
- {!exception:Error.HTTPError}: HTTP error response received (4xx/5xx status)
115
-
- {!exception:Error.SSLError}: TLS/SSL connection error
116
-
- {!exception:Error.AuthenticationError}: Authentication failed
121
+
All request functions may raise [Eio.Io] exceptions with {!Error.E} payload:
122
+
- [Error.Timeout]: Request exceeded timeout limit
123
+
- [Error.Dns_resolution_failed], [Error.Tcp_connect_failed]: Network connection failed
124
+
- [Error.Too_many_redirects]: Exceeded maximum redirect count
125
+
- [Error.Http_error]: HTTP error response received (4xx/5xx status)
126
+
- [Error.Tls_handshake_failed]: TLS/SSL connection error
127
+
- [Error.Authentication_failed]: Authentication failed
117
128
118
129
{b Note on HTTP Status Codes:}
119
130
···
257
268
All resources are bound to the provided switch and will be cleaned up automatically.
258
269
259
270
@param sw Switch for resource management
260
-
@param http_pool Optional pre-configured HTTP connection pool (creates new if not provided)
261
-
@param https_pool Optional pre-configured HTTPS connection pool (creates new if not provided)
262
-
@param cookie_jar Cookie storage (default: empty in-memory jar)
271
+
@param http_pool Optional pre-configured HTTP {!Conpool.t} connection pool (creates new if not provided)
272
+
@param https_pool Optional pre-configured HTTPS {!Conpool.t} connection pool (creates new if not provided)
273
+
@param cookie_jar {!Cookeio_jar.t} cookie storage (default: empty in-memory jar)
263
274
@param default_headers Headers included in every request
264
275
@param auth Default authentication
265
276
@param timeout Default timeout configuration
···
272
283
@param connection_idle_timeout Max idle time before closing pooled connection (default: 60s)
273
284
@param connection_lifetime Max lifetime of any pooled connection (default: 300s)
274
285
@param retry Retry configuration for failed requests
275
-
@param persist_cookies Whether to persist cookies to disk (default: false)
276
-
@param xdg XDG directory context for cookies (required if persist_cookies=true)
286
+
@param persist_cookies Whether to persist cookies to disk via {!Cookeio_jar} (default: false)
287
+
@param xdg {!Xdge.t} XDG directory context for cookies (required if persist_cookies=true)
277
288
@param auto_decompress Whether to automatically decompress gzip/deflate responses (default: true)
278
289
@param expect_100_continue Whether to use HTTP 100-continue for large uploads (default: true)
279
290
@param expect_100_continue_threshold Body size threshold to trigger 100-continue in bytes (default: 1MB)
+4
-4
lib/response.mli
+4
-4
lib/response.mli
···
225
225
@raise Failure if the response has already been closed. *)
226
226
227
227
val raise_for_status : t -> t
228
-
(** [raise_for_status response] raises {!Error.HTTPError} if the response
229
-
status code indicates an error (>= 400). Returns the response unchanged
230
-
if the status indicates success (< 400).
228
+
(** [raise_for_status response] raises [Eio.Io] with [Error.Http_error] if the
229
+
response status code indicates an error (>= 400). Returns the response
230
+
unchanged if the status indicates success (< 400).
231
231
232
232
This is useful for failing fast on HTTP errors:
233
233
{[
···
236
236
process_success response
237
237
]}
238
238
239
-
@raise Error.HTTPError if status code >= 400. *)
239
+
@raise Eio.Io with [Error.Http_error] if status code >= 400. *)
240
240
241
241
val check_status : t -> (t, Error.error) result
242
242
(** [check_status response] returns [Ok response] if the status code is < 400,