Module http/client

Options for configuring an HTTP request.

An HTTP client that OWNS a pool of idle keep-alive connections (reqwest::Client's model, not a process-global one — a std with global mutable state has no way to say when those sockets close).

Requests made through a client reuse an idle connection to the same target when there is one, and put it back afterwards unless the exchange said otherwise (RFC 9112 §9.3 — see _response_keeps_alive). The free fetch and fetch_with do NOT use a client: they open a connection, announce Connection: close and close it, exactly as before.

A connection is only ever reused for the same scheme, host and port — the pool key. Handing an https://a connection to a request for https://b would speak to the wrong peer under the first peer's certificate, so the key is checked, never inferred.

dispose closes every idle connection, and close_idle() is the same operation under a name a caller can invoke (Go's Transport.CloseIdleConnections). Call close_idle() when you are done with a client: a client that has made a request does not currently reach reference count zero, because a ref value passed as a parameter to an io.async future is never released (issues/fixed/a-ref-value-passed-to-an-async-future-is-never-released.md), so the dispose on a scope exit does not yet fire. It is correct and will start firing when that defect is fixed.

Example

client := HttpClient.new();
a := io.await(client.fetch(`http://127.0.0.1:8080/one`, io), e);
b := io.await(client.fetch(`http://127.0.0.1:8080/two`, io), e); // same socket
client.close_idle();                                             // both closed

Stability

unstable — new, fetch, fetch_with, with_max_idle, with_idle_timeout, idle_count and close_idle are intended to keep their names and meanings; the pool's policies (a TOTAL idle cap, expiry on the next request rather than on a timer, closing the connection in hand rather than evicting one already pooled, and retrying only idempotent methods) are implementation choices that may change.

fetch_with's options, over this client's connection pool.

GET url_str, reusing an idle connection to the same scheme/host/port when the pool has one and returning it to the pool afterwards.

Default redirect cap — what browsers and curl use.

Default response ceiling: 64 MiB.

Default idle-connection cap: 16.

It is a TOTAL cap, not a per-target one, because the resource it protects is the process's descriptor table: a client that fans out over a thousand hosts would otherwise hold a thousand sockets open with a per-host cap of

1. 16 is enough for several concurrent tasks against a handful of targets, which is what a single-threaded event loop can actually keep busy.

Default idle age limit: 30 seconds.

A pooled connection can only be reused until the SERVER's own idle timeout closes it, and that number is not knowable from here — nginx defaults to 75 s, Apache to 5 s. Expiring at 30 s throws away connections a short-timeout server has probably already dropped, which is the half of the race a client can win on its own; the retry below covers the rest.