blockworx/storage/

lock.rs

//! One writer per container.
//!
//! Two editors on one directory would not merely race — each holds a whole
//! document in memory and rewrites `root.kdl` from it, so the second to save
//! silently discards everything the first did. The history would record both
//! sides of the fight as if they were one person's edits.
//!
//! The exclusion is an **advisory lock on the `lock` file**, taken through
//! `File::try_lock`. That matters more than it sounds: the kernel drops the lock
//! when the holding process exits, however it exits, so a crashed session cannot
//! leave a container permanently unopenable. A hand-rolled pid file would need a
//! liveness check, and would get it wrong the first time a pid was reused.
//!
//! The file's *contents* are separate from the exclusion: they name the holder,
//! so the second session can say who has it rather than only that someone does.

use std::fs::File;
use std::path::Path;

use serde::{Deserialize, Serialize};

/// The file a container's claim is taken on.
pub const LOCK: &str = "lock";

/// Who holds a container. Written by the holder, read by whoever is turned away.
#[derive(Clone, PartialEq, Eq, Debug, Serialize, Deserialize)]
pub struct Holder {
    pub pid: u32,
    /// When the claim was taken, in milliseconds since the epoch.
    pub since: u64,
}

/// An exclusive claim on a container, released when this is dropped — or when
/// the process ends, by the kernel.
#[derive(Debug)]
pub struct Lock {
    // Held solely for its lock; the bytes were written when it was taken.
    _file: File,
}

/// The outcome of trying to claim a container.
#[derive(Debug)]
pub enum Claim {
    Held(Lock),
    /// Someone else has it. The holder is `None` when the `lock` file could not
    /// be read or made sense of — which still means taken, just anonymously.
    Taken(Option<Holder>),
}

/// Claim the container rooted at `dir` for this process.
///
/// Creates the directory: taking the claim is what an editing session does when
/// it decides it owns a container, so there is something to own afterwards.
pub fn claim(dir: &Path, now: u64) -> std::io::Result<Claim> {
    std::fs::create_dir_all(dir)?;
    let path = dir.join(LOCK);
    let file = File::options()
        .read(true)
        .write(true)
        .create(true)
        .truncate(false)
        .open(&path)?;

    match file.try_lock() {
        Ok(()) => {
            // Only now, holding the lock, is it safe to replace the previous
            // holder's identity.
            let holder = Holder {
                pid: std::process::id(),
                since: now,
            };
            file.set_len(0)?;
            serde_json::to_writer(&file, &holder).map_err(std::io::Error::other)?;
            Ok(Claim::Held(Lock { _file: file }))
        }
        // Advisory locks do not block reading, so the holder can be named.
        Err(std::fs::TryLockError::WouldBlock) => Ok(Claim::Taken(read_holder(&path))),
        Err(std::fs::TryLockError::Error(e)) => Err(e),
    }
}

fn read_holder(path: &Path) -> Option<Holder> {
    let bytes = std::fs::read(path).ok()?;
    serde_json::from_slice(&bytes).ok()
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::storage::atomic::tests::TempDir;

    #[test]
    fn claiming_a_free_container_succeeds_and_names_the_holder() {
        let dir = TempDir::new("lock-free");
        let root = dir.join("d.bwx");
        let Claim::Held(_held) = claim(&root, 1234).unwrap() else {
            panic!("a container nobody holds should be claimable");
        };
        assert_eq!(
            read_holder(&root.join(LOCK)),
            Some(Holder {
                pid: std::process::id(),
                since: 1234,
            })
        );
    }

    /// The whole point: a second session is turned away rather than allowed to
    /// overwrite the first one's document on its next save.
    #[test]
    fn a_second_claim_is_refused_and_can_say_who_holds_it() {
        let dir = TempDir::new("lock-contended");
        let root = dir.join("d.bwx");
        let Claim::Held(_first) = claim(&root, 1234).unwrap() else {
            panic!("the first claim should succeed");
        };

        let Claim::Taken(holder) = claim(&root, 5678).unwrap() else {
            panic!("the second claim should be refused");
        };
        assert_eq!(
            holder,
            Some(Holder {
                pid: std::process::id(),
                since: 1234,
            }),
            "the refusal should name who has it"
        );
    }

    /// Releasing has to actually release, or closing one editor would leave the
    /// container unopenable until the machine was rebooted.
    #[test]
    fn releasing_the_claim_frees_the_container() {
        let dir = TempDir::new("lock-release");
        let root = dir.join("d.bwx");

        let first = claim(&root, 1).unwrap();
        assert!(matches!(first, Claim::Held(_)));
        assert!(matches!(claim(&root, 2).unwrap(), Claim::Taken(_)));

        drop(first);
        let Claim::Held(_) = claim(&root, 3).unwrap() else {
            panic!("the claim was not released");
        };
    }

    /// A `lock` file left holding nonsense — hand-edited, or from a build that
    /// wrote something else — must not make a free container unopenable.
    #[test]
    fn an_unreadable_lock_file_does_not_block_a_claim() {
        let dir = TempDir::new("lock-garbage");
        let root = dir.join("d.bwx");
        std::fs::create_dir_all(&root).unwrap();
        std::fs::write(root.join(LOCK), b"not json at all").unwrap();

        let Claim::Held(_held) = claim(&root, 9).unwrap() else {
            panic!("nobody holds this, whatever the file says");
        };
        // ...and the nonsense is replaced with a real holder.
        assert_eq!(read_holder(&root.join(LOCK)).map(|h| h.since), Some(9));
    }

    /// The identity is only replaced by whoever actually took the lock, so a
    /// refused session cannot overwrite the holder's name.
    #[test]
    fn a_refused_claim_leaves_the_holders_identity_alone() {
        let dir = TempDir::new("lock-identity");
        let root = dir.join("d.bwx");
        let Claim::Held(_first) = claim(&root, 111).unwrap() else {
            panic!("the first claim should succeed");
        };
        let _ = claim(&root, 222).unwrap();
        assert_eq!(read_holder(&root.join(LOCK)).map(|h| h.since), Some(111));
    }
}