use freenet_stdlib::prelude::ContractKey;
use std::collections::HashMap;
use std::time::Duration;
use tokio::time::Instant;
use super::demand::NEUTRAL_DEMAND;
use crate::ring::interest::PeerKey;
use crate::util::time_source::TimeSource;
use crate::wasm_runtime::read_total_ram_bytes;
pub const MIN_DEFAULT_HOSTING_BUDGET_BYTES: u64 = 128 * 1024 * 1024;
pub const MAX_DEFAULT_HOSTING_BUDGET_BYTES: u64 = 1024 * 1024 * 1024;
pub const LEGACY_FLAT_HOSTING_BUDGET_BYTES: u64 = 1024 * 1024 * 1024;
const DEFAULT_HOSTING_BUDGET_RAM_DIVISOR: u64 = 8;
const FALLBACK_TOTAL_RAM_BYTES: u64 = 1024 * 1024 * 1024;
pub fn default_hosting_budget_bytes() -> u64 {
let total_ram = read_total_ram_bytes()
.map(|v| v as u64)
.unwrap_or(FALLBACK_TOTAL_RAM_BYTES);
budget_for_ram(total_ram)
}
fn budget_for_ram(total_ram: u64) -> u64 {
(total_ram / DEFAULT_HOSTING_BUDGET_RAM_DIVISOR).clamp(
MIN_DEFAULT_HOSTING_BUDGET_BYTES,
MAX_DEFAULT_HOSTING_BUDGET_BYTES,
)
}
pub const DEFAULT_HOSTING_DISK_PCT: f64 = 0.5;
pub const DEFAULT_MAX_HOSTING_DISK_BYTES: u64 = 32 * 1024 * 1024 * 1024;
#[allow(dead_code)]
pub fn disk_budget_for(freenet_used: u64, available: u64, pct: f64) -> u64 {
disk_budget_for_clamped(
freenet_used,
available,
pct,
MIN_DEFAULT_HOSTING_BUDGET_BYTES,
DEFAULT_MAX_HOSTING_DISK_BYTES,
)
}
pub fn disk_budget_for_clamped(
freenet_used: u64,
available: u64,
pct: f64,
min_bytes: u64,
max_bytes: u64,
) -> u64 {
let pct = if pct.is_finite() {
pct.clamp(0.0, 1.0)
} else {
0.0
};
let basis = freenet_used.saturating_add(available);
let raw = (basis as f64) * pct;
let budget = if raw >= u64::MAX as f64 {
u64::MAX
} else {
raw as u64
};
budget.min(max_bytes).max(min_bytes)
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub(crate) struct HostingCacheStats {
pub budget_bytes: u64,
pub current_bytes: u64,
pub contract_count: u64,
pub budget_evictions_total: u64,
pub evictions_of_recently_read_total: u64,
pub evicted_unread_total: u64,
pub evicted_unread_age_secs_sum: u64,
pub oom_valve_evictions_total: u64,
pub subscribed_evictions_total: u64,
}
#[derive(Debug, Clone, Copy)]
pub(crate) struct HostingContractScore {
pub key: ContractKey,
pub keep_score: f64,
pub predicted_demand: f64,
pub size_bytes: u64,
pub read_count: u32,
pub recency_seq: u64,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum AccessType {
Get,
Put,
#[cfg_attr(not(test), allow(dead_code))]
Subscribe,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum MemoryPressure {
AtCapacity,
#[cfg_attr(not(test), allow(dead_code))]
Overflow,
}
#[derive(Debug)]
pub struct RecordAccessResult {
pub is_new: bool,
pub evicted: Vec<(ContractKey, u64)>,
pub evicted_in_use: Vec<ContractKey>,
pub evicted_in_use_teardown: Vec<EvictedInUseTeardown>,
pub observed_read_rate: Option<f64>,
}
#[derive(Debug, Clone)]
pub struct EvictedInUseTeardown {
pub key: ContractKey,
pub downstream_peers: Vec<PeerKey>,
pub local_client_count: usize,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub(crate) struct EvictedContract {
pub key: ContractKey,
pub write_generation: u64,
pub was_in_use: bool,
}
#[derive(Debug, Clone)]
pub struct HostedContract {
pub size_bytes: u64,
pub last_accessed: Instant,
pub last_access_seq: u64,
pub recency_seq: u64,
pub keep_score: f64,
pub predicted_demand: f64,
pub read_count: u32,
pub inserted_at: Instant,
pub seeded_this_run: bool,
pub access_type: AccessType,
pub local_client_access: bool,
pub local_client_last_access: Option<Instant>,
pub write_generation: u64,
pub abandoned_at: Option<Instant>,
}
pub struct HostingCache<T: TimeSource> {
budget_bytes: u64,
current_bytes: u64,
contracts: HashMap<ContractKey, HostedContract>,
access_seq: u64,
eviction_floor: f64,
budget_evictions_total: u64,
evictions_of_recently_read_total: u64,
evicted_unread_total: u64,
evicted_unread_age_secs_sum: u64,
oom_valve_evictions_total: u64,
subscribed_evictions_total: u64,
time_source: T,
}
pub(crate) fn victim_order(
a: (usize, usize, u64, &ContractKey),
b: (usize, usize, u64, &ContractKey),
) -> std::cmp::Ordering {
let (a_local, a_down, a_seq, a_key) = a;
let (b_local, b_down, b_seq, b_key) = b;
a_local
.cmp(&b_local)
.then_with(|| a_down.cmp(&b_down))
.then_with(|| a_seq.cmp(&b_seq))
.then_with(|| a_key.as_bytes().cmp(b_key.as_bytes()))
}
impl<T: TimeSource> HostingCache<T> {
pub fn new(budget_bytes: u64, time_source: T) -> Self {
Self {
budget_bytes,
current_bytes: 0,
contracts: HashMap::new(),
access_seq: 0,
eviction_floor: 0.0,
budget_evictions_total: 0,
evictions_of_recently_read_total: 0,
evicted_unread_total: 0,
evicted_unread_age_secs_sum: 0,
oom_valve_evictions_total: 0,
subscribed_evictions_total: 0,
time_source,
}
}
fn next_seq(&mut self) -> u64 {
self.access_seq = self.access_seq.saturating_add(1);
self.access_seq
}
fn evict_over_budget<G>(
&mut self,
subscriber_counts: &G,
pressure: MemoryPressure,
protected: Option<&ContractKey>,
) -> Vec<EvictedContract>
where
G: Fn(&ContractKey) -> (usize, usize),
{
if self.current_bytes <= self.budget_bytes {
return Vec::new();
}
let mut candidates: Vec<(ContractKey, usize, usize, u64)> = self
.contracts
.iter()
.filter_map(|(key, entry)| {
let eligible = match pressure {
MemoryPressure::AtCapacity => protected != Some(key),
MemoryPressure::Overflow => true,
};
if !eligible {
return None;
}
let (local, downstream) = subscriber_counts(key);
Some((*key, local, downstream, entry.recency_seq))
})
.collect();
candidates.sort_by(|a, b| victim_order((a.1, a.2, a.3, &a.0), (b.1, b.2, b.3, &b.0)));
let now = self.time_source.now();
let mut evicted = Vec::new();
for (key, local, downstream, _seq) in candidates {
if self.current_bytes <= self.budget_bytes {
break; }
if let Some(entry) = self.contracts.remove(&key) {
let was_in_use = local + downstream > 0;
self.current_bytes = self.current_bytes.saturating_sub(entry.size_bytes);
self.budget_evictions_total = self.budget_evictions_total.saturating_add(1);
if was_in_use {
self.subscribed_evictions_total =
self.subscribed_evictions_total.saturating_add(1);
}
if matches!(pressure, MemoryPressure::Overflow) {
self.oom_valve_evictions_total =
self.oom_valve_evictions_total.saturating_add(1);
}
if entry.read_count >= 2 {
self.evictions_of_recently_read_total =
self.evictions_of_recently_read_total.saturating_add(1);
}
if entry.read_count == 0 && entry.seeded_this_run {
self.evicted_unread_total = self.evicted_unread_total.saturating_add(1);
let age_secs = now.saturating_duration_since(entry.inserted_at).as_secs();
self.evicted_unread_age_secs_sum =
self.evicted_unread_age_secs_sum.saturating_add(age_secs);
}
if entry.keep_score > self.eviction_floor {
self.eviction_floor = entry.keep_score;
}
evicted.push(EvictedContract {
key,
write_generation: entry.write_generation,
was_in_use,
});
}
}
if self.current_bytes > self.budget_bytes {
if let Some(protected_key) = protected {
if matches!(pressure, MemoryPressure::AtCapacity)
&& self.contracts.contains_key(protected_key)
{
tracing::warn!(
contract = %protected_key,
current_bytes = self.current_bytes,
budget_bytes = self.budget_bytes,
over_by = self.current_bytes - self.budget_bytes,
"op-scoped backstop kept an in-flight contract while still over \
budget (pathological — a genuine RAM-overflow signal would pierce \
this via Overflow)",
);
}
}
}
evicted
}
#[cfg_attr(not(test), allow(dead_code))]
pub fn record_access<G>(
&mut self,
key: ContractKey,
size_bytes: u64,
access_type: AccessType,
write_generation: u64,
subscriber_counts: G,
) -> RecordAccessResult
where
G: Fn(&ContractKey) -> (usize, usize),
{
self.record_access_with_demand(
key,
size_bytes,
access_type,
write_generation,
NEUTRAL_DEMAND,
subscriber_counts,
)
}
pub fn record_access_with_demand<G>(
&mut self,
key: ContractKey,
size_bytes: u64,
access_type: AccessType,
write_generation: u64,
predicted_demand: f64,
subscriber_counts: G,
) -> RecordAccessResult
where
G: Fn(&ContractKey) -> (usize, usize),
{
let now = self.time_source.now();
let seq = self.next_seq();
let is_read = matches!(access_type, AccessType::Get | AccessType::Subscribe);
let resets_recency = matches!(access_type, AccessType::Get | AccessType::Put);
if let Some(existing) = self.contracts.get_mut(&key) {
if existing.size_bytes != size_bytes {
self.current_bytes = self
.current_bytes
.saturating_add(size_bytes)
.saturating_sub(existing.size_bytes);
existing.size_bytes = size_bytes;
}
existing.last_accessed = now;
existing.last_access_seq = seq;
existing.access_type = access_type;
existing.write_generation = write_generation;
existing.predicted_demand = predicted_demand;
if resets_recency {
existing.recency_seq = seq;
}
let observed_read_rate = if is_read {
existing.read_count = existing.read_count.saturating_add(1);
existing.abandoned_at = None;
existing.keep_score = self.eviction_floor + predicted_demand;
Self::rate_sample(existing.read_count, now, existing.inserted_at)
} else {
None
};
RecordAccessResult {
is_new: false,
evicted: Vec::new(),
evicted_in_use: Vec::new(),
evicted_in_use_teardown: Vec::new(),
observed_read_rate,
}
} else {
let contract = HostedContract {
size_bytes,
last_accessed: now,
last_access_seq: seq,
recency_seq: if resets_recency { seq } else { 0 },
keep_score: self.eviction_floor + predicted_demand,
predicted_demand,
read_count: if is_read { 1 } else { 0 },
inserted_at: now,
seeded_this_run: true,
access_type,
local_client_access: false,
local_client_last_access: None,
write_generation,
abandoned_at: None,
};
self.contracts.insert(key, contract);
self.current_bytes = self.current_bytes.saturating_add(size_bytes);
let evicted =
self.evict_over_budget(&subscriber_counts, MemoryPressure::AtCapacity, Some(&key));
let evicted_in_use: Vec<ContractKey> = evicted
.iter()
.filter(|e| e.was_in_use)
.map(|e| e.key)
.collect();
let evicted = evicted
.into_iter()
.map(|e| (e.key, e.write_generation))
.collect();
RecordAccessResult {
is_new: true,
evicted,
evicted_in_use,
evicted_in_use_teardown: Vec::new(),
observed_read_rate: None,
}
}
}
fn rate_sample(read_count: u32, now: Instant, inserted_at: Instant) -> Option<f64> {
let residency = now.saturating_duration_since(inserted_at);
if residency.is_zero() {
return None;
}
let residency_secs = residency.as_secs_f64().max(1.0);
Some(read_count as f64 / residency_secs)
}
pub fn mark_local_client_access(&mut self, key: &ContractKey) {
if let Some(existing) = self.contracts.get_mut(key) {
existing.local_client_access = true;
existing.local_client_last_access = Some(self.time_source.now());
}
}
pub fn has_local_client_access(&self, key: &ContractKey) -> bool {
self.contracts
.get(key)
.map(|c| c.local_client_access)
.unwrap_or(false)
}
pub fn has_recent_local_client_access(
&self,
key: &ContractKey,
max_age: std::time::Duration,
) -> bool {
let now = self.time_source.now();
self.contracts
.get(key)
.and_then(|c| c.local_client_last_access)
.map(|t| now.saturating_duration_since(t) < max_age)
.unwrap_or(false)
}
pub fn touch_with_demand(&mut self, key: &ContractKey, predicted_demand: f64) -> Option<f64> {
let floor = self.eviction_floor;
let seq = self.next_seq();
let now = self.time_source.now();
if let Some(existing) = self.contracts.get_mut(key) {
existing.last_accessed = now;
existing.last_access_seq = seq;
existing.recency_seq = seq;
existing.read_count = existing.read_count.saturating_add(1);
existing.abandoned_at = None;
existing.predicted_demand = predicted_demand;
existing.keep_score = floor + predicted_demand;
Self::rate_sample(existing.read_count, now, existing.inserted_at)
} else {
None
}
}
#[cfg_attr(not(test), allow(dead_code))]
pub fn touch(&mut self, key: &ContractKey) -> Option<f64> {
let stored = self.contracts.get(key)?.predicted_demand;
self.touch_with_demand(key, stored)
}
pub fn record_abandonment(&mut self, key: &ContractKey) {
let floor = self.eviction_floor;
let is_termination = self
.contracts
.get(key)
.is_some_and(|e| e.abandoned_at.is_none());
if !is_termination {
return;
}
let seq = self.next_seq();
let now = self.time_source.now();
if let Some(existing) = self.contracts.get_mut(key) {
existing.abandoned_at = Some(now);
existing.recency_seq = seq;
existing.keep_score = floor;
}
}
pub fn refresh_entry_generation(&mut self, key: &ContractKey, new_gen: u64) {
if let Some(existing) = self.contracts.get_mut(key) {
existing.write_generation = new_gen;
}
}
pub fn contains(&self, key: &ContractKey) -> bool {
self.contracts.contains_key(key)
}
#[allow(dead_code)] pub fn get(&self, key: &ContractKey) -> Option<&HostedContract> {
self.contracts.get(key)
}
pub fn len(&self) -> usize {
self.contracts.len()
}
#[allow(dead_code)] pub fn is_empty(&self) -> bool {
self.contracts.is_empty()
}
#[allow(dead_code)] pub fn current_bytes(&self) -> u64 {
self.current_bytes
}
#[allow(dead_code)] pub fn budget_bytes(&self) -> u64 {
self.budget_bytes
}
#[cfg(test)]
pub fn set_budget_for_test(&mut self, budget_bytes: u64) {
self.budget_bytes = budget_bytes;
}
pub(crate) fn set_budget_bytes(&mut self, budget_bytes: u64) {
self.budget_bytes = budget_bytes;
}
pub fn stats(&self) -> HostingCacheStats {
HostingCacheStats {
budget_bytes: self.budget_bytes,
current_bytes: self.current_bytes,
contract_count: self.contracts.len() as u64,
budget_evictions_total: self.budget_evictions_total,
subscribed_evictions_total: self.subscribed_evictions_total,
evictions_of_recently_read_total: self.evictions_of_recently_read_total,
evicted_unread_total: self.evicted_unread_total,
evicted_unread_age_secs_sum: self.evicted_unread_age_secs_sum,
oom_valve_evictions_total: self.oom_valve_evictions_total,
}
}
pub(crate) fn eviction_ordered_scores(&self) -> Vec<HostingContractScore> {
let mut rows: Vec<HostingContractScore> = self
.contracts
.iter()
.map(|(k, v)| HostingContractScore {
key: *k,
keep_score: v.keep_score,
predicted_demand: v.predicted_demand,
size_bytes: v.size_bytes,
read_count: v.read_count,
recency_seq: v.recency_seq,
})
.collect();
rows.sort_by(|a, b| {
a.recency_seq
.cmp(&b.recency_seq)
.then_with(|| a.key.as_bytes().cmp(b.key.as_bytes()))
});
rows
}
#[cfg(test)]
pub fn keys_eviction_order(&self) -> Vec<ContractKey> {
let mut entries: Vec<_> = self
.contracts
.iter()
.map(|(k, v)| (*k, v.recency_seq))
.collect();
entries.sort_by(|a, b| {
a.1.cmp(&b.1)
.then_with(|| a.0.as_bytes().cmp(b.0.as_bytes()))
});
entries.into_iter().map(|(k, _)| k).collect()
}
#[cfg(test)]
pub fn eviction_floor(&self) -> f64 {
self.eviction_floor
}
pub fn iter(&self) -> impl Iterator<Item = ContractKey> + '_ {
self.contracts.keys().cloned()
}
pub fn sweep_expired<G>(
&mut self,
subscriber_counts: G,
pressure: MemoryPressure,
) -> Vec<EvictedContract>
where
G: Fn(&ContractKey) -> (usize, usize),
{
self.evict_over_budget(&subscriber_counts, pressure, None)
}
pub fn load_persisted_entry_with_demand(
&mut self,
key: ContractKey,
size_bytes: u64,
access_type: AccessType,
last_access_age: Duration,
local_client_access: bool,
predicted_demand: f64,
) {
if self.contracts.contains_key(&key) {
return;
}
let now = self.time_source.now();
let last_accessed = now.checked_sub(last_access_age).unwrap_or(now);
let local_client_last_access = if local_client_access { Some(now) } else { None };
let contract = HostedContract {
size_bytes,
last_accessed,
last_access_seq: 0,
recency_seq: 0,
keep_score: self.eviction_floor + predicted_demand,
predicted_demand,
read_count: 0,
inserted_at: now,
seeded_this_run: false,
access_type,
local_client_access,
local_client_last_access,
write_generation: 0,
abandoned_at: None,
};
self.contracts.insert(key, contract);
self.current_bytes = self.current_bytes.saturating_add(size_bytes);
}
#[cfg_attr(not(test), allow(dead_code))]
pub fn load_persisted_entry(
&mut self,
key: ContractKey,
size_bytes: u64,
access_type: AccessType,
last_access_age: Duration,
local_client_access: bool,
) {
self.load_persisted_entry_with_demand(
key,
size_bytes,
access_type,
last_access_age,
local_client_access,
NEUTRAL_DEMAND,
)
}
pub fn finalize_loading(&mut self) {
let mut entries: Vec<_> = self
.contracts
.iter()
.map(|(k, v)| (*k, v.last_accessed))
.collect();
entries.sort_by_key(|(_, last_accessed)| *last_accessed);
for (key, _) in entries {
let seq = self.next_seq();
if let Some(entry) = self.contracts.get_mut(&key) {
entry.last_access_seq = seq;
}
}
}
}
#[cfg(test)]
mod tests {
use super::*;
use crate::util::time_source::SharedMockTimeSource;
use freenet_stdlib::prelude::{CodeHash, ContractInstanceId};
fn make_key(seed: u8) -> ContractKey {
ContractKey::from_id_and_code(
ContractInstanceId::new([seed; 32]),
CodeHash::new([seed.wrapping_add(1); 32]),
)
}
fn make_cache(budget: u64) -> (HostingCache<SharedMockTimeSource>, SharedMockTimeSource) {
let time_source = SharedMockTimeSource::new();
let cache = HostingCache::new(budget, time_source.clone());
(cache, time_source)
}
fn evicted_pairs(evicted: &[EvictedContract]) -> Vec<(ContractKey, u64)> {
evicted
.iter()
.map(|e| (e.key, e.write_generation))
.collect()
}
#[test]
fn victim_order_is_local_then_downstream_then_get_recency_then_key() {
use std::cmp::Ordering;
let k1 = make_key(1);
let k2 = make_key(2);
assert_eq!(
victim_order((0, 99, 999, &k2), (1, 0, 0, &k1)),
Ordering::Less,
"fewer local subscriptions must rank ahead of everything else"
);
assert_eq!(
victim_order((1, 0, 999, &k2), (1, 3, 0, &k1)),
Ordering::Less,
"with equal local count, fewer downstream subscribers ranks first"
);
assert_eq!(
victim_order((2, 2, 5, &k1), (2, 2, 6, &k2)),
Ordering::Less,
"with equal subscriber counts, least-recent GET ranks first"
);
let (small, large) = if k1.as_bytes() < k2.as_bytes() {
(&k1, &k2)
} else {
(&k2, &k1)
};
assert_eq!(
victim_order((3, 1, 7, small), (3, 1, 7, large)),
Ordering::Less,
"equal subscriber counts + GET recency fall back to key-byte order"
);
assert_eq!(
victim_order((1, 1, 1, &k1), (1, 1, 1, &k1)),
Ordering::Equal
);
}
#[test]
fn test_empty_cache() {
let (cache, _) = make_cache(1000);
assert!(cache.is_empty());
assert_eq!(cache.len(), 0);
assert_eq!(cache.current_bytes(), 0);
assert!(!cache.contains(&make_key(1)));
}
#[test]
fn test_add_single_contract() {
let (mut cache, _) = make_cache(1000);
let key = make_key(1);
let result = cache.record_access(key, 100, AccessType::Get, 0, |_| (0, 0));
assert!(result.is_new);
assert!(result.evicted.is_empty());
assert!(cache.contains(&key));
assert_eq!(cache.len(), 1);
assert_eq!(cache.current_bytes(), 100);
let info = cache.get(&key).unwrap();
assert_eq!(info.size_bytes, 100);
assert_eq!(info.access_type, AccessType::Get);
}
#[test]
fn test_refresh_existing_contract() {
let (mut cache, time) = make_cache(1000);
let key = make_key(1);
cache.record_access(key, 100, AccessType::Get, 0, |_| (0, 0));
let first_access = cache.get(&key).unwrap().last_accessed;
time.advance_time(Duration::from_secs(10));
cache.record_access(key, 100, AccessType::Put, 0, |_| (0, 0));
assert_eq!(cache.len(), 1);
assert_eq!(cache.current_bytes(), 100);
let info = cache.get(&key).unwrap();
assert_eq!(info.access_type, AccessType::Put);
assert!(info.last_accessed > first_access);
}
#[test]
fn test_over_budget_evicts_least_recent_no_min_ttl_floor() {
let (mut cache, _time) = make_cache(200);
let key1 = make_key(1);
let key2 = make_key(2);
let key3 = make_key(3);
cache.record_access(key1, 100, AccessType::Get, 0, |_| (0, 0));
cache.record_access(key2, 100, AccessType::Get, 0, |_| (0, 0));
assert_eq!(cache.current_bytes(), 200);
let result = cache.record_access(key3, 100, AccessType::Get, 0, |_| (0, 0));
assert!(result.is_new);
assert_eq!(result.evicted, vec![(key1, 0)]);
assert_eq!(cache.len(), 2);
assert!(!cache.contains(&key1));
assert!(cache.contains(&key2));
assert!(cache.contains(&key3));
}
#[test]
fn test_access_refreshes_lru_position() {
let (mut cache, time) = make_cache(200);
let key1 = make_key(1);
let key2 = make_key(2);
let key3 = make_key(3);
cache.record_access(key1, 100, AccessType::Get, 0, |_| (0, 0));
cache.record_access(key2, 100, AccessType::Get, 0, |_| (0, 0));
cache.record_access(key1, 100, AccessType::Get, 0, |_| (0, 0));
let order = cache.keys_eviction_order();
assert_eq!(order, vec![key2, key1]);
time.advance_time(Duration::from_secs(61));
let result = cache.record_access(key3, 100, AccessType::Get, 0, |_| (0, 0));
assert_eq!(result.evicted, vec![(key2, 0)]);
assert!(cache.contains(&key1));
assert!(!cache.contains(&key2));
assert!(cache.contains(&key3));
}
#[test]
fn test_touch_refreshes_ttl() {
let (mut cache, time) = make_cache(200);
let key1 = make_key(1);
let key2 = make_key(2);
let key3 = make_key(3);
cache.record_access(key1, 100, AccessType::Get, 0, |_| (0, 0));
cache.record_access(key2, 100, AccessType::Get, 0, |_| (0, 0));
time.advance_time(Duration::from_secs(50));
cache.touch(&key1);
time.advance_time(Duration::from_secs(15));
let result = cache.record_access(key3, 100, AccessType::Get, 0, |_| (0, 0));
assert_eq!(
result.evicted,
vec![(key2, 0)],
"Should evict key2 which is past TTL"
);
assert!(
cache.contains(&key1),
"key1 should remain (touched recently)"
);
assert!(cache.contains(&key3));
}
#[test]
fn test_large_contract_evicts_multiple() {
let (mut cache, time) = make_cache(300);
let small1 = make_key(1);
let small2 = make_key(2);
let small3 = make_key(3);
let large = make_key(4);
cache.record_access(small1, 100, AccessType::Get, 0, |_| (0, 0));
cache.record_access(small2, 100, AccessType::Get, 0, |_| (0, 0));
cache.record_access(small3, 100, AccessType::Get, 0, |_| (0, 0));
assert_eq!(cache.current_bytes(), 300);
time.advance_time(Duration::from_secs(61));
let result = cache.record_access(large, 200, AccessType::Put, 0, |_| (0, 0));
assert_eq!(result.evicted.len(), 2);
assert_eq!(result.evicted[0], (small1, 0)); assert_eq!(result.evicted[1], (small2, 0));
assert!(!cache.contains(&small1));
assert!(!cache.contains(&small2));
assert!(cache.contains(&small3));
assert!(cache.contains(&large));
}
#[test]
fn test_sweep_expired() {
let (mut cache, _time) = make_cache(100_000);
let key1 = make_key(1);
let key2 = make_key(2);
let key3 = make_key(3);
cache.record_access(key1, 100, AccessType::Get, 0, |_| (0, 0)); cache.record_access(key2, 100, AccessType::Get, 0, |_| (0, 0));
cache.record_access(key3, 100, AccessType::Get, 0, |_| (0, 0));
cache.set_budget_for_test(200);
assert_eq!(cache.len(), 3);
assert_eq!(cache.current_bytes(), 300);
let evicted = cache.sweep_expired(|_| (0, 0), MemoryPressure::AtCapacity);
assert_eq!(evicted_pairs(&evicted), vec![(key1, 0)]);
assert_eq!(cache.current_bytes(), 200);
}
#[test]
fn test_sweep_orders_subscribed_last() {
let (mut cache, _time) = make_cache(100_000);
let key1 = make_key(1);
let key2 = make_key(2);
let key3 = make_key(3);
cache.record_access(key1, 100, AccessType::Get, 0, |_| (0, 0));
cache.record_access(key2, 100, AccessType::Get, 0, |_| (0, 0));
cache.record_access(key3, 100, AccessType::Get, 0, |_| (0, 0));
cache.set_budget_for_test(200);
let evicted =
cache.sweep_expired(|k| (0, (*k == key1) as usize), MemoryPressure::AtCapacity);
assert_eq!(evicted_pairs(&evicted), vec![(key2, 0)]);
assert!(cache.contains(&key1));
assert!(!cache.contains(&key2));
assert!(cache.contains(&key3));
assert_eq!(cache.current_bytes(), 200);
}
#[test]
fn test_record_access_orders_subscribed_last() {
let (mut cache, time) = make_cache(200);
let retained = make_key(1);
let evictable = make_key(2);
let trigger = make_key(3);
cache.record_access(retained, 100, AccessType::Get, 0, |_| (0, 0));
cache.record_access(evictable, 100, AccessType::Get, 0, |_| (0, 0));
assert_eq!(cache.current_bytes(), 200);
time.advance_time(Duration::from_secs(61));
let result = cache.record_access(trigger, 100, AccessType::Get, 0, |k| {
(0, (*k == retained) as usize)
});
assert_eq!(
result.evicted,
vec![(evictable, 0)],
"the subscribed contract is ordered last; the zero-subscriber \
past-TTL contract must be evicted instead"
);
assert!(
cache.contains(&retained),
"subscribed contract survives while a zero-subscriber one can be shed"
);
assert!(!cache.contains(&evictable));
assert!(cache.contains(&trigger));
}
#[test]
fn test_record_access_never_evicts_the_new_entry() {
let (mut cache, _time) = make_cache(100);
let first = make_key(1);
let second = make_key(2);
cache.record_access(first, 100, AccessType::Get, 0, |_| (0, 0));
let result = cache.record_access(second, 100, AccessType::Get, 0, |_| (0, 0));
assert_eq!(result.evicted, vec![(first, 0)]);
assert!(cache.contains(&second));
assert!(!cache.contains(&first));
}
#[test]
fn test_touch_non_existent_is_no_op() {
let (mut cache, _) = make_cache(1000);
let key = make_key(1);
cache.touch(&key);
assert!(cache.is_empty());
assert!(!cache.contains(&key));
}
#[test]
fn test_access_types() {
let (mut cache, _) = make_cache(1000);
let key = make_key(1);
cache.record_access(key, 100, AccessType::Get, 0, |_| (0, 0));
assert_eq!(cache.get(&key).unwrap().access_type, AccessType::Get);
cache.record_access(key, 100, AccessType::Put, 0, |_| (0, 0));
assert_eq!(cache.get(&key).unwrap().access_type, AccessType::Put);
cache.record_access(key, 100, AccessType::Subscribe, 0, |_| (0, 0));
assert_eq!(cache.get(&key).unwrap().access_type, AccessType::Subscribe);
}
#[test]
fn test_contract_size_change() {
let (mut cache, _) = make_cache(1000);
let key = make_key(1);
cache.record_access(key, 100, AccessType::Get, 0, |_| (0, 0));
assert_eq!(cache.current_bytes(), 100);
assert_eq!(cache.get(&key).unwrap().size_bytes, 100);
cache.record_access(key, 200, AccessType::Put, 0, |_| (0, 0));
assert_eq!(cache.current_bytes(), 200);
assert_eq!(cache.get(&key).unwrap().size_bytes, 200);
cache.record_access(key, 150, AccessType::Put, 0, |_| (0, 0));
assert_eq!(cache.current_bytes(), 150);
assert_eq!(cache.get(&key).unwrap().size_bytes, 150);
}
#[test]
fn test_iter_returns_all_hosted_keys() {
let (mut cache, _) = make_cache(1000);
assert_eq!(cache.iter().count(), 0);
let key1 = make_key(1);
let key2 = make_key(2);
let key3 = make_key(3);
cache.record_access(key1, 100, AccessType::Get, 0, |_| (0, 0));
cache.record_access(key2, 100, AccessType::Put, 0, |_| (0, 0));
cache.record_access(key3, 100, AccessType::Subscribe, 0, |_| (0, 0));
let keys: Vec<ContractKey> = cache.iter().collect();
assert_eq!(keys.len(), 3);
assert!(keys.contains(&key1));
assert!(keys.contains(&key2));
assert!(keys.contains(&key3));
}
#[test]
fn test_record_access_carries_write_generation_through_eviction() {
let (mut cache, time) = make_cache(100);
let evicted_key = make_key(1);
let trigger_key = make_key(2);
let captured_generation: u64 = 0xABCD_EF42;
let first = cache.record_access(
evicted_key,
100,
AccessType::Get,
captured_generation,
|_| (0, 0),
);
assert!(first.evicted.is_empty(), "first insert evicts nothing");
assert_eq!(
cache
.get(&evicted_key)
.expect("just inserted")
.write_generation,
captured_generation,
"captured generation must be stored on the HostedContract entry"
);
time.advance_time(Duration::from_secs(61));
let result = cache.record_access(
trigger_key,
100,
AccessType::Get,
999, |_| (0, 0),
);
assert_eq!(
result.evicted,
vec![(evicted_key, captured_generation)],
"evicted tuple must carry the generation captured atomically \
when the evicted entry was inserted"
);
}
#[test]
fn test_record_access_refresh_updates_write_generation() {
let (mut cache, _) = make_cache(1000);
let key = make_key(7);
cache.record_access(key, 100, AccessType::Get, 1, |_| (0, 0));
assert_eq!(cache.get(&key).unwrap().write_generation, 1);
cache.record_access(key, 100, AccessType::Put, 5, |_| (0, 0));
assert_eq!(
cache.get(&key).unwrap().write_generation,
5,
"re-access must refresh the captured generation snapshot"
);
}
#[test]
fn test_local_client_access_age_gate_expiry() {
let lease = Duration::from_secs(480); let (mut cache, time) = make_cache(10000);
let key = make_key(1);
cache.record_access(key, 100, AccessType::Get, 0, |_| (0, 0));
cache.mark_local_client_access(&key);
assert!(cache.has_local_client_access(&key));
assert!(cache.has_recent_local_client_access(&key, lease));
time.advance_time(lease - Duration::from_secs(1));
assert!(cache.has_recent_local_client_access(&key, lease));
time.advance_time(Duration::from_secs(2));
assert!(
!cache.has_recent_local_client_access(&key, lease),
"Contract should exit renewal after lease expires"
);
assert!(
cache.has_local_client_access(&key),
"Flag should remain sticky even after age gate expires"
);
cache.mark_local_client_access(&key);
assert!(
cache.has_recent_local_client_access(&key, lease),
"Re-marking should refresh the age gate"
);
}
#[test]
fn eviction_ordered_scores_matches_key_order_and_carries_fields() {
let (mut cache, _) = make_cache(10_000);
let key1 = make_key(1);
let key2 = make_key(2);
let key3 = make_key(3);
cache.record_access(key1, 111, AccessType::Get, 0, |_| (0, 0));
cache.record_access(key2, 222, AccessType::Get, 0, |_| (0, 0));
cache.record_access(key3, 333, AccessType::Get, 0, |_| (0, 0));
let scores = cache.eviction_ordered_scores();
let score_keys: Vec<_> = scores.iter().map(|s| s.key).collect();
assert_eq!(
score_keys,
cache.keys_eviction_order(),
"eviction_ordered_scores must use the same order as keys_eviction_order"
);
for s in &scores {
let entry = cache.get(&s.key).expect("scored key is in the cache");
assert_eq!(s.keep_score, entry.keep_score);
assert_eq!(s.size_bytes, entry.size_bytes);
assert_eq!(s.read_count, entry.read_count);
assert_eq!(s.predicted_demand, entry.predicted_demand);
assert_eq!(s.recency_seq, entry.recency_seq);
}
}
#[ignore]
#[test]
fn test_record_abandonment_moves_entry_to_eviction_front() {
let (mut cache, _) = make_cache(1000);
let key1 = make_key(1);
let key2 = make_key(2);
let key3 = make_key(3);
cache.record_access(key1, 100, AccessType::Get, 0, |_| (0, 0));
cache.record_access(key2, 100, AccessType::Get, 0, |_| (0, 0));
cache.record_access(key3, 100, AccessType::Get, 0, |_| (0, 0));
assert_eq!(cache.keys_eviction_order(), vec![key1, key2, key3]);
cache.record_abandonment(&key3);
assert_eq!(cache.keys_eviction_order(), vec![key3, key1, key2]);
let info = cache.get(&key3).unwrap();
assert!(
info.abandoned_at.is_some(),
"Abandonment must record a timestamp"
);
assert_eq!(
info.keep_score,
cache.eviction_floor(),
"abandonment must strip demand credit to the floor"
);
}
#[test]
fn record_abandonment_resets_recency_at_subscription_termination() {
let (mut cache, _time) = make_cache(300); let subscribed = make_key(1);
let older = make_key(2);
let newer = make_key(3);
let trigger = make_key(4);
cache.record_access(subscribed, 100, AccessType::Get, 0, |_| (0, 0));
cache.record_access(older, 100, AccessType::Get, 0, |_| (0, 0));
cache.record_access(newer, 100, AccessType::Get, 0, |_| (0, 0));
cache.record_abandonment(&subscribed);
assert!(
cache.get(&subscribed).unwrap().recency_seq > cache.get(&newer).unwrap().recency_seq,
"termination must reset recency to the frontier (newer than everything else)"
);
let result = cache.record_access(trigger, 100, AccessType::Get, 0, |_| (0, 0));
assert_eq!(
result.evicted,
vec![(older, 0)],
"the least-recent zero-subscriber contract is shed; termination protected `subscribed`"
);
assert!(
cache.contains(&subscribed),
"the formerly-subscribed contract survived: termination reset its recency"
);
assert!(!cache.contains(&older));
}
#[test]
fn test_record_abandonment_is_idempotent() {
let (mut cache, time) = make_cache(1000);
let key = make_key(1);
cache.record_access(key, 100, AccessType::Get, 0, |_| (0, 0));
cache.record_abandonment(&key);
let first = cache.get(&key).unwrap().abandoned_at;
assert!(first.is_some());
time.advance_time(Duration::from_secs(5));
cache.record_abandonment(&key);
let second = cache.get(&key).unwrap().abandoned_at;
assert_eq!(first, second);
}
#[test]
fn test_record_abandonment_missing_key_is_noop() {
let (mut cache, _) = make_cache(1000);
let key = make_key(42);
cache.record_abandonment(&key);
assert!(!cache.contains(&key));
assert_eq!(cache.len(), 0);
}
#[test]
fn test_record_access_clears_abandoned_marker() {
let (mut cache, _) = make_cache(1000);
let key = make_key(1);
cache.record_access(key, 100, AccessType::Get, 0, |_| (0, 0));
cache.record_abandonment(&key);
assert!(cache.get(&key).unwrap().abandoned_at.is_some());
cache.record_access(key, 100, AccessType::Get, 0, |_| (0, 0));
assert!(
cache.get(&key).unwrap().abandoned_at.is_none(),
"record_access must clear abandoned_at"
);
}
#[test]
fn test_touch_clears_abandoned_marker() {
let (mut cache, _) = make_cache(1000);
let key = make_key(1);
cache.record_access(key, 100, AccessType::Get, 0, |_| (0, 0));
cache.record_abandonment(&key);
cache.touch(&key);
assert!(
cache.get(&key).unwrap().abandoned_at.is_none(),
"touch must clear abandoned_at"
);
}
#[ignore]
#[test]
fn test_abandoned_entry_evicted_before_active_under_pressure() {
let (mut cache, time) = make_cache(200);
let key1 = make_key(1);
let key2 = make_key(2);
let key3 = make_key(3);
cache.record_access(key1, 100, AccessType::Get, 0, |_| (0, 0));
cache.record_access(key2, 100, AccessType::Get, 0, |_| (0, 0));
cache.record_abandonment(&key2);
time.advance_time(Duration::from_secs(61));
let result = cache.record_access(key3, 100, AccessType::Get, 0, |_| (0, 0));
assert!(result.is_new);
assert_eq!(
result.evicted,
vec![(key2, 0)],
"abandoned entry must evict first"
);
assert!(cache.contains(&key1));
assert!(!cache.contains(&key2));
assert!(cache.contains(&key3));
}
#[test]
fn test_idle_persistence_preserved_when_under_pressure() {
let (mut cache, time) = make_cache(1000);
let key1 = make_key(1);
let key2 = make_key(2);
cache.record_access(key1, 100, AccessType::Get, 0, |_| (0, 0));
cache.record_access(key2, 100, AccessType::Get, 0, |_| (0, 0));
cache.record_abandonment(&key2);
time.advance_time(Duration::from_secs(3600));
let evicted = cache.sweep_expired(|_| (0, 0), MemoryPressure::AtCapacity);
assert!(evicted.is_empty(), "no pressure → no eviction");
assert!(cache.contains(&key1));
assert!(cache.contains(&key2));
}
const MIB: u64 = 1024 * 1024;
const GIB: u64 = 1024 * 1024 * 1024;
#[test]
fn budget_for_ram_scales_and_clamps() {
assert_eq!(budget_for_ram(512 * MIB), MIN_DEFAULT_HOSTING_BUDGET_BYTES);
assert_eq!(budget_for_ram(GIB), MIN_DEFAULT_HOSTING_BUDGET_BYTES);
assert_eq!(budget_for_ram(2 * GIB), 256 * MIB);
assert_eq!(budget_for_ram(4 * GIB), 512 * MIB);
assert_eq!(budget_for_ram(8 * GIB), MAX_DEFAULT_HOSTING_BUDGET_BYTES);
assert_eq!(budget_for_ram(128 * GIB), MAX_DEFAULT_HOSTING_BUDGET_BYTES);
}
#[test]
fn budget_for_ram_is_ram_scaled_not_fixed() {
let small = budget_for_ram(2 * GIB);
let large = budget_for_ram(6 * GIB);
assert!(
small < large,
"budget must vary with RAM within the band, got small={small} large={large}"
);
assert!(
small < MAX_DEFAULT_HOSTING_BUDGET_BYTES,
"a memory-constrained box must get less than the old flat 1 GiB default"
);
assert_ne!(budget_for_ram(2 * GIB), budget_for_ram(3 * GIB));
assert_ne!(budget_for_ram(3 * GIB), budget_for_ram(4 * GIB));
}
#[test]
fn disk_budget_for_scales_and_clamps() {
assert_eq!(
disk_budget_for(0, 100 * MIB, 0.5),
MIN_DEFAULT_HOSTING_BUDGET_BYTES,
"50 MiB budget is below the 128 MiB floor"
);
assert_eq!(disk_budget_for(4 * GIB, 4 * GIB, 0.5), 4 * GIB);
assert_eq!(disk_budget_for(2 * GIB, 0, 0.5), GIB);
assert_eq!(
disk_budget_for(200 * GIB, 200 * GIB, 0.5),
DEFAULT_MAX_HOSTING_DISK_BYTES,
"200 GiB budget is above the 32 GiB cap"
);
}
#[test]
fn disk_budget_for_pct_endpoints() {
assert_eq!(
disk_budget_for(10 * GIB, 10 * GIB, 0.0),
MIN_DEFAULT_HOSTING_BUDGET_BYTES
);
assert_eq!(
disk_budget_for(100 * GIB, 0, 1.0),
DEFAULT_MAX_HOSTING_DISK_BYTES
);
assert_eq!(disk_budget_for(GIB, GIB, 1.0), 2 * GIB);
}
#[test]
fn disk_budget_for_zero_and_huge_free() {
assert_eq!(disk_budget_for(0, 0, 0.5), MIN_DEFAULT_HOSTING_BUDGET_BYTES);
assert_eq!(
disk_budget_for(0, u64::MAX, 0.5),
DEFAULT_MAX_HOSTING_DISK_BYTES
);
}
#[test]
fn disk_budget_for_rejects_bad_pct() {
assert_eq!(
disk_budget_for(10 * GIB, 10 * GIB, f64::NAN),
MIN_DEFAULT_HOSTING_BUDGET_BYTES
);
assert_eq!(
disk_budget_for(10 * GIB, 10 * GIB, f64::INFINITY),
MIN_DEFAULT_HOSTING_BUDGET_BYTES
);
assert_eq!(
disk_budget_for(10 * GIB, 10 * GIB, -1.0),
MIN_DEFAULT_HOSTING_BUDGET_BYTES
);
assert_eq!(
disk_budget_for(100 * GIB, 0, 5.0),
DEFAULT_MAX_HOSTING_DISK_BYTES
);
}
#[test]
fn disk_budget_for_saturating_overflow() {
assert_eq!(
disk_budget_for(u64::MAX, u64::MAX, 0.5),
DEFAULT_MAX_HOSTING_DISK_BYTES
);
}
#[test]
fn disk_budget_for_clamped_honors_explicit_bounds() {
assert_eq!(
disk_budget_for_clamped(4 * GIB, 4 * GIB, 0.5, MIN_DEFAULT_HOSTING_BUDGET_BYTES, GIB),
GIB
);
assert_eq!(
disk_budget_for_clamped(100 * GIB, 0, 0.5, 512 * MIB, 128 * MIB),
512 * MIB
);
}
#[test]
fn default_hosting_budget_within_clamp() {
let b = default_hosting_budget_bytes();
assert!(
(MIN_DEFAULT_HOSTING_BUDGET_BYTES..=MAX_DEFAULT_HOSTING_BUDGET_BYTES).contains(&b),
"default {b} must be within [{}, {}]",
MIN_DEFAULT_HOSTING_BUDGET_BYTES,
MAX_DEFAULT_HOSTING_BUDGET_BYTES,
);
}
#[test]
fn test_budget_eviction_counter_tracks_over_budget_evictions() {
let (mut cache, _time) = make_cache(200);
let key1 = make_key(1);
let key2 = make_key(2);
let key3 = make_key(3);
let key4 = make_key(4);
cache.record_access(key1, 100, AccessType::Get, 0, |_| (0, 0));
cache.record_access(key2, 100, AccessType::Get, 0, |_| (0, 0));
assert_eq!(cache.stats().budget_evictions_total, 0);
let result = cache.record_access(key3, 100, AccessType::Get, 0, |_| (0, 0));
assert_eq!(result.evicted, vec![(key1, 0)]);
assert_eq!(
cache.stats().budget_evictions_total,
1,
"an over-budget insert counts one budget eviction (no min_ttl grace)"
);
let result = cache.record_access(key4, 100, AccessType::Get, 0, |_| (0, 0));
assert_eq!(result.evicted, vec![(key2, 0)]);
let stats = cache.stats();
assert_eq!(stats.budget_evictions_total, 2);
assert_eq!(stats.current_bytes, 200);
assert_eq!(stats.contract_count, 2);
assert_eq!(stats.budget_bytes, 200);
let evicted = cache.sweep_expired(|_| (0, 0), MemoryPressure::AtCapacity);
assert!(evicted.is_empty(), "at budget -> no further eviction");
assert_eq!(
cache.stats().budget_evictions_total,
2,
"counter must not advance with no budget pressure"
);
}
#[test]
fn test_evicted_unread_counts_only_never_read_seeds() {
let (mut cache, time) = make_cache(100);
let key1 = make_key(1);
let key2 = make_key(2);
let key3 = make_key(3);
cache.record_access(key1, 100, AccessType::Put, 0, |_| (0, 0));
assert_eq!(cache.stats().evicted_unread_total, 0);
time.advance_time(Duration::from_secs(61));
let result = cache.record_access(key2, 100, AccessType::Put, 0, |_| (0, 0));
assert_eq!(result.evicted, vec![(key1, 0)]);
let stats = cache.stats();
assert_eq!(stats.budget_evictions_total, 1);
assert_eq!(stats.evicted_unread_total, 1, "an unread seed was evicted");
assert_eq!(
stats.evicted_unread_age_secs_sum, 61,
"age-at-eviction of the unread seed is recorded"
);
cache.record_access(key2, 100, AccessType::Get, 0, |_| (0, 0));
time.advance_time(Duration::from_secs(61));
let result = cache.record_access(key3, 100, AccessType::Get, 0, |_| (0, 0));
assert_eq!(result.evicted, vec![(key2, 0)]);
let stats = cache.stats();
assert_eq!(stats.budget_evictions_total, 2);
assert_eq!(
stats.evicted_unread_total, 1,
"a victim read at least once must NOT count as an unread seed"
);
assert_eq!(
stats.evicted_unread_age_secs_sum, 61,
"age sum unchanged when the eviction is not an unread seed"
);
}
#[test]
fn test_reloaded_entry_eviction_does_not_count_as_unread_seed() {
let (mut cache, _time) = make_cache(100);
let key1 = make_key(1);
let key2 = make_key(2);
cache.load_persisted_entry(key1, 100, AccessType::Put, Duration::from_secs(1), false);
cache.finalize_loading();
assert!(cache.contains(&key1));
assert_eq!(cache.stats().evicted_unread_total, 0);
let result = cache.record_access(key2, 100, AccessType::Get, 0, |_| (0, 0));
assert_eq!(
result.evicted,
vec![(key1, 0)],
"the reloaded entry is evicted in the post-load over-budget burst"
);
let stats = cache.stats();
assert_eq!(stats.budget_evictions_total, 1, "it WAS evicted");
assert_eq!(
stats.evicted_unread_total, 0,
"a reloaded entry (not seeded this run) must NOT count as an unread seed"
);
assert_eq!(
stats.evicted_unread_age_secs_sum, 0,
"no age is recorded for a reloaded (non-unread-seed) eviction"
);
}
#[test]
fn reloaded_entry_has_zero_get_recency_regardless_of_access_type() {
let (mut cache, _) = make_cache(10_000);
let put_seed = make_key(1);
let subscribed = make_key(2);
cache.load_persisted_entry(
put_seed,
100,
AccessType::Put,
Duration::from_secs(30),
false,
);
cache.load_persisted_entry(
subscribed,
100,
AccessType::Subscribe,
Duration::from_secs(10),
false,
);
cache.finalize_loading();
assert_eq!(
cache.get(&put_seed).unwrap().recency_seq,
0,
"a reloaded PUT entry must have recency_seq == 0 (never GET-read since restart)"
);
assert_eq!(
cache.get(&subscribed).unwrap().recency_seq,
0,
"a reloaded SUBSCRIBE entry must also have recency_seq == 0"
);
cache.record_access(put_seed, 100, AccessType::Get, 0, |_| (0, 0));
assert!(
cache.get(&put_seed).unwrap().recency_seq > 0,
"a real GET after restart must re-stamp recency_seq to a real value"
);
}
#[test]
fn fuel_gauge_keep_score_set_on_insert_and_refreshed_on_read() {
let (mut cache, _) = make_cache(10_000);
let key = make_key(1);
cache.record_access_with_demand(key, 100, AccessType::Get, 0, 3.0, |_| (0, 0));
assert_eq!(cache.get(&key).unwrap().keep_score, 3.0);
assert_eq!(cache.get(&key).unwrap().predicted_demand, 3.0);
assert_eq!(cache.get(&key).unwrap().read_count, 1);
cache.record_access_with_demand(key, 100, AccessType::Get, 0, 5.0, |_| (0, 0));
assert_eq!(cache.get(&key).unwrap().keep_score, 5.0);
assert_eq!(cache.get(&key).unwrap().read_count, 2);
}
#[ignore]
#[test]
fn fuel_gauge_evicts_lowest_demand_not_lru() {
let (mut cache, time) = make_cache(200);
let high = make_key(1);
let low = make_key(2);
let trigger = make_key(3);
cache.record_access_with_demand(high, 100, AccessType::Get, 0, 10.0, |_| (0, 0));
cache.record_access_with_demand(low, 100, AccessType::Get, 0, 1.0, |_| (0, 0));
assert_eq!(cache.current_bytes(), 200);
time.advance_time(Duration::from_secs(61));
let result =
cache.record_access_with_demand(trigger, 100, AccessType::Get, 0, 1.0, |_| (0, 0));
assert_eq!(
result.evicted,
vec![(low, 0)],
"lowest-demand contract must evict, not the least-recently-used one"
);
assert!(cache.contains(&high), "high-demand contract must survive");
assert!(!cache.contains(&low));
}
#[ignore]
#[test]
fn fuel_gauge_cold_start_keeps_near_key_over_far_key() {
let prior = super::super::demand::ProximityPrior::new();
assert_eq!(prior.len(), 0, "cold estimator has no samples");
let near_demand = prior.predict(0.02); let far_demand = prior.predict(0.45); assert!(
near_demand > far_demand,
"cold distance prior must slope down: near={near_demand}, far={far_demand}"
);
let (mut cache, time) = make_cache(200);
let near = make_key(1);
let far = make_key(2);
let trigger = make_key(3);
cache.record_access_with_demand(near, 100, AccessType::Get, 0, near_demand, |_| (0, 0));
cache.record_access_with_demand(far, 100, AccessType::Get, 0, far_demand, |_| (0, 0));
assert_eq!(cache.current_bytes(), 200);
assert!(
cache.get(&near).unwrap().keep_score > cache.get(&far).unwrap().keep_score,
"near-key contract must carry more cold demand credit than far-key"
);
time.advance_time(Duration::from_secs(61));
let result = cache.record_access_with_demand(
trigger,
100,
AccessType::Get,
0,
NEUTRAL_DEMAND,
|_| (0, 0),
);
assert_eq!(
result.evicted,
vec![(far, 0)],
"cold start must evict the FAR-key contract (lower distance prior) first"
);
assert!(
cache.contains(&near),
"the NEAR-key contract out-survives the FAR-key one at cold start"
);
assert!(!cache.contains(&far));
}
#[ignore]
#[test]
fn fuel_gauge_keeps_repeatedly_read_contract_over_junk() {
let (mut cache, time) = make_cache(200);
let room = make_key(1); let junk = make_key(2); let trigger = make_key(3);
cache.record_access_with_demand(room, 100, AccessType::Get, 0, 10.0, |_| (0, 0));
for _ in 0..3 {
time.advance_time(Duration::from_secs(5));
cache.touch(&room);
}
time.advance_time(Duration::from_secs(5));
cache.record_access_with_demand(junk, 100, AccessType::Get, 0, 1.0, |_| (0, 0));
time.advance_time(Duration::from_secs(61));
let room_entry = cache.get(&room).expect("room hosted");
let junk_entry = cache.get(&junk).expect("junk hosted");
assert!(
room_entry.last_access_seq < junk_entry.last_access_seq,
"room must be the least-recently-accessed of the two, so recency \
alone (byte-LRU) would evict it first"
);
assert!(
room_entry.keep_score > junk_entry.keep_score,
"room must carry more demand credit than junk ({} vs {})",
room_entry.keep_score,
junk_entry.keep_score,
);
let result =
cache.record_access_with_demand(trigger, 100, AccessType::Get, 0, 1.0, |_| (0, 0));
assert_eq!(
result.evicted,
vec![(junk, 0)],
"low-demand junk must evict, NOT the older-but-high-demand room"
);
assert!(
cache.contains(&room),
"the repeatedly-read high-demand room survives even though it is the \
least-recently-accessed past-TTL entry (byte-LRU would have evicted it)"
);
assert!(!cache.contains(&junk));
assert_eq!(
cache.stats().evictions_of_recently_read_total,
0,
"a repeatedly-read contract must never be evicted (no miscalibration)"
);
}
#[test]
fn eviction_floor_ratchets_up_on_eviction() {
let (mut cache, time) = make_cache(100);
assert_eq!(cache.eviction_floor(), 0.0);
let a = make_key(1);
cache.record_access_with_demand(a, 100, AccessType::Get, 0, 7.0, |_| (0, 0));
time.advance_time(Duration::from_secs(61));
let b = make_key(2);
let r = cache.record_access_with_demand(b, 100, AccessType::Get, 0, 2.0, |_| (0, 0));
assert_eq!(r.evicted, vec![(a, 0)]);
assert_eq!(
cache.eviction_floor(),
7.0,
"floor ratchets to evicted score"
);
time.advance_time(Duration::from_secs(61));
let c = make_key(3);
let r = cache.record_access_with_demand(c, 100, AccessType::Get, 0, 1.0, |_| (0, 0));
assert_eq!(r.evicted, vec![(b, 0)], "b (keep_score 2) evicts");
assert_eq!(
cache.eviction_floor(),
7.0,
"floor must not drop below its high-water mark"
);
}
#[test]
fn put_seeds_but_earns_no_read_demand_credit() {
let (mut cache, _) = make_cache(10_000);
let key = make_key(1);
cache.record_access_with_demand(key, 100, AccessType::Put, 0, 2.0, |_| (0, 0));
assert_eq!(cache.get(&key).unwrap().read_count, 0, "PUT is not a read");
let seed_score = cache.get(&key).unwrap().keep_score;
assert_eq!(seed_score, 2.0);
cache.record_access_with_demand(key, 100, AccessType::Put, 0, 9.0, |_| (0, 0));
assert_eq!(
cache.get(&key).unwrap().read_count,
0,
"re-PUT must not count as a read"
);
assert_eq!(
cache.get(&key).unwrap().keep_score,
seed_score,
"re-PUT (seed) must not refresh keep_score to the frontier"
);
cache.record_access_with_demand(key, 100, AccessType::Get, 0, 9.0, |_| (0, 0));
assert_eq!(cache.get(&key).unwrap().read_count, 1);
assert_eq!(cache.get(&key).unwrap().keep_score, 9.0);
}
#[test]
fn evictions_of_recently_read_counts_only_repeat_demand() {
let (mut cache, time) = make_cache(100);
let read_twice = make_key(1);
cache.record_access(read_twice, 100, AccessType::Get, 0, |_| (0, 0));
cache.touch(&read_twice); time.advance_time(Duration::from_secs(61));
let junk = make_key(2);
let r = cache.record_access_with_demand(junk, 100, AccessType::Get, 0, 5.0, |_| (0, 0));
assert_eq!(r.evicted, vec![(read_twice, 0)]);
assert_eq!(
cache.stats().evictions_of_recently_read_total,
1,
"evicting a twice-read contract is a miscalibration signal"
);
time.advance_time(Duration::from_secs(61));
let seed = make_key(3);
let r = cache.record_access_with_demand(seed, 100, AccessType::Get, 0, 9.0, |_| (0, 0));
assert_eq!(r.evicted, vec![(junk, 0)], "junk (read once) evicts");
assert_eq!(
cache.stats().evictions_of_recently_read_total,
1,
"a one-off seed eviction must not count as recently-read"
);
}
#[test]
fn subscribed_contract_ordered_last_survives_while_zero_sub_evicted() {
let (mut cache, time) = make_cache(200);
let subscribed = make_key(1); let other = make_key(2);
let trigger = make_key(3);
cache.record_access_with_demand(subscribed, 100, AccessType::Get, 0, 0.1, |_| (0, 0));
cache.record_access_with_demand(other, 100, AccessType::Get, 0, 5.0, |_| (0, 0));
time.advance_time(Duration::from_secs(61));
let result = cache.record_access_with_demand(trigger, 100, AccessType::Get, 0, 5.0, |k| {
(0, (*k == subscribed) as usize)
});
assert_eq!(
result.evicted,
vec![(other, 0)],
"the subscribed contract is ordered last; the zero-subscriber one sheds"
);
assert_eq!(
result.evicted_in_use,
Vec::<ContractKey>::new(),
"no in-use contract was shed here, so nothing needs subscription teardown"
);
assert!(cache.contains(&subscribed));
assert!(!cache.contains(&other));
}
#[test]
fn evict_normal_drops_zero_sub_before_subscribed() {
let (mut cache, time) = make_cache(200);
let a = make_key(1);
let b = make_key(2);
let c = make_key(3);
let subs = |k: &ContractKey| (0, usize::from(*k == a));
cache.record_access(a, 100, AccessType::Get, 0, subs);
cache.record_access(b, 100, AccessType::Get, 0, subs);
assert_eq!(cache.current_bytes(), 200);
time.advance_time(Duration::from_secs(61));
let result = cache.record_access(c, 100, AccessType::Get, 0, subs);
assert_eq!(
result.evicted,
vec![(b, 0)],
"the zero-subscriber contract sheds before the subscribed one"
);
assert!(cache.contains(&a), "subscribed A survives (ordered last)");
assert!(cache.contains(&c));
assert!(!cache.contains(&b));
}
#[test]
fn real_get_and_put_refresh_recency_subscribe_does_not() {
let (mut cache, _time) = make_cache(300);
let a = make_key(1);
let b = make_key(2);
let c = make_key(3);
let d = make_key(4);
cache.record_access(a, 100, AccessType::Get, 0, |_| (0, 0));
cache.record_access(b, 100, AccessType::Get, 0, |_| (0, 0));
cache.record_access(c, 100, AccessType::Get, 0, |_| (0, 0));
cache.record_access(a, 100, AccessType::Put, 0, |_| (0, 0));
cache.record_access(b, 100, AccessType::Subscribe, 0, |_| (0, 0));
let result = cache.record_access(d, 100, AccessType::Get, 0, |_| (0, 0));
assert_eq!(
result.evicted,
vec![(b, 0)],
"B is evicted: SUBSCRIBE did not refresh recency, but A's PUT did (A survives)"
);
assert!(cache.contains(&a), "A survives: its PUT refreshed recency");
assert!(!cache.contains(&b));
assert!(cache.contains(&c));
assert!(cache.contains(&d));
}
#[test]
fn real_get_refreshes_recency() {
let (mut cache, time) = make_cache(300);
let a = make_key(1);
let b = make_key(2);
let c = make_key(3);
let d = make_key(4);
cache.record_access(a, 100, AccessType::Get, 0, |_| (0, 0));
cache.record_access(b, 100, AccessType::Get, 0, |_| (0, 0));
cache.record_access(c, 100, AccessType::Get, 0, |_| (0, 0));
cache.record_access(a, 100, AccessType::Get, 0, |_| (0, 0));
time.advance_time(Duration::from_secs(61));
let result = cache.record_access(d, 100, AccessType::Get, 0, |_| (0, 0));
assert_eq!(
result.evicted,
vec![(b, 0)],
"B is evicted: A's real GET made A newest, leaving B least-recent"
);
assert!(cache.contains(&a));
assert!(!cache.contains(&b));
assert!(cache.contains(&c));
assert!(cache.contains(&d));
}
#[test]
fn oom_valve_sheds_fewest_subscriber() {
let (mut cache, _time) = make_cache(100_000);
let a = make_key(1);
let b = make_key(2);
let subs = |k: &ContractKey| if *k == a { (0, 2) } else { (0, 1) };
cache.record_access(a, 100, AccessType::Get, 0, subs);
cache.record_access(b, 100, AccessType::Get, 0, subs);
cache.set_budget_for_test(100);
assert!(cache.contains(&a));
assert!(cache.contains(&b));
assert_eq!(cache.current_bytes(), 200, "200 bytes over the 100 budget");
let evicted = cache.sweep_expired(subs, MemoryPressure::Overflow);
assert_eq!(
evicted_pairs(&evicted),
vec![(b, 0)],
"fewest-subscriber contract sheds first"
);
assert!(
evicted.iter().all(|e| e.was_in_use),
"the shed contract was subscribed, so it is flagged in-use for teardown"
);
assert!(cache.contains(&a), "the more-subscribed contract survives");
assert!(!cache.contains(&b));
assert_eq!(cache.stats().oom_valve_evictions_total, 1);
assert_eq!(
cache.stats().subscribed_evictions_total,
1,
"shedding a subscribed contract bumps the subscribed-eviction falsifier"
);
}
#[test]
fn oom_valve_equal_subscribers_sheds_least_recent_get() {
let (mut cache, _time) = make_cache(100_000);
let a = make_key(1);
let b = make_key(2);
cache.record_access(a, 100, AccessType::Get, 0, |_| (0, 1)); cache.record_access(b, 100, AccessType::Get, 0, |_| (0, 1)); cache.set_budget_for_test(100);
assert_eq!(cache.current_bytes(), 200);
let evicted = cache.sweep_expired(|_| (0, 1), MemoryPressure::Overflow);
assert_eq!(
evicted_pairs(&evicted),
vec![(a, 0)],
"with equal subscribers, the least-recently-accessed contract (A) sheds"
);
assert!(!cache.contains(&a));
assert!(cache.contains(&b));
assert_eq!(cache.stats().oom_valve_evictions_total, 1);
}
#[test]
fn oom_valve_counter_zero_under_normal_atcapacity() {
let (mut cache, _time) = make_cache(100);
let a = make_key(1);
let b = make_key(2);
cache.record_access(a, 100, AccessType::Get, 0, |_| (0, 0));
let result = cache.record_access(b, 100, AccessType::Get, 0, |_| (0, 0));
assert_eq!(result.evicted, vec![(a, 0)]);
assert!(
result.evicted_in_use.is_empty(),
"a zero-subscriber eviction needs no subscription teardown"
);
assert_eq!(
cache.stats().oom_valve_evictions_total,
0,
"a normal zero-subscriber eviction must not touch the OOM-valve counter"
);
assert_eq!(
cache.stats().subscribed_evictions_total,
0,
"a zero-subscriber eviction must not touch the subscribed-eviction counter"
);
}
#[test]
fn fresh_put_protected_by_recency_not_min_ttl() {
let (mut cache, _time) = make_cache(100);
let old = make_key(1);
let seed = make_key(2);
cache.record_access(old, 100, AccessType::Get, 0, |_| (0, 0)); let result = cache.record_access(seed, 100, AccessType::Put, 0, |_| (0, 0));
assert_eq!(
result.evicted,
vec![(old, 0)],
"the fresh PUT out-survives the older contract by recency"
);
assert!(
cache.contains(&seed),
"a fresh PUT is protected by its recency + the op-scoped backstop"
);
assert!(!cache.contains(&old));
}
#[test]
fn evict_all_subscribed_sheds_fewest_as_last_resort() {
let (mut cache, time) = make_cache(200);
let local_sub = make_key(1); let downstream_sub = make_key(2); let trigger = make_key(3);
let subs = |k: &ContractKey| {
if *k == local_sub {
(1, 0)
} else if *k == downstream_sub {
(0, 5)
} else {
(0, 1) }
};
cache.record_access(local_sub, 100, AccessType::Get, 0, subs);
cache.record_access(downstream_sub, 100, AccessType::Get, 0, subs);
assert_eq!(cache.current_bytes(), 200);
time.advance_time(Duration::from_secs(61));
let result = cache.record_access(trigger, 100, AccessType::Get, 0, subs);
assert_eq!(
result.evicted,
vec![(downstream_sub, 0)],
"with only subscribed contracts, the fewest-LOCAL (then fewest-\
downstream) one is shed — the local-client contract is evicted last"
);
assert_eq!(
result.evicted_in_use,
vec![downstream_sub],
"the shed subscribed contract is flagged in-use for teardown"
);
assert!(
cache.contains(&local_sub),
"the local-client contract survives (ordered last)"
);
assert!(!cache.contains(&downstream_sub));
assert_eq!(
cache.stats().subscribed_evictions_total,
1,
"shedding a subscribed contract bumps the falsifier under AtCapacity"
);
assert_eq!(
cache.stats().oom_valve_evictions_total,
0,
"AtCapacity last-resort shed is NOT an OOM-valve eviction"
);
}
}