bxcore, loopd, inferproxy: a lock file keeps each to one instance

Co-Authored-By: ornith-1.5-35b-a3b <agent@wntrmute.dev>

crates/bxcore/src/instance.rs

@@ -0,0 +1,97 @@
+//! One instance per daemon (M5b spec, section 9a). Every daemon removes a socket it finds at its
+//! path before it binds, so a second copy started by mistake would take the sockets of the one
+//! that runs. Before it touches them, a daemon takes an exclusive lock on its lock file with
+//! `lock`, and keeps the `InstanceLock` until the process ends.
+
+use std::fs::{DirBuilder, File, OpenOptions, TryLockError};
+use std::os::unix::fs::{DirBuilderExt, OpenOptionsExt};
+use std::path::Path;
+
+/// The runbook entry for both ways `lock` can fail.
+pub const RUNBOOK: &str = "see docs/runbook.md#already-running";
+
+/// A held lock: the open lock file. The system releases the lock when the file is closed, which is
+/// when this is dropped or the process ends, however it ends. The file itself stays: removing it
+/// would let a second copy lock a new file while the first still runs.
+#[derive(Debug)]
+#[must_use = "the lock is released when this value is dropped"]
+pub struct InstanceLock {
+    _file: File,
+}
+
+/// Why `lock` did not take the lock.
+#[derive(Debug)]
+pub enum LockError {
+    /// Another open file holds the lock: another instance is running.
+    Held,
+    /// The lock file, or its directory, could not be created or opened, or the lock failed.
+    Io(std::io::Error),
+}
+
+impl std::fmt::Display for LockError {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match self {
+            LockError::Held => write!(f, "another instance holds the lock"),
+            LockError::Io(e) => write!(f, "{e}"),
+        }
+    }
+}
+
+impl std::error::Error for LockError {
+    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
+        match self {
+            LockError::Held => None,
+            LockError::Io(e) => Some(e),
+        }
+    }
+}
+
+impl LockError {
+    /// The line a daemon prints when it does not start: `role` is its name, `path` the lock file.
+    pub fn line(&self, role: &str, path: &Path) -> String {
+        // `Held`: "{role}: another {role} is running (it holds {path}); {RUNBOOK}".
+        // `Io(e)`: "{role}: cannot take the lock {path}: {e}; {RUNBOOK}".
+        // Each with `format!`, the path shown with `path.display()`.
+        match self {
+            LockError::Held => format!(
+                "{role}: another {role} is running (it holds {}); {RUNBOOK}",
+                path.display()
+            ),
+            LockError::Io(e) => format!(
+                "{role}: cannot take the lock {path}: {e}; {RUNBOOK}",
+                path = path.display()
+            ),
+        }
+    }
+}
+
+/// Take the exclusive lock on `path`, creating the file with mode 0600, and its directory with
+/// mode 0700 when it is missing, as the daemons make their socket directories. The lock is tried
+/// once, never waited for.
+pub fn lock(path: &Path) -> Result<InstanceLock, LockError> {
+    // 1. If `path.parent()` is `Some(dir)`: `DirBuilder::new().recursive(true).mode(0o700)
+    //    .create(dir)`. 2. `OpenOptions::new().write(true).create(true).truncate(false)
+    //    .mode(0o600).open(path)`. An error of either is `LockError::Io`, through `map_err`.
+    // 3. `file.try_lock()`: `Ok(())` is `Ok(InstanceLock { _file: file })`,
+    //    `Err(TryLockError::WouldBlock)` is `Err(LockError::Held)`, and
+    //    `Err(TryLockError::Error(e))` is `Err(LockError::Io(e))`.
+    if let Some(dir) = path.parent() {
+        DirBuilder::new()
+            .recursive(true)
+            .mode(0o700)
+            .create(dir)
+            .map_err(LockError::Io)?;
+    }
+    let file = OpenOptions::new()
+        .write(true)
+        .create(true)
+        .truncate(false)
+        .mode(0o600)
+        .open(path)
+        .map_err(LockError::Io)?;
+    match file.try_lock() {
+        Ok(()) => Ok(InstanceLock { _file: file }),
+        Err(TryLockError::WouldBlock) => Err(LockError::Held),
+        Err(TryLockError::Error(e)) => Err(LockError::Io(e)),
+    }
+}

crates/bxcore/src/lib.rs

@@ -1,5 +1,6 @@
 //! Shared data types and the frame codec for Boxmaker. No policy and no I/O beyond frames, except
-//! the secret store (`secrets`), behind the feature of that name.
+//! the secret store (`secrets`), behind the feature of that name, and the lock that keeps a daemon
+//! to one instance (`instance`).
 
 pub mod audit;
 pub mod chain;
@@ -11,6 +12,7 @@ pub mod grant;
 pub mod hash;
 pub mod hosts;
 pub mod ids;
+pub mod instance;
 pub mod log;
 pub mod memory;
 pub mod sanitize;