foghttp 0.3.5

Observable Rust-powered HTTP client for Python services.

FogHTTP

Rust-powered HTTP client for Python with sync and asyncio APIs.

FogHTTP is an early MVP HTTP client. The public API is Python-first, while the transport core is implemented in Rust on top of hyper.

FogHTTP is positioned as an observable, high-concurrency Rust-powered transport for Python services. It is built for controlled service-to-service HTTP workloads where explicit lifecycle, predictable resource usage, cancellation, redirect history, and request backpressure visibility matter more than browser-like feature parity.

Until version 0.5.0, backward compatibility is not guaranteed. I will still try to keep public interfaces stable and avoid unnecessary breaking changes.

Why FogHTTP

• Rust hyper transport with a Python-first API
• sync and asyncio clients with the same request model
• explicit close()/aclose() lifecycle for Rust runtime resources
• graceful sync close() for in-flight requests and cancellable async requests
• global/per-origin request backpressure, per-origin acquire pressure stats, and stuck request diagnostics
• typed telemetry event hooks with redacted request/response lifecycle events
• versioned telemetry snapshots that separate alert-oriented stats from diagnostic dump APIs
• opt-in async lifecycle debug snapshots for staging and tests
• advanced per-client Tokio runtime worker tuning
• focused HTTP surface for JSON, form, streaming upload, and multipart API workloads in internal services, workers, and benchmarks

Install

pip install foghttp

Runtime requirements:

• Python >=3.11
• orjson>=3.11,<4

Quick Start

import foghttp


with foghttp.Client(
    base_url="https://api.example.com",
    headers={"accept": "application/json"},
    params={"api-version": "1"},
) as client:
    response = client.get(
        "users",
        params={"limit": 10},
    )

    response.raise_for_status()
    print(response.status_code)
    print(response.json())

Async clients use the same request API:

import foghttp


async with foghttp.AsyncClient() as client:
    response = await client.post(
        "https://api.example.com/users",
        json={"name": "Ada Lovelace"},
    )
    response.raise_for_status()

What Works Today

• sync Client and async AsyncClient
• GET, HEAD, POST, PUT, PATCH, DELETE
• base_url for reusable API clients and relative request paths
• default client headers and query params for reusable API clients
• query params with repeated keys, JSON, form-urlencoded data, buffered bytes/text bodies, binary file-like request bodies, and streaming bytes-like upload providers
• multipart files= uploads with bytes-like parts, binary file-like objects, direct byte streams, and replayable byte-stream factories
• buffered Response with status flags, charset-aware text, json(), raise_for_status(), and request metadata
• transparent gzip, deflate, and br decoding for buffered responses
• sync and async bytes/text/line response streaming with explicit context-managed lifecycle
• prepared Request objects with build_request() and send()
• case-insensitive Headers with repeated values
• safe policy for transport-managed request headers
• redacted repr/error surfaces for sensitive headers, URL credentials, token-like URL params, and buffered body bytes
• normalized URL model with origin comparison and relative joins
• GET/HEAD/POST redirects with final URL, history, and conservative replay policy
• HTTP proxy routing and HTTPS proxy CONNECT tunnelling through explicit proxy= or trust_env=True when the proxy endpoint uses http://
• HTTPS with default WebPKI roots, explicit custom CA certificates, and custom-only CA trust
• graceful sync close() that waits for in-flight sync requests
• async request cancellation that aborts the in-flight Rust request
• global and per-origin request backpressure, per-origin acquire pressure snapshots, stuck request diagnostics, and HTTP/1.1 over HTTP/HTTPS
• opt-in typed telemetry event hooks for request, redirect, response headers, response body, and request completion lifecycle
• versioned telemetry snapshot metadata for stats(), dump_transport_state(), and dump_pool_diagnostics()
• opt-in async lifecycle debug mode for active request snapshots, strict leak checks, and unclosed-client diagnostics
• default per-response and aggregate buffered response body limits for memory safety
• advanced per-client Tokio runtime worker tuning
• grouped HTTP status constants and reusable HTTP method constants

Documentation

• Documentation
• Quickstart
• Request builder compatibility
• Client lifecycle
• Timeout model
• Upload typing contracts
• Telemetry contract
• Response streaming
• Proxy and trust_env
• TLS trust
• Use cases
• Redirects
• Limitations
• Benchmarks
• Runnable examples

Current Limitations

FogHTTP is currently focused on controlled HTTP workloads. Buffered responses are the broadest supported response path; sync and async response streaming are available as bytes/text/line context-managed APIs. Streaming content= uploads and multipart files= uploads are available with explicit replayability and cleanup rules. HTTP proxy routing and HTTPS proxy CONNECT tunnelling are available through proxy= and trust_env=True when the proxy endpoint itself uses http://. Cookies, auth helpers, HTTP/2, automatic Accept-Encoding negotiation, streaming decompression, strict connection-level pool limits, and per-request connect timeout reconfiguration are planned for later versions. Response body read timeout is available for buffered and streaming response bodies; request body write timeout is available for buffered and streaming request bodies. Socket lifecycle telemetry is available for the current HTTP/1 path. Disabling TLS verification is intentionally not supported.

Development

Development requires a Rust toolchain with cargo available in PATH.

uv run --extra dev --with "maturin>=1.7,<2" maturin develop
uv run --extra dev coverage run -m pytest
uv run --extra dev coverage report -m
uv run --extra dev pre-commit run --all-files --show-diff-on-failure