Struct reqwest::blocking::ClientBuilder
source · [−]pub struct ClientBuilder { /* private fields */ }
Expand description
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
sourceimpl 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 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.
sourcepub 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::blocking::Client::builder()
.user_agent(APP_USER_AGENT)
.build()?;
let res = client.get("https://www.rust-lang.org").send()?;
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"));
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()?;
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::blocking::Client::builder()
.default_headers(headers)
.build()?;
let res = client
.get("https://www.rust-lang.org")
.header("X-MY-HEADER", "new_value")
.send()?;
sourcepub fn gzip(self, enable: bool) -> ClientBuilder
pub fn gzip(self, enable: bool) -> ClientBuilder
Enable auto gzip decompression by checking the Content-Encoding
response header.
If auto gzip decompresson 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 it’s headers contain a
Content-Encoding
value that equals togzip
, both valuesContent-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
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_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 redirect::Policy
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.
This also disables the automatic usage of the “system” proxy.
sourcepub fn timeout<T>(self, timeout: T) -> ClientBuilder where
T: Into<Option<Duration>>,
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.
sourcepub fn connect_timeout<T>(self, timeout: T) -> ClientBuilder where
T: Into<Option<Duration>>,
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
.
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 where
D: Into<Option<Duration>>,
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.
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
Enable case sensitive headers.
sourcepub fn http2_prior_knowledge(self) -> ClientBuilder
pub fn http2_prior_knowledge(self) -> ClientBuilder
Only use HTTP/2.
sourcepub fn http2_initial_stream_window_size(
self,
sz: impl Into<Option<u32>>
) -> ClientBuilder
pub fn http2_initial_stream_window_size(
self,
sz: impl Into<Option<u32>>
) -> ClientBuilder
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.
sourcepub 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.
sourcepub fn http2_adaptive_window(self, enabled: bool) -> ClientBuilder
pub fn http2_adaptive_window(self, enabled: bool) -> ClientBuilder
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
.
sourcepub fn http2_max_frame_size(self, sz: impl Into<Option<u32>>) -> ClientBuilder
pub fn http2_max_frame_size(self, sz: impl Into<Option<u32>>) -> ClientBuilder
Sets the maximum frame size to use for HTTP2.
Default is currently 16,384 but may change internally to optimize for common uses.
sourcepub fn tcp_nodelay(self, enabled: bool) -> ClientBuilder
pub fn tcp_nodelay(self, enabled: bool) -> ClientBuilder
Set whether sockets have SO_NODELAY
enabled.
Default is true
.
sourcepub fn local_address<T>(self, addr: T) -> ClientBuilder where
T: Into<Option<IpAddr>>,
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();
sourcepub fn tcp_keepalive<D>(self, val: D) -> ClientBuilder where
D: Into<Option<Duration>>,
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.
sourcepub fn add_root_certificate(self, cert: Certificate) -> ClientBuilder
pub fn add_root_certificate(self, cert: Certificate) -> ClientBuilder
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.
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 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.
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 native-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.
sourcepub fn use_native_tls(self) -> ClientBuilder
pub fn use_native_tls(self) -> ClientBuilder
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.
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 no_trust_dns(self) -> ClientBuilder
pub fn no_trust_dns(self) -> ClientBuilder
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.
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.
Trait Implementations
sourceimpl Debug for ClientBuilder
impl Debug for ClientBuilder
sourceimpl Default for ClientBuilder
impl Default for ClientBuilder
sourceimpl From<ClientBuilder> for ClientBuilder
impl From<ClientBuilder> for ClientBuilder
sourcefn from(builder: ClientBuilder) -> Self
fn from(builder: ClientBuilder) -> Self
Converts to this type from the input type.
Auto Trait Implementations
impl !RefUnwindSafe for ClientBuilder
impl Send for ClientBuilder
impl Sync for ClientBuilder
impl Unpin for ClientBuilder
impl !UnwindSafe for ClientBuilder
Blanket Implementations
sourceimpl<T> BorrowMut<T> for T where
T: ?Sized,
impl<T> BorrowMut<T> for T where
T: ?Sized,
const: unstable · sourcefn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
Mutably borrows from an owned value. Read more
sourceimpl<T> Instrument for T
impl<T> Instrument for T
sourcefn instrument(self, span: Span) -> Instrumented<Self>
fn instrument(self, span: Span) -> Instrumented<Self>
sourcefn in_current_span(self) -> Instrumented<Self>
fn in_current_span(self) -> Instrumented<Self>
sourceimpl<T> WithSubscriber for T
impl<T> WithSubscriber for T
sourcefn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self> where
S: Into<Dispatch>,
fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self> where
S: Into<Dispatch>,
Attaches the provided Subscriber
to this type, returning a
WithDispatch
wrapper. Read more
sourcefn with_current_subscriber(self) -> WithDispatch<Self>
fn with_current_subscriber(self) -> WithDispatch<Self>
Attaches the current default Subscriber
to this type, returning a
WithDispatch
wrapper. Read more