Crate scion_http3

Expand description

§SCION HTTP/3 client

A high-level HTTP/3-over-SCION client: give it a URL, get a response.

§Features

SCION connectivity, discovered through an endhost API
TSAR DNS resolution (SCION addresses from DNS TXT records)
Per-origin connection pooling
Staggered multi-candidate connection establishment (RFC 8305, Happy Eyeballs)
Connect, request, and idle-connection timeouts
Recovery from network changes

The transport engine underneath is scion_quic::h3::client::Http3Client. It stays available for callers that need transport-level control.

§Usage

Issue a GET request with the Client::get shorthand (see also Client::post):

use scion_http3::{Client, Config};

/// Cap on a collected response body.
const MAX_BODY_SIZE: usize = 1 << 20;

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

Or build a Request from scratch and issue it with Client::request:

use scion_http3::Request;

let request = Request::post("https://chat.example.org/messages")
    .header("content-type", "application/json")
    .body(r#"{"room":"general","text":"hi"}"#)
    .build()?;
let response = client.request(request).await?;

§Tunnels

Client::connect opens an HTTP CONNECT tunnel to an Authority (host:port). The returned Tunnel is a byte stream that implements tokio::io::AsyncRead and tokio::io::AsyncWrite:

use scion_http3::Authority;
use tokio::io::{AsyncReadExt, AsyncWriteExt};

let authority: Authority = "chat.example.org:443".parse()?;
let mut tunnel = client.connect(&authority).await?;
tunnel.write_all(b"hello").await?;
let mut reply = vec![0u8; 5];
tunnel.read_exact(&mut reply).await?;
tunnel.shutdown().await?;

The authority’s host is resolved like a URL’s host. Config::with_dns_override maps a host that has no TSAR records to fixed addresses.

§Connection pooling and lifecycle

A Client holds a connection pool, so create one client per application and share it.

Construction does no I/O: connections are established lazily on first use and then reused per origin. Use Client::warm_up to establish a connection before the first request.

Client::close closes all pooled connections and frees their resources. Calling it before dropping the client is optional.

§Network changes

Call Client::reset when the network below the client changes, for example when the platform reports a switch from Wi-Fi to mobile data. The call never blocks: it marks the current connections stale, and the next request tears them down and rebuilds connectivity.

§Error handling

Every request-path failure surfaces as one error type, Error. To decide whether to retry a failed request, use Error::is_retryable instead of matching variants. A retryable error does not imply the request never reached the server, so retry non-idempotent requests with care.

Re-exports§

pub use bytes;
pub use http;
pub use scion_quic;
pub use scion_stack;
pub use sciparse;
pub use tokio;
pub use url;

Structs§

Authority: Body bytes (bytes::Bytes) used for request bodies and collected response bodies. Body bytes (bytes::Bytes) used for request bodies and collected response bodies. Body bytes (bytes::Bytes) used for request bodies and collected response bodies. The host:port target of a CONNECT tunnel.
Client: A high-level HTTP/3-over-SCION client: URL in, response out.
Config: Configuration for a Client.
Request: An HTTP request: method, URL, headers, and a buffered body.
RequestBuilder: Builder for a Request.
Response: A response whose head has arrived and whose body is still on the wire.
StaticTokenSource: Authentication token plumbing for Config::with_auth_token_source: implement TokenSource to supply tokens that expire; StaticTokenSource wraps a fixed one. A static token source that always returns the same token. Can be created from a String or &'static str.
Tunnel: A byte stream through an accepted CONNECT tunnel.

Enums§

BuildRequestError: A Request could not be built.
Error: Any failure on the request path.
InvalidAuthority: Body bytes (bytes::Bytes) used for request bodies and collected response bodies. Body bytes (bytes::Bytes) used for request bodies and collected response bodies. Body bytes (bytes::Bytes) used for request bodies and collected response bodies. An Authority could not be built.
TimeoutPhase: The phase of a request during which a timeout fired.
TokenSourceError: Authentication token plumbing for Config::with_auth_token_source: implement TokenSource to supply tokens that expire; StaticTokenSource wraps a fixed one. Why a token source could not provide a token.

Constants§

DEFAULT_CONNECTION_ATTEMPT_DELAY: Default stagger between connection attempts to an origin’s candidate addresses (RFC 8305, Happy Eyeballs).
DEFAULT_CONNECT_TIMEOUT: Default timeout for establishing a connection to an origin.
DEFAULT_IDLE_CONNECTION_TIMEOUT: Default idle time after which an origin’s connection is swept.
DEFAULT_MAX_ORIGINS: Default bound on the number of distinct origins with pooled connections.
DEFAULT_REQUEST_TIMEOUT: Default timeout for a request (response head plus body collection).

Traits§

IntoUrl: A type that can be converted into a Url.
TokenSource: Authentication token plumbing for Config::with_auth_token_source: implement TokenSource to supply tokens that expire; StaticTokenSource wraps a fixed one. A source for authentication tokens.

Type Aliases§

TokenSourceWatch: Authentication token plumbing for Config::with_auth_token_source: implement TokenSource to supply tokens that expire; StaticTokenSource wraps a fixed one. A watch receiver for token source updates.