+
+
Rust API shape
+
+ web-faith has one noun and one verb. An Agent owns the pool, jar, cache, and
+ resolver; fetch is how every request goes out. Defaults match the Node surface: redirects
+ followed and HTTP/3 upgrade on, cookie jar and HTTP cache opted into.
+
+
+
+
The whole surface
+
+ fetch takes a URL or a prebuilt Request and returns a builder.
+ The builder is a future, so a bare call awaits directly and a configured one awaits after its options.
+ There is no send() and no second entry point.
+
+
+
+
+
Fetch some JSON
+
use web_faith::Agent;
+
+let agent = Agent::new()?;
+
+let things: Vec<Thing> = agent
+ .fetch("https://api.example/things")
+ .await?
+ .json()
+ .await?;
+
+
+
+
Configured POST
+
let agent = Agent::builder()
+ .user_agent("myapp/1.0")
+ .cache(Cache::disk("/var/cache/app"))
+ .cookies(true)
+ .build()?;
+
+let res = agent
+ .fetch("https://api.example/things")
+ .method(Method::POST)
+ .header("authorization", tok)
+ .integrity("sha384-oqVuAfXR")
+ .cache_mode(CacheMode::NoStore)
+ .timeout(Duration::from_secs(5))
+ .json(&thing)
+ .await?;
+
+
+
+
Stream the body
+
let res = agent.fetch(url).await?;
+
+let mut body = res.body_stream();
+while let Some(chunk) = body.next().await {
+ sink.write_all(&chunk?).await?;
+}
+
+let trailers = res.trailers().await;
+let timing = res.timing().await;
+
+
+
+
+
+
Building a request once
+
+ A Request is the built, inert form. Because fetch accepts one and still returns a
+ builder, a request can be prepared once and tweaked at each call site, or sent unchanged across
+ two agents. Cloning follows the body: a buffered body clones, a stream body cannot, so it is
+ try_clone rather than Clone.
+
+
+
+
+
Prepare, then vary
+
let probe = Request::new("https://api.example/health")
+ .header("accept", "application/json")
+ .timeout(Duration::from_secs(2))
+ .build()?;
+
+for region in regions {
+ let Some(req) = probe.try_clone() else { break };
+
+ let res = agent
+ .fetch(req)
+ .header("x-region", region)
+ .await?;
+}
+
+
+
+
Same request, two agents
+
let req = Request::new(url)
+ .method(Method::POST)
+ .json(&payload)?
+ .build()?;
+
+let Some(copy) = req.try_clone() else {
+ return Err(Error::NotCloneable);
+};
+
+let (primary, mirror) = tokio::join!(
+ live_agent.fetch(req),
+ audit_agent.fetch(copy),
+);
+
+
+
+
+
+
Agent lifecycle
+
+ An agent is cheap to clone and every clone names the same pool, so close acts on the shared
+ agent rather than on the handle it was called through. Requests already issued run to completion, even
+ ones no work has started on; a request issued afterwards fails with the closed-agent error.
+
+
+
+
+
Shutting down
+
let agent = Agent::new()?;
+let handle = agent.clone();
+
+tokio::spawn(async move {
+ handle.fetch(url).await
+});
+
+// releases the pool, resolver, and probes
+// for every clone, not just this one
+agent.close();
+
+
+
+
Acting on a live agent
+
agent.network_changed();
+
+let stats = agent.stats();
+let conns = agent.connections();
+let resolvers = agent.resolvers();
+let jar = agent.cookies();
+
+agent.prefetch_dns("api.example").await?;
+agent.preconnect("https://api.example").await?;
+
+
+
+
+
Response
+
+
+
+ | Fetch surface |
+ status, status_text, ok, headers, url,
+ redirected, kind, body_used |
+
+
+ | Reading |
+ text(), json(), bytes(), body_stream(),
+ to_file(), discard(). Reading consumes the body and a second read is an
+ error, following the fetch standard rather than reqwest's owned-response model. |
+
+
+ | Faith additions |
+ peer, version, trailers(), timing() |
+
+
+ | Errors |
+ One Error type carrying the existing kinds, each reporting the same code the Node
+ binding does. |
+
+
+ | Cancellation |
+ Dropping the future cancels the request. timeout stays an option for the deadline case. |
+
+
+ | Runtime |
+ Tokio, as today. |
+
+
+
+
+
Ecosystem types
+
+ The http crate's types are canonical wherever one exists, so a Faith request composes with
+ tower, hyper, and axum code without a shim. Setters stay fetch-flavoured by taking anything that
+ converts, so a string literal works where JS would pass a string.
+
+
+
+ | Concept | Canonical type | What setters accept |
|---|
+
+
+
+ | Method |
+ http::Method |
+ .method(impl TryInto<Method>), so "POST" and Method::POST both work |
+
+
+ | Header |
+ http::HeaderName, http::HeaderValue |
+ .header(impl TryInto<HeaderName>, impl TryInto<HeaderValue>) |
+
+
+ | Header set |
+ http::HeaderMap |
+ .headers(impl IntoIterator<Item = (K, V)>), which covers a HeaderMap, a
+ Vec of pairs, and an array of string pairs |
+
+
+ | Status |
+ http::StatusCode |
+ Read-only. ok and status_text derive from it |
+
+
+ | Version |
+ http::Version |
+ Read-only, replacing the Node binding's string |
+
+
+ | URL |
+ url::Url |
+ impl TryInto<Url>, matching what the fetch standard parses and what reqwest already uses |
+
+
+ | Request in |
+ Request |
+ fetch and Request::new take an impl TryInto<Url>, a
+ Request, or an http::Request<B> |
+
+
+ | Response out |
+ Response |
+ Converts into http::Response<Body>, and the body implements
+ http_body::Body so it feeds tower and hyper directly |
+
+
+ | Conversion errors |
+ Error::InvalidHeader and friends |
+ Held until the builder resolves: at build() for a request, at the await for a fetch.
+ Either way the error names the offending header |
+
+
+
+
+
Considered and dropped
+
+
+ - A process-wide default agent with
set and close accessors,
+ so a bare fetch(url) free function could exist. Dropped because a hidden global owning a
+ connection pool and a disk cache is worth more scrutiny in Rust than in Node. The cost is that two
+ libraries in one process cannot share a pool without passing an agent between them.
+ - A reqwest-shaped
Client with get, post, and
+ friends. Dropped in favour of one verb, which keeps the fetch vocabulary the specs are written in.
+ - Crate namespaces (
web-faith::cookies). Not available: RFC 3243 is
+ accepted but unimplemented, with the cargo, crates.io, and docs.rs issues all open.
+
+
+
+