blockworx_store/

transfer.rs

//! A container as one file: the `.bwx.zip` a document travels in.
//!
//! A `.bwx` is a directory, which a host that has one hands over as it
//! stands. A browser has none to hand over, so a container leaves the
//! origin — and comes back into it — packed, and this is the one place that
//! packing is written. Over a [`Storage`], so the two ends are the same
//! bytes whether a desktop or a tab wrote them.
//!
//! The lock does not travel: it says who is writing a container *here*, and
//! a copy someone else is opening is not that container. Everything else in
//! the layout does, which is what makes an unpacked archive a container the
//! ordinary open verifies rather than a shape that only looks like one.

use std::io::{Cursor, Read as _, Write as _};

use crate::container::{ASSETS, LOCK, MANIFEST};
use crate::revs::REVS;
use crate::storage::{Entry, Storage};

/// The directories a container files entries in, which is the whole of its
/// nesting: `pack` walks these and nothing deeper.
const WITHIN: [&str; 2] = [REVS, ASSETS];

/// Everything in `storage` as a zip, entry names being the container's own.
///
/// # Errors
/// The read that did not work, or a zip that would not be written.
pub async fn pack<S: Storage>(storage: &S) -> std::io::Result<Vec<u8>> {
    let mut archive = zip::ZipWriter::new(Cursor::new(Vec::new()));
    // Stored, not deflated: a rev is already gzip and a payload is already
    // PNG, so the second pass costs the tab a second compression of the
    // same bytes and saves the transfer almost nothing.
    let how =
        zip::write::SimpleFileOptions::default().compression_method(zip::CompressionMethod::Stored);
    for at in entries(storage).await? {
        let Some(bytes) = storage.read(&at).await? else {
            continue;
        };
        archive.start_file(at.as_str(), how).map_err(refused)?;
        archive.write_all(&bytes)?;
    }
    Ok(archive.finish().map_err(refused)?.into_inner())
}

/// Lay the container `archive` holds down in `storage`.
///
/// # Errors
/// [`std::io::ErrorKind::InvalidData`] for an archive that is not a
/// container — one holding no manifest, or naming an entry outside the
/// layout — and the write that did not land.
pub async fn unpack<S: Storage>(storage: &S, archive: &[u8]) -> std::io::Result<()> {
    let mut read = zip::ZipArchive::new(Cursor::new(archive)).map_err(refused)?;
    let mut held: Vec<(Entry, Vec<u8>)> = Vec::new();
    for at in 0..read.len() {
        let mut file = read.by_index(at).map_err(refused)?;
        if file.is_dir() {
            continue;
        }
        let Some(at) = named(file.name()) else {
            return Err(std::io::Error::new(
                std::io::ErrorKind::InvalidData,
                format!("{} is not part of a diagram", file.name()),
            ));
        };
        let mut bytes = Vec::with_capacity(file.size() as usize);
        file.read_to_end(&mut bytes)?;
        held.push((at, bytes));
    }
    if !held.iter().any(|(at, _)| *at == MANIFEST) {
        return Err(std::io::Error::new(
            std::io::ErrorKind::InvalidData,
            format!("this archive holds no {MANIFEST}, so it holds no diagram"),
        ));
    }
    for dir in WITHIN {
        storage.create_dir(&Entry::fixed(dir)).await?;
    }
    for (at, bytes) in held {
        storage.write(&at, &bytes).await?;
    }
    Ok(())
}

/// The entry `name` spells, or `None` for a name no container ever wrote:
/// one that climbs out of the container, or sits under a directory the
/// layout does not have.
fn named(name: &str) -> Option<Entry> {
    let mut path = name.split('/');
    match (path.next()?, path.next(), path.next()) {
        (first, None, _) if first == LOCK.as_str() || !is_a_name(first) => None,
        (first, None, _) => Some(Entry::named(first)),
        (dir, Some(entry), None) if WITHIN.contains(&dir) && is_a_name(entry) => {
            Some(Entry::under(dir, entry))
        }
        _ => None,
    }
}

fn is_a_name(entry: &str) -> bool {
    !entry.is_empty() && entry != "." && entry != ".."
}

/// What a container holds, in the order it was laid out: the files beside
/// the manifest, then what each directory of it holds.
async fn entries<S: Storage>(storage: &S) -> std::io::Result<Vec<Entry>> {
    let mut found = Vec::new();
    for name in storage.list(&Entry::ROOT).await? {
        if WITHIN.contains(&name.as_str()) || name == LOCK.as_str() {
            continue;
        }
        found.push(Entry::named(&name));
    }
    found.sort();
    for dir in WITHIN {
        let mut within = storage.list(&Entry::fixed(dir)).await.unwrap_or_default();
        within.sort();
        found.extend(within.iter().map(|name| Entry::under(dir, name)));
    }
    Ok(found)
}

fn refused(why: zip::result::ZipError) -> std::io::Error {
    match why {
        zip::result::ZipError::Io(error) => error,
        other => std::io::Error::new(std::io::ErrorKind::InvalidData, other.to_string()),
    }
}

/// The document an archive holds.
///
/// Laid down in memory and opened exactly as the library opens one, so what
/// an archive *reads* as and what it *opens* as cannot come apart. Reading
/// one file off the top would be cheaper, and was how this started: the
/// container used to carry a pretty-printed copy of its head beside the
/// revs. That copy was allowed to fall behind, so an archive packed between
/// an edit and the save after it read as a drawing missing its most recent
/// edits — and the file is gone now
/// (`docs/retire-projection-playbook.md`).
///
/// # Errors
/// [`std::io::ErrorKind::InvalidData`] for an archive that is not a
/// container, and for a container that will not open.
pub fn document_in(archive: &[u8]) -> std::io::Result<blockworx_doc::document::Document> {
    let storage = crate::storage::Memory::new("embedded.bwx");
    crate::storage::ready_now(unpack(&storage, archive))?;
    let store = crate::handle::Store::reading(crate::storage::Any::new(storage))
        .map_err(|why| std::io::Error::new(std::io::ErrorKind::InvalidData, why.to_string()))?;
    Ok(store.document().clone())
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::fixture::{self, block_on};
    use crate::handle::Store;
    use crate::storage::{Any, Memory, Name};

    /// A container with rows, revs and a payload in it — everything the
    /// layout has places for.
    fn packed() -> (Memory, Vec<u8>) {
        let bytes = Memory::new("carried.bwx");
        let mut store =
            Store::create(Any::new(bytes.clone()), fixture::clock()).expect("the container");
        let asset = fixture::svg(1);
        for commit in fixture::edits(2) {
            store
                .submit_edit(commit, &fixture::author())
                .expect("an edit");
        }
        store
            .submit_edit(
                fixture::commit("Added an icon", fixture::icon(1, &asset)),
                &fixture::author(),
            )
            .expect("the icon");
        assert!(
            block_on(bytes.exists(&LOCK)).expect("the read"),
            "precondition: what is packed is a container this session holds",
        );
        let archive = block_on(pack(&bytes)).expect("the archive");
        (bytes, archive)
    }

    /// Artwork lives once, in `assets/<hash>`, and everything else keeps
    /// only the hash — so reading a document out of an archive has to put
    /// the payloads back, not just find the references.
    #[test]
    fn the_document_an_archive_holds_comes_back_with_its_artwork_attached() {
        let (was, archive) = packed();
        let stood = Store::open(Any::new(was), fixture::clock()).expect("the original");
        assert!(
            stood.document().assets().next().is_some(),
            "precondition: the packed document holds a payload, so reading it back \
             proves the bytes travel and not only the hash",
        );

        let read = document_in(&archive).expect("the archive holds a diagram");
        assert_eq!(&read, stood.document());
        assert_eq!(read.assets().count(), stood.document().assets().count());
    }

    #[test]
    fn what_is_not_an_archive_at_all_is_refused_rather_than_read() {
        let refused = document_in(b"not a zip").expect_err("there is no archive here");
        assert_eq!(refused.kind(), std::io::ErrorKind::InvalidData);
    }

    /// An archive read is an archive opened: one path, so the two cannot
    /// come apart. They did while this read `document.json` — a view, which
    /// a container packed between an edit and the save after it carried
    /// behind its own head.
    #[test]
    fn what_an_archive_reads_as_is_what_it_opens_as() {
        let bytes = Memory::new("drifting.bwx");
        let mut store =
            Store::create(Any::new(bytes.clone()), fixture::clock()).expect("the container");
        for commit in fixture::edits(2) {
            store
                .submit_edit(commit, &fixture::author())
                .expect("the edit lands");
        }
        let archive = block_on(pack(&bytes)).expect("the archive");

        let read = document_in(&archive).expect("the archive holds a diagram");
        let laid = Memory::new("opened.bwx");
        block_on(unpack(&laid, &archive)).expect("the archive lays down");
        let opened = Store::open(Any::new(laid), fixture::clock()).expect("a container");

        assert_eq!(
            opened.document().rev().get(),
            2,
            "precondition: two edits stand"
        );
        assert_eq!(
            &read,
            opened.document(),
            "reading an archive and opening it must come to the same drawing",
        );
    }

    #[test]
    fn a_container_packed_and_unpacked_is_the_container_it_was() {
        let (was, archive) = packed();
        let now = Memory::new("arrived.bwx");
        block_on(unpack(&now, &archive)).expect("the archive lays down");

        let opened = Store::open(Any::new(now.clone()), fixture::clock()).expect("a container");
        let stood = Store::open(Any::new(was.clone()), fixture::clock()).expect("the original");
        assert_eq!(opened.rows().len(), stood.rows().len());
        assert_eq!(opened.document(), stood.document());
        assert!(
            opened.read_only_reason().is_none(),
            "an unpacked container is one this session may write",
        );
        assert_eq!(
            block_on(super::entries(&was)).expect("the entries"),
            block_on(super::entries(&now)).expect("the entries"),
            "the two containers hold the same entries",
        );
    }

    /// The lock is about who is writing a container here, so a copy of it
    /// arrives unheld.
    #[test]
    fn the_lock_does_not_travel() {
        let (_, archive) = packed();
        let now = Memory::new("arrived.bwx");
        block_on(unpack(&now, &archive)).expect("the archive lays down");
        assert!(!block_on(now.exists(&LOCK)).expect("the read"));
    }

    #[test]
    fn an_archive_that_is_not_a_container_is_refused() {
        let nothing = Memory::new("refused.bwx");
        let mut archive = zip::ZipWriter::new(Cursor::new(Vec::new()));
        archive
            .start_file("notes.txt", zip::write::SimpleFileOptions::default())
            .expect("a file");
        archive.write_all(b"hello").expect("the bytes");
        let archive = archive.finish().expect("the archive").into_inner();

        let refusal = block_on(unpack(&nothing, &archive)).expect_err("not a diagram");
        assert_eq!(refusal.kind(), std::io::ErrorKind::InvalidData);
    }

    /// A name that climbs out of the container is refused rather than
    /// written somewhere it was never meant to reach.
    #[test]
    fn an_entry_outside_the_layout_is_refused() {
        for climbing in [
            "../escaped",
            "..",
            "",
            "revs/../../escaped",
            "revs/..",
            "elsewhere/rev.json.gz",
        ] {
            assert_eq!(named(climbing), None, "{climbing} was taken for an entry");
        }
        assert_eq!(named(LOCK.as_str()), None, "the lock is not carried");
        assert_eq!(named(MANIFEST.as_str()), Some(MANIFEST));
        assert_eq!(
            named("revs/000001.json.gz"),
            Some(Entry::under(REVS, "000001.json.gz")),
        );
    }

    /// The whole point of the form: a container leaves one storage and
    /// opens in another under a name of its own.
    #[test]
    fn a_container_travels_between_two_storages_under_a_new_name() {
        let (_, archive) = packed();
        let arrived = Memory::new("renamed.bwx");
        block_on(unpack(&arrived, &archive)).expect("the archive lays down");
        let store = Store::open(Any::new(arrived), fixture::clock()).expect("a container");
        assert_eq!(store.name(), Name::of_document("renamed").expect("a name"));
    }
}