Struct HttpClientBuilder 

pub struct HttpClientBuilder { /* private fields */ }

Builder for constructing an [HttpClient] with a layered tower middleware stack.

Implementations

impl HttpClientBuilder

pub fn new() -> Self

Create a new builder with default configuration

pub fn with_config(config: HttpClientConfig) -> Self

Create a builder with a specific configuration

pub fn timeout(self, timeout: Duration) -> Self

Set the per-request timeout

This timeout applies to each individual HTTP request/attempt. If retries are enabled, each retry attempt gets its own timeout.

pub fn total_timeout(self, timeout: Duration) -> Self

Set the total timeout spanning all retry attempts

When set, the entire operation (including all retries and backoff delays) must complete within this duration. If the deadline is exceeded, the request fails with HttpError::DeadlineExceeded(total_timeout).

pub fn user_agent(self, user_agent: impl Into<String>) -> Self

Set the user agent string

pub fn retry(self, retry: Option<RetryConfig>) -> Self

Set the retry configuration

pub fn max_body_size(self, size: usize) -> Self

Set the maximum response body size

pub fn transport(self, transport: TransportSecurity) -> Self

Set transport security mode

Use TransportSecurity::AllowInsecureHttp only for testing with mock servers.

pub fn allow_insecure_http(self) -> Self

Allow insecure HTTP connections (for testing only)

Equivalent to .transport(TransportSecurity::AllowInsecureHttp).

WARNING: This should only be used for local testing with mock servers. Never use in production as it exposes traffic to interception.

Compile-time Safety

This method is only available in debug builds or when the allow-insecure-http feature is explicitly enabled. This prevents accidental use in production.

To use in release builds (e.g., for integration tests), add:

[features]
allow-insecure-http = []

pub fn with_otel(self) -> Self

Enable OpenTelemetry tracing layer

When enabled, creates spans for outbound requests with HTTP metadata and injects W3C trace context headers (when otel feature is enabled).

pub fn with_auth_layer( self, wrap: impl FnOnce(BoxCloneService<Request<Full<Bytes>>, Response<ResponseBody>, HttpError>) -> BoxCloneService<Request<Full<Bytes>>, Response<ResponseBody>, HttpError> + Send + 'static, ) -> Self

Insert an optional auth layer between retry and timeout in the stack.

Stack position: … → Retry → **this layer** → Timeout → …

The layer sits inside the retry loop so each attempt re-executes it (e.g. re-reads a refreshed bearer token). Only one auth layer can be set; a second call replaces the first.

pub fn buffer_capacity(self, capacity: usize) -> Self

Set the buffer capacity for concurrent request handling

The HTTP client uses an internal buffer to allow concurrent requests without external locking. This sets the maximum number of requests that can be queued.

Note: A capacity of 0 is invalid and will be clamped to 1. Tower’s Buffer panics with capacity=0, so we enforce minimum of 1.

pub fn max_redirects(self, max_redirects: usize) -> Self

Set the maximum number of redirects to follow

Set to 0 to disable redirect following (3xx responses pass through as-is). Default: 10

pub fn no_redirects(self) -> Self

Disable redirect following

Equivalent to .max_redirects(0). When disabled, 3xx responses are returned to the caller without following the Location header.

pub fn redirect(self, config: RedirectConfig) -> Self

Set the redirect policy configuration

Use this to configure redirect security settings:

• same_origin_only: Only follow redirects to the same host
• strip_sensitive_headers: Remove Authorization/Cookie on cross-origin
• allow_https_downgrade: Allow HTTPS → HTTP redirects (not recommended)

Example

let client = HttpClient::builder()
    .redirect(RedirectConfig::permissive()) // Allow all redirects with header stripping
    .build()?;

pub fn pool_idle_timeout(self, timeout: Option<Duration>) -> Self

Set the idle connection timeout for the connection pool

Connections that remain idle for longer than this duration will be closed and removed from the pool. Default: 90 seconds.

Set to None to disable idle timeout (connections kept indefinitely).

pub fn pool_max_idle_per_host(self, max: usize) -> Self

Set the maximum number of idle connections per host

Limits how many idle connections are kept in the pool for each host. Default: 32.

• Setting to 0 disables connection reuse entirely
• Setting too high may waste resources on rarely-used connections

pub fn build(self) -> Result<HttpClient, HttpError>

Build the HTTP client with all configured layers

Errors

Returns an error if TLS initialization fails or configuration is invalid

Trait Implementations

impl Default for HttpClientBuilder

fn default() -> Self

Returns the “default value” for a type.