Struct ClientBuilder

pub struct ClientBuilder { /* private fields */ }

A ClientBuilder can be used to create a Client with custom configuration.

Example

use std::time::Duration;

let client = reqwest::blocking::Client::builder()
    .timeout(Duration::from_secs(10))
    .build()?;

Implementations

impl ClientBuilder

pub fn new() -> Self

Constructs a new ClientBuilder.

This is the same as Client::builder().

impl ClientBuilder

pub fn build(self) -> Result<Client>

Returns a Client that uses this ClientBuilder configuration.

Errors

This method fails if TLS backend cannot be initialized, or the resolver cannot load the system configuration.

Panics

This method panics if called from within an async runtime. See docs on reqwest::blocking for details.

pub fn user_agent<V>(self, value: V) -> ClientBuilder

where V: TryInto<HeaderValue>, V::Error: Into<Error>,

Sets the User-Agent header to be used by this client.

Example

// Name your user agent after your app?
static APP_USER_AGENT: &str = concat!(
    env!("CARGO_PKG_NAME"),
    "/",
    env!("CARGO_PKG_VERSION"),
);

let client = reqwest::blocking::Client::builder()
    .user_agent(APP_USER_AGENT)
    .build()?;
let res = client.get("https://www.rust-lang.org").send()?;

pub fn default_headers(self, headers: HeaderMap) -> ClientBuilder

Sets the default headers for every request.

Example

use reqwest::header;
let mut headers = header::HeaderMap::new();
headers.insert("X-MY-HEADER", header::HeaderValue::from_static("value"));
headers.insert(header::AUTHORIZATION, header::HeaderValue::from_static("secret"));

// Consider marking security-sensitive headers with `set_sensitive`.
let mut auth_value = header::HeaderValue::from_static("secret");
auth_value.set_sensitive(true);
headers.insert(header::AUTHORIZATION, auth_value);

// get a client builder
let client = reqwest::blocking::Client::builder()
    .default_headers(headers)
    .build()?;
let res = client.get("https://www.rust-lang.org").send()?;

pub fn cookie_store(self, enable: bool) -> ClientBuilder

Available on crate feature cookies only.

Enable a persistent cookie store for the client.

Cookies received in responses will be preserved and included in additional requests.

By default, no cookie store is used.

Optional

This requires the optional cookies feature to be enabled.

pub fn cookie_provider<C: CookieStore + 'static>( self, cookie_store: Arc<C>, ) -> ClientBuilder

Available on crate feature cookies only.

Set the persistent cookie store for the client.

Cookies received in responses will be passed to this store, and additional requests will query this store for cookies.

By default, no cookie store is used.

Optional

This requires the optional cookies feature to be enabled.

pub fn gzip(self, enable: bool) -> ClientBuilder

Available on crate feature gzip only.

Enable auto gzip decompression by checking the Content-Encoding response header.

If auto gzip decompression is turned on:

• When sending a request and if the request’s headers do not already contain an Accept-Encoding and Range values, the Accept-Encoding header is set to gzip. The request body is not automatically compressed.
• When receiving a response, if it’s headers contain a Content-Encoding value that equals to gzip, both values Content-Encoding and Content-Length are removed from the headers’ set. The response body is automatically decompressed.

If the gzip feature is turned on, the default option is enabled.

Optional

This requires the optional gzip feature to be enabled

pub fn brotli(self, enable: bool) -> ClientBuilder

Available on crate feature brotli only.

Enable auto brotli decompression by checking the Content-Encoding response header.

If auto brotli decompression is turned on:

• When sending a request and if the request’s headers do not already contain an Accept-Encoding and Range values, the Accept-Encoding header is set to br. The request body is not automatically compressed.
• When receiving a response, if it’s headers contain a Content-Encoding value that equals to br, both values Content-Encoding and Content-Length are removed from the headers’ set. The response body is automatically decompressed.

If the brotli feature is turned on, the default option is enabled.

Optional

This requires the optional brotli feature to be enabled

pub fn zstd(self, enable: bool) -> ClientBuilder

Available on crate feature zstd only.

Enable auto zstd decompression by checking the Content-Encoding response header.

If auto zstd decompression is turned on:

• When sending a request and if the request’s headers do not already contain an Accept-Encoding and Range values, the Accept-Encoding header is set to zstd. The request body is not automatically compressed.
• When receiving a response, if its headers contain a Content-Encoding value of zstd, both Content-Encoding and Content-Length are removed from the headers’ set. The response body is automatically decompressed.

If the zstd feature is turned on, the default option is enabled.

Optional

This requires the optional zstd feature to be enabled

pub fn deflate(self, enable: bool) -> ClientBuilder

Available on crate feature deflate only.

Enable auto deflate decompression by checking the Content-Encoding response header.

If auto deflate decompression is turned on:

• When sending a request and if the request’s headers do not already contain an Accept-Encoding and Range values, the Accept-Encoding header is set to deflate. The request body is not automatically compressed.
• When receiving a response, if it’s headers contain a Content-Encoding value that equals to deflate, both values Content-Encoding and Content-Length are removed from the headers’ set. The response body is automatically decompressed.

If the deflate feature is turned on, the default option is enabled.

Optional

This requires the optional deflate feature to be enabled

pub fn no_gzip(self) -> ClientBuilder

Disable auto response body gzip decompression.

This method exists even if the optional gzip feature is not enabled. This can be used to ensure a Client doesn’t use gzip decompression even if another dependency were to enable the optional gzip feature.

pub fn no_brotli(self) -> ClientBuilder

Disable auto response body brotli decompression.

This method exists even if the optional brotli feature is not enabled. This can be used to ensure a Client doesn’t use brotli decompression even if another dependency were to enable the optional brotli feature.

pub fn no_zstd(self) -> ClientBuilder

Disable auto response body zstd decompression.

This method exists even if the optional zstd feature is not enabled. This can be used to ensure a Client doesn’t use zstd decompression even if another dependency were to enable the optional zstd feature.

pub fn no_deflate(self) -> ClientBuilder

Disable auto response body deflate decompression.

This method exists even if the optional deflate feature is not enabled. This can be used to ensure a Client doesn’t use deflate decompression even if another dependency were to enable the optional deflate feature.

pub fn redirect(self, policy: Policy) -> ClientBuilder

Set a redirect::Policy for this client.

Default will follow redirects up to a maximum of 10.

pub fn referer(self, enable: bool) -> ClientBuilder

Enable or disable automatic setting of the Referer header.

Default is true.

pub fn proxy(self, proxy: Proxy) -> ClientBuilder

Add a Proxy to the list of proxies the Client will use.

Note

Adding a proxy will disable the automatic usage of the “system” proxy.

pub fn no_proxy(self) -> ClientBuilder

Clear all Proxies, so Client will use no proxy anymore.

Note

To add a proxy exclusion list, use Proxy::no_proxy() on all desired proxies instead.

This also disables the automatic usage of the “system” proxy.

pub fn timeout<T>(self, timeout: T) -> ClientBuilder

where T: Into<Option<Duration>>,

Set a timeout for connect, read and write operations of a Client.

Default is 30 seconds.

Pass None to disable timeout.

pub fn connect_timeout<T>(self, timeout: T) -> ClientBuilder

where T: Into<Option<Duration>>,

Set a timeout for only the connect phase of a Client.

Default is None.

pub fn connection_verbose(self, verbose: bool) -> ClientBuilder

Set whether connections should emit verbose logs.

Enabling this option will emit log messages at the TRACE level for read and write operations on connections.

pub fn pool_idle_timeout<D>(self, val: D) -> ClientBuilder

where D: Into<Option<Duration>>,

Set an optional timeout for idle sockets being kept-alive.

Pass None to disable timeout.

Default is 90 seconds.

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

Sets the maximum idle connection per host allowed in the pool.

pub fn http1_title_case_headers(self) -> ClientBuilder

Send headers as title case instead of lowercase.

pub fn http1_allow_obsolete_multiline_headers_in_responses( self, value: bool, ) -> ClientBuilder

Set whether HTTP/1 connections will accept obsolete line folding for header values.

Newline codepoints (\r and \n) will be transformed to spaces when parsing.

pub fn http1_ignore_invalid_headers_in_responses( self, value: bool, ) -> ClientBuilder

Sets whether invalid header lines should be silently ignored in HTTP/1 responses.

pub fn http1_allow_spaces_after_header_name_in_responses( self, value: bool, ) -> ClientBuilder

Set whether HTTP/1 connections will accept spaces between header names and the colon that follow them in responses.

Newline codepoints (\r and \n) will be transformed to spaces when parsing.

pub fn http1_only(self) -> ClientBuilder

Only use HTTP/1.

pub fn http09_responses(self) -> ClientBuilder

Allow HTTP/0.9 responses

pub fn http2_prior_knowledge(self) -> ClientBuilder

Available on crate feature http2 only.

Only use HTTP/2.

pub fn http2_initial_stream_window_size( self, sz: impl Into<Option<u32>>, ) -> ClientBuilder

Available on crate feature http2 only.

Sets the SETTINGS_INITIAL_WINDOW_SIZE option for HTTP2 stream-level flow control.

Default is currently 65,535 but may change internally to optimize for common uses.

pub fn http2_initial_connection_window_size( self, sz: impl Into<Option<u32>>, ) -> ClientBuilder

Available on crate feature http2 only.

Sets the max connection-level flow control for HTTP2

Default is currently 65,535 but may change internally to optimize for common uses.

pub fn http2_adaptive_window(self, enabled: bool) -> ClientBuilder

Available on crate feature http2 only.

Sets whether to use an adaptive flow control.

Enabling this will override the limits set in http2_initial_stream_window_size and http2_initial_connection_window_size.

pub fn http2_max_frame_size(self, sz: impl Into<Option<u32>>) -> ClientBuilder

Available on crate feature http2 only.

Sets the maximum frame size to use for HTTP2.

Default is currently 16,384 but may change internally to optimize for common uses.

pub fn http2_max_header_list_size( self, max_header_size_bytes: u32, ) -> ClientBuilder

Available on crate feature http2 only.

Sets the maximum size of received header frames for HTTP2.

Default is currently 16KB, but can change.

pub fn http3_prior_knowledge(self) -> ClientBuilder

Available on crate feature http3 only.

This requires the optional http3 feature to be enabled.

pub fn tcp_nodelay(self, enabled: bool) -> ClientBuilder

Set whether sockets have TCP_NODELAY enabled.

Default is true.

pub fn local_address<T>(self, addr: T) -> ClientBuilder

where T: Into<Option<IpAddr>>,

Bind to a local IP Address.

Example

use std::net::IpAddr;
let local_addr = IpAddr::from([12, 4, 1, 8]);
let client = reqwest::blocking::Client::builder()
    .local_address(local_addr)
    .build().unwrap();

pub fn interface(self, interface: &str) -> ClientBuilder

Bind to an interface by SO_BINDTODEVICE.

Example

let interface = "lo";
let client = reqwest::blocking::Client::builder()
    .interface(interface)
    .build().unwrap();

pub fn tcp_keepalive<D>(self, val: D) -> ClientBuilder

where D: Into<Option<Duration>>,

Set that all sockets have SO_KEEPALIVE set with the supplied duration.

If None, the option will not be set.

pub fn add_root_certificate(self, cert: Certificate) -> ClientBuilder

Available on crate features default-tls or native-tls or rustls-tls only.

Add a custom root certificate.

This allows connecting to a server that has a self-signed certificate for example. This does not replace the existing trusted store.

Example

// read a local binary DER encoded certificate
let der = std::fs::read("my-cert.der")?;

// create a certificate
let cert = reqwest::Certificate::from_der(&der)?;

// get a client builder
let client = reqwest::blocking::Client::builder()
    .add_root_certificate(cert)
    .build()?;

Optional

This requires the optional default-tls, native-tls, or rustls-tls(-...) feature to be enabled.

pub fn add_crl(self, crl: CertificateRevocationList) -> ClientBuilder

Available on crate feature rustls-tls only.

Add a certificate revocation list.

Optional

This requires the rustls-tls(-...) Cargo feature enabled.

pub fn add_crls( self, crls: impl IntoIterator<Item = CertificateRevocationList>, ) -> ClientBuilder

Available on crate feature rustls-tls only.

Add multiple certificate revocation lists.

Optional

This requires the rustls-tls(-...) Cargo feature enabled.

pub fn tls_built_in_root_certs( self, tls_built_in_root_certs: bool, ) -> ClientBuilder

Available on crate features default-tls or native-tls or rustls-tls only.

Controls the use of built-in system certificates during certificate validation.

Defaults to true – built-in system certs will be used.

Optional

This requires the optional default-tls, native-tls, or rustls-tls(-...) feature to be enabled.

pub fn tls_built_in_webpki_certs(self, enabled: bool) -> ClientBuilder

Available on crate feature rustls-tls-webpki-roots-no-provider only.

Sets whether to load webpki root certs with rustls.

If the feature is enabled, this value is true by default.

pub fn tls_built_in_native_certs(self, enabled: bool) -> ClientBuilder

Available on crate feature rustls-tls-native-roots-no-provider only.

Sets whether to load native root certs with rustls.

If the feature is enabled, this value is true by default.

pub fn identity(self, identity: Identity) -> ClientBuilder

Available on crate features native-tls or rustls-tls only.

Sets the identity to be used for client certificate authentication.

Optional

This requires the optional native-tls or rustls-tls(-...) feature to be enabled.

pub fn danger_accept_invalid_hostnames( self, accept_invalid_hostname: bool, ) -> ClientBuilder

Available on crate features default-tls or native-tls or rustls-tls only.

Controls the use of hostname verification.

Defaults to false.

Warning

You should think very carefully before you use this method. If hostname verification is not used, any valid certificate for any site will be trusted for use from any other. This introduces a significant vulnerability to man-in-the-middle attacks.

Optional

This requires the optional default-tls, native-tls, or rustls-tls(-...) feature to be enabled.

pub fn danger_accept_invalid_certs( self, accept_invalid_certs: bool, ) -> ClientBuilder

Available on crate features default-tls or native-tls or rustls-tls only.

Controls the use of certificate validation.

Defaults to false.

Warning

You should think very carefully before using this method. If invalid certificates are trusted, any certificate for any site will be trusted for use. This includes expired certificates. This introduces significant vulnerabilities, and should only be used as a last resort.

pub fn tls_sni(self, tls_sni: bool) -> ClientBuilder

Available on crate features default-tls or native-tls or rustls-tls only.

Controls the use of TLS server name indication.

Defaults to true.

pub fn min_tls_version(self, version: Version) -> ClientBuilder

Available on crate features default-tls or native-tls or rustls-tls only.

Set the minimum required TLS version for connections.

By default, the TLS backend’s own default is used.

Errors

A value of tls::Version::TLS_1_3 will cause an error with the native-tls/default-tls backend. This does not mean the version isn’t supported, just that it can’t be set as a minimum due to technical limitations.

Optional

This requires the optional default-tls, native-tls, or rustls-tls(-...) feature to be enabled.

pub fn max_tls_version(self, version: Version) -> ClientBuilder

Available on crate features default-tls or native-tls or rustls-tls only.

Set the maximum allowed TLS version for connections.

By default, there’s no maximum.

Errors

A value of tls::Version::TLS_1_3 will cause an error with the native-tls/default-tls backend. This does not mean the version isn’t supported, just that it can’t be set as a maximum due to technical limitations.

Optional

This requires the optional default-tls, native-tls, or rustls-tls(-...) feature to be enabled.

pub fn use_native_tls(self) -> ClientBuilder

Available on crate feature native-tls only.

Force using the native TLS backend.

Since multiple TLS backends can be optionally enabled, this option will force the native-tls backend to be used for this Client.

Optional

This requires the optional native-tls feature to be enabled.

pub fn use_rustls_tls(self) -> ClientBuilder

Available on crate feature rustls-tls only.

Force using the Rustls TLS backend.

Since multiple TLS backends can be optionally enabled, this option will force the rustls backend to be used for this Client.

Optional

This requires the optional rustls-tls(-...) feature to be enabled.

pub fn tls_info(self, tls_info: bool) -> ClientBuilder

Available on crate features default-tls or native-tls or rustls-tls only.

Add TLS information as TlsInfo extension to responses.

Optional

This requires the optional default-tls, native-tls, or rustls-tls(-...) feature to be enabled.

pub fn use_preconfigured_tls(self, tls: impl Any) -> ClientBuilder

Available on crate features native-tls or rustls-tls only.

Use a preconfigured TLS backend.

If the passed Any argument is not a TLS backend that reqwest understands, the ClientBuilder will error when calling build.

Advanced

This is an advanced option, and can be somewhat brittle. Usage requires keeping the preconfigured TLS argument version in sync with reqwest, since version mismatches will result in an “unknown” TLS backend.

If possible, it’s preferable to use the methods on ClientBuilder to configure reqwest’s TLS.

Optional

This requires one of the optional features native-tls or rustls-tls(-...) to be enabled.

pub fn trust_dns(self, enable: bool) -> ClientBuilder

👎Deprecated since 0.12.0: use hickory_dns instead

Available on crate feature hickory-dns only.

Enables the hickory-dns async resolver instead of a default threadpool using getaddrinfo.

If the hickory-dns feature is turned on, the default option is enabled.

Optional

This requires the optional hickory-dns feature to be enabled

pub fn hickory_dns(self, enable: bool) -> ClientBuilder

Available on crate feature hickory-dns only.

Enables the hickory-dns async resolver instead of a default threadpool using getaddrinfo.

If the hickory-dns feature is turned on, the default option is enabled.

Optional

This requires the optional hickory-dns feature to be enabled

pub fn no_trust_dns(self) -> ClientBuilder

👎Deprecated since 0.12.0: use no_hickory_dns instead

Disables the hickory-dns async resolver.

This method exists even if the optional hickory-dns feature is not enabled. This can be used to ensure a Client doesn’t use the hickory-dns async resolver even if another dependency were to enable the optional hickory-dns feature.

pub fn no_hickory_dns(self) -> ClientBuilder

Disables the hickory-dns async resolver.

This method exists even if the optional hickory-dns feature is not enabled. This can be used to ensure a Client doesn’t use the hickory-dns async resolver even if another dependency were to enable the optional hickory-dns feature.

pub fn https_only(self, enabled: bool) -> ClientBuilder

Restrict the Client to be used with HTTPS only requests.

Defaults to false.

pub fn resolve(self, domain: &str, addr: SocketAddr) -> ClientBuilder

Override DNS resolution for specific domains to a particular IP address.

Set the port to 0 to use the conventional port for the given scheme (e.g. 80 for http). Ports in the URL itself will always be used instead of the port in the overridden addr.

pub fn resolve_to_addrs( self, domain: &str, addrs: &[SocketAddr], ) -> ClientBuilder

Override DNS resolution for specific domains to particular IP addresses.

Set the port to 0 to use the conventional port for the given scheme (e.g. 80 for http). Ports in the URL itself will always be used instead of the port in the overridden addr.

pub fn dns_resolver<R: Resolve + 'static>( self, resolver: Arc<R>, ) -> ClientBuilder

Override the DNS resolver implementation.

Pass an Arc wrapping a trait object implementing Resolve. Overrides for specific names passed to resolve and resolve_to_addrs will still be applied on top of this resolver.

pub fn connector_layer<L>(self, layer: L) -> ClientBuilder

where L: Layer<BoxCloneSyncService<Unnameable, Conn, Box<dyn StdError + Send + Sync>>> + Clone + Send + Sync + 'static, L::Service: Service<Unnameable, Response = Conn, Error = Box<dyn StdError + Send + Sync>> + Clone + Send + Sync + 'static, <L::Service as Service<Unnameable>>::Future: Send + 'static,

Adds a new Tower Layer to the base connector Service which is responsible for connection establishment.

Each subsequent invocation of this function will wrap previous layers.

Example usage:

use std::time::Duration;

let client = reqwest::blocking::Client::builder()
                     // resolved to outermost layer, meaning while we are waiting on concurrency limit
                     .connect_timeout(Duration::from_millis(200))
                     // underneath the concurrency check, so only after concurrency limit lets us through
                     .connector_layer(tower::timeout::TimeoutLayer::new(Duration::from_millis(50)))
                     .connector_layer(tower::limit::concurrency::ConcurrencyLimitLayer::new(2))
                     .build()
                     .unwrap();

Trait Implementations

impl Debug for ClientBuilder

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

Formats the value using the given formatter.

impl Default for ClientBuilder

fn default() -> Self

Returns the “default value” for a type.

impl From<ClientBuilder> for ClientBuilder

fn from(builder: ClientBuilder) -> Self

Converts to this type from the input type.