Skip to main content

AFS_AETHER_CACHE_DIRTY_MAX_BYTES

Deep-dive reference for:

  • AFS_AETHER_CACHE_DIRTY_MAX_BYTES

Status​

  • active

Audience​

  • production/user

Type and Default​

  • Type: integer bytes (u64).
  • Default: 0 (disabled / unlimited).

What It Does​

Sets a hard cap for dirty cache bytes.

When a write would push tracked dirty bytes above this limit, Aether rejects that write path with a cache-limit error instead of accepting more dirty data.

This is a hard quota, not a backpressure watermark.

Runtime Behavior​

  • Dirty limit check is applied when dirty entries are inserted/updated in the cache facade.
  • If projected dirty bytes exceed the configured limit, the operation returns DirtyLimitExceeded.
  • 0 disables the limit.

Current integration note:

  • Enforcement is in cache limiter/facade paths (record_range, put_range, insert_pending) when entry.dirty == true.
  • This is distinct from cache backpressure high/low thresholds; those are evaluated separately.

Input Surfaces​

  • Env: AFS_AETHER_CACHE_DIRTY_MAX_BYTES=<bytes>
  • Config file (aether.toml):
    • cache_dirty_max_bytes = <bytes>
  • Programmatic override:
    • ConfigOverrides.cache_dirty_max_bytes

No dedicated CLI flag is currently exposed for this variable.

Resolution and Override Order​

  • Defaults < aether.toml < environment < overrides.

Value Rules​

  • Must parse as unsigned integer bytes (u64).
  • Unit suffixes are not accepted (512MiB is invalid; use raw bytes).
  • 0 means unlimited (limit disabled).

Interactions and Notes​

  • AFS_AETHER_CACHE_DIRTY_MAX_BYTES is different from:
    • AFS_AETHER_CACHE_DIRTY_HIGH_WATER_BYTES
    • AFS_AETHER_CACHE_DIRTY_LOW_WATER_BYTES

High/low values control backpressure state transitions; CACHE_DIRTY_MAX_BYTES controls hard acceptance/rejection of dirty bytes.

Observability​

  • Configured limit gauge: aether_cache_dirty_max_bytes
  • Current dirty bytes gauge: aether_cache_dirty_bytes
  • Dirty-limit exceed counter exists as: aether_cache_dirty_limit_exceeded_total (currently incremented for dirty-count limit events).

Example​

export AFS_AETHER_CACHE_DIRTY_MAX_BYTES=536870912

This caps dirty cache bytes at 512 MiB. Any dirty write that would exceed that projected total is rejected by cache-limit enforcement.

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/mount/mount_main.rs
  • packages/aether/src/cache/limiter/limiter_types.rs
  • packages/aether/src/cache/moka_facade/tiered.rs
  • packages/aether/src/cache/moka_facade/facade.rs