Struct isahc::HttpClientBuilder [−][src]
pub struct HttpClientBuilder { /* fields omitted */ }
Expand description
An HTTP client builder, capable of creating custom HttpClient
instances
with customized behavior.
Any option that can be configured per-request can also be configured on a
client builder as a default setting. Request configuration is provided by
the Configurable
trait, which is also available in the
prelude
module.
Examples
use isahc::{
config::{RedirectPolicy, VersionNegotiation},
prelude::*,
HttpClient,
};
use std::time::Duration;
let client = HttpClient::builder()
.timeout(Duration::from_secs(60))
.redirect_policy(RedirectPolicy::Limit(10))
.version_negotiation(VersionNegotiation::http2())
.build()?;
Implementations
Create a new builder for building a custom client. All configuration will start out with the default values.
This is equivalent to the Default
implementation.
Enable persistent cookie handling for all requests using this client using a shared cookie jar.
Examples
use isahc::{prelude::*, HttpClient};
// Create a client with a cookie jar.
let client = HttpClient::builder()
.cookies()
.build()?;
// Make a request that sets a cookie.
let uri = "http://httpbin.org/cookies/set?foo=bar".parse()?;
client.get(&uri)?;
// Get the cookie from the cookie jar.
let cookie = client.cookie_jar()
.unwrap()
.get_by_name(&uri, "foo")
.unwrap();
assert_eq!(cookie, "bar");
Availability
This method is only available when the cookies
feature is enabled.
Set a maximum number of simultaneous connections that this client is allowed to keep open at one time.
If set to a value greater than zero, no more than max
connections will
be opened at one time. If executing a new request would require opening
a new connection, then the request will stay in a “pending” state until
an existing connection can be used or an active request completes and
can be closed, making room for a new connection.
Setting this value to 0
disables the limit entirely.
This is an effective way of limiting the number of sockets or file descriptors that this client will open, though note that the client may use file descriptors for purposes other than just HTTP connections.
By default this value is 0
and no limit is enforced.
To apply a limit per-host, see
HttpClientBuilder::max_connections_per_host
.
Set a maximum number of simultaneous connections that this client is allowed to keep open to individual hosts at one time.
If set to a value greater than zero, no more than max
connections will
be opened to a single host at one time. If executing a new request would
require opening a new connection, then the request will stay in a
“pending” state until an existing connection can be used or an active
request completes and can be closed, making room for a new connection.
Setting this value to 0
disables the limit entirely. By default this
value is 0
and no limit is enforced.
To set a global limit across all hosts, see
HttpClientBuilder::max_connections
.
Set the size of the connection cache.
After requests are completed, if the underlying connection is reusable, it is added to the connection cache to be reused to reduce latency for future requests.
Setting the size to 0
disables connection caching for all requests
using this client.
By default this value is unspecified. A reasonable default size will be chosen.
Set the maximum time-to-live (TTL) for connections to remain in the connection cache.
After requests are completed, if the underlying connection is reusable, it is added to the connection cache to be reused to reduce latency for future requests. This option controls how long such connections should be still considered valid before being discarded.
Old connections have a high risk of not working any more and thus attempting to use them wastes time if the server has disconnected.
The default TTL is 118 seconds.
Configure DNS caching.
By default, DNS entries are cached by the client executing the request and are used until the entry expires. Calling this method allows you to change the entry timeout duration or disable caching completely.
Note that DNS entry TTLs are not respected, regardless of this setting.
By default caching is enabled with a 60 second timeout.
Examples
use isahc::{config::*, prelude::*, HttpClient};
use std::time::Duration;
let client = HttpClient::builder()
// Cache entries for 10 seconds.
.dns_cache(Duration::from_secs(10))
// Cache entries forever.
.dns_cache(DnsCache::Forever)
// Don't cache anything.
.dns_cache(DnsCache::Disable)
.build()?;
Set a mapping of DNS resolve overrides.
Entries in the given map will be used first before using the default DNS resolver for host+port pairs.
Note that DNS resolving is only performed when establishing a new
Examples
use isahc::{config::ResolveMap, prelude::*, HttpClient};
use std::net::IpAddr;
let client = HttpClient::builder()
.dns_resolve(ResolveMap::new()
// Send requests for example.org on port 80 to 127.0.0.1.
.add("example.org", 80, [127, 0, 0, 1]))
.build()?;
pub fn default_header<K, V>(self, key: K, value: V) -> Self where
HeaderName: TryFrom<K>,
<HeaderName as TryFrom<K>>::Error: Into<Error>,
HeaderValue: TryFrom<V>,
<HeaderValue as TryFrom<V>>::Error: Into<Error>,
pub fn default_header<K, V>(self, key: K, value: V) -> Self where
HeaderName: TryFrom<K>,
<HeaderName as TryFrom<K>>::Error: Into<Error>,
HeaderValue: TryFrom<V>,
<HeaderValue as TryFrom<V>>::Error: Into<Error>,
Add a default header to be passed with every request.
If a default header value is already defined for the given key, then a second header value will be appended to the list and multiple header values will be included in the request.
If any values are defined for this header key on an outgoing request, they will override any default header values.
If the header key or value are malformed, HttpClientBuilder::build
will return an error.
Examples
use isahc::{prelude::*, HttpClient};
let client = HttpClient::builder()
.default_header("some-header", "some-value")
.build()?;
pub fn default_headers<K, V, I, P>(self, headers: I) -> Self where
HeaderName: TryFrom<K>,
<HeaderName as TryFrom<K>>::Error: Into<Error>,
HeaderValue: TryFrom<V>,
<HeaderValue as TryFrom<V>>::Error: Into<Error>,
I: IntoIterator<Item = P>,
P: HeaderPair<K, V>,
pub fn default_headers<K, V, I, P>(self, headers: I) -> Self where
HeaderName: TryFrom<K>,
<HeaderName as TryFrom<K>>::Error: Into<Error>,
HeaderValue: TryFrom<V>,
<HeaderValue as TryFrom<V>>::Error: Into<Error>,
I: IntoIterator<Item = P>,
P: HeaderPair<K, V>,
Set the default headers to include in every request, replacing any previously set default headers.
Headers defined on an individual request always override headers in the default map.
If any header keys or values are malformed, HttpClientBuilder::build
will return an error.
Examples
Set default headers from a slice:
use isahc::{prelude::*, HttpClient};
let mut builder = HttpClient::builder()
.default_headers(&[
("some-header", "value1"),
("some-header", "value2"),
("some-other-header", "some-other-value"),
])
.build()?;
Using an existing header map:
use isahc::{prelude::*, HttpClient};
let mut headers = http::HeaderMap::new();
headers.append("some-header".parse::<http::header::HeaderName>()?, "some-value".parse()?);
let mut builder = HttpClient::builder()
.default_headers(&headers)
.build()?;
Using a hashmap:
use isahc::{prelude::*, HttpClient};
use std::collections::HashMap;
let mut headers = HashMap::new();
headers.insert("some-header", "some-value");
let mut builder = HttpClient::builder()
.default_headers(headers)
.build()?;
Build an HttpClient
using the configured options.
If the client fails to initialize, an error will be returned.
Trait Implementations
Set a cookie jar to use to accept, store, and supply cookies for incoming responses and outgoing requests. Read more
Specify a maximum amount of time that a complete request/response cycle is allowed to take before being aborted. This includes DNS resolution, connecting to the server, writing the request, and reading the response. Read more
Set a timeout for establishing connections to a host. Read more
Specify a maximum amount of time where transfer rate can go below
a minimum speed limit. low_speed
is that limit in bytes/s. Read more
Configure how the use of HTTP versions should be negotiated with the server. Read more
Set a policy for automatically following server redirects. Read more
Update the Referer
header automatically when following redirects.
Enable or disable automatic decompression of the response body for
various compression algorithms as returned by the server in the
Content-Encoding
response header. Read more
Configure the use of the Expect
request header when sending request
bodies with HTTP/1.1. Read more
Set one or more default HTTP authentication methods to attempt to use when authenticating with the server. Read more
Set the credentials to use for HTTP authentication. Read more
Enable TCP keepalive with a given probe interval.
Enables the TCP_NODELAY
option on connect.
Bind local socket connections to a particular network interface. Read more
Select a specific IP version when resolving hostnames. If a given hostname does not resolve to an IP address of the desired version, then the request will fail with a connection error. Read more
Specify a socket to connect to instead of the using the host and port defined in the request URI. Read more
Set a proxy to use for requests. Read more
fn proxy_blacklist<I, T>(self, hosts: I) -> Self where
I: IntoIterator<Item = T>,
T: Into<String>,
fn proxy_blacklist<I, T>(self, hosts: I) -> Self where
I: IntoIterator<Item = T>,
T: Into<String>,
Disable proxy usage for the provided list of hosts. Read more
Set one or more HTTP authentication methods to attempt to use when authenticating with a proxy. Read more
Set the credentials to use for proxy authentication. Read more
Set a maximum upload speed for the request body, in bytes per second. Read more
Set a maximum download speed for the response body, in bytes per second. Read more
Set a custom SSL/TLS client certificate to use for client connections. Read more
Set a custom SSL/TLS CA certificate bundle to use for client connections. Read more
fn ssl_ciphers<I, T>(self, ciphers: I) -> Self where
I: IntoIterator<Item = T>,
T: Into<String>,
fn ssl_ciphers<I, T>(self, ciphers: I) -> Self where
I: IntoIterator<Item = T>,
T: Into<String>,
Set a list of ciphers to use for SSL/TLS connections. Read more
Set various options for this request that control SSL/TLS behavior. Read more
Enable or disable sending HTTP header names in Title-Case instead of lowercase form. Read more
Auto Trait Implementations
impl !RefUnwindSafe for HttpClientBuilder
impl Send for HttpClientBuilder
impl Sync for HttpClientBuilder
impl Unpin for HttpClientBuilder
impl !UnwindSafe for HttpClientBuilder
Blanket Implementations
Mutably borrows from an owned value. Read more
Instruments this type with the provided Span
, returning an
Instrumented
wrapper. Read more
Instruments this type with the provided Span
, returning an
Instrumented
wrapper. Read more
Attaches the provided Subscriber
to this type, returning a
WithDispatch
wrapper. Read more
Attaches the current default Subscriber
to this type, returning a
WithDispatch
wrapper. Read more