Struct Client 

pub struct Client { /* private fields */ }

Traced outbound HTTP client with automatic retries and test-mock support.

Extracted from AppState via Axum’s extractor machinery — declare it as a handler parameter to get a pre-configured instance that respects [http.client] config and, in test builds, intercepts requests against any registered mocks.

use autumn_web::prelude::*;
use autumn_web::http::Client;

#[get("/ping-upstream")]
async fn ping(client: Client) -> AutumnResult<&'static str> {
    client.get("https://api.example.com/health").send().await?;
    Ok("ok")
}

You can also construct a standalone client outside of a handler:

use autumn_web::http::Client;

let client = Client::new();

Implementations

impl Client

pub fn new() -> Self

Create a new client with default settings (30 s timeout, 3 retries on idempotent methods).

pub fn with_timeout(timeout: Duration) -> Self

Create a client with a custom per-request timeout.

Panics

Panics if the underlying TLS backend cannot be initialised (should not happen with the default rustls-tls feature).

pub fn from_config(config: &HttpClientConfig) -> Self

Create a client from [http.client] framework configuration.

Panics

Panics if the underlying TLS backend cannot be initialised (should not happen with the default rustls-tls feature).

pub fn from_state(state: &AppState) -> Self

Build a client from runtime application state.

When the server was started via AppBuilder, a single reqwest::Client is registered in AppState at boot as a SharedReqwestClient. This method clones that shared instance (O(1), preserves the connection pool) instead of constructing a new one, eliminating per-request TCP/TLS handshakes and DNS-resolver-spawn overhead.

Falls back to Self::new() for detached or test state that does not carry a shared client.

pub fn named(&self, alias: &str) -> Self

Return a clone of this client scoped to the named alias.

When a [http.client.base_urls] entry exists for the alias the client will prepend that URL to all relative paths. Mocks registered for the alias via TestApp::http_mock will match requests made through this named client.

pub fn with_base_url(&self, base_url: impl Into<String>) -> Self

Set (or override) the base URL prepended to relative request paths.

pub fn get(&self, url: impl AsRef<str>) -> RequestBuilder

Build a GET request.

pub fn post(&self, url: impl AsRef<str>) -> RequestBuilder

Build a POST request.

pub fn put(&self, url: impl AsRef<str>) -> RequestBuilder

Build a PUT request.

pub fn patch(&self, url: impl AsRef<str>) -> RequestBuilder

Build a PATCH request.

pub fn delete(&self, url: impl AsRef<str>) -> RequestBuilder

Build a DELETE request.

pub fn head(&self, url: impl AsRef<str>) -> RequestBuilder

Build a HEAD request.

pub fn get_ssrf_safe(&self, url: impl Into<String>) -> RequestBuilder

Build an SSRF-safe GET request.

This is the composed safe path for fetching untrusted URLs. Before connecting it resolves the host once, validates every resolved IP against the built-in SSRF deny-list (is_blocked_ip) and rejects the request if any address is blocked. The connection is then pinned to the full set of validated addresses so reqwest cannot re-resolve the host (closing the DNS-rebinding / TOCTOU window) yet can still fall back across them in order if the first is unreachable. Redirects are followed manually up to SSRF_SAFE_MAX_REDIRECTS hops, re-running resolve→validate→pin on each hop; a hop that downgrades the scheme from https to http is rejected as defence-in-depth.

The redirect count and per-hop validation honour a chained builder override (the built-in resolve→validate→pin and scheme-downgrade guards always apply):

• by default, up to SSRF_SAFE_MAX_REDIRECTS hops are followed;
• a chained no_redirect returns the initial 3xx verbatim — the initial URL is still resolved, validated and pinned, but no redirect is followed;
• a chained follow_redirects(max, validator) caps following at max hops (so max == 0 turns the first 3xx into ClientError::TooManyRedirects) and additionally runs the caller’s validator(&next) on every hop, on top of the built-in guards.

Like the test-mock path, this custom send path bypasses the process-wide circuit-breaker registry to avoid entangling per-URL SSRF fetches with the shared per-host breaker state.

Env proxies are bypassed. Each pinned per-hop client is built with .no_proxy(), so HTTP_PROXY / HTTPS_PROXY / ALL_PROXY are ignored and the socket connects directly to the validated/pinned address. This is required for the pin to hold: reqwest checks proxy interception before the connector where the resolve() override applies, so a configured proxy would otherwise receive the request and re-resolve the host — reopening the DNS-rebinding / SSRF window this API closes.

Cannot be combined with pin_to. This path performs its own per-hop resolve→validate→pin and never reads the pin_to address, so an explicit pin would be silently ignored. Chaining the two is therefore rejected at send time with ClientError::PinNotAllowedWithSsrfSafe. Use pin_to alone for a caller-chosen fixed address, or get_ssrf_safe alone for guarded automatic per-hop pinning.

Trait Implementations

impl Clone for Client

fn clone(&self) -> Client

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Default for Client

fn default() -> Self

Returns the “default value” for a type.

impl FromRequestParts<AppState> for Client

type Rejection = Infallible

If the extractor fails it’ll use this “rejection” type. A rejection is a kind of error that can be converted into a response.

async fn from_request_parts( _parts: &mut Parts, state: &AppState, ) -> Result<Self, Infallible>

Perform the extraction.