Struct FlatFileStore 

pub struct FlatFileStore { /* private fields */ }

Content-addressed flat-file blob store keyed by BLAKE3.

An in-memory cache of (meta_hash, node_id) pairs and known meta_hash values is maintained to avoid O(n) linear scans of index.ndjson on the indexer hot path. The cache is populated during [init] and updated by [append_index].

Implementations

impl FlatFileStore

pub fn open(root: impl Into<PathBuf>) -> Self

Open (or create) a store rooted at root.

Directories are created lazily by [init].

pub async fn init(&self) -> Result<(), StoreError>

Create the required directory structure and populate the in-memory dedup cache from any existing index.ndjson.

pub fn resolve_path( &self, blake3_hex: &str, ) -> Result<Option<PathBuf>, StoreError>

Return the filesystem path for a blob without reading it.

Returns Some(path) if the blob exists locally, None otherwise.

pub async fn put(&self, bytes: &[u8]) -> Result<Blake3Hex, StoreError>

Hash bytes with BLAKE3 and store under blobs/.

Returns the 64-char hex key. Idempotent: if the blob already exists the write is skipped (content-addressable deduplication).

pub async fn get(&self, blake3_hex: &str) -> Result<Option<Vec<u8>>, StoreError>

Read a blob by its 64-char BLAKE3 hex key. Returns None if not found.

pub fn contains(&self, blake3_hex: &str) -> Result<bool, StoreError>

Check existence without reading the full blob.

pub async fn append_index(&self, record: &IndexRecord) -> Result<(), StoreError>

Append one record to index.ndjson (one JSON object per line).

Also updates the in-memory dedup and meta_hash caches.

pub async fn append_index_if_absent( &self, record: &IndexRecord, ) -> Result<bool, StoreError>

Append one record only if the (meta_hash, node_id) pair is absent.

Returns true when a new record was appended, false when the record was already present in the dedup cache.

pub fn iter_index( &self, ) -> Result<impl Iterator<Item = Result<IndexRecord, StoreError>>, StoreError>

Iterate all records from the in-memory index cache.

pub fn has_index_record( &self, meta_hash: &str, node_id: &str, ) -> Result<bool, StoreError>

True if the exact (meta_hash, node_id) pair is already recorded.

Uses the in-memory dedup cache — O(1) after [init].

pub fn has_meta_hash(&self, meta_hash: &str) -> Result<bool, StoreError>

True if any record is known for this metadata blob.

Uses the in-memory meta_hash cache — O(1) after [init].

pub fn discovery_events_since( &self, since_seq: u64, ) -> Result<Vec<(u64, IndexRecord)>, StoreError>

Return all RemoteAnnouncement index records at or after position since_seq.

since_seq is a 0-based line number in index.ndjson. The discovery worker persists the last processed seq and resumes from there on restart, providing at-least-once delivery across restarts.

Returns (seq, record) pairs ordered by ascending seq.

pub fn latest_local_publish( &self, igc_hash: &Blake3Hex, node_id: &NodeIdHex, ) -> Result<Option<IndexRecord>, StoreError>

Return the latest local publish record for an IGC hash from this node.

pub fn load_key_bytes(&self) -> Result<Option<[u8; 32]>, StoreError>

Load the raw 32-byte secret key from node.key, or return None if the file does not exist.

pub fn save_key_bytes(&self, bytes: &[u8; 32]) -> Result<(), StoreError>

Persist a 32-byte secret key to node.key with mode 0600.