Struct Client 

pub struct Client { /* private fields */ }

An HTTP client supporting HTTP/1.x, HTTP/2 (via ALPN), and — when configured with a QUIC implementation — HTTP/3. See Client::new and Client::new_with_quic for construction information.

Implementations

impl Client

pub fn h2_idle_timeout(&self) -> Option<Duration>

Returns a copy of Maximum idle time for a pooled HTTP/2 connection. None disables expiry.

Defaults to 5 minutes.

pub fn set_h2_idle_timeout( &mut self, h2_idle_timeout: Option<Duration>, ) -> &mut Self

Sets Maximum idle time for a pooled HTTP/2 connection. None disables expiry., returning &mut Self for chaining

Defaults to 5 minutes.

pub fn with_h2_idle_timeout(self, h2_idle_timeout: Duration) -> Self

Owned chainable setter for Maximum idle time for a pooled HTTP/2 connection. None disables expiry., returning Self

Defaults to 5 minutes.

pub fn without_h2_idle_timeout(self) -> Self

Owned chainable setter for Maximum idle time for a pooled HTTP/2 connection. None disables expiry., returning Self

Defaults to 5 minutes.

pub fn h2_idle_ping_threshold(&self) -> Option<Duration>

Returns a copy of If a pooled HTTP/2 connection has been idle for longer than this, an active PING is sent to verify it’s still alive before being handed out. None disables the probe.

Defaults to 10 seconds.

pub fn set_h2_idle_ping_threshold( &mut self, h2_idle_ping_threshold: Option<Duration>, ) -> &mut Self

Sets If a pooled HTTP/2 connection has been idle for longer than this, an active PING is, returning &mut Self for chaining sent to verify it’s still alive before being handed out. None disables the probe.

Defaults to 10 seconds.

pub fn with_h2_idle_ping_threshold( self, h2_idle_ping_threshold: Duration, ) -> Self

Owned chainable setter for If a pooled HTTP/2 connection has been idle for longer than this, an active PING is, returning Self sent to verify it’s still alive before being handed out. None disables the probe.

Defaults to 10 seconds.

pub fn without_h2_idle_ping_threshold(self) -> Self

Owned chainable setter for If a pooled HTTP/2 connection has been idle for longer than this, an active PING is, returning Self sent to verify it’s still alive before being handed out. None disables the probe.

Defaults to 10 seconds.

pub fn h2_idle_ping_timeout(&self) -> Duration

Returns a copy of Timeout for the liveness PING sent under the h2_idle_ping_threshold policy. Connections whose ACK doesn’t arrive within this window are treated as dead.

Defaults to 20 seconds.

pub fn set_h2_idle_ping_timeout( &mut self, h2_idle_ping_timeout: Duration, ) -> &mut Self

Sets Timeout for the liveness PING sent under the h2_idle_ping_threshold policy., returning &mut Self for chaining Connections whose ACK doesn’t arrive within this window are treated as dead.

Defaults to 20 seconds.

pub fn with_h2_idle_ping_timeout(self, h2_idle_ping_timeout: Duration) -> Self

Owned chainable setter for Timeout for the liveness PING sent under the h2_idle_ping_threshold policy., returning Self Connections whose ACK doesn’t arrive within this window are treated as dead.

Defaults to 20 seconds.

pub fn base(&self) -> Option<&Url>

Borrows url base for this client

pub fn default_headers(&self) -> &Headers

Borrows default request headers

pub fn timeout(&self) -> Option<Duration>

Returns a copy of optional per-request timeout

pub fn set_timeout(&mut self, timeout: Duration) -> &mut Self

Sets optional per-request timeout, returning &mut Self for chaining

pub fn with_timeout(self, timeout: Duration) -> Self

Owned chainable setter for optional per-request timeout, returning Self

pub fn without_timeout(self) -> Self

Owned chainable setter for optional per-request timeout, returning Self

pub fn context(&self) -> &HttpContext

Borrows configuration

pub fn context_mut(&mut self) -> &mut Arc<HttpContext>

Mutably borrow configuration

pub fn set_context(&mut self, context: impl Into<Arc<HttpContext>>) -> &mut Self

Sets configuration, returning &mut Self for chaining

pub fn with_context(self, context: impl Into<Arc<HttpContext>>) -> Self

Owned chainable setter for configuration, returning Self

impl Client

pub fn get(&self, url: impl IntoUrl) -> Conn

Builds a new client conn with the get http method and the provided url.

use trillium_client::{Client, Method};
use trillium_testing::client_config;

let client = Client::new(client_config());
let conn = client.get("http://localhost:8080/some/route"); //<-

assert_eq!(conn.method(), Method::Get);
assert_eq!(conn.url().to_string(), "http://localhost:8080/some/route");

pub fn post(&self, url: impl IntoUrl) -> Conn

Builds a new client conn with the post http method and the provided url.

use trillium_client::{Client, Method};
use trillium_testing::client_config;

let client = Client::new(client_config());
let conn = client.post("http://localhost:8080/some/route"); //<-

assert_eq!(conn.method(), Method::Post);
assert_eq!(conn.url().to_string(), "http://localhost:8080/some/route");

pub fn put(&self, url: impl IntoUrl) -> Conn

Builds a new client conn with the put http method and the provided url.

use trillium_client::{Client, Method};
use trillium_testing::client_config;

let client = Client::new(client_config());
let conn = client.put("http://localhost:8080/some/route"); //<-

assert_eq!(conn.method(), Method::Put);
assert_eq!(conn.url().to_string(), "http://localhost:8080/some/route");

pub fn delete(&self, url: impl IntoUrl) -> Conn

Builds a new client conn with the delete http method and the provided url.

use trillium_client::{Client, Method};
use trillium_testing::client_config;

let client = Client::new(client_config());
let conn = client.delete("http://localhost:8080/some/route"); //<-

assert_eq!(conn.method(), Method::Delete);
assert_eq!(conn.url().to_string(), "http://localhost:8080/some/route");

pub fn patch(&self, url: impl IntoUrl) -> Conn

Builds a new client conn with the patch http method and the provided url.

use trillium_client::{Client, Method};
use trillium_testing::client_config;

let client = Client::new(client_config());
let conn = client.patch("http://localhost:8080/some/route"); //<-

assert_eq!(conn.method(), Method::Patch);
assert_eq!(conn.url().to_string(), "http://localhost:8080/some/route");

pub fn new(connector: impl Connector) -> Self

builds a new client from this Connector

pub fn new_with_quic<C: Connector, Q: QuicClientConfig<C>>( connector: C, quic: Q, ) -> Self

Build a new client with both a TCP connector and a QUIC connector for HTTP/3 support.

The connector’s runtime and UDP socket type are bound to the QUIC connector here, before type erasure, so that trillium-quinn and the runtime adapter remain independent crates that neither depends on the other.

When H3 is configured, the client will track Alt-Svc headers in responses and automatically use HTTP/3 for subsequent requests to origins that advertise it. Other requests follow the standard h1 / h2-via-ALPN path.

pub fn with_handler<H: ClientHandler>(self, handler: H) -> Self

Install a ClientHandler middleware stack on this client.

The handler runs around every request issued by this client: its run method fires before the network round-trip (with the option to halt + synthesize a response), and its after_response fires afterwards. Compose multiple handlers with tuples — see ClientHandler for the lifecycle and Vec/tuple/Option impls.

Returns self for chaining.

pub fn set_handler<H: ClientHandler>(&mut self, handler: H) -> &mut Self

Install a ClientHandler middleware stack on this client. See Client::with_handler for details.

pub fn handler(&self) -> &impl ClientHandler

Borrow the type-erased ClientHandler

See also Client::downcast_handler if you can name the type

pub fn downcast_handler<T: Any + 'static>(&self) -> Option<&T>

Borrow the installed ClientHandler as the concrete type T, returning None if the installed handler is not of that type.

Useful for inspecting handler-internal state from outside the request path — e.g., reading counters from a metrics handler.

pub fn without_default_header( self, name: impl Into<HeaderName<'static>>, ) -> Self

chainable method to remove a header from default request headers

pub fn with_default_header( self, name: impl Into<HeaderName<'static>>, value: impl Into<HeaderValues>, ) -> Self

chainable method to insert a new default request header, replacing any existing value

pub fn default_headers_mut(&mut self) -> &mut Headers

borrow the default headers mutably

calling this will copy-on-write if the default headers are shared with another client clone

pub fn without_keepalive(self) -> Self

chainable constructor to disable http/1.1 connection reuse.

use trillium_client::Client;
use trillium_smol::ClientConfig;

let client = Client::new(ClientConfig::default()).without_keepalive();

pub fn build_conn<M>(&self, method: M, url: impl IntoUrl) -> Conn

where M: TryInto<Method>, <M as TryInto<Method>>::Error: Debug,

builds a new conn.

if the client has pooling enabled and there is an available connection for this origin (scheme + host + port), the new conn will reuse it when sent.

use trillium_client::{Client, Method};
use trillium_smol::ClientConfig;
let client = Client::new(ClientConfig::default());

let conn = client.build_conn("get", "http://trillium.rs"); //<-

assert_eq!(conn.method(), Method::Get);
assert_eq!(conn.url().host_str().unwrap(), "trillium.rs");

pub fn connector(&self) -> &ArcedConnector

borrow the connector for this client

pub fn clean_up_pool(&self)

The pool implementation accumulates a small memory footprint for each new host. If your application is reusing a pool against a large number of unique hosts, call this method intermittently.

pub fn with_base(self, base: impl IntoUrl) -> Self

chainable method to set the base for this client

pub fn build_url(&self, url: impl IntoUrl) -> Result<Url>

attempt to build a url from this IntoUrl and the Client::base, if set

pub fn set_base(&mut self, base: impl IntoUrl) -> Result<()>

set the base for this client

pub fn base_mut(&mut self) -> Option<&mut Url>

Mutate the url base for this client.

This has “clone-on-write” semantics if there are other clones of this client. If there are other clones of this client, they will not be updated.

impl Client

pub fn with_doh(self, resolver: impl AsRef<str>) -> Self

Available on crate feature hickory only.

Route all DNS resolution for this client through the given DNS-over-HTTPS (RFC 8484) resolver, including SVCB/HTTPS records (RFC 9460).

resolver may be a full URL (https://1.1.1.1/dns-query) or a bare host or IP (1.1.1.1). A missing scheme defaults to https and a missing path to /dns-query, so 1.1.1.1, https://1.1.1.1, and https://1.1.1.1/dns-query are equivalent; an explicit path is honored, since RFC 8484 leaves the path to out-of-band configuration. An IP avoids any bootstrap lookup; a hostname is resolved once via the underlying connector and then cached like any other name.

A client holds a single DNS resolver; calling with_doh3, with_dot, or with_doq after this replaces it and logs a warning.

Panics

Panics if resolver is neither a valid URL nor a valid host.

pub fn with_doh3(self, resolver: impl AsRef<str>) -> Self

Available on crate feature hickory only.

Route all DNS resolution for this client through the given DNS-over-HTTPS (RFC 8484) resolver, forcing the connection to the resolver itself onto HTTP/3.

Identical to with_doh except that the connection to the resolver is pinned to HTTP/3 rather than negotiated (h1/h2) over ALPN. Use this for resolvers that serve DoH over HTTP/3 but don’t advertise it via Alt-Svc — which would otherwise leave the client on h2 indefinitely. Only the resolver connection is affected; requests to resolved hosts pick their protocol from SVCB/Alt-Svc as usual.

A client holds a single DNS resolver; calling with_doh, with_dot, or with_doq after this replaces it and logs a warning.

Panics

Panics if the client is not HTTP/3-capable (build it with Client::new_with_quic), or if resolver is neither a valid URL nor a valid host.

pub fn with_dot(self, resolver: impl AsRef<str>) -> Self

Available on crate feature hickory only.

Route all DNS resolution for this client through the given DNS-over-TLS (RFC 7858) resolver, including SVCB/HTTPS records (RFC 9460).

resolver may be a full https:// URL or a bare host or IP (1.1.1.1), which expands to https://<host>:853 — the registered DoT port. An IP avoids any bootstrap lookup; a hostname is resolved once via the underlying connector and then cached like any other name.

Each lookup opens a one-shot TLS connection to the resolver, so the client must be configured with a TLS connector; a plaintext connector fails the lookup (and, because resolution is fail-closed, the request) rather than falling back to the system resolver.

A client holds a single DNS resolver; calling with_doh, with_doh3, or with_doq after this replaces it and logs a warning.

Panics

Panics if resolver is neither a valid URL nor a valid host.

pub fn with_doq(self, resolver: impl AsRef<str>) -> Self

Available on crate feature hickory only.

Route all DNS resolution for this client through the given DNS-over-QUIC (RFC 9250) resolver, including SVCB/HTTPS records (RFC 9460).

resolver may be a full https:// URL or a bare host or IP (1.1.1.1), which expands to https://<host>:853 — the registered DoQ port. An IP avoids any bootstrap lookup; a hostname is resolved once via the underlying connector and then cached like any other name.

Queries ride a cached, multiplexed QUIC connection (one bidirectional stream per query) established over this client’s HTTP/3 UDP endpoint with the doq ALPN, independent of the HTTP/3 connection pool. Resolution is fail-closed, like with_doh.

A client holds a single DNS resolver; calling with_doh, with_doh3, or with_dot after this replaces it and logs a warning.

Panics

Panics if the client is not HTTP/3-capable (build it with Client::new_with_quic), or if resolver is neither a valid URL nor a valid host.

Trait Implementations

impl Clone for Client

fn clone(&self) -> Client

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Client

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

Formats the value using the given formatter.

impl<T: Connector> From<T> for Client

fn from(connector: T) -> Self

Converts to this type from the input type.