Struct Extensions 

pub struct Extensions { /* private fields */ }

A type map of protocol extensions.

Extensions are internally stored in a type erased Arc. Since values are stored in an Arc there are extra methods exposed that build on top of this and leverage characteristics of an Arc to expose things like cheap cloning of the Arc.

Extensions may have an optional parent: the Extensions this one was forked from. Lookups walk the parent chain when the local Extensions don’t have the requested type. The parent relationship is best described as “I’m layered on top of that, but I’m not exactly the same”:

• Retry attempts fork from the original request (don’t leak failed extensions)
• Responses fork the request (response != request)
• H2 streams fork from underlying H2 connection (nested connection with isolated properties)

Connection’s who logically map one-to-one we don’t fork and we just pass the Extensions up, examples are:

• TLS layered on top of TCP
• HTTP layered on top of TLS
• …

Implementations

impl Extensions

pub fn new() -> Self

Create an empty Extensions store with no parent.

pub fn fork(&self) -> Self

Create a fresh child Extensions whose parent is this Extensions store.

The child has its own empty top-level storage. Lookups that miss locally walk into the parent (and recursively up the chain). Inserts land on this child only, parents are never mutated through the child.

pub fn parent(&self) -> Option<&Self>

The parent Extensions this blob was forked from, if any.

pub fn with_base(&self, base: &Self) -> Self

Return a view of this Extensions chain layered on top of base.

The toplevel extensions are still the same and are editable. Lookups resolve through this chain first falling back to base only when nothing matches. base is all the way at the bottom.

Use this when you have an Extensions (chain) to which you want to apply defaults, e.g. request_extensions().with_base(&base_extension_config)

pub fn insert<T: Extension>(&self, val: T) -> &T

Insert a type T into this Extensions store.

This method returns a reference to the just inserted value.

If the value you are inserting is an Arc<T>, prefer using Self::insert_arc to prevent the double indirection of storing an Arc<Arc<T>>.

pub fn insert_arc<T: Extension>(&self, val: Arc<T>) -> Arc<T>

Insert a type Arc<T> into this [Extensions] store.

This method returns a a cloned Arc of the value just inserted

If the value you are inserting is not an Arc<T> or you don’t need a cloned Arc<T> prefer using Self::insert()

pub fn extend(&self, other: &Self)

Extend this Extensions store with the other Extensions.

The other Extensionss will be appended behind the current ones

pub fn contains<T: Extension>(&self) -> bool

Returns true if the Extensions store contains the given type.

This function is recursive and will traverse multiple nested Extensions stores to find the correct item. See Extensions::get_ref() for how this works.

If you don’t want any of this special logic and you just want to check this Extensions store, use Extensions::self_contains() instead.

pub fn self_contains<T: Extension>(&self) -> bool

Returns true if this Extensions store contains the given type

This only checks this Extensions store

pub fn get_ref<T: Extension>(&self) -> Option<&T>

Get a reference to T. Walks the parent chain and the connection wrappers (Egress / Ingress) if not found locally.

Search rule (single pass, newest insertion wins):

1. Iterate local entries newest -> oldest. For each entry:
   • if its type matches T, return it,
   • if it is an Egress<Extensions> or Ingress<Extensions> wrapper, recurse into the wrapped blob with the same rule (its own local first, then its wrappers, then its parent) and return any match found,
   • otherwise skip.
2. If still not found, recurse into the parent (same rule applied).

Wrappers are spliced into the local scan in insertion order, so a connection-pointer detour inserted on this blob is treated as part of “local” for ordering purposes: a directly-inserted T and a wrapper containing T both compete by insertion time, newest wins. Parent is only consulted after the entire local scan (including wrapper recursion) finishes empty. The wrappers themselves can still be retrieved directly (or via Self::egress / Self::ingress).

For a raw flat lookup, use Self::self_get_ref.

Returns the most recently inserted match, for the oldest, see Self::self_first_ref.

pub fn self_get_ref<T: Extension>(&self) -> Option<&T>

Raw flat Self::get_ref: returns the most recently inserted T, for the oldest, see Self::self_first_ref.

This only checks this Extensions store

pub fn get_arc<T: Extension>(&self) -> Option<Arc<T>>

Get an owned Arc<T>. Walks the parent chain and the structural connection wrappers if not found locally.

See Self::get_ref for the search order.

For a raw flat lookup (top-level only), use Self::self_get_arc.

pub fn self_get_arc<T: Extension>(&self) -> Option<Arc<T>>

Raw flat Self::get_arc: returns the most recently inserted T

This only checks this Extensions store

pub fn get_many_ref<'a, T: GetManyRef<'a>>(&'a self) -> T::Output

Fetch several extension types in a single pass, returning a tuple of Option<&T> mirroring the requested tuple. Each slot uses the same search rule as Self::get_ref (newest-wins, walking the Egress / Ingress wrappers and the parent chain), but the whole structure is traversed only once instead of once per type.

See Self::get_many_arc for an owned-Arc variant.

pub fn get_many_arc<T: GetManyArc>(&self) -> T::Output

Like Self::get_many_ref, but returns a tuple of Option<Arc<T>> (cheap, owned Arc clones) instead of borrowed references, the multi-fetch counterpart of Self::get_arc. Same single-pass traversal.

pub fn get_ref_or_insert<T, F>(&self, create_fn: F) -> &T

where T: Extension, F: FnOnce() -> T,

Recursive find-or-create: return &T if one exists anywhere in this this Extensions store (using Self::get_ref dispatch), otherwise insert the value produced by create_fn at the top level and return a reference to it.

Useful when a type conceptually belongs to the scope (e.g. ConnectionHealth on a connection chain) and you want to reuse an existing instance rather than create a duplicate at every layer. For strict “ensure local exists”, use Self::self_get_ref_or_insert.

pub fn get_arc_or_insert<T, F>(&self, create_fn: F) -> Arc<T>

where T: Extension, F: FnOnce() -> Arc<T>,

Recursive find-or-create returning an Arc<T>: see Self::get_ref_or_insert.

pub fn self_get_ref_or_insert<T, F>(&self, create_fn: F) -> &T

where T: Extension, F: FnOnce() -> T,

Raw flat find-or-create: return &T if one exists at the top level of this Extensions store, otherwise insert the value produced by create_fn at the top level and return a reference to it.

Does not follow the parent chain. Useful when you want strict “ensure T exists on THIS blob” (e.g. materializing a direction wrapper like Ingress<Connection<Extensions>> at the outer blob).

pub fn self_get_arc_or_insert<T, F>(&self, create_fn: F) -> Arc<T>

where T: Extension, F: FnOnce() -> Arc<T>,

Raw flat find-or-create returning an Arc<T>: see Self::self_get_ref_or_insert.

pub fn self_first_ref<T: Extension>(&self) -> Option<&T>

Raw flat reference to the oldest inserted T at the top level of this Extensions store, does not walk structural wrappers.

In most cases you want Self::get_ref (newest, scope-aware). Use this only when you specifically need insertion order access inside this Extensions store.

Currently we don’t provide a recursive variant of this method since we don’t have a use case for it, and it’s not exactly clear what would be considered “first”.

pub fn self_first_arc<T: Extension>(&self) -> Option<Arc<T>>

Raw flat Arc<T> to the oldest inserted T at the top level, see Self::self_first_ref for caveats.

pub fn self_iter_ref<T: Extension>(&self) -> impl Iterator<Item = &T>

Raw flat iteration over all inserted items of type T at the top level of this Extensions store, newest to oldest.

The order matches Self::self_get_ref (newest-first), so self_iter_ref::<T>().next() == self_get_ref::<T>().

pub fn self_iter_arc<T: Extension>(&self) -> impl Iterator<Item = Arc<T>>

Raw flat iteration over all inserted items of type T at the top level as cloned Arc values, newest to oldest.

The order matches Self::self_get_arc (newest-first), so self_iter_arc::<T>().next() == self_get_arc::<T>().

pub fn self_iter_all(&self) -> impl Iterator<Item = &TypeErasedExtension>

Raw flat iteration over all TypeErasedExtension entries at the top level of this Extensions store.

Use to efficiently combine different types of Extensions in a single iteration. TypeErasedExtension exposes methods to convert back to type T when it matches the erased type.

pub fn iter_ref<T: Extension>(&self) -> impl Iterator<Item = &T> + '_

Iterate over all inserted items of type T, walking the parent chain and the structural Egress / Ingress connection wrappers.

Yield order matches Self::get_ref preference (so iter_ref::<T>().next() == get_ref::<T>()):

At each level, iterate the local entries newest -> oldest. For each entry: yield it if its type matches T, if it is an Egress<Extensions> or Ingress<Extensions> wrapper, recurse into the wrapped blob (same rule applied) and yield its results inline. Then recurse into the parent.

For a flat top-level-only iteration use Self::self_iter_ref.

The iterator type is left opaque (impl Iterator) so the internal representation can change without breaking callers.

pub fn iter_arc<T: Extension>(&self) -> impl Iterator<Item = Arc<T>> + '_

Iteration yielding cloned Arc<T> values, see Self::iter_ref.

pub fn ingress(&self) -> Option<&Ingress<Self>>

Get a reference to the Ingress<Extensions> wrapper if one exists on this blob or anywhere reachable through the parent chain.

Returns None when no ingress wrapper has been set up. For correctly constructed server-side requests this is always Some, server stacks insert the wrapper at the boundary where the connection becomes visible to a request, so a None here is almost always a framework setup bug rather than a normal state.

This is just a shortcut for extensions.get_ref::<Ingress<Extensions>>()

pub fn egress(&self) -> Option<&Egress<Self>>

Get a reference to the Egress<Extensions> wrapper if one exists on this blob or anywhere reachable through the parent chain. See Self::ingress for semantics.

This is just a shortcut for extensions.get_ref::<Egress<Extensions>>()

pub fn clone_to<T: Extension>(&self, target: &Self) -> Option<Arc<T>>

Clone an Extension from Extensions to another and get a Arc clone of it.

pub fn clone_to_if_absent<T: Extension>(&self, target: &Self) -> Option<Arc<T>>

Clone an Extension from Extensions to another, if and only if the other Extensions store does not already contain this Extension T.

If the other Extensions store already contains it, we return Extension T from the other store, otherwise we return the T that we transferred over.

This is mainly used in connectors where Extensions that become part of the connection should be transfer from the input to the connection.

Trait Implementations

impl Clone for Extensions

fn clone(&self) -> Extensions

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Extensions

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

Formats the value using the given formatter.

impl Default for Extensions

fn default() -> Extensions

Returns the “default value” for a type.

impl ExtensionsRef for Extensions

fn extensions(&self) -> &Extensions

Get reference to the underlying Extensions store