Struct isahc::HttpClientBuilder

pub struct HttpClientBuilder { /* fields omitted */ }

An HTTP client builder, capable of creating custom HttpClient instances with customized behavior.

Examples

use isahc::config::RedirectPolicy;
use isahc::http;
use isahc::prelude::*;
use std::time::Duration;

let client = HttpClient::builder()
    .timeout(Duration::from_secs(60))
    .redirect_policy(RedirectPolicy::Limit(10))
    .preferred_http_version(http::Version::HTTP_2)
    .build()?;

Methods

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.

This method requires the cookies feature to be enabled.

pub fn middleware(self, middleware: impl Middleware) -> Self

Add a middleware layer to the client.

This method requires the middleware-api feature to be enabled.

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

Set a timeout for the maximum time allowed for a request-response cycle.

If not set, no timeout will be enforced.

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

Set a timeout for the initial connection phase.

If not set, a connect timeout of 300 seconds will be used.

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

Set a policy for automatically following server redirects.

The default is to not follow redirects.

pub fn auto_referer(self) -> Self

Update the Referer header automatically when following redirects.

pub fn preferred_http_version(self, version: Version) -> Self

Set a preferred HTTP version the client should attempt to use to communicate to the server with.

This is treated as a suggestion. A different version may be used if the server does not support it or negotiates a different version.

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

Enable TCP keepalive with a given probe interval.

pub fn tcp_nodelay(self) -> Self

Enables the TCP_NODELAY option on connect.

pub fn proxy(self, proxy: Uri) -> Self

Set a proxy to use for requests.

The proxy protocol is specified by the URI scheme.

• http: Proxy. Default when no scheme is specified.
• https: HTTPS Proxy. (Added in 7.52.0 for OpenSSL, GnuTLS and NSS)
• socks4: SOCKS4 Proxy.
• socks4a: SOCKS4a Proxy. Proxy resolves URL hostname.
• socks5: SOCKS5 Proxy.
• socks5h: SOCKS5 Proxy. Proxy resolves URL hostname.

By default no proxy will be used, unless one is specified in either the http_proxy or https_proxy environment variables.

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

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

The default is unlimited.

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

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

The default is unlimited.

pub fn dns_servers(self, servers: impl IntoIterator<Item = SocketAddr>) -> Self

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

By default this option is not set and the system's built-in DNS resolver is used. This option can only be used if libcurl is compiled with c-ares, otherwise this option has no effect.

pub fn ssl_ciphers(self, servers: impl IntoIterator<Item = String>) -> Self

Set a list of ciphers to use for SSL/TLS connections.

The list of valid cipher names is dependent on the underlying SSL/TLS engine in use. You can find an up-to-date list of potential cipher names at https://curl.haxx.se/docs/ssl-ciphers.html.

The default is unset and will result in the system defaults being used.

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

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

If a format is not supported by the underlying SSL/TLS engine, an error will be returned when attempting to send a request using the offending certificate.

The default value is none.

Examples

let client = HttpClient::builder()
    .ssl_client_certificate(ClientCertificate::PEM {
        path: "client.pem".into(),
        private_key: Some(PrivateKey::PEM {
            path: "key.pem".into(),
            password: Some("secret".into()),
        }),
    })
    .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 Default for HttpClientBuilder

fn default() -> HttpClientBuilder

Returns the "default value" for a type.

impl Debug for HttpClientBuilder

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

Formats the value using the given formatter.