fix(object-data-cache): make memory container-aware and bound cache config (#4655)

* fix(object-data-cache): bound cache config and make memory container-aware

Harden the object data cache configuration path so a single bad input
degrades to the disabled adapter instead of OOM-killing pods, panicking
at boot, or silently mis-sizing the cache (backlog#1110/1113/1114/1115/
1127/1140/1130).

- ODC-05: resolve capacity and the fill gate from the effective
  (container-aware) memory. Prefer sysinfo cgroup_limits() and use
  min(host, cgroup) as the total plus cgroup-derived availability, falling
  back to host values when no cgroup limit constrains. Log the resolved
  capacity and its basis once at startup.
- ODC-08: cap ttl/time_to_idle at 30 days in validate() so an unbounded
  Duration can no longer trip moka's ~1000-year builder assertion.
- ODC-09: drop the max_entry_bytes floor from the derived-capacity clamp so
  MAX_ENTRY_BYTES can no longer inflate total capacity above the safety
  clamp; reject an entry larger than the resolved capacity instead.
- ODC-10: require an explicit max_bytes to clear max_entry_bytes plus the
  weigher overhead so a fillable-but-unretainable cache is rejected.
- ODC-22: reject max_entry_bytes at/above the u32 weigher boundary.
- ODC-35: warn (not reject) when time_to_idle exceeds ttl and document the
  min(ttl, time_to_idle) expiry interaction.
- ODC-25: give numeric env overrides two-valued semantics via a new
  rustfs_utils::get_env_parse_outcome; a malformed value now disables the
  whole cache with one aggregated warning instead of silently keeping
  defaults.

Co-Authored-By: heihutu <heihutu@gmail.com>

* fix(object-data-cache): require identity_keys_max of at least 2

The identity index admits a new key by evicting the oldest one, so a
budget of 1 evicts the previous key on every fill and can never hold two
live keys of one object at once — a versioned bucket alternating two
versions then hits a permanent 0% hit rate.

Reject the degenerate value at config validation time, where the adapter
turns it into a disabled cache with a warning, since the bounded-eviction
policy cannot rescue it at runtime.

Handed off from the identity-index batch (backlog#1128), which changed the
overflow policy but could not touch validate().

Refs: backlog#1115, backlog#1128

Co-Authored-By: heihutu <heihutu@gmail.com>

* fix(object-data-cache): let a zero free-memory floor opt out of the gate

Making the memory gate container-aware turned it live in CI: the runners
are Kubernetes pods, so the gate now reads the pod's cgroup free memory,
finds it below the 20% floor, and refuses the fill. Tests that assert a
fill succeeds then failed on CI while passing on a developer host, which
has no cgroup and falls back to host memory.

The gate is behaving correctly — the tests were the ones depending on a
live memory reading. Treat min_free_memory_percent = 0 as a deliberate
opt-out rather than an invalid value: allows_fill returns early before it
touches any snapshot, so admission becomes independent of where the suite
runs. Operators gain the same escape hatch.

Every test that requires a fill to succeed now sets the floor to 0. The
tests that exercise the gate keep it enabled via memory_gated_config, so
the ODC-05 coverage they provide is preserved rather than short-circuited.

Refs: backlog#1110

Co-Authored-By: heihutu <heihutu@gmail.com>

* fix(object-data-cache): opt the usecase fill tests out of the memory gate

The previous commit exempted the fill-dependent tests it could find, but
missed the six adapters built inside object_usecase.rs. Fixing the first
batch moved nextest's fail-fast point forward and CI surfaced them:
build_get_object_body_with_cache_materializes_once_and_hits_later and
..._uses_cached_body_without_reader_preread both assert a fill lands, and
both ran with the default 20% free-memory floor.

Set the floor to 0 on all six, matching the sibling test modules. Verified
by pinning the gate's snapshot to 0% available — harsher than any CI pod —
and confirming these tests still pass, which shows the exemption path never
reads memory at all.

An exhaustive sweep over every fill-enabled ObjectDataCacheConfig in the
tree now shows no remaining site: the only unexempted ones are
fill_enabled()'s matches! arm and two adapter tests that assert the adapter
is disabled and therefore never fill.

Refs: backlog#1110

Co-Authored-By: heihutu <heihutu@gmail.com>

---------

Co-authored-by: heihutu <heihutu@gmail.com>

crates/object-data-cache/src/cache.rs

@@ -348,6 +348,9 @@ mod tests {
         let config = ObjectDataCacheConfig {
             mode: ObjectDataCacheMode::FillBufferedOnly,
             max_bytes: 8_388_608,
+            // Fill must not depend on the live memory reading, which differs
+            // between a developer host and a CI container.
+            min_free_memory_percent: 0,
             ..ObjectDataCacheConfig::default()
         };
         ObjectDataCache::new(config).expect("fill-enabled cache config should initialize")

crates/object-data-cache/src/config.rs

@@ -13,12 +13,32 @@
 // limitations under the License.
 
 use crate::error::ObjectDataCacheConfigError;
+use crate::memory::{MemoryBasis, resolve_effective_memory};
+use std::sync::Once;
 use std::time::Duration;
-use sysinfo::System;
 
 const DEFAULT_DERIVED_MAX_MEMORY_PERCENT_CAP: u64 = 10;
 const DEFAULT_DERIVED_MAX_BYTES_CAP: u64 = 64 * 1024 * 1024 * 1024;
 
+/// Upper bound (seconds) for `ttl` / `time_to_idle`. Kept far below moka's
+/// ~1000-year builder assertion while remaining a sane operational cap so a
+/// bad env var degrades to the disabled adapter instead of panicking at boot.
+const MAX_DURATION_SECS: u64 = 30 * 24 * 60 * 60;
+
+/// Overhead reserved on top of a cached body when validating an explicit
+/// `max_bytes`. moka's weigher charges key bytes + a small per-entry overhead
+/// on top of the body, so `max_bytes` must clear `max_entry_bytes` by at least
+/// this margin for the entry to ever be retained.
+const ENTRY_WEIGHT_OVERHEAD_BYTES: u64 = 4096;
+
+/// Upper bound for `max_entry_bytes`. moka weighers return `u32`, so an entry
+/// above ~4 GiB would be under-weighted and bypass capacity accounting; stay
+/// below `u32::MAX` with room for the weigher overhead.
+const MAX_ENTRY_BYTES_LIMIT: u64 = u32::MAX as u64 - ENTRY_WEIGHT_OVERHEAD_BYTES;
+
+/// Guards the one-shot startup log of the resolved cache capacity.
+static RESOLVED_CAPACITY_LOGGED: Once = Once::new();
+
 /// Runtime mode for the object data cache.
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
 pub enum ObjectDataCacheMode {
@@ -56,16 +76,25 @@ pub struct ObjectDataCacheConfig {
     /// Maximum cacheable entry size in bytes.
     pub max_entry_bytes: u64,
     /// Time-to-live for a cache entry.
+    ///
+    /// moka expires an entry at `min(ttl, time_to_idle-since-last-access)`, so
+    /// a `time_to_idle` larger than `ttl` never takes effect.
     pub ttl: Duration,
     /// Time-to-idle for a cache entry.
+    ///
+    /// See [`ttl`](Self::ttl): expiration uses `min(ttl, time_to_idle)`, so
+    /// setting `time_to_idle` above `ttl` is inert.
     pub time_to_idle: Duration,
-    /// Minimum free memory percent before fill is paused.
+    /// Minimum free memory percent before fill is paused. Zero disables the
+    /// memory gate entirely, which makes fill admission independent of the
+    /// host's or container's live memory reading.
     pub min_free_memory_percent: u8,
     /// Fill concurrency multiplier applied to CPU count.
     pub fill_concurrency_per_cpu: u16,
     /// Absolute fill concurrency cap.
     pub fill_concurrency_max: u16,
-    /// Conservative cap for keys attached to one object identity.
+    /// Conservative cap for keys attached to one object identity. Must be at
+    /// least 2: the index admits a new key by evicting the oldest one.
     pub identity_keys_max: u16,
 }
 
@@ -111,16 +140,27 @@ impl ObjectDataCacheConfig {
             return Ok(self.max_bytes);
         }
 
-        let mut system = System::new();
-        system.refresh_memory();
-        let total_memory = system.total_memory();
+        // Resolve capacity from the effective (container-aware) total memory so
+        // a pod with a cgroup limit far below the node RAM does not size the
+        // cache to the node.
+        let effective = resolve_effective_memory();
+        let total_memory = effective.total_bytes;
         let derived = total_memory.saturating_mul(u64::from(self.max_memory_percent)) / 100;
-        let resolved = clamp_derived_max_bytes(derived, total_memory, self.max_entry_bytes);
+        let resolved = clamp_derived_max_bytes(derived, total_memory);
 
         if resolved == 0 {
             return Err(ObjectDataCacheConfigError::ZeroResolvedMaxBytes);
         }
 
+        // The derived capacity is no longer floored by `max_entry_bytes` (that
+        // used to silently inflate the cache above the safety clamp). If a
+        // single entry cannot fit, reject rather than inflate.
+        if self.max_entry_bytes > resolved {
+            return Err(ObjectDataCacheConfigError::MaxEntryBytesExceedsCapacity);
+        }
+
+        log_resolved_capacity_once(resolved, total_memory, effective.basis);
+
         Ok(resolved)
     }
 
@@ -134,15 +174,46 @@ impl ObjectDataCacheConfig {
             return Err(ObjectDataCacheConfigError::ZeroMaxEntryBytes);
         }
 
+        if self.max_entry_bytes > MAX_ENTRY_BYTES_LIMIT {
+            return Err(ObjectDataCacheConfigError::MaxEntryBytesTooLarge);
+        }
+
+        // An explicit capacity must leave room for a full entry plus the
+        // weigher overhead, otherwise moka can never retain the entry while
+        // fills still report success.
+        if self.max_bytes > 0 && self.max_bytes < self.max_entry_bytes.saturating_add(ENTRY_WEIGHT_OVERHEAD_BYTES) {
+            return Err(ObjectDataCacheConfigError::MaxEntryBytesExceedsMaxBytes);
+        }
+
         if self.ttl.is_zero() {
             return Err(ObjectDataCacheConfigError::ZeroTimeToLiveSecs);
         }
 
+        if self.ttl.as_secs() > MAX_DURATION_SECS {
+            return Err(ObjectDataCacheConfigError::TimeToLiveTooLarge);
+        }
+
         if self.time_to_idle.is_zero() {
             return Err(ObjectDataCacheConfigError::ZeroTimeToIdleSecs);
         }
 
-        if self.min_free_memory_percent == 0 || self.min_free_memory_percent > 100 {
+        if self.time_to_idle.as_secs() > MAX_DURATION_SECS {
+            return Err(ObjectDataCacheConfigError::TimeToIdleTooLarge);
+        }
+
+        // moka expires at min(ttl, time_to_idle); a larger time_to_idle is
+        // inert. Warn instead of rejecting so a benign misconfiguration still
+        // starts the cache.
+        if self.time_to_idle > self.ttl {
+            tracing::warn!(
+                time_to_idle_secs = self.time_to_idle.as_secs(),
+                ttl_secs = self.ttl.as_secs(),
+                "object data cache time_to_idle exceeds ttl; moka expires at min(ttl, time_to_idle) so the larger time_to_idle has no effect"
+            );
+        }
+
+        // Zero is a deliberate opt-out of the memory gate, not an invalid value.
+        if self.min_free_memory_percent > 100 {
             return Err(ObjectDataCacheConfigError::InvalidMinFreeMemoryPercent);
         }
 
@@ -162,15 +233,33 @@ impl ObjectDataCacheConfig {
             return Err(ObjectDataCacheConfigError::ZeroIdentityKeysMax);
         }
 
+        // The identity index evicts the oldest key to admit a new one, so a
+        // budget of 1 evicts the previous key on every fill and can never hold
+        // two live keys of one object at once.
+        if self.identity_keys_max < 2 {
+            return Err(ObjectDataCacheConfigError::IdentityKeysMaxTooSmall);
+        }
+
         Ok(())
     }
 }
 
-fn clamp_derived_max_bytes(derived: u64, total_memory: u64, max_entry_bytes: u64) -> u64 {
+fn clamp_derived_max_bytes(derived: u64, total_memory: u64) -> u64 {
     let percent_cap = total_memory.saturating_mul(DEFAULT_DERIVED_MAX_MEMORY_PERCENT_CAP) / 100;
-    let safe_cap = percent_cap.min(DEFAULT_DERIVED_MAX_BYTES_CAP).max(max_entry_bytes);
+    let safe_cap = percent_cap.min(DEFAULT_DERIVED_MAX_BYTES_CAP);
 
-    derived.min(safe_cap).max(max_entry_bytes)
+    derived.min(safe_cap)
+}
+
+fn log_resolved_capacity_once(resolved_max_bytes: u64, effective_total_bytes: u64, basis: MemoryBasis) {
+    RESOLVED_CAPACITY_LOGGED.call_once(|| {
+        tracing::info!(
+            resolved_max_bytes,
+            effective_total_bytes,
+            basis = basis.as_str(),
+            "object data cache resolved capacity"
+        );
+    });
 }
 
 #[cfg(test)]
@@ -260,6 +349,54 @@ mod tests {
         assert_eq!(err, ObjectDataCacheConfigError::FillConcurrencyMaxTooSmall);
     }
 
+    #[test]
+    fn validate_accepts_zero_min_free_memory_percent_as_gate_opt_out() {
+        let config = ObjectDataCacheConfig {
+            min_free_memory_percent: 0,
+            ..ObjectDataCacheConfig::default()
+        };
+
+        assert!(config.validate().is_ok());
+    }
+
+    #[test]
+    fn validate_rejects_min_free_memory_percent_above_100() {
+        let config = ObjectDataCacheConfig {
+            min_free_memory_percent: 101,
+            ..ObjectDataCacheConfig::default()
+        };
+
+        let err = config
+            .validate()
+            .expect_err("a free-memory floor above 100% is unsatisfiable");
+
+        assert_eq!(err, ObjectDataCacheConfigError::InvalidMinFreeMemoryPercent);
+    }
+
+    #[test]
+    fn validate_rejects_single_key_identity_budget() {
+        let config = ObjectDataCacheConfig {
+            identity_keys_max: 1,
+            ..ObjectDataCacheConfig::default()
+        };
+
+        let err = config
+            .validate()
+            .expect_err("a one-key identity budget evicts the previous key on every fill");
+
+        assert_eq!(err, ObjectDataCacheConfigError::IdentityKeysMaxTooSmall);
+    }
+
+    #[test]
+    fn validate_accepts_two_key_identity_budget() {
+        let config = ObjectDataCacheConfig {
+            identity_keys_max: 2,
+            ..ObjectDataCacheConfig::default()
+        };
+
+        assert!(config.validate().is_ok());
+    }
+
     #[test]
     fn validate_accepts_explicit_byte_cap() {
         let config = ObjectDataCacheConfig {
@@ -287,25 +424,129 @@ mod tests {
     }
 
     #[test]
-    fn resolved_max_bytes_is_at_least_max_entry_bytes() {
+    fn derived_capacity_is_not_inflated_by_max_entry_bytes() {
+        // 512 MiB effective memory with a tiny percent yields a small derived
+        // capacity. A large max_entry_bytes must NOT raise the total capacity
+        // (the old `.max(max_entry_bytes)` floor did exactly that).
+        let host = 512_u64 * 1024 * 1024;
+        let derived = host / 100;
+        let resolved = clamp_derived_max_bytes(derived, host);
+
+        assert_eq!(resolved, derived);
+        assert!(resolved < 1024 * 1024 * 1024);
+    }
+
+    #[test]
+    fn resolved_max_bytes_rejects_entry_larger_than_capacity() {
+        // Derived capacity is clamped to at most 64 GiB, so a 128 GiB entry cap
+        // can never fit regardless of the test host's memory.
         let config = ObjectDataCacheConfig {
             max_bytes: 0,
-            max_memory_percent: 1,
-            max_entry_bytes: 8_388_608,
+            max_memory_percent: 100,
+            max_entry_bytes: 128 * 1024 * 1024 * 1024,
             ..ObjectDataCacheConfig::default()
         };
 
-        let resolved = config.resolved_max_bytes().expect("derived capacity should stay positive");
+        let err = config
+            .resolved_max_bytes()
+            .expect_err("entry cap above the derived capacity must be rejected");
 
-        assert!(resolved >= config.max_entry_bytes);
+        assert_eq!(err, ObjectDataCacheConfigError::MaxEntryBytesExceedsCapacity);
     }
 
     #[test]
     fn derived_max_bytes_clamps_to_v3_safe_cap() {
         let one_tib = 1024_u64 * 1024 * 1024 * 1024;
         let derived = one_tib / 2;
-        let resolved = clamp_derived_max_bytes(derived, one_tib, 1_048_576);
+        let resolved = clamp_derived_max_bytes(derived, one_tib);
 
         assert_eq!(resolved, DEFAULT_DERIVED_MAX_BYTES_CAP);
     }
+
+    #[test]
+    fn validate_rejects_ttl_above_upper_bound() {
+        let config = ObjectDataCacheConfig {
+            ttl: Duration::from_secs(u64::MAX),
+            ..ObjectDataCacheConfig::default()
+        };
+
+        let err = config.validate().expect_err("ttl above the operational cap must be rejected");
+
+        assert_eq!(err, ObjectDataCacheConfigError::TimeToLiveTooLarge);
+    }
+
+    #[test]
+    fn validate_rejects_time_to_idle_above_upper_bound() {
+        let config = ObjectDataCacheConfig {
+            time_to_idle: Duration::from_secs(u64::MAX),
+            ..ObjectDataCacheConfig::default()
+        };
+
+        let err = config
+            .validate()
+            .expect_err("time-to-idle above the operational cap must be rejected");
+
+        assert_eq!(err, ObjectDataCacheConfigError::TimeToIdleTooLarge);
+    }
+
+    #[test]
+    fn validate_rejects_entry_above_weigher_limit() {
+        let config = ObjectDataCacheConfig {
+            max_entry_bytes: u32::MAX as u64,
+            ..ObjectDataCacheConfig::default()
+        };
+
+        let err = config
+            .validate()
+            .expect_err("entry size at the u32 weigher boundary must be rejected");
+
+        assert_eq!(err, ObjectDataCacheConfigError::MaxEntryBytesTooLarge);
+    }
+
+    #[test]
+    fn validate_rejects_entry_larger_than_explicit_max_bytes() {
+        let config = ObjectDataCacheConfig {
+            mode: ObjectDataCacheMode::HitOnly,
+            max_bytes: 2 * 1024 * 1024,
+            max_memory_percent: 0,
+            max_entry_bytes: 8 * 1024 * 1024,
+            ..ObjectDataCacheConfig::default()
+        };
+
+        let err = config
+            .validate()
+            .expect_err("an entry larger than max_bytes can never be retained");
+
+        assert_eq!(err, ObjectDataCacheConfigError::MaxEntryBytesExceedsMaxBytes);
+    }
+
+    #[test]
+    fn validate_rejects_entry_equal_to_explicit_max_bytes() {
+        // Equal fails because the weigher adds key bytes + per-entry overhead.
+        let config = ObjectDataCacheConfig {
+            mode: ObjectDataCacheMode::HitOnly,
+            max_bytes: 4 * 1024 * 1024,
+            max_memory_percent: 0,
+            max_entry_bytes: 4 * 1024 * 1024,
+            ..ObjectDataCacheConfig::default()
+        };
+
+        let err = config
+            .validate()
+            .expect_err("max_entry_bytes must clear max_bytes by the weigher overhead");
+
+        assert_eq!(err, ObjectDataCacheConfigError::MaxEntryBytesExceedsMaxBytes);
+    }
+
+    #[test]
+    fn validate_accepts_time_to_idle_greater_than_ttl() {
+        // A time_to_idle above ttl is inert (warned, not rejected).
+        let config = ObjectDataCacheConfig {
+            ttl: Duration::from_secs(30),
+            time_to_idle: Duration::from_secs(60),
+            ..ObjectDataCacheConfig::default()
+        };
+
+        assert!(config.validate().is_ok());
+    }
 }

crates/object-data-cache/src/error.rs

@@ -25,14 +25,34 @@ pub enum ObjectDataCacheConfigError {
     #[error("object data cache max_entry_bytes must be greater than 0")]
     ZeroMaxEntryBytes,
 
+    /// The configured entry size exceeds the moka weigher's u32 accounting range.
+    #[error("object data cache max_entry_bytes must stay below 4 GiB so the capacity weigher does not under-count entries")]
+    MaxEntryBytesTooLarge,
+
+    /// The configured entry size cannot fit inside the explicit byte capacity.
+    #[error("object data cache max_entry_bytes plus weigher overhead must not exceed max_bytes")]
+    MaxEntryBytesExceedsMaxBytes,
+
+    /// The configured entry size exceeds the resolved (derived) cache capacity.
+    #[error("object data cache max_entry_bytes must not exceed the resolved cache capacity")]
+    MaxEntryBytesExceedsCapacity,
+
     /// The configured time-to-live cannot be zero.
     #[error("object data cache ttl_secs must be greater than 0")]
     ZeroTimeToLiveSecs,
 
+    /// The configured time-to-live exceeds the supported upper bound.
+    #[error("object data cache ttl_secs must not exceed 2592000 seconds (30 days)")]
+    TimeToLiveTooLarge,
+
     /// The configured time-to-idle cannot be zero.
     #[error("object data cache time_to_idle_secs must be greater than 0")]
     ZeroTimeToIdleSecs,
 
+    /// The configured time-to-idle exceeds the supported upper bound.
+    #[error("object data cache time_to_idle_secs must not exceed 2592000 seconds (30 days)")]
+    TimeToIdleTooLarge,
+
     /// The configured minimum free memory percentage exceeded the supported range.
     #[error("object data cache min_free_memory_percent must be in 1..=100")]
     InvalidMinFreeMemoryPercent,
@@ -53,6 +73,10 @@ pub enum ObjectDataCacheConfigError {
     #[error("object data cache identity_keys_max must be greater than 0")]
     ZeroIdentityKeysMax,
 
+    /// A single-key identity budget evicts the previous key on every fill.
+    #[error("object data cache identity_keys_max must be at least 2")]
+    IdentityKeysMaxTooSmall,
+
     /// Failed to resolve a non-zero cache capacity from the runtime environment.
     #[error("object data cache could not resolve a positive max capacity")]
     ZeroResolvedMaxBytes,

crates/object-data-cache/src/memory.rs

@@ -22,6 +22,73 @@ use sysinfo::System;
 
 const DEFAULT_REFRESH_INTERVAL: Duration = Duration::from_secs(5);
 
+/// Source used to resolve the effective memory limits.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub(crate) enum MemoryBasis {
+    /// Limits come from host memory reported by sysinfo.
+    Host,
+    /// Limits come from a constraining cgroup (container) memory limit.
+    Cgroup,
+}
+
+impl MemoryBasis {
+    pub(crate) const fn as_str(self) -> &'static str {
+        match self {
+            Self::Host => "host",
+            Self::Cgroup => "cgroup",
+        }
+    }
+}
+
+/// Effective memory totals after reconciling host memory with cgroup limits.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub(crate) struct EffectiveMemory {
+    /// Effective total memory in bytes.
+    pub(crate) total_bytes: u64,
+    /// Effective available memory in bytes.
+    pub(crate) available_bytes: u64,
+    /// Whether the limits are host- or cgroup-derived.
+    pub(crate) basis: MemoryBasis,
+}
+
+/// Reconciles host memory with an optional cgroup limit.
+///
+/// `cgroup` carries `(total_memory, free_memory)` as reported for the cgroup
+/// hierarchy (sysinfo already caps `total_memory` at the host total). A cgroup
+/// only counts when it actually constrains below the host, so an unlimited
+/// cgroup transparently falls back to host values.
+pub(crate) fn select_effective_memory(host_total: u64, host_available: u64, cgroup: Option<(u64, u64)>) -> EffectiveMemory {
+    match cgroup {
+        Some((cgroup_total, cgroup_free)) if cgroup_total > 0 && cgroup_total < host_total => EffectiveMemory {
+            total_bytes: cgroup_total,
+            available_bytes: cgroup_free.min(cgroup_total),
+            basis: MemoryBasis::Cgroup,
+        },
+        _ => EffectiveMemory {
+            total_bytes: host_total,
+            available_bytes: host_available,
+            basis: MemoryBasis::Host,
+        },
+    }
+}
+
+/// Resolves the effective memory from an already-refreshed system handle.
+///
+/// `cgroup_limits()` is computed fresh on each call and is only implemented on
+/// Linux (it returns `None` elsewhere), so non-Linux hosts always use host
+/// values.
+pub(crate) fn effective_memory_from_system(system: &System) -> EffectiveMemory {
+    let cgroup = system.cgroup_limits().map(|limits| (limits.total_memory, limits.free_memory));
+    select_effective_memory(system.total_memory(), system.available_memory(), cgroup)
+}
+
+/// Resolves the effective memory using a fresh, memory-refreshed system handle.
+pub(crate) fn resolve_effective_memory() -> EffectiveMemory {
+    let mut system = System::new();
+    system.refresh_memory();
+    effective_memory_from_system(&system)
+}
+
 /// Immutable memory snapshot used by the cache fill gate.
 #[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
 pub struct ObjectDataCacheMemorySnapshot {
@@ -62,9 +129,10 @@ impl ObjectDataCacheMemoryGate {
     pub fn new(config: &ObjectDataCacheConfig, stats: Arc<ObjectDataCacheStats>) -> Self {
         let mut system = System::new();
         system.refresh_memory();
+        let effective = effective_memory_from_system(&system);
         let snapshot = ObjectDataCacheMemorySnapshot {
-            total_bytes: system.total_memory(),
-            available_bytes: system.available_memory(),
+            total_bytes: effective.total_bytes,
+            available_bytes: effective.available_bytes,
         };
 
         Self {
@@ -106,9 +174,10 @@ impl ObjectDataCacheMemoryGate {
 
         let mut system = lock_or_recover(&self.system);
         system.refresh_memory();
+        let effective = effective_memory_from_system(&system);
         let snapshot = ObjectDataCacheMemorySnapshot {
-            total_bytes: system.total_memory(),
-            available_bytes: system.available_memory(),
+            total_bytes: effective.total_bytes,
+            available_bytes: effective.available_bytes,
         };
 
         self.snapshot_total_bytes.store(snapshot.total_bytes, Ordering::Relaxed);
@@ -119,6 +188,12 @@ impl ObjectDataCacheMemoryGate {
 
     /// Returns true when the fill path may proceed under current memory pressure.
     pub fn allows_fill(&self, required_bytes: u64) -> bool {
+        // A zero floor opts out of the gate, so fill admission never depends on
+        // a live memory reading — which differs between a host and a container.
+        if self.min_free_memory_percent == 0 {
+            return true;
+        }
+
         self.refresh_if_stale();
         let snapshot = self.snapshot();
         if snapshot.total_bytes == 0 {
@@ -152,11 +227,65 @@ fn lock_or_recover<T>(mutex: &Mutex<T>) -> std::sync::MutexGuard<'_, T> {
 
 #[cfg(test)]
 mod tests {
-    use super::{ObjectDataCacheMemoryGate, ObjectDataCacheMemorySnapshot};
+    use super::{MemoryBasis, ObjectDataCacheMemoryGate, ObjectDataCacheMemorySnapshot, select_effective_memory};
     use crate::config::ObjectDataCacheConfig;
     use crate::stats::ObjectDataCacheStats;
     use std::sync::Arc;
 
+    const GIB: u64 = 1024 * 1024 * 1024;
+
+    #[test]
+    fn select_effective_memory_prefers_constraining_cgroup() {
+        let effective = select_effective_memory(64 * GIB, 40 * GIB, Some((2 * GIB, GIB)));
+
+        assert_eq!(effective.basis, MemoryBasis::Cgroup);
+        assert_eq!(effective.total_bytes, 2 * GIB);
+        assert_eq!(effective.available_bytes, GIB);
+    }
+
+    #[test]
+    fn select_effective_memory_ignores_non_constraining_cgroup() {
+        // A cgroup total equal to (or above) the host total means no real limit.
+        let effective = select_effective_memory(64 * GIB, 40 * GIB, Some((64 * GIB, 10 * GIB)));
+
+        assert_eq!(effective.basis, MemoryBasis::Host);
+        assert_eq!(effective.total_bytes, 64 * GIB);
+        assert_eq!(effective.available_bytes, 40 * GIB);
+    }
+
+    #[test]
+    fn select_effective_memory_falls_back_to_host_without_cgroup() {
+        let effective = select_effective_memory(8 * GIB, 4 * GIB, None);
+
+        assert_eq!(effective.basis, MemoryBasis::Host);
+        assert_eq!(effective.total_bytes, 8 * GIB);
+        assert_eq!(effective.available_bytes, 4 * GIB);
+    }
+
+    #[test]
+    fn select_effective_memory_caps_available_at_total() {
+        let effective = select_effective_memory(64 * GIB, 40 * GIB, Some((2 * GIB, 3 * GIB)));
+
+        assert_eq!(effective.total_bytes, 2 * GIB);
+        assert_eq!(effective.available_bytes, 2 * GIB);
+    }
+
+    #[test]
+    fn gate_pauses_fill_when_container_memory_is_low() {
+        // Simulate a pod-sized snapshot (256 MiB total, 16 MiB free): below the
+        // default 20% free-memory floor, so fills must pause even though a node
+        // would have plenty of headroom.
+        let stats = Arc::new(ObjectDataCacheStats::default());
+        let gate = ObjectDataCacheMemoryGate::new(&ObjectDataCacheConfig::default(), Arc::clone(&stats));
+        gate.set_test_snapshot(Some(ObjectDataCacheMemorySnapshot {
+            total_bytes: 256 * 1024 * 1024,
+            available_bytes: 16 * 1024 * 1024,
+        }));
+
+        assert!(!gate.allows_fill(1024));
+        assert_eq!(stats.snapshot().memory_pressure_events, 1);
+    }
+
     #[test]
     fn allows_fill_when_memory_snapshot_has_headroom() {
         let stats = Arc::new(ObjectDataCacheStats::default());
@@ -169,6 +298,27 @@ mod tests {
         assert!(gate.allows_fill(100));
     }
 
+    #[test]
+    fn zero_min_free_percent_disables_the_gate() {
+        // A pod-sized snapshot far below any floor: the gate is opted out, so
+        // fill admission stays independent of the live memory reading.
+        let stats = Arc::new(ObjectDataCacheStats::default());
+        let gate = ObjectDataCacheMemoryGate::new(
+            &ObjectDataCacheConfig {
+                min_free_memory_percent: 0,
+                ..ObjectDataCacheConfig::default()
+            },
+            Arc::clone(&stats),
+        );
+        gate.set_test_snapshot(Some(ObjectDataCacheMemorySnapshot {
+            total_bytes: 1_000,
+            available_bytes: 1,
+        }));
+
+        assert!(gate.allows_fill(512));
+        assert_eq!(stats.snapshot().memory_pressure_events, 0);
+    }
+
     #[test]
     fn blocks_fill_under_memory_pressure() {
         let stats = Arc::new(ObjectDataCacheStats::default());

crates/object-data-cache/src/moka_backend.rs

@@ -275,6 +275,9 @@ mod tests {
     use std::sync::Arc;
     use std::time::Duration;
 
+    /// Fills here must succeed regardless of the live memory reading, which
+    /// differs between a developer host and a CI container, so the gate is
+    /// opted out of. Tests that exercise the gate re-enable it explicitly.
     fn enabled_config() -> ObjectDataCacheConfig {
         ObjectDataCacheConfig {
             mode: ObjectDataCacheMode::FillMaterializeEnabled,
@@ -283,13 +286,20 @@ mod tests {
             max_entry_bytes: 1_048_576,
             ttl: Duration::from_millis(100),
             time_to_idle: Duration::from_millis(100),
-            min_free_memory_percent: 20,
+            min_free_memory_percent: 0,
             fill_concurrency_per_cpu: 1,
             fill_concurrency_max: 32,
             identity_keys_max: 16,
         }
     }
 
+    fn memory_gated_config() -> ObjectDataCacheConfig {
+        ObjectDataCacheConfig {
+            min_free_memory_percent: 20,
+            ..enabled_config()
+        }
+    }
+
     fn cacheable_plan(object: &str, etag: &str) -> ObjectDataCacheGetPlan {
         ObjectDataCacheGetPlan::Cacheable {
             key: ObjectDataCacheKey::new("bucket", object, None, etag, 5, ObjectDataCacheBodyVariant::FullObjectPlainV1),
@@ -394,7 +404,8 @@ mod tests {
     #[tokio::test]
     async fn moka_backend_skips_fill_under_memory_pressure() {
         let stats = Arc::new(ObjectDataCacheStats::default());
-        let backend = MokaBackend::new(&enabled_config(), Arc::clone(&stats)).expect("moka backend should build");
+        // The gate must be enabled here, otherwise allows_fill short-circuits.
+        let backend = MokaBackend::new(&memory_gated_config(), Arc::clone(&stats)).expect("moka backend should build");
         backend
             .memory_gate
             .set_test_snapshot(Some(crate::memory::ObjectDataCacheMemorySnapshot {