Struct Client 

pub struct Client { /* private fields */ }

A high-level HTTP/3-over-SCION client: URL in, response out.

The client owns everything between a URL and a connection: SCION connectivity, DNS resolution, a connection pool, and timeouts. It is cheap to construct and intended to be a long-lived value shared across an application: it is Send + Sync, and requests borrow it immutably.

use scion_http3::{Client, Config};

const MAX_BODY_SIZE: usize = 1 << 20;

let client = Client::new(Config::new("https://endhost-api.example.org".parse()?));
let response = client.get("https://chat.example.org/rooms").await?;
let (body, _trailers) = response.text(Some(MAX_BODY_SIZE)).await?;

Implementations

impl Client

pub fn new(config: Config) -> Self

Creates a client. Performs no I/O: connectivity is built lazily by the first request (or by warm_up).

pub async fn request(&self, request: Request) -> Result<Response, Error>

Issues a request and returns the response once its head has arrived.

The whole call, building connectivity if needed, resolving the origin, establishing or reusing its connection, and waiting for the response head, runs under the request timeout (the per-request override, or the configured default). Collecting the body on the returned Response runs under the remainder of the same deadline.

If establishing a connection through a pooled client fails, the origin is re-resolved and re-established once and the request re-issued. This is safe for non-idempotent requests: establishment failure means nothing reached the wire, and bodies are buffered and thus replayable. Errors after the request reached the wire are never retried here; see Error::is_retryable for what the caller may retry.

pub async fn get(&self, url: impl IntoUrl) -> Result<Response, Error>

Issues a GET request to url. Shorthand for building a Request with defaults and calling request.

pub async fn post( &self, url: impl IntoUrl, body: impl Into<Bytes>, ) -> Result<Response, Error>

Issues a POST request with the given body to url. Shorthand for building a Request with defaults and calling request.

pub async fn connect(&self, authority: &Authority) -> Result<Tunnel, Error>

Opens a CONNECT tunnel to authority.

The connection to the authority is resolved and pooled like the one of a request to https://host:port/. The call runs under the request timeout up to the response head; the open Tunnel has no deadline. A non-2xx response is Error::TunnelRefused.

pub async fn connect_via( &self, via: &Authority, target: &Authority, ) -> Result<Tunnel, Error>

Opens a CONNECT tunnel to target through the tunnel server at via.

The client dials via and sends target as the CONNECT authority. Otherwise it works like connect.

pub async fn connect_via_unverified( &self, via: &Authority, target: &Authority, ) -> Result<Tunnel, Error>

Like connect_via, but does not verify the certificate of via.

The caller must authenticate target inside the tunnel, for example with TLS.

pub async fn warm_up(&self, url: impl IntoUrl) -> Result<(), Error>

Pre-establishes connectivity to url’s origin: builds the stack if needed, resolves the origin, and performs the QUIC handshake, so the first request pays none of it. Runs under the connect timeout (plus stack build time).

pub fn reset(&self)

Marks connectivity stale: the next request tears down the current connections and rebuilds the stack, discovery, and resolver state.

Call this when the network below the client changed (for example on a platform network-change signal). Never blocks; if the rebuild fails, the failing request reports the build error and the next request retries the rebuild.

pub async fn close(&self)

Closes the client: tears down all pooled connections, faulting in-flight requests promptly. Subsequent requests fail with Error::Closed. Idempotent.