Struct HttpClientBuilder

pub struct HttpClientBuilder { /* private fields */ }

Builder for configuring and creating an HttpClient.

Implementations

impl HttpClientBuilder

pub fn new() -> Self

Start a new builder with default settings.

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

Set a request timeout to apply to client operations.

Examples found in repository

examples/self-signed-certs/main.rs (line 11)

fn main() {
    // Default secure client (uses OS trust store when built with default features)
    let mut headers = HashMap::new();
    headers.insert("x-app".into(), "example".into());

    let client = HttpClient::builder()
        .with_timeout(Duration::from_secs(10))
        .with_default_headers(headers)
        .build();

    // Demonstrate a request (no network I/O in this example crate yet)
    client
        .request("https://example.com")
        .expect("request should succeed on native targets");

    // Production with rustls + custom Root CA (e.g., self-signed for your private service)
    // Note: Requires building with: --no-default-features --features rustls
    #[cfg(feature = "rustls")]
    {
        // Option 1: Load CA certificate from raw PEM bytes
        let ca_pem: &[u8] =
            b"-----BEGIN CERTIFICATE-----\n...your root ca...\n-----END CERTIFICATE-----\n";
        let _rustls_client = HttpClient::builder()
            .with_timeout(Duration::from_secs(10))
            .with_root_ca_pem(ca_pem)
            .build();
        let _ = _rustls_client.request("https://private.local");

        // Option 2: Load CA certificate from a file path
        // Note: This will panic if the file doesn't exist - ensure your cert file is available
        // let _rustls_client_from_file = HttpClient::builder()
        //     .with_timeout(Duration::from_secs(10))
        //     .with_root_ca_file("path/to/your/root-ca.pem")
        //     .build();
        // let _ = _rustls_client_from_file.request("https://private.local");
    }

    // Local development only: accept invalid/self-signed certs (dangerous)
    // Build with: --features insecure-dangerous (or with rustls,insecure-dangerous)
    #[cfg(feature = "insecure-dangerous")]
    {
        // Shortcut:
        let _dev_client = HttpClient::with_self_signed_certs();
        let _ = _dev_client.request("https://localhost:8443");

        // Or explicit builder method:
        let _dev_client2 = HttpClient::builder()
            .insecure_accept_invalid_certs(true)
            .build();
        let _ = _dev_client2.request("https://localhost:8443");
    }

    println!("Example finished. See README for feature flags and commands.");
}

pub fn with_default_headers(self, headers: HashMap<String, String>) -> Self

Set default headers that will be added to every request initiated by this client.

Examples found in repository

examples/self-signed-certs/main.rs (line 12)

fn main() {
    // Default secure client (uses OS trust store when built with default features)
    let mut headers = HashMap::new();
    headers.insert("x-app".into(), "example".into());

    let client = HttpClient::builder()
        .with_timeout(Duration::from_secs(10))
        .with_default_headers(headers)
        .build();

    // Demonstrate a request (no network I/O in this example crate yet)
    client
        .request("https://example.com")
        .expect("request should succeed on native targets");

    // Production with rustls + custom Root CA (e.g., self-signed for your private service)
    // Note: Requires building with: --no-default-features --features rustls
    #[cfg(feature = "rustls")]
    {
        // Option 1: Load CA certificate from raw PEM bytes
        let ca_pem: &[u8] =
            b"-----BEGIN CERTIFICATE-----\n...your root ca...\n-----END CERTIFICATE-----\n";
        let _rustls_client = HttpClient::builder()
            .with_timeout(Duration::from_secs(10))
            .with_root_ca_pem(ca_pem)
            .build();
        let _ = _rustls_client.request("https://private.local");

        // Option 2: Load CA certificate from a file path
        // Note: This will panic if the file doesn't exist - ensure your cert file is available
        // let _rustls_client_from_file = HttpClient::builder()
        //     .with_timeout(Duration::from_secs(10))
        //     .with_root_ca_file("path/to/your/root-ca.pem")
        //     .build();
        // let _ = _rustls_client_from_file.request("https://private.local");
    }

    // Local development only: accept invalid/self-signed certs (dangerous)
    // Build with: --features insecure-dangerous (or with rustls,insecure-dangerous)
    #[cfg(feature = "insecure-dangerous")]
    {
        // Shortcut:
        let _dev_client = HttpClient::with_self_signed_certs();
        let _ = _dev_client.request("https://localhost:8443");

        // Or explicit builder method:
        let _dev_client2 = HttpClient::builder()
            .insecure_accept_invalid_certs(true)
            .build();
        let _ = _dev_client2.request("https://localhost:8443");
    }

    println!("Example finished. See README for feature flags and commands.");
}

pub fn insecure_accept_invalid_certs(self, accept: bool) -> Self

Dev-only: accept self-signed/invalid TLS certificates. Requires the insecure-dangerous feature to be enabled. NEVER enable this in production.

Examples

Enable insecure mode during local development (dangerous):

use hyper_custom_cert::HttpClient;

// Requires: --features insecure-dangerous
let client = HttpClient::builder()
    .insecure_accept_invalid_certs(true)
    .build();

Examples found in repository

examples/self-signed-certs/main.rs (line 52)

fn main() {
    // Default secure client (uses OS trust store when built with default features)
    let mut headers = HashMap::new();
    headers.insert("x-app".into(), "example".into());

    let client = HttpClient::builder()
        .with_timeout(Duration::from_secs(10))
        .with_default_headers(headers)
        .build();

    // Demonstrate a request (no network I/O in this example crate yet)
    client
        .request("https://example.com")
        .expect("request should succeed on native targets");

    // Production with rustls + custom Root CA (e.g., self-signed for your private service)
    // Note: Requires building with: --no-default-features --features rustls
    #[cfg(feature = "rustls")]
    {
        // Option 1: Load CA certificate from raw PEM bytes
        let ca_pem: &[u8] =
            b"-----BEGIN CERTIFICATE-----\n...your root ca...\n-----END CERTIFICATE-----\n";
        let _rustls_client = HttpClient::builder()
            .with_timeout(Duration::from_secs(10))
            .with_root_ca_pem(ca_pem)
            .build();
        let _ = _rustls_client.request("https://private.local");

        // Option 2: Load CA certificate from a file path
        // Note: This will panic if the file doesn't exist - ensure your cert file is available
        // let _rustls_client_from_file = HttpClient::builder()
        //     .with_timeout(Duration::from_secs(10))
        //     .with_root_ca_file("path/to/your/root-ca.pem")
        //     .build();
        // let _ = _rustls_client_from_file.request("https://private.local");
    }

    // Local development only: accept invalid/self-signed certs (dangerous)
    // Build with: --features insecure-dangerous (or with rustls,insecure-dangerous)
    #[cfg(feature = "insecure-dangerous")]
    {
        // Shortcut:
        let _dev_client = HttpClient::with_self_signed_certs();
        let _ = _dev_client.request("https://localhost:8443");

        // Or explicit builder method:
        let _dev_client2 = HttpClient::builder()
            .insecure_accept_invalid_certs(true)
            .build();
        let _ = _dev_client2.request("https://localhost:8443");
    }

    println!("Example finished. See README for feature flags and commands.");
}

pub fn with_root_ca_pem(self, pem_bytes: &[u8]) -> Self

Provide a PEM-encoded Root CA certificate to be trusted by the client. This is the production-ready way to trust a custom CA.

Examples

use hyper_custom_cert::HttpClient;

// Requires: --no-default-features --features rustls
let client = HttpClient::builder()
    .with_root_ca_pem(include_bytes!("../examples-data/root-ca.pem"))
    .build();

Examples found in repository

examples/self-signed-certs/main.rs (line 29)

fn main() {
    // Default secure client (uses OS trust store when built with default features)
    let mut headers = HashMap::new();
    headers.insert("x-app".into(), "example".into());

    let client = HttpClient::builder()
        .with_timeout(Duration::from_secs(10))
        .with_default_headers(headers)
        .build();

    // Demonstrate a request (no network I/O in this example crate yet)
    client
        .request("https://example.com")
        .expect("request should succeed on native targets");

    // Production with rustls + custom Root CA (e.g., self-signed for your private service)
    // Note: Requires building with: --no-default-features --features rustls
    #[cfg(feature = "rustls")]
    {
        // Option 1: Load CA certificate from raw PEM bytes
        let ca_pem: &[u8] =
            b"-----BEGIN CERTIFICATE-----\n...your root ca...\n-----END CERTIFICATE-----\n";
        let _rustls_client = HttpClient::builder()
            .with_timeout(Duration::from_secs(10))
            .with_root_ca_pem(ca_pem)
            .build();
        let _ = _rustls_client.request("https://private.local");

        // Option 2: Load CA certificate from a file path
        // Note: This will panic if the file doesn't exist - ensure your cert file is available
        // let _rustls_client_from_file = HttpClient::builder()
        //     .with_timeout(Duration::from_secs(10))
        //     .with_root_ca_file("path/to/your/root-ca.pem")
        //     .build();
        // let _ = _rustls_client_from_file.request("https://private.local");
    }

    // Local development only: accept invalid/self-signed certs (dangerous)
    // Build with: --features insecure-dangerous (or with rustls,insecure-dangerous)
    #[cfg(feature = "insecure-dangerous")]
    {
        // Shortcut:
        let _dev_client = HttpClient::with_self_signed_certs();
        let _ = _dev_client.request("https://localhost:8443");

        // Or explicit builder method:
        let _dev_client2 = HttpClient::builder()
            .insecure_accept_invalid_certs(true)
            .build();
        let _ = _dev_client2.request("https://localhost:8443");
    }

    println!("Example finished. See README for feature flags and commands.");
}

pub fn with_root_ca_file<P: AsRef<Path>>(self, path: P) -> Self

Provide a PEM-encoded Root CA certificate file to be trusted by the client. This is the production-ready way to trust a custom CA from a file path.

The file will be read during builder configuration and its contents stored in the client. This method will panic if the file cannot be read, similar to how include_bytes! macro behaves.

Security Considerations

Only use certificate files from trusted sources. Ensure proper file permissions are set to prevent unauthorized modification of the certificate file.

Panics

This method will panic if:

• The file does not exist
• The file cannot be read due to permissions or I/O errors
• The path is invalid

Examples

use hyper_custom_cert::HttpClient;

// Requires: --no-default-features --features rustls
let client = HttpClient::builder()
    .with_root_ca_file("path/to/root-ca.pem")
    .build();

Using a std::path::Path:

use hyper_custom_cert::HttpClient;
use std::path::Path;

// Requires: --no-default-features --features rustls
let ca_path = Path::new("certs/custom-ca.pem");
let client = HttpClient::builder()
    .with_root_ca_file(ca_path)
    .build();

pub fn with_pinned_cert_sha256(self, pins: Vec<[u8; 32]>) -> Self

Configure certificate pinning using SHA256 fingerprints for additional security.

Certificate pinning provides an additional layer of security beyond CA validation by verifying that the server’s certificate matches one of the provided fingerprints. This helps protect against compromised CAs and man-in-the-middle attacks.

Security Considerations

• Certificate pinning should be used in conjunction with, not as a replacement for, proper CA validation.
• Pinned certificates must be updated when the server’s certificate changes.
• Consider having backup pins for certificate rotation scenarios.
• This method provides additional security but requires careful maintenance.

Parameters

• pins - A vector of 32-byte SHA256 fingerprints of certificates to pin. Each fingerprint should be the SHA256 hash of the certificate’s DER encoding.

Examples

use hyper_custom_cert::HttpClient;

// Example SHA256 fingerprints (these are just examples)
let pin1: [u8; 32] = [
    0x12, 0x34, 0x56, 0x78, 0x9a, 0xbc, 0xde, 0xf0,
    0x11, 0x22, 0x33, 0x44, 0x55, 0x66, 0x77, 0x88,
    0x99, 0xaa, 0xbb, 0xcc, 0xdd, 0xee, 0xff, 0x00,
    0xa1, 0xb2, 0xc3, 0xd4, 0xe5, 0xf6, 0x07, 0x18
];

let pin2: [u8; 32] = [
    0xf0, 0xe1, 0xd2, 0xc3, 0xb4, 0xa5, 0x96, 0x87,
    0x78, 0x69, 0x5a, 0x4b, 0x3c, 0x2d, 0x1e, 0x0f,
    0x00, 0x11, 0x22, 0x33, 0x44, 0x55, 0x66, 0x77,
    0x88, 0x99, 0xaa, 0xbb, 0xcc, 0xdd, 0xee, 0xff
];

// Requires: --no-default-features --features rustls
let client = HttpClient::builder()
    .with_pinned_cert_sha256(vec![pin1, pin2])
    .build();

pub fn build(self) -> HttpClient

Finalize the configuration and build an HttpClient.

Examples found in repository

examples/self-signed-certs/main.rs (line 13)

fn main() {
    // Default secure client (uses OS trust store when built with default features)
    let mut headers = HashMap::new();
    headers.insert("x-app".into(), "example".into());

    let client = HttpClient::builder()
        .with_timeout(Duration::from_secs(10))
        .with_default_headers(headers)
        .build();

    // Demonstrate a request (no network I/O in this example crate yet)
    client
        .request("https://example.com")
        .expect("request should succeed on native targets");

    // Production with rustls + custom Root CA (e.g., self-signed for your private service)
    // Note: Requires building with: --no-default-features --features rustls
    #[cfg(feature = "rustls")]
    {
        // Option 1: Load CA certificate from raw PEM bytes
        let ca_pem: &[u8] =
            b"-----BEGIN CERTIFICATE-----\n...your root ca...\n-----END CERTIFICATE-----\n";
        let _rustls_client = HttpClient::builder()
            .with_timeout(Duration::from_secs(10))
            .with_root_ca_pem(ca_pem)
            .build();
        let _ = _rustls_client.request("https://private.local");

        // Option 2: Load CA certificate from a file path
        // Note: This will panic if the file doesn't exist - ensure your cert file is available
        // let _rustls_client_from_file = HttpClient::builder()
        //     .with_timeout(Duration::from_secs(10))
        //     .with_root_ca_file("path/to/your/root-ca.pem")
        //     .build();
        // let _ = _rustls_client_from_file.request("https://private.local");
    }

    // Local development only: accept invalid/self-signed certs (dangerous)
    // Build with: --features insecure-dangerous (or with rustls,insecure-dangerous)
    #[cfg(feature = "insecure-dangerous")]
    {
        // Shortcut:
        let _dev_client = HttpClient::with_self_signed_certs();
        let _ = _dev_client.request("https://localhost:8443");

        // Or explicit builder method:
        let _dev_client2 = HttpClient::builder()
            .insecure_accept_invalid_certs(true)
            .build();
        let _ = _dev_client2.request("https://localhost:8443");
    }

    println!("Example finished. See README for feature flags and commands.");
}

Trait Implementations

impl Default for HttpClientBuilder

Default builder state is secure and ergonomic.

fn default() -> Self

Returns the “default value” for a type.