Struct SubcConsumer 

pub struct SubcConsumer { /* private fields */ }

Managed Rust consumer for subc route calls.

Implementations

impl SubcConsumer

pub async fn connect( connection_file: &Path, opts: ConsumerOptions, ) -> Result<Self, ConsumerError>

Connect, authenticate, and start the connection’s I/O. The epoch starts at 1.

pub async fn open_route( &self, target: RouteTarget, identity: BindIdentity, opts: CallOptions, ) -> Result<RouteHandle, CallError>

Open or reuse a managed route and return its connection-fenced handle.

pub async fn open_route_with_admission_facts( &self, target: RouteTarget, identity: BindIdentity, facts: Value, ) -> Result<RouteHandle, CallError>

Open one admitted route without entering the managed route cache.

Admitted routes are never cached or reopened after a connection drop. If this call fails or the route later closes, the caller must perform admission again and call this method with fresh facts.

pub async fn catalog_list(&self) -> Result<CatalogList, CallError>

Fetch the daemon’s module catalog over channel 0.

pub async fn request( &self, handle: &RouteHandle, body: Vec<u8>, opts: CallOptions, ) -> Result<Vec<u8>, CallError>

Send one request using an already-opened route handle.

pub async fn subscribe_route( &self, handle: &RouteHandle, body: Vec<u8>, opts: SubscribeOptions, ) -> Result<Subscription, CallError>

Start a held-open request using an already-opened route handle.

pub async fn poll_route( &self, handle: &RouteHandle, kind: PollKind, timeout: Duration, ) -> Result<RoutePollResult, CallError>

Poll status or liveness for exactly this route handle.

pub fn dropped_route_frames(&self) -> u64

Locally observed count of unknown or stale route frames dropped by layer-2 validation.

pub fn push_events( &self, handle: &RouteHandle, ) -> Result<Receiver<PushEvent>, CallError>

Register a receiver for provider-originated Push frames on exactly one live route.

Registering another receiver for the same route replaces and closes the prior receiver. The receiver closes when its route closes, the connection drops, or its bounded buffer fills; the reader never waits for an application that is not draining pushes.

pub fn pushes_dropped_no_receiver(&self) -> u64

Number of Push frames dropped because their live route has no active receiver.

Push is a one-way latency optimization, not a durable feed: the client does not acknowledge it, and callers retain polling as their correctness backstop. Counting intentional default-path drops makes an application that has not opted in observable.

pub async fn call( &self, target: RouteTarget, identity: BindIdentity, body: Vec<u8>, opts: CallOptions, ) -> Result<Vec<u8>, CallError>

Managed unary call. Route-open failures happen before the body is sent and are classified as NotSent; module handler Error frames are the only Module errors.

pub async fn subscribe( &self, target: RouteTarget, identity: BindIdentity, body: Vec<u8>, opts: SubscribeOptions, ) -> Result<Subscription, CallError>

Open a held-open subscription on a managed route.

This opens or reuses the same (target, identity, consumer_identity, consumer_capabilities) route as SubcConsumer::call, sends one Request that the provider keeps open, and returns a Subscription whose event receiver yields each matching StreamData payload. The request holds one route flow-control permit until StreamEnd, an Error frame, route teardown, connection loss, local backpressure, or Subscription::unsubscribe. Reconnects reject the subscription; callers that need durable replay should resubscribe with their own cursor after observing the failure.

pub async fn close_route( &self, target: RouteTarget, identity: BindIdentity, opts: CloseRouteOptions, )

Tear down ONE route, keyed by its route-open identity tuple — the parity of the TS client’s closeRoute. For a long-lived consumer that opens unbounded distinct routes (one per session), this releases a route on session-end without dropping the whole consumer: it drops the cached route, settles in-flight requests on it at-most-once (OutcomeUnknown if already sent, NotSent otherwise), and sends a best-effort route GOODBYE so the daemon releases it and notifies the module.

Idempotent: a no-op if the route was never opened or is already closed (callers over-call on session-end). NOT a permanent tombstone — a later call() for the same key opens a fresh route. The close-beats-reopen guard ensures a close that races an in-flight route.open WINS (the opened channel is GOODBYE’d, not cached).

pub async fn close_handle( &self, handle: &RouteHandle, opts: CloseRouteOptions, ) -> Result<(), CallError>

Close exactly this route handle. A stale connection token fails locally and emits no frame.

pub fn current_epoch(&self) -> u64

Current transport epoch: 1 on initial connect, then +1 per successful reconnect.

pub fn on_connection_state(&self, cb: impl Fn(ConnectionState) + Send + 'static)

Register a connection-state callback. Callbacks are best-effort observability hooks.

pub async fn close(&self)

Close the consumer and settle every pending caller.

Trait Implementations

impl Drop for SubcConsumer

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.