Crate trillium_client

Expand description

trillium client is a 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 at time of writing): 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 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. The default value is Version::Http1_1, which means “no hint — use auto-discovery.”

hint	URL scheme	behavior	curl equivalent
`Version::Http3`	`https`	Skip the `Alt-Svc` cache and dial QUIC directly. Falls back to h2 / h1 if QUIC connect fails. Requires `Client::new_with_quic`.	`--http3`
`Version::Http2`	`https`	TLS handshake (with whatever ALPN the connector advertises), then start the h2 driver immediately without checking the negotiated ALPN. No fallback — a non-h2-speaking server surfaces as an IO error. Useful 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` (default)	any	Auto-discovery as described above.	(default)
`Version::Http1_0`	any	h1.0 wire format (no `Host`, no chunked encoding, etc.).	`--http1.0`

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

§Forcing h1.1 (no h2 ALPN)

There is no per-request knob equivalent to curl’s --http1.1. Opting out of h2 ALPN advertisement is a TLS configuration concern, not a per-request 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.

Re-exports§

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§

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: A HTTP Client supporting HTTP/1.x 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 header value is a collection of one or more HeaderValue. It has been optimized for the “one HeaderValue” case, but can accomodate more than one value.
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: A short non-exhaustive enum of headers that trillium represents as an enum.
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: Trait for streaming body sources that can optionally produce trailers.
ClientHandler: Client middleware extension point.
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