froe 0.12.0

Reader and offline maintenance toolkit for Apache Jackrabbit Oak segment-tar (TarMK) repositories: parse archives and records, extract node data, compact, back up, and recover.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140

//! Every boundary of the manifest replacement: whichever way a run dies,
//! the file left behind is exactly the old manifest or exactly the new.

#[cfg(test)]
mod tests {
    use crate::writer::commit::create_checkpoint;
    use crate::writer::fault_injection::test_support::{
        MANIFEST_SCENARIO, RepositorySnapshot, TestDirectory, assert_exact_snapshot_reopens,
        run_crash_child, run_error_child, snapshot_repository,
    };
    use crate::writer::store_writer::WritableRepository;
    use std::path::Path;

    fn create_manifest_upgrade_fixture(
        directory: &TestDirectory,
    ) -> (RepositorySnapshot, Vec<u8>, Vec<u8>) {
        {
            let store = WritableRepository::open(&directory.path).expect("open manifest fixture");
            create_checkpoint(&store, 60_000, &[])
                .expect("create deterministically unreferenced checkpoint");
            store.close().expect("close manifest fixture writer");
        }
        let old_manifest = b"custom.property=kept\nstore.version=1\n".to_vec();
        std::fs::write(directory.path.join("manifest"), &old_manifest)
            .expect("install version-one manifest fixture");
        let mut upgraded_manifest = old_manifest.clone();
        upgraded_manifest.push(b'\n');
        upgraded_manifest
            .extend_from_slice(b"# upgraded atomically by froe cleanup\nstore.version=2\n");
        (
            snapshot_repository(&directory.path),
            old_manifest,
            upgraded_manifest,
        )
    }

    /// What a fault at a manifest-replacement cutpoint must leave on disk.
    #[derive(Clone, Copy)]
    struct ExpectedManifestResidue {
        /// The upgraded manifest is in place under its final name.
        replacement_installed: bool,
        /// The staging temporary is still present.
        temporary_exists: bool,
    }

    fn assert_manifest_residue(
        directory: &Path,
        snapshot: &RepositorySnapshot,
        old_manifest: &[u8],
        upgraded_manifest: &[u8],
        residue: ExpectedManifestResidue,
        cutpoint: &str,
    ) {
        let ExpectedManifestResidue {
            replacement_installed,
            temporary_exists,
        } = residue;
        assert_exact_snapshot_reopens(directory, snapshot);
        assert_eq!(
            std::fs::read(directory.join("manifest")).expect("read canonical manifest"),
            if replacement_installed {
                upgraded_manifest
            } else {
                old_manifest
            },
            "canonical manifest must be one complete valid generation at {cutpoint}"
        );
        let temporary = directory.join("manifest.cleaning.000");
        assert_eq!(temporary.exists(), temporary_exists, "{cutpoint}");
        if temporary_exists {
            assert_eq!(
                std::fs::read(temporary).expect("read staged manifest residue"),
                upgraded_manifest,
                "manifest staging residue must contain the exact valid upgrade"
            );
        }
    }

    #[test]
    fn manifest_replacement_crash_boundaries_keep_an_exact_old_or_new_manifest() {
        let cutpoints = [
            ("manifest.temporary-durable", false, true),
            ("manifest.before-rename", false, true),
            ("manifest.renamed-before-directory-sync", true, false),
            ("manifest.before-post-rename-directory-sync", true, false),
            ("manifest.rename-durable", true, false),
        ];

        for (cutpoint, replacement_installed, temporary_exists) in cutpoints {
            let directory = TestDirectory::repository(cutpoint);
            let (snapshot, old_manifest, upgraded_manifest) =
                create_manifest_upgrade_fixture(&directory);

            run_crash_child(&directory.path, MANIFEST_SCENARIO, cutpoint);

            assert_manifest_residue(
                &directory.path,
                &snapshot,
                &old_manifest,
                &upgraded_manifest,
                ExpectedManifestResidue {
                    replacement_installed,
                    temporary_exists,
                },
                cutpoint,
            );
        }
    }

    #[test]
    fn manifest_replacement_errors_keep_an_exact_old_or_new_manifest() {
        let cutpoints = [
            ("manifest.temporary-durable", false),
            ("manifest.before-rename", false),
            ("manifest.renamed-before-directory-sync", true),
            ("manifest.before-post-rename-directory-sync", true),
            ("manifest.rename-durable", true),
        ];

        for (cutpoint, replacement_installed) in cutpoints {
            let directory = TestDirectory::repository(cutpoint);
            let (snapshot, old_manifest, upgraded_manifest) =
                create_manifest_upgrade_fixture(&directory);

            run_error_child(&directory.path, MANIFEST_SCENARIO, cutpoint);

            assert_manifest_residue(
                &directory.path,
                &snapshot,
                &old_manifest,
                &upgraded_manifest,
                ExpectedManifestResidue {
                    replacement_installed,
                    temporary_exists: false,
                },
                cutpoint,
            );
        }
    }
}