better-fetch

Typed HTTP client layer on top of reqwest, inspired by @better-fetch/fetch. Independent Rust implementation.

Installation

Pick one crate name (same library):

[dependencies]
better-fetch = "0.2"
serde = { version = "1", features = ["derive"] }
tokio = { version = "1", features = ["macros", "rt-multi-thread"] }
tokio-util = "0.7"

Aliases on crates.io: typed-fetch, api-fetch — pub use better_fetch::*.

Optional features:

better-fetch = { version = "0.2", features = ["tower", "validate", "multipart"] }

Quick start

use better_fetch::{Client, Result};
use serde::Deserialize;

#[derive(Debug, Deserialize)]
#[serde(rename_all = "camelCase")]
struct Todo {
    user_id: u64,
    id: u64,
    title: String,
    completed: bool,
}

#[tokio::main]
async fn main() -> Result<()> {
    let client = Client::new("https://jsonplaceholder.typicode.com")?;

    // send() returns Response (any status); json() fails on non-2xx
    let todo: Todo = client
        .get("/todos/:id")
        .param("id", 1)
        .send()
        .await?
        .json()
        .await?;

    // Or in one step:
    let todo: Todo = client.get("/todos/:id").param("id", 1).send_json().await?;

    println!("{todo:#?}");
    Ok(())
}

Highlights

• Builder API — Client::builder(), per-request .timeout(), .retry(), .auth(), headers, JSON body.
• Retries — linear, exponential, or count; Retry-After, jitter, custom should_retry; default retry on 408/429/502/503/504.
• Hooks & plugins — compose client and plugin hooks; optional LoggerPlugin (requires a tracing subscriber in your app).
• Errors — Result + ?; Error::api_json() to parse JSON error bodies from APIs.
• Typed endpoints — Endpoint trait + client.call::<E>() → EndpointRequestBuilder with typed send_json().
• Testing — inject ClientBuilder::backend(Arc<dyn HttpBackend>).
• Cancellation — CancellationToken per request; cooperative abort during requests and retry backoff.
• Throw mode — throw_on_error(true) makes send() return Err on non-2xx (like upstream throw: true).
• Form & multipart — .form([...]) for url-encoded bodies; .multipart(form) with feature multipart.

Request options

Cancellation

use better_fetch::{CancellationToken, Client, Result};
use std::time::Duration;

#[tokio::main]
async fn main() -> Result<()> {
    let token = CancellationToken::new();
    let client = Client::new("https://httpbin.org")?;

    let handle = tokio::spawn({
        let token = token.clone();
        let client = client.clone();
        async move {
            client
                .get("/delay/10")
                .cancellation_token(token)
                .send()
                .await
        }
    });

    tokio::time::sleep(Duration::from_millis(100)).await;
    token.cancel();

    assert!(handle.await.unwrap().unwrap_err().is_cancelled());
    Ok(())
}

Throw on HTTP error

// Default: Ok(Response) even for 404
let response = client.get("/missing").send().await?;

// Like upstream throw: true
let err = client
    .get("/missing")
    .throw_on_error(true)
    .send()
    .await
    .unwrap_err();

Typed endpoint

use better_fetch::{Client, Endpoint, Result};
use http::Method;
use serde::Deserialize;

struct GetTodo;
impl Endpoint for GetTodo {
    const METHOD: Method = Method::GET;
    const PATH: &'static str = "/todos/:id";
    type Response = Todo;
    type Params = ();
    type Query = ();
}

#[derive(Deserialize)]
struct Todo { id: u64, title: String }

async fn example(client: &Client) -> Result<()> {
    let todo = client
        .call::<GetTodo>()
        .param("id", 1)
        .send_json()
        .await?;
    Ok(())
}

Form and multipart

// URL-encoded form
client
    .post("/login")
    .form([("user", "alice"), ("pass", "secret")])
    .send()
    .await?;

// Multipart (feature "multipart")
let form = better_fetch::multipart::Form::new().text("file", "hello");
client.post("/upload").multipart(form).send().await?;

Note: automatic retry is not supported with .multipart() (the body cannot be replayed). Use .form, JSON, or raw bytes if you need retries.

Client builder

ClientBuilder::build() requires .base_url(...) — otherwise Error::MissingBaseUrl.

use better_fetch::ClientBuilder;

let client = ClientBuilder::new()
    .base_url("https://api.example.com")?
    .retry(RetryPolicy::exponential(3, Duration::from_secs(1), Duration::from_secs(30)))
    .build()?;

Concurrency limits

ClientBuilder::max_in_flight uses a tokio semaphore in the core client (counts retries as in-flight work). The tower feature’s ConcurrencyLimitLayer is a separate transport-level cap. Use one of these at a given limit unless you intentionally want two stacked caps (e.g. app-wide budget + per-host transport limit).

Plugins

Plugin::init receives PreparedRequest with url, path, method, and headers (after auth, before lifecycle hooks). Use it to rewrite URLs or inspect auth headers.

Features

See CHANGELOG.md for release notes.

Examples

cargo run -p better-fetch --example basic
cargo run -p better-fetch --example multipart --features multipart
cargo run -p better-fetch --example retry
cargo test -p better-fetch
cargo test -p better-fetch --features default,validate,tower,multipart

Crates in this repository

License

MIT — see LICENSE. Upstream inspiration: THIRD_PARTY_NOTICES.md.