Struct reqwest::ClientBuilder
source · pub struct ClientBuilder { /* private fields */ }
Expand description
A ClientBuilder
can be used to create a Client
with custom configuration.
Implementations§
source§impl ClientBuilder
impl ClientBuilder
sourcepub fn new() -> ClientBuilder
pub fn new() -> ClientBuilder
Constructs a new ClientBuilder
.
This is the same as Client::builder()
.
sourcepub fn build(self) -> Result<Client>
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.
sourcepub fn user_agent<V>(self, value: V) -> ClientBuilder
pub fn user_agent<V>(self, value: V) -> ClientBuilder
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?;
sourcepub fn default_headers(self, headers: HeaderMap) -> ClientBuilder
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?;
sourcepub fn no_gzip(self) -> ClientBuilder
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.
sourcepub fn no_brotli(self) -> ClientBuilder
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.
sourcepub fn no_zstd(self) -> ClientBuilder
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.
sourcepub fn no_deflate(self) -> ClientBuilder
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.
sourcepub fn redirect(self, policy: Policy) -> ClientBuilder
pub fn redirect(self, policy: Policy) -> ClientBuilder
Set a RedirectPolicy
for this client.
Default will follow redirects up to a maximum of 10.
sourcepub fn referer(self, enable: bool) -> ClientBuilder
pub fn referer(self, enable: bool) -> ClientBuilder
Enable or disable automatic setting of the Referer
header.
Default is true
.
sourcepub fn proxy(self, proxy: Proxy) -> ClientBuilder
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.
sourcepub fn no_proxy(self) -> ClientBuilder
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.
sourcepub fn timeout(self, timeout: Duration) -> ClientBuilder
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.
sourcepub fn read_timeout(self, timeout: Duration) -> ClientBuilder
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.
sourcepub fn connect_timeout(self, timeout: Duration) -> ClientBuilder
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.
sourcepub fn connection_verbose(self, verbose: bool) -> ClientBuilder
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.
sourcepub fn pool_idle_timeout<D>(self, val: D) -> ClientBuilder
pub fn pool_idle_timeout<D>(self, val: D) -> ClientBuilder
Set an optional timeout for idle sockets being kept-alive.
Pass None
to disable timeout.
Default is 90 seconds.
sourcepub fn pool_max_idle_per_host(self, max: usize) -> ClientBuilder
pub fn pool_max_idle_per_host(self, max: usize) -> ClientBuilder
Sets the maximum idle connection per host allowed in the pool.
sourcepub fn http1_title_case_headers(self) -> ClientBuilder
pub fn http1_title_case_headers(self) -> ClientBuilder
Send headers as title case instead of lowercase.
sourcepub fn http1_allow_obsolete_multiline_headers_in_responses(
self,
value: bool,
) -> ClientBuilder
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.
sourcepub fn http1_ignore_invalid_headers_in_responses(
self,
value: bool,
) -> ClientBuilder
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.
sourcepub fn http1_allow_spaces_after_header_name_in_responses(
self,
value: bool,
) -> ClientBuilder
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.
sourcepub fn http1_only(self) -> ClientBuilder
pub fn http1_only(self) -> ClientBuilder
Only use HTTP/1.
sourcepub fn http09_responses(self) -> ClientBuilder
pub fn http09_responses(self) -> ClientBuilder
Allow HTTP/0.9 responses
sourcepub fn tcp_nodelay(self, enabled: bool) -> ClientBuilder
pub fn tcp_nodelay(self, enabled: bool) -> ClientBuilder
Set whether sockets have TCP_NODELAY
enabled.
Default is true
.
sourcepub fn local_address<T>(self, addr: T) -> ClientBuilder
pub fn local_address<T>(self, addr: T) -> ClientBuilder
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();
sourcepub fn interface(self, interface: &str) -> ClientBuilder
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();
sourcepub fn tcp_keepalive<D>(self, val: D) -> ClientBuilder
pub fn tcp_keepalive<D>(self, val: D) -> ClientBuilder
Set that all sockets have SO_KEEPALIVE
set with the supplied duration.
If None
, the option will not be set.
sourcepub fn add_root_certificate(self, cert: Certificate) -> ClientBuilder
pub fn add_root_certificate(self, cert: Certificate) -> ClientBuilder
Add a custom root certificate.
This can be used to connect to a server that has a self-signed certificate for example.
§Optional
This requires the optional default-tls
, native-tls
, or rustls-tls(-...)
feature to be enabled.
sourcepub fn add_crl(self, crl: CertificateRevocationList) -> ClientBuilder
pub fn add_crl(self, crl: CertificateRevocationList) -> ClientBuilder
Add a certificate revocation list.
§Optional
This requires the rustls-tls(-...)
Cargo feature enabled.
sourcepub fn add_crls(
self,
crls: impl IntoIterator<Item = CertificateRevocationList>,
) -> ClientBuilder
pub fn add_crls( self, crls: impl IntoIterator<Item = CertificateRevocationList>, ) -> ClientBuilder
Add multiple certificate revocation lists.
§Optional
This requires the rustls-tls(-...)
Cargo feature enabled.
sourcepub fn tls_built_in_root_certs(
self,
tls_built_in_root_certs: bool,
) -> ClientBuilder
pub fn tls_built_in_root_certs( self, tls_built_in_root_certs: bool, ) -> ClientBuilder
Controls the use of built-in/preloaded certificates during certificate validation.
Defaults to true
– built-in system certs will be used.
§Bulk Option
If this value is true
, all enabled system certs configured with Cargo
features will be loaded.
You can set this to false
, and enable only a specific source with
individual methods. Do that will prevent other sources from being loaded
even if their feature Cargo feature is enabled.
§Optional
This requires the optional default-tls
, native-tls
, or rustls-tls(-...)
feature to be enabled.
sourcepub fn tls_built_in_webpki_certs(self, enabled: bool) -> ClientBuilder
pub fn tls_built_in_webpki_certs(self, enabled: bool) -> ClientBuilder
Sets whether to load webpki root certs with rustls.
If the feature is enabled, this value is true
by default.
sourcepub fn identity(self, identity: Identity) -> ClientBuilder
pub fn identity(self, identity: Identity) -> ClientBuilder
Sets the identity to be used for client certificate authentication.
§Optional
This requires the optional native-tls
or rustls-tls(-...)
feature to be
enabled.
sourcepub fn danger_accept_invalid_hostnames(
self,
accept_invalid_hostname: bool,
) -> ClientBuilder
pub fn danger_accept_invalid_hostnames( self, accept_invalid_hostname: bool, ) -> ClientBuilder
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.
sourcepub fn danger_accept_invalid_certs(
self,
accept_invalid_certs: bool,
) -> ClientBuilder
pub fn danger_accept_invalid_certs( self, accept_invalid_certs: bool, ) -> ClientBuilder
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.
§Optional
This requires the optional default-tls
, native-tls
, or rustls-tls(-...)
feature to be enabled.
sourcepub fn tls_sni(self, tls_sni: bool) -> ClientBuilder
pub fn tls_sni(self, tls_sni: bool) -> ClientBuilder
Controls the use of TLS server name indication.
Defaults to true
.
§Optional
This requires the optional default-tls
, native-tls
, or rustls-tls(-...)
feature to be enabled.
sourcepub fn min_tls_version(self, version: Version) -> ClientBuilder
pub fn min_tls_version(self, version: Version) -> ClientBuilder
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.
sourcepub fn max_tls_version(self, version: Version) -> ClientBuilder
pub fn max_tls_version(self, version: Version) -> ClientBuilder
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.
Cannot set a maximum outside the protocol versions supported by
rustls
with the rustls-tls
backend.
§Optional
This requires the optional default-tls
, native-tls
, or rustls-tls(-...)
feature to be enabled.
sourcepub fn use_rustls_tls(self) -> ClientBuilder
pub fn use_rustls_tls(self) -> ClientBuilder
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.
sourcepub fn use_preconfigured_tls(self, tls: impl Any) -> ClientBuilder
pub fn use_preconfigured_tls(self, tls: impl Any) -> ClientBuilder
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.
sourcepub fn tls_info(self, tls_info: bool) -> ClientBuilder
pub fn tls_info(self, tls_info: bool) -> ClientBuilder
Add TLS information as TlsInfo
extension to responses.
§Optional
This requires the optional default-tls
, native-tls
, or rustls-tls(-...)
feature to be enabled.
sourcepub fn https_only(self, enabled: bool) -> ClientBuilder
pub fn https_only(self, enabled: bool) -> ClientBuilder
Restrict the Client to be used with HTTPS only requests.
Defaults to false.
sourcepub fn no_hickory_dns(self) -> ClientBuilder
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.
sourcepub fn resolve(self, domain: &str, addr: SocketAddr) -> ClientBuilder
pub fn resolve(self, domain: &str, addr: SocketAddr) -> ClientBuilder
Override DNS resolution for specific domains to a particular IP address.
Warning
Since the DNS protocol has no notion of ports, if you wish to send traffic to a particular port you must include this port in the URL itself, any port in the overridden addr will be ignored and traffic sent to the conventional port for the given scheme (e.g. 80 for http).
sourcepub fn resolve_to_addrs(
self,
domain: &str,
addrs: &[SocketAddr],
) -> ClientBuilder
pub fn resolve_to_addrs( self, domain: &str, addrs: &[SocketAddr], ) -> ClientBuilder
Override DNS resolution for specific domains to particular IP addresses.
Warning
Since the DNS protocol has no notion of ports, if you wish to send traffic to a particular port you must include this port in the URL itself, any port in the overridden addresses will be ignored and traffic sent to the conventional port for the given scheme (e.g. 80 for http).
sourcepub fn dns_resolver<R: Resolve + 'static>(
self,
resolver: Arc<R>,
) -> ClientBuilder
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.