pub struct ClientBuilder { /* private fields */ }Expand description
Builder for configuring a Client.
Implementations§
Source§impl ClientBuilder
impl ClientBuilder
Sourcepub fn default_header(self, name: &str, value: &str) -> Result<Self>
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.
Sourcepub fn default_headers(self, headers: Headers) -> Self
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.
Sourcepub fn user_agent(self, agent: &str) -> Self
pub fn user_agent(self, agent: &str) -> Self
Set the default user-agent header.
Sourcepub fn max_idle_connections(self, max: usize) -> Self
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.
Sourcepub fn max_idle_connections_per_host(self, max: usize) -> Self
pub fn max_idle_connections_per_host(self, max: usize) -> Self
Set the maximum number of idle connections per individual host.
Sourcepub fn max_connections(self, max: usize) -> Self
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.
Sourcepub fn max_connections_per_host(self, max: usize) -> Self
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.
Sourcepub fn max_in_flight_requests(self, max: usize) -> Self
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.
Sourcepub fn max_in_flight_requests_per_origin(self, max: usize) -> Self
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.
Sourcepub fn idle_timeout(self, timeout: Duration) -> Self
pub fn idle_timeout(self, timeout: Duration) -> Self
Set the duration after which idle connections are closed.
Sourcepub fn timeout(self, timeout: Timeout) -> Self
pub fn timeout(self, timeout: Timeout) -> Self
Set the default timeout for all requests made by this client.
Sourcepub fn merge_timeout(self, timeout: Timeout) -> Self
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).
Sourcepub fn limits(self, limits: Limits) -> Self
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.
Sourcepub fn follow_redirects(self, follow: bool) -> Self
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.
Sourcepub fn max_redirects(self, max: usize) -> Self
pub fn max_redirects(self, max: usize) -> Self
Set the maximum number of redirects to follow.
Only available with the redirects feature.
Sourcepub fn redirect_policy(self, policy: RedirectPolicy) -> Self
pub fn redirect_policy(self, policy: RedirectPolicy) -> Self
Set the full redirect policy.
Only available with the redirects feature.
Sourcepub fn redirect_downgrade_policy(self, policy: RedirectDowngradePolicy) -> Self
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.
Sourcepub fn auth(self, auth: impl Into<AuthScheme>) -> Self
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.
Sourcepub fn tls_config(self, config: TlsConfig) -> Self
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).
Sourcepub fn danger_accept_invalid_certs(self, accept: bool) -> Self
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.
Sourcepub fn automatic_decompression(self, enabled: bool) -> Self
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.
Sourcepub fn max_decoded_body_size(self, max: usize) -> Self
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.
Sourcepub fn max_decompression_ratio(self, ratio: f64) -> Self
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.
Sourcepub fn retry(self, policy: RetryPolicy) -> Self
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.
Sourcepub fn retry_canceled_requests(self, enabled: bool) -> Self
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.
Sourcepub fn dialer<D>(self, dialer: D) -> Selfwhere
D: Dialer,
pub fn dialer<D>(self, dialer: D) -> Selfwhere
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.
Sourcepub fn physical_connection_policy(
self,
policy: PhysicalConnectionPolicy,
) -> Self
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.
Sourcepub fn transport_io_timeout(self, timeout: TransportIoTimeout) -> Self
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.
Sourcepub fn http_version_policy(self, policy: HttpVersionPolicy) -> Self
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.
Sourcepub fn local_address(self, addr: SocketAddr) -> Self
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.
Sourcepub fn socket_options(self, options: Vec<SocketOption>) -> Self
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.
Sourcepub fn uds_path(self, path: String) -> Self
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.