Skip to main content

AFS_AETHER_DIR_CACHE_TTL_SECS

Deep-dive reference for:

  • AFS_AETHER_DIR_CACHE_TTL_SECS

Status​

  • active

Audience​

  • production/user

Type and Default​

  • Type: positive integer seconds.
  • Default: 30 seconds.

What It Does​

Controls how long cached directory listings (readdir / readdirplus) are kept before expiring.

In practice, this is passed into the fuse3 adapter directory cache TTL (CacheTtlConfig.dir), which backs the in-process directory entry cache.

Higher values:

  • fewer backend directory-list calls,
  • better directory traversal performance,
  • more chance of briefly stale listings.

Lower values:

  • fresher listings,
  • more backend work for repeated directory reads.

Input Surfaces​

  • Env: AFS_AETHER_DIR_CACHE_TTL_SECS=30
  • Config file (aether.toml): dir_cache_ttl_secs = 30
  • CLI override: aether mount --dir-cache-ttl 30

Resolution and Override Order​

  1. Built-in default (30s)
  2. aether.toml (dir_cache_ttl_secs)
  3. Env (AFS_AETHER_DIR_CACHE_TTL_SECS)
  4. CLI (--dir-cache-ttl)

Validation and Errors​

  • Must be greater than 0.
  • Invalid values fail config load with source-specific errors:
    • env: AFS_AETHER_DIR_CACHE_TTL_SECS
    • file: <path>:dir_cache_ttl_secs
    • CLI override path: dir_cache_ttl

Runtime Behavior Notes​

  • Applied when mount options are built and passed to the fuse3 adapter cache config.
  • Directory cache entries are also invalidated on many local mutations/invalidation events, so TTL is an upper bound, not a guaranteed retention time.

Tuning Guidance​

  • General-purpose default: 30s.
  • High-churn trees (freshness prioritized): 3-10s.
  • Read-heavy mostly-static trees (throughput prioritized): 30-120s.

Quick Examples​

  • Env:
    • AFS_AETHER_DIR_CACHE_TTL_SECS=10 aether mount --session-id s1 --mount-dir /mnt/s1
  • Config file:
    • dir_cache_ttl_secs = 45
  • CLI one-off:
    • aether mount --dir-cache-ttl 15 --session-id s1 --mount-dir /mnt/s1

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/apply_env.rs
  • packages/aether/src/config/types/config_resolution.rs
  • packages/aether/src/mount/mount_main.rs
  • packages/afs-fuse3/src/adapter/state/adapter_state.rs
  • packages/afs-fuse3/src/adapter/ops/directory/read_ops.rs
  • packages/afs-fuse3/src/adapter/ops/directory/mutating_ops.rs