Struct Config 

pub struct Config { /* private fields */ }

Configuration for a Client.

Construct with Config::new and customize with the consuming with_* methods. The endhost API URL is the only required setting: it is how the client discovers the data planes available to it, and the same single setting reaches a real SCION network or a local PocketSCION topology.

Implementations

impl Config

pub fn new(endhost_api: Url) -> Self

Creates a configuration that discovers connectivity through the given endhost API.

pub fn with_auth_token(self, token: impl Into<String>) -> Self

Sets a fixed token to authenticate with the endhost API and the SNAP control plane.

Use with_auth_token_source instead when the token expires: connectivity is rebuilt on every reset, and a token captured here is reused verbatim each time.

pub fn with_auth_token_source(self, source: impl TokenSource) -> Self

Sets the token source used to authenticate with the endhost API and the SNAP control plane.

The source is shared, not rebuilt: the same one is handed to every stack this configuration builds, so a refreshing source keeps its schedule and its cached token across a reset. Implement TokenSource to supply tokens that expire.

For a source scoped to the endhost API alone, reach the builder’s with_endhost_api_auth_token_source through with_stack_customizer.

pub fn with_api_key(self, auth: ApiKeyAuth) -> Self

Sets an Anapaya AA API key. The client exchanges the key for the tokens that the endhost API and the SNAP control plane need.

The client exchanges the key on the first request, and renews the token in the background while the client lives. The exchange is shared, like a token source: every stack this configuration builds reuses the same token, across every reset. A refused key, or an AA out of reach, fails that first request with Error::StackBuild; is_retryable is false for a refused key and true for an AA out of reach. Construction never fails.

The AA URL has to be https, so that the key does not cross the network in cleartext. ApiKeyAuth::allow_insecure_http permits http for local testing; without it an http URL fails the first request.

The key, a token, and a token source occupy one slot: the last one set wins.

pub fn with_preferred_underlay(self, underlay: PreferredUnderlay) -> Self

Sets the preferred underlay, applied to whatever endhost API discovery returns (default: UDP).

pub fn with_stack_customizer( self, customizer: impl Fn(ScionStackBuilder) -> ScionStackBuilder + Send + Sync + 'static, ) -> Self

Customizes the ScionStackBuilder used to build connectivity, for settings this configuration does not expose directly (underlay-specific configuration, discovery tuning, token sources).

The hook runs every time connectivity is (re)built: on first use and after every reset. It runs after the settings above are applied, so it can override them.

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

Sets the timeout for establishing a connection to an origin, covering name resolution and all staggered connection attempts.

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

Sets the default timeout for a whole request: connectivity build, establishment, response head, and body collection. Overridable per request with RequestBuilder::request_timeout.

It is one deadline across all of those phases, and it keeps running while the caller holds the Response — see there for what that means for body collection.

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

Sets how long an origin’s pooled connection may sit unused before an opportunistic sweep reclaims it (and its socket).

pub fn with_max_origins(self, max_origins: usize) -> Self

Bounds the number of distinct origins with pooled connections. Each pooled connection holds a socket, and therefore a file descriptor; when the bound is hit, the least recently used origin is evicted (and the eviction logged).

pub fn with_connection_attempt_delay(self, delay: Duration) -> Self

Sets the stagger between connection attempts to an origin’s candidate addresses: the next candidate is only tried this long after the previous one, unless it already failed (RFC 8305, Happy Eyeballs).

pub fn with_quic_config(self, quic: QuicConfig) -> Self

Sets the QUIC configuration used for every connection: trust anchors (ca_certs_file / ca_certs_dir / ca_certs_pem) or a certificate verifier (with_cert_verifier / with_platform_verifier), peer verification, handshake and idle timeouts, and transport tuning. The application protocol list must contain h3 (the default).

pub fn with_resolver(self, resolver: Arc<dyn ScionDnsResolver>) -> Self

Replaces the default DNS resolver (ScionTxtDnsResolver) with a caller-supplied one.

The default resolver is constructed fresh on every connectivity rebuild, because system DNS configuration is a property of the current network. An injected resolver is reused across rebuilds as-is; reacting to network changes is then its responsibility.

pub fn with_dns_override( self, host: impl Into<String>, addrs: Vec<ScionIpAddr>, ) -> Self

Resolves host to addrs instead of looking it up, for a host that has no TSAR records. Applies to URLs and to CONNECT authorities alike.

Only the default resolver applies overrides. A resolver injected with with_resolver does its own resolution.

Trait Implementations

impl Clone for Config

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Config

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

Formats the value using the given formatter.