Crate reqx 

reqx is a reusable HTTP transport crate for Rust API SDKs with retry, timeout, idempotency, proxy, streaming, and pluggable TLS backends.

Quick Start

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

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

    let client = Client::builder("https://api.example.com")
        .client_name("my-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(())

Recommended Defaults

• Use RetryPolicy::standard() for SDK traffic.
• Set both request timeout and total timeout.
• For POST retries, always set idempotency_key(...).
• Reach for advanced when you need non-default transport controls.

Common Tasks

Start from these entry points:

• Build an async client: Client::builder
• Build a blocking client: reqx::blocking::Client::builder(...)
• Prepare requests: RequestBuilder and reqx::blocking::RequestBuilder
• Handle buffered responses: Response
• Handle streaming responses: ResponseStream and reqx::blocking::ResponseStream
• Tune retries: prelude::RetryPolicy and advanced::RetryClassifier
• Configure TLS: TlsBackend, TlsVersion, and TlsRootStore
• Add advanced hooks: advanced::Interceptor, advanced::Observer, and advanced::EndpointSelector

Feature Selection

Transport modes are selected through concrete transport+TLS feature flags:

• Async + rustls + ring: async-tls-rustls-ring
• Async + rustls + aws-lc-rs: async-tls-rustls-aws-lc-rs
• Async + native-tls: async-tls-native
• Blocking + ureq + rustls + ring: blocking-tls-rustls-ring
• Blocking + ureq + rustls + aws-lc-rs: blocking-tls-rustls-aws-lc-rs
• Blocking + ureq + native-tls: blocking-tls-native

The docs.rs build enables async-tls-rustls-ring and blocking-tls-rustls-ring, so async and blocking entry points are both visible there.

Cookbook

Scenario-focused examples ship in examples/:

• JSON request flow: examples/basic_json.rs
• Per-request overrides: examples/request_overrides.rs
• Streaming uploads/downloads: examples/streaming.rs and examples/blocking_streaming.rs
• Proxy and no_proxy: examples/proxy_and_no_proxy.rs
• TLS backend selection and mTLS: examples/tls_backends.rs and examples/custom_ca_mtls.rs
• Metrics and observers: examples/metrics_snapshot.rs and examples/profile_and_observer.rs
• Retry and resilience controls: examples/resilience_controls.rs, examples/retry_classifier.rs, and examples/rate_limit_429.rs
• Resumable uploads: examples/resumable_upload.rs

The full scenario index lives in examples/README.md.

TLS Backend Notes

• Async rustls backends support TLS version bounds via Client::builder(...).tls_version(...), Client::builder(...).tls_min_version(...), and Client::builder(...).tls_max_version(...).
• native-tls backends do not support TlsRootStore::WebPki.
• Async native-tls forwards TLS version bounds to the platform TLS stack.
• Blocking ureq transport currently rejects TLS version bounds at build() time.
• Custom root CAs require TlsRootStore::System or TlsRootStore::Specific.
• Blocking native-tls cannot merge custom root CAs into the system trust store; use TlsRootStore::Specific when adding explicit roots there.

Modules

advanced

Advanced transport controls and extensibility points.

blockingblocking-tls-rustls-ring or blocking-tls-rustls-aws-lc-rs or blocking-tls-native

Blocking transport API.

prelude

Recommended imports for most SDK transport code.

Structs

Clientasync-tls-rustls-ring or async-tls-rustls-aws-lc-rs or async-tls-native

Reusable async HTTP client for SDK transports.

ClientBuilderasync-tls-rustls-ring or async-tls-rustls-aws-lc-rs or async-tls-native

Builds an async Client with transport, timeout, retry, TLS, and observability settings.

RequestBuilderasync-tls-rustls-ring or async-tls-rustls-aws-lc-rs or async-tls-native

Builds and executes a single request against an existing Client.

Response

Fully buffered HTTP response body and metadata.

ResponseStreamasync-tls-rustls-ring or async-tls-rustls-aws-lc-rs or async-tls-native

Streaming async response body with request metadata.

Enums

Error

Error returned by reqx.

ErrorCode

Stable machine-readable error code.

TimeoutPhase

Request phase associated with a timeout.

TlsBackend

TLS backend used by the transport.

TlsRootStore

Root certificate source used when verifying TLS peers.

TlsVersion

Supported TLS protocol versions.

TransportErrorKind

High-level transport failure category.

Type Aliases

Result

Convenient result alias used by reqx APIs.