hairpin.bend
bend-kit-hairpin@0.8.0.0 · 454 lines · 0 definitions
1# Hairpin: an HTTP client with a base URL, default headers, a pool, cookies, mTLS, redirects, and proven retries. Source: https://github.com/paymog/bend-kit/tree/main/hairpin
2import Base
3import bend-kit-http@0.35.0.0/http.bend as Http
4import bend-kit-time@0.2.0.0/time.bend as Time
5import bend-kit-url@0.4.1.0/url.bend as Url
6import bend-kit-json@0.6.1.1/json.bend as Json
7import bend-kit-bytes@0.3.2.0/bytes.bend as Bytes
8import bend-kit-retry@0.1.0.0/retry.bend as Retry
9
10# base: "" for none. headers: lowercase names. ms: the step timeout. policy: attempts, backoff, and deadline of each request.
11type Opts is Data:
12 Opts{base: String, headers: Map<&2, List<&2, String>>, ms: U32, mode: Http.Mode, policy: Retry.Policy, cert: Maybe<&2, Http.Cert>}
13
14# breaker: the circuit breaker of every request on this client.
15type Client is Type:
16 Client{opts: Opts, pool: Http.Pool, jar: Maybe<&2, Http.Jar>, breaker: Retry.Breaker}
17
18# ErrHttp: the last attempt failed. ErrDenied: no attempt started, for why.
19type Err is Data:
20 ErrHttp{error: Http.Err}
21 ErrDenied{why: Retry.Deny}
22
23# One attempt, the first included; backoff from 500 ms, doubled to at most 30 s; no deadline.
24def policy() -> Retry.Policy:
25 Retry.Policy{1n, 500n, 30000, None{}}
26
27# A pool of up to cap idle sockets per origin, no base, no default headers, 30 s steps, follow redirects,
28# no retries, and no circuit breaker.
29def new.with(+cap: U32) -> Client:
30 Client{Opts{"", Http.empty(), 30000, Http.ModeFollow{}, policy(), None{}}, Http.pool.new.with(cap), None{}, Retry.BreakerOff{}}
31
32def new() -> Client:
33 new.with(8)
34
35def base(c: Client, url: String) -> Client:
36 Client{Opts{b, h, ms, mode, p, cert}, pool, j, br} = c
37 Client{Opts{url, h, ms, mode, p, cert}, pool, j, br}
38
39# A default header. It replaces an earlier default of the same name; a request header of that name replaces it.
40def header(c: Client, k: String, v: String) -> Client:
41 Client{Opts{b, h, ms, mode, p, cert}, pool, j, br} = c
42 Client{Opts{b, Http.set(h, String.to_lower(k), v), ms, mode, p, cert}, pool, j, br}
43
44def timeout(c: Client, ms: U32) -> Client:
45 Client{Opts{b, h, old, mode, p, cert}, pool, j, br} = c
46 Client{Opts{b, h, ms, mode, p, cert}, pool, j, br}
47
48def redirect(c: Client, mode: Http.Mode) -> Client:
49 Client{Opts{b, h, ms, old, p, cert}, pool, j, br} = c
50 Client{Opts{b, h, ms, mode, p, cert}, pool, j, br}
51
52# Up to n retries after the first attempt: n + 1 attempts in all.
53def retry(c: Client, n: U32) -> Client:
54 Client{Opts{b, h, ms, mode, Retry.Policy{old, base, cap, d}, cert}, pool, j, br} = c
55 Client{Opts{b, h, ms, mode, Retry.Policy{1n+U32.to_nat(n), base, cap, d}, cert}, pool, j, br}
56
57# No attempt of a request starts ms or more after the request starts.
58def deadline(c: Client, ms: U32) -> Client:
59 Client{Opts{b, h, t, mode, Retry.Policy{a, base, cap, old}, cert}, pool, j, br} = c
60 Client{Opts{b, h, t, mode, Retry.Policy{a, base, cap, Some{U32.to_nat(ms)}}, cert}, pool, j, br}
61
62# A circuit breaker in front of every request, starting closed.
63def circuit(c: Client, circ: Retry.Circuit) -> Client:
64 Client{o, pool, j, old} = c
65 Client{o, pool, j, Retry.Breaker.new(circ)}
66
67# The breaker, for inspection.
68def breaker.of(c: Client) -> Client & Retry.Breaker:
69 Client{o, pool, j, +br} = c
70 (Client{o, pool, j, br}, br)
71
72# Paths to a PEM client chain and its private key, presented to every HTTPS origin.
73def cert(c: Client, chain: String, key: String) -> Client:
74 Client{Opts{b, h, ms, mode, p, old}, pool, j, br} = c
75 Client{Opts{b, h, ms, mode, p, Some{Http.Cert{chain, key}}}, pool, j, br}
76
77# Every request stores and sends cookies through jar. Its clock moves to Time.now() before each try.
78def jar(c: Client, jar: Http.Jar) -> Client:
79 Client{o, pool, old, br} = c
80 Client{o, pool, Some{jar}, br}
81
82# The jar, if the client has one.
83def jar.of(c: Client) -> Client & Maybe<&2, Http.Jar>:
84 Client{o, pool, +j, br} = c
85 (Client{o, pool, j, br}, j)
86
87def close(c: Client) -> IO(Unit):
88 Client{o, pool, j, br} = c
89 Http.pool.close(pool)
90
91def target.pick(none: Bool, b: String, ref: String) -> Maybe<&2, String>:
92 match none:
93 case True{}:
94 Some{ref}
95 case False{}:
96 Http.resolve(b, ref)
97
98# ref against the base (RFC 3986 §5.2); with no base, ref as given. None when the base is not absolute.
99def target(+b: String, ref: String) -> Maybe<&2, String>:
100 target.pick(String.is_empty(b), b, ref)
101
102def target.abs(m: Maybe<&2, String>) -> Maybe<&2, Url.Abs>:
103 match m:
104 case None{}:
105 None{}
106 case Some{s}:
107 Url.absolute(s)
108
109# The defaults under the request headers, names lowercased; a request header replaces a default of its name.
110# Host, Connection, Content-Length, and Transfer-Encoding are the client's own, so both sides drop them.
111def merge(defaults: Map<&2, List<&2, String>>, headers: Map<&2, List<&2, String>>) -> Map<&2, List<&2, String>>:
112 Http.req.put(Map.to_list(&2, List<&2, String>, headers), Http.req.put(Map.to_list(&2, List<&2, String>, defaults), Http.empty()))
113
114def jar.now(j: Maybe<&2, Http.Jar>) -> IO(Maybe<&2, Http.Jar>):
115 match j:
116 case None{}:
117 IO.pure(Maybe<&2, Http.Jar>, None{})
118 case Some{jar}:
119 do IO<Maybe<&2, Http.Jar>>:
120 now : Time.Instant <- Time.now()
121 return Some{Http.jar.at(jar, now)}
122
123def once.final(+enc: String, x: Http.Pool & Result<&1, &1, Http.Err, Http.Res> & Maybe<&2, Http.Jar>) ->
124 IO(Http.Pool & Maybe<&2, Http.Jar> & Result<&1, &1, Http.Err, Http.Res>):
125 (p, r, j) = x
126 do IO<Http.Pool & Maybe<&2, Http.Jar> & Result<&1, &1, Http.Err, Http.Res>>:
127 d : Result<&1, &1, Http.Err, Http.Res> <- Http.fetch.final(enc, r)
128 return (p, j, d)
129
130# One try: the redirect loop on the pool, with the jar and the certificate, then the body decoded.
131def once(+ms: U32, +mode: Http.Mode, +cert: Maybe<&2, Http.Cert>, +enc: String, p: Http.Pool, j: Maybe<&2, Http.Jar>,
132 +method: String, +u: Maybe<&2, Url.Abs>, +headers: Map<&2, List<&2, String>>, body: Bytes.Bytes) ->
133 IO(Http.Pool & Maybe<&2, Http.Jar> & Result<&1, &1, Http.Err, Http.Res>):
134 do IO<Http.Pool & Maybe<&2, Http.Jar> & Result<&1, &1, Http.Err, Http.Res>>:
135 now : Maybe<&2, Http.Jar> <- jar.now(j)
136 x : Http.Pool & Result<&1, &1, Http.Err, Http.Res> & Maybe<&2, Http.Jar> <-
137 Http.pool.hops(mode, ms, Http.Hops{p, Http.fetch.start(method, headers, body, u, enc), cert, now, ""})
138 once.final(enc, x)
139
140def hint.ms(m: Maybe<&2, U32>) -> Maybe<&2, Nat>:
141 match m:
142 case None{}:
143 None{}
144 case Some{ms}:
145 Some{U32.to_nat(ms)}
146
147# m is Http.retry.judge's verdict for an idempotent request: Some{Retry-After} when another try may help.
148# A non-idempotent request with that verdict is Unsafe: the breaker counts it, but it never repeats.
149def outcome(+idem: Bool, m: Maybe<&2, String>, now: Time.Instant) -> Retry.Outcome:
150 match m:
151 case None{}:
152 Retry.Settled{}
153 case Some{+v}:
154 Bool.pick(Retry.Outcome, idem, Retry.Transient{hint.ms(Http.retry.after(v, now))}, Retry.Unsafe{})
155
156def lift(-R: Type, r: Result<&1, &1, Http.Err, R>) -> Result<&1, &1, Err, R>:
157 match r:
158 case Fail{e}:
159 Fail{ErrHttp{e}}
160 case Done{res}:
161 Done{res}
162
163# The live state of one request between attempts. R: a response or a stream. last: the result of the last
164# attempt, None before the first.
165type Step<-R: Type> is Type:
166 Step{pool: Http.Pool, jar: Maybe<&2, Http.Jar>, breaker: Retry.Breaker, budget: Retry.Budget, body: Bytes.Bytes,
167 last: Maybe<&1, Result<&1, &1, Err, R>>, plan: Retry.Plan}
168
169# The clock, read only when a decision depends on it; 0 otherwise, which no such decision reads.
170def clock(need: Bool) -> IO(Nat):
171 match need:
172 case True{}:
173 Time.mono.ms()
174 case False{}:
175 IO.pure(Nat, 0n)
176
177def breaker.on(br: Retry.Breaker) -> Bool:
178 match br:
179 case Retry.BreakerOff{}:
180 False{}
181 case Retry.BreakerOn{c, s}:
182 True{}
183
184def transient(o: Retry.Outcome) -> Bool:
185 match o:
186 case Retry.Transient{after}:
187 True{}
188 case Retry.Settled{}:
189 False{}
190 case Retry.Unsafe{}:
191 False{}
192
193def some(m: Maybe<&2, Nat>) -> Bool:
194 match m:
195 case None{}:
196 False{}
197 case Some{t}:
198 True{}
199
200def deadline.some(b: Retry.Budget) -> Bool:
201 Retry.Budget{l, d} = b
202 some(d)
203
204# The wall clock dates a Retry-After, so it is read only for a transient failure.
205def outcome.io(+idem: Bool, m: Maybe<&2, String>) -> IO(Retry.Outcome):
206 match m:
207 case None{}:
208 IO.pure(Retry.Outcome, Retry.Settled{})
209 case Some{v}:
210 do IO<Retry.Outcome>:
211 wall : Time.Instant <- Time.now()
212 return outcome(idem, Some{v}, wall)
213
214# Jitter for the backoff, drawn only when a retry may follow.
215def jitter.io(need: Bool) -> IO(Nat):
216 match need:
217 case True{}:
218 do IO<Nat>:
219 rnd : Result<&1, &1, U32 & String, U32> <- IO.random_u32()
220 return U32.to_nat(Http.retry.jitter(rnd))
221 case False{}:
222 IO.pure(Nat, 0n)
223
224def settle.at(-R: Type, +now: Nat, +rnd: Nat, +p: Retry.Policy, +n: Nat, +o: Retry.Outcome, br: Retry.Breaker, +b: Retry.Budget,
225 body: Bytes.Bytes, pool: Http.Pool, jar: Maybe<&2, Http.Jar>, r: Result<&1, &1, Http.Err, R>) -> Step<R>:
226 Step{pool, jar, Retry.Breaker.done(br, now, Retry.failed(o)), b, body, Some{lift(R, r)}, Retry.plan(o, p, b, n, now, rnd)}
227
228# The attempt has ended: tell the breaker, and plan the next step.
229def settle.outcome(-R: Type, +p: Retry.Policy, +n: Nat, +o: Retry.Outcome, +br: Retry.Breaker, b: Retry.Budget, body: Bytes.Bytes,
230 pool: Http.Pool, jar: Maybe<&2, Http.Jar>, r: Result<&1, &1, Http.Err, R>) -> IO(Step<R>):
231 do IO<Step<R>>:
232 now : Nat <- clock(Bool.or(breaker.on(br), transient(o)))
233 rnd : Nat <- jitter.io(transient(o))
234 return settle.at(R, now, rnd, p, n, o, br, b, body, pool, jar, r)
235
236def settle.judged(-R: Type, +p: Retry.Policy, +idem: Bool, +n: Nat, br: Retry.Breaker, b: Retry.Budget, body: Bytes.Bytes,
237 pool: Http.Pool, jar: Maybe<&2, Http.Jar>, j: Result<&1, &1, Http.Err, R> & Maybe<&2, String>) -> IO(Step<R>):
238 (r, m) = j
239 do IO<Step<R>>:
240 o : Retry.Outcome <- outcome.io(idem, m)
241 settle.outcome(R, p, n, o, br, b, body, pool, jar, r)
242
243# The default judge: Http.retry.judge, as if the request were idempotent; outcome then applies idem.
244def judge(r: Result<&1, &1, Http.Err, Http.Res>) -> Result<&1, &1, Http.Err, Http.Res> & Maybe<&2, String>:
245 Http.retry.judge(True{}, r)
246
247def settle(~R: Type, ~judge: Result<&1, &1, Http.Err, R> -> Result<&1, &1, Http.Err, R> & Maybe<&2, String>,
248 +p: Retry.Policy, +idem: Bool, +n: Nat, br: Retry.Breaker, b: Retry.Budget, body: Bytes.Bytes,
249 x: Http.Pool & Maybe<&2, Http.Jar> & Result<&1, &1, Http.Err, R>) -> IO(Step<R>):
250 (pool, jar, r) = x
251 settle.judged(R, p, idem, n, br, b, body, pool, jar, judge(r))
252
253# The inputs of one attempt. u: the target, None when it is not absolute. headers: the merged headers.
254type Call is Data:
255 Call{enc: String, method: String, u: Maybe<&2, Url.Abs>, headers: Map<&2, List<&2, String>>}
256
257# One attempt that reads a whole response: the redirect loop on the pool, with the jar and the certificate.
258def try.res(o: Opts, call: Call, pool: Http.Pool, jar: Maybe<&2, Http.Jar>, body: Bytes.Bytes) ->
259 IO(Http.Pool & Maybe<&2, Http.Jar> & Result<&1, &1, Http.Err, Http.Res>):
260 Opts{base, h, +ms, +mode, p, +cert} = o
261 Call{+enc, +method, +u, +headers} = call
262 once(ms, mode, cert, enc, pool, jar, method, u, headers, body)
263
264def try.stream.got(pool: Http.Pool, x: Maybe<&2, Http.Jar> & Result<&1, &1, Http.Err, Http.Stream>) ->
265 Http.Pool & Maybe<&2, Http.Jar> & Result<&1, &1, Http.Err, Http.Stream>:
266 (jar, s) = x
267 (pool, jar, s)
268
269# One attempt that opens a stream on its own connection, outside the pool: the redirect loop with the mode,
270# the jar, and the certificate, then the body decoded by enc.
271def try.stream(o: Opts, call: Call, pool: Http.Pool, jar: Maybe<&2, Http.Jar>, body: Bytes.Bytes) ->
272 IO(Http.Pool & Maybe<&2, Http.Jar> & Result<&1, &1, Http.Err, Http.Stream>):
273 Opts{base, h, +ms, mode, p, cert} = o
274 Call{+enc, method, u, headers} = call
275 do IO<Http.Pool & Maybe<&2, Http.Jar> & Result<&1, &1, Http.Err, Http.Stream>>:
276 now : Maybe<&2, Http.Jar> <- jar.now(jar)
277 r : Maybe<&2, Http.Jar> & Result<&1, &1, Http.Err, Http.Stream> <-
278 Http.stream.hops(mode, ms, Http.StreamHops{Http.stream.start(method, Http.accept.enc(headers, enc), body, u), cert, now})
279 x : Maybe<&2, Http.Jar> & Result<&1, &1, Http.Err, Http.Stream> <- Http.stream.init.jar(enc, r)
280 return try.stream.got(pool, x)
281
282def close.res(r: Http.Res) -> IO(Unit):
283 IO.pure(Unit, Unit{})
284
285def close.last(~R: Type, ~close: R -> IO(Unit), last: Maybe<&1, Result<&1, &1, Err, R>>) -> IO(Unit):
286 match last:
287 case None{}:
288 IO.pure(Unit, Unit{})
289 case Some{r}:
290 match r:
291 case Fail{e}:
292 IO.pure(Unit, Unit{})
293 case Done{x}:
294 close(x)
295
296def attempt.run(~R: Type, ~judge: Result<&1, &1, Http.Err, R> -> Result<&1, &1, Http.Err, R> & Maybe<&2, String>,
297 ~try: Opts -> Call -> Http.Pool -> Maybe<&2, Http.Jar> -> Bytes.Bytes -> IO(Http.Pool & Maybe<&2, Http.Jar> & Result<&1, &1, Http.Err, R>),
298 +o: Opts, +call: Call, +idem: Bool, +n: Nat, pool: Http.Pool, jar: Maybe<&2, Http.Jar>, br: Retry.Breaker,
299 b: Retry.Budget, r: Bytes.Bytes & Bytes.Bytes) -> IO(Step<R>):
300 Opts{base, h, ms, mode, +p, cert} = o
301 (body, spare) = r
302 do IO<Step<R>>:
303 x : Http.Pool & Maybe<&2, Http.Jar> & Result<&1, &1, Http.Err, R> <- try(o, call, pool, jar, spare)
304 settle(~R, ~judge, p, idem, n, br, b, body, x)
305
306def denied(-R: Type, why: Retry.Deny, last: Maybe<&1, Result<&1, &1, Err, R>>) -> Maybe<&1, Result<&1, &1, Err, R>>:
307 match last:
308 case None{}:
309 Some{Fail{ErrDenied{why}}}
310 case Some{r}:
311 Some{r}
312
313# A refused stream closes only when the next attempt is admitted, so a denied attempt still returns it.
314def attempt.gate(~R: Type, ~judge: Result<&1, &1, Http.Err, R> -> Result<&1, &1, Http.Err, R> & Maybe<&2, String>,
315 ~try: Opts -> Call -> Http.Pool -> Maybe<&2, Http.Jar> -> Bytes.Bytes -> IO(Http.Pool & Maybe<&2, Http.Jar> & Result<&1, &1, Http.Err, R>),
316 ~close: R -> IO(Unit),
317 x: Retry.Breaker & Retry.Budget & Retry.Gate, +o: Opts, +call: Call, +idem: Bool, +n: Nat, pool: Http.Pool,
318 jar: Maybe<&2, Http.Jar>, body: Bytes.Bytes, last: Maybe<&1, Result<&1, &1, Err, R>>) -> IO(Step<R>):
319 (br, b, g) = x
320 match g:
321 case Retry.GateNo{why}:
322 IO.pure(Step<R>, Step{pool, jar, br, b, body, denied(R, why, last), Retry.PlanStop{}})
323 case Retry.GateGo{}:
324 do IO<Step<R>>:
325 close.last(~R, ~close, last)
326 attempt.run(~R, ~judge, ~try, o, call, idem, n, pool, jar, br, b, Bytes.slice(body, 0, 4294967295))
327
328# Ask the gate; when it admits, make attempt n (0 first) of this layer. With no deadline and no breaker,
329# admission does not read the clock.
330def attempt(~R: Type, ~judge: Result<&1, &1, Http.Err, R> -> Result<&1, &1, Http.Err, R> & Maybe<&2, String>,
331 ~try: Opts -> Call -> Http.Pool -> Maybe<&2, Http.Jar> -> Bytes.Bytes -> IO(Http.Pool & Maybe<&2, Http.Jar> & Result<&1, &1, Http.Err, R>),
332 ~close: R -> IO(Unit),
333 +o: Opts, +call: Call, +idem: Bool, +n: Nat, s: Step<R>) -> IO(Step<R>):
334 Step{pool, jar, +br, +b, body, last, plan} = s
335 do IO<Step<R>>:
336 now : Nat <- clock(Bool.or(breaker.on(br), deadline.some(b)))
337 attempt.gate(~R, ~judge, ~try, ~close, Retry.admit(br, b, now), o, call, idem, n, pool, jar, body, last)
338
339def pause(ms: Nat) -> IO(Unit):
340 match ms:
341 case 0n:
342 IO.pure(Unit, Unit{})
343 case 1n+k:
344 IO.sleep(U32.from_nat(1n+k))
345
346# left: attempts this layer may still make. n: attempts made so far. Each turn follows the plan of the last step.
347def go(~R: Type, ~judge: Result<&1, &1, Http.Err, R> -> Result<&1, &1, Http.Err, R> & Maybe<&2, String>,
348 ~try: Opts -> Call -> Http.Pool -> Maybe<&2, Http.Jar> -> Bytes.Bytes -> IO(Http.Pool & Maybe<&2, Http.Jar> & Result<&1, &1, Http.Err, R>),
349 ~close: R -> IO(Unit),
350 left: Nat, +n: Nat, +o: Opts, +call: Call, +idem: Bool, s: Step<R>) -> IO(Step<R>):
351 match left:
352 case 0n:
353 IO.pure(Step<R>, s)
354 case 1n+rest:
355 Step{pool, jar, br, b, body, last, plan} = s
356 match plan:
357 case Retry.PlanStop{}:
358 IO.pure(Step<R>, Step{pool, jar, br, b, body, last, Retry.PlanStop{}})
359 case Retry.PlanWait{ms}:
360 do IO<Step<R>>:
361 pause(ms)
362 next : Step<R> <- attempt(~R, ~judge, ~try, ~close, o, call, idem, n, Step{pool, jar, br, b, body, last, Retry.PlanStop{}})
363 go(~R, ~judge, ~try, ~close, rest, 1n+n, o, call, idem, next)
364
365def result.of(-R: Type, m: Maybe<&1, Result<&1, &1, Err, R>>) -> Result<&1, &1, Err, R>:
366 match m:
367 case None{}:
368 Fail{ErrDenied{Retry.DenySpent{}}}
369 case Some{r}:
370 r
371
372def request.done(-R: Type, +o: Opts, s: Step<R>) -> Client & Retry.Budget & Result<&1, &1, Err, R>:
373 Step{pool, jar, br, b, body, last, plan} = s
374 (Client{o, pool, jar, br}, b, result.of(R, last))
375
376def attempts(p: Retry.Policy) -> Nat:
377 Retry.Policy{a, base, cap, d} = p
378 a
379
380# The budget of one plain request: the policy's attempts, and its deadline from now. The clock is read only for a deadline.
381def budget(c: Client) -> IO(Client & Retry.Budget):
382 Client{+o, pool, jar, br} = c
383 Opts{base, h, ms, mode, Retry.Policy{+a, bs, cap, +d}, cert} = o
384 do IO<Client & Retry.Budget>:
385 now : Nat <- clock(some(d))
386 return (Client{o, pool, jar, br}, Retry.Budget.new(a, now, d))
387
388def run(~R: Type, ~judge: Result<&1, &1, Http.Err, R> -> Result<&1, &1, Http.Err, R> & Maybe<&2, String>,
389 ~try: Opts -> Call -> Http.Pool -> Maybe<&2, Http.Jar> -> Bytes.Bytes -> IO(Http.Pool & Maybe<&2, Http.Jar> & Result<&1, &1, Http.Err, R>),
390 ~close: R -> IO(Unit),
391 c: Client, b: Retry.Budget, +idem: Bool, enc: String, method: String, url: String,
392 headers: Map<&2, List<&2, String>>, body: Bytes.Bytes) -> IO(Client & Retry.Budget & Result<&1, &1, Err, R>):
393 Client{+o, pool, jar, br} = c
394 Opts{+base, +h, ms, mode, +p, cert} = o
395 +call = {Call{enc, method, target.abs(target(base, url)), merge(h, headers)} : Call}
396 do IO<Client & Retry.Budget & Result<&1, &1, Err, R>>:
397 s : Step<R> <- go(~R, ~judge, ~try, ~close, attempts(p), 0n, o, call, idem, Step{pool, jar, br, b, body, None{}, Retry.PlanWait{0n}})
398 return request.done(R, o, s)
399
400# One request inside a caller's retry layer, with every choice explicit. Every attempt takes from b, the
401# caller's shared budget, and obeys its deadline; the client's own policy caps the attempts of this call.
402# The budget left comes back beside the result: pass it to the next call, so nested layers never reset or
403# multiply it. The client's own deadline does not apply here; b's does.
404# judge: Some{Retry-After} when another attempt may help. idem: the request is safe to repeat, so a judged
405# failure is retried; else the breaker counts it and it never repeats. enc: the Accept-Encoding codings.
406def request.as(~judge: Result<&1, &1, Http.Err, Http.Res> -> Result<&1, &1, Http.Err, Http.Res> & Maybe<&2, String>,
407 c: Client, b: Retry.Budget, +idem: Bool, +enc: String, +method: String, url: String,
408 headers: Map<&2, List<&2, String>>, body: Bytes.Bytes) -> IO(Client & Retry.Budget & Result<&1, &1, Err, Http.Res>):
409 run(~Http.Res, ~judge, ~try.res, ~close.res, c, b, idem, enc, method, url, headers, body)
410
411# A streamed request under the same budget, deadline, backoff, and breaker as request.as. The stream opens its
412# own connection outside the pool. It follows the client's redirect mode, presents its certificate, and sends
413# and stores cookies through its jar, as request.as does. judge reads the status and headers through
414# Http.stream.res. A refused stream closes before the next attempt; the last one comes back open, so the
415# caller can read its body.
416def open.as(~judge: Result<&1, &1, Http.Err, Http.Stream> -> Result<&1, &1, Http.Err, Http.Stream> & Maybe<&2, String>,
417 c: Client, b: Retry.Budget, +idem: Bool, +enc: String, +method: String, url: String,
418 headers: Map<&2, List<&2, String>>, body: Bytes.Bytes) -> IO(Client & Retry.Budget & Result<&1, &1, Err, Http.Stream>):
419 run(~Http.Stream, ~judge, ~try.stream, ~Http.stream.close, c, b, idem, enc, method, url, headers, body)
420
421# request.as with judge, the idempotency of method, and every coding Http decodes.
422def request.in(c: Client, b: Retry.Budget, +method: String, url: String, headers: Map<&2, List<&2, String>>,
423 body: Bytes.Bytes) -> IO(Client & Retry.Budget & Result<&1, &1, Err, Http.Res>):
424 do IO<Client & Retry.Budget & Result<&1, &1, Err, Http.Res>>:
425 enc : String <- Http.codings()
426 request.as(~judge, c, b, Http.pool.idempotent(method), enc, method, url, headers, body)
427
428def request.drop(x: Client & Retry.Budget & Result<&1, &1, Err, Http.Res>) -> Client & Result<&1, &1, Err, Http.Res>:
429 (c, b, r) = x
430 (c, r)
431
432def request.budget(+method: String, url: String, headers: Map<&2, List<&2, String>>, body: Bytes.Bytes,
433 x: Client & Retry.Budget) -> IO(Client & Retry.Budget & Result<&1, &1, Err, Http.Res>):
434 (c, b) = x
435 request.in(c, b, method, url, headers, body)
436
437# url resolves against the base; headers go over the defaults. Redirects follow the client's mode, at most 20.
438# Each request gets a fresh budget from budget(c). Before each attempt the deadline, the
439# budget, and the breaker must admit it. GET, HEAD, OPTIONS, TRACE, PUT, and DELETE try again after a connect
440# error, a timeout, or 408, 429, 500, 502, 503, or 504, as Http.retry.judge says, on the same pool.
441# When the attempts run out, the last result comes back; when none started, ErrDenied says why.
442def request(c: Client, +method: String, url: String, headers: Map<&2, List<&2, String>>, body: Bytes.Bytes) ->
443 IO(Client & Result<&1, &1, Err, Http.Res>):
444 do IO<Client & Result<&1, &1, Err, Http.Res>>:
445 y : Client & Retry.Budget <- budget(c)
446 x : Client & Retry.Budget & Result<&1, &1, Err, Http.Res> <- request.budget(method, url, headers, body, y)
447 return request.drop(x)
448
449def get(c: Client, url: String) -> IO(Client & Result<&1, &1, Err, Http.Res>):
450 request(c, "GET", url, Http.empty(), Bytes.new(0))
451
452# POST v as compact JSON, with content-type: application/json.
453def post.json(c: Client, url: String, v: Json.Val) -> IO(Client & Result<&1, &1, Err, Http.Res>):
454 request(c, "POST", url, Http.set(Http.empty(), "content-type", "application/json"), Json.encode.bytes(v))