Skip to main content

ClientBuilder

Struct ClientBuilder 

Source
pub struct ClientBuilder { /* private fields */ }
Expand description

Builder for configuring a Client.

Implementations§

Source§

impl ClientBuilder

Source

pub fn new() -> Self

Create a new client builder with defaults.

Source

pub fn default_header(self, name: &str, value: &str) -> Result<Self>

Add a default header to all requests made by this client.

§Errors

Returns an error if name or value is not a valid header field.

Source

pub fn default_headers(self, headers: Headers) -> Self

Set the default headers for all requests made by this client.

This preserves valid header values containing HTTP obs-text bytes.

Source

pub fn user_agent(self, agent: &str) -> Self

Set the default user-agent header.

Source

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

Set the maximum number of idle (unused) connections kept per host.

This is a convenience alias for max_idle_connections_per_host: the transport enforces the limit on a per-host basis, so total idle connections grow with the number of distinct origins. Use max_connections for a global concurrency cap.

Source

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

Set the maximum number of idle connections per individual host.

Source

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

Set the maximum total number of concurrent in-flight requests.

Compatibility alias for Self::max_in_flight_requests kept for the pre-1.0 line. One permit equals one logical request, not one TCP connection (H2/H3 multiplex many requests over one connection). Prefer max_in_flight_requests in new code.

Source

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

Set the maximum number of concurrent in-flight requests per origin.

Compatibility alias for Self::max_in_flight_requests_per_origin.

Source

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

Set the maximum total number of concurrent in-flight requests.

Preferred native name. Bounds logical request concurrency (one permit per request). Under H1 one request typically owns its connection slot; under H2/H3 many permits multiplex over one TCP/QUIC connection. When both this and max_connections are set, this wins.

Source

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

Set the maximum number of concurrent in-flight requests per origin.

Preferred native name. When both this and max_connections_per_host are set, this wins.

Source

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

Set the duration after which idle connections are closed.

Source

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

Set the default timeout for all requests made by this client.

Source

pub fn merge_timeout(self, timeout: Timeout) -> Self

Merge a partial timeout configuration into the currently configured timeout.

Unlike timeout, which replaces the entire configuration, each phase set in timeout overrides only that phase; unset phases keep any previously configured value (or remain unset when no timeout was configured yet).

Source

pub fn limits(self, limits: Limits) -> Self

Set resource limits for the connection pool.

Limits control logical request concurrency (pool permits) and physical connection behavior (idle connection caps and expiry). When set, the limits are applied to the pool configuration.

Source

pub fn follow_redirects(self, follow: bool) -> Self

Set the redirect policy for this client.

Only available with the redirects feature (enabled by the http1/http2 compatibility aliases). The lean profile omits redirect following and returns 3xx responses without a second hop.

Source

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

Set the maximum number of redirects to follow.

Only available with the redirects feature.

Source

pub fn redirect_policy(self, policy: RedirectPolicy) -> Self

Set the full redirect policy.

Only available with the redirects feature.

Source

pub fn redirect_downgrade_policy(self, policy: RedirectDowngradePolicy) -> Self

Set the HTTPS-downgrade rule for redirects without replacing the rest of the redirect policy.

Only available with the redirects feature.

Select RedirectDowngradePolicy::Deny to reject HTTPS -> HTTP downgrades before the downgraded request is dispatched. The default is Allow for compatibility.

Source

pub fn auth(self, auth: impl Into<AuthScheme>) -> Self

Set default authentication for all requests made by this client.

The configured auth is applied to every request unless overridden or disabled at the request level. Auth is recomputed per redirect hop; cross-origin redirects never carry client auth.

Source

pub fn tls_config(self, config: TlsConfig) -> Self

Set a custom TLS configuration for this client.

When set, the client uses the provided crate::tls::TlsConfig for all TLS connections instead of the default native-root-with-WebPKI-fallback strategy (or the packaged-WebPKI default when tls-native-roots is not enabled).

Source

pub fn danger_accept_invalid_certs(self, accept: bool) -> Self

Enable or disable insecure TLS verification while retaining other TLS configuration already applied to this builder.

Source

pub fn automatic_decompression(self, enabled: bool) -> Self

Enable or disable automatic response decompression.

When enabled (the default), the client sends an Accept-Encoding header and transparently decompresses response bodies. Decoded Content-Encoding and Content-Length headers are removed from the response.

Can be overridden per-request via RequestBuilder::decompress.

Source

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

Set the maximum decoded response body size in bytes.

The limit applies to bytes made available after decoding and also to ordinary unencoded/identity response bodies, in both buffered and streaming paths. Exceeding it produces Error::DecodedBodyTooLarge without requiring a second caller-side accumulation loop. A wire Content-Length may be used for an early metadata check, but this body limit remains authoritative when the header is absent, incorrect, or describes encoded bytes.

Source

pub fn max_decompression_ratio(self, ratio: f64) -> Self

Set the maximum decompression ratio (decoded bytes / compressed bytes). When set, responses whose expansion ratio exceeds this limit produce an error. This guards against zip-bomb style attacks.

§Panics

Panics if ratio is not finite or not positive.

Source

pub fn retry(self, policy: RetryPolicy) -> Self

Set the retry policy for this client.

Only available with the logical-retry feature (enabled by the http1/http2 compatibility aliases). The lean profile dispatches once under the outer total deadline with no retry backoff/jitter/status policy.

When set, failed requests that match the policy (safe methods, retryable statuses/errors, replayable bodies) are automatically retried with exponential backoff.

Source

pub fn retry_canceled_requests(self, enabled: bool) -> Self

Allow or disallow Hyper’s implicit retry when a reused idle connection is found unusable before a request starts writing.

This is separate from eggfetch’s explicit logical retry (the logical-retry feature and RetryPolicy). The default is true, preserving Hyper’s existing behavior.

Source

pub fn dialer<D>(self, dialer: D) -> Self
where D: Dialer,

Install a client-scoped caller-owned raw-stream dialer.

Eggfetch continues to own HTTP framing, destination TLS, SNI, certificate verification, redirects, retries, and response bodies. The dialer is incompatible with built-in proxy, UDS, resolved-target, local-address, and socket-option routing; those combinations fail closed before network I/O.

Only available with the advanced-routing feature (enabled by the native-http1/native-http2 compatibility slices). The lean standard-route profile omits custom dialing.

Source

pub fn physical_connection_policy( self, policy: PhysicalConnectionPolicy, ) -> Self

Install a shared caller-scoped live physical-connection policy.

This controls established Hyper connections, including idle pooled connections. It does not change the logical request limits in PoolConfig. A max_live value of zero fails requests closed because no useful client can be created from it.

Source

pub fn transport_io_timeout(self, timeout: TransportIoTimeout) -> Self

Install established-transport read/write inactivity guardrails.

These timers are distinct from Timeout’s request body and response-stream semantics and are disabled by default.

Source

pub fn http_version_policy(self, policy: HttpVersionPolicy) -> Self

Set the HTTP version policy for this client.

Controls which HTTP protocol versions the client may negotiate. The default is HttpVersionPolicy::Auto, which allows HTTP/2 negotiation via ALPN when the http2 feature is enabled.

When the http2 feature is not compiled in, Http2Only and Auto are silently downgraded to Http1Only.

Source

pub fn local_address(self, addr: SocketAddr) -> Self

Set a local address to bind outbound sockets to before connecting.

When set, all direct (non-proxy, non-UDS) connections will bind to the specified local address before connecting to the remote. This uses a custom connector path instead of the standard hyper-rustls connector.

Only available with advanced-routing; omitted by the lean profile.

Source

pub fn socket_options(self, options: Vec<SocketOption>) -> Self

Set socket options to apply to outbound TCP connections.

Options are applied to the socket before the connect operation. Recognized options are applied via tokio::net::TcpSocket setters; unrecognized options produce a connection error (never silently ignored, per the plan’s Track 2.4 requirement).

Only available with advanced-routing; omitted by the lean profile.

Source

pub fn uds_path(self, path: String) -> Self

Set a Unix domain socket path for all connections.

When set, all requests are routed through the specified UDS path instead of making TCP connections. The URL in the request still provides HTTP scheme/authority/path semantics.

Only supported on Unix platforms. On non-Unix platforms, this option is accepted but will produce an error at request time.

Only available with advanced-routing; omitted by the lean profile.

Source

pub fn build(self) -> Client

Build the client.

Native system roots are preferred. If the platform root store is unavailable, the client falls back to the packaged Mozilla root set while retaining certificate and hostname verification.

Trait Implementations§

Source§

impl Default for ClientBuilder

Source§

fn default() -> Self

Returns the “default value” for a type. Read more

Auto Trait Implementations§

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T> Instrument for T

Source§

fn instrument(self, span: Span) -> Instrumented<Self> ⓘ

Instruments this type with the provided Span, returning an Instrumented wrapper. Read more
Source§

fn in_current_span(self) -> Instrumented<Self> ⓘ

Instruments this type with the current Span, returning an Instrumented wrapper. Read more
Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = !

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, !>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
Source§

impl<T> WithSubscriber for T

Source§

fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self> ⓘ
where S: Into<Dispatch>,

Attaches the provided Subscriber to this type, returning a WithDispatch wrapper. Read more
Source§

fn with_current_subscriber(self) -> WithDispatch<Self> ⓘ

Attaches the current default Subscriber to this type, returning a WithDispatch wrapper. Read more