Struct ConnectionSupervisor

Source

pub struct ConnectionSupervisor { /* private fields */ }

Expand description

Supervisor that owns the beamr scheduler for per-connection processes.

Implementations§

Source §

impl ConnectionSupervisor

Source

pub fn from_config(config: &ServerConfig) -> Result<Self, ServerError>

Creates a connection supervisor backed by the services the config’s [services] profile selects: the full liminal channel/conversation stack (the default) or the capability-scoped worker front door. Profile enforcement is build_connection_services’s, so this constructor can never build full services for a worker-front-door config.

§Errors

Returns ServerError when service construction or scheduler startup fails.

Source

pub fn new() -> Result<Self, ServerError>

Creates a connection supervisor with no configured channels.

§Errors

Returns ServerError when scheduler startup fails.

Source

pub fn with_services( services: Arc<dyn ConnectionServices>, ) -> Result<Self, ServerError>

Creates a connection supervisor using an explicit service adapter.

§Errors

Returns ServerError when scheduler startup fails.

Source

pub fn with_services_and_auth( services: Arc<dyn ConnectionServices>, auth_token: Option<Vec<u8>>, ) -> Result<Self, ServerError>

Creates a connection supervisor with an explicit service adapter and the configured connection auth token.

This is the production constructor for callers that build services themselves (the runtime needs the shared channel cluster before the supervisor takes ownership) and therefore cannot use Self::from_config: without it the configured [auth] token would be silently dropped and the server would run open-access.

§Errors

Returns ServerError when scheduler startup fails.

Source

pub fn with_services_and_notifier( services: Arc<dyn ConnectionServices>, notifier: Arc<dyn ConnectionNotifier>, ) -> Result<Self, ServerError>

Creates a connection supervisor with an explicit service adapter and a connection-keyed worker-registration notifier.

The notifier is invoked when a worker registers on a connection and when such a connection closes. Supervisors built via Self::with_services, Self::from_config, or Self::new carry no notifier, so liminal still runs standalone; a WorkerRegister frame is then accepted without any application callback.

§Errors

Returns ServerError when scheduler startup fails.

Source

pub fn spawn_connection( &self, stream: TcpStream, ) -> Result<ConnectionHandle, ServerError>

Spawns one supervised beamr process that owns stream.

§Errors

Returns ServerError when stream configuration or beamr spawn fails.

Source

pub fn scheduler(&self) -> Arc<Scheduler>

Returns the underlying beamr scheduler.

Source

pub fn reap_crashed_connections(&self) -> usize

Reaps connection processes that have exited outside the normal handler path.

Source

pub fn is_tracked(&self, pid: u64) -> bool

Returns true when pid is still tracked by the supervisor.

Source

pub fn active_connection_count(&self) -> usize

Returns the number of tracked live connections.

Source

pub fn active_connection_pids(&self) -> Vec<u64>

Returns the beamr process ids of the currently tracked live connections.

Useful for addressing a specific connection — e.g. as the pid argument to push_to_connection when the caller knows there is a single connected client.

Source

pub fn notify_shutdown_subscribers(&self)

Broadcasts a best-effort shutdown notification to active connections.

Connections with no active subscriptions ignore the notification. Failures to enqueue the control message are logged and skipped; they are not retried.

Source

pub fn force_close_active_connections(&self)

Sends a force-close control message to every tracked connection process.

Each live process attempts one shutdown notification before closing its stream and exiting normally. Enqueue failures are logged and skipped.

Source

pub fn push_to_connection( &self, pid: u64, payload: Vec<u8>, ) -> Result<PushReplyAwaiter, ServerError>

Pushes an opaque payload to a specific connected client over that client’s existing connection and returns an awaiter for the client’s correlated reply.

This is the server-initiated leg (server-to-client), the inverse of every other request frame. It allocates a correlation id, registers a one-shot reply slot keyed by that id, and enqueues a [ConnectionControl::Push] for the connection process owning pid; that process writes a [Frame::Push] out on its socket. When the client answers with a PushReply carrying the same correlation id, the connection process resolves the awaiter’s slot. The returned PushReplyAwaiter blocks (bounded) for that reply.

The reply’s lifetime belongs to the push, not to any one PushReplyAwaiter::receive call: this no-deadline push reserves a slot that is reclaimed only by (a) the reply being consumed or (b) the connection closing. An elapsed receive poll is a benign re-arm, never a failure and never a cancellation. The §5 max_pending_pushes_per_connection cap bounds abandonment; use push_to_connection_with_deadline when the reply must have an explicit expiry.

§Errors

Returns ServerError when the correlation id cannot be allocated, the reply slot cannot be registered, or the control message cannot be enqueued for the (possibly already-gone or concurrently-closing) connection process. PUBLICATION INVARIANT: an Err guarantees no Push control was published — the client never sees a Push frame for a failed call. Conversely Ok promises ADMISSION, not delivery: the awaiter’s outcome is the delivery truth (a push admitted just as its connection closes resolves to the truthful disconnected outcome, never to a lost reply).

Source

pub fn push_to_connection_with_deadline( &self, pid: u64, payload: Vec<u8>, deadline: Duration, ) -> Result<PushReplyAwaiter, ServerError>

Like push_to_connection but attaches an explicit reply deadline to the reserved slot: deadline is a DURATION FROM NOW bounding the reply’s lifetime — a property of THIS push rather than of any PushReplyAwaiter::receive wait quantum.

Deadline expiry is evaluated HOST-SIDE and LAZILY — at the next receive touch, and at connection close at the latest. It never wakes the connection process, adds no timer thread, and runs no periodic sweeper: a push that is abandoned and never polled resolves at the next host-side touch (connection close). At expiry the slot resolves to ServerError::PushReplyExpired, is removed, and its §5 max_pending_pushes_per_connection cap admission is released. An elapsed receive poll BEFORE the deadline is still a benign re-arm. A receive call in flight when the deadline falls due returns the terminal expiry PROMPTLY — it waits the earlier of its quantum and the deadline, so a large quantum can never extend the reply’s lifetime and the terminal outcome is quantum-independent.

The deadline is evaluated at OBSERVATION POINTS, not enforced against the wall clock: a reply that arrives before expiry is observed is delivered normally, even if it arrives after the deadline instant. The deadline bounds waiting and slot occupancy; it is not a delivery-freshness guarantee. (This is deliberate — a reply is checked for at every observation point before the deadline is, so an answer in hand always beats an expiry.)

§Errors

Returns ServerError when deadline is not representable on the monotonic clock (an extreme duration is refused, never a panic), the correlation id cannot be allocated, the reply slot cannot be registered, or the control message cannot be enqueued for the (possibly already-gone or concurrently-closing) connection process. PUBLICATION INVARIANT: an Err guarantees no Push control was published — the client never sees a Push frame for a failed call. Conversely Ok promises ADMISSION, not delivery: the awaiter’s outcome is the delivery truth.

Source