qubit-http - English

Documentation: User Guide | API Reference

qubit-http is a production-oriented Rust HTTP infrastructure crate for building API clients with consistent behavior across services.

It builds on reqwest and provides the common pieces most API clients need: request construction, timeouts, retries, cancellation, streaming responses, SSE, logging, and unified errors.

Why Use It

Use qubit-http when you need:

one request execution flow for buffered, lazy, and streaming response bodies
shared timeout, retry, cancellation, proxy, redirect, and logging behavior
consistent error handling through HttpError, HttpErrorKind, and RetryHint
built-in helpers for JSON, form, multipart, NDJSON, streaming, and SSE
config-driven client creation for service-level consistency

For full examples and advanced options, read the User Guide.

Installation

[dependencies]
qubit-http = "0.8"
http = "1"
tokio = { version = "1", features = ["macros", "rt-multi-thread"] }

Some examples in the user guide use optional helper crates such as serde, serde_json, futures-util, and qubit-config.

Quick Start

This example uses httpbin.org, so you can run it without starting a local test server.

use http::Method;
use qubit_http::{HttpClientFactory, HttpClientOptions};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut options = HttpClientOptions::new();
    options.set_base_url("https://httpbin.org")?;
    options.add_header("x-client-id", "demo")?;

    let client = HttpClientFactory::new().create(options)?;

    let request = client
        .request(Method::GET, "/anything")
        .query_param("from", "readme")
        .build();

    let mut response = client.execute(request).await?;
    println!("status = {}", response.status());
    println!("text = {}", response.text().await?);
    Ok(())
}

Logging Sanitization

HTTP TRACE logs are sanitized before they are emitted. The default policy masks URL userinfo/fragments, sensitive headers, query parameters, and JSON/form/multipart body fields with shared field matching and mask levels. The built-in names and mask levels come from qubit_sanitize::SensitiveFields. Unsupported bodies without a structured or textual Content-Type are redacted instead of being logged raw. Multipart file parts and malformed, missing-boundary, or truncated multipart bodies are redacted as well. You can extend the policy when a service uses custom secret names. Names are matched case-insensitively across common styles such as access_token, access-token, and accessToken:

use qubit_http::{HttpClientFactory, HttpClientOptions};
use qubit_sanitize::SensitivityLevel;

let mut options = HttpClientOptions::new();
options.logging.enabled = true;
options.logging.log_request_body = true;
options
    .log_sanitize_policy
    .sensitive_headers
    .insert("x-api-key", SensitivityLevel::High);
options
    .log_sanitize_policy
    .sensitive_query_params
    .insert("access_token", SensitivityLevel::High);
options
    .log_sanitize_policy
    .sensitive_body_fields
    .insert("password", SensitivityLevel::Secret);

let client = HttpClientFactory::new().create(options)?;

Common Next Steps

Task	Read
Create clients from defaults, options, or config	User Guide
Build JSON, form, multipart, NDJSON, or stream request bodies	User Guide
Add default headers, header injectors, and interceptors	User Guide
Configure timeouts, retries, cancellation, and `Retry-After` handling	User Guide
Read bytes, text, JSON, streams, or SSE chunks	User Guide
Configure logging sanitization, proxy, redirects, and IPv4-only mode	User Guide
Handle status, transport, timeout, cancellation, decode, and retry errors	User Guide

Core API At A Glance

Type	Purpose
`HttpClientFactory`	Creates clients from defaults, explicit options, or config.
`HttpClientOptions`	Holds client-level defaults for base URL, headers, timeouts, retry, logging, proxy, redirects, connection pool, and SSE decoding.
`HttpClient`	Executes requests and applies headers, injectors, interceptors, retry, logging, and SSE reconnect helpers.
`HttpRequestBuilder`	Builds method, path, query, headers, body, and request-level overrides.
`HttpResponse`	Exposes response metadata and lazy readers for bytes, text, JSON, streams, and SSE.
`HttpResponseInterceptorContext`	Lets response interceptors inspect status/method and mutate headers/final URL without breaking success-status invariants.

Project Scope

qubit-http is built on top of reqwest; it focuses on a stable shared HTTP surface rather than exposing every reqwest API.
Response bodies are read lazily unless TRACE response-body logging is enabled.
Built-in request retry covers failures before HttpResponse is returned. Stream body errors after return are surfaced to the caller.
SSE reconnect has a dedicated API: HttpClient::execute_sse_with_reconnect(...).

Contributing

Issues and pull requests are welcome.

Please keep contributions focused and easy to review:

open an issue for bug reports, design questions, or larger feature proposals
keep pull requests scoped to one behavior change, fix, or documentation update
follow the Rust coding style
include tests when changing runtime behavior
update the user guide or README when public API behavior changes

By contributing to this project, you agree that your contribution will be licensed under the same license as the project.

License

Licensed under the Apache License, Version 2.0.