kithara-net

HTTP client with retry, timeout, and streaming. Wraps reqwest behind the Net trait, with a TimeoutNet decorator and a MockNet for tests.

Usage

use kithara_net::{HttpClient, Net, NetOptions};
use tokio_util::sync::CancellationToken;

let client = HttpClient::new(NetOptions::default(), CancellationToken::new());
let bytes = client.get_bytes(url, None).await?;        // None = no extra headers
let stream = client.stream(url, None).await?;

Decorators

TimeoutNet<N> wraps all methods with tokio::time::timeout and is exported in the public API. A retry decorator with exponential backoff (retries on 5xx, 429, 408, timeouts; does not retry on other 4xx) is also available, but only via the NetExt builder methods — the wrapper type itself is not part of the public surface.

Decorators compose via the NetExt extension trait:

use kithara_net::{HttpClient, Net, NetExt, NetOptions, RetryPolicy};
use std::time::Duration;
use tokio_util::sync::CancellationToken;

let client = HttpClient::new(NetOptions::default(), CancellationToken::new())
    .with_retry(RetryPolicy::default(), CancellationToken::new())
    .with_timeout(Duration::from_secs(30));

Key Types

Timeout Behavior

Two independent limits in NetOptions, applied to all methods (get_bytes, head, get_range, stream):

inactivity_timeout (default 30s) — max gap between reads (reqwest read_timeout); guards against stalled connections, not total duration.
total_timeout (default 120s) — hard cap on request lifetime. Set to None to allow indefinite streaming as long as data keeps flowing.

The TimeoutNet decorator can wrap any Net with an additional tokio::time::timeout over the whole call.

Integration