Struct Agent 

pub struct Agent { /* private fields */ }

A Faith HTTP agent: where all fetches start.

An agent holds the resources and state shared across requests — connection pool, caches, DNS resolver, cookie jar, HTTP/3 upgrade memory — and is the browser instance of this library. A typical application makes one and starts every request from it.

Agent::new takes the defaults; Agent::builder configures one.

Implementations

impl Agent

pub fn new() -> Result<Self, FaithError>

An agent with default options.

pub fn builder() -> AgentOptionsBuilder

Build an agent a setting at a time.

Each option group is reached through a closure, so a group left alone is absent from the call rather than spelled out as absent. Durations are Duration whatever unit the setting is carried in, and anything unset takes its default.

use std::time::Duration;
use web_faith::Agent;

let agent = Agent::builder()
    .user_agent("YourApp/1.2.3")
    .timeout(|timeout| timeout.connect(Duration::from_secs(2)).build())
    .pool(|pool| pool.max_idle_per_host(8).build())
    .build()?;

impl Agent

pub fn prefetch_dns( &self, host: &str, ) -> Result<impl Future<Output = ()> + use<>, FaithError>

Warm the DNS cache for host, so a later request to it skips the lookup.

Takes a bare host; a scheme, port or path is ignored. The future completes when the answer lands and never fails — the work is advisory — and does nothing under the system resolver, which has no cache to warm. A host with nothing to resolve, or a closed agent, is refused here rather than by the future.

pub fn preconnect( &self, origin: &str, ) -> Result<impl Future<Output = ()> + use<>, FaithError>

Open a pooled connection to origin, so the first request to it skips DNS, TCP and TLS setup.

Takes an origin (scheme://host[:port]); a longer URL is reduced to one. Sends a synthetic HEAD to the origin’s root — which the origin will see in its logs — over the transport the next request would use. The future completes when the attempt finishes and never fails. Something unconnectable, or a closed agent, is refused here rather than by the future.

impl Agent

pub fn cookies(&self) -> Option<&Arc<FaithJar>>

Available on crate feature cookies only.

The agent’s cookie jar, if it keeps one.

The jar itself, so cookies go in and out through the type web-faith-cookies documents. It stays readable after Self::close.

pub fn client(&self) -> Option<ClientWithMiddleware>

Available on crate feature raw-client only.

The client this agent sends through, or None once it is closed.

A request takes its handle when it is issued, which lets one already in flight finish while a later one is refused.

pub fn raw_client(&self) -> Option<Client>

Available on crate feature raw-client only.

The same client without Faith’s middleware.

A request on it skips the HTTP cache and the Alt-Svc layer, while sharing the connection pool.

pub fn dns_resolver(&self) -> Option<FaithResolver>

Available on crate features dns and raw-client only.

The agent’s DNS resolver, or None once it is closed.

pub fn close(&self)

Close the agent, releasing its connection pool, DNS resolver, and background tasks without waiting for the last clone to drop. Worth doing if you make many short-lived agents.

Requests already in flight run to completion. A request issued on a closed agent fails with FaithErrorKind::Closed. Calling it more than once is a no-op, and the cookie jar, if any, stays readable through cookies().

pub fn network_changed(&self)

Tell the agent the network under it has changed, so it stops acting on what it learned about a network that is gone.

There is no portable signal for an interface or connectivity change, so call this yourself on whatever trigger fits — an OS notification, a VPN transition, a captive-portal sign-in.

Drops pooled connections, flushes the DNS cache, demotes confirmed HTTP/3 origins back to advertised so a probe re-verifies them, and clears the HTTP/3 failure, slow and path-time state. Configuration, http3.hints, Alt-Svc advertisements, the cookie jar, the HTTP cache and the counters are kept — none of those is a claim about a network path.

Requests in flight run to completion on the connections they hold. Harmless to call repeatedly, or on a closed agent.

pub fn stats(&self) -> AgentStats

The agent’s counters, as they stand.

pub fn connections(&self) -> Vec<ConnectionSnapshot>

Available on crate feature connection-tracking only.

The connections this agent currently holds open.

TCP only; QUIC connections are not visible here. Statistics refresh once a second, so sample over time for rates such as retransmissions. Which fields are filled depends on the platform: the lost-packet count and delivery rate are Linux-only, an unsupported platform reports an empty list, and no field is guaranteed to stay available.

pub fn resolvers(&self) -> Vec<ResolverReport>

Available on crate feature dns only.

The DNS servers this agent resolves through, in query order.

Each entry gives the nameserver’s address, the transport in use, and how that was arrived at. Empty until the resolver has been used, and empty under the system resolver.

pub fn is_closed(&self) -> bool

Whether Self::close has been called.

impl Agent

pub fn fetch<T>(&self, target: T) -> FetchBuilder

where T: TryInto<Target>, T::Error: Into<FaithError>,

Aim a request at target, to send when awaited.

The target is a URL, or a Request to layer over. See FetchBuilder.

Trait Implementations

impl Clone for Agent

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Agent

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.