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