Struct HttpClient 

pub struct HttpClient { /* private fields */ }

Reusable HTTP client configured via HttpClientBuilder.

Examples

Build a client with a custom timeout and default headers:

use hyper_custom_cert::{HttpClient, RequestOptions};
use std::time::Duration;
use std::collections::HashMap;

let mut headers = HashMap::new();
headers.insert("x-app".into(), "demo".into());

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

// Placeholder call; does not perform I/O in this crate.
let _ = client.request_with_options("https://example.com", None);

Implementations

impl HttpClient

pub fn new() -> Self

Construct a new client using secure defaults by delegating to the builder. This provides a convenient way to get a functional client without explicit configuration, relying on sensible defaults (e.g., 30-second timeout, no custom CAs).

pub fn builder() -> HttpClientBuilder

Start building a client with explicit configuration. This method exposes the HttpClientBuilder to allow granular control over various client settings like timeouts, default headers, and TLS configurations.

Examples found in repository

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

async 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 (now returns HttpResponse with raw body data)
    let _response = client
        .request_with_options("https://example.com", None)
        .await
        .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_with_options("https://private.local", None)
            .await;

        // 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_with_options("https://localhost:8443", None)
            .await;

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

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

pub fn with_self_signed_certs() -> Self

Convenience constructor that enables acceptance of self-signed/invalid certificates. This is gated behind the insecure-dangerous feature and intended strictly for development and testing. NEVER enable in production.

Security Warning

⚠️ CRITICAL SECURITY WARNING ⚠️

This method deliberately bypasses TLS certificate validation, creating a serious security vulnerability to man-in-the-middle attacks. When used:

• ANY certificate will be accepted, regardless of its validity
• Expired certificates will be accepted
• Certificates from untrusted issuers will be accepted
• Certificates for the wrong domain will be accepted

This is equivalent to calling insecure_accept_invalid_certs(true) on the builder and inherits all of its security implications. See that method’s documentation for more details.

Intended Use Cases

This method should ONLY be used for:

• Local development with self-signed certificates
• Testing environments where security is not a concern
• Debugging TLS connection issues

Implementation Details

This is a convenience wrapper that calls:

HttpClient::builder()
    .insecure_accept_invalid_certs(true)
    .build()

Examples found in repository

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

async 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 (now returns HttpResponse with raw body data)
    let _response = client
        .request_with_options("https://example.com", None)
        .await
        .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_with_options("https://private.local", None)
            .await;

        // 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_with_options("https://localhost:8443", None)
            .await;

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

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

impl HttpClient

pub async fn request(&self, url: &str) -> Result<HttpResponse, ClientError>

👎Deprecated since 0.4.0: Use request(url, Some(options)) instead

Performs a GET request and returns the raw response body. This method constructs a hyper::Request with the GET method and any default headers configured on the client, then dispatches it via perform_request. Returns HttpResponse with raw body data exposed without any permutations.

Arguments

• url - The URL to request
• options - Optional request options to customize this specific request

Examples

use hyper_custom_cert::{HttpClient, RequestOptions};
use std::collections::HashMap;

let client = HttpClient::new();

// Basic request with no custom options
let response1 = client.request_with_options("https://example.com", None).await?;

// Request with custom options
let mut headers = HashMap::new();
headers.insert("x-request-id".into(), "abc123".into());
let options = RequestOptions::new().with_headers(headers);
let response2 = client.request_with_options("https://example.com", Some(options)).await?;

pub async fn request_with_options( &self, url: &str, options: Option<RequestOptions>, ) -> Result<HttpResponse, ClientError>

Performs a GET request and returns the raw response body. This method constructs a hyper::Request with the GET method and any default headers configured on the client, then dispatches it via perform_request. Returns HttpResponse with raw body data exposed without any permutations.

Arguments

• url - The URL to request
• options - Optional request options to customize this specific request

Examples

use hyper_custom_cert::{HttpClient, RequestOptions};
use std::collections::HashMap;

let client = HttpClient::new();

// Basic request with no custom options
let response1 = client.request_with_options("https://example.com", None).await?;

// Request with custom options
let mut headers = HashMap::new();
headers.insert("x-request-id".into(), "abc123".into());
let options = RequestOptions::new().with_headers(headers);
let response2 = client.request_with_options("https://example.com", Some(options)).await?;

Examples found in repository

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

async 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 (now returns HttpResponse with raw body data)
    let _response = client
        .request_with_options("https://example.com", None)
        .await
        .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_with_options("https://private.local", None)
            .await;

        // 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_with_options("https://localhost:8443", None)
            .await;

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

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

pub async fn post<B: AsRef<[u8]>>( &self, url: &str, body: B, ) -> Result<HttpResponse, ClientError>

👎Deprecated since 0.4.0: Use post_with_options(url, body, Some(options)) instead

Performs a POST request with the given body and returns the raw response. Similar to request, this method builds a hyper::Request for a POST operation, handles the request body conversion to Bytes, and applies default headers before calling perform_request. Returns HttpResponse with raw body data exposed without any permutations.

Arguments

• url - The URL to request
• body - The body content to send with the POST request
• options - Optional request options to customize this specific request

Examples

use hyper_custom_cert::{HttpClient, RequestOptions};
use std::collections::HashMap;
use std::time::Duration;

let client = HttpClient::new();

// Basic POST request with no custom options
let response1 = client.post_with_options("https://example.com/api", b"{\"key\":\"value\"}", None).await?;

// POST request with custom options
let mut headers = HashMap::new();
headers.insert("Content-Type".into(), "application/json".into());
let options = RequestOptions::new()
    .with_headers(headers)
    .with_timeout(Duration::from_secs(5));
let response2 = client.post_with_options("https://example.com/api", b"{\"key\":\"value\"}", Some(options)).await?;

pub async fn post_with_options<B: AsRef<[u8]>>( &self, url: &str, body: B, options: Option<RequestOptions>, ) -> Result<HttpResponse, ClientError>

Performs a POST request with the given body and returns the raw response. Similar to request, this method builds a hyper::Request for a POST operation, handles the request body conversion to Bytes, and applies default headers before calling perform_request. Returns HttpResponse with raw body data exposed without any permutations.

Arguments

• url - The URL to request
• body - The body content to send with the POST request
• options - Optional request options to customize this specific request

Examples

use hyper_custom_cert::{HttpClient, RequestOptions};
use std::collections::HashMap;
use std::time::Duration;

let client = HttpClient::new();

// Basic POST request with no custom options
let response1 = client.post_with_options("https://example.com/api", b"{\"key\":\"value\"}", None).await?;

// POST request with custom options
let mut headers = HashMap::new();
headers.insert("Content-Type".into(), "application/json".into());
let options = RequestOptions::new()
    .with_headers(headers)
    .with_timeout(Duration::from_secs(5));
let response2 = client.post_with_options("https://example.com/api", b"{\"key\":\"value\"}", Some(options)).await?;

Trait Implementations

impl Default for HttpClient

Default construction uses builder defaults.

fn default() -> Self

Returns the “default value” for a type.