Struct reqwest::ClientBuilder [−][src]
pub struct ClientBuilder { /* fields omitted */ }
Expand description
A ClientBuilder
can be used to create a Client
with custom configuration.
Implementations
Constructs a new ClientBuilder
.
This is the same as Client::builder()
.
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>,
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?;
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?;
Override the default headers:
use reqwest::header; let mut headers = header::HeaderMap::new(); headers.insert("X-MY-HEADER", header::HeaderValue::from_static("value")); // get a client builder let client = reqwest::Client::builder() .default_headers(headers) .build()?; let res = client .get("https://www.rust-lang.org") .header("X-MY-HEADER", "new_value") .send() .await?;
This is supported on crate feature cookies
only.
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.
This is supported on crate feature cookies
only.
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.
This is supported on crate feature gzip
only.
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
andRange
values, theAccept-Encoding
header is set togzip
. The request body is not automatically compressed. - When receiving a response, if its headers contain a
Content-Encoding
value ofgzip
, bothContent-Encoding
andContent-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
This is supported on crate feature brotli
only.
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
andRange
values, theAccept-Encoding
header is set tobr
. The request body is not automatically compressed. - When receiving a response, if its headers contain a
Content-Encoding
value ofbr
, bothContent-Encoding
andContent-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
This is supported on crate feature deflate
only.
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
andRange
values, theAccept-Encoding
header is set todeflate
. The request body is not automatically compressed. - When receiving a response, if it’s headers contain a
Content-Encoding
value that equals todeflate
, both valuesContent-Encoding
andContent-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
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.
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.
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.
Set a RedirectPolicy
for this client.
Default will follow redirects up to a maximum of 10.
Enable or disable automatic setting of the Referer
header.
Default is true
.
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.
Clear all Proxies
, so Client
will use no proxy anymore.
This also disables the automatic usage of the “system” proxy.
Enables a request timeout.
The timeout is applied from when the request starts connecting until the response body has finished.
Default is no timeout.
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.
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.
Set an optional timeout for idle sockets being kept-alive.
Pass None
to disable timeout.
Default is 90 seconds.
Sets the maximum idle connection per host allowed in the pool.
Enable case sensitive headers.
Only use HTTP/2.
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
pub fn http2_initial_connection_window_size(
self,
sz: impl Into<Option<u32>>
) -> ClientBuilder
Sets the max connection-level flow control for HTTP2
Default is currently 65,535 but may change internally to optimize for common uses.
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
.
Sets the maximum frame size to use for HTTP2.
Default is currently 16,384 but may change internally to optimize for common uses.
Set whether sockets have SO_NODELAY
enabled.
Default is true
.
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();
Set that all sockets have SO_KEEPALIVE
set with the supplied duration.
If None
, the option will not be set.
This is supported on crate features default-tls
or native-tls
or rustls-tls
only.
default-tls
or native-tls
or rustls-tls
only.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.
This is supported on crate features default-tls
or native-tls
or rustls-tls
only.
default-tls
or native-tls
or rustls-tls
only.Controls the use of built-in/preloaded 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.
This is supported on crate features native-tls
or rustls-tls
only.
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.
This is supported on crate feature native-tls
only.
native-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 native-tls
feature to be enabled.
This is supported on crate features default-tls
or native-tls
or rustls-tls
only.
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.
Optional
This requires the optional default-tls
, native-tls
, or rustls-tls(-...)
feature to be enabled.
This is supported on crate feature native-tls
only.
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.
This is supported on crate feature rustls-tls
only.
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.
This is supported on crate features native-tls
or rustls-tls
only.
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.
This is supported on crate feature trust-dns
only.
trust-dns
only.Disables the trust-dns async resolver.
This method exists even if the optional trust-dns
feature is not enabled.
This can be used to ensure a Client
doesn’t use the trust-dns async resolver
even if another dependency were to enable the optional trust-dns
feature.
Restrict the Client to be used with HTTPS only requests.
Defaults to false.
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 addr will be ignored and traffic sent to the conventional port for the given scheme (e.g. 80 for http).
Trait Implementations
Performs the conversion.
Auto Trait Implementations
impl !RefUnwindSafe for ClientBuilder
impl Send for ClientBuilder
impl Sync for ClientBuilder
impl Unpin for ClientBuilder
impl !UnwindSafe for ClientBuilder