Skip to main content

AFS_AETHER_CACHE_SHARED_ROOT

Deep-dive reference for:

  • AFS_AETHER_CACHE_SHARED_ROOT

Status​

  • active

Audience​

  • production/user

Type and Default​

  • Type: filesystem path (PathBuf) or disable token.
  • Default: <cache_dir>/shared (derived when not explicitly set).

cache_dir comes from AFS_AETHER_CACHE_DIR / aether.toml / CLI --cache-dir resolution.

What It Does​

Controls the host-wide shared blob store root used for cross-session deduplication.

When enabled, Aether hard-links finalized session blobs into:

  • <shared_root>/blobs/<hash>

so multiple sessions on the same host can reuse content without duplicating blob bytes.

Runtime Behavior​

  • Cache layout is created with CacheLayout::from_session_with_shared(..., shared_root).
  • During cache-miss finalization, Aether attempts link_blob_into_shared(hash):
    • acquires host lock at <session_content>/locks/.host.lock
    • ensures shared base dirs exist
    • creates a hard link from session blob path to shared blob path
  • Shared refcount tracking records/releases blob references across sessions.
  • If shared-link or tracker initialization fails, runtime logs warnings and continues without shared dedupe/accounting instead of failing the mount.

Shared-Store Layout​

Session-local cache remains at:

  • <cache>/<session>/content/{blobs,staging,dirty,index,shared,locks}

Host-wide shared store (this variable) is separate:

  • <shared_root>/blobs/... (hard-link targets)
  • <shared_root>/refcounts.db (shared refcount registry backend path)

Input Surfaces​

  • Env:
    • AFS_AETHER_CACHE_SHARED_ROOT=/path/to/shared-root
    • disable via: off, none, disabled, false, 0, or empty string
  • Config file (aether.toml):
    • shared_cache_root = "/path/to/shared-root"
    • disable via: shared_cache_root = "off" (or other disable tokens)
  • CLI (mount):
    • --cache-shared-root /path/to/shared-root
    • --no-cache-shared-root (explicit disable)

Resolution and Override Order​

  • Defaults < aether.toml < environment < CLI overrides.
  • If not explicitly set/disabled by file/env/CLI, loader derives:
    • shared_cache_root = <resolved cache_dir>/shared

Value Rules​

  • Value is used as a path when not a disable token.
  • Relative paths are allowed and resolve relative to process working directory.
  • Cross-filesystem hard links are not supported; if session blob path and shared root are on different filesystems, shared-linking fails and runtime falls back to non-shared behavior.

Interactions and Notes​

  • AFS_AETHER_CACHE_DIR controls the session cache base.
  • AFS_AETHER_CACHE_SHARED_ROOT controls host-wide shared blob storage.
  • Independent from cache quota/backpressure controls:
    • AFS_AETHER_CACHE_MAX_BYTES
    • AFS_AETHER_CACHE_DIRTY_MAX_BYTES
    • AFS_AETHER_CACHE_DISK_*
    • AFS_AETHER_CACHE_DIRTY_*

Observability​

  • aether cache hosts reports host totals + per-session shared usage from refcount DB.
  • Cache operations that fail shared linking/refcount updates emit warnings with shared-cache context but continue normal cache flow.

Example​

# default-on behavior (derived):
# shared root => <cache_dir>/shared

# explicit custom root
export AFS_AETHER_CACHE_SHARED_ROOT=/var/lib/aetherfs/shared-blobs

# explicit disable
export AFS_AETHER_CACHE_SHARED_ROOT=off

Primary Implementation Sources​

  • packages/aether/src/config/types/model_defaults.rs
  • packages/aether/src/config/types/file_config_loader.rs
  • packages/aether/src/config/types/config_resolution.rs
  • packages/aether/src/config/types/apply_env.rs
  • packages/aether/src/config/types/parse_helpers.rs
  • packages/aether-cli/src/cli/args/cli_option_args.rs
  • packages/aether-cli/src/cli/args/cli_root_commands.rs
  • packages/aether/src/cache/mod.rs
  • packages/aether/src/cache/shared/refcount_store.rs
  • packages/aether/src/mount/mount_main.rs
  • packages/aether/src/runtime/infra/cache_miss/cache_miss_handler.rs