anil.recoil.org
A batteries included HTTP/1.1 client in OCaml
odoc
+2
-2
lib/auth.mli
+2
-2
lib/auth.mli
···
13
13
14
14
{2 Security}
15
15
16
-
Per {{:https://datatracker.ietf.org/doc/html/rfc7617#section-4}RFC 7617 Section 4}} and
17
-
{{:https://datatracker.ietf.org/doc/html/rfc6750#section-5.1}RFC 6750 Section 5.1}},
16
+
Per {{:https://datatracker.ietf.org/doc/html/rfc7617#section-4}RFC 7617 Section 4} and
17
+
{{:https://datatracker.ietf.org/doc/html/rfc6750#section-5.1}RFC 6750 Section 5.1},
18
18
Basic, Bearer, and Digest authentication transmit credentials that MUST be
19
19
protected by TLS. The library enforces HTTPS by default for these schemes. *)
20
20
+2
-2
lib/headers.mli
+2
-2
lib/headers.mli
···
6
6
(** HTTP header field handling per {{:https://datatracker.ietf.org/doc/html/rfc9110#section-5}RFC 9110 Section 5}
7
7
8
8
This module provides an efficient implementation of HTTP headers with
9
-
case-insensitive field names per {{:https://datatracker.ietf.org/doc/html/rfc9110#section-5.1}RFC 9110 Section 5.1}}.
9
+
case-insensitive field names per {{:https://datatracker.ietf.org/doc/html/rfc9110#section-5.1}RFC 9110 Section 5.1}.
10
10
Headers can have multiple values for the same field name (e.g., Set-Cookie).
11
11
12
12
{2 Security}
13
13
14
14
Header names and values are validated to prevent HTTP header injection
15
15
attacks. CR and LF characters are rejected per
16
-
{{:https://datatracker.ietf.org/doc/html/rfc9110#section-5.5}RFC 9110 Section 5.5}}.
16
+
{{:https://datatracker.ietf.org/doc/html/rfc9110#section-5.5}RFC 9110 Section 5.5}.
17
17
18
18
{2 Examples}
19
19
+1
-1
lib/method.mli
+1
-1
lib/method.mli
···
11
11
{2 Safe Methods}
12
12
13
13
Methods are considered "safe" if their semantics are read-only (GET, HEAD,
14
-
OPTIONS, TRACE). Per {{:https://datatracker.ietf.org/doc/html/rfc9110#section-9.2.1}RFC 9110 Section 9.2.1}}.
14
+
OPTIONS, TRACE). Per {{:https://datatracker.ietf.org/doc/html/rfc9110#section-9.2.1}RFC 9110 Section 9.2.1}.
15
15
16
16
{2 Idempotent Methods}
17
17
+2
-2
lib/one.mli
+2
-2
lib/one.mli
···
10
10
Each request opens a new TCP connection (with TLS for https://) that is
11
11
closed when the Eio switch closes.
12
12
13
-
Implements {{:https://datatracker.ietf.org/doc/html/rfc9112}RFC 9112}} (HTTP/1.1)
14
-
with {{:https://datatracker.ietf.org/doc/html/rfc9110}RFC 9110}} semantics.
13
+
Implements {{:https://datatracker.ietf.org/doc/html/rfc9112}RFC 9112} (HTTP/1.1)
14
+
with {{:https://datatracker.ietf.org/doc/html/rfc9110}RFC 9110} semantics.
15
15
16
16
For stateful requests with automatic cookie handling, connection pooling,
17
17
and persistent configuration, use the main {!Requests} module instead.
+4
-4
lib/requests.mli
+4
-4
lib/requests.mli
···
107
107
108
108
{b Exception-Based Errors:}
109
109
110
-
All request functions may raise exceptions from the {!Error} module:
110
+
All request functions may raise exceptions from the {!module:Error} module:
111
111
- {!exception:Error.Timeout}: Request exceeded timeout limit
112
112
- {!exception:Error.ConnectionError}: Network connection failed
113
113
- {!exception:Error.TooManyRedirects}: Exceeded maximum redirect count
···
161
161
log_error "Unexpected error: %s" (Printexc.to_string exn)
162
162
]}
163
163
164
-
The {!Error} module also provides a Result-based API for functional error
164
+
The {!module:Error} module also provides a Result-based API for functional error
165
165
handling, though the primary API uses exceptions for better integration
166
166
with Eio's structured concurrency.
167
167
···
284
284
HTTP requests use absolute-URI form (RFC 9112 Section 3.2.2).
285
285
HTTPS requests use CONNECT tunneling (RFC 9110 Section 9.3.6).
286
286
@param allow_insecure_auth Allow Basic/Bearer/Digest authentication over plaintext HTTP (default: false).
287
-
Per {{:https://datatracker.ietf.org/doc/html/rfc7617#section-4}RFC 7617 Section 4}} and
288
-
{{:https://datatracker.ietf.org/doc/html/rfc6750#section-5.1}RFC 6750 Section 5.1}},
287
+
Per {{:https://datatracker.ietf.org/doc/html/rfc7617#section-4}RFC 7617 Section 4} and
288
+
{{:https://datatracker.ietf.org/doc/html/rfc6750#section-5.1}RFC 6750 Section 5.1},
289
289
these auth schemes transmit credentials that SHOULD be protected by TLS.
290
290
{b Only set to [true] for local development or testing environments.}
291
291
Example for local dev server:
+1
-1
lib/response.mli
+1
-1
lib/response.mli
···
9
9
status codes, headers, and response bodies. Responses support streaming
10
10
to efficiently handle large payloads.
11
11
12
-
Caching semantics follow {{:https://datatracker.ietf.org/doc/html/rfc9111}RFC 9111}} (HTTP Caching).
12
+
Caching semantics follow {{:https://datatracker.ietf.org/doc/html/rfc9111}RFC 9111} (HTTP Caching).
13
13
14
14
{2 Examples}
15
15
+2
-2
lib/retry.mli
+2
-2
lib/retry.mli
···
7
7
8
8
This module provides configurable retry logic for HTTP requests,
9
9
including exponential backoff, custom retry predicates, and
10
-
Retry-After header support per {{:https://datatracker.ietf.org/doc/html/rfc9110#section-10.2.3}RFC 9110 Section 10.2.3}}.
10
+
Retry-After header support per {{:https://datatracker.ietf.org/doc/html/rfc9110#section-10.2.3}RFC 9110 Section 10.2.3}.
11
11
12
12
{2 Custom Retry Predicates}
13
13
···
106
106
107
107
(** Parse Retry-After header value (seconds or HTTP date).
108
108
109
-
Per {{:https://datatracker.ietf.org/doc/html/rfc9110#section-10.2.3}RFC 9110 Section 10.2.3}},
109
+
Per {{:https://datatracker.ietf.org/doc/html/rfc9110#section-10.2.3}RFC 9110 Section 10.2.3},
110
110
Retry-After can be either:
111
111
- A non-negative integer (delay in seconds)
112
112
- An HTTP-date (absolute time to retry after)