Struct AltSvcCache 

pub struct AltSvcCache { /* private fields */ }

Available on crate features http and std only.

Bounded Alt-Svc advertisements, independent of connector protocol capabilities.

Records retain preference order, protocol and endpoint, including protocols a particular client does not support. Both the number of origins and alternatives per origin are bounded. Lookup shares immutable candidate storage; freshness, persistence and temporary failure state remain private to this cache.

Headers and HTTP/2 ALTSVC frames update the same origin entry: each accepted advertisement replaces the previous list, and either source can clear it. Neither source has precedence. RFC 7838 section 4 discourages mixing them because their processing order can be difficult to predict.

These are hints, not proof of authority. An HTTPS alternative must authenticate the logical origin and negotiate its advertised protocol. Using an alternative for an HTTP origin additionally requires RFC 8164’s origin authorization; TLS authentication alone does not grant that permission.

Share a cache between connectors with the same default authentication policy: endpoint failures are shared as well as advertisements. Middleware excludes request-specific authentication from shared learning and failure updates; opaque per-route configuration is excluded from shared backoff.

Implementations

impl AltSvcCache

pub fn new( capacity: u64, max_age: Duration, failure_backoff: Duration, ) -> AltSvcCache

Set origin capacity, maximum retention and alternative failure backoff.

pub fn with_max_alternatives_per_origin(self, capacity: usize) -> AltSvcCache

Bound retained alternatives per advertisement. Zero disables retention.

Configure this before sharing the cache; existing entries are unaffected.

pub fn set_max_alternatives_per_origin( &mut self, capacity: usize, ) -> &mut AltSvcCache

Bound retained alternatives per advertisement. Zero disables retention.

Configure this before sharing the cache; existing entries are unaffected.

pub fn with_max_advertisement_bytes(self, capacity: usize) -> AltSvcCache

Bound combined Alt-Svc field bytes before parsing or allocating records. Oversized advertisements are ignored, preserving existing cache state.

pub fn set_max_advertisement_bytes( &mut self, capacity: usize, ) -> &mut AltSvcCache

Bound combined Alt-Svc field bytes before parsing or allocating records. Oversized advertisements are ignored, preserving existing cache state.

pub fn record( &self, origin: &HttpOrigin, headers: &HeaderMap, response_delay: Duration, )

Record response hints for their logical origin, including plaintext HTTP.

The caller must establish that these headers belong to this origin. HTTPS responses require origin authentication. Plaintext HTTP can advertise alternatives, but selection must also meet RFC 8164’s origin-authorization requirements; this cache does not perform those checks. response_delay is the time from request dispatch to response headers.

pub fn record_frame( &self, origin: &HttpOrigin, field_value: Bytes, received_at: Instant, )

Record the field value of an HTTP/2 ALTSVC frame for its verified origin.

The caller must validate the frame’s stream/origin association and ensure the connection is authoritative for origin (RFC 7838 section 4). received_at starts the freshness lifetime; delayed delivery does not extend it. Response Age, Date and request latency do not apply to frames. Malformed or oversized values leave existing advertisements unchanged.

pub fn record_frame_received( &self, origin: &HttpOrigin, field_value: Bytes, received: AltSvcReceivedAt, )

Record an authorized frame using its original receive ordering metadata. Custom observers must apply the same origin and shared-policy checks as the response middleware before calling this method.

pub fn record_received( &self, origin: &HttpOrigin, headers: &HeaderMap, response_delay: Duration, received: AltSvcReceivedAt, )

Record a response advertisement in transport receive order. Use the response’s AltSvcReceivedAt when available so delayed header delivery cannot overwrite a newer HTTP/2 ALTSVC frame. The caller must first authorize this origin under the cache’s shared trust policy.

pub fn lookup(&self, origin: &HttpOrigin) -> Option<Arc<HttpServiceCandidates>>

Share a snapshot when at least one candidate is currently usable.

The snapshot retains stable advertisement indices, including candidates that have expired or been suppressed. Call Self::is_usable before attempting each candidate. This avoids rebuilding a vector on every lookup.

pub fn lookup_fresh( &self, origin: &HttpOrigin, ) -> Option<Arc<HttpServiceCandidates>>

Share a fresh snapshot without applying direct-path failure backoff.

Proxy routes can reach alternatives unavailable on the direct path. Use this with Self::is_fresh for proxy route plans, and do not call Self::failed for those attempts.

pub fn is_usable( &self, snapshot: &Arc<HttpServiceCandidates>, index: usize, ) -> bool

Check current freshness and failure state for this exact advertisement. A replaced snapshot or out-of-range index is never usable.

pub fn is_fresh( &self, snapshot: &Arc<HttpServiceCandidates>, index: usize, ) -> bool

Check advertisement freshness independently of direct-path failure state. Used with Self::lookup_fresh for proxy-routed establishment.

pub fn failed(&self, snapshot: &Arc<HttpServiceCandidates>, index: usize)

Temporarily suppress a candidate after direct-path establishment failure.

Do not report proxy-route failures here: reachability can differ by route. Proxy selection uses Self::lookup_fresh instead of this direct-path backoff. Re-advertising an endpoint preserves its failure history.

pub fn network_epoch(&self) -> u64

Capture the current network generation before an attempt or dispatch. Reports from older generations are ignored after Self::network_changed.

pub fn failed_attempt( &self, snapshot: &Arc<HttpServiceCandidates>, index: usize, network: u64, started: Instant, terminal: bool, )

Record a completed attempt even when its endpoint was re-advertised during the dial. A network change invalidates the captured path context.

pub fn route_usable( &self, snapshot: &Arc<HttpServiceCandidates>, index: usize, route: &ProxyRouteContext, ) -> bool

Check freshness and backoff for a particular proxy route plan.

pub fn failed_route( &self, snapshot: &Arc<HttpServiceCandidates>, index: usize, network: u64, started: Instant, route: &ProxyRouteContext, )

Report an unsuccessful connection attempt on the captured route.

pub fn failed_service( &self, service: &EstablishedHttpService, route: Option<&ProxyRouteContext>, network: u64, started: Instant, )

Report a remote response failure under the shared connector policy. Caller cancellation, local body errors and request-only trust failures must not be reported as evidence that this endpoint is unavailable.

pub fn succeeded_service( &self, service: &EstablishedHttpService, route: Option<&ProxyRouteContext>, network: u64, )

A complete response ends the selected path’s failure streak. Merely connecting or receiving response headers does not establish stream health.

pub fn misdirected(&self, snapshot: &Arc<HttpServiceCandidates>, index: usize)

Remove the alternative that returned 421 without replaying a request. Retain failure backoff across repeated advertisements of that endpoint; delayed responses from older discovery generations remain harmless.

pub fn network_changed(&self)

Forget network-specific alternatives while retaining persist=1 entries.

Call this when the application’s network changes (for example, switching interfaces or VPNs). Rama does not monitor operating-system connectivity. This also clears path failure backoff, including persistent alternatives, because reachability on the previous network does not describe the new one.

pub fn clear_all(&self)

Forget all advertisements and failure history, for example when clearing browsing data (RFC 7838 §9.4). Existing connections remain usable; later responses can advertise again. This does not allocate unused stores.

pub fn clear(&self, origin: &HttpOrigin)

Explicitly invalidate this origin’s advertisements.

impl AltSvcCache

pub fn frame_observer(&self, origin: HttpOrigin) -> Arc<AltSvcObserverExtension>

Observe HTTP/2 advertisements for this logical origin using connection authentication metadata. Install on the connection input before handshake; the observer also handles frames received while requests are idle.

Trait Implementations

impl Clone for AltSvcCache

fn clone(&self) -> AltSvcCache

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for AltSvcCache

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

Formats the value using the given formatter.

impl Default for AltSvcCache

fn default() -> AltSvcCache

Returns the “default value” for a type.