froe

A Rust implementation of Apache Jackrabbit Oak's segment-tar ("TarMK") storage format — the repository format used by Apache Jackrabbit Oak and Adobe Experience Manager.

This crate opens a segment store directly from disk, without a running Oak instance. The reading API (store, content, tooling) is read-only and safe against a live repository: it neither takes the lock nor writes. Like Oak, it 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, applying compaction and the reclamation it performs, backup, restore, and journal recovery. It takes the exclusive repository lock and produces stores byte-for-byte compatible with Oak (apart from the documented extreme-subnormal double_to_text rendering residue), so a subsequent AEM start consumes the result cleanly. Planning Planning a compaction is the read-only exception and never takes the lock. Run mutations only against a stopped repository. The writer currently requires a Unix operating-system entropy source and therefore refuses to open on Windows. If repo.lock is absent, opening any writer also requires same-directory hard-link and durable directory-fsync support to publish the new mode-0600 lock safely; an unsupported filesystem fails closed.

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.

See the workspace repository for the complete feature map and storage format documentation, including the compaction safety guide, and the froe-cli crate for the command-line interface.

Large inline binaries can be consumed without materializing their full contents through content::read_binary_stream, whose returned BinaryStream implements std::io::Read. The bounded opener does not follow a long external blob-identifier record merely to report that local content is unavailable; the legacy materializing helper retains its identifier-bearing error. The read-only gc_journal module parses both legacy six-field and current seven-field gc.log histories even when the repository itself cannot resolve a head. Its default readers preserve Oak's empty result for unavailable or undecodable optional journals, while returning typed errors instead of silently discarding entries that exceed froe's configurable resource limits.

Low-level diagnostics expose tooling::dump_segment_bytes, which preserves a raw hex dump even when segment parsing fails, and tooling::debug_archive_with_options, which applies explicit retained-row, retained-text, total-work, per-node child/name, pending-traversal, and graph row/edge budgets. Archive graphs are totalized to one row per segment and reconstructed archive-locally when the stored graph is missing or corrupt.

Licensed under the Apache License, Version 2.0.