Skip to main content

AFS_AETHER_NEGATIVE_LOOKUP_TTL_SECS

Deep-dive reference for:

  • AFS_AETHER_NEGATIVE_LOOKUP_TTL_SECS

Status​

  • active

Type and Default​

  • Type: integer seconds (u64, must be > 0).
  • Default: 5 seconds.

What It Does​

Controls how long Aether keeps a negative lookup cached.

Negative lookup means: path metadata lookup returned ENOENT (path does not exist).

During this TTL window, repeated lookups for the same missing path can return ENOENT from Aether’s negative cache instead of re-querying backend metadata.

Runtime Flow​

  1. A path lookup misses in backend metadata (ENOENT).
  2. Aether inserts that path into negative cache.
  3. Subsequent lookups for that path hit negative cache and return ENOENT quickly.
  4. After TTL expiry, lookup probes backend again.

Where It Is Applied​

  • Parsed from env/config/CLI into Config.negative_lookup_ttl.
  • Wired into mount TTL config as CacheTtlConfig.negative.
  • Used as time_to_live for the fuse adapter’s negative_cache.

Input Surfaces​

  • Env: AFS_AETHER_NEGATIVE_LOOKUP_TTL_SECS=<seconds>
  • Config file: negative_lookup_ttl_secs = <seconds>
  • CLI override: aether mount --negative-lookup-ttl <seconds>

Validation​

  • 0 is rejected (value must be greater than zero).
  • Non-numeric values are rejected.

Behavior Notes and Safeguards​

  • Negative cache is bounded (max_capacity(50_000) entries).
  • If a path is now linked locally (for example during rename/replace windows), Aether treats a stale negative entry as invalid, drops it, and retries metadata fetch.
  • Negative cache entries are explicitly invalidated by local cache invalidation paths and by mount lifecycle reset/destroy paths.

Tuning Guidance​

  • Lower value (for example 1):
    • Faster visibility of newly-created files after prior misses.
    • More backend metadata probes.
  • Higher value (for example 15 or 30):
    • Fewer repeated backend probes for missing paths.
    • Longer stale-miss window before re-check.

Primary Implementation Sources​

  • packages/aether/src/config/types/model_defaults.rs
  • packages/aether/src/config/types/apply_env.rs
  • packages/aether/src/config/types/config_resolution.rs
  • packages/aether/src/config/types/file_config_loader.rs
  • packages/aether/src/mount/mount_main.rs
  • packages/afs-fuse3/src/adapter/state/adapter_state.rs
  • packages/afs-fuse3/src/adapter/ops/metadata.rs
  • packages/afs-fuse3/src/adapter/ops/lifecycle.rs
  • packages/afs-fuse3/src/adapter/ops/metadata/tests_lookup_getattr_setattr.rs