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 cleanup, compaction, 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 cleanup 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 cleanup 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.