blockworx_store/

bundle.rs

//! The share bundle: a container as one file.
//!
//! The user: *"I suspect that the application should allow for opening a .zip
//! file of a .bwx, since that is something that can be sent via e-mail or
//! dropped on a thumb drive. Directories don't cross OS boundaries all that
//! well."*
//!
//! A container is a directory and stays one — a commit is an append and an
//! fsync, and the single-writer claim is a file another process can see,
//! neither of which a zip has anywhere to put. So the bundle is the
//! *transfer* form and only that: [`pack`] writes one, [`unpack`] lays it back
//! out as a directory, and opening a bundle is always unpack-then-open. There
//! is no working-in-place path here to keep in step with the directory one.
//!
//! What goes in is the container's own bytes, verbatim and in sorted order:
//! the rev files — which *are* the diagram, so re-serializing would be
//! the projection beside it, the rev files, the assets, and the git template. The names given
//! rewriting them. Names given to revs are `tag` rows in the manifest
//! rather than a sidecar, so they travel without being asked to. The lock
//! does not travel: it is one machine's
//! claim on one directory, and a copy of it is a claim about nothing.
//!
//! Whole history, always. The ledger's without-history variant would have to
//! decide which rev the bundle is cut at and re-stamp the projection, which is
//! Save-as's question ([`super::prefix`]) rather than this module's; it is
//! deferred until somebody asks for it.

use std::ffi::OsStr;
use std::io::{Read, Seek, Write as _};
use std::path::{Path, PathBuf};

use zip::write::SimpleFileOptions;
use zip::{CompressionMethod, DateTime, ZipArchive, ZipWriter};

use super::container::{ASSETS, LOCK, MANIFEST};
use super::revs::REVS;

/// Why a bundle could not be written or read back.
#[derive(Debug, thiserror::Error)]
pub enum BundleFailure {
    #[error("{0} is not a diagram to share")]
    NotADiagram(PathBuf),
    #[error("a diagram at {0} has no name to share it under")]
    Nameless(PathBuf),
    #[error("it is not a zip file: {0}")]
    NotAZip(zip::result::ZipError),
    #[error("it holds no diagram \u{2014} a shared diagram is a zip of a .bwx folder")]
    NoDiagram,
    #[error("it holds {0} diagrams, and a shared one is a single diagram")]
    ManyDiagrams(usize),
    #[error("it would write {0} outside the diagram")]
    Escapes(String),
    #[error("{0} already holds a diagram")]
    Occupied(PathBuf),
    #[error("{0}")]
    Read(std::io::Error),
    #[error("{0}")]
    Write(std::io::Error),
}

/// Write the container at `root` into a bundle at `to`.
///
/// The archive holds one top-level directory, named as the container is, so
/// unpacking it with any tool on any platform yields the `.bwx` folder rather
/// than its contents loose in whatever directory the user was standing in.
///
/// # Errors
/// [`BundleFailure`]: `root` is no container, its files could not be read, or
/// the archive could not be written.
pub fn pack(root: &Path, to: &Path) -> Result<(), BundleFailure> {
    if !root.join(MANIFEST).is_file() {
        return Err(BundleFailure::NotADiagram(root.to_path_buf()));
    }
    let held = root
        .file_name()
        .and_then(OsStr::to_str)
        .ok_or_else(|| BundleFailure::Nameless(root.to_path_buf()))?;
    let mut archive = ZipWriter::new(std::io::Cursor::new(Vec::new()));
    for at in contents(root).map_err(BundleFailure::Read)? {
        let bytes = std::fs::read(root.join(&at)).map_err(BundleFailure::Read)?;
        archive
            .start_file(entry_name(held, &at), stamped())
            .map_err(BundleFailure::NotAZip)?;
        archive.write_all(&bytes).map_err(BundleFailure::Write)?;
    }
    let bytes = archive
        .finish()
        .map_err(BundleFailure::NotAZip)?
        .into_inner();
    crate::atomic::write_atomically(to, &bytes).map_err(BundleFailure::Write)
}

/// Lay the bundle at `from` out as a container at `to`, which must not exist.
///
/// A failure part-way leaves nothing behind: half a container is worse than no
/// container, since the half would still look openable.
///
/// # Errors
/// [`BundleFailure`]: `to` is taken, `from` is not a zip, it holds no diagram
/// or more than one, an entry names a path outside the diagram, or the files
/// could not be written.
pub fn unpack(from: &Path, to: &Path) -> Result<(), BundleFailure> {
    if to.exists() {
        return Err(BundleFailure::Occupied(to.to_path_buf()));
    }
    let file = std::fs::File::open(from).map_err(BundleFailure::Read)?;
    let mut archive =
        ZipArchive::new(std::io::BufReader::new(file)).map_err(BundleFailure::NotAZip)?;
    let held = diagram_in(&archive)?;
    lay_out(&mut archive, &held, to).inspect_err(|_| {
        let _ = std::fs::remove_dir_all(to);
    })
}

/// Every file under `root`, relative to it and sorted, so the same container
/// packs to comparable archives. The lock is left out.
fn contents(root: &Path) -> std::io::Result<Vec<PathBuf>> {
    let mut found = Vec::new();
    let mut walk = vec![PathBuf::new()];
    while let Some(at) = walk.pop() {
        for entry in std::fs::read_dir(root.join(&at))? {
            let entry = entry?;
            let here = at.join(entry.file_name());
            if entry.file_type()?.is_dir() {
                walk.push(here);
            } else if here != Path::new(LOCK) {
                found.push(here);
            }
        }
    }
    found.sort();
    Ok(found)
}

/// A zip entry always spells its separator `/`, whatever this platform spells
/// a path with.
fn entry_name(held: &str, at: &Path) -> String {
    let mut name = held.to_owned();
    for part in at.components() {
        name.push('/');
        name.push_str(&part.as_os_str().to_string_lossy());
    }
    name
}

/// One timestamp for every entry, so two packs of the same container differ
/// in no byte. The archive says nothing about when it was made; the manifest
/// already says when everything in it happened.
fn stamped() -> SimpleFileOptions {
    SimpleFileOptions::default()
        .compression_method(CompressionMethod::Deflated)
        .last_modified_time(DateTime::default())
}

/// Which directory inside the archive is the diagram — the one holding a
/// manifest, since that is what makes a directory one. Refusing two of them is the
/// point: an archive of a folder of diagrams is not a shared diagram, and
/// picking one of them for the user would be picking for them.
fn diagram_in<R: Read + Seek>(archive: &ZipArchive<R>) -> Result<PathBuf, BundleFailure> {
    let mut roots: Vec<PathBuf> = archive
        .file_names()
        .filter_map(|name| {
            let path = Path::new(name);
            (path.file_name() == Some(OsStr::new(MANIFEST)))
                .then(|| path.parent().unwrap_or(Path::new("")).to_path_buf())
        })
        .collect();
    roots.sort();
    roots.dedup();
    match roots.len() {
        0 => Err(BundleFailure::NoDiagram),
        1 => Ok(roots.swap_remove(0)),
        many => Err(BundleFailure::ManyDiagrams(many)),
    }
}

/// Write the entries under `held` into `to`. Anything the archiver put beside
/// the diagram — a `__MACOSX` sidecar, a readme somebody zipped along — is
/// left in the archive rather than dropped into the container, where a file
/// nothing wrote would keep it from ever being discarded as pristine.
fn lay_out<R: Read + Seek>(
    archive: &mut ZipArchive<R>,
    held: &Path,
    to: &Path,
) -> Result<(), BundleFailure> {
    std::fs::create_dir_all(to.join(ASSETS)).map_err(BundleFailure::Write)?;
    std::fs::create_dir_all(to.join(REVS)).map_err(BundleFailure::Write)?;
    for nth in 0..archive.len() {
        let mut entry = archive.by_index(nth).map_err(BundleFailure::NotAZip)?;
        // `enclosed_name` is the crate's own zip-slip guard: `None` for an
        // absolute path, a `..` component, or a drive letter.
        let Some(inside) = entry.enclosed_name() else {
            return Err(BundleFailure::Escapes(entry.name().to_owned()));
        };
        let Ok(at) = inside.strip_prefix(held) else {
            continue;
        };
        if entry.is_dir() || at.as_os_str().is_empty() || at == Path::new(LOCK) {
            continue;
        }
        let target = to.join(at);
        if let Some(dir) = target.parent() {
            std::fs::create_dir_all(dir).map_err(BundleFailure::Write)?;
        }
        let mut file = std::fs::File::create(&target).map_err(BundleFailure::Write)?;
        std::io::copy(&mut entry, &mut file).map_err(BundleFailure::Write)?;
    }
    Ok(())
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::container::{GITATTRIBUTES, PROJECTION};
    use crate::fixture;
    use crate::handle::Store;
    use crate::record::Identity;
    use blockworx_doc::fixtures::rev;

    /// A container with three edits, a named rev and a piece of artwork —
    /// everything a bundle has to carry.
    fn source(root: &Path) -> Vec<u8> {
        let mut store = Store::create(root, fixture::clock()).expect("the container");
        let author = Identity::new("ada");
        for commit in fixture::edits(2) {
            store.submit_edit(commit, &author).expect("the edit lands");
        }
        let asset = fixture::svg(1);
        store
            .submit_edit(
                fixture::commit("Added an icon", fixture::icon(1, &asset)),
                &author,
            )
            .expect("the icon lands");
        store
            .tag(
                rev(2),
                "worth keeping",
                crate::tags::Tagging::Added,
                &author,
            )
            .expect("the tag");
        store.save_projection().expect("the projection");
        drop(store);
        asset.bytes().to_vec()
    }

    /// The round trip the whole feature is: a container shared to one file,
    /// opened somewhere else, is the same diagram — the same manifest
    /// *bytes*, with its revs, its names and its artwork, and it
    /// verifies rather than opening read-only over a broken chain.
    #[test]
    fn a_shared_diagram_opens_elsewhere_as_the_diagram_it_was() {
        let dir = fixture::dir("bundle-round-trip");
        let from = dir.join("engine.bwx");
        let artwork = source(&from);
        let bundle = dir.join("engine.bwx.zip");
        pack(&from, &bundle).expect("the bundle is written");

        let to = dir.join("elsewhere").join("engine.bwx");
        unpack(&bundle, &to).expect("the bundle unpacks");

        assert_eq!(
            std::fs::read(from.join(MANIFEST)).expect("the source manifest"),
            std::fs::read(to.join(MANIFEST)).expect("the unpacked manifest"),
            "the unpacked manifest is not the bytes that were shared",
        );
        // Before it is opened: opening a container backfills the revs it
        // is missing, which would hide a bundle that carried none.
        for at in crate::revs::through(rev(3)) {
            assert_eq!(
                std::fs::read(crate::revs::path(&from, at)).expect("the shared rev"),
                std::fs::read(crate::revs::path(&to, at)).expect("the unpacked rev"),
                "rev {} did not come over in the bundle",
                at.get(),
            );
        }
        let opened = Store::open(&to, fixture::clock()).expect("the unpacked container opens");
        assert!(
            opened.read_only_reason().is_none(),
            "the unpacked diagram did not verify: {:?}",
            opened.read_only_reason(),
        );
        assert_eq!(opened.repo().rev(), rev(3), "the head did not come over");
        assert_eq!(
            opened.tags().of(rev(2)),
            ["worth keeping"],
            "a rev's name did not come over",
        );
        assert_eq!(
            opened.projection(),
            crate::projection::Freshness::Fresh,
            "the projection beside the unpacked revs does not stamp its own head",
        );
        let carried: Vec<Vec<u8>> = std::fs::read_dir(to.join(ASSETS))
            .expect("the unpacked assets")
            .map(|entry| std::fs::read(entry.expect("an entry").path()).expect("the payload"))
            .collect();
        assert_eq!(carried, vec![artwork], "the artwork did not come over");
    }

    /// The lock is one machine's claim on one directory. Packed into an
    /// archive it would arrive as a claim by a process that is not running,
    /// and the diagram would open read-only on the far side.
    #[test]
    fn the_bundle_carries_no_lock() {
        let dir = fixture::dir("bundle-no-lock");
        let from = dir.join("engine.bwx");
        // Held open, so the lock is on disk while the bundle is written —
        // which is the case that matters: Share is pressed from inside the
        // session that holds it.
        let mut store = Store::create(&from, fixture::clock()).expect("the container");
        store
            .submit_edit(fixture::edits(1)[0].clone(), &Identity::new("ada"))
            .expect("the edit lands");
        assert!(
            from.join(LOCK).is_file(),
            "precondition: the open session holds the lock",
        );

        let bundle = dir.join("engine.bwx.zip");
        pack(&from, &bundle).expect("the bundle is written");
        let names = names_in(&bundle);
        assert!(
            !names.iter().any(|name| name.ends_with(LOCK)),
            "the bundle carries a lock: {names:?}",
        );
        assert_eq!(
            names,
            vec![
                format!("engine.bwx/{GITATTRIBUTES}"),
                format!("engine.bwx/{MANIFEST}"),
                format!("engine.bwx/{REVS}/000001.json.zst"),
            ],
            "the bundle is not the container's own files under its own name",
        );

        drop(store);
        let to = dir.join("unpacked.bwx");
        unpack(&bundle, &to).expect("the bundle unpacks");
        assert!(
            !to.join(LOCK).exists(),
            "the unpacked diagram arrived locked"
        );
    }

    /// Sorted paths, one timestamp: the same container shared twice is the
    /// same archive, so two bundles can be compared byte for byte.
    #[test]
    fn the_same_diagram_shares_to_the_same_bytes() {
        let dir = fixture::dir("bundle-deterministic");
        let from = dir.join("engine.bwx");
        source(&from);
        let (once, twice) = (dir.join("once.zip"), dir.join("twice.zip"));
        pack(&from, &once).expect("the first bundle");
        pack(&from, &twice).expect("the second bundle");
        assert_eq!(
            std::fs::read(&once).expect("the first"),
            std::fs::read(&twice).expect("the second"),
            "two shares of one diagram are not the same archive",
        );
        assert!(
            names_in(&once).windows(2).all(|pair| pair[0] < pair[1]),
            "the entries are not in sorted order: {:?}",
            names_in(&once),
        );
    }

    /// A zip that is not a shared diagram is refused, and the refusal says
    /// which of the things that can be wrong with it was.
    #[test]
    fn a_zip_with_no_diagram_in_it_is_refused_by_name() {
        let dir = fixture::dir("bundle-not-a-diagram");
        let bundle = dir.join("holiday.zip");
        write_zip(&bundle, &[("photos/beach.jpg", b"not a diagram")]);
        let refusal =
            unpack(&bundle, &dir.join("out.bwx")).expect_err("a zip of photos is refused");
        assert!(
            matches!(refusal, BundleFailure::NoDiagram),
            "the wrong refusal: {refusal}",
        );
        assert!(
            refusal.to_string().contains(".bwx"),
            "the refusal does not say what a shared diagram is: {refusal}",
        );
        assert!(
            !dir.join("out.bwx").exists(),
            "a refused unpack left a container behind",
        );

        let two = dir.join("both.zip");
        write_zip(
            &two,
            &[
                ("one.bwx/manifest.jsonl", b""),
                ("two.bwx/manifest.jsonl", b""),
            ],
        );
        assert!(
            matches!(
                unpack(&two, &dir.join("out.bwx")),
                Err(BundleFailure::ManyDiagrams(2)),
            ),
            "a zip of two diagrams was taken for one",
        );

        let corrupt = dir.join("corrupt.zip");
        std::fs::write(&corrupt, b"PK\x03\x04 and then nothing").expect("the corrupt file");
        assert!(matches!(
            unpack(&corrupt, &dir.join("out.bwx")),
            Err(BundleFailure::NotAZip(_)),
        ));
    }

    /// An entry naming a path outside the diagram is refused rather than
    /// skipped: an archive reaching for the filesystem around it is not a
    /// bundle we finish reading.
    #[test]
    fn an_entry_reaching_outside_the_diagram_is_refused() {
        let dir = fixture::dir("bundle-escape");
        let bundle = dir.join("nasty.zip");
        write_zip(
            &bundle,
            &[
                ("engine.bwx/manifest.jsonl", b""),
                ("engine.bwx/../../taken.txt", b"gotcha"),
            ],
        );
        let out = dir.join("out.bwx");
        assert!(matches!(
            unpack(&bundle, &out),
            Err(BundleFailure::Escapes(_)),
        ));
        assert!(!out.exists(), "a refused unpack left a container behind");
        assert!(
            !dir.path().join("taken.txt").exists(),
            "the archive wrote outside the diagram",
        );
    }

    /// Nothing is ever overwritten to make room for an unpack. The chrome
    /// asks the user where instead ([`crate::file::unpacks_to`]); this is the
    /// same refusal at the seam under it.
    #[test]
    fn unpacking_onto_something_that_exists_is_refused() {
        let dir = fixture::dir("bundle-occupied");
        let from = dir.join("engine.bwx");
        source(&from);
        let bundle = dir.join("engine.bwx.zip");
        pack(&from, &bundle).expect("the bundle");

        let standing = std::fs::read(from.join(MANIFEST)).expect("the manifest that is in the way");
        let refusal = unpack(&bundle, &from).expect_err("unpacking over a diagram is refused");
        assert!(matches!(refusal, BundleFailure::Occupied(_)));
        assert_eq!(
            std::fs::read(from.join(MANIFEST)).expect("the manifest that was in the way"),
            standing,
            "the diagram in the way was written over",
        );
        assert!(
            from.join(PROJECTION).is_file(),
            "the diagram in the way lost a file",
        );
    }

    #[test]
    fn a_directory_that_is_not_a_diagram_is_not_shareable() {
        let dir = fixture::dir("bundle-source");
        let plain = dir.join("just-a-folder");
        std::fs::create_dir_all(&plain).expect("the directory");
        assert!(matches!(
            pack(&plain, &dir.join("out.zip")),
            Err(BundleFailure::NotADiagram(_)),
        ));
    }

    fn names_in(bundle: &Path) -> Vec<String> {
        let file = std::fs::File::open(bundle).expect("the bundle");
        let archive = ZipArchive::new(std::io::BufReader::new(file)).expect("a zip");
        archive.file_names().map(str::to_owned).collect()
    }

    /// A zip written by hand, so a test can put things in one that `pack`
    /// never would.
    fn write_zip(at: &Path, entries: &[(&str, &[u8])]) {
        let file = std::fs::File::create(at).expect("the file");
        let mut archive = ZipWriter::new(std::io::BufWriter::new(file));
        for (name, bytes) in entries {
            archive
                .start_file(*name, stamped())
                .expect("the entry starts");
            archive.write_all(bytes).expect("the entry is written");
        }
        archive.finish().expect("the archive closes");
    }
}