My agentic slop goes here. Not intended for anyone else!
anil.recoil.org
1(** One-shot HTTP client for stateless requests
2
3 The One module provides a stateless HTTP client for single requests without
4 session state like cookies, connection pooling, or persistent configuration.
5 Each request opens a new connection that is closed after use.
6
7 For stateful requests with automatic cookie handling, connection pooling,
8 and persistent configuration, use the main {!Requests} module instead.
9
10 {2 Examples}
11
12 {[
13 open Eio_main
14
15 let () = run @@ fun env ->
16 Switch.run @@ fun sw ->
17
18 (* Simple GET request *)
19 let response = One.get ~sw
20 ~clock:env#clock ~net:env#net
21 "https://example.com" in
22 Printf.printf "Status: %d\n" (Response.status_code response);
23 Response.close response;
24
25 (* POST with JSON body *)
26 let response = One.post ~sw
27 ~clock:env#clock ~net:env#net
28 ~body:(Body.json {|{"key": "value"}|})
29 ~headers:(Headers.empty |> Headers.content_type Mime.json)
30 "https://api.example.com/data" in
31 Response.close response;
32
33 (* Download file with streaming *)
34 One.download ~sw
35 ~clock:env#clock ~net:env#net
36 "https://example.com/large-file.zip"
37 ~sink:(Eio.Path.(fs / "download.zip" |> sink))
38 ]}
39*)
40
41(** Log source for one-shot request operations *)
42val src : Logs.Src.t
43
44(** {1 HTTP Request Methods}
45
46 All functions are stateless - they open a new TCP connection for each request
47 and close it when the switch closes. No connection pooling or reuse. *)
48
49val request :
50 sw:Eio.Switch.t ->
51 clock:_ Eio.Time.clock ->
52 net:_ Eio.Net.t ->
53 ?headers:Headers.t ->
54 ?body:Body.t ->
55 ?auth:Auth.t ->
56 ?timeout:Timeout.t ->
57 ?follow_redirects:bool ->
58 ?max_redirects:int ->
59 ?verify_tls:bool ->
60 ?tls_config:Tls.Config.client ->
61 method_:Method.t ->
62 string ->
63 Response.t
64(** [request ~sw ~clock ~net ?headers ?body ?auth ?timeout ?follow_redirects
65 ?max_redirects ?verify_tls ?tls_config ~method_ url] makes a single HTTP
66 request without connection pooling.
67
68 Each call opens a new TCP connection (with TLS if https://), makes the
69 request, and closes the connection when the switch closes.
70
71 @param sw Switch for resource management (response/connection bound to this)
72 @param clock Clock for timeouts
73 @param net Network interface for TCP connections
74 @param headers Request headers (default: empty)
75 @param body Request body (default: none)
76 @param auth Authentication to apply (default: none)
77 @param timeout Request timeout (default: 30s connect, 60s read)
78 @param follow_redirects Whether to follow HTTP redirects (default: true)
79 @param max_redirects Maximum redirects to follow (default: 10)
80 @param verify_tls Whether to verify TLS certificates (default: true)
81 @param tls_config Custom TLS configuration (default: system CA certs)
82 @param method_ HTTP method (GET, POST, etc.)
83 @param url URL to request
84*)
85
86val get :
87 sw:Eio.Switch.t ->
88 clock:_ Eio.Time.clock ->
89 net:_ Eio.Net.t ->
90 ?headers:Headers.t ->
91 ?auth:Auth.t ->
92 ?timeout:Timeout.t ->
93 ?follow_redirects:bool ->
94 ?max_redirects:int ->
95 ?verify_tls:bool ->
96 ?tls_config:Tls.Config.client ->
97 string ->
98 Response.t
99(** GET request. See {!request} for parameter details. *)
100
101val post :
102 sw:Eio.Switch.t ->
103 clock:_ Eio.Time.clock ->
104 net:_ Eio.Net.t ->
105 ?headers:Headers.t ->
106 ?body:Body.t ->
107 ?auth:Auth.t ->
108 ?timeout:Timeout.t ->
109 ?verify_tls:bool ->
110 ?tls_config:Tls.Config.client ->
111 string ->
112 Response.t
113(** POST request. See {!request} for parameter details. *)
114
115val put :
116 sw:Eio.Switch.t ->
117 clock:_ Eio.Time.clock ->
118 net:_ Eio.Net.t ->
119 ?headers:Headers.t ->
120 ?body:Body.t ->
121 ?auth:Auth.t ->
122 ?timeout:Timeout.t ->
123 ?verify_tls:bool ->
124 ?tls_config:Tls.Config.client ->
125 string ->
126 Response.t
127(** PUT request. See {!request} for parameter details. *)
128
129val delete :
130 sw:Eio.Switch.t ->
131 clock:_ Eio.Time.clock ->
132 net:_ Eio.Net.t ->
133 ?headers:Headers.t ->
134 ?auth:Auth.t ->
135 ?timeout:Timeout.t ->
136 ?verify_tls:bool ->
137 ?tls_config:Tls.Config.client ->
138 string ->
139 Response.t
140(** DELETE request. See {!request} for parameter details. *)
141
142val head :
143 sw:Eio.Switch.t ->
144 clock:_ Eio.Time.clock ->
145 net:_ Eio.Net.t ->
146 ?headers:Headers.t ->
147 ?auth:Auth.t ->
148 ?timeout:Timeout.t ->
149 ?verify_tls:bool ->
150 ?tls_config:Tls.Config.client ->
151 string ->
152 Response.t
153(** HEAD request. See {!request} for parameter details. *)
154
155val patch :
156 sw:Eio.Switch.t ->
157 clock:_ Eio.Time.clock ->
158 net:_ Eio.Net.t ->
159 ?headers:Headers.t ->
160 ?body:Body.t ->
161 ?auth:Auth.t ->
162 ?timeout:Timeout.t ->
163 ?verify_tls:bool ->
164 ?tls_config:Tls.Config.client ->
165 string ->
166 Response.t
167(** PATCH request. See {!request} for parameter details. *)
168
169val upload :
170 sw:Eio.Switch.t ->
171 clock:_ Eio.Time.clock ->
172 net:_ Eio.Net.t ->
173 ?headers:Headers.t ->
174 ?auth:Auth.t ->
175 ?timeout:Timeout.t ->
176 ?method_:Method.t ->
177 ?mime:Mime.t ->
178 ?length:int64 ->
179 ?on_progress:(sent:int64 -> total:int64 option -> unit) ->
180 ?verify_tls:bool ->
181 ?tls_config:Tls.Config.client ->
182 source:Eio.Flow.source_ty Eio.Resource.t ->
183 string ->
184 Response.t
185(** Upload from stream. See {!request} for parameter details. *)
186
187val download :
188 sw:Eio.Switch.t ->
189 clock:_ Eio.Time.clock ->
190 net:_ Eio.Net.t ->
191 ?headers:Headers.t ->
192 ?auth:Auth.t ->
193 ?timeout:Timeout.t ->
194 ?on_progress:(received:int64 -> total:int64 option -> unit) ->
195 ?verify_tls:bool ->
196 ?tls_config:Tls.Config.client ->
197 string ->
198 sink:Eio.Flow.sink_ty Eio.Resource.t ->
199 unit
200(** Download to stream. See {!request} for parameter details. *)