Skip to main content

Crate micromux_control

Crate micromux_control 

Source
Expand description

The micromux control plane: a per-session local control endpoint and its wire protocol.

The session binds a Unix domain socket (Unix/macOS) keyed by a hash of its canonical config path; clients — the micromux ctl CLI and the MCP proxy — connect, speak newline-delimited JSON (Request/Response), and probe local endpoint paths, removing only the stale sockets no session owns. The core knows nothing about any of this; the server is driven by a micromux::SessionModelReader (reads), a micromux::ServiceControl (mutations and the environment read), and optionally a micromux::TerminalControl (PTY input and resizes from attached TUIs), so it can observe and command but never mutate the model directly.

Modules§

wait
Waiting for a service to become healthy or exit, shared by micromux ctl wait and the MCP waits so both resolve, fail fast, and honor generations the same way.

Structs§

AmbiguousSelection
Details for a selector that matched more than one live session.
CanonicalConfigPath
A session config path in canonical form, the only input endpoint names are derived from.
Client
A connected control client.
ControlServer
The control server. Cheap to clone-share via Arc.
DiskLogReadHealth
Current capacity, occupancy, and timeout history of the disk-log read pool.
DynamicServiceAck
Scheduler acknowledgement for a dynamic-service mutation. Reused directly as the control-protocol wire payload, like ServiceCommandAck.
DynamicServicesCaps
Dynamic-service limits and current usage advertised by a session.
EndpointGuard
A bound control endpoint plus the lifetime ownership lock.
EndpointProbe
Probe result for one concrete endpoint.
InputBytes
Raw PTY input carried by Request::SendInput.
ProbeReport
Structured transport facts collected while resolving a selector.
ProjectClaim
A config’s owner lock, which makes the config’s session unique.
ProtocolVersion
A typed control protocol version.
ReconcileAction
One configured-service change reported by config reconciliation.
ReconcileReceipt
Scheduler acknowledgement for a config reconciliation.
ResolvedEnvironment
Environment variables as the scheduler resolved them, for the session or for one service.
ResolvedSession
A live session selected together with the endpoint that drives it.
RuntimeDirDetail
Usability details for one candidate runtime directory.
RuntimeDirStatus
Preparation status for one plausible runtime directory.
ServiceBrief
A brief, identity-only view of a service for SessionInfo.
SessionCapabilities
Optional session features and their current limits.
SessionIdentity
Static session identity used to answer Describe.
SessionInfo
Live session identity returned by Request::Describe. Never stored on disk.
SocketProbeDetail
Probe details for one derived or discovered control endpoint.
SocketProbeDetails
Probe diagnostics that stay bounded however many dead endpoints a scan finds.
Subscription
A streaming subscription to liveness-only session changes.
UnclaimedProject
A shared hold on a config’s owner lock, which shows that no session claims the config while it lasts.

Enums§

ClaimError
Why claim_project could not claim a config.
ControlEndpoint
A control endpoint, keyed by filesystem path / pipe name. The supported transports are a closed set: no network transport, ever.
ControlError
Errors produced by the control plane.
EndpointProbeResult
The outcome of probing one endpoint.
ErrorCode
A typed error code shared by the protocol and the proxy diagnostics.
ReconcileActionKind
Kind of semantic change reported by config reconciliation.
Request
A request from a client (the micromux ctl CLI or the MCP proxy) to a session’s control server.
Response
A response from a session’s control server.
SelectError
Failures produced while selecting a live session.
SessionSelector
A session selector accepted by the control-plane resolver.
SocketProbeStatus
Result class for a control endpoint probe.

Constants§

ENVIRONMENT_PROTOCOL_VERSION
The first protocol revision whose sessions answer Request::GetEnvironment.
EVENTS_PROTOCOL_VERSION
The first protocol revision whose sessions answer Request::GetEvents.
IDLE_TIMEOUT
How long a request/response connection may sit idle before it is closed.
LISTED_ABSENT_PROBES
Most probes that found nothing live which diagnostics list one by one; the rest are counted.
MAX_FRAME_BYTES
Maximum size of a single protocol frame. Oversized frames are rejected, not buffered, so a broken peer cannot pin memory.
MAX_REMOTE_PASTE_BYTES
The largest paste one Request::SendInput carries.
PROBE_TIMEOUT
How long discovery probes wait before classifying an endpoint as busy/unreachable.
PROTOCOL_VERSION
The current control protocol version.
REQUEST_TIMEOUT
How long a client waits for a single response before giving up.
SESSION_ALREADY_STARTING
How the error a session reports when another session holds its config’s owner lock begins, for a process that only sees the session’s stderr, such as the one that started it.
SESSION_ENV_FILE_PROTOCOL_VERSION
The first protocol revision whose sessions answer Request::GetSessionEnvironment and Request::WriteEnvironmentFile, and load a session-wide env_file.
SUBSCRIPTION_HEARTBEAT_INTERVAL
How often compatible subscription peers exchange a liveness notification while idle.
SUBSCRIPTION_READ_TIMEOUT
How long a version-aware client waits without a subscription frame before reconnecting.
TERMINAL_PROTOCOL_VERSION
The first protocol revision whose sessions answer Request::SendInput and Request::ResizeTerminal.

Functions§

answering_session_probes
Return every probe that answered Describe, preserving probe order.
bind
Bind the control endpoint via the race-safe lifetime-lock dance.
bind_project
Binds a session endpoint under the config’s owner lock, which claim holds.
claim_project
Claims the owner lock of config_path for this process, and records its process id there.
claim_project_at
Claims the owner lock at lock_path like claim_project, for tests that keep their locks out of the user’s coordination directory.
config_for_target
Resolve a config target: use a file directly or search upward from a directory.
coordination_dir
The fixed, private per-user directory for files every micromux process of the user must agree on, such as session locks and the shared proxy’s socket.
coordination_dir_in
The coordination directory of an isolated setup in state_directory, which holds its session locks and its shared proxy’s socket and lock.
endpoint_for
Compute the control endpoint for a session’s canonical config path within runtime_dir.
endpoint_from_hash
Build a control endpoint from a known endpoint hash within runtime_dir.
endpoint_hash
The deterministic short digest of a canonical config path. Fixed length keeps the macOS sun_path budget under control.
endpoint_owner_lock_held
Return whether a live owner currently holds the endpoint’s lifetime lock.
hold_unclaimed_project
Take a hold on the owner lock of config_path when no session claims the config, or return None when one does.
hold_unclaimed_project_at
Takes a hold on the owner lock at lock_path like hold_unclaimed_project, for tests that keep their locks out of the user’s coordination directory.
probe_detail
Convert an endpoint probe into its transport-level diagnostic representation.
probe_endpoint
Probe one known endpoint.
probe_endpoints
Probe known endpoints in order.
probe_runtime_dir
Probe every socket endpoint in one runtime directory.
probe_runtime_dirs
Probe every socket endpoint across runtime directories in one concurrent batch.
resolve_selector
Resolve a selector to exactly one live session across all usable runtime directories.
resolve_selector_in_runtime_dirs
Resolve a selector against caller-supplied runtime directories.
resolve_selector_with_statuses
Resolve a selector across the usable directories among dir_statuses.
runtime_dir
Resolve the per-user runtime directory for micromux endpoints, creating it with restrictive permissions. Returns None when no directory can be resolved (control plane disabled).
runtime_dir_in
The runtime directory of an isolated setup in state_directory, which holds its sessions’ control sockets.
runtime_dir_statuses
Report every plausible runtime directory and whether it is currently usable.
session_config_path_is_under
Return whether a session’s canonical config path is inside a directory.
session_matches_config_path
Return whether a session’s identity hash matches a canonical config path.
transport_supported
Whether this build has a concrete control transport implementation.
unique_answering_session_probes
Return answering sessions deduped by the session start token, preserving first-seen order.
usable_runtime_dirs
Extract the usable paths from runtime-dir preparation results.