use std::fmt;
use std::path::{Path, PathBuf};
#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord)]
pub enum ControlEndpoint {
Unix(PathBuf),
WindowsNamedPipe(String),
}
impl fmt::Display for ControlEndpoint {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
match self {
Self::Unix(path) => write!(f, "{}", path.display()),
Self::WindowsNamedPipe(name) => f.write_str(name),
}
}
}
#[derive(Debug, Clone)]
pub struct RuntimeDirStatus {
pub path: PathBuf,
pub usable: bool,
pub error: Option<String>,
}
#[must_use]
pub fn usable_runtime_dirs(statuses: &[RuntimeDirStatus]) -> Vec<PathBuf> {
statuses
.iter()
.filter(|status| status.usable)
.map(|status| status.path.clone())
.collect()
}
#[cfg(unix)]
#[must_use]
pub const fn transport_supported() -> bool {
true
}
#[cfg(not(unix))]
#[must_use]
pub const fn transport_supported() -> bool {
false
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct CanonicalConfigPath(PathBuf);
impl CanonicalConfigPath {
pub fn new(path: impl AsRef<Path>) -> std::io::Result<Self> {
Ok(Self(std::fs::canonicalize(path)?))
}
pub(crate) fn from_canonicalized(path: PathBuf) -> Self {
Self(path)
}
#[must_use]
pub fn as_path(&self) -> &Path {
&self.0
}
}
impl std::ops::Deref for CanonicalConfigPath {
type Target = Path;
fn deref(&self) -> &Path {
&self.0
}
}
impl AsRef<Path> for CanonicalConfigPath {
fn as_ref(&self) -> &Path {
&self.0
}
}
#[must_use]
pub fn endpoint_hash(config_path: &CanonicalConfigPath) -> String {
hash_path(config_path.as_path())
}
pub(crate) fn hash_path(path: &Path) -> String {
micromux::session::config_path_key(path)
}
#[must_use]
pub fn runtime_dir() -> Option<PathBuf> {
for path in runtime_dir_candidates() {
match ensure_private_dir(&path) {
Ok(()) => return Some(path),
Err(err) => {
tracing::warn!(?err, dir = %path.display(), "failed to prepare runtime dir");
}
}
}
None
}
#[must_use]
pub fn runtime_dir_statuses() -> Vec<RuntimeDirStatus> {
runtime_dir_candidates()
.into_iter()
.map(|path| match ensure_private_dir(&path) {
Ok(()) => RuntimeDirStatus {
path,
usable: true,
error: None,
},
Err(err) => RuntimeDirStatus {
path,
usable: false,
error: Some(err.to_string()),
},
})
.collect()
}
fn runtime_dir_candidates() -> Vec<PathBuf> {
if let Some(state) = micromux::state_directory_override() {
return vec![runtime_dir_in(&state)];
}
let mut candidates = Vec::new();
if let Some(directory) = micromux::project_dir()
.and_then(|directories| directories.runtime_dir().map(Path::to_path_buf))
{
push_unique(&mut candidates, directory);
}
#[cfg(unix)]
if let Some(directory) = xdg_runtime_directory() {
push_unique(&mut candidates, directory);
}
#[cfg(all(unix, target_os = "linux"))]
if let Some(directory) =
systemd_runtime_directory(Path::new("/run/user"), nix::unistd::Uid::current())
{
push_unique(&mut candidates, directory);
}
push_unique(&mut candidates, per_user_fallback_dir());
candidates
}
fn push_unique(candidates: &mut Vec<PathBuf>, candidate: PathBuf) {
if !candidates.iter().any(|existing| existing == &candidate) {
candidates.push(candidate);
}
}
#[cfg(unix)]
fn per_user_fallback_dir() -> PathBuf {
let uid = nix::unistd::Uid::current();
std::env::temp_dir().join(format!("micromux-{uid}"))
}
#[cfg(unix)]
pub fn coordination_dir() -> std::io::Result<PathBuf> {
let directory = micromux::state_directory_override().map_or_else(
|| {
let uid = nix::unistd::Uid::current();
Path::new("/tmp").join(format!("micromux-{uid}"))
},
|state| coordination_dir_in(&state),
);
ensure_private_dir(&directory)?;
Ok(directory)
}
#[must_use]
pub fn runtime_dir_in(state_directory: &Path) -> PathBuf {
state_directory.join("run")
}
#[must_use]
pub fn coordination_dir_in(state_directory: &Path) -> PathBuf {
state_directory.join("coordination")
}
#[cfg(unix)]
pub(crate) fn project_lock_path(config_path: &CanonicalConfigPath) -> std::io::Result<PathBuf> {
Ok(coordination_dir()?.join(format!("{}.session.lock", endpoint_hash(config_path))))
}
#[cfg(not(unix))]
fn per_user_fallback_dir() -> PathBuf {
std::env::temp_dir().join("micromux")
}
#[cfg(unix)]
fn xdg_runtime_directory() -> Option<PathBuf> {
std::env::var_os("XDG_RUNTIME_DIR").and_then(|directory| {
if directory.is_empty() {
None
} else {
Some(PathBuf::from(directory).join("micromux"))
}
})
}
#[cfg(all(unix, target_os = "linux"))]
fn systemd_runtime_directory(base: &Path, user_identifier: nix::unistd::Uid) -> Option<PathBuf> {
let user_runtime_directory = base.join(user_identifier.as_raw().to_string());
user_runtime_directory
.is_dir()
.then(|| user_runtime_directory.join("micromux"))
}
#[cfg(unix)]
fn ensure_private_dir(dir: &Path) -> std::io::Result<()> {
use nix::fcntl::{OFlag, open};
use nix::sys::stat::{Mode, SFlag, fchmod, fstat};
use std::os::unix::fs::DirBuilderExt;
std::fs::DirBuilder::new()
.recursive(true)
.mode(0o700)
.create(dir)?;
let fd = open(
dir,
OFlag::O_RDONLY | OFlag::O_DIRECTORY | OFlag::O_NOFOLLOW | OFlag::O_CLOEXEC,
Mode::empty(),
)
.map_err(nix_to_io)?;
let metadata = fstat(&fd).map_err(nix_to_io)?;
if !SFlag::from_bits_truncate(metadata.st_mode).contains(SFlag::S_IFDIR) {
return Err(std::io::Error::new(
std::io::ErrorKind::NotADirectory,
"runtime dir path is not a directory",
));
}
if metadata.st_uid != nix::unistd::Uid::current().as_raw() {
return Err(std::io::Error::new(
std::io::ErrorKind::PermissionDenied,
"runtime dir is not owned by the current user",
));
}
if metadata.st_mode & 0o777 != 0o700 {
fchmod(&fd, Mode::from_bits_truncate(0o700)).map_err(nix_to_io)?;
}
Ok(())
}
#[cfg(unix)]
fn nix_to_io(err: nix::errno::Errno) -> std::io::Error {
std::io::Error::from_raw_os_error(err as i32)
}
#[cfg(not(unix))]
fn ensure_private_dir(dir: &Path) -> std::io::Result<()> {
std::fs::create_dir_all(dir)
}
const ENDPOINT_HASH_LEN: usize = 16;
pub(crate) fn is_endpoint_hash(value: &str) -> bool {
value.len() == ENDPOINT_HASH_LEN
&& value
.bytes()
.all(|byte| matches!(byte, b'0'..=b'9' | b'a'..=b'f'))
}
#[cfg(unix)]
pub(crate) fn session_socket_hash(path: &Path) -> Option<&str> {
let hash = path.file_name()?.to_str()?.strip_suffix(".sock")?;
is_endpoint_hash(hash).then_some(hash)
}
#[must_use]
pub fn endpoint_from_hash(runtime_dir: &Path, hash: &str) -> ControlEndpoint {
#[cfg(unix)]
{
ControlEndpoint::Unix(runtime_dir.join(format!("{hash}.sock")))
}
#[cfg(not(unix))]
{
let _ = runtime_dir;
ControlEndpoint::WindowsNamedPipe(format!(r"\\.\pipe\micromux-{hash}"))
}
}
#[must_use]
pub fn endpoint_for(runtime_dir: &Path, config_path: &CanonicalConfigPath) -> ControlEndpoint {
endpoint_from_hash(runtime_dir, &endpoint_hash(config_path))
}
#[cfg(test)]
mod tests {
use super::*;
#[cfg(unix)]
use color_eyre::eyre;
use similar_asserts::assert_eq;
#[cfg(all(unix, target_os = "linux"))]
use std::io;
#[cfg(unix)]
#[test]
fn only_endpoint_hash_sockets_are_session_sockets() -> eyre::Result<()> {
let directory = Path::new("/run/micromux");
let config = CanonicalConfigPath(PathBuf::from("/home/user/project/micromux.yaml"));
let ControlEndpoint::Unix(session) = endpoint_for(directory, &config) else {
eyre::bail!("expected a Unix socket endpoint");
};
assert_eq!(
session_socket_hash(&session),
Some(endpoint_hash(&config).as_str())
);
for other in [
"proxy.sock",
"garbage.sock",
"3F98F83E6E2C8D23.sock",
"3f98f83e6e2c8d2.sock",
"3f98f83e6e2c8d233.sock",
"3f98f83e6e2c8d23.lock",
"3f98f83e6e2c8d23.session.lock",
] {
assert_eq!(session_socket_hash(&directory.join(other)), None, "{other}");
}
Ok(())
}
#[test]
fn endpoint_hash_is_deterministic_and_fixed_length() {
let a = hash_path(Path::new("/home/user/project/micromux.yaml"));
let b = hash_path(Path::new("/home/user/project/micromux.yaml"));
let c = hash_path(Path::new("/home/user/other/micromux.yaml"));
assert_eq!(a, b);
assert_eq!(a, "3f98f83e6e2c8d23");
assert_eq!(a.len(), 16);
assert_ne!(a, c);
}
#[cfg(unix)]
#[test]
fn symlinked_and_real_config_paths_derive_the_same_endpoint() -> eyre::Result<()> {
let root = tempfile::tempdir()?;
let project = root.path().join("project");
std::fs::create_dir(&project)?;
let config = project.join("micromux.yaml");
std::fs::write(&config, "version: 1\nservices: {}\n")?;
let alias = root.path().join("alias");
std::os::unix::fs::symlink(&project, &alias)?;
let through_real = CanonicalConfigPath::new(&config)?;
let through_alias = CanonicalConfigPath::new(alias.join("micromux.yaml"))?;
assert_eq!(through_real, through_alias);
assert_eq!(
endpoint_for(root.path(), &through_real),
endpoint_for(root.path(), &through_alias)
);
Ok(())
}
#[cfg(unix)]
#[test]
fn per_user_fallback_socket_path_fits_the_darwin_sun_path_budget() -> eyre::Result<()> {
use std::os::unix::ffi::OsStrExt;
const DARWIN_SUN_PATH_LEN: usize = 104;
let representative_macos_tmp =
Path::new("/var/folders/8j/sfr9qqcj73j4p6nhwcfpr0th0000gn/T");
let uid = nix::unistd::Uid::current().to_string();
let fallback_name = per_user_fallback_dir()
.file_name()
.map(|name| name.to_string_lossy().into_owned())
.ok_or_else(|| eyre::eyre!("fallback runtime dir has no final component"))?;
assert!(
fallback_name.contains(&uid),
"fallback dir name {fallback_name:?} no longer embeds the uid; update this test"
);
let worst_case_name = fallback_name.replace(&uid, &u32::MAX.to_string());
let worst_case_dir = representative_macos_tmp.join(worst_case_name);
let hash = hash_path(Path::new("/any/project/micromux.yaml"));
let ControlEndpoint::Unix(socket_path) = endpoint_from_hash(&worst_case_dir, &hash) else {
eyre::bail!("a unix build must derive unix socket endpoints");
};
let len = socket_path.as_os_str().as_bytes().len();
assert!(
len < DARWIN_SUN_PATH_LEN,
"worst-case fallback socket path is {len} bytes, over the {DARWIN_SUN_PATH_LEN}-byte \
macOS sun_path budget: {}",
socket_path.display()
);
Ok(())
}
#[cfg(not(unix))]
#[test]
fn non_unix_endpoints_are_named_pipes_and_transport_is_unsupported() {
let hash = hash_path(Path::new("C:/project/micromux.yaml"));
let endpoint = endpoint_from_hash(Path::new("ignored"), &hash);
assert_eq!(
endpoint,
ControlEndpoint::WindowsNamedPipe(format!(r"\\.\pipe\micromux-{hash}"))
);
assert!(!transport_supported());
}
#[cfg(unix)]
#[test]
fn endpoint_hash_uses_raw_unix_path_bytes() {
use std::ffi::OsString;
use std::os::unix::ffi::OsStringExt;
let first = PathBuf::from(OsString::from_vec(b"/tmp/micromux-\xff.yaml".to_vec()));
let second = PathBuf::from(OsString::from_vec(b"/tmp/micromux-\xfe.yaml".to_vec()));
assert_ne!(hash_path(&first), hash_path(&second));
}
#[cfg(unix)]
#[test]
fn ensure_private_dir_rejects_symlink_leaf() -> std::io::Result<()> {
use std::os::unix::fs::PermissionsExt;
let root = tempfile::Builder::new()
.prefix("micromux-control-symlink-test-")
.tempdir()?;
let target = root.path().join("target");
std::fs::create_dir_all(&target)?;
std::fs::set_permissions(&target, std::fs::Permissions::from_mode(0o755))?;
let link = root.path().join("link");
std::os::unix::fs::symlink(&target, &link)?;
let err = ensure_private_dir(&link).expect_err("symlink leaf must be rejected");
assert!(is_symlink_leaf_error(&err));
assert_eq!(
std::fs::metadata(&target)?.permissions().mode() & 0o777,
0o755,
"the symlink target must not be chmodded"
);
Ok(())
}
#[cfg(all(unix, target_os = "linux"))]
#[test]
fn inferred_systemd_runtime_directory_matches_project_runtime_shape() -> io::Result<()> {
let root = tempfile::Builder::new()
.prefix("micromux-control-endpoint-test-")
.tempdir()?;
let user_identifier = nix::unistd::Uid::from_raw(4242);
assert_eq!(
systemd_runtime_directory(root.path(), user_identifier),
None
);
let user_runtime_directory = root.path().join("4242");
std::fs::create_dir_all(&user_runtime_directory)?;
assert_eq!(
systemd_runtime_directory(root.path(), user_identifier),
Some(user_runtime_directory.join("micromux"))
);
Ok(())
}
#[cfg(unix)]
fn is_symlink_leaf_error(err: &std::io::Error) -> bool {
matches!(
err.kind(),
std::io::ErrorKind::AlreadyExists | std::io::ErrorKind::NotADirectory
) || err.raw_os_error() == Some(nix::errno::Errno::ELOOP as i32)
}
}