blockworx/storage/

container.rs

//! A document container: the directory a drawing and its history live in.
//!
//! Opening is deliberately **tolerant**. A container is meant to be something a
//! person can make by hand — create a directory, drop a `.kdl` in as `root.kdl`
//! — so a directory missing `assets/`, missing `history/`, or missing `root.kdl`
//! altogether is opened rather than rejected. The missing parts are materialized
//! when something is first written to them.

use super::{Durability, Storage};
use crate::document::Document;
use crate::document::schema_convert::{asset_from_bytes, asset_to_bytes, finish_load};
use crate::schema::model as schema;

/// The current document, at the container root.
pub const ROOT: &str = "root.kdl";

/// Where image payloads live, one file per asset, named by its id.
pub const ASSETS: &str = "assets";

fn asset_path(id: &str) -> String {
    format!("{ASSETS}/{id}")
}

pub struct Container<S: Storage> {
    storage: S,
    /// Names the container itself — the directory's own name. Used as the
    /// display name whenever the document carries no `name` of its own.
    fallback_name: String,
}

impl<S: Storage> Container<S> {
    pub fn new(storage: S, fallback_name: impl Into<String>) -> Self {
        Self {
            storage,
            fallback_name: fallback_name.into(),
        }
    }

    pub fn storage(&self) -> &S {
        &self.storage
    }

    /// The document at [`ROOT`], with the images its placements name read back
    /// out of [`ASSETS`]. An empty container opens blank; a malformed
    /// `root.kdl` is an error, since silently replacing a document we failed to
    /// *read* would be a way to lose the drawing.
    pub fn load(&self) -> miette::Result<Document> {
        if !self.storage.exists(ROOT) {
            return Ok(Document::default());
        }
        let bytes = self
            .storage
            .read(ROOT)
            .map_err(|e| miette::miette!("reading {ROOT}: {e}"))?;
        let src = String::from_utf8(bytes)
            .map_err(|e| miette::miette!("{ROOT} is not valid UTF-8: {e}"))?;
        let mut model = schema::Document::parse_kdl(&src, ROOT)?;

        // A container normally carries no `asset` nodes at all — the placement
        // already names the file. One that does (hand-written, or a loose
        // document dropped in) keeps its inline payload, which is why the
        // already-defined ids are skipped rather than overwritten.
        let inline: Vec<String> = model.assets.iter().map(|a| a.id.clone()).collect();
        let wanted: Vec<String> = model
            .referenced_assets()
            .into_iter()
            .filter(|id| !inline.iter().any(|had| had == id))
            .map(str::to_string)
            .collect();
        for id in wanted {
            let path = asset_path(&id);
            let bytes = self
                .storage
                .read(&path)
                .map_err(|e| miette::miette!("reading {path}: {e}"))?;
            model.assets.push(asset_from_bytes(&id, bytes)?);
        }
        finish_load(model)
    }

    /// Write the document, with its images as files in [`ASSETS`] rather than
    /// inline in `root.kdl`.
    ///
    /// Assets are **write-once**: the id is a hash of the content, so a file
    /// that is already there already holds the right bytes. Nothing is ever
    /// deleted, even when the document stops referencing it — the history may
    /// still point at it, and disk is cheaper than a lost image.
    pub fn save(&self, doc: &Document) -> miette::Result<()> {
        self.write_document(doc, None)
    }

    /// Write the document *and* record it as history entry `seq`.
    pub fn save_and_record(
        &self,
        doc: &Document,
        seq: u64,
        meta: &super::history::Entry,
    ) -> miette::Result<()> {
        self.write_document(doc, Some((seq, meta)))
    }

    /// Ordered so the one synced write lands last: by the time `root.kdl` names
    /// an asset or a history entry mentions it, that file is already there.
    fn write_document(
        &self,
        doc: &Document,
        record: Option<(u64, &super::history::Entry)>,
    ) -> miette::Result<()> {
        let mut model = schema::Document::from(doc);
        for asset in &model.assets {
            let path = asset_path(&asset.id);
            if !self.storage.exists(&path) {
                self.storage
                    // Synced, unlike a history entry: `root.kdl` is synced and
                    // *references* this file, so losing the write would leave a
                    // document that cannot load. Only a new image pays for it.
                    .write(&path, &asset_to_bytes(asset)?, Durability::Sync)
                    .map_err(|e| miette::miette!("writing {path}: {e}"))?;
            }
        }
        model.assets.clear();
        let root = model.to_kdl();
        if let Some((seq, meta)) = record {
            super::history::append(&self.storage, seq, meta, &root)
                .map_err(|e| miette::miette!("recording history entry {seq}: {e}"))?;
        }
        self.storage
            .write(ROOT, root.as_bytes(), Durability::Sync)
            .map_err(|e| miette::miette!("writing {ROOT}: {e}"))
    }

    /// What to call this document: its own `name` when it has one, else the
    /// container directory's name.
    pub fn display_name<'a>(&'a self, doc: &'a Document) -> &'a str {
        doc.name.as_deref().unwrap_or(&self.fallback_name)
    }
}

#[cfg(not(target_arch = "wasm32"))]
impl Container<super::fs::FsStorage> {
    /// Open the container rooted at `dir`. Nothing is required to exist — not
    /// `assets/`, not `history/`, not `root.kdl`, not `dir` itself. Opening
    /// creates nothing either; the directory is materialized by the first write,
    /// so a mistyped path does not leave an empty container behind.
    pub fn open(dir: &std::path::Path) -> Self {
        let name = dir
            .file_name()
            .map_or_else(|| dir.display().to_string(), |n| n.to_string_lossy().into());
        Self::new(super::fs::FsStorage::new(dir), name)
    }
}

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

    fn container(name: &str) -> (TempDir, Container<FsStorage>) {
        let dir = TempDir::new(name);
        let c = Container::new(FsStorage::new(dir.path()), "the-drawing");
        (dir, c)
    }

    #[test]
    fn a_document_round_trips_through_the_container() {
        let (_dir, c) = container("container-roundtrip");
        let doc = Document {
            name: Some("CT Scanner".to_string()),
            ..Document::default()
        };
        c.save(&doc).unwrap();
        assert_eq!(c.load().unwrap(), doc);
    }

    /// The hand-made container: a bare directory holding nothing at all opens as
    /// an empty document rather than failing.
    #[test]
    fn an_empty_directory_opens_empty() {
        let (dir, c) = container("container-bare");
        assert!(!c.storage().exists(ROOT));
        assert_eq!(c.load().unwrap(), Document::default());
        // Nothing was created just by opening and reading.
        assert!(std::fs::read_dir(dir.path()).unwrap().next().is_none());
    }

    /// The other hand-made case: a directory holding only a `root.kdl` someone
    /// dropped in, with no `assets/` or `history/` beside it.
    #[test]
    fn a_directory_holding_only_a_root_kdl_opens() {
        let (dir, c) = container("container-root-only");
        std::fs::write(
            dir.path().join(ROOT),
            "top \"b0\"\nblock \"b0\" x=0 y=0 w=8 h=8",
        )
        .unwrap();
        let doc = c.load().unwrap();
        assert_eq!(doc.blocks.len(), 1);
        assert!(doc.name.is_none());
        assert!(!c.storage().exists("assets"));
        assert!(!c.storage().exists("history"));
    }

    /// A document we could not read is an error, never a silently empty one —
    /// saving over that would be a way to lose the drawing.
    #[test]
    fn a_malformed_root_is_an_error_not_an_empty_document() {
        let (dir, c) = container("container-malformed");
        std::fs::write(dir.path().join(ROOT), "top \"b0\" {").unwrap();
        assert!(c.load().is_err());
    }

    #[test]
    fn the_directory_name_is_the_fallback_display_name() {
        let (_dir, c) = container("container-name");
        let mut doc = Document::default();
        assert_eq!(c.display_name(&doc), "the-drawing");
        doc.name = Some("CT Scanner".to_string());
        assert_eq!(c.display_name(&doc), "CT Scanner");
    }

    /// Opening is read-only: a container that is not there yet reads as empty
    /// without being created, so a mistyped path leaves nothing behind. The
    /// directory appears when something is written to it.
    #[test]
    fn open_creates_nothing_until_a_write() {
        let dir = TempDir::new("container-open");
        let root = dir.join("ct-scanner.bwx");
        let c = Container::open(&root);
        assert!(!root.exists());
        assert_eq!(c.load().unwrap(), Document::default());
        assert!(!root.exists());
        assert_eq!(c.display_name(&Document::default()), "ct-scanner.bwx");

        c.save(&Document::default()).unwrap();
        assert!(root.join(ROOT).is_file());
    }

    fn with_image(marker: &str) -> Document {
        use crate::document::{Image, ImageData};
        use crate::store::IdMapExt as _;
        let mut doc = Document::default();
        let top = doc.top_id;
        let block = doc.blocks.get_mut(&top).expect("the top block");
        block.images.insert_value(Image::new(
            ImageData::Svg(format!("<svg viewBox=\"0 0 1 1\"><!--{marker}--></svg>")),
            egui::Rect::ZERO,
        ));
        doc
    }

    /// The split: payloads live in `assets/`, and `root.kdl` names them without
    /// carrying them.
    #[test]
    fn images_are_files_beside_the_document_not_inside_it() {
        let (dir, c) = container("container-assets");
        let doc = with_image("split");
        c.save(&doc).unwrap();

        let root = std::fs::read_to_string(dir.path().join(ROOT)).unwrap();
        assert!(!root.contains("asset \""), "payload inlined:\n{root}");
        assert!(!root.contains("<svg"), "payload inlined:\n{root}");

        let assets: Vec<_> = std::fs::read_dir(dir.path().join(ASSETS))
            .unwrap()
            .map(|e| e.unwrap().file_name().to_string_lossy().into_owned())
            .collect();
        assert_eq!(assets.len(), 1, "{assets:?}");
        assert_eq!(assets[0].rsplit_once('.').map(|(_, e)| e), Some("svg"));
        // The placement names exactly that file.
        assert!(root.contains(&format!("image \"{}\"", assets[0])), "{root}");

        assert_eq!(c.load().unwrap(), doc, "the image comes back");
    }

    /// The reason assets are never deleted: a snapshot in `history/` may still
    /// name one the current document has dropped.
    #[test]
    fn an_asset_the_document_stops_using_stays_on_disk() {
        let (dir, c) = container("container-asset-kept");
        c.save(&with_image("orphaned")).unwrap();
        let orphan = std::fs::read_dir(dir.path().join(ASSETS))
            .unwrap()
            .next()
            .unwrap()
            .unwrap()
            .path();
        assert!(orphan.is_file());

        // Save a document that references nothing.
        c.save(&Document::default()).unwrap();
        assert!(
            orphan.is_file(),
            "an unreferenced asset was deleted; history may still point at it"
        );
    }

    /// Write-once: the id is a hash, so a file already there already holds the
    /// right bytes and re-saving must not rewrite it.
    #[test]
    fn re_saving_does_not_rewrite_an_existing_asset() {
        let (dir, c) = container("container-asset-write-once");
        let doc = with_image("write-once");
        c.save(&doc).unwrap();
        let asset = std::fs::read_dir(dir.path().join(ASSETS))
            .unwrap()
            .next()
            .unwrap()
            .unwrap()
            .path();
        let first = std::fs::metadata(&asset).unwrap().modified().unwrap();

        // Sentinel content proves the second save left the file alone; a
        // rewrite would restore the real payload.
        std::fs::write(&asset, b"untouched").unwrap();
        c.save(&doc).unwrap();
        assert_eq!(std::fs::read(&asset).unwrap(), b"untouched");
        let _ = first;
    }

    /// A container missing a payload its document names is an error, not a
    /// document that silently loses an image.
    #[test]
    fn a_missing_asset_file_is_an_error() {
        let (dir, c) = container("container-asset-missing");
        c.save(&with_image("vanishing")).unwrap();
        let asset = std::fs::read_dir(dir.path().join(ASSETS))
            .unwrap()
            .next()
            .unwrap()
            .unwrap()
            .path();
        std::fs::remove_file(&asset).unwrap();
        assert!(c.load().is_err());
    }

    /// A hand-written container may still inline a payload; the inline one wins
    /// and no file is looked for.
    #[test]
    fn an_inline_asset_is_honoured_without_a_file() {
        let (dir, c) = container("container-asset-inline");
        std::fs::write(
            dir.path().join(ROOT),
            "top \"b0\"\n\
             block \"b0\" x=0 y=0 w=8 h=8 {\n\
             \x20   image \"logo.svg\" x=0 y=0 w=4 h=4\n\
             }\n\
             asset \"logo.svg\" {\n    svg r#\"<svg/>\"#\n}",
        )
        .unwrap();
        assert!(!c.storage().exists(ASSETS));
        let doc = c.load().expect("an inline payload needs no file");
        assert_eq!(doc.blocks[&doc.top_id].images.len(), 1);
    }
}