Struct Consumer 

pub struct Consumer { /* private fields */ }

Cheap read handle over an origin’s route table.

Clones share the underlying state without allocating any per-cursor resources. To receive route announcements, call Self::announced; to resolve a path into a broadcast, call Self::request_broadcast.

Implementations

impl Consumer

pub fn hop(&self) -> Hop

This origin’s hop identity.

pub fn with_stats(self, session: Session) -> Self

Attach an egress stats context: broadcasts handed out through this handle (and any handle derived from it) are attributed to session on the publisher (egress) side. Pass stats::Session::default to opt out.

pub fn announced(&self) -> AnnounceConsumer

Subscribe to route announcements for this consumer’s scope.

Allocates a per-cursor coalescing buffer and replays the currently announced routes as initial updates. Routes stay prefixes and are named relative to this consumer’s root; its patterns only filter visibility. Drop the returned AnnounceConsumer to unregister.

pub fn consume(&self) -> Self

Returns a cheap duplicate of this read handle.

pub async fn routed(&self, path: impl AsPath) -> Option<Route>

Block until an announced route covers path, and return it.

Covering means the route’s prefix is a (segment-wise) prefix of path, including the exact path itself. Returns None if the path is outside this consumer’s scope or the consumer is closed first.

To resolve a broadcast rather than inspect the route, use Self::routed_broadcast: pairing this with Self::request_broadcast leaves a gap where the covering route can retract, and misses a local broadcast that serves the path without announcing.

pub async fn routed_broadcast( &self, path: impl AsPath, ) -> Result<Consumer, Error>

Block until path resolves to a broadcast: Self::request_broadcast, retried whenever the routes covering the path change.

A request answers for the routes as they stand, so it can miss an announcement that has not arrived yet, lose its covering route to failover churn, find a route that covers the path while nothing serves it yet (an advertise-only announce racing its handler), or be turned down by a handler. This rides all of that out by watching the covering routes and asking again each time they move, which is what makes it the right call for resolving a path right after connecting. Returns Error::Unauthorized for a path outside this consumer’s scope, Error::Closed once the origin closes, and any other resolution failure as-is.

pub fn scope( &self, root: impl AsPath, patterns: &Patterns, ) -> Result<Consumer, Error>

Returns a consumer rooted at root and restricted to matching patterns.

root is relative to this consumer’s root, and patterns are relative to the new root. Returns Error::Unauthorized when the requested scope has no overlap with this consumer’s scope, or Error::BoundsExceeded when rooting the patterns would exceed the path limit.

pub fn request_broadcast(&self, path: impl AsPath) -> Pending<Requesting>

Resolve a broadcast by exact path.

Returns a kio::Pending future, mirroring track::Consumer::fetch_group. Every path resolves through a front the origin’s Driver runs: the request mints one or joins the one already serving the path, and the front picks the best route covering it (a broadcast published on this origin at the exact path first, announced or not; then the most specific prefix, then the cheapest) and materializes it, from the broadcast itself or from the peer that announced the route. When its serving source dies or a better qualifying route appears, the front re-splices through the best route sharing its first hop at a group boundary, invisibly to subscribers. A change that does not preserve the first hop ends the broadcast instead, and the next request re-serves the path.

The returned future fails with Error::Unroutable at once when nothing covers the path. A route claims capability, not inventory: resolving a covered path succeeds optimistically, and a path that names nothing surfaces as Error::NotFound on its tracks instead.

pub fn root(&self) -> &Path<'_>

Returns the prefix that is automatically stripped from all paths.

pub fn allowed(&self) -> Patterns

The patterns this consumer may reach, relative to its root.

pub fn absolute(&self, path: impl AsPath) -> Path<'_>

Converts a relative path to an absolute path.

Trait Implementations

impl Clone for Consumer

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Consume<Consumer> for Producer

fn consume(&self) -> Consumer

Derive a read view (a consumer) from this handle.

impl Consume<Consumer> for Consumer

fn consume(&self) -> Consumer

Derive a read view (a consumer) from this handle.