Struct HttpClientConfig 

pub struct HttpClientConfig {

    pub request_timeout: Duration,
    pub total_timeout: Option<Duration>,
    pub max_body_size: usize,
    pub user_agent: String,
    pub retry: Option<RetryConfig>,
    pub rate_limit: Option<RateLimitConfig>,
    pub transport: TransportSecurity,
    pub tls_roots: TlsRootConfig,
    pub otel: bool,
    pub buffer_capacity: usize,
    pub redirect: RedirectConfig,
    pub pool_idle_timeout: Option<Duration>,
    pub pool_max_idle_per_host: usize,
}

Overall HTTP client configuration

Fields

request_timeout: Duration

Per-request timeout (default: 30 seconds)

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

total_timeout: Option<Duration>

Total timeout spanning all retry attempts (default: None)

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).

When None, there is no total deadline - each attempt can take up to request_timeout, and retries can continue indefinitely within their limits.

max_body_size: usize

Maximum response body size in bytes (default: 10 MB)

user_agent: String

User-Agent header value (default: “modkit-http/1.0”)

retry: Option<RetryConfig>

Retry policy configuration

rate_limit: Option<RateLimitConfig>

Rate limiting / concurrency configuration

transport: TransportSecurity

Transport security mode (default: TlsOnly)

Use AllowInsecureHttp only for testing with local mock servers.

tls_roots: TlsRootConfig

TLS root certificate strategy (default: WebPki)

otel: bool

Enable OpenTelemetry tracing layer (default: false) Creates spans for outbound requests and injects trace context headers.

buffer_capacity: usize

Buffer capacity for concurrent request handling (default: 1024)

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

redirect: RedirectConfig

Redirect policy configuration (default: same-origin only with header stripping)

Controls how 3xx redirect responses are handled with security protections:

• Same-origin enforcement (SSRF protection)
• Sensitive header stripping on cross-origin redirects
• HTTPS downgrade protection

Use RedirectConfig::permissive() for general-purpose HTTP client behavior that allows cross-origin redirects with header stripping.

Use RedirectConfig::disabled() to turn off redirect following entirely.

pool_idle_timeout: Option<Duration>

Timeout for idle connections in the pool (default: 90 seconds)

Connections that remain idle (unused) for longer than this duration will be closed and removed from the pool. This prevents resource leaks and ensures connections don’t become stale.

Set to None to use hyper-util’s default idle timeout.

pool_max_idle_per_host: usize

Maximum number of idle connections per host (default: 32)

Limits how many idle connections are kept in the pool for each host. Setting this to 0 disables connection reuse entirely. Setting this too high may waste resources on rarely-used connections.

Note: This only limits idle connections. Active connections are not limited by this setting.

Implementations

impl HttpClientConfig

pub fn minimal() -> Self

Create minimal configuration (no retry, no rate limit, small timeout)

pub fn infra_default() -> Self

Create configuration for infrastructure services (aggressive retry, large timeout)

pub fn token_endpoint() -> Self

Create configuration for OAuth2 token endpoints (conservative retry)

Token endpoints use POST but are effectively idempotent for retry purposes:

• Getting a token twice is safe (you’d just use the second one)
• Transport errors before response mean no token was issued

This config retries on transport errors, timeout, and 429 for all methods.

pub fn for_testing() -> Self

Create configuration for testing with mock servers (allows insecure HTTP)

WARNING: This configuration allows plain HTTP connections. Use only for local testing with mock servers, never in production.

pub fn sse() -> Self

Create configuration optimized for Server-Sent Events (SSE) streaming.

SSE connections are long-lived HTTP requests where the server holds the connection open and pushes events. This preset disables retry and rate limiting, and sets a permissive request timeout.

Timeout behavior

request_timeout is set to 24 hours rather than truly unlimited, because TimeoutLayer requires a finite Duration. Override if needed:

let mut config = HttpClientConfig::sse();
config.request_timeout = Duration::from_secs(3600); // 1 hour
let client = HttpClientBuilder::with_config(config).build()?;

Streaming

Use [HttpResponse::into_body()] for streaming — it bypasses the max_body_size limit. SSE reconnection with Last-Event-ID is the caller’s responsibility.

let client = HttpClientBuilder::with_config(HttpClientConfig::sse()).build()?;

let response = client
    .get("https://api.example.com/events")
    .header("accept", "text/event-stream")
    .send()
    .await?;

let mut body = response.into_body();
while let Some(frame) = body.frame().await {
    let frame = frame?;
    if let Some(chunk) = frame.data_ref() {
        // parse SSE event data
    }
}

Trait Implementations

impl Clone for HttpClientConfig

fn clone(&self) -> HttpClientConfig

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for HttpClientConfig

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for HttpClientConfig

fn default() -> Self

Returns the “default value” for a type.