reqx

reqx is an HTTP transport client for Rust API SDK libraries.

It focuses on SDK transport concerns: retries, timeout phases, idempotency, proxy routing, structured errors, and metrics.

For SDK Authors

• Start with a profile: ClientProfile::StandardSdk, ClientProfile::LowLatency, or ClientProfile::HighThroughput.
• Override specific builder knobs only when required after .profile(...).
• Keep strict behavior with StatusPolicy::Error (default), or opt into response-first mode with StatusPolicy::Response.
• For multi-endpoint SDKs, plug in an EndpointSelector (for example RoundRobinEndpointSelector).
• Hook transport events through Observer for retries and server-throttle telemetry.
• Use control_clock(...) only when you need deterministic Retry-After or control-loop behavior in tests.
• See advanced_time_controls for the minimal expert-only setup of control_clock(...) and stream_deadline_slack(...).
• Reach for reqx::advanced::{...} when you need non-default transport controls.

Install

cargo add reqx

Use native-tls:

cargo add reqx --no-default-features -F async-tls-native

Use rustls (ring):

cargo add reqx --no-default-features -F async-tls-rustls-ring

Use rustls + aws-lc-rs:

cargo add reqx --no-default-features -F async-tls-rustls-aws-lc-rs

Use blocking client with ureq + rustls(ring):

cargo add reqx --no-default-features -F blocking-tls-rustls-ring

Use blocking client with ureq + native-tls:

cargo add reqx --no-default-features -F blocking-tls-native

TLS Backends

• feature contract:
  • enable at least one transport mode
  • for each enabled mode (async / blocking), enable exactly one TLS backend
  • enabling both async and blocking is supported
• async backends (default mode):
  • async-tls-rustls-ring (default)
  • async-tls-rustls-aws-lc-rs
  • async-tls-native
• blocking backends (ureq):
  • blocking-tls-rustls-ring
  • blocking-tls-rustls-aws-lc-rs
  • blocking-tls-native
• runtime selection via tls_backend(TlsBackend::...)
• build-time mismatch returns structured error from build()
• trust store selection via tls_root_store(TlsRootStore::BackendDefault | WebPki | System | Specific)
• async TLS version controls via tls_version(...), tls_min_version(...), and tls_max_version(...)
• use tls_max_version(TlsVersion::V1_2) for version-intolerant endpoints that reject TLS 1.3
• async native-tls forwards TLS version bounds to the platform TLS stack
• blocking ureq transports do not expose TLS version selection
• BackendDefault follows each backend's default trust roots
• custom root CA with public roots: tls_root_store(TlsRootStore::WebPki) + tls_root_ca_pem(...) / tls_root_ca_der(...)
• custom root CA only: tls_root_store(TlsRootStore::Specific) + tls_root_ca_pem(...) / tls_root_ca_der(...)
• PEM root CA and certificate-chain inputs must contain only CERTIFICATE blocks; pass private keys through the dedicated identity key parameter.
• mTLS identity:
  • PEM chain + key: tls_client_identity_pem(...) (async + sync)
  • PKCS#12: tls_client_identity_pkcs12(...) (async async-tls-native)

Quick Start

use std::time::Duration;

use reqx::prelude::{Client, RetryPolicy};
use serde::Deserialize;

#[derive(Debug, Deserialize)]
struct CreateItemResponse {
    id: String,
}

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = Client::builder("https://api.example.com")
        .client_name("example-sdk")
        .request_timeout(Duration::from_secs(3))
        .total_timeout(Duration::from_secs(8))
        .retry_policy(
            RetryPolicy::standard()
                .max_attempts(3)
                .base_backoff(Duration::from_millis(100))
                .max_backoff(Duration::from_millis(800)),
        )
        .build()?;

    let created: CreateItemResponse = client
        .post("/v1/items")
        .idempotency_key("create-item-001")?
        .json(&serde_json::json!({ "name": "demo" }))?
        .send_json()
        .await?;

    println!("created id={}", created.id);
    Ok(())
}

Blocking Quick Start

use std::time::Duration;

use reqx::blocking::Client;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = Client::builder("https://api.example.com")
        .request_timeout(Duration::from_secs(3))
        .total_timeout(Duration::from_secs(8))
        .build()?;

    let response = client.get("/v1/items").send()?;
    println!("status={}", response.status());
    Ok(())
}

Core Capabilities

• global defaults + per-request overrides
• profile presets (ClientProfile) + direct builder overrides
• idempotency-aware retries
• retry budget + circuit breaker + adaptive concurrency controls
• global/per-host rate limiting with 429 Retry-After backpressure
• request-level and client-level status handling (StatusPolicy)
• bounded redirect following (RedirectPolicy)
• transport timeout + response-body timeout + total deadline
• stream_deadline_slack(...) tunes only near-deadline streaming error classification when total deadline is already tighter than the body-read timeout; it does not shorten actual I/O waits
• separate connect timeout (connect_timeout(...))
• streaming upload plus ResponseStream: AsyncRead / blocking::ResponseStream: Read
• stream copy_to_writer* / into_bytes_limited keep raw bytes (wire semantics)
• explicit buffered conversion (send(), into_response_limited, into_json_limited) decodes gzip, br, deflate, zstd for both async and blocking
• proxy support with auth and no_proxy
• blocking mode proxy auth contract: for blocking-* features, configure proxy credentials in http_proxy URI (http://user:pass@proxy:port); direct proxy_authorization(...) forwarding is intentionally rejected by ureq transport
• interceptor hooks for SDK concerns (Interceptor)
• response body size limit
• structured error variants + machine error codes
• stable status-error metadata helpers: status_code(), response_headers(), retry_after(), request_id()
• metrics snapshot for retries, latency, status and error buckets
• observer hooks (Observer) for request-start, retry scheduling, and server throttling

Examples

• Full index: examples/README.md
• cargo run --example basic_json
• cargo run --example advanced_time_controls
• cargo run --example request_helpers
• cargo run --example request_overrides
• cargo run --example profile_and_observer
• cargo run --example error_handling
• cargo run --example metrics_snapshot
• cargo run --example streaming
• cargo run --example concurrency_limits
• cargo run --example resilience_controls
• cargo run --example rate_limit_429
• cargo run --example retry_classifier
• cargo run --example proxy_and_no_proxy
• cargo run --example tls_backends
• cargo run --example custom_ca_mtls
• cargo run --example interceptor_redirect
• cargo run --example blocking_basic --no-default-features -F blocking-tls-rustls-ring