gazagnaire.org
forked from
anil.recoil.org/ocaml-requests
A batteries included HTTP/1.1 client in OCaml
1(*---------------------------------------------------------------------------
2 Copyright (c) 2025 Anil Madhavapeddy <anil@recoil.org>. All rights reserved.
3 SPDX-License-Identifier: ISC
4 ---------------------------------------------------------------------------*)
5
6(** HTTP 100-Continue configuration
7
8 Configuration for the HTTP 100-Continue protocol, which allows clients to
9 check if the server will accept a request before sending a large body. Per
10 RFC 9110 Section 10.1.1 (Expect) and Section 15.2.1 (100 Continue).
11
12 {2 Usage}
13
14 The simplest way to configure 100-continue is with the polymorphic variant:
15 {[
16 (* Use 100-continue for bodies >= 1MB (default) *)
17 let session =
18 Requests.v ~sw ~expect_100_continue:(`Threshold 1_048_576L) env
19
20 (* Always use 100-continue *)
21 let session = Requests.v ~sw ~expect_100_continue:`Always env
22
23 (* Disable 100-continue *)
24 let session = Requests.v ~sw ~expect_100_continue:`Disabled env
25 ]} *)
26
27(** {1 Configuration Types} *)
28
29type config =
30 [ `Disabled (** Never use 100-continue *)
31 | `Always (** Always use 100-continue regardless of body size *)
32 | `Threshold of int64 (** Use 100-continue for bodies >= threshold bytes *)
33 ]
34(** User-facing configuration as a polymorphic variant.
35
36 - [`Disabled]: Never send Expect: 100-continue header
37 - [`Always]: Always send Expect: 100-continue for requests with bodies
38 - [`Threshold n]: Send Expect: 100-continue for bodies >= n bytes *)
39
40type t
41(** Internal configuration type with timeout. *)
42
43(** {1 Default Values} *)
44
45val default_threshold : int64
46(** Default threshold: 1MB (1_048_576 bytes). *)
47
48val default : t
49(** Default configuration: [`Threshold 1_048_576L] with 1.0s timeout. *)
50
51val disabled : t
52(** Configuration with 100-Continue disabled. *)
53
54(** {1 Construction} *)
55
56val of_config : ?timeout:float -> config -> t
57(** [of_config ?timeout config] creates internal configuration from user-facing
58 config. Timeout defaults to 1.0s. *)
59
60val v : ?enabled:bool -> ?threshold:int64 -> ?timeout:float -> unit -> t
61(** [v ?enabled ?threshold ?timeout ()] creates custom 100-Continue
62 configuration. All parameters are optional and default to the values in
63 {!default}. *)
64
65(** {1 Accessors} *)
66
67val enabled : t -> bool
68(** Whether 100-continue is enabled. *)
69
70val threshold : t -> int64
71(** Body size threshold in bytes to trigger 100-continue. *)
72
73val timeout : t -> float
74(** Timeout in seconds to wait for 100 response. *)
75
76val should_use : t -> int64 -> bool
77(** [should_use t body_size] returns [true] if 100-continue should be used for a
78 request with the given [body_size]. *)
79
80(** {1 Pretty Printing} *)
81
82val pp : Format.formatter -> t -> unit
83(** Pretty-printer for 100-Continue configuration. *)
84
85val to_string : t -> string
86(** Convert configuration to a human-readable string. *)
87
88val pp_config : Format.formatter -> config -> unit
89(** Pretty-printer for the user-facing config variant. *)