blockworx_store/

prefix.rs

//! Save-as over a container: a new one holding the source's manifest up
//! to a rev, line for line, and the rev files those rows name.
//!
//! The user, dropping Restore for this: *"a cleaner solution is to have a
//! way to save a log up to a given rev as a new document. This allows you to
//! time-machine back to an earlier rev and make clean edits on top of it."*
//!
//! The rows are copied **verbatim**. The hash chain is over the bytes a file
//! holds, so a save that re-serialized them would be a save that could
//! break the chain that verifies it; copying a *contiguous prefix* keeps
//! it whole by construction — every row still follows the one it named as
//! its parent — and carries every column a re-serialization would have to
//! invent: the wall times, the authors, the cameras, the edit/undo/redo
//! kinds, the tag rows, and any field a later build adds.
//!
//! What is left behind is everything after the cut, which is what the user
//! asked for: the revs past it, and the names given to them.
//!
//! Names given to revs *inside* the cut are kept whatever order they were
//! written in — a rev tagged from the head, long after it was made, still
//! arrives named. Those tag rows cannot be copied (their parent link names
//! a row that is not here), so they are written again, by whoever asked
//! for the save: a tag is a claim about history rather than part of it, so
//! re-stating one is honest where re-stating an edit would not be.

use std::collections::BTreeSet;

use blockworx_doc::{hash::AssetHash, rev::Rev};

use super::assets::AssetFormat;
use super::container::{Container, ContainerError, MANIFEST, asset_entry};
use super::handle::{Clock, Store};
use super::manifest::{Replays, Row};
use super::record::Identity;
use super::revs;
use super::storage::{Storage, ready_now};
use super::tags::{Tagging, Tags};

/// Why a document could not be saved as it stood at a rev.
#[derive(Debug, thiserror::Error)]
pub enum PrefixFailure {
    #[error("the manifest could not be read: {0}")]
    Read(std::io::Error),
    #[error("line {line} of the manifest is not a row this build can read: {why}")]
    NotARow { line: usize, why: serde_json::Error },
    #[error("this history has no rev {}", .0.get())]
    NoSuchRev(Rev),
    #[error(transparent)]
    Create(#[from] ContainerError),
    #[error("{name} could not be carried over: {why}")]
    Asset { name: String, why: std::io::Error },
    #[error("rev {}'s copy could not be carried over: {why}", .at.get())]
    Rev { at: Rev, why: std::io::Error },
    #[error("the new container's projection did not land: {0}")]
    Projection(super::Refusal),
    #[error("rev {}'s name did not come over: {why}", .at.get())]
    Tag { at: Rev, why: super::Refusal },
}

/// Write the document as it stood at `at` into a new container at `to`,
/// and open it.
///
/// The head of the new history is `at`, so the session that lands in it is
/// writable at the rev it was looking at — which is the whole point.
///
/// # Errors
/// [`PrefixFailure`]: the source manifest could not be read or does not
/// hold `at`, the container could not be laid out, revs or artwork the
/// prefix names could not be carried over, or the projection did not land.
pub fn save_through<S: Storage, T: Storage>(
    source: &S,
    at: Rev,
    to: T,
    mut clock: Clock,
    by: &Identity,
) -> Result<Store<T>, PrefixFailure> {
    let text = read_manifest(source)?;
    let prefix = through(&text, at)?;
    let container = Container::create_holding(to, clock.tick(), prefix.as_bytes())?;
    carry_revs(source, &container, at)?;
    carry_assets(source, &container, at)?;
    let mut store = Store::over(container, clock)?;
    rename_revs(&mut store, &named_through(&text, at)?, by)?;
    Ok(store)
}

/// Make the saved container call its revs what `wanted` calls them.
///
/// Two directions, because the copied rows can be wrong either way: a name
/// given after the cut is missing from them, and a name *taken off* after
/// the cut is still in them. Both are one appended tag row, which is what
/// a tag has always been.
fn rename_revs<T: Storage>(
    store: &mut Store<T>,
    wanted: &Tags,
    by: &Identity,
) -> Result<(), PrefixFailure> {
    let carried: Vec<(Rev, Vec<String>)> = store
        .tags()
        .iter()
        .map(|(rev, names)| (rev, names.to_vec()))
        .collect();
    let mut restated: Vec<(Rev, String, Tagging)> = Vec::new();
    for (rev, names) in &carried {
        for name in names {
            if !wanted.of(*rev).contains(name) {
                restated.push((*rev, name.clone(), Tagging::Removed));
            }
        }
    }
    for (rev, names) in wanted.iter() {
        for name in names {
            if !store.tags().of(rev).contains(name) {
                restated.push((rev, name.clone(), Tagging::Added));
            }
        }
    }
    for (rev, name, how) in restated {
        store
            .tag(rev, &name, how, by)
            .map_err(|why| PrefixFailure::Tag { at: rev, why })?;
    }
    Ok(())
}

/// What the whole manifest calls the revs at or before `at` — the names
/// the saved container owes, wherever in the file they were written. A
/// later row that *clears* a name is honoured like any other: the rev
/// arrives unnamed, because that is what the source says it is called.
fn named_through(text: &str, at: Rev) -> Result<Tags, PrefixFailure> {
    let mut tags = Tags::default();
    for (nth, line) in whole_lines(text) {
        let row = parse(nth, line)?;
        if row.rev <= at
            && let Replays::Vocabulary(how) = row.kind.replays()
        {
            tags.apply(row.rev, &row.label, how);
        }
    }
    Ok(tags)
}

/// The leading run of `text`'s lines that reaches no further than `at`.
///
/// A *contiguous* prefix, because that is what keeps the hash chain whole: a
/// line dropped from the middle would leave its successor naming a parent
/// that is no longer there. Which means the tags that survive are the ones
/// written before the cut — and a tag can only ever name a rev the history
/// already held, so every one of them names a rev at or before `at`. The
/// names given later to revs inside the cut are [`named_through`]'s to put
/// back.
fn through(text: &str, at: Rev) -> Result<&str, PrefixFailure> {
    let mut end = 0;
    let mut reached = Rev::ZERO;
    for (nth, line) in whole_lines(text) {
        let row = parse(nth, line)?;
        if row.kind.takes_a_rev() {
            if row.rev > at {
                break;
            }
            reached = row.rev;
        }
        end += line.len();
    }
    if reached != at {
        return Err(PrefixFailure::NoSuchRev(at));
    }
    Ok(&text[..end])
}

fn parse(nth: usize, line: &str) -> Result<Row, PrefixFailure> {
    serde_json::from_str(line.trim_end())
        .map_err(|why| PrefixFailure::NotARow { line: nth + 1, why })
}

/// The manifest's finished lines, numbered from one. A trailing line with
/// no newline is left out, exactly as a load drops it: it is a row a crash
/// caught half-written.
fn whole_lines(text: &str) -> impl Iterator<Item = (usize, &str)> {
    text.split_inclusive('\n')
        .take_while(|line| line.ends_with('\n'))
        .enumerate()
}

/// The source manifest, as text.
fn read_manifest<S: Storage>(source: &S) -> Result<String, PrefixFailure> {
    let bytes = ready_now(source.read(&MANIFEST))
        .map_err(PrefixFailure::Read)?
        .ok_or_else(|| PrefixFailure::Read(std::io::Error::from(std::io::ErrorKind::NotFound)))?;
    String::from_utf8(bytes).map_err(|why| {
        PrefixFailure::Read(std::io::Error::new(
            std::io::ErrorKind::InvalidData,
            why.to_string(),
        ))
    })
}

/// Copy the rev files at or below the cut, so the saved container arrives
/// with the history it inherited already written.
fn carry_revs<S: Storage, T: Storage>(
    from: &S,
    to: &Container<T>,
    at: Rev,
) -> Result<(), PrefixFailure> {
    for rev in revs::through(at) {
        let missing = || std::io::Error::from(std::io::ErrorKind::NotFound);
        let entry = revs::entry(rev);
        let carried = ready_now(from.read(&entry))
            .and_then(|bytes| bytes.ok_or_else(missing))
            .and_then(|bytes| to.write(&entry, &bytes));
        carried.map_err(|why| PrefixFailure::Rev { at: rev, why })?;
    }
    Ok(())
}

/// Copy the artwork the carried revs reference from one container's
/// `assets/` to another's. Content-addressed, so the file's name in the
/// new container is the name it had in the old one and nothing has to be
/// rewritten.
///
/// The revs are read back rather than the whole directory copied: what a
/// save-as owes is the payloads its own history points at, and a payload
/// nothing past the cut references is not part of what was asked for.
fn carry_assets<S: Storage, T: Storage>(
    from: &S,
    to: &Container<T>,
    at: Rev,
) -> Result<(), PrefixFailure> {
    let backing = to.revs();
    let mut wanted: BTreeSet<AssetHash> = BTreeSet::new();
    for rev in revs::through(at) {
        let Ok(document) = revs::read(&backing, rev) else {
            continue;
        };
        wanted.extend(document.referenced_assets());
    }
    for (hash, format) in wanted
        .into_iter()
        .flat_map(|hash| AssetFormat::ALL.map(move |format| (hash, format)))
    {
        let entry = asset_entry(hash, format);
        let carried = || -> std::io::Result<()> {
            if to.exists(&entry)? {
                return Ok(());
            }
            match ready_now(from.read(&entry))? {
                Some(bytes) => to.write(&entry, &bytes),
                None => Ok(()),
            }
        };
        carried().map_err(|why| PrefixFailure::Asset {
            name: format.file_name(hash),
            why,
        })?;
    }
    Ok(())
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::container::ASSETS;
    use crate::fixture;
    use crate::record::Identity;
    use crate::storage::Native;
    use blockworx_doc::fixtures::rev;
    use std::path::Path;

    /// A container of three edits with a tag on the first and another on
    /// the third, written by a pinned clock so the bytes are stable.
    fn source(root: &Path) -> Store<Native> {
        let mut store = Store::create(Native::at(root), fixture::clock()).expect("the container");
        let author = Identity::new("ada");
        for (n, commit) in fixture::edits(3).iter().enumerate() {
            store
                .submit_edit(commit.clone(), &author)
                .expect("the edit lands");
            if n == 0 {
                store
                    .tag(rev(1), "the start", Tagging::Added, &author)
                    .expect("the tag");
            }
        }
        store
            .tag(rev(3), "the end", Tagging::Added, &author)
            .expect("the tag");
        store
    }

    /// The load-bearing claim: the new log *is* the old log's first lines,
    /// byte for byte. Anything less and the chain, the wall times, the
    /// authors and the record kinds would all be this module's to reproduce.
    #[test]
    fn the_saved_log_is_the_sources_own_lines() {
        let dir = fixture::dir("prefix-bytes");
        let from = dir.join("source.bwx");
        drop(source(&from));
        let to = dir.join("through-2.bwx");

        let saved = save_through(
            &Native::at(&from),
            rev(2),
            Native::at(&to),
            fixture::clock(),
            &Identity::new("grace"),
        )
        .expect("the prefix saves");
        drop(saved);

        let whole =
            std::fs::read_to_string(from.join(MANIFEST.as_str())).expect("the source manifest");
        let prefix =
            std::fs::read_to_string(to.join(MANIFEST.as_str())).expect("the saved manifest");
        assert!(
            whole.starts_with(&prefix),
            "the saved log is not a prefix of the one it came from",
        );
        assert_eq!(
            prefix.lines().count(),
            3,
            "expected two edits and the tag between them, not {prefix}",
        );
        assert!(
            whole.len() > prefix.len(),
            "precondition: the source runs past rev 2",
        );
    }

    /// The rev files come over as files, and only the ones at or below the
    /// cut: the saved container arrives with the history it inherited
    /// already written, and carries nothing of the revs it left behind.
    #[test]
    fn the_saved_container_carries_exactly_the_revs_through_the_cut() {
        let dir = fixture::dir("prefix-revs");
        let from = dir.join("source.bwx");
        drop(source(&from));
        let to = dir.join("through-2.bwx");
        assert!(
            from.join(revs::entry(rev(3)).as_str()).is_file(),
            "precondition: the source holds a rev past the cut",
        );

        let saved = save_through(
            &Native::at(&from),
            rev(2),
            Native::at(&to),
            fixture::clock(),
            &Identity::new("grace"),
        )
        .expect("the prefix saves");
        drop(saved);

        for at in revs::through(rev(2)) {
            assert_eq!(
                std::fs::read(from.join(revs::entry(at).as_str())).expect("the source rev"),
                std::fs::read(to.join(revs::entry(at).as_str())).expect("the saved rev"),
                "rev {} did not come over as the bytes it was",
                at.get(),
            );
        }
        assert!(
            !to.join(revs::entry(rev(3)).as_str()).exists(),
            "a rev past the cut came over with the save",
        );
    }

    /// Verify-grade: the container replays, its head is the rev that was
    /// asked for, and the document it folds to is the one that rev held.
    #[test]
    fn the_saved_container_replays_to_the_rev_it_was_cut_at() {
        let dir = fixture::dir("prefix-replay");
        let from = dir.join("source.bwx");
        let held = source(&from);
        let at_two = blockworx_doc::repo::Repo::folding(&held.repo().log()[..2])
            .expect("the prefix folds")
            .document()
            .clone();
        drop(held);

        let to = dir.join("through-2.bwx");
        let saved = save_through(
            &Native::at(&from),
            rev(2),
            Native::at(&to),
            fixture::clock(),
            &Identity::new("grace"),
        )
        .expect("the prefix saves");
        assert_eq!(saved.repo().rev(), rev(2), "the head is not the cut");
        drop(saved);

        let reopened =
            Store::open(Native::at(&to), fixture::clock()).expect("the container reopens");
        assert!(
            reopened.read_only_reason().is_none(),
            "the saved container did not verify: {:?}",
            reopened.read_only_reason(),
        );
        assert_eq!(
            reopened.document().clone(),
            at_two,
            "the saved container is not the document that rev held",
        );
    }

    /// The tags the user asked to keep, and the ones they asked to lose:
    /// a name for a rev inside the prefix survives, and one for a rev past
    /// it is not there to be found.
    #[test]
    fn a_tag_inside_the_cut_survives_and_one_past_it_does_not() {
        let dir = fixture::dir("prefix-tags");
        let from = dir.join("source.bwx");
        let held = source(&from);
        assert_eq!(held.tags().len(), 2, "precondition: both revs are named");
        drop(held);

        let to = dir.join("through-2.bwx");
        let saved = save_through(
            &Native::at(&from),
            rev(2),
            Native::at(&to),
            fixture::clock(),
            &Identity::new("grace"),
        )
        .expect("the prefix saves");
        assert_eq!(saved.tags().of(rev(1)), ["the start"]);
        assert_eq!(
            saved.tags().of(rev(3)),
            Vec::<String>::new(),
            "a rev past the cut came over with its name",
        );
    }

    /// Editing on top of a saved prefix is ordinary authoring: the new
    /// container is writable at the rev it was cut at, and the next commit
    /// is rev N+1 of *its* log.
    #[test]
    fn a_saved_prefix_takes_the_next_edit_normally() {
        let dir = fixture::dir("prefix-authoring");
        let from = dir.join("source.bwx");
        drop(source(&from));

        let to = dir.join("through-1.bwx");
        let mut saved = save_through(
            &Native::at(&from),
            rev(1),
            Native::at(&to),
            fixture::clock(),
            &Identity::new("grace"),
        )
        .expect("the prefix");
        let next = saved
            .submit_edit(fixture::edits(3)[1].clone(), &Identity::new("grace"))
            .expect("the edit lands on the saved prefix");
        assert_eq!(
            next,
            rev(2),
            "the saved container did not author from its own head"
        );
        drop(saved);

        let reopened =
            Store::open(Native::at(&to), fixture::clock()).expect("the container reopens");
        assert_eq!(reopened.repo().rev(), rev(2));
        assert!(
            reopened.read_only_reason().is_none(),
            "the edit broke the chain"
        );
    }

    /// A rev named from the head — long after it was made — is still named
    /// in the container the cut writes. Its record cannot be copied (its
    /// parent link names a line that is not there), so it is written again
    /// by whoever asked for the save.
    #[test]
    fn a_name_given_later_to_a_rev_inside_the_cut_is_written_again() {
        let dir = fixture::dir("prefix-late-tag");
        let from = dir.join("source.bwx");
        {
            let mut store = source(&from);
            store
                .tag(
                    rev(2),
                    "worth keeping",
                    Tagging::Added,
                    &Identity::new("ada"),
                )
                .expect("the late tag");
        }

        let to = dir.join("through-2.bwx");
        let saved = save_through(
            &Native::at(&from),
            rev(2),
            Native::at(&to),
            fixture::clock(),
            &Identity::new("grace"),
        )
        .expect("the prefix saves");
        assert_eq!(
            saved.tags().of(rev(2)),
            ["worth keeping"],
            "a name given after the cut's own rev was left behind with it",
        );
        assert_eq!(saved.repo().rev(), rev(2), "a re-written tag spent a rev");
        drop(saved);

        let reopened =
            Store::open(Native::at(&to), fixture::clock()).expect("the container reopens");
        assert!(
            reopened.read_only_reason().is_none(),
            "the re-written tag broke the chain: {:?}",
            reopened.read_only_reason(),
        );
        assert_eq!(reopened.tags().of(rev(2)), ["worth keeping"]);
    }

    /// A name the source later *cleared* is not put back: what the saved
    /// container calls a rev is what the source calls it now.
    #[test]
    fn a_name_the_source_took_back_does_not_come_over() {
        let dir = fixture::dir("prefix-untag");
        let from = dir.join("source.bwx");
        {
            let mut store = source(&from);
            store
                .tag(rev(1), "the start", Tagging::Removed, &Identity::new("ada"))
                .expect("the untag");
        }

        let to = dir.join("through-2.bwx");
        let saved = save_through(
            &Native::at(&from),
            rev(2),
            Native::at(&to),
            fixture::clock(),
            &Identity::new("grace"),
        )
        .expect("the prefix saves");
        assert_eq!(
            saved.tags().of(rev(1)),
            Vec::<String>::new(),
            "the saved container kept a name the source had dropped",
        );
    }

    /// Artwork the prefix names travels with it — content-addressed, so
    /// the file keeps its name — and the saved container hydrates it on
    /// replay rather than opening read-only over a reference it cannot
    /// honour.
    #[test]
    fn the_artwork_the_prefix_names_comes_with_it() {
        let dir = fixture::dir("prefix-assets");
        let from = dir.join("source.bwx");
        let asset = {
            let mut store =
                Store::create(Native::at(&from), fixture::clock()).expect("the container");
            let author = Identity::new("ada");
            store
                .submit_edit(fixture::edits(1)[0].clone(), &author)
                .expect("the block lands");
            let asset = fixture::svg(1);
            store
                .submit_edit(
                    fixture::commit("Added an icon", fixture::icon(1, &asset)),
                    &author,
                )
                .expect("the icon lands");
            asset
        };
        assert_eq!(
            std::fs::read_dir(from.join(ASSETS))
                .expect("the source assets")
                .count(),
            1,
            "precondition: the payload was extracted beside the source log",
        );

        let to = dir.join("through-2.bwx");
        let saved = save_through(
            &Native::at(&from),
            rev(2),
            Native::at(&to),
            fixture::clock(),
            &Identity::new("grace"),
        )
        .expect("the prefix saves");
        assert!(
            saved.read_only_reason().is_none(),
            "the saved container could not honour its own artwork: {:?}",
            saved.read_only_reason(),
        );
        drop(saved);
        let carried: Vec<Vec<u8>> = std::fs::read_dir(to.join(ASSETS))
            .expect("the saved assets")
            .map(|entry| std::fs::read(entry.expect("an entry").path()).expect("the payload"))
            .collect();
        assert_eq!(carried, vec![asset.bytes().to_vec()]);
    }

    /// The cut is a rev this log holds, or it is refused — a container half
    /// written is worse than a save that did not happen.
    #[test]
    fn a_rev_the_log_does_not_hold_is_refused() {
        let dir = fixture::dir("prefix-no-such-rev");
        let from = dir.join("source.bwx");
        drop(source(&from));

        let to = dir.join("through-9.bwx");
        assert!(matches!(
            save_through(
                &Native::at(&from),
                rev(9),
                Native::at(&to),
                fixture::clock(),
                &Identity::new("grace")
            ),
            Err(PrefixFailure::NoSuchRev(_)),
        ));
        assert!(!to.exists(), "a refused save left a container behind");
    }

    /// Cutting at the head copies the whole log — which is what an ordinary
    /// Save-as of an open container now is.
    #[test]
    fn cutting_at_the_head_copies_every_line() {
        let dir = fixture::dir("prefix-whole");
        let from = dir.join("source.bwx");
        drop(source(&from));

        let to = dir.join("whole.bwx");
        let saved = save_through(
            &Native::at(&from),
            rev(3),
            Native::at(&to),
            fixture::clock(),
            &Identity::new("grace"),
        )
        .expect("the whole log");
        assert_eq!(saved.repo().rev(), rev(3));
        assert_eq!(saved.tags().len(), 2, "a whole copy dropped a name");
        drop(saved);
        assert_eq!(
            std::fs::read(from.join(MANIFEST.as_str())).expect("the source manifest"),
            std::fs::read(to.join(MANIFEST.as_str())).expect("the copy"),
            "a whole copy is not the same bytes",
        );
    }
}