Struct ConnectionSupervisor 

pub struct ConnectionSupervisor { /* private fields */ }

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

Implementations

impl ConnectionSupervisor

pub fn install_link_call_executor( &self, host: &LinkHost, ring_bytes: NonZeroUsize, answer_bytes: NonZeroUsize, ) -> Result<Arc<dyn CallExecutor>, CallError>

Installs far calls after this supervisor’s normal Lys admission is ready. ring_bytes bounds each inner transport; answer_bytes bounds a far reply before allocation, independently of the outer Noise frame ceiling.

Errors

A second executor was installed on the same host.

impl ConnectionSupervisor

pub fn incarnation_start_failure(&self) -> Option<ServerError>

The incarnation start’s typed error once it has failed, which a server stopped by that failure returns; nothing while it has not.

impl ConnectionSupervisor

pub fn install_lifecycle( &self, lifecycle: Arc<Lifecycle>, ) -> Result<(), ServerError>

Installs the services registry (SRV-028), once: lifecycle requests are served from it and its processes’ credentials admitted.

Errors

ServerError::ConfigValidation when one is already installed.

pub fn install_revocation( &self, authority: Arc<RevocationAuthority>, ) -> Result<(), ServerError>

Installs the grant-revocation policy (ACCESS-005), once, before the first connection. From then on every Connect must present a pass whose grant-decision binding the authority admits and must negotiate the reason-bearing close; a bearer or open-access Connect is refused revocation_binding_missing.

Errors

ServerError::ConfigValidation when an authority is already installed.

pub fn apply_grant_event( &self, event: &GrantFeedEvent, ) -> Result<ApplyOutcome, ServerError>

Applies one event of the Lys grant-change stream the caller owns and reads (ACCESS-005 R2, R4), then tells each affected connection once. The denied state is in force before any connection is told; when a connection’s control cannot be published the refusal is counted by name and the connection’s own ready wake delivers the sweep. Nothing is retried on a timer.

Errors

ServerError::ConfigValidation when no authority is installed.

impl ConnectionSupervisor

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.

pub fn builder( services: Arc<dyn ConnectionServices>, ) -> ConnectionSupervisorBuilder

Starts composing a connection supervisor over services the caller built and keeps: the embedder’s constructor.

Every other public constructor fixes one of the three optional parts — Self::from_config installs the configured [auth] (bearer AND pass verifier) but builds its own services, Self::with_services_and_auth carries a bearer and never a pass verifier, and Self::with_services_and_notifier carries a notifier and no auth at all. An application that embeds liminal — holding the Arc<LiminalConnectionServices> to publish in-process, verifying registry passes at Connect, and observing connection lifecycle through a notifier — needs all three at once, and this is the one route to them. Nothing set on the builder defaults exactly as the non-config constructors default it: open access, no notifier, signed default limits.

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.

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.

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

Creates a connection supervisor with explicit services, authentication, and operational limits.

Production runtime construction uses this form so the durable incarnation stream’s complete-reference bound is the same signed max_connections bound enforced by connection admission.

Errors

Returns ServerError when incarnation startup or scheduler startup fails.

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, and when a pass-stamped connection attaches and 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.

pub fn admission_readiness(&self) -> AdmissionReadiness

A handle on whether this server can admit a connection, for the readiness probe (P0 #56 R4).

Handed to SharedReadinessState::track_admission once the supervisor exists. The health endpoint binds BEFORE the supervisor is built — liveness has to be answerable while the rest of the server is still coming up — so this cannot be wired at readiness construction and is installed afterwards instead.

pub fn membership_gate(&self) -> Option<Arc<MembershipGate>>

The channel membership gate [auth.lys.membership] installed (ACCESS-006 R2), for the ACCESS-005 grant owner: it installs itself with crate::auth_membership::MembershipGate::install_authority and drives each applied change and resume into the gate through crate::auth_membership::MembershipListener. None without the section.

impl ConnectionSupervisor

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.

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

Returns the underlying beamr scheduler.

pub fn reap_crashed_connections(&self) -> usize

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

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

Returns true when pid is still tracked by the supervisor.

pub fn active_connection_count(&self) -> usize

Returns the number of tracked live connections.

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.

pub fn directory_lookups(&self) -> u64

SRV-027 R4: how many keyed lookups the service directory has made, read by the count pins.

impl ConnectionSupervisor

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

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

Like push_to_connection, with the push made ON subject: the reply slot retains the subject, and a connection admitted on a Lys pass has its PushReply decided as serve on that subject before the slot is resolved (the access matrix’s push_binding source). A refused reply resolves the awaiter to ServerError::PushReplyRefused, so the pusher learns the outcome by type rather than waiting out a deadline. A push made without a subject to a Lys-admitted connection is refused the same way when its reply arrives: the subject is recorded here, at push time, or not at all. deadline is as in push_to_connection_with_deadline.

Errors

As push_to_connection_with_deadline.

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.

pub fn pushes_queued(&self) -> u64

Server Push frames this supervisor’s connections have queued for their sockets since it started. A push that failed, was cancelled or was rolled back never reaches a socket and is not counted.

impl ConnectionSupervisor

pub fn departures(&self) -> Result<u64, ServerError>

How many connections have departed this supervisor: the count of connection records removed, raised by the one removal funnel every exit route reaches. A teardown that completes its connection’s fate does so before the record is removed, so a departure counted here is one whose fate has already completed. Pass it to Self::await_departures.

Errors

Returns ServerError when the departure count’s lock is poisoned.

pub fn await_departures( &self, since: u64, count: u64, deadline: Instant, ) -> Result<bool, ServerError>

Parks until count connections have departed since since, a value Self::departures returned, or until deadline elapses. Returns true when they have departed and false when the deadline won.

Woken by each departure through the removal Condvar, never by a timer or a count scan; the deadline is the one bound on the park.

Errors

Returns ServerError when the departure count’s lock is poisoned.

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.

pub fn force_close_active_connections(&self)

Sends the orderly close control message to every tracked connection process.

Each live process enqueues one protocol Disconnect, drains its outbound buffer, completes its connection fate as ServerShutdown and — on the WebSocket transport — writes a close frame carrying CloseCode::Away and the reason “server shutdown” before exiting normally. A peer reads a shutdown, not an error. Enqueue failures are logged and skipped.

Since 0.14.3 this is the ONLY close route in run_shutdown_sequence: nothing waits for a peer to hang up first, so the log line below is the ordinary shutdown record rather than a warning about an expired drain.

pub fn flush_durable_state(&self) -> Result<(), ServerError>

Flushes durable channel state through the configured liminal services.

Errors

Returns ServerError::ShutdownFlush when the underlying service flush fails.

pub fn shutdown(&self)

Stops the beamr scheduler used by connection processes.

Trait Implementations

impl Clone for ConnectionSupervisor

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for ConnectionSupervisor

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.