Struct reqwest::ClientBuilder

pub struct ClientBuilder { /* private fields */ }

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

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 a TLS backend cannot be initialized, or the resolver cannot load the system configuration.

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::Client::builder()
    .user_agent(APP_USER_AGENT)
    .build()?;
let res = client.get("https://www.rust-lang.org").send().await?;

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"));

// 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::Client::builder()
    .default_headers(headers)
    .build()?;
let res = client.get("https://www.rust-lang.org").send().await?;

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 RedirectPolicy 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 crate::proxy::Proxy::no_proxy() on all desired proxies instead.

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

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

Enables a total request timeout.

The timeout is applied from when the request starts connecting until the response body has finished. Also considered a total deadline.

Default is no timeout.

pub fn read_timeout(self, timeout: Duration) -> ClientBuilder

Enables a read timeout.

The timeout applies to each read operation, and resets after a successful read. This is more appropriate for detecting stalled connections when the size isn’t known beforehand.

Default is no timeout.

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

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

Default is None.

Note

This requires the futures be executed in a tokio runtime with a tokio timer enabled.

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 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::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::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 https_only(self, enabled: bool) -> ClientBuilder

Restrict the Client to be used with HTTPS only requests.

Defaults to false.

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

If configured, the connect_timeout will be the outermost layer.

Example usage:

use std::time::Duration;

let client = reqwest::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.