Skip to main content

AFS_AETHER_ENABLE_RANGE_CACHE

Deep-dive reference for:

  • AFS_AETHER_ENABLE_RANGE_CACHE

Status​

  • active

Audience​

  • production/user

Type and Default​

  • Type: boolean.
  • Default: true.

Accepted truthy values:

  • true, 1, yes, y, on

Accepted falsey values:

  • false, 0, no, n, off

What It Does​

Controls whether LocalEngine attempts cache-index-backed range assembly on the read path before normal blob reads.

When enabled (true):

  • read_impl tries read_via_cache(...) first.
  • If a full requested range can be assembled from cache-index ranges and local blobs, that read is served from this path.
  • If coverage is partial/missing, it falls back to normal blob/remote logic.

When disabled (false):

  • read_via_cache(...) is skipped entirely.
  • Reads go straight to normal blob reads (and remote fallback when needed).

Input Surfaces​

  • Env: AFS_AETHER_ENABLE_RANGE_CACHE=true|false
  • Config file (aether.toml): enable_range_cache = true|false

There is currently no dedicated aether mount CLI flag for this toggle.

Resolution and Override Order​

  1. Built-in default (true)
  2. aether.toml (enable_range_cache)
  3. Env (AFS_AETHER_ENABLE_RANGE_CACHE)
  4. Internal/programmatic override layer (ConfigOverrides.enable_range_cache) when set by caller code

What It Does Not Control​

  • Does not disable metadata/lookup/dir TTL caches.
  • Does not disable local blob reads.
  • Does not disable remote range fallback behavior.

It only gates the extra cache-index range-read attempt in LocalEngine.

Reload Semantics​

  • Config reload can detect changes to this value.
  • Current mount path does not hot-switch this safely; logs state that restart is required for new read behavior to apply.

Tuning Guidance​

  • Keep true for typical production usage; it can reduce read work when cache-index ranges are available.
  • Use false for troubleshooting/comparison runs when you want to bypass cache-index range assembly.

Quick Examples​

  • Disable for one run:
    • AFS_AETHER_ENABLE_RANGE_CACHE=false aether mount --session-id s1 --mount-dir /mnt/s1
  • Persist in config:
    • enable_range_cache = false

Primary Implementation Sources​

  • packages/aether/src/config/env/env_keys.rs
  • packages/aether/src/config/types/apply_env.rs
  • packages/aether/src/config/types/file_config_loader.rs
  • packages/aether/src/config/types/config_resolution.rs
  • packages/aether/src/engine/local/read.rs
  • packages/aether/src/mount/mount_main.rs
  • packages/aether/src/config/reload.rs