fix: retry policy
diff --git a/src/Std/Http/Client/Agent.lean b/src/Std/Http/Client/Agent.lean index df90db0..2af2c4f 100644 --- a/src/Std/Http/Client/Agent.lean +++ b/src/Std/Http/Client/Agent.lean
@@ -8,7 +8,7 @@ prelude public import Std.Http.Client.Session public import Std.Http.Data.Cookie -public import Std.Http.Data.Redirect +public import Std.Http.Client.Redirect import Init.Data.Array public section
diff --git a/src/Std/Http/Client/Connector.lean b/src/Std/Http/Client/Connector.lean new file mode 100644 index 0000000..0063073 --- /dev/null +++ b/src/Std/Http/Client/Connector.lean
@@ -0,0 +1,79 @@ +/- +Copyright (c) 2026 Lean FRO, LLC. All rights reserved. +Released under Apache 2.0 license as described in the file LICENSE. +Authors: Sofia Rodrigues +-/ +module + +prelude +public import Std.Http.Client.Session +import Std.Async.DNS + +public section + +namespace Std.Http.Client + +open Std Async TCP +open Time + +set_option linter.all true + +/-! +# Connector + +A `Connector` abstracts DNS resolution and TCP/transport connection establishment for the +connection pool, mirroring the role of `http.Agent` in Node.js. + +The default `TcpConnector` resolves via the system DNS and dials a raw TCP socket. +Alternatives — a TLS connector, a Unix-socket connector, a mock for testing — implement +the same interface and can be plugged in at pool construction time. +-/ + +/-- +Type class for creating an HTTP session given a target `(scheme, host, port)` and a `Config`. + +Implement this to customize DNS resolution, transport selection (plain TCP, TLS, Unix socket), +or connection pooling behaviour at the socket level. +-/ +class Connector (α : Type) where + /-- + Open a new transport connection and wrap it in a `Session`. + + `scheme` is provided so implementations can dispatch between plain and encrypted + transports. `config.proxy` is available for proxy routing. + -/ + connect : α → URI.Scheme → URI.Host → UInt16 → Config → Async (Session Socket.Client) + +/-- +The default connector: resolves `host` via the system DNS, iterates over the returned +addresses, and opens a TCP socket to the first one that succeeds. + +When `config.proxy` is set, the TCP connection is made to the proxy address instead +and the original `host`/`port` are left for the HTTP layer to handle. +-/ +structure TcpConnector where + +instance : Connector TcpConnector where + connect _ _scheme host port config := do + let (connectHost, connectPort) := config.proxy.getD (toString host, port) + let addrs ← DNS.getAddrInfo connectHost (toString connectPort) + + if addrs.isEmpty then + throw (IO.userError s!"could not resolve host: {connectHost.quote}") + + let mut lastErr : IO.Error := IO.userError s!"could not connect to {connectHost.quote}:{connectPort}" + + for ipAddr in addrs do + let socketAddr : Std.Net.SocketAddress := match ipAddr with + | .v4 ip => .v4 ⟨ip, connectPort⟩ + | .v6 ip => .v6 ⟨ip, connectPort⟩ + try + let socket ← Socket.Client.mk + socket.connect socketAddr + return ← Session.new socket config + catch err => + lastErr := err + + throw lastErr + +end Std.Http.Client
diff --git a/src/Std/Http/Client/Pool.lean b/src/Std/Http/Client/Pool.lean index 51f14ea..c2dff93 100644 --- a/src/Std/Http/Client/Pool.lean +++ b/src/Std/Http/Client/Pool.lean
@@ -7,7 +7,7 @@ prelude public import Std.Http.Client.Agent -import Std.Async.DNS +public import Std.Http.Client.Connector import Std.Data.HashMap import Init.Data.Array @@ -33,32 +33,6 @@ -/ /-- -Resolves `host` via DNS, opens a TCP socket to `port`, and creates an HTTP session. -When `config.proxy` is set the TCP connection is made to the proxy address instead. --/ -private def createTcpSession (host : URI.Host) (port : UInt16) (config : Config) : Async (Session Socket.Client) := do - let (connectHost, connectPort) := config.proxy.getD (toString host, port) - let addrs ← DNS.getAddrInfo connectHost (toString connectPort) - - if addrs.isEmpty then - throw (IO.userError s!"could not resolve host: {connectHost.quote}") - - let mut lastErr : IO.Error := IO.userError s!"could not connect to {connectHost.quote}:{connectPort}" - - for ipAddr in addrs do - let socketAddr : Std.Net.SocketAddress := match ipAddr with - | .v4 ip => .v4 ⟨ip, connectPort⟩ - | .v6 ip => .v6 ⟨ip, connectPort⟩ - try - let socket ← Socket.Client.mk - socket.connect socketAddr - return ← Session.new socket config - catch err => - lastErr := err - - throw lastErr - -/-- Per-origin bucket inside the pool's state map. -/ structure Agent.Pool.Entry where @@ -66,10 +40,45 @@ idle : Array (Session Socket.Client) /-- All registered sessions, including idle and in-use. -/ all : Array (Session Socket.Client) - /-- Monotonically advancing round-robin index. -/ + /-- + Monotonically advancing round-robin index. + + Round-robin is correct for HTTP/1.1 because each connection is fully sequential — + no connection is "less loaded" than another while in use. If HTTP/2 multiplexing + is added in the future, switch to least-requests-in-flight selection instead. + -/ idx : Nat /-- +Policy controlling whether a failed request should be retried on a fresh connection. + +Retries only apply to connection-level failures (the session died before a response +was received). Application-level errors (4xx, 5xx) are never retried automatically. +-/ +structure RetryPolicy where + /-- + Called before evicting a broken session and re-dispatching. + `err` is the transport error; `attempt` is 0-based (0 = first failure). + Return `true` to retry on a new connection, `false` to propagate the error. + -/ + shouldRetry : IO.Error → Nat → Bool + /-- Hard cap on the number of retries regardless of `shouldRetry`. -/ + maxRetries : Nat + +namespace RetryPolicy + +/-- Never retries — the default. Mirrors Finch's explicit caller-responsibility approach. -/ +def never : RetryPolicy := { shouldRetry := fun _ _ => false, maxRetries := 0 } + +/-- +Retries once on any connection error. Safe for idempotent methods (GET, HEAD, PUT, +DELETE); callers must take care with non-idempotent methods (POST, PATCH). +-/ +def once : RetryPolicy := { shouldRetry := fun _ _ => true, maxRetries := 1 } + +end RetryPolicy + +/-- A connection pool that manages multiple sessions per `(scheme, host, port)` triple. -/ structure Agent.Pool where @@ -82,26 +91,42 @@ maxPerHost : Nat /-- Configuration used when creating new sessions. -/ config : Config - /-- Cookie jar shared across all sessions. -/ + /-- + Cookie jar shared across all sessions. + + The jar is decoupled from construction: pass an existing jar to `Pool.new` to share + cookies across multiple pools (e.g. a default pool and a TLS pool), or omit it to + get a fresh, isolated jar. + -/ cookieJar : Cookie.Jar /-- Monotonically increasing counter for unique session IDs. -/ nextId : Mutex UInt64 /-- Middlewares applied (outermost-first) around every request/response hop. -/ middlewares : Array Middleware := #[] + /-- Connector used to open new transport sessions. Defaults to plain TCP. -/ + connector : TcpConnector := {} + /-- Retry policy for connection-level failures. Defaults to no retries. -/ + retryPolicy : RetryPolicy := RetryPolicy.never namespace Agent.Pool -/-- Creates a new, empty connection pool. -/ -def new (config : Config := {}) (maxPerHost : Nat := 4) : Async Agent.Pool := do +/-- +Creates a new, empty connection pool. + +Pass `cookieJar` to share an existing jar across pools; omit it for a fresh isolated jar. +-/ +def new (config : Config := {}) (maxPerHost : Nat := 4) (cookieJar : Option Cookie.Jar := none) : Async Agent.Pool := do let state ← Mutex.new (∅ : Std.HashMap (String × String × UInt16) Agent.Pool.Entry) - let cookieJar ← Cookie.Jar.new + let cookieJar ← match cookieJar with + | some jar => pure jar + | none => Cookie.Jar.new let nextId ← Mutex.new (1 : UInt64) pure { state, maxPerHost, config, cookieJar, nextId, middlewares := #[] } /-- Returns a session for `(scheme, host, port)`. -Priority: idle session → new session (if under limit) → round-robin. +Priority: idle session → new session (if under limit) → round-robin across all sessions. -/ def getOrCreateSession (pool : Agent.Pool) (scheme : URI.Scheme) (host : URI.Host) (port : UInt16) : Async (Session Socket.Client) := do let key := (scheme.val, toString host, port) @@ -127,7 +152,7 @@ if let some session := maybeSession then return session - let session ← createTcpSession host port pool.config + let session ← Connector.connect pool.connector scheme host port pool.config let newId ← pool.nextId.atomically do let id ← MonadState.get MonadState.set (id + 1) @@ -163,24 +188,36 @@ MonadState.set (st.insert key { entry with idle := entry.idle.push session }) /-- -Sends a request through a pooled session, following redirects, injecting cookies, and -applying response interceptors. +Sends a request through a pooled session, following redirects, injecting cookies, +and applying middlewares. On connection failure, evicts the broken session and retries +according to `pool.retryPolicy`. -/ def send {β : Type} [Coe β Body.Any] (pool : Agent.Pool) (scheme : URI.Scheme) (host : URI.Host) (port : UInt16) (request : Request β) : Async (Response Body.Stream) := do - let session ← pool.getOrCreateSession scheme host port - Agent.send { - session - scheme - host - port - cookieJar := pool.cookieJar - middlewares := pool.middlewares - acquire := some (fun s h p => pool.getOrCreateSession s h p) - release := some (fun broken s h p => pool.evictSession s h p broken.id) - releaseHealthy := some (fun session s h p => pool.returnToIdle s h p session) - } request + let attempts := pool.retryPolicy.maxRetries + 1 + let mut lastErr : IO.Error := .userError "no attempts" + for attempt in List.range attempts do + let session ← pool.getOrCreateSession scheme host port + try + return ← Agent.send { + session + scheme + host + port + cookieJar := pool.cookieJar + middlewares := pool.middlewares + acquire := some (fun s h p => pool.getOrCreateSession s h p) + release := some (fun broken s h p => pool.evictSession s h p broken.id) + releaseHealthy := some (fun sess s h p => pool.returnToIdle s h p sess) + } request + catch err => + pool.evictSession scheme host port session.id + if pool.retryPolicy.shouldRetry err attempt then + lastErr := err + else + throw err + throw lastErr end Agent.Pool
diff --git a/src/Std/Http/Data/Redirect.lean b/src/Std/Http/Client/Redirect.lean similarity index 100% rename from src/Std/Http/Data/Redirect.lean rename to src/Std/Http/Client/Redirect.lean
diff --git a/src/Std/Http/Data.lean b/src/Std/Http/Data.lean index c8a18c5..b870655 100644 --- a/src/Std/Http/Data.lean +++ b/src/Std/Http/Data.lean
@@ -15,7 +15,6 @@ public import Std.Http.Data.Headers public import Std.Http.Data.URI public import Std.Http.Data.Body -public import Std.Http.Data.Redirect /-! # HTTP Data Types