use anyhow::{Context, Result};
use serde::Deserialize;
use std::env;
use std::fs;
use std::path::{Path, PathBuf};
#[derive(Clone, Debug, Deserialize, PartialEq, Eq)]
pub enum MuxServerStatus {
Starting,
Running,
Restarting,
Failed(String),
Stopped,
}
impl MuxServerStatus {
pub fn label(&self) -> &'static str {
match self {
MuxServerStatus::Starting => "Starting",
MuxServerStatus::Running => "Running",
MuxServerStatus::Restarting => "Restarting",
MuxServerStatus::Failed(_) => "Failed",
MuxServerStatus::Stopped => "Stopped",
}
}
pub fn is_healthy(&self) -> bool {
matches!(
self,
MuxServerStatus::Running | MuxServerStatus::Starting | MuxServerStatus::Restarting
)
}
pub fn failure_reason(&self) -> Option<&str> {
match self {
MuxServerStatus::Failed(reason) => Some(reason.as_str()),
_ => None,
}
}
}
#[derive(Clone, Debug, Deserialize)]
pub struct MuxStatusSnapshot {
pub service_name: String,
pub server_status: MuxServerStatus,
pub restarts: u64,
pub connected_clients: usize,
pub active_clients: usize,
pub max_active_clients: usize,
pub pending_requests: usize,
pub cached_initialize: bool,
pub initializing: bool,
#[serde(default)]
pub last_reset: Option<String>,
pub queue_depth: usize,
#[serde(default)]
pub child_pid: Option<u32>,
pub max_request_bytes: usize,
pub restart_backoff_ms: u64,
pub restart_backoff_max_ms: u64,
pub max_restarts: u64,
}
impl MuxStatusSnapshot {
pub fn from_json(raw: &str) -> Result<Self> {
serde_json::from_str(raw).context("failed to parse rmcp-mux status JSON")
}
pub fn read(path: &Path) -> Result<Self> {
let path = safe_status_file(path)?;
let raw = fs::read_to_string(&path)
.with_context(|| format!("failed to read rmcp-mux status file {}", path.display()))?;
Self::from_json(&raw).with_context(|| format!("rmcp-mux status file {}", path.display()))
}
pub fn summary_line(&self) -> String {
let mut parts = vec![format!(
"{}: {} clients={}/{} pending={} queue={} restarts={}",
self.service_name,
self.server_status.label(),
self.active_clients,
self.connected_clients,
self.pending_requests,
self.queue_depth,
self.restarts,
)];
if let Some(pid) = self.child_pid {
parts.push(format!("pid={pid}"));
}
if let Some(reason) = self.server_status.failure_reason() {
parts.push(format!("reason={reason}"));
}
parts.join(" ")
}
}
fn safe_status_file(path: &Path) -> Result<PathBuf> {
if path.extension().and_then(|ext| ext.to_str()) != Some("json") {
anyhow::bail!("refusing non-json rmcp-mux status file {}", path.display());
}
let meta = fs::symlink_metadata(path)
.with_context(|| format!("failed to inspect rmcp-mux status file {}", path.display()))?;
if meta.file_type().is_symlink() || !meta.is_file() {
anyhow::bail!("refusing unsafe rmcp-mux status file {}", path.display());
}
fs::canonicalize(path).with_context(|| {
format!(
"failed to canonicalize rmcp-mux status file {}",
path.display()
)
})
}
fn default_mux_status_root() -> Option<PathBuf> {
let home = env::var_os("HOME").filter(|value| !value.is_empty())?;
Some(PathBuf::from(home).join(".rmcp_servers/rmcp_mux"))
}
pub fn discover_status_files() -> Vec<PathBuf> {
let mut out: Vec<PathBuf> = Vec::new();
let mut seen: std::collections::BTreeSet<PathBuf> = std::collections::BTreeSet::new();
if let Some(raw) = env::var_os("VIBECRAFTED_MUX_STATUS_PATHS")
&& !raw.is_empty()
{
let raw = raw.to_string_lossy().into_owned();
for entry in raw.split(':').filter(|s| !s.is_empty()) {
let path = PathBuf::from(entry);
if seen.insert(path.clone()) {
out.push(path);
}
}
}
if let Some(root) = default_mux_status_root() {
let flat = root.join("status.json");
if flat.is_file() && seen.insert(flat.clone()) {
out.push(flat);
}
if let Ok(entries) = fs::read_dir(&root) {
let mut dir_files: Vec<PathBuf> = entries
.filter_map(|entry| entry.ok())
.filter(|entry| {
entry.file_type().map(|ty| ty.is_file()).unwrap_or(false)
&& entry.path().extension().and_then(|ext| ext.to_str()) == Some("json")
})
.map(|entry| entry.path())
.collect();
dir_files.sort();
for path in dir_files {
if seen.insert(path.clone()) {
out.push(path);
}
}
}
}
out
}
pub fn read_all_known_snapshots() -> Vec<(PathBuf, Result<MuxStatusSnapshot>)> {
discover_status_files()
.into_iter()
.map(|path| {
let snapshot = MuxStatusSnapshot::read(&path);
(path, snapshot)
})
.collect()
}
#[derive(Clone, Debug)]
pub struct MuxSummary {
pub path: PathBuf,
pub display_name: String,
pub state: MuxSummaryState,
}
#[derive(Clone, Debug)]
pub enum MuxSummaryState {
Healthy(MuxStatusSnapshot),
Unhealthy(MuxStatusSnapshot),
Unreadable { error: String },
}
impl MuxSummary {
pub fn from_path_and_result(path: PathBuf, result: Result<MuxStatusSnapshot>) -> Self {
match result {
Ok(snapshot) => {
let display_name = snapshot.service_name.clone();
let state = if snapshot.server_status.is_healthy() {
MuxSummaryState::Healthy(snapshot)
} else {
MuxSummaryState::Unhealthy(snapshot)
};
MuxSummary {
path,
display_name,
state,
}
}
Err(err) => {
let display_name = path
.file_stem()
.and_then(|stem| stem.to_str())
.map(ToOwned::to_owned)
.unwrap_or_else(|| path.to_string_lossy().into_owned());
MuxSummary {
path,
display_name,
state: MuxSummaryState::Unreadable {
error: format!("{err:#}"),
},
}
}
}
}
pub fn is_healthy(&self) -> bool {
matches!(self.state, MuxSummaryState::Healthy(_))
}
pub fn summary_line(&self) -> String {
match &self.state {
MuxSummaryState::Healthy(snapshot) | MuxSummaryState::Unhealthy(snapshot) => {
snapshot.summary_line()
}
MuxSummaryState::Unreadable { error } => {
format!("{}: unreadable ({error})", self.display_name)
}
}
}
}
pub fn current_summaries() -> Vec<MuxSummary> {
read_all_known_snapshots()
.into_iter()
.map(|(path, result)| MuxSummary::from_path_and_result(path, result))
.collect()
}
#[cfg(test)]
mod tests {
use super::*;
const RUNNING_FIXTURE: &str = r#"{
"service_name": "general-memory",
"server_status": "Running",
"restarts": 0,
"connected_clients": 3,
"active_clients": 1,
"max_active_clients": 5,
"pending_requests": 0,
"cached_initialize": true,
"initializing": false,
"last_reset": null,
"queue_depth": 0,
"child_pid": 12345,
"max_request_bytes": 1048576,
"restart_backoff_ms": 1000,
"restart_backoff_max_ms": 30000,
"max_restarts": 5
}"#;
const FAILED_FIXTURE: &str = r#"{
"service_name": "brave-search",
"server_status": {"Failed": "max restarts reached"},
"restarts": 5,
"connected_clients": 0,
"active_clients": 0,
"max_active_clients": 5,
"pending_requests": 0,
"cached_initialize": false,
"initializing": false,
"last_reset": "2026-04-30T12:00:00Z",
"queue_depth": 0,
"child_pid": null,
"max_request_bytes": 1048576,
"restart_backoff_ms": 1000,
"restart_backoff_max_ms": 30000,
"max_restarts": 5
}"#;
const FORWARD_COMPAT_FIXTURE: &str = r#"{
"service_name": "loctree",
"server_status": "Starting",
"restarts": 0,
"connected_clients": 0,
"active_clients": 0,
"max_active_clients": 5,
"pending_requests": 0,
"cached_initialize": false,
"initializing": true,
"queue_depth": 0,
"max_request_bytes": 1048576,
"restart_backoff_ms": 1000,
"restart_backoff_max_ms": 30000,
"max_restarts": 5,
"future_unknown_field": {"new": "shape"}
}"#;
#[test]
fn parses_running_snapshot_with_pid() {
let snap = MuxStatusSnapshot::from_json(RUNNING_FIXTURE).unwrap();
assert_eq!(snap.service_name, "general-memory");
assert_eq!(snap.server_status, MuxServerStatus::Running);
assert_eq!(snap.child_pid, Some(12345));
assert!(snap.cached_initialize);
assert_eq!(snap.connected_clients, 3);
assert_eq!(snap.active_clients, 1);
assert!(snap.server_status.is_healthy());
assert!(snap.server_status.failure_reason().is_none());
}
#[test]
fn parses_failed_snapshot_and_carries_reason() {
let snap = MuxStatusSnapshot::from_json(FAILED_FIXTURE).unwrap();
assert_eq!(snap.service_name, "brave-search");
assert_eq!(snap.server_status.label(), "Failed");
assert_eq!(
snap.server_status.failure_reason(),
Some("max restarts reached")
);
assert!(!snap.server_status.is_healthy());
assert_eq!(snap.restarts, 5);
assert_eq!(snap.child_pid, None);
assert_eq!(snap.last_reset.as_deref(), Some("2026-04-30T12:00:00Z"));
}
#[test]
fn unknown_extra_fields_do_not_break_parsing() {
let snap = MuxStatusSnapshot::from_json(FORWARD_COMPAT_FIXTURE).unwrap();
assert_eq!(snap.service_name, "loctree");
assert_eq!(snap.server_status, MuxServerStatus::Starting);
assert!(snap.initializing);
}
#[test]
fn summary_line_packs_the_essentials_and_includes_pid_when_present() {
let snap = MuxStatusSnapshot::from_json(RUNNING_FIXTURE).unwrap();
let line = snap.summary_line();
assert!(line.contains("general-memory: Running"));
assert!(line.contains("clients=1/3"));
assert!(line.contains("pending=0"));
assert!(line.contains("queue=0"));
assert!(line.contains("restarts=0"));
assert!(line.contains("pid=12345"));
assert!(!line.contains("reason="));
}
#[test]
fn summary_line_surfaces_failure_reason_for_failed_state() {
let snap = MuxStatusSnapshot::from_json(FAILED_FIXTURE).unwrap();
let line = snap.summary_line();
assert!(line.contains("brave-search: Failed"));
assert!(line.contains("reason=max restarts reached"));
assert!(line.contains("restarts=5"));
assert!(!line.contains("pid="));
}
#[test]
fn read_returns_actionable_io_error_for_missing_file() {
let dir = tempfile::tempdir().unwrap();
let missing = dir.path().join("does-not-exist.json");
let err = MuxStatusSnapshot::read(&missing).expect_err("missing file must error");
let chain = format!("{err:#}");
assert!(
chain.contains(missing.to_string_lossy().as_ref()),
"error chain should embed the path: {chain}"
);
}
#[test]
fn read_refuses_non_json_status_file() {
let dir = tempfile::tempdir().unwrap();
let status = dir.path().join("status.txt");
fs::write(&status, RUNNING_FIXTURE).unwrap();
let err = MuxStatusSnapshot::read(&status).expect_err("non-json status must be refused");
let chain = format!("{err:#}");
assert!(
chain.contains("refusing non-json rmcp-mux status file"),
"error chain should explain the refused path shape: {chain}"
);
}
#[cfg(unix)]
#[test]
fn read_refuses_symlinked_status_file() {
use std::os::unix::fs::symlink;
let dir = tempfile::tempdir().unwrap();
let real = dir.path().join("real.json");
let linked = dir.path().join("status.json");
fs::write(&real, RUNNING_FIXTURE).unwrap();
symlink(&real, &linked).unwrap();
let err = MuxStatusSnapshot::read(&linked).expect_err("symlinked status must be refused");
let chain = format!("{err:#}");
assert!(
chain.contains("refusing unsafe rmcp-mux status file"),
"error chain should explain the refused symlink: {chain}"
);
}
fn env_guard() -> std::sync::MutexGuard<'static, ()> {
use std::sync::{Mutex, OnceLock};
static LOCK: OnceLock<Mutex<()>> = OnceLock::new();
LOCK.get_or_init(|| Mutex::new(()))
.lock()
.unwrap_or_else(|err| err.into_inner())
}
fn with_env<F, R>(home: Option<&Path>, paths: Option<&str>, f: F) -> R
where
F: FnOnce() -> R,
{
let prev_home = env::var_os("HOME");
let prev_paths = env::var_os("VIBECRAFTED_MUX_STATUS_PATHS");
unsafe {
match home {
Some(p) => env::set_var("HOME", p),
None => env::remove_var("HOME"),
}
match paths {
Some(v) => env::set_var("VIBECRAFTED_MUX_STATUS_PATHS", v),
None => env::remove_var("VIBECRAFTED_MUX_STATUS_PATHS"),
}
}
let result = f();
unsafe {
match prev_home {
Some(value) => env::set_var("HOME", value),
None => env::remove_var("HOME"),
}
match prev_paths {
Some(value) => env::set_var("VIBECRAFTED_MUX_STATUS_PATHS", value),
None => env::remove_var("VIBECRAFTED_MUX_STATUS_PATHS"),
}
}
result
}
#[test]
fn discovery_returns_empty_when_home_has_no_rmcp_dir() {
let _guard = env_guard();
let dir = tempfile::tempdir().unwrap();
with_env(Some(dir.path()), None, || {
let files = discover_status_files();
assert!(
files.is_empty(),
"expected no status files under empty HOME: got {files:?}"
);
});
}
#[test]
fn discovery_picks_up_default_root_status_json_and_lexicographic_extras() {
let _guard = env_guard();
let dir = tempfile::tempdir().unwrap();
let root = dir.path().join(".rmcp_servers/rmcp_mux");
fs::create_dir_all(&root).unwrap();
fs::write(root.join("status.json"), "{}").unwrap();
fs::write(root.join("brave-search.json"), "{}").unwrap();
fs::write(root.join("memory.json"), "{}").unwrap();
fs::write(root.join("notes.txt"), "ignored").unwrap();
with_env(Some(dir.path()), None, || {
let files = discover_status_files();
let names: Vec<String> = files
.iter()
.map(|path| path.file_name().unwrap().to_string_lossy().into_owned())
.collect();
assert_eq!(
names,
vec!["status.json", "brave-search.json", "memory.json"],
"expected status.json first, then *.json sorted lexicographically: got {files:?}"
);
});
}
#[test]
fn discovery_honors_env_override_first_then_default_root_extras() {
let _guard = env_guard();
let dir = tempfile::tempdir().unwrap();
let root = dir.path().join(".rmcp_servers/rmcp_mux");
fs::create_dir_all(&root).unwrap();
fs::write(root.join("status.json"), "{}").unwrap();
let override_path = dir.path().join("custom.json");
fs::write(&override_path, "{}").unwrap();
let env_value = override_path.to_string_lossy().into_owned();
with_env(Some(dir.path()), Some(&env_value), || {
let files = discover_status_files();
assert_eq!(
files.first().map(|p| p.as_path()),
Some(override_path.as_path()),
"env override must come first: got {files:?}"
);
assert!(
files
.iter()
.any(|p| p.file_name().and_then(|s| s.to_str()) == Some("status.json")),
"default-root status.json must still be discovered after the override"
);
let unique: std::collections::BTreeSet<&Path> =
files.iter().map(|p| p.as_path()).collect();
assert_eq!(unique.len(), files.len(), "no duplicates: {files:?}");
});
}
#[test]
fn mux_summary_classifies_healthy_unhealthy_and_unreadable() {
let path = PathBuf::from("/tmp/general-memory.json");
let healthy = MuxSummary::from_path_and_result(
path.clone(),
MuxStatusSnapshot::from_json(RUNNING_FIXTURE),
);
assert!(healthy.is_healthy());
assert_eq!(healthy.display_name, "general-memory");
assert!(matches!(healthy.state, MuxSummaryState::Healthy(_)));
assert!(healthy.summary_line().contains("Running"));
let failed = MuxSummary::from_path_and_result(
path.clone(),
MuxStatusSnapshot::from_json(FAILED_FIXTURE),
);
assert!(!failed.is_healthy());
assert!(matches!(failed.state, MuxSummaryState::Unhealthy(_)));
assert!(failed.summary_line().contains("Failed"));
assert!(failed.summary_line().contains("max restarts reached"));
let broken_path = PathBuf::from("/tmp/loctree-broken.json");
let unreadable =
MuxSummary::from_path_and_result(broken_path.clone(), Err(anyhow::anyhow!("nope")));
assert!(!unreadable.is_healthy());
assert_eq!(unreadable.display_name, "loctree-broken");
let line = unreadable.summary_line();
assert!(line.contains("loctree-broken"));
assert!(line.contains("unreadable"));
assert!(line.contains("nope"));
}
#[test]
fn read_all_known_snapshots_pairs_paths_with_results() {
let _guard = env_guard();
let dir = tempfile::tempdir().unwrap();
let root = dir.path().join(".rmcp_servers/rmcp_mux");
fs::create_dir_all(&root).unwrap();
fs::write(root.join("status.json"), RUNNING_FIXTURE).unwrap();
fs::write(root.join("broken.json"), "not json").unwrap();
with_env(Some(dir.path()), None, || {
let pairs = read_all_known_snapshots();
assert_eq!(pairs.len(), 2);
let (good_path, good_result) = &pairs[0];
assert_eq!(
good_path.file_name().and_then(|s| s.to_str()),
Some("status.json")
);
let snap = good_result.as_ref().expect("status.json must parse");
assert_eq!(snap.service_name, "general-memory");
let (bad_path, bad_result) = &pairs[1];
assert_eq!(
bad_path.file_name().and_then(|s| s.to_str()),
Some("broken.json")
);
assert!(
bad_result.is_err(),
"broken.json must surface a parse error so the operator can see it"
);
});
}
}
use std::sync::{Arc, RwLock};
pub type MuxSummaries = Vec<MuxSummary>;
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum SubscriberState {
Connected,
Reconnecting,
Polling,
Failed,
}
#[derive(Debug)]
pub struct MuxSubscriber {
pub handle: tokio::task::JoinHandle<()>,
pub state: Arc<RwLock<SubscriberState>>,
pub rx: std::sync::mpsc::Receiver<rmcp_mux::ipc::IpcEvent>,
}
impl MuxSubscriber {
pub fn start(socket_path: PathBuf, _summaries: Arc<RwLock<MuxSummaries>>) -> Self {
let (tx, rx) = std::sync::mpsc::channel();
let state = Arc::new(RwLock::new(SubscriberState::Reconnecting));
let state_clone = state.clone();
let handle = tokio::spawn(async move {
let mut attempts = 0;
let mut backoff = std::time::Duration::from_secs(1);
loop {
if let Ok(mut s) = state_clone.write() {
*s = SubscriberState::Reconnecting;
}
match tokio::net::UnixStream::connect(&socket_path).await {
Ok(mut stream) => {
attempts = 0;
backoff = std::time::Duration::from_secs(1);
if let Ok(mut s) = state_clone.write() {
*s = SubscriberState::Connected;
}
use tokio::io::{AsyncBufReadExt, AsyncWriteExt};
let cmd = rmcp_mux::ipc::MuxControlCommand::Subscribe;
if let Ok(json) = serde_json::to_string(&cmd)
&& stream
.write_all(format!("{json}\n").as_bytes())
.await
.is_ok()
{
let (reader, _) = stream.into_split();
let mut lines = tokio::io::BufReader::new(reader).lines();
while let Ok(Some(line)) = lines.next_line().await {
if let Ok(rmcp_mux::ipc::MuxControlResponse::Event(event)) =
serde_json::from_str(&line)
{
let _ = tx.send(event.clone());
if let rmcp_mux::ipc::IpcEvent::StateChange { .. } = event {
}
}
}
}
}
Err(_) => {
attempts += 1;
if attempts >= 10 {
if let Ok(mut s) = state_clone.write() {
*s = SubscriberState::Polling;
}
break;
}
tokio::time::sleep(backoff).await;
backoff = std::cmp::min(backoff * 2, std::time::Duration::from_secs(30));
}
}
}
});
Self { handle, state, rx }
}
}
#[cfg(test)]
mod subscriber_tests {
use super::*;
use rmcp_mux::ipc::{IpcEvent, MuxControlResponse};
use std::sync::Arc;
use tokio::io::{AsyncBufReadExt, AsyncWriteExt};
use tokio::net::UnixListener;
#[tokio::test(start_paused = true)]
async fn connects_and_subscribes() {
let dir = tempfile::tempdir().unwrap();
let socket_path = dir.path().join("mux.sock");
let listener = UnixListener::bind(&socket_path).unwrap();
let summaries = Arc::new(RwLock::new(vec![]));
let sub = MuxSubscriber::start(socket_path.clone(), summaries);
let (mut stream, _) = listener.accept().await.unwrap();
let mut buf = String::new();
tokio::io::BufReader::new(&mut stream)
.read_line(&mut buf)
.await
.unwrap();
assert!(buf.contains("Subscribe"));
for _ in 0..10 {
tokio::task::yield_now().await;
if *sub.state.read().unwrap() == SubscriberState::Connected {
break;
}
}
assert_eq!(*sub.state.read().unwrap(), SubscriberState::Connected);
}
#[tokio::test(start_paused = true)]
async fn reconnects_on_disconnect() {
let dir = tempfile::tempdir().unwrap();
let socket_path = dir.path().join("mux.sock");
let listener = UnixListener::bind(&socket_path).unwrap();
let summaries = Arc::new(RwLock::new(vec![]));
let sub = MuxSubscriber::start(socket_path.clone(), summaries);
{
let (mut stream, _) = listener.accept().await.unwrap();
let mut buf = String::new();
tokio::io::BufReader::new(&mut stream)
.read_line(&mut buf)
.await
.unwrap();
for _ in 0..10 {
tokio::task::yield_now().await;
}
assert_eq!(*sub.state.read().unwrap(), SubscriberState::Connected);
}
tokio::time::advance(std::time::Duration::from_secs(2)).await;
let (mut stream, _) = listener.accept().await.unwrap();
let mut buf = String::new();
tokio::io::BufReader::new(&mut stream)
.read_line(&mut buf)
.await
.unwrap();
for _ in 0..10 {
tokio::task::yield_now().await;
}
assert_eq!(*sub.state.read().unwrap(), SubscriberState::Connected);
}
#[tokio::test(start_paused = true)]
async fn falls_back_to_polling_after_10_attempts() {
let dir = tempfile::tempdir().unwrap();
let socket_path = dir.path().join("mux.sock");
let summaries = Arc::new(RwLock::new(vec![]));
let sub = MuxSubscriber::start(socket_path.clone(), summaries);
for _ in 0..15 {
tokio::time::advance(std::time::Duration::from_secs(40)).await;
tokio::task::yield_now().await;
if *sub.state.read().unwrap() == SubscriberState::Polling {
break;
}
}
assert_eq!(*sub.state.read().unwrap(), SubscriberState::Polling);
}
#[tokio::test(start_paused = true)]
async fn forwards_events_to_rx_channel() {
let dir = tempfile::tempdir().unwrap();
let socket_path = dir.path().join("mux.sock");
let listener = UnixListener::bind(&socket_path).unwrap();
let summaries = Arc::new(RwLock::new(vec![]));
let sub = MuxSubscriber::start(socket_path.clone(), summaries);
let (mut stream, _) = listener.accept().await.unwrap();
let mut buf = String::new();
tokio::io::BufReader::new(&mut stream)
.read_line(&mut buf)
.await
.unwrap();
let evt = IpcEvent::StateChange {
service: "test".into(),
from: "Init".into(),
to: "Running".into(),
};
let resp = MuxControlResponse::Event(evt.clone());
let payload = format!("{}\n", serde_json::to_string(&resp).unwrap());
stream.write_all(payload.as_bytes()).await.unwrap();
let mut received = None;
for _ in 0..20 {
tokio::task::yield_now().await;
if let Ok(e) = sub.rx.try_recv() {
received = Some(e);
break;
}
tokio::time::sleep(std::time::Duration::from_millis(10)).await;
}
assert_eq!(received, Some(evt));
}
}