flare.http.client

Initialise an HttpClient with secure defaults.

Initialise an HttpClient with custom TLS configuration.

Initialise an HttpClient with authentication.

Initialise an HttpClient with a base URL and authentication.

Free the pooled fds + the Alt-Svc store owned by this client.

Idempotent on a moved-from client (_pool._addr == 0 / _alt_svc._addr == 0). Single-owner: copies are never produced for HttpClient because the type is :trait:Movable only, so each heap state is freed exactly once.

Enable connection pooling on this client.

Returns the client (move-in / move-out so the call chains with the regular HttpClient(...) constructor). Two pools are enabled, both keyed on the origin: the cleartext HTTP/1.1 pool (http://, reuses idle fds) and the HTTPS HTTP/1.1 pool (https://, reuses the whole established TlsStream so the TLS handshake is skipped on keep-alive reuse). An h2- negotiated TLS connection is multiplexed on the h2 path and is not pooled here.

Example:

with HttpClient(base_url="https://api.example.com")
    .with_pool() as c:
    # Two GETs reuse the same TLS connection on idle reuse.
    _ = c.get("/users")
    _ = c.get("/items")

Return the total number of connections currently sitting idle across both keep-alive pools (cleartext HTTP/1.1 fds + HTTPS TlsStream connections). Returns 0 when pooling is disabled.

Return the number of idle HTTPS (TLS HTTP/1.1) connections in the pool. Returns 0 when pooling is disabled.

Number of fresh HTTP/3 (QUIC) connections this client has had to dial (pool misses). Stays at 1 across repeated same-origin h3 requests when reuse is working.

Number of established HTTP/3 connections currently idle in the QUIC pool.

Opt this client into HTTP/3 (move-in / move-out so it chains off the constructor like :meth:with_pool).

When enabled, https:// requests prefer h3 over QUIC; the decision still flows through :meth:http3_wire_choice and any QUIC dial failure falls back transparently to the existing h2/h1 path.

Example:

with HttpClient("https://example.com").with_prefer_http3() as c:
    _ = c.get("/")

Choose how cleartext HTTP/2 is reached.

Added in v0.11 as the spelling for what the prefer_h2c and h2c_upgrade constructor arguments set. Those still work and are not going away this release, but a knob reachable two ways is a knob that drifts.

Idle-connection counts and dial totals across all three pools.

Added in v0.11. Replaces reading idle_count / tls_idle_count / quic_idle_count / quic_dials separately, which made it easy to check one pool and believe you had checked them all. Those four accessors still work.

One difference worth knowing when migrating: idle_count() returns the cleartext and TLS pools added together, while :attr:PoolStats.h1_idle is the cleartext pool alone and :attr:PoolStats.tls_idle the TLS one. h1_idle + tls_idle is the old number.

Bound body reads, not just connect(2) (move-in / move-out so it chains off the constructor like :meth:with_pool).

timeout_ms only ever reached connect; once the connection was up a read could block forever. That is what a half-open connection looks like to the client -- the network drops after the request goes out, the peer never learns it should FIN, and recv waits for bytes that will never arrive. ms sets SO_RCVTIMEO on the socket, so a read that stalls that long raises Timeout instead.

The bound is per-read inactivity, not a deadline on the whole response: a large body that keeps arriving never trips it, and a stalled one trips it after ms of silence. The client has no whole-request deadline.

Set it before the first request. The timeout rides on the socket, so a connection keeps it for its whole lifetime. Cleartext pooled fds are re-armed on checkout; pooled TLS connections keep whatever was armed when they were dialled, and lowering ms to 0 clears neither.

Example:

with HttpClient().with_read_timeout(10_000) as c:
    _ = c.get("https://example.com/")

Set the redirect-following policy (move-in / move-out so it chains off the constructor like :meth:with_pool).

The default (:meth:RedirectPolicy.follow_all) preserves the legacy unconditional-follow behaviour. Swap in :meth:RedirectPolicy.same_origin_only to refuse cross-origin redirects (and never leak the Authorization header across origins), or :meth:RedirectPolicy.deny to surface 3xx responses to the caller unfollowed.

Example:

var pol = RedirectPolicy.same_origin_only(max_redirects=5)
with HttpClient("https://api.example.com")
    .with_redirect_policy(pol) as c:
    _ = c.get("/protected")

Opt into request-level retries on transient failure (move-in / move-out, chains off the constructor).

Retries fire when a request raises (connection/I/O error) or returns a >= 500 status, up to policy.max_attempts total attempts. By default only idempotent methods (RFC 9110 sec 9.2.2) are retried; set policy.retry_only_idempotent = False to retry any method. Backoff follows the same jittered exponential schedule as the server-side :class:flare.http.reliability.Retry middleware.

Example:

var pol = RetryPolicy()
pol.max_attempts = 4
pol.initial_backoff_ms = 50
with HttpClient().with_retry(pol) as c:
    _ = c.get("https://flaky.example.com/data")

Set the decompressed-size ceiling for auto-decompressed response bodies (move-in / move-out, chains off the constructor).

Guards against a decompression bomb: a small compressed body that inflates without bound. Defaults to 16 MiB; raise or lower it to fit the largest legitimate response this client expects.

Example:

with HttpClient().with_max_decompressed_bytes(64 * 1024 * 1024) as c:
    _ = c.get("https://example.com/big.json.gz")

Route every request through the HTTP proxy at proxy_url (move-in / move-out, chains off the constructor).

Establishes a CONNECT tunnel to the origin through the proxy for both http:// and https:// (TLS then runs over the tunnel). Overrides the HTTP_PROXY / HTTPS_PROXY env policy; NO_PROXY is still honored. Pass "" to clear.

Example:

with HttpClient().with_proxy("http://127.0.0.1:8080") as c:
    var r = c.get("http://example.com/")

Enable a per-client cookie jar (move-in / move-out, chains off the constructor).

When enabled, the client captures Set-Cookie response headers and replays the stored cookies as a Cookie request header on subsequent requests -- the standard session-cookie flow for a logged-in client. The jar is origin-agnostic (every stored cookie is sent on every request from this client), which matches the common single-origin HttpClient(base_url=...) session.

Example:

with HttpClient("https://api.example.com")
    .with_cookies() as c:
    _ = c.post("/login", '{"u":"a","p":"b"}')  # stores session
    _ = c.get("/me")                            # replays cookie

The Cookie request header value the jar would send to url, or "" when cookies are disabled / none match. Useful for tests and introspection.

Record an origin's Alt-Svc response header (RFC 7838) into the discovery cache.

Reads self (the cache is interior-mutable behind the :class:AltSvcStore handle), so it composes with the read-self request surface and the transparent auto-record in :meth:send. origin is the host:port the response came from; alt_svc_header is the raw header value. A later request to the same origin then sees a fresh h3 advert via :meth:http3_wire_choice. A clear token evicts the cached entry. Non-h3 adverts are ignored.

The transparent h3-vs-h2 decision for one request.

Consults the prefer_http3 knob + the per-origin Alt-Svc cache and returns an :class:flare.http._client.alt_svc.Http3WireChoice codepoint (HTTP_3 or HTTP_2_OR_LOWER). QUIC support is compiled in, so the only gates are the scheme (https only) and whether h3 is preferred or freshly advertised. The runtime send path falls back to h2/h1 on any QUIC dial failure regardless of this result.

Send a request whose body is streamed from a ChunkSource using Transfer-Encoding: chunked, without materializing the full body in memory.

For large uploads (multi-MB / multi-GB) this keeps client memory bounded to one chunk in flight: the source's next(cancel) is pulled, framed as a chunked-transfer chunk, and written straight to the socket. The body is never assembled into a single buffer.

This is an explicit bounded-memory path over HTTP/1.1 (cleartext or TLS, ALPN forced to http/1.1); it deliberately does not go through connection pooling, redirects, retries, h2, or h3 (all of which buffer or re-send the body). Use :meth:post / :meth:send for those.

Transfer ownership of self into the with block.

Return a client with secure defaults (TLS verification enabled).

Perform a GET request.

Stream a GET response body without buffering it.

Works on http:// and https:// alike. The wire is chosen the way :meth:send chooses it, with one exception: ALPN settles h2 versus HTTP/1.1 on TLS, and cleartext uses HTTP/1.1 unless :meth:with_h2c asked for prior-knowledge h2c. The Upgrade: h2c handshake is the exception -- a streaming response cannot be re-read if the origin declines the upgrade, so this path stays on HTTP/1.1 rather than guessing.

The response head is parsed before this returns; the body is pulled by :meth:HttpStreamResponse.read_chunk, so a multi-gigabyte download costs one buffer rather than one allocation the size of the body. The connection is exclusive to this response and is not pooled.

Changed in v0.11. This used to be cleartext-only and raised on https://, with get_streaming_tls as its TLS twin pinned to HTTP/1.1. One entry point covers both now and the return type changed from HttpDownload[TcpStream] to HttpStreamResponse.

POST a JSON body and stream the response.

The shape server-sent events and JSON-lines APIs want: a small request, then a response read incrementally for as long as the server keeps writing.

Send req and stream the response body.

The primitive the other two are written in terms of. Redirects, retries and cookie handling apply only up to the point the head is parsed; after that the body belongs to the caller and cannot be replayed, so nothing re-sends it.

Perform a POST request with a JSON string body.

Sets Content-Type: application/json automatically. This is the default for string bodies because virtually every HTTP API that accepts a string payload expects JSON.

Example:

var resp = client.post("https://httpbin.org/post", '{"key": "value"}')
resp.raise_for_status()

Perform a POST request with a json.Value body.

Serialises body to JSON with dumps and sets Content-Type: application/json automatically.

Perform a POST request with a raw byte body.

No Content-Type header is set automatically; the caller is responsible for setting it via a custom Request if required.

Perform a PUT request with a JSON string body.

Sets Content-Type: application/json automatically.

Perform a PUT request with a json.Value body.

Serialises body to JSON with dumps and sets Content-Type: application/json automatically.

Perform a PUT request with a raw byte body.

No Content-Type header is set automatically.

Perform a DELETE request.

Perform a HEAD request.

Identical to GET but the server MUST NOT include a message body in the response (RFC 7231 §4.3.2).

Perform a PATCH request with a JSON string body.

Sets Content-Type: application/json automatically.

Perform a PATCH request with a json.Value body.

Serialises body to JSON with dumps and sets Content-Type: application/json automatically.

Perform a PATCH request with a raw byte body.

No Content-Type header is set automatically.

Send an HTTP request and return the response.

Follows redirects per the configured :class:RedirectPolicy (default: follow all, capped at max_redirects), transparently decodes a compressed body when auto_decompress is on, and replays / captures cookies when the jar is enabled. When :meth:with_retry opted in, the whole exchange is retried on a transient failure per the :class:RetryPolicy.