Skip to main content

AFS_AETHER_LOOKUP_TTL_SECS

Deep-dive reference for:

  • AFS_AETHER_LOOKUP_TTL_SECS

Status​

  • active

Audience​

  • production/user

Type and Default​

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

What It Does​

Controls the default metadata/lookup TTL used by Aether for positive inode/path cache entries.

This value controls how long metadata can be reused before Aether revalidates from the backend path.

Important separation:

  • AFS_AETHER_LOOKUP_TTL_SECS is for positive metadata lookups/getattr.
  • AFS_AETHER_NEGATIVE_LOOKUP_TTL_SECS is for ENOENT caching.
  • AFS_AETHER_DIR_CACHE_TTL_SECS is for directory listing cache TTL.

Where It Is Applied​

  • Config parsing/resolution populates Config.lookup_ttl.
  • Mount startup wires it into:
    • InodeTable::new(options.lookup_ttl) (default inode metadata cache TTL),
    • LookupConfig::new(options.lookup_ttl) (lookup/getattr default TTL fallback),
    • CacheTtlConfig.metadata (fuse adapter metadata/file cache TTL).
  • LookupService and GetattrService use it when engine responses do not provide explicit TTLs.
  • Local engine metadata update paths also upsert inode metadata using this TTL.

Input Surfaces​

  • Env: AFS_AETHER_LOOKUP_TTL_SECS=<seconds>
  • Config file (aether.toml): lookup_ttl_secs = <seconds>
  • CLI override: aether mount --metadata-ttl <seconds>

Resolution and Override Order​

  1. Built-in default (60s)
  2. aether.toml (lookup_ttl_secs)
  3. Env (AFS_AETHER_LOOKUP_TTL_SECS)
  4. CLI (--metadata-ttl)

Validation and Errors​

  • Must parse as integer seconds.
  • Must be greater than 0.
  • Invalid values fail config load with source-specific names, for example:
    • env: AFS_AETHER_LOOKUP_TTL_SECS
    • file: <path>:lookup_ttl_secs
    • CLI override path: lookup_ttl

Runtime Behavior Notes​

  • This is a cache freshness/performance tradeoff knob:
    • higher TTL: fewer metadata round-trips, more stale-window risk,
    • lower TTL: fresher metadata, more backend metadata lookups.
  • Running mounts initialize TTL behavior at startup from resolved config; set this before launching mount for deterministic behavior.

Tuning Guidance​

  • General-purpose default: 60s.
  • Faster metadata freshness for high-churn trees: 3-15s.
  • Read-heavy mostly-static trees: 60-300s.

Quick Examples​

  • Env:
    • AFS_AETHER_LOOKUP_TTL_SECS=30 aether mount --session-id s1 --mount-dir /mnt/s1
  • Config file:
    • lookup_ttl_secs = 120
  • CLI one-off:
    • aether mount --metadata-ttl 20 --session-id s1 --mount-dir /mnt/s1

Primary Implementation Sources​

  • packages/aether/src/config/types/model_defaults.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-cli/src/cli/args/cli_option_args.rs
  • packages/aether-cli/src/cli/args/cli_root_commands.rs
  • packages/aether/src/mount/mount_main.rs
  • packages/aether/src/runtime/services/lookup.rs
  • packages/aether/src/runtime/services/getattr.rs
  • packages/aether/src/engine/local/metadata.rs
  • packages/afs-fuse3/src/adapter/state/adapter_state.rs