Struct FsStore 

pub struct FsStore { /* private fields */ }

Filesystem-based storage for Heddle objects.

Layout:

.heddle/
  objects/
    blobs/
      ab/
        cdef1234...
    trees/
      ab/
        cdef1234...
    states/
      <change_id>.state
  actions/
    <action_id>.action
  packs/
    <hash>.pack
    <hash>.idx

Implementations

impl FsStore

pub fn new(root: impl AsRef<Path>) -> Self

Create a new filesystem store rooted at the given path.

The path should be the .heddle directory.

pub fn with_compression( root: impl AsRef<Path>, compression: CompressionConfig, ) -> Self

Create a new filesystem store with custom compression settings.

pub fn init(&self) -> Result<()>

Initialize the directory structure.

pub fn root(&self) -> &Path

Get the root path.

pub fn compression(&self) -> CompressionConfig

Get the compression configuration.

pub fn set_compression(&mut self, compression: CompressionConfig)

Set the compression configuration.

pub fn loose_object_write_mode(&self) -> LooseObjectWriteMode

pub fn set_loose_object_write_mode(&mut self, mode: LooseObjectWriteMode)

pub fn reload_packs(&self) -> Result<()>

Reload pack files from disk.

pub fn pack_manager(&self) -> &RwLock<PackManager>

Get the pack manager for pack operations.

pub fn clear_recent_object_caches(&self)

pub fn pack_ids(&self) -> Result<Vec<PackObjectId>>

Trait Implementations

impl ObjectStore for FsStore

fn get_blob_bytes(&self, hash: &ContentHash) -> Result<Option<Bytes>>

Zero-copy pack fast path. When the blob lives in a packfile and is non-delta + uncompressed, returns a Bytes::slice view of the pack’s mmap — no decompression, no allocation, no memcpy. Compressed pack entries, delta entries, and loose blobs fall back to get_blob and wrap the result in a Bytes (the Vec → Bytes conversion is itself zero-copy).

fn loose_blob_path(&self, hash: &ContentHash) -> Option<PathBuf>

Loose blob path safe for clonefile/copy materialization.

Returns Some(path) only when the loose file exists, is stored uncompressed, and its bytes hash to the expected content hash. Compressed blobs and pack-only blobs fall through to None; so do torn cache-mirror files (the AtomicWriteMode::NoSync write side may leave one if the host crashed during a previous promote). On the torn case the caller re-promotes from the authoritative pack copy.

Verification is amortised: a hash that passes the check once in this process is recorded in verified_loose_blobs and subsequent calls skip the read+hash. So the cost on the materialize hot path is at most one BLAKE3 over each unique blob per process lifetime — negligible for tiny blobs, bounded by working-set size for huge ones.

fn promote_to_loose_uncompressed(&self, hash: &ContentHash) -> Result<bool>

Promote a blob to its uncompressed-loose canonical path so loose_blob_path returns Some(path) and hardlink-first materialization fires.

Three cases:

1. Already loose+uncompressed: peek the header, no-op.
2. Loose but compressed: read+decompress, atomically rewrite the canonical path with raw bytes.
3. Pack-only: read out of the pack via get_blob, atomically write to the canonical loose path. Pack copy is left in place — the next prune cycle will discard the loose mirror and a future materialize will re-promote.

fn clear_recent_caches(&self)

Drop any in-memory caches of decompressed blobs / trees / states. The next access to any object pays full I/O + decompression cost. No-op for stores that don’t cache (InMemoryStore is already the source of truth).

fn get_blob(&self, hash: &ContentHash) -> Result<Option<Blob>>

fn put_blob(&self, blob: &Blob) -> Result<ContentHash>

fn put_blob_with_hash( &self, blob: &Blob, hash: ContentHash, ) -> Result<ContentHash>

fn put_blob_bytes_with_hash( &self, data: &[u8], hash: ContentHash, ) -> Result<ContentHash>

fn has_blob(&self, hash: &ContentHash) -> Result<bool>

fn blob_size(&self, hash: &ContentHash) -> Result<Option<u64>>

Return the uncompressed byte length of the blob identified by hash, or Ok(None) when the blob is not in the store.

fn get_tree(&self, hash: &ContentHash) -> Result<Option<Tree>>

fn put_tree(&self, tree: &Tree) -> Result<ContentHash>

fn put_tree_serialized( &self, data: &[u8], hash: ContentHash, ) -> Result<ContentHash>

fn has_tree(&self, hash: &ContentHash) -> Result<bool>

fn get_state(&self, id: &ChangeId) -> Result<Option<State>>

fn put_state(&self, state: &State) -> Result<()>

fn put_state_serialized(&self, data: &[u8], id: ChangeId) -> Result<()>

fn has_state(&self, id: &ChangeId) -> Result<bool>

fn list_states(&self) -> Result<Vec<ChangeId>>

fn get_action(&self, id: &ActionId) -> Result<Option<Action>>

fn put_action(&self, action: &mut Action) -> Result<ActionId>

fn list_actions(&self) -> Result<Vec<ActionId>>

fn list_blobs(&self) -> Result<Vec<ContentHash>>

fn list_trees(&self) -> Result<Vec<ContentHash>>

fn pack_objects(&self, aggressive: bool) -> Result<(u64, u64)>

fn get_pack_object( &self, id: &PackObjectId, ) -> Result<Option<(ObjectType, Vec<u8>)>>

fn install_pack( &self, pack_data: &[u8], index_data: &[u8], ) -> Result<Vec<PackObjectId>>

fn put_blobs_packed(&self, blobs: Vec<(ContentHash, Vec<u8>)>) -> Result<()>

Bulk-write a batch of blobs as a single durable unit. The default implementation falls back to per-blob writes; backends that support packfiles (i.e. FsStore) override this to install one packfile + index — two fsyncs total instead of N. Used by the snapshot hot path so writing 1000 small files takes ~one fsync, not 1000.

fn install_pack_streaming( &self, pack_path: &Path, index_path: &Path, ) -> Result<Vec<PackObjectId>>

Install a pack and its index from on-disk files (typically produced by StreamingPackBuilder). The default impl reads both files fully and delegates to install_pack, so any backend that doesn’t override this still works (at the cost of giving back the bounded-memory promise). Real fs- backed stores override this to rename(2) both files into the pack directory without ever loading them.

fn prune_loose_objects(&self) -> Result<(u64, u64)>

fn begin_snapshot_write_batch(&self) -> Result<()>

fn flush_snapshot_write_batch(&self) -> Result<()>

fn abort_snapshot_write_batch(&self)

fn has_redactions_for_blob(&self, blob: &ContentHash) -> Result<bool>

Whether the store holds any redaction record for the given blob.

fn get_redactions_bytes_for_blob( &self, blob: &ContentHash, ) -> Result<Option<Vec<u8>>>

Return the raw rmp-encoded RedactionsBlob bytes for the given blob, or Ok(None) if no redaction record exists. The bytes are byte-identical to what was written by put_redactions_bytes_for_blob (or by Repository::put_redaction); this is the wire-transfer payload, not a re-serialized view.

fn put_redactions_bytes_for_blob( &self, blob: &ContentHash, bytes: &[u8], ) -> Result<()>

Persist the rmp-encoded RedactionsBlob bytes for the given blob. Receiver-side replay calls this after signature verification so the bytes land in the same sidecar that the sender’s Repository::put_redaction writes to.

fn list_blobs_with_redactions(&self) -> Result<Vec<ContentHash>>

List every blob that has at least one redaction record. Used by the GC pin guard and by sync to enumerate redactions for the state closure. Order is unspecified; callers that need stable ordering should sort.

fn has_state_visibility_for_state(&self, state: &ChangeId) -> Result<bool>

Whether the store holds any state-visibility record for state.

fn get_state_visibility_bytes_for_state( &self, state: &ChangeId, ) -> Result<Option<Vec<u8>>>

Return the raw rmp-encoded StateVisibilityBlob bytes for state, or Ok(None) if no sidecar exists. The bytes are the wire-transfer payload for state visibility.

fn put_state_visibility_bytes_for_state( &self, state: &ChangeId, bytes: &[u8], ) -> Result<()>

Persist raw StateVisibilityBlob bytes for state.

fn list_states_with_visibility(&self) -> Result<Vec<ChangeId>>

List every state with at least one state-visibility record.

fn put_action_serialized(&self, data: &[u8], id: ActionId) -> Result<()>