blockworx/store/

container.rs

//! The `.bwx` container: a directory, per D1.
//!
//! ```text
//! doc.bwx/
//!   revs/           the whole document at every rev, compressed — THE document
//!   manifest.jsonl  one appended row per rev: who, when, where, what it named
//!   document.json   readable projection at head, self-contained
//!   assets/         content-addressed artwork
//!   lock            advisory single-writer lock
//!   .gitattributes  how git must treat them
//! ```
//!
//! A directory rather than a packed file because appends,
//! content-addressed blobs, and per-writer sidecars all want to be
//! separate files, and because git and text tools then handle a container
//! natively. The single-file form is the share bundle, later.

use std::fs::{File, OpenOptions};
use std::io::Write as _;
use std::path::{Path, PathBuf};

use super::assets;
use super::lock::{Claim, LockGuard, LockHolder};
use super::manifest::{BreakReport, Row};
use super::record::{Digest, WallTime};
use super::revs::{self, REVS};

use blockworx_doc::{document::Document, rev::Rev};

pub const MANIFEST: &str = "manifest.jsonl";
pub const PROJECTION: &str = "document.json";
pub const ASSETS: &str = "assets";
pub const LOCK: &str = "lock";
pub const GITATTRIBUTES: &str = ".gitattributes";

/// D1's template. `document.json` stays *diffable* — reading the change is
/// the whole reason it exists — but never auto-merged, since it is
/// generated and a merged projection would claim to be a fold nothing
/// produced. Two divergent `manifest.jsonl`s are concurrent editing through the
/// back door, which this design deliberately has no answer for, so the
/// conflict is surfaced at merge time instead of waiting for a replay to
/// refuse the result.
const GITATTRIBUTES_TEMPLATE: &str = "\
# A blockworx container. revs/ holds the document at every rev and
# manifest.jsonl is the trail that names them; document.json is a
# projection of the head, regenerated on save.
#
# The merge driver named here is not built in. Define it once, globally:
#     git config --global merge.conflict-always.name 'never auto-merge'
#     git config --global merge.conflict-always.driver false
# Without it git falls back to the text merge, and a merged manifest will
# be refused by the integrity chain at load — loudly, but later.
manifest.jsonl merge=conflict-always
document.json linguist-generated=true merge=binary
revs/** binary
assets/** binary
lock export-ignore
";

/// Why a container is open without the right to write it. Every arm is
/// something the user must be told, which is why this is not a bool.
#[derive(Debug)]
pub enum ReadOnlyReason {
    /// Another live process holds the advisory lock.
    Locked(LockHolder),
    /// Opened to be read rather than edited — someone else's document being
    /// looked at. The lock was never claimed, which is the
    /// whole point: a reader must not stand between an owner and their own
    /// document.
    Reading,
    /// The manifest does not verify; only the prefix before the break is
    /// real.
    HistoryBroken(BreakReport),
    /// A row could not be appended, so this session's document and the
    /// files have parted ways. Nothing more is written until the container
    /// is reopened.
    WriteFailed(std::io::Error),
}

impl std::fmt::Display for ReadOnlyReason {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            ReadOnlyReason::Locked(held) => {
                write!(f, "another blockworx ({held}) has this diagram open")
            }
            ReadOnlyReason::Reading => write!(f, "this container was opened to be read"),
            ReadOnlyReason::HistoryBroken(report) => {
                write!(f, "the manifest does not verify at {report}")
            }
            ReadOnlyReason::WriteFailed(error) => {
                write!(f, "a row could not be appended: {error}")
            }
        }
    }
}

/// Whether this handle may write, and the manifest it writes through.
pub enum Access {
    Writable(Writer),
    ReadOnly(ReadOnlyReason),
}

pub struct Writer {
    manifest: File,
    /// Released when the container is dropped, and moved with the container
    /// when it is renamed.
    lock: LockGuard,
}

/// Why a container could not be opened at all — as opposed to opened
/// read-only, which is an outcome rather than a failure.
#[derive(Debug, thiserror::Error)]
pub enum ContainerError {
    #[error("{0} already holds a diagram")]
    Exists(PathBuf),
    #[error("{0} is not a blockworx diagram: it has no {MANIFEST}")]
    NotAContainer(PathBuf),
    #[error(transparent)]
    Io(#[from] std::io::Error),
}

pub struct Container {
    root: PathBuf,
    access: Access,
}

impl Container {
    /// Lay out a new container and take its lock.
    ///
    /// # Errors
    /// [`ContainerError::Exists`] if `root` already holds a manifest, or the
    /// underlying I/O failure.
    pub fn create(root: &Path, now: WallTime) -> Result<Self, ContainerError> {
        Self::create_holding(root, now, b"")
    }

    /// The same, with `rows` already in it — the prefix Save-as, which
    /// copies an existing manifest's lines rather than re-writing them.
    /// The bytes go down before the lock is taken, so nothing can append
    /// into the middle of them.
    ///
    /// # Errors
    /// As [`Self::create`].
    pub fn create_holding(root: &Path, now: WallTime, rows: &[u8]) -> Result<Self, ContainerError> {
        if root.join(MANIFEST).exists() {
            return Err(ContainerError::Exists(root.to_path_buf()));
        }
        std::fs::create_dir_all(root.join(ASSETS))?;
        std::fs::create_dir_all(root.join(REVS))?;
        std::fs::write(root.join(GITATTRIBUTES), GITATTRIBUTES_TEMPLATE)?;
        let mut file = File::create(root.join(MANIFEST))?;
        file.write_all(rows)?;
        file.sync_all()?;
        // The entries themselves, not just their contents: a power cut
        // between here and the first append must not leave a directory
        // that has a manifest in it only sometimes.
        sync_dir(root)?;
        Self::attach(root, now)
    }

    /// Open an existing container, taking its lock if nobody holds it.
    ///
    /// # Errors
    /// [`ContainerError::NotAContainer`] when there is no manifest to open, or
    /// the underlying I/O failure.
    pub fn open(root: &Path, now: WallTime) -> Result<Self, ContainerError> {
        Self::require_manifest(root)?;
        Self::attach(root, now)
    }

    /// Open an existing container to be read and never written, leaving the
    /// lock untouched.
    ///
    /// The honest mode for a reader: claiming the lock merely to look
    /// would either demote the session editing that container or hold a
    /// lock against one nobody is writing, and a handle that will refuse
    /// every write anyway has no business taking either.
    ///
    /// # Errors
    /// As [`Self::open`].
    pub fn reading(root: &Path) -> Result<Self, ContainerError> {
        Self::require_manifest(root)?;
        Ok(Self {
            root: root.to_path_buf(),
            access: Access::ReadOnly(ReadOnlyReason::Reading),
        })
    }

    fn require_manifest(root: &Path) -> Result<(), ContainerError> {
        if root.join(MANIFEST).is_file() {
            Ok(())
        } else {
            Err(ContainerError::NotAContainer(root.to_path_buf()))
        }
    }

    fn attach(root: &Path, now: WallTime) -> Result<Self, ContainerError> {
        let access = match super::lock::claim(root, now)? {
            Claim::Held(held) => Access::ReadOnly(ReadOnlyReason::Locked(held)),
            Claim::Taken(lock) => Access::Writable(Writer {
                manifest: OpenOptions::new().append(true).open(root.join(MANIFEST))?,
                lock,
            }),
        };
        Ok(Self {
            root: root.to_path_buf(),
            access,
        })
    }

    pub fn root(&self) -> &Path {
        &self.root
    }

    pub fn access(&self) -> &Access {
        &self.access
    }

    /// Rename this container's directory — which renames the document,
    /// since the directory's name is what the document is called (D20).
    ///
    /// The session carries on through it: the open manifest is held by a
    /// descriptor rather than by its path, and the lock file moves with the
    /// directory it is inside, so an edit made after the rename lands in
    /// the same manifest the edits before it did.
    ///
    /// # Errors
    /// [`std::io::ErrorKind::AlreadyExists`] when something already stands
    /// at `to`, or the rename's own failure.
    pub fn rename(&mut self, to: &Path) -> std::io::Result<()> {
        if to.exists() {
            return Err(std::io::Error::new(
                std::io::ErrorKind::AlreadyExists,
                format!("{} already exists", to.display()),
            ));
        }
        std::fs::rename(&self.root, to)?;
        // No directory fsync, unlike `create`: a rename a power cut takes
        // back leaves a whole container under its old name, where `create`
        // interrupted would leave half of one.
        self.root = to.to_path_buf();
        if let Access::Writable(writer) = &mut self.access {
            writer.lock.follow(to);
        }
        Ok(())
    }

    /// Give up the right to write, releasing the lock with it. Called when
    /// the manifest turns out not to verify, and when an append fails.
    pub fn demote(&mut self, reason: ReadOnlyReason) {
        self.access = Access::ReadOnly(reason);
    }

    /// # Errors
    /// The underlying read failure.
    pub fn read_manifest(&self) -> std::io::Result<String> {
        std::fs::read_to_string(self.root.join(MANIFEST))
    }

    /// Where this container's artwork is read and written.
    pub fn assets(&self) -> assets::Dir {
        assets::Dir::at(&self.root)
    }

    /// Where this container keeps the document at every rev.
    pub fn revs(&self) -> revs::Dir {
        revs::Dir::at(&self.root)
    }

    /// Write the document as it stands at `rev` into `revs/`, its payloads
    /// into `assets/`, and hand back the digest of the rev's bytes.
    ///
    /// Called before the row that names the rev is appended, so the
    /// manifest never names bytes a crash could still take away — and the
    /// payloads land before the rev that references them, for the same
    /// reason one level down.
    ///
    /// # Errors
    /// [`WriteRefusal::ReadOnly`] if this handle does not hold the lock,
    /// or the write that did not land.
    pub fn write_rev(&mut self, rev: Rev, document: &Document) -> Result<Digest, WriteRefusal> {
        let Access::Writable(_) = &self.access else {
            return Err(WriteRefusal::ReadOnly);
        };
        Ok(revs::write(
            &mut self.revs(),
            rev,
            document,
            &mut self.assets(),
        )?)
    }

    /// The document this container holds at `rev`, payloads and all.
    ///
    /// # Errors
    /// [`revs::RevFault`]: no file, one that is not a document this build
    /// reads, or artwork the container cannot hand back.
    pub fn read_rev(&self, rev: Rev) -> Result<Document, revs::RevFault> {
        let document = revs::read(&self.revs(), rev)?;
        Ok(revs::attached(document, &self.assets())?)
    }

    /// Append one row and make it durable before returning: the line and
    /// its newline in one write, then an fsync. A crash anywhere in here
    /// loses at most this row, and loses it *visibly* — the manifest then
    /// ends without a newline, which is how load knows to drop it.
    ///
    /// # Errors
    /// [`WriteRefusal::ReadOnly`] if this handle does not hold the lock,
    /// or the underlying write failure.
    pub fn append(&mut self, row: &Row) -> Result<(), WriteRefusal> {
        let Access::Writable(writer) = &mut self.access else {
            return Err(WriteRefusal::ReadOnly);
        };
        let mut line = row.canonical_bytes();
        line.push(b'\n');
        writer.manifest.write_all(&line)?;
        writer.manifest.sync_data()?;
        Ok(())
    }

    /// Cut a partial trailing row off, so the next append does not splice
    /// itself onto half a line.
    ///
    /// # Errors
    /// As [`Self::append`].
    pub fn truncate_manifest(&mut self, bytes: u64) -> Result<(), WriteRefusal> {
        let Access::Writable(writer) = &mut self.access else {
            return Err(WriteRefusal::ReadOnly);
        };
        writer.manifest.set_len(bytes)?;
        writer.manifest.sync_all()?;
        Ok(())
    }
}

#[derive(Debug, thiserror::Error)]
pub enum WriteRefusal {
    #[error("this diagram is open read-only")]
    ReadOnly,
    #[error(transparent)]
    Io(#[from] std::io::Error),
}

/// What became of a container offered for [`discard_pristine`].
#[derive(Clone, Copy, PartialEq, Eq, Debug)]
pub enum Discarded {
    Removed,
    /// Something is in it, so it stays: a row in the manifest, artwork, or a
    /// file this layout never writes.
    Kept,
}

/// The files [`Container::create`] lays down. Anything else in a container
/// belongs to whoever put it there.
const LAID_DOWN: [&str; 4] = [MANIFEST, PROJECTION, LOCK, GITATTRIBUTES];

/// The directories it lays down. Each must be empty for the container to
/// count as pristine.
const LAID_DOWN_DIRS: [&str; 2] = [ASSETS, REVS];

/// Remove a container nothing was ever written into — D20's cleanup, so a
/// launch and a quit leave the documents directory as they found it.
///
/// Deliberately timid: an empty manifest is necessary but not sufficient, and
/// only a directory holding exactly what [`Container::create`] laid down is
/// removed. Anything else — a row, an asset, a file the user put beside
/// the manifest — and the container stays, because deleting a directory we did
/// not write every part of is not ours to decide. The caller narrows this
/// further: only a container *this session created* is ever offered.
///
/// # Errors
/// The read or the removal that did not work.
pub fn discard_pristine(root: &Path) -> std::io::Result<Discarded> {
    if std::fs::metadata(root.join(MANIFEST))?.len() != 0 {
        return Ok(Discarded::Kept);
    }
    let mut files = Vec::new();
    let mut dirs = Vec::new();
    for entry in std::fs::read_dir(root)? {
        let entry = entry?;
        let name = entry.file_name();
        let named = |ours: &[&str]| name.to_str().is_some_and(|name| ours.contains(&name));
        let kind = entry.file_type()?;
        if kind.is_dir() && named(&LAID_DOWN_DIRS) {
            if std::fs::read_dir(entry.path())?.next().is_some() {
                return Ok(Discarded::Kept);
            }
            dirs.push(entry.path());
        } else if kind.is_file() && named(&LAID_DOWN) {
            files.push(entry.path());
        } else {
            return Ok(Discarded::Kept);
        }
    }
    for file in files {
        std::fs::remove_file(file)?;
    }
    for dir in dirs {
        std::fs::remove_dir(dir)?;
    }
    std::fs::remove_dir(root)?;
    Ok(Discarded::Removed)
}

/// Flush the directory entry itself, so a freshly laid-out container
/// survives a power cut and not just a process crash.
#[cfg(unix)]
fn sync_dir(dir: &Path) -> std::io::Result<()> {
    File::open(dir)?.sync_all()
}

/// Windows has no directory handle to sync.
#[cfg(not(unix))]
fn sync_dir(_dir: &Path) -> std::io::Result<()> {
    Ok(())
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::store::tests::fixture;

    #[test]
    fn a_created_container_holds_the_whole_template() {
        let dir = fixture::dir("container-layout");
        let root = dir.join("doc.bwx");
        let container =
            Container::create(&root, WallTime::EPOCH).expect("the container is laid out");

        assert!(matches!(container.access(), Access::Writable(_)));
        assert_eq!(container.read_manifest().expect("an empty manifest"), "");
        assert!(root.join(ASSETS).is_dir());
        assert!(root.join(REVS).is_dir(), "a new container has no revs/");
        assert!(
            root.join(LOCK).is_file(),
            "a writable handle holds the lock"
        );
        let attributes =
            std::fs::read_to_string(root.join(GITATTRIBUTES)).expect("the git template");
        assert!(attributes.contains("manifest.jsonl merge=conflict-always"));
        assert!(attributes.contains("document.json linguist-generated=true"));
        assert!(attributes.contains("revs/** binary"));
    }

    #[test]
    fn creating_over_an_existing_container_is_refused() {
        let dir = fixture::dir("container-exists");
        let root = dir.join("doc.bwx");
        let first = Container::create(&root, WallTime::EPOCH).expect("the first is laid out");
        drop(first);

        assert!(matches!(
            Container::create(&root, WallTime::EPOCH),
            Err(ContainerError::Exists(_)),
        ));
        assert!(matches!(
            Container::open(&dir.join("nothing-here"), WallTime::EPOCH),
            Err(ContainerError::NotAContainer(_)),
        ));
    }

    /// The lock is the writable handle's lifetime, so closing a container
    /// hands the next one the right to write.
    #[test]
    fn dropping_a_container_releases_its_lock() {
        let dir = fixture::dir("container-lock-lifetime");
        let root = dir.join("doc.bwx");
        let container = Container::create(&root, WallTime::EPOCH).expect("the container");
        assert!(matches!(
            Container::open(&root, WallTime::EPOCH)
                .expect("a second handle opens")
                .access(),
            Access::ReadOnly(ReadOnlyReason::Locked(_)),
        ));

        drop(container);
        assert!(matches!(
            Container::open(&root, WallTime::EPOCH)
                .expect("a third handle opens")
                .access(),
            Access::Writable(_),
        ));
    }

    /// The property renaming a document rests on: the session keeps the
    /// container through the move. The manifest's descriptor follows the
    /// inode rather than the path, so an append after the rename lands in
    /// the renamed file — and the lock, which is a *path*, has to be told.
    #[test]
    fn a_renamed_container_keeps_its_lock_and_its_open_manifest() {
        let dir = fixture::dir("container-rename");
        let root = dir.join("doc.bwx");
        let renamed = dir.join("engine.bwx");
        let mut container = Container::create(&root, WallTime::EPOCH).expect("the container");
        let row = fixture::rows(1).pop().expect("one row");
        container.append(&row).expect("the first row lands");

        container.rename(&renamed).expect("the container moves");

        assert_eq!(container.root(), renamed);
        assert!(!root.exists(), "the old name still stands");
        assert!(
            renamed.join(LOCK).is_file(),
            "the lock did not travel with the container",
        );
        container.append(&row).expect("an append after the rename");
        assert_eq!(
            std::fs::read_to_string(renamed.join(MANIFEST))
                .expect("the renamed manifest")
                .lines()
                .count(),
            2,
            "the session kept appending to the file it had open",
        );
        assert!(
            matches!(
                Container::open(&renamed, WallTime::EPOCH)
                    .expect("a second handle")
                    .access(),
                Access::ReadOnly(ReadOnlyReason::Locked(_)),
            ),
            "the lock was dropped somewhere in the move",
        );

        drop(container);
        assert!(
            !renamed.join(LOCK).exists(),
            "releasing the lock removed the wrong path",
        );
    }

    #[test]
    fn a_rename_onto_something_that_exists_is_refused() {
        let dir = fixture::dir("container-rename-onto");
        let root = dir.join("doc.bwx");
        let taken = dir.join("taken.bwx");
        let mut container = Container::create(&root, WallTime::EPOCH).expect("the container");
        Container::create(&taken, WallTime::EPOCH).expect("the container in the way");

        let refusal = container
            .rename(&taken)
            .expect_err("renaming over a container must be refused");
        assert_eq!(refusal.kind(), std::io::ErrorKind::AlreadyExists);
        assert_eq!(container.root(), root, "the store moved anyway");
        assert!(
            taken.join(MANIFEST).is_file(),
            "the container in the way is gone"
        );
    }

    /// The cleanup D20 asks for, and everything it refuses to do: only a
    /// container holding exactly what `create` laid down, with an empty log,
    /// is removed.
    #[test]
    fn only_a_container_with_nothing_in_it_is_discarded() {
        let dir = fixture::dir("container-discard");

        let empty = dir.join("empty.bwx");
        drop(Container::create(&empty, WallTime::EPOCH).expect("the empty container"));
        assert_eq!(
            discard_pristine(&empty).expect("the sweep answers"),
            Discarded::Removed,
        );
        assert!(!empty.exists(), "a pristine container was left behind");

        let written = dir.join("written.bwx");
        let mut container = Container::create(&written, WallTime::EPOCH).expect("the container");
        let row = fixture::rows(1).pop().expect("one row");
        container.append(&row).expect("the row lands");
        drop(container);
        assert_eq!(
            discard_pristine(&written).expect("the sweep answers"),
            Discarded::Kept,
            "a container with a row in it was removed",
        );
        assert!(written.join(MANIFEST).is_file());

        let theirs = dir.join("theirs.bwx");
        drop(Container::create(&theirs, WallTime::EPOCH).expect("the container"));
        std::fs::write(theirs.join("notes.txt"), b"mine").expect("a file of the user's own");
        assert_eq!(
            discard_pristine(&theirs).expect("the sweep answers"),
            Discarded::Kept,
            "a directory holding something we did not write was removed",
        );
        assert!(theirs.join(MANIFEST).is_file(), "and it was half-removed");
    }

    #[test]
    fn a_read_only_handle_refuses_to_write() {
        let dir = fixture::dir("container-read-only");
        let root = dir.join("doc.bwx");
        let _held = Container::create(&root, WallTime::EPOCH).expect("the container");
        let mut second = Container::open(&root, WallTime::EPOCH).expect("a second handle");

        let row = fixture::rows(1).pop().expect("one row");
        assert!(matches!(second.append(&row), Err(WriteRefusal::ReadOnly)));
        assert!(matches!(
            second.truncate_manifest(0),
            Err(WriteRefusal::ReadOnly)
        ));
    }
}