HTTP Client Trait - WhatsApp Rust

Overview

The HTTP client abstraction provides a runtime-agnostic interface for making HTTP requests. It’s primarily used for:

Media uploads to WhatsApp servers
Media downloads (with streaming support)
Fetching metadata and authentication tokens

The client supports both buffered and streaming responses for efficient handling of large files.

HttpClient Trait

use async_trait::async_trait;
use wacore::sync_marker::MaybeSendSync;

#[cfg_attr(target_arch = "wasm32", async_trait(?Send))]
#[cfg_attr(not(target_arch = "wasm32"), async_trait)]
pub trait HttpClient: MaybeSendSync {
    /// Executes a given HTTP request and returns the response
    async fn execute(&self, request: HttpRequest) -> Result<HttpResponse>;

    /// Whether this client supports synchronous streaming downloads.
    /// Defaults to `false`. Override to return `true` if you implement
    /// `execute_streaming`.
    fn supports_streaming(&self) -> bool { false }

    /// Synchronous streaming variant. Returns a reader over the response body
    /// instead of buffering it all in memory.
    /// 
    /// Must be called from a blocking context (e.g. inside `spawn_blocking`).
    /// Returns an error by default if not implemented.
    fn execute_streaming(&self, request: HttpRequest) -> Result<StreamingHttpResponse>;

    /// Whether this client can stream a request body from a reader (upload).
    /// Defaults to `false`. Override alongside `execute_upload` to enable
    /// constant-memory uploads via `Client::upload_stream`.
    fn supports_upload_streaming(&self) -> bool { false }

    /// Synchronous streaming upload: send `body` (exactly `content_length`
    /// bytes) as the request body. Implementations MUST set an explicit
    /// `Content-Length` header rather than chunked transfer-encoding (the
    /// WhatsApp CDN rejects chunked uploads). Any body set on `request` is
    /// ignored. Must be called from a blocking context.
    fn execute_upload(
        &self,
        request: HttpRequest,
        body: UploadBody,        // = Box<dyn std::io::Read + Send>
        content_length: u64,
    ) -> Result<HttpResponse>;
}

MaybeSendSync is Send + Sync on native targets and carries no bounds on wasm32. Custom HttpClient implementations backed by !Send browser fetch handles now compile on the wasm port. On native, Arc<dyn HttpClient> remains Send + Sync as before.

supports_upload_streaming / execute_upload were added in v0.6 to back Client::upload_stream. Both have safe defaults (returning false / an error), so existing custom HttpClient implementations keep compiling — implement them only if you want constant-memory uploads through your client. UreqHttpClient implements both. UploadBody is Box<dyn std::io::Read + Send>.

Return Ok for every completed exchange, even a non-2xx status. Reserve Err for a request that never completed — DNS failure, connection refused, a TLS error, or a timeout.execute and execute_upload have one more Err case. If you read a 2xx body past your declared cap (max_body_bytes on UreqHttpClient), fail that read — a truncated payload must never look like a complete one. execute_streaming doesn’t raise this error: its reader just reaches EOF at the cap, and a downstream integrity check (MAC or SHA) catches the truncation instead. See Internal Implementation for how UreqHttpClient implements both halves of this.Read status_code off the Ok response to decide what to do next. Download and upload both use it to refresh a stale media-auth token (401/403) and to move to the next CDN host on other errors like 5xx — see download’s retry and URL re-derivation and upload’s retry on auth errors. Download has one case upload doesn’t: it treats an expired URL (404/410) the same as an auth error and re-derives it. If you map 4xx/5xx to Err instead, you hide the status from all of this, and every retry repeats the same stale auth token.Some HTTP crates default the wrong way. ureq’s http_status_as_error turns non-2xx into an Err unless you disable it, which is why UreqHttpClient disables it on every request. If you build a custom client on ureq or a similar library, disable that default yourself. MockHttpClient below shows the shape a compliant implementation should have: Err only when there’s no response to give at all.

Methods

supports_streaming

Returns whether this HTTP client supports synchronous streaming downloads via execute_streaming. The default implementation returns false. When this returns false, download_to_writer automatically falls back to a buffered download using execute instead.

fn supports_streaming(&self) -> bool { false }

Returns:

true if execute_streaming is implemented (e.g., UreqHttpClient)
false (default) if streaming is not supported

execute

Executes an HTTP request and buffers the entire response body.

async fn execute(&self, request: HttpRequest) -> Result<HttpResponse>;

Parameters:

request: HttpRequest - The request to execute

Returns:

HttpResponse for any completed exchange — a non-2xx status_code is still Ok; read it to classify the response
anyhow::Error when the request never completed (a transport-level failure), or when a 2xx body exceeds your configured cap

Example:

let request = HttpRequest::get("https://api.example.com/data")
    .with_header("Authorization", "Bearer token");

let response = client.execute(request).await?;
println!("Status: {}", response.status_code);
println!("Body: {:?}", response.body);

execute_streaming

Executes an HTTP request and returns a streaming reader over the response body. Important: This is a synchronous method that must be called from within tokio::task::spawn_blocking.

fn execute_streaming(&self, request: HttpRequest) -> Result<StreamingHttpResponse>;

Parameters:

request: HttpRequest - The request to execute

Returns:

StreamingHttpResponse for any completed exchange — a non-2xx status_code is still Ok
anyhow::Error on a transport-level failure, or if streaming is not supported. A body past your cap is not one of these cases — the reader reaches EOF early instead; see the contract note above

Example:

let http_client = Arc::new(UreqHttpClient::new());
let request = HttpRequest::get("https://mmg.whatsapp.net/large-file.enc");

// Must be called inside spawn_blocking
let response = tokio::task::spawn_blocking(move || {
    http_client.execute_streaming(request)
}).await??;

// Read in chunks
let mut buffer = vec![0u8; 4096];
while let Ok(n) = response.body.read(&mut buffer) {
    if n == 0 { break; }
    // Process chunk
}

resource_report

Best-effort per-session footprint of this client: idle connection-pool buffers plus any in-flight download/media buffering the implementation can see. Defaulted to None (“not reported”) — a client that can introspect its pool overrides it.

fn resource_report(&self) -> Option<wacore::stats::HttpResourceReport> {
    None
}

Returns:

Some(HttpResourceReport) with any subset of pool_connections, pool_buffer_bytes, inflight_bytes filled in (each Option<u64>)
None (default) if the client doesn’t report

Feeds into Client::resource_report(). UreqHttpClient overrides this (below) with an estimate for its default agent’s idle pool; media downloads are a real transient-RAM source, so even a coarse estimate is worth reporting.

Data Structures

HttpRequest

Represents an HTTP request with headers and optional body.

pub struct HttpRequest {
    pub url: String,
    pub method: String,  // "GET" or "POST"
    pub headers: HashMap<String, String>,
    pub body: Option<Vec<u8>>,
}

Constructors

// GET request
let request = HttpRequest::get("https://example.com/data");

// POST request
let request = HttpRequest::post("https://example.com/upload");

Builder Methods

// Add header
let request = HttpRequest::get("https://example.com/data")
    .with_header("Authorization", "Bearer token")
    .with_header("Content-Type", "application/json");

// Add body (for POST)
let body = b"{\"key\": \"value\"}";
let request = HttpRequest::post("https://example.com/upload")
    .with_body(body.to_vec());

HttpResponse

Represents an HTTP response with buffered body.

pub struct HttpResponse {
    pub status_code: u16,
    pub body: Vec<u8>,
}

Methods

// Convert body to string
let text = response.body_string()?;
println!("Response text: {}", text);

StreamingHttpResponse

Represents an HTTP response with streaming body reader.

pub struct StreamingHttpResponse {
    pub status_code: u16,
    pub body: Box<dyn std::io::Read + Send>,
}

Usage:

use std::io::Read;

let mut buffer = vec![0u8; 8192];
loop {
    match response.body.read(&mut buffer) {
        Ok(0) => break,  // EOF
        Ok(n) => {
            // Process n bytes from buffer
            process_chunk(&buffer[..n]);
        }
        Err(e) => return Err(e.into()),
    }
}

UreqHttpClient

The default HTTP client implementation using the ureq crate (v3.4) for synchronous HTTP requests.

Features

Blocking I/O - Uses synchronous ureq, wrapped in tokio::task::spawn_blocking
Connection pooling - Shares a ureq::Agent across requests for connection reuse
Streaming support - Implements efficient streaming downloads
Simple API - Minimal configuration required
Thread-safe - Implements Clone for easy sharing (cloning the Agent is cheap)
TLS via rustls - Uses rustls for TLS, with optional danger-skip-tls-verify for testing

Creating a client

use whatsapp_rust_ureq_http_client::UreqHttpClient;

// Basic usage — creates a shared ureq::Agent internally
let client = UreqHttpClient::new();

// Or use default
let client = UreqHttpClient::default();

// With a pre-configured agent (proxy, custom TLS, timeouts, etc.)
let agent = ureq::Agent::new_with_config(
    ureq::config::Config::builder()
        // your custom settings here
        .build()
);
let client = UreqHttpClient::with_agent(agent);

with_agent

pub fn with_agent(agent: ureq::Agent) -> Self

Creates a client with a pre-configured ureq::Agent. This lets you configure proxy support, custom TLS, timeouts, or any other agent-level settings externally. This is the primary extension point for customizing HTTP behavior — for example, routing media uploads and downloads through a proxy, or using custom CA certificates. Parameters:

agent - A pre-configured ureq::Agent

Example — proxy support:

use ureq::config::Config;

let agent: ureq::Agent = Config::builder()
    .proxy(ureq::Proxy::new("socks5://127.0.0.1:1080")?)
    .build()
    .into();

let client = UreqHttpClient::with_agent(agent);

See custom backends — proxy and custom TLS for a complete guide.

The version fetch does not pool a connection

Client::connect() fetches a version update unless you’ve set with_version or the cached version is under 24h old. The source depends on the target: everywhere except wasm32, it’s https://web.whatsapp.com/sw.js; that request sends Connection: close, so ureq drops the connection at cleanup instead of returning it to the pool. Previously this fetch left one idle TLS connection resident for the rest of the session, even for a session that never touched media, measured at roughly 88 KiB of RssAnon per session. This change eliminates that idle-connection cost. It doesn’t guarantee zero residual state, though — a shared agent can still retain a small TLS session-resumption ticket after the handshake (see below). On wasm32, sw.js can’t be reached from a page. It only answers 200 to a Sec-Fetch-Site: none request. That’s a forbidden header name a script can’t set, so a browser drops it and gets a 400 instead. No response from web.whatsapp.com carries Access-Control-Allow-Origin either, so a request that got past the header would still fail cross-origin. So the wasm build instead reads the same build revision from https://connect.facebook.net/en_US/sdk.js — the Facebook JS SDK bundle. Meta serves it with Access-Control-Allow-Origin: * for cross-origin loading, with no fetch-metadata gate. The number is Meta’s shared www build revision. It’s identical across web.whatsapp.com, facebook.com, instagram.com, and messenger.com, so it’s the same revision sw.js would have reported. The request adds no headers of its own. There’s no fallback between the two sources — whichever one applies to the target is the only one tried, never the other. What happens after a failure there differs by target, though: on native, it surfaces as ConnectError::Version. On wasm32, as of PR #1360, it usually doesn’t — the connection survives on the version the device already holds, and Event::Connected reports the fallback via app_version_fallback instead. See Connected for when that fallback fires and when a wasm32 failure still reaches ConnectError::Version. resource_report() reflects the same change for the default client: a request carrying Connection: close is treated as non-pooling, so a session using UreqHttpClient::new() whose only HTTP traffic is the version fetch reports an empty pool (pool_connections: Some(0), pool_buffer_bytes: Some(0)) instead of latching onto the 96 KiB cap described below after its first request. A client created with UreqHttpClient::with_agent(...) continues to report None because its pool configuration is opaque. Media requests are untouched by this — the pool still exists there to make the next range request against the same CDN host cheap. If your process runs many WhatsApp sessions, build one UreqHttpClient. Wrap it in an Arc and pass it to every builder with BotBuilder::with_http_client_arc instead of constructing one per session. UreqHttpClient is also Clone, and cloning it shares the underlying ureq::Agent and therefore its connection pool — so with_http_client(shared_http_client.clone()) shares just as well. Reach for with_http_client_arc instead once the client is already type-erased to Arc<dyn HttpClient>, since nothing lets that reach the by-value setter at all. This is worth doing for a process with pooled HTTP traffic — media, in practice. An idle session retains no idle connection-pool buffers (on the non-wasm32 targets UreqHttpClient runs on, the version fetch sends Connection: close, so it pools no connection either way — though a shared agent can still hold onto a small TLS session-resumption ticket, see above), but a session that has transferred media retains its own connection-pool buffers — on the order of tens of KiB of live heap over plain HTTP, more over TLS — for as long as its UreqHttpClient lives. Building one per bot pays that cost once per session; sharing collapses the whole fleet onto one pool. Does sharing serialize requests? No. ureq::Agent holds its pool lock only across checkout, never across the request itself, so concurrent requests through one shared client run concurrently — each still occupies its own spawn_blocking thread, exactly as it would with a client per bot. What sharing does change: the idle pool is capped per agent, not per bot. UreqHttpClient::new()’s default agent retains 3 idle connections and 2 per host — sized for one bot’s traffic, not a fleet’s. Share it across several concurrent workers and they now contend over that one small pool; measured at 8 concurrent workers, a shared default agent reused ~80% of connections versus ~95% with one client each. If you’re sharing across meaningful concurrency, size a ureq::Agent for the fleet with with_agent before sharing it, raising both max_idle_connections and max_idle_connections_per_host. Raising only the global cap can still leave you bottlenecked: media traffic concentrates on a small, fixed set of CDN hosts — WhatsApp’s default media route is two, a primary and a fallback — so whichever of those hosts a request lands on, the per-host cap of 2 binds well before the global one does. Sized for the fleet, reuse comes back in line with a client per bot while retention stays collapsed into one pool. You can share the connection with the same per-request auth guarantees as an unshared one. Media requests carry their own auth per request, and the client sends no cookies. A shared connection therefore doesn’t leak anything between sessions beyond what the shared source IP already reveals — with two exceptions. A live pooled connection reused across sessions lets the CDN see both sessions’ requests on the same TCP/TLS stream, a stronger correlation signal than a shared IP alone. TLS session resumption is the other: it lets a server correlate two sessions even across a source-IP change. Both are why sharing stays opt-in rather than the default.

use std::sync::Arc;
use whatsapp_rust::http::{HttpClient, UreqHttpClient};

let shared_http_client: Arc<dyn HttpClient> = Arc::new(UreqHttpClient::new());
let mut handles = Vec::new();

for backend in session_backends {
    let bot = Bot::builder()
        .with_backend(backend)
        .with_http_client_arc(shared_http_client.clone())
        // ...
        .build()
        .await?;

    // spawn() runs the bot in the background and returns a BotHandle;
    // keep it so the handle (and the task it tracks) isn't dropped.
    handles.push(bot.spawn());
}

Usage Examples

Basic GET Request

use whatsapp_rust_ureq_http_client::UreqHttpClient;
use wacore::net::HttpRequest;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = UreqHttpClient::new();
    
    let request = HttpRequest::get("https://api.example.com/data")
        .with_header("User-Agent", "whatsapp-rust");
    
    let response = client.execute(request).await?;
    
    if response.status_code == 200 {
        println!("Success! Body length: {}", response.body.len());
    }
    
    Ok(())
}

POST request with body

let client = UreqHttpClient::new();

let body = serde_json::to_vec(&json!({
    "key": "value",
    "number": 42
}))?;

let request = HttpRequest::post("https://api.example.com/upload")
    .with_header("Content-Type", "application/json")
    .with_body(body);

let response = client.execute(request).await?;

Streaming Download

use std::fs::File;
use std::io::Write;

let client = Arc::new(UreqHttpClient::new());
let url = "https://mmg.whatsapp.net/file.enc";

// Must use spawn_blocking for streaming
let file_data = tokio::task::spawn_blocking(move || -> Result<Vec<u8>> {
    let request = HttpRequest::get(url);
    let response = client.execute_streaming(request)?;
    
    if response.status_code != 200 {
        return Err(anyhow::anyhow!("HTTP {}", response.status_code));
    }
    
    let mut buffer = vec![0u8; 65536];
    let mut output = Vec::new();
    let mut reader = response.body;
    
    loop {
        match reader.read(&mut buffer) {
            Ok(0) => break,
            Ok(n) => output.extend_from_slice(&buffer[..n]),
            Err(e) => return Err(e.into()),
        }
    }
    
    Ok(output)
}).await??;

println!("Downloaded {} bytes", file_data.len());

Internal Implementation

The UreqHttpClient wraps a shared ureq::Agent for connection pooling. All requests go through the agent rather than standalone ureq::get()/ureq::post() functions:

#[derive(Debug, Clone)]
pub struct UreqHttpClient {
    agent: ureq::Agent,
    /// Cap for `execute` and the reader `execute_streaming` returns.
    /// Defaults to WhatsApp's 2 GiB max file size; override with `with_max_body_bytes`.
    max_body_bytes: u64,
}

impl UreqHttpClient {
    pub fn new() -> Self {
        Self {
            agent: ureq::Agent::new_with_defaults(),
            max_body_bytes: DEFAULT_MAX_BODY_BYTES, // 2 GiB
        }
    }
}

When the danger-skip-tls-verify feature is enabled, the agent is built with TLS verification disabled:

use ureq::config::Config;
use ureq::tls::TlsConfig;

let agent: ureq::Agent = Config::builder()
    .tls_config(TlsConfig::builder().disable_verification(true).build())
    .build()
    .into();

UreqHttpClient::new() (the default agent) tracks whether it has ever dispatched a request it could actually send. Before that, resource_report() reports pool_connections: Some(0), pool_buffer_bytes: Some(0), inflight_bytes: None — ureq allocates its buffers per connection, not per agent, so a client that has never connected really does hold an empty pool. Once a request has gone out, it reports the cap instead: up to 3 idle connections, each with a 16 KiB input and 16 KiB output buffer, so pool_connections: Some(3), pool_buffer_bytes: Some(96 * 1024). That cap is an upper bound estimate, not a live measurement, and it stays set even if every subsequent request fails — a failed or redirected request still opens (or reuses) a connection, so the pool is no longer provably empty. “Dispatched” is decided before the request goes on the wire — a request ureq itself refuses to build (an unsupported method, a malformed URI, or a header it rejects) never flips the flag, and neither does a request that reaches the wire but carries Connection: close (see above): ureq closes that connection at cleanup instead of pooling it, so nothing is retained for the flag to describe. UreqHttpClient::with_agent(...) (a caller-supplied agent) reports None throughout — its buffer and pool configuration is opaque, and since every clone of that agent shares one pool it may already have connected before reaching this client, so an empty pool isn’t a safe guess either. Cloning a client shares the underlying ureq::Agent and therefore its pool: a request made through one clone is reflected in every other clone’s resource_report(), including clones held by other sessions when you’ve shared one client across many sessions. pool_connections and pool_buffer_bytes describe that one shared pool, not a per-session allocation. If you sum Client::resource_report().await.http across sessions that share a client, sum it once for the shared agent instead of once per session — otherwise you count the same pool N times over. ureq 3.4 treats any 4xx/5xx as ureq::Error::StatusCode by default — the opposite of the HttpClient contract above. UreqHttpClient sends every request through status_as_response, which disables http_status_as_error per request instead of once on the shared agent. That placement matters: a caller-supplied agent from with_agent carries ureq’s own defaults, not UreqHttpClient’s, so only a per-request override reaches it too:

fn status_as_response<Any>(req: ureq::RequestBuilder<Any>) -> ureq::RequestBuilder<Any> {
    req.config().http_status_as_error(false).build()
}

The execute method clones the agent and wraps the call in spawn_blocking:

#[async_trait]
impl HttpClient for UreqHttpClient {
    async fn execute(&self, request: HttpRequest) -> Result<HttpResponse> {
        let agent = self.agent.clone();
        let max_body_bytes = self.max_body_bytes;
        // ureq is blocking, so wrap in spawn_blocking
        tokio::task::spawn_blocking(move || {
            let response = match request.method.as_str() {
                "GET" => {
                    let mut req = status_as_response(agent.get(&request.url));
                    for (key, value) in &request.headers {
                        req = req.header(key, value);
                    }
                    req.call()?
                }
                "POST" => {
                    let mut req = status_as_response(agent.post(&request.url));
                    for (key, value) in &request.headers {
                        req = req.header(key, value);
                    }
                    if let Some(body) = request.body {
                        req.send(&body[..])?
                    } else {
                        req.send(&[])?
                    }
                }
                method => {
                    return Err(anyhow::anyhow!("Unsupported HTTP method: {}", method));
                }
            };

            let status_code = response.status().as_u16();
            let body = read_body(response, max_body_bytes)?;

            Ok(HttpResponse { status_code, body })
        })
        .await?
    }
}

read_body is where the non-2xx contract meets your max_body_bytes cap, and it treats the two cases differently. A 2xx body is the payload, so an over-cap read stays an Err — you must never mistake a truncated media file for a complete one. A non-2xx body is diagnostic text (an error page), so read_body truncates it instead of erroring. That truncation cap is 64 KiB on top of max_body_bytes, not instead of it: losing the tail of an error page costs nothing, but losing the status code costs the media-conn refresh:

const ERROR_BODY_CAP: u64 = 64 * 1024;

fn read_body(response: ureq::http::Response<ureq::Body>, max_body_bytes: u64) -> Result<Vec<u8>> {
    if response.status().is_success() {
        return Ok(response
            .into_body()
            .into_with_config()
            .limit(max_body_bytes)
            .read_to_vec()?);
    }

    let mut body = Vec::new();
    let mut reader = std::io::Read::take(
        response.into_body().into_reader(),
        max_body_bytes.min(ERROR_BODY_CAP),
    );
    // A read that fails partway still leaves the status worth returning.
    let _ = std::io::Read::read_to_end(&mut reader, &mut body);
    Ok(body)
}

The execute_streaming method is synchronous (no spawn_blocking) because it’s called from within a blocking context. It also uses the shared agent and status_as_response:

fn execute_streaming(&self, request: HttpRequest) -> Result<StreamingHttpResponse> {
    let response = match request.method.as_str() {
        "GET" => {
            let mut req = status_as_response(self.agent.get(&request.url));
            for (key, value) in &request.headers {
                req = req.header(key, value);
            }
            req.call()?
        }
        method => {
            return Err(anyhow::anyhow!(
                "Streaming only supports GET, got: {}",
                method
            ));
        }
    };

    let status_code = response.status().as_u16();
    let reader = std::io::Read::take(response.into_body().into_reader(), self.max_body_bytes);

    Ok(StreamingHttpResponse {
        status_code,
        body: Box::new(reader),
    })
}

Notice execute_streaming doesn’t error when a body exceeds max_body_bytes, unlike read_body above. std::io::Read::take reaches EOF at the cap instead of raising an error, so execute_streaming itself always returns Ok once the response headers arrive. That silent truncation is safe inside Client::download and download_to_writer: they decrypt the result and verify a MAC or SHA over it, so a body truncated at the cap fails that check instead of passing as a complete file. It is not safe if you call execute_streaming directly, the way the Streaming Download example above does — that example has no integrity check of its own, so a truncated body would come back as an ordinary success. If you call execute_streaming directly, check the response against an expected length (a Content-Length header, for example) or your own integrity check before you trust it. execute_upload follows the buffered shape, not the streaming one: it applies status_as_response to the request builder, then reads the response through read_body. This is what makes upload’s auth-error retry reachable at all. Before this fix, a rejected upload’s status was swallowed into an opaque transport error, so the media-conn refresh it should have triggered never ran.

Implementing custom HTTP clients

You can implement custom HTTP clients for different runtimes or requirements.

Example: Reqwest client (async)

use async_trait::async_trait;
use wacore::net::{HttpClient, HttpRequest, HttpResponse};

#[derive(Clone)]
pub struct ReqwestHttpClient {
    client: reqwest::Client,
}

impl ReqwestHttpClient {
    pub fn new() -> Self {
        Self {
            client: reqwest::Client::new(),
        }
    }
}

#[async_trait]
impl HttpClient for ReqwestHttpClient {
    async fn execute(&self, request: HttpRequest) -> Result<HttpResponse> {
        let mut req = match request.method.as_str() {
            "GET" => self.client.get(&request.url),
            "POST" => self.client.post(&request.url),
            method => return Err(anyhow::anyhow!("Unsupported method: {}", method)),
        };
        
        // Add headers
        for (key, value) in request.headers {
            req = req.header(key, value);
        }
        
        // Add body for POST
        if let Some(body) = request.body {
            req = req.body(body);
        }
        
        let response = req.send().await?;
        let status_code = response.status().as_u16();
        let body = response.bytes().await?.to_vec();
        
        Ok(HttpResponse { status_code, body })
    }
    
    // supports_streaming() defaults to false, so download_to_writer
    // will use a buffered fallback automatically — no need to implement
    // execute_streaming.
}

Notice what this example doesn’t do: it never calls .error_for_status(). reqwest::RequestBuilder::send() (req.send() above) already returns Ok for a non-2xx status by default, so this example matches the HttpClient contract for free. Don’t add .error_for_status() here — it turns every 4xx/5xx into an Err and breaks the contract.

Example: mock client for testing

use async_trait::async_trait;
use std::collections::HashMap;

pub struct MockHttpClient {
    responses: HashMap<String, HttpResponse>,
}

impl MockHttpClient {
    pub fn new() -> Self {
        Self {
            responses: HashMap::new(),
        }
    }
    
    pub fn with_response(mut self, url: &str, response: HttpResponse) -> Self {
        self.responses.insert(url.to_string(), response);
        self
    }
}

#[async_trait]
impl HttpClient for MockHttpClient {
    async fn execute(&self, request: HttpRequest) -> Result<HttpResponse> {
        self.responses
            .get(&request.url)
            .cloned()
            .ok_or_else(|| anyhow::anyhow!("No mock response for {}", request.url))
    }
}

// Usage in tests:
let client = MockHttpClient::new()
    .with_response(
        "https://api.example.com/test",
        HttpResponse {
            status_code: 200,
            body: b"test data".to_vec(),
        },
    );

Usage with Bot builder

use whatsapp_rust::Bot;
use whatsapp_rust_ureq_http_client::UreqHttpClient;
use std::sync::Arc;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let http_client = UreqHttpClient::new();
    
    let mut bot = Bot::builder()
        .with_backend(backend)
        .with_transport_factory(transport_factory)
        .with_http_client(http_client)
        .on_event(|event, client| async move { /* handle events */ })
        .build()
        .await?;
    
    Ok(())
}

Best Practices

Blocking operations - Always wrap blocking HTTP libraries in tokio::task::spawn_blocking
Streaming for large files - Use execute_streaming for media downloads to avoid buffering
Error handling - Return descriptive errors with context
Timeouts - ureq 3.4 applies per-IP connection timeouts automatically; implement request-level timeouts for reliability
Retries - Consider retry logic for transient failures
Connection pooling - Use a shared ureq::Agent (as UreqHttpClient does) for connection reuse within a session, and share one UreqHttpClient across sessions when running many of them in one process

Media Operations

The HTTP client is primarily used for media operations in whatsapp-rust:

Media upload flow

The client manages media connections internally. Use the high-level upload method instead of building requests manually:

use whatsapp_rust::download::MediaType;

// Upload handles encryption, auth, and CDN host selection automatically
let upload_response = client.upload(media_bytes, MediaType::Image, Default::default()).await?;

Under the hood, the client uses the HTTP client to:

Fetch media connection credentials from WhatsApp servers
Encrypt the media with AES-256-CBC
Upload to the CDN with proper auth headers
Parse the response for direct_path and file hashes

Media download flow

// 1. Extract media info from message
let media_info = extract_media_info(&message)?;

// 2. Build download URL
let url = format!("https://mmg.whatsapp.net{}", media_info.direct_path);

// 3. Download with streaming (in spawn_blocking)
let file_data = tokio::task::spawn_blocking(move || {
    let request = HttpRequest::get(&url);
    let response = http_client.execute_streaming(request)?;
    
    // Read and decrypt chunks
    decrypt_media_stream(response.body, &media_key, &expected_sha256)
}).await??;

Testing

Unit test example

#[cfg(test)]
mod tests {
    use super::*;
    
    #[tokio::test]
    async fn test_http_get() {
        let client = UreqHttpClient::new();
        
        let request = HttpRequest::get("https://httpbin.org/get")
            .with_header("User-Agent", "test");
        
        let response = client.execute(request).await.unwrap();
        assert_eq!(response.status_code, 200);
    }
    
    #[tokio::test]
    async fn test_http_post() {
        let client = UreqHttpClient::new();
        
        let body = b"test data";
        let request = HttpRequest::post("https://httpbin.org/post")
            .with_body(body.to_vec());
        
        let response = client.execute(request).await.unwrap();
        assert_eq!(response.status_code, 200);
    }
}

​Overview

​HttpClient Trait

​Methods

​supports_streaming

​execute

​execute_streaming

​resource_report

​Data Structures

​HttpRequest

​Constructors

​Builder Methods

​HttpResponse

​Methods

​StreamingHttpResponse

​UreqHttpClient

​Features

​Creating a client

​with_agent

​The version fetch does not pool a connection

​Sharing one client across many sessions

​Usage Examples

​Basic GET Request

​POST request with body

​Streaming Download

​Internal Implementation

​Implementing custom HTTP clients

​Example: Reqwest client (async)

​Example: mock client for testing

​Usage with Bot builder

​Best Practices

​Media Operations

​Media upload flow

​Media download flow

​Testing

​Unit test example

​See Also

Overview

HttpClient Trait

Methods

supports_streaming

execute

execute_streaming

resource_report

Data Structures

HttpRequest

Constructors

Builder Methods

HttpResponse

Methods

StreamingHttpResponse

UreqHttpClient

Features

Creating a client

with_agent

The version fetch does not pool a connection

Sharing one client across many sessions

Usage Examples

Basic GET Request

POST request with body

Streaming Download

Internal Implementation

Implementing custom HTTP clients

Example: Reqwest client (async)

Example: mock client for testing

Usage with Bot builder

Best Practices

Media Operations

Media upload flow

Media download flow

Testing

Unit test example

See Also