modkit-http

HTTP client library for ModKit, built on hyper and tower.

What it does

• HTTPS client with TLS via rustls (WebPki roots by default, no OS dependency)
• Connection pooling via hyper
• Configurable request timeouts
• Automatic retries with exponential backoff (429, 5xx, transport errors, timeouts)
• User-Agent header injection
• Concurrency limiting with fail-fast load shedding
• Response body size limits (applied after decompression)
• Transparent response decompression (gzip, brotli, deflate)
• Secure redirect following with SSRF protection and credential leakage prevention

What it does NOT do

• Cookie management
• Request body compression
• Caching
• WebSocket support
• Streaming uploads

Usage

Basic GET request

use cf_modkit_http::HttpClient;
use std::time::Duration;

let client = HttpClient::builder()
    .timeout(Duration::from_secs(10))
    .user_agent("my-app/1.0")
    .build()?;

// RequestBuilder API: chain methods then send
let data: MyResponse = client
    .get("https://api.example.com/data")
    .send()
    .await?
    .json()
    .await?;

POST with form body

use cf_modkit_http::HttpClient;
use std::time::Duration;

let client = HttpClient::builder()
    .timeout(Duration::from_secs(30))
    .build()?;

let token: TokenResponse = client
    .post("https://auth.example.com/token")
    .header("authorization", "Basic dXNlcjpwYXNz")
    .form(&[
        ("grant_type", "client_credentials"),
        ("client_id", "my-client"),
    ])?
    .send()
    .await?
    .json()
    .await?;

Transparent Decompression

The client automatically handles compressed responses:

• Sends Accept-Encoding: gzip, br, deflate on all requests
• Decompresses response bodies based on Content-Encoding header
• Body size limit applies to decompressed bytes, protecting against "zip bombs"

This is enabled by default with no configuration required. Example:

// Server sends gzip-compressed JSON with Content-Encoding: gzip
// Client automatically decompresses before parsing
let data: MyResponse = client
    .get("https://api.example.com/data")
    .send()
    .await?
    .json()
    .await?;

Configuration

Configuration presets

use cf_modkit_http::{HttpClientBuilder, HttpClientConfig};

// Minimal: no retry, no rate limit, 10s timeout
let client = HttpClientBuilder::with_config(HttpClientConfig::minimal()).build()?;

// Infrastructure: aggressive retry, 60s timeout, 50MB body limit
let client = HttpClientBuilder::with_config(HttpClientConfig::infra_default()).build()?;

// Token endpoint: conservative rate limit, no retry on POST
let client = HttpClientBuilder::with_config(HttpClientConfig::token_endpoint()).build()?;

// Testing: allows plain HTTP for mock servers
let client = HttpClientBuilder::with_config(HttpClientConfig::for_testing()).build()?;

// SSE streaming: 24h timeout, no retry, no rate limit
let client = HttpClientBuilder::with_config(HttpClientConfig::sse()).build()?;

Redirect Security

By default, modkit-http follows redirects with security protections:

Redirect policies

use cf_modkit_http::{HttpClient, RedirectConfig};

// Default: same-origin only (most secure)
let client = HttpClient::builder().build()?;

// Permissive: follow all redirects, but strip credentials on cross-origin
let client = HttpClient::builder()
    .redirect(RedirectConfig::permissive())
    .build()?;

// Disable redirects entirely
let client = HttpClient::builder()
    .redirect(RedirectConfig::disabled())
    .build()?;

// Custom: allow specific trusted hosts
use std::collections::HashSet;
let config = RedirectConfig {
    same_origin_only: true,
    allowed_redirect_hosts: HashSet::from(["cdn.example.com".to_string()]),
    ..Default::default()
};
let client = HttpClient::builder().redirect(config).build()?;

Retry Behavior

The default retry policy:

Non-idempotent methods (POST, PATCH) are only retried on 429 by default to avoid duplicate side effects. To enable broader retry for these methods, include an Idempotency-Key header.

Error handling

All operations return HttpError:

License

Apache-2.0