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 local(self) -> Self

A view of the routes that entered here: every route a handle marked Producer::peer announced is hidden from Self::announced and never resolved by Self::request_broadcast.

On a relay, this is what the relay ingests itself, from clients and in-process producers, as opposed to what its cluster peers forward.

pub fn with_hidden(self, hidden: bool) -> Self

A clone whose announced also reports hidden routes: those with a segment starting with . below the requested prefix. Hidden routes are left out by default, so a platform can add .-named broadcasts without them turning up in apps that list everything.

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. Routes with a segment starting with . below the literal head of those patterns are hidden unless with_hidden opted in. 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.

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 announced route covering it (the most specific prefix, then the cheapest, a broadcast published on this origin winning ties) 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, as does its route retracting with no replacement, and the next request re-serves the path. Tracks already in flight carry on to their own end.

The returned future fails with Error::Unroutable at once when no announced route covers the path, including a broadcast created on this origin but not announced. 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.