froe 0.10.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

//! Reader for Apache Jackrabbit Oak `segment-tar` (`TarMK`) repositories.
//!
//! `TarMK` is the storage engine used by Apache Jackrabbit Oak and Adobe
//! Experience Manager: content is stored as immutable *segments* packed into
//! tar archives, and a *journal* records the sequence of repository head
//! states. This crate opens such a repository directly from disk, resolves
//! the current head state, and exposes the content tree for traversal and
//! extraction — without a running Oak instance.
//!
//! The reading API ([`Repository`], [`store`], [`content`], [`tooling`]) is
//! read-only by design: it never takes the repository lock and never
//! modifies any file, so it is safe to point at a live repository. Like Oak,
//! the reader memory-maps archives and relies on the store's
//! never-modify-in-place file protocol; an external process that truncates or
//! rewrites an archive would disturb both froe and a running Oak instance.
//!
//! The mutating writing API ([`writer`]) covers commits, checkpoints,
//! compaction and the reclamation it performs, backup, restore, and journal
//! recovery. It takes the exclusive repository lock first, so it cannot race a
//! cooperating running instance, and produces stores byte-for-byte compatible
//! with Oak (apart from the documented extreme-subnormal rendering residue;
//! see [`content::property::double_to_text`]). Planning a compaction is the
//! read-only exception and never takes the lock. Run mutations only against a *stopped*
//! repository. The writer requires a Unix operating-system entropy source and
//! therefore refuses to open on Windows.
//!
//! **The writing API is verified against a real Oak instance**: the
//! workspace interoperability suite round-trips it through Apache
//! Jackrabbit Oak `oak-segment-tar` 1.90.0 — Oak writes the store, froe
//! commits, checkpoints, compacts, cleans up, backs up, restores and
//! recovers the journal, and Oak then boots against each result and serves
//! a byte-identical content tree without logging any of its own repair
//! messages. Still unverified against a live instance: `store.version=1`
//! stores, external blob stores, native macOS or Windows execution, and
//! Adobe AEM itself, which ships its own Oak build. Writing still requires
//! a stopped repository, and keeping a copy before a destructive operation
//! on irreplaceable data remains ordinary prudence.
//!
//! # Example
//!
//! ```no_run
//! use froe::store::Repository;
//!
//! fn main() -> froe::Result<()> {
//!     let repository = Repository::open(std::path::Path::new("/path/to/segmentstore"))?;
//!     if let Some(node) = repository.node_at_path("/content")? {
//!         for property in node.properties()? {
//!             println!("{} = {:?}", property.name, property.values);
//!         }
//!         for (name, child) in node.child_node_entries()? {
//!             println!("{name}: {} children", child.child_node_count()?);
//!         }
//!     }
//!     Ok(())
//! }
//! ```
//!
//! # Layers
//!
//! Each layer is usable on its own:
//!
//! * [`tar_archive`] — archives, indexes, segment graphs, binary
//!   reference catalogs;
//! * [`segment`] — segment parsing and record addressing;
//! * [`content`] — decoding records into nodes, properties, and values;
//! * [`journal`] — the head revision log;
//! * [`gc_journal`] — optional garbage-collection history;
//! * [`store`] — the assembled read-only repository.
//!
//! Long-running operations — opening a large store, planning a compaction,
//! compacting, checking consistency — have a `_with_progress` twin that
//! reports what they are doing to a [`progress::ProgressObserver`], so a
//! caller need not guess whether a silent minute means work or a hang.
//!
//! Custom backends (in-memory fixtures, remote stores) implement
//! [`SegmentProvider`] and reuse the whole content layer unchanged.

pub(crate) mod cache;
pub mod checksum;
pub mod content;
pub mod error;
pub mod gc_journal;
pub mod hashing;
mod java;
pub mod journal;
pub(crate) mod packed_records;
pub(crate) mod parallel;
pub mod progress;
pub mod segment;
pub mod store;
pub mod tar_archive;
pub mod tooling;
pub mod units;
pub mod writer;

pub use content::{
    BinaryStream, BinaryValue, NodeState, PropertyState, PropertyType, PropertyValue,
    PropertyValues, SegmentProvider, Template, read_binary_stream,
};
pub use error::{Error, Result};
pub use gc_journal::GarbageCollectionJournalEntry;
pub use journal::JournalEntry;
pub use progress::{DiscardedProgress, ProgressObserver, Step, WorkUnit};
pub use segment::{
    GarbageCollectionGeneration, RecordIdentifier, RecordType, SegmentIdentifier, SegmentKind,
};
pub use store::Repository;
pub use units::format_byte_size;
pub use writer::{
    ArchiveRewritePolicy, CompactedGeneration, CompactionAction, CompactionKind, CompactionOptions,
    CompactionOutcome, CompactionPlan, FileDeletionFailure, JournalLineRemoval,
    JournalRemovalReason, PreparedCompaction, RecoveryBackupPolicy, RecoveryOutcome,
    StaleArchiveReason, WritableRepository, backup, backup_with_progress, compact,
    compact_with_progress, plan_compaction, plan_compaction_with_progress, recover_journal,
    recover_journal_with_progress, restore, restore_with_progress,
};