Crate trillium_client

Expand description

trillium client is an HTTP client that uses the same conn approach as trillium but which can be used independently for any HTTP client application.

§Connector

trillium_client::Client is built with a Connector. Each runtime crate (trillium_smol, trillium_tokio, trillium_async_std) offers a Connector implementation, which can optionally be combined with a tls crate such as trillium_rustls, trillium_native_tls, or trillium_openssl.

See the documentation for Client and Conn for further usage examples.

§Protocol selection

By default, trillium-client auto-discovers the best HTTP version for each request:

Over https:// with a TLS connector that advertises h2 in ALPN and exposes the server’s selection back to trillium (the default for trillium_rustls::RustlsConfig and trillium_openssl::OpenSslConfig): the server picks h2 or h1.1 during the TLS handshake. Whatever ALPN selects is what the client uses.
Over https:// with h2 removed from the ALPN list (e.g. RustlsConfig::without_http2()): h1 only.
Over https:// with a TLS connector that doesn’t surface ALPN selection (trillium_native_tls): h1 only by default, since trillium can’t tell whether the server picked h2. Use the Version::Http2 hint described below to force h2 over TLS in that case.
Over https:// when the Client was built with Client::new_with_quic: the client may use h3 for origins that have advertised it via Alt-Svc, that publish an alpn=h3 SVCB/HTTPS DNS record (when an encrypted resolver is configured — see Encrypted DNS), or that the user has hinted (see below).
Over http://: h1 only. There is no h2c probing without explicit prior knowledge.

§Prior-knowledge hints

Setting Conn::http_version before sending the request signals prior knowledge of what the server speaks. By default no hint is set, which means “use auto-discovery.” Setting any explicit version pins the protocol and suppresses auto-discovery — no Alt-Svc h3, no ALPN/pooled h2 promotion — and constrains the connection’s ALPN to match (an h1 pin advertises only http/1.1, an h2 pin only h2), so the pin is honored over TLS rather than overridden by ALPN. The http_version accessor reports the unset default as Version::Http1_1.

hint	URL scheme	behavior	curl equivalent
`Version::Http3`	`https`	Skip the `Alt-Svc` cache and dial QUIC directly. Falls back to auto-discovery (h2 / h1) if QUIC connect fails. Requires `Client::new_with_quic`.	`--http3`
`Version::Http2`	`https`	TLS handshake advertising only `h2` in ALPN, then start the h2 driver immediately without checking the negotiated ALPN. No fallback — a non-h2-speaking server surfaces as an IO error. Also works with TLS connectors that don’t surface ALPN selection.	(curl bundles this with `--http2-prior-knowledge`’s cleartext mode)
`Version::Http2`	`http`	h2c immediate preface (cleartext h2 prior knowledge). No fallback.	`--http2-prior-knowledge`
`Version::Http1_1`	any	Force HTTP/1.1: no h3 Alt-Svc, no h2 ALPN/pool promotion.	`--http1.1`
`Version::Http1_0`	any	h1.0 wire format (no `Host`, no chunked encoding, etc.).	`--http1.0`
unset (default)	any	Auto-discovery as described above.	(default)

Hints are per-Conn; mix them freely on requests sharing one Client.

§Forcing h1.1

Set the Version::Http1_1 hint on the request — the per-request equivalent of curl’s --http1.1. It pins HTTP/1.1 even when the connector would otherwise negotiate h2 via ALPN or use h3 via Alt-Svc, by advertising only http/1.1 in this connection’s ALPN. (Over trillium_native_tls, which doesn’t yet honor per-connection ALPN, the pin still skips h2/h3 promotion but can’t constrain the handshake — in practice harmless, since native-tls advertises no ALPN by default.) To opt out of h2 ALPN advertisement at the connection level for all requests on a client, that remains a TLS configuration concern: use RustlsConfig::without_http2() (or the equivalent on whichever TLS crate you’re using) when constructing the Client.

§WebSockets and WebTransport

With the websockets cargo feature, Conn::into_websocket transforms a built conn into a WebSocketConn (RFC 6455 over h1, RFC 8441 extended CONNECT over h2). With the webtransport cargo feature, Client::webtransport(url) + Conn::into_webtransport() open a multiplexed WebTransport-over-h3 session (RFC 9220 + draft-ietf-webtrans-http3). Multiple WebTransport sessions to the same origin coalesce onto a single underlying QUIC connection — see the webtransport module for details.

§Server-Sent Events

With the sse cargo feature, Conn::into_sse executes a request and reads the response body as a text/event-stream, returning an EventStream — a Stream of Events parsed per the SSE specification. Unlike the WebSocket and WebTransport upgrades, SSE is not a protocol switch: an event stream is an ordinary response whose body is read incrementally, so it works the same over HTTP/1.x, HTTP/2, and HTTP/3. This is a single-response stream — it ends when the connection closes and does not implement the EventSource automatic-reconnection behavior. See the sse module for details.

§Encrypted DNS

With the hickory cargo feature, the client can route all of its DNS through an encrypted resolver of your choice rather than sending plaintext queries to the operating system’s resolver. Client::with_doh uses DNS-over-HTTPS (RFC 8484), Client::with_dot DNS-over-TLS (RFC 7858), and Client::with_doq DNS-over-QUIC (RFC 9250); a client uses at most one, and a later call replaces an earlier one. DoH lookups ride the client’s own connection pool, so they reuse and multiplex like any other request. A single resolution is cached and shared across HTTP/1, HTTP/2, and HTTP/3.

Resolution is fail-closed: once a resolver is configured, a lookup it can’t answer fails the request rather than falling back to the system resolver, so a query never leaks to a (possibly plaintext) local resolver. The resolver’s own host is the one exception — it’s resolved once via the underlying connector to bootstrap the connection; give the resolver as an IP address to skip even that.

SVCB and HTTPS DNS records (RFC 9460) are fetched too, letting a server advertise HTTP/3 support directly in DNS. A domain publishing alpn=h3 is reached over HTTP/3 on the first request by an HTTP/3-capable client (Client::new_with_quic), with no Alt-Svc round-trip. The connection to a DoH resolver itself negotiates h1/h2 by default; Client::with_doh3 pins it to HTTP/3 for resolvers that serve DoH over HTTP/3 without advertising it. with_dot requires a TLS connector and with_doq an HTTP/3-capable client.

Re-exports§

pub use sse::Event;sse
pub use sse::EventStream;sse
pub use sse::SseError;sse
pub use sse::SseErrorKind;sse
pub use websocket::WebSocketUpgradeError;websockets
pub use trillium_server_common::url;
pub use trillium_websockets::async_tungstenite;websockets
pub use trillium_websockets::tungstenite;websockets

Modules§

ssesse: Client-side Server-Sent Events.
websocketwebsockets: Support for client-side WebSockets

Macros§

jsonsonic-rs: Construct a sonic_rs::Value from a JSON literal.

Structs§

ArcedConnector: An Arced and type-erased Connector
ArcedQuicClientConfig: An arc-wrapped, type-erased QUIC client config (endpoint factory).
Body: The trillium representation of a http body. This can contain either &'static [u8] content, Vec<u8> content, or a boxed AsyncRead/BodySource type.
Client: 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.
Conn: a client connection, representing both an outbound http request and a http response
HeaderName: The name of a http header. This can be either a KnownHeaderName or a string representation of an unknown header.
HeaderValue: A HeaderValue represents the right hand side of a single name: value pair.
HeaderValues: A collection of one or more HeaderValue, optimized for the single-value case.
Headers: Trillium’s header map type
ResponseBody: A response body received from a server.
UnexpectedStatusError: An unexpected HTTP status code was received. Transform this back into the conn with From::from/Into::into.
Url: A parsed URL record.
Valuesonic-rs: Represents any valid JSON value.
WebSocketConfigwebsockets: The configuration for WebSocket connection.
WebSocketConnwebsockets: A struct that represents an specific websocket connection.

Enums§

ClientSerdeErrorserde_json or sonic-rs: A wrapper error for trillium_http::Error or, depending on json serializer feature, either sonic_rs::Error or serde_json::Error. Only available when either the sonic-rs or serde_json cargo features are enabled.
Error: Concrete errors that occur within trillium’s HTTP implementation
KnownHeaderName: Non-exhaustive enum of well-known HTTP header names.
Method: HTTP request methods.
Status: HTTP response status codes.
Version: The version of the HTTP protocol in use.

Constants§

USER_AGENT: default http user-agent header

Traits§

BodySource: Streaming body source that can optionally produce trailers.
ClientHandler: Client middleware extension point.
ConnExt: The extension trait handler authors use to drive the ClientHandler lifecycle.
Connector: Interface for runtime and tls adapters for the trillium client
IntoUrl: attempt to construct a url, with base if present
QuicClientConfig: Factory for creating client-side QUIC endpoints.

Functions§

client: constructs a new Client – alias for Client::new

Type Aliases§

Result: this crate’s result type