blockworx_store/

dump.rs

//! `blockworx log` and `blockworx verify`: a container's audit trail on
//! the console, and the fsck that proves it whole.
//!
//! Deliberately not a [`Store`](super::handle::Store): both read, so
//! neither takes the container's lock nor repairs a crash-truncated
//! tail. They read the file's own bytes through the same scanner the
//! editor opens with, and report a manifest that stops verifying the way
//! the editor does — the trail up to the break, then the break, with the
//! line it happened on.
//!
//! What separates them is depth. `log` reads history, so it checks the
//! chain and nothing else; `verify` hashes **every** rev file against the
//! row that names it, which is the only thing that names a damaged rev
//! exactly.

use blockworx_doc::rev::Rev;

use super::container::{Container, MANIFEST};
use super::history::{self, Journal};
use super::manifest::{self, BreakReport, End};
use super::revs;
use super::storage::{Storage, ready_now};

/// A container's trail as text, and — when the manifest stops verifying —
/// the break the trail ends at.
pub struct Dump {
    pub lines: Vec<String>,
    /// The typed failure, already carrying the manifest's source, so the
    /// console shows the offending row under an arrow.
    pub broken: Option<miette::Report>,
}

/// Read the container's manifest and render it.
///
/// # Errors
/// The read failure — there is no container there, or its manifest cannot
/// be read.
pub fn dump<S: Storage>(storage: &S) -> std::io::Result<Dump> {
    let named = storage.names(&MANIFEST);
    let text = manifest_text(storage)?;
    let scanned = manifest::scan(&text);
    let broken = ended(&named, &text, &scanned.end);
    let history = manifest::history(&scanned.rows);
    Ok(Dump {
        lines: history::lines(&history::rows(
            Journal::Recorded(&history.rows),
            &history.tags,
        )),
        broken,
    })
}

/// What a full verification covered, and — when something does not hold
/// up — the first thing that did not.
pub struct Verification {
    pub lines: Vec<String>,
    pub broken: Option<miette::Report>,
}

/// Recompute every chain link in the container's manifest, and hash every
/// rev file against the row that names it.
///
/// # Errors
/// The read failure — there is no container there, or its manifest cannot
/// be read.
pub fn verify<S: Storage>(storage: S) -> std::io::Result<Verification> {
    let named = storage.names(&MANIFEST);
    let text = manifest_text(&storage)?;
    let written = text.lines().count();
    let scanned = manifest::scan(&text);
    let verified = scanned.rows.len();
    let ended = ended(&named, &text, &scanned.end);
    let history = manifest::history(&scanned.rows);
    if let End::Broken(_) = scanned.end {
        return Ok(Verification {
            lines: vec![format!(
                "{named}: {verified} of {written} rows verified before the break",
            )],
            broken: ended,
        });
    }
    let mut lines = vec![
        format!("{named}: {verified} of {written} rows verified — every chain link"),
        format!("head {}", history.head),
    ];
    // Read-only throughout: the fsck neither takes the lock nor repairs
    // anything, so it looks through a handle that claims nothing.
    let reading = Container::reading(storage).map_err(std::io::Error::other)?;
    let unwitnessed = history
        .rows
        .iter()
        .find_map(|row| revs::witnessed(&reading.revs(), row.rev, row.hash).err());
    match &unwitnessed {
        None => lines.push(format!(
            "{revs} rev files hold the bytes their rows name",
            revs = history.rows.len(),
        )),
        Some(fault) => lines.push(format!("{fault}")),
    }
    // A rev file the container cannot decode is a finding too: the row
    // chain and the bytes can both be intact over a document this build
    // no longer reads.
    let unreadable = missing_artwork(&reading, &history.rows);
    let said = unwitnessed
        .map(|fault| miette::miette!("{fault}"))
        .or_else(|| unreadable.map(|fault| miette::miette!("{fault}")));
    Ok(Verification {
        lines,
        broken: said.or(ended),
    })
}

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

/// The first rev whose document, artwork and all, the container cannot
/// hand back.
fn missing_artwork<S: Storage>(
    container: &Container<S>,
    rows: &[manifest::Row],
) -> Option<revs::RevFault> {
    rows.iter()
        .map(|row| row.rev)
        .find_map(|at| container.read_rev(at).err())
}

/// How the row sequence stopped, as a located report — or nothing, for a
/// manifest that ends where it should.
fn ended(named: &str, text: &str, end: &End) -> Option<miette::Report> {
    match end {
        End::Whole => None,
        End::Truncated(dropped) => Some(report(
            named,
            text,
            dropped.at.offset,
            text.len() - dropped.at.offset,
            "the manifest ends in a row that was never finished; the editor drops it \
             on the next open",
        )),
        End::Broken(BreakReport { at, fault }) => {
            Some(report(named, text, at.offset, at.len, &fault.to_string()))
        }
    }
}

fn report(named: &str, text: &str, offset: usize, len: usize, said: &str) -> miette::Report {
    miette::miette!(
        labels = vec![miette::LabeledSpan::at(offset..offset + len, "here")],
        "{said}",
    )
    .with_source_code(miette::NamedSource::new(named, text.to_owned()))
}

/// Whether a rev this history holds can be read back at all — what an
/// undo to it would need.
pub fn reachable<S: Storage>(storage: S, at: Rev) -> bool {
    Container::reading(storage).is_ok_and(|container| container.read_rev(at).is_ok())
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::fixture;
    use crate::handle::{Clock, Store};
    use crate::record::WallTime;
    use crate::storage::Native;
    use blockworx_doc::fixtures::rev;
    use std::path::Path;

    fn pinned() -> Clock {
        Clock::Pinned {
            at: WallTime::from_unix_millis(1_756_000_000_000),
            step: std::time::Duration::from_secs(1),
        }
    }

    fn three_edits(root: &Path) {
        let mut store = Store::create(Native::at(root), pinned()).expect("the container");
        for commit in fixture::edits(3) {
            store
                .submit_edit(commit, &fixture::author())
                .expect("the edit lands");
        }
    }

    #[test]
    fn a_whole_manifest_dumps_every_row_and_reports_nothing() {
        let dir = fixture::dir("dump-whole");
        let root = dir.join("doc.bwx");
        three_edits(&root);

        let dumped = dump(&Native::at(&root)).expect("the manifest reads");
        assert_eq!(dumped.lines.len(), 3);
        assert!(dumped.broken.is_none());
        assert!(dumped.lines[0].starts_with("r1  "), "{}", dumped.lines[0]);
        assert!(
            dumped.lines[2].contains("Added a block"),
            "{}",
            dumped.lines[2]
        );
    }

    /// The one behaviour that makes the dump worth running on a container
    /// the editor already refused: the trail up to the break is real, and
    /// is printed before the break is named.
    #[test]
    fn a_broken_manifest_dumps_its_verified_prefix_and_then_the_break() {
        let dir = fixture::dir("dump-broken");
        let root = dir.join("doc.bwx");
        three_edits(&root);

        let mut lines = crate::tests::manifest_lines(&root);
        lines[1] = r#"{"rev":2,"kind":"edit","#.to_owned();
        crate::tests::write_manifest(&root, &lines);

        let dumped = dump(&Native::at(&root)).expect("a damaged manifest still reads");
        assert_eq!(
            dumped.lines.len(),
            1,
            "the prefix that verified is what there is to show",
        );
        let said = format!("{:?}", dumped.broken.expect("the break is reported"));
        assert!(said.contains("does not parse"), "{said}");
        assert!(
            said.contains("2 │"),
            "the report points at the line: {said}"
        );
    }

    /// The fsck's own job: a rev file that is not the bytes its row names
    /// is found by rev, and the manifest chaining is no defence.
    #[test]
    fn verify_names_a_rev_file_that_is_not_what_its_row_says() {
        let dir = fixture::dir("verify-rev-drift");
        let root = dir.join("doc.bwx");
        three_edits(&root);
        assert!(
            verify(Native::at(&root))
                .expect("the manifest reads")
                .broken
                .is_none(),
            "precondition: the container verifies before it is tampered with",
        );

        std::fs::write(root.join(revs::entry(rev(2)).as_str()), b"not a document")
            .expect("the rev file is rewritten");

        let checked = verify(Native::at(&root)).expect("the manifest reads");
        let said = format!("{:?}", checked.broken.expect("the damage is reported"));
        assert!(said.contains("rev 2"), "{said}");
        assert!(
            checked.lines[0].contains("3 of 3 rows verified"),
            "the manifest itself is still whole: {}",
            checked.lines[0],
        );
        assert!(
            !reachable(Native::at(&root), rev(2)),
            "an undo to a rev the container cannot read must refuse",
        );
    }

    /// A rev that is simply gone is the same finding, and the same
    /// refusal.
    #[test]
    fn verify_names_a_rev_file_that_is_missing() {
        let dir = fixture::dir("verify-rev-missing");
        let root = dir.join("doc.bwx");
        three_edits(&root);
        std::fs::remove_file(root.join(revs::entry(rev(2)).as_str())).expect("the rev file goes");

        let checked = verify(Native::at(&root)).expect("the manifest reads");
        let said = format!("{:?}", checked.broken.expect("the hole is reported"));
        assert!(said.contains("rev 2"), "{said}");
        assert!(!reachable(Native::at(&root), rev(2)));
        assert!(
            reachable(Native::at(&root), rev(3)),
            "the head is still readable, so the container still opens",
        );
    }

    #[test]
    fn a_path_that_is_not_a_container_says_so() {
        let dir = fixture::dir("dump-missing");
        assert!(dump(&Native::at(dir.join("nothing-here"))).is_err());
        assert!(verify(Native::at(dir.join("nothing-here"))).is_err());
    }

    #[test]
    fn a_whole_manifest_verifies_end_to_end_and_says_what_it_covered() {
        let dir = fixture::dir("verify-whole");
        let root = dir.join("doc.bwx");
        three_edits(&root);

        let checked = verify(Native::at(&root)).expect("the manifest reads");
        assert!(checked.broken.is_none(), "{:?}", checked.broken);
        assert!(
            checked.lines[0].contains("3 of 3 rows verified"),
            "{}",
            checked.lines[0],
        );
        assert!(
            checked.lines[1].starts_with("head "),
            "{}",
            checked.lines[1]
        );
        assert!(
            checked.lines[2].contains("3 rev files"),
            "{}",
            checked.lines[2],
        );
    }
}