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 waitand the MCP waits so both resolve, fail fast, and honor generations the same way.
Structs§
- Ambiguous
Selection - Details for a selector that matched more than one live session.
- Canonical
Config Path - A session config path in canonical form, the only input endpoint names are derived from.
- Client
- A connected control client.
- Control
Server - The control server. Cheap to clone-share via
Arc. - Disk
LogRead Health - Current capacity, occupancy, and timeout history of the disk-log read pool.
- Dynamic
Service Ack - Scheduler acknowledgement for a dynamic-service mutation. Reused directly as the
control-protocol wire payload, like
ServiceCommandAck. - Dynamic
Services Caps - Dynamic-service limits and current usage advertised by a session.
- Endpoint
Guard - A bound control endpoint plus the lifetime ownership lock.
- Endpoint
Probe - Probe result for one concrete endpoint.
- Input
Bytes - Raw PTY input carried by
Request::SendInput. - Probe
Report - Structured transport facts collected while resolving a selector.
- Project
Claim - A config’s owner lock, which makes the config’s session unique.
- Protocol
Version - A typed control protocol version.
- Reconcile
Action - One configured-service change reported by config reconciliation.
- Reconcile
Receipt - Scheduler acknowledgement for a config reconciliation.
- Resolved
Environment - Environment variables as the scheduler resolved them, for the session or for one service.
- Resolved
Session - A live session selected together with the endpoint that drives it.
- Runtime
DirDetail - Usability details for one candidate runtime directory.
- Runtime
DirStatus - Preparation status for one plausible runtime directory.
- Service
Brief - A brief, identity-only view of a service for
SessionInfo. - Session
Capabilities - Optional session features and their current limits.
- Session
Identity - Static session identity used to answer
Describe. - Session
Info - Live session identity returned by
Request::Describe. Never stored on disk. - Socket
Probe Detail - Probe details for one derived or discovered control endpoint.
- Socket
Probe Details - Probe diagnostics that stay bounded however many dead endpoints a scan finds.
- Subscription
- A streaming subscription to liveness-only session changes.
- Unclaimed
Project - A shared hold on a config’s owner lock, which shows that no session claims the config while it lasts.
Enums§
- Claim
Error - Why
claim_projectcould not claim a config. - Control
Endpoint - A control endpoint, keyed by filesystem path / pipe name. The supported transports are a closed set: no network transport, ever.
- Control
Error - Errors produced by the control plane.
- Endpoint
Probe Result - The outcome of probing one endpoint.
- Error
Code - A typed error code shared by the protocol and the proxy diagnostics.
- Reconcile
Action Kind - Kind of semantic change reported by config reconciliation.
- Request
- A request from a client (the
micromux ctlCLI or the MCP proxy) to a session’s control server. - Response
- A response from a session’s control server.
- Select
Error - Failures produced while selecting a live session.
- Session
Selector - A session selector accepted by the control-plane resolver.
- Socket
Probe Status - 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::SendInputcarries. - 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::GetSessionEnvironmentandRequest::WriteEnvironmentFile, and load a session-wideenv_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::SendInputandRequest::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
claimholds. - claim_
project - Claims the owner lock of
config_pathfor this process, and records its process id there. - claim_
project_ at - Claims the owner lock at
lock_pathlikeclaim_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_pathbudget 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_pathwhen no session claims the config, or returnNonewhen one does. - hold_
unclaimed_ project_ at - Takes a hold on the owner lock at
lock_pathlikehold_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
Nonewhen 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.