Struct ChannelHandle

Source

pub struct ChannelHandle { /* private fields */ }

Expand description

Cloneable handle for interacting with a channel actor process.

Implementations§

Source §

impl ChannelHandle

Source

pub fn new(config: ChannelConfig) -> Self

Creates an ephemeral handle backed by a real supervised channel actor on the shared default supervisor.

The actor process is spawned lazily on first use; a scheduler failure is surfaced as a LiminalError from the first operation, not a panic.

Source

pub fn with_supervisor( config: ChannelConfig, supervisor: ChannelSupervisor, ) -> Self

Creates an ephemeral handle bound to an explicit supervisor (isolation for the registry and tests).

Source

pub fn new_durable( config: ChannelConfig, store: Arc<dyn DurableStore>, ) -> Result<Self, LiminalError>

Creates a durable handle that persists every accepted publish to store before fanning it out to subscribers.

Construction reads the store: every partition’s next-sequence counter is recovered from the existing stream head, so a handle rebuilt over a previously used store resumes appending where the log left off instead of conflicting at sequence zero. A fresh store recovers to zero, which is identical to cold start. This makes construction O(stream length) in store reads and adds store read errors to the failure modes below.

§Errors

Returns LiminalError::PublishFailed when the durable channel cannot be initialized over store, including when recovering the per-partition sequence counters from the store fails.

Source

pub fn new_durable_with_supervisor( config: ChannelConfig, store: Arc<dyn DurableStore>, supervisor: ChannelSupervisor, ) -> Result<Self, LiminalError>

Creates a durable handle bound to an explicit supervisor.

Used by the standalone server so every channel — durable or ephemeral — shares ONE (optionally clustered) supervisor and thus one scheduler, which is the precondition for cross-node delivery (SRV-005): a subscriber pid joined to a channel’s distributed process group must live on the same scheduler that owns the distribution links.

Like Self::new_durable, construction recovers each partition’s next-sequence counter from the store, so restarting over an existing persistence path resumes the log instead of conflicting at sequence zero.

§Errors

Returns LiminalError::PublishFailed when the durable channel cannot be initialized over store, including when recovering the per-partition sequence counters from the store fails.

Source

pub const fn config(&self) -> &ChannelConfig

Returns the channel configuration used to create this handle.

Source

pub fn publish<Payload>(&self, payload: Payload) -> Result<(), LiminalError>
where Payload: AsRef<[u8]>,

Publishes a payload to the channel with the default publisher identity.

§Errors

Returns a LiminalError when the channel cannot accept the payload or the schema rejects it.

Source

pub fn publish_from<Payload>( &self, publisher_id: impl Into<PublisherId>, payload: Payload, ) -> Result<(), LiminalError>
where Payload: AsRef<[u8]>,

Publishes a payload with an explicit publisher identity.

§Errors

Returns a LiminalError when the channel cannot accept the payload or the schema rejects it.

Source

pub fn publish_with_context<Payload>( &self, payload: Payload, publisher_id: PublisherId, causal_context: Option<CausalContext>, ) -> Result<(), LiminalError>
where Payload: AsRef<[u8]>,

Publishes a payload with explicit publisher and causal metadata.

§Errors

Returns a LiminalError when the channel cannot accept the payload or the schema rejects it.

Source

pub fn publish_with_delivery<Payload>( &self, payload: Payload, publisher_id: PublisherId, causal_context: Option<CausalContext>, ) -> Result<ChannelDelivery, LiminalError>
where Payload: AsRef<[u8]>,

Publishes a payload and reports a genuine delivery ack.

Returns a ChannelDelivery whose delivered_count is the number of local subscribers the message was actually delivered to. A caller that needs to know the message was ACCEPTED by a subscriber (not merely buffered/published) inspects ChannelDelivery::is_delivered. This is the channel-library half of the 13-L1 delivery-ack signal; the publish-without- delivery methods stay unchanged for existing callers.

§Errors

Returns a LiminalError when the channel cannot accept the payload or the schema rejects it.

Source

pub fn current_schema_id(&self) -> Result<SchemaId, LiminalError>

Returns the schema version currently owned by the channel actor.

§Errors

Returns a LiminalError when the channel actor cannot be read.

Source

pub fn evolve_schema_add_field( &self, name: impl Into<String>, field_schema: Value, default: Value, ) -> Result<SchemaId, SchemaValidationError>

Evolves the channel schema by adding a defaulted field without disconnecting subscribers.

§Errors

Returns SchemaValidationError when the schema cannot be evolved.

Subscribes to the channel, receiving every published message.

§Errors

Returns a LiminalError when a subscription cannot be created.

Source

pub fn subscribe_with_install( &self, install: InboxInstall, ) -> Result<SubscriptionHandle, LiminalError>

Subscribes with a server-connection InboxInstall: the §5 shared byte budget, per-inbox fairness cap, and R3 wake notifier are installed on the inbox AT CONSTRUCTION — strictly before the registration is published to the channel actor — so no envelope can be admitted uncharged, past the depth cap, or without a wake (the pre-install window is structurally closed, not merely narrowed).

§Errors

Returns a LiminalError when a subscription cannot be created.

Source

pub fn subscribe_filtered<F>( &self, predicate: F, ) -> Result<SubscriptionHandle, LiminalError>
where F: Fn(&Envelope) -> bool + Send + Sync + 'static,

Subscribes with a delivery predicate: only messages for which predicate returns true are delivered to this subscriber. The predicate is owned and evaluated by the actor process (R3).

§Clustering

The predicate filters local-node publishes only. Under clustering (SRV-005), messages published on a remote node are delivered to this subscriber ungated — the predicate is a non-serializable closure and is not propagated across the wire, so remote nodes cannot evaluate it. If you need filtering to hold for cross-node traffic, filter again on receipt rather than relying on this predicate alone.