Struct isahc::HttpClientBuilder

pub struct HttpClientBuilder { /* fields omitted */ }

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};
use isahc::prelude::*;
use std::time::Duration;

let client = HttpClient::builder()
    .timeout(Duration::from_secs(60))
    .redirect_policy(RedirectPolicy::Limit(10))
    .version_negotiation(VersionNegotiation::http2())
    .build()?;

Implementations

impl HttpClientBuilder

pub fn new() -> Self

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.

pub fn cookies(self) -> Self

Enable persistent cookie handling using a cookie jar.

Availability

This method is only available when the cookies feature is enabled.

pub fn max_connections(self, max: usize) -> Self

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.

pub fn max_connections_per_host(self, max: usize) -> Self

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.

pub fn connection_cache_size(self, size: usize) -> Self

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.

pub fn dns_cache(self, cache: impl Into<DnsCache>) -> Self

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

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()?;

pub fn dns_resolve(self, map: ResolveMap) -> Self

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

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

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

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

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:

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:

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:

let mut headers = HashMap::new();
headers.insert("some-header", "some-value");

let mut builder = HttpClient::builder()
    .default_headers(headers)
    .build()?;

pub fn build(self) -> Result<HttpClient, Error>

Build an HttpClient using the configured options.

If the client fails to initialize, an error will be returned.

Trait Implementations

impl Configurable for HttpClientBuilder

fn timeout(self, timeout: Duration) -> Self

Set a maximum amount of time that a request is allowed to take before being aborted.

fn connect_timeout(self, timeout: Duration) -> Self

Set a timeout for the initial connection phase.

fn version_negotiation(self, negotiation: VersionNegotiation) -> Self

Configure how the use of HTTP versions should be negotiated with the server.

fn redirect_policy(self, policy: RedirectPolicy) -> Self

Set a policy for automatically following server redirects.

fn auto_referer(self) -> Self

Update the Referer header automatically when following redirects.

fn automatic_decompression(self, decompress: bool) -> Self

Enable or disable automatic decompression of the response body for various compression algorithms as returned by the server in the Content-Encoding response header.

fn authentication(self, authentication: Authentication) -> Self

Set one or more default HTTP authentication methods to attempt to use when authenticating with the server.

fn credentials(self, credentials: Credentials) -> Self

Set the credentials to use for HTTP authentication.

fn tcp_keepalive(self, interval: Duration) -> Self

Enable TCP keepalive with a given probe interval.

fn tcp_nodelay(self) -> Self

Enables the TCP_NODELAY option on connect.

fn interface(self, interface: impl Into<NetworkInterface>) -> Self

Bind local socket connections to a particular network interface.

fn dial(self, dialer: impl Into<Dialer>) -> Self

Specify a socket to connect to instead of the using the host and port defined in the request URI.

fn proxy(self, proxy: impl Into<Option<Uri>>) -> Self

Set a proxy to use for requests.

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.

fn proxy_authentication(self, authentication: Authentication) -> Self

Set one or more HTTP authentication methods to attempt to use when authenticating with a proxy.

fn proxy_credentials(self, credentials: Credentials) -> Self

Set the credentials to use for proxy authentication.

fn max_upload_speed(self, max: u64) -> Self

Set a maximum upload speed for the request body, in bytes per second.

fn max_download_speed(self, max: u64) -> Self

Set a maximum download speed for the response body, in bytes per second.

fn dns_servers<I, T>(self, servers: I) -> Self where
    I: IntoIterator<Item = T>,
    T: Into<SocketAddr>, 

Set a list of specific DNS servers to be used for DNS resolution.

fn ssl_client_certificate(self, certificate: ClientCertificate) -> Self

Set a custom SSL/TLS client certificate to use for client connections.

fn ssl_ca_certificate(self, certificate: CaCertificate) -> Self

Set a custom SSL/TLS CA certificate bundle to use for client connections.

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.

fn ssl_options(self, options: SslOption) -> Self

Set various options for this request that control SSL/TLS behavior.

fn title_case_headers(self, enable: bool) -> Self

Enable or disable sending HTTP header names in Title-Case instead of lowercase form.

fn metrics(self, enable: bool) -> Self

Enable or disable comprehensive per-request metrics collection.

impl Debug for HttpClientBuilder

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for HttpClientBuilder

fn default() -> Self

Returns the "default value" for a type.