Ferricstore.DataDir (ferricstore v0.4.0)

Manages the FerricStore on-disk directory layout (spec section 2B.4).

The canonical directory structure under data_dir is:

data_dir/
  data/shard_0/ ... shard_N/      (shared Bitcask per shard)
  dedicated/shard_0/ ... shard_N/ (for future promoted collections)
  blob/shard_0/ ... shard_N/      (large-value side-channel blobs)
  prob/shard_0/ ... shard_N/      (probabilistic structure files)
  waraft/                         (WARaft consensus segment logs)
  registry/                        (merge scheduler state)
  hints/                           (hot cache warm-up files)

Usage

Call ensure_layout!/2 during application startup to create all placeholder directories. Then use shard_data_path/2 wherever a per-shard Bitcask path is needed.

Summary

Functions

blob_shard_path(data_dir, shard_index)

Returns the canonical large-value blob path for a given shard index.

ensure_layout!(data_dir, shard_count \\ 4)

Creates the full directory layout under data_dir.

root_from_shard_path(shard_data_path)

Returns the FerricStore root data directory for a shard Bitcask path.

shard_data_path(data_dir, shard_index)

Returns the canonical Bitcask data path for a given shard index.

top_level_dirs()

Returns the list of top-level subdirectory names that make up the layout.

Functions

blob_shard_path(data_dir, shard_index)

@spec blob_shard_path(binary(), non_neg_integer()) :: binary()

Returns the canonical large-value blob path for a given shard index.

This is intentionally outside the shared Bitcask shard directory. Large blob side-channel files must be copied and cleaned as shard-owned storage during cluster setup/join, but should not be scanned as normal Bitcask records.

ensure_layout!(data_dir, shard_count \\ 4)

@spec ensure_layout!(binary(), pos_integer()) :: :ok

Creates the full directory layout under data_dir.

For each of data/, dedicated/, blob/, and prob/, per-shard subdirectories shard_0 through shard_{N-1} are created. registry/ and hints/ are top-level directories without per-shard subdirectories.

This function is idempotent -- calling it multiple times is safe.

Parameters

data_dir -- the root data directory
shard_count -- number of shards (default: 4)

Returns

:ok

Raises

Raises on filesystem errors (e.g. permission denied).