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.

§Errors

Returns LiminalError::PublishFailed when the durable channel cannot be initialized over store.

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.

§Errors

Returns LiminalError::PublishFailed when the durable channel cannot be initialized over store.

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_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.