feat: add configurable ttl on stampede protected cache, eviction telemetry

Cargo.toml

@@ -26,8 +26,8 @@ homepage = "https://github.com/microsoft/oxidizer"
 anyspawn = { path = "crates/anyspawn", default-features = false, version = "0.5.0" }
 bytesbuf = { path = "crates/bytesbuf", default-features = false, version = "0.5.0" }
 bytesbuf_io = { path = "crates/bytesbuf_io", default-features = false, version = "0.5.0" }
-cachet = { path = "crates/cachet", default-features = false, version = "0.5.0" }
-cachet_memory = { path = "crates/cachet_memory", default-features = false, version = "0.2.0" }
+cachet = { path = "crates/cachet", default-features = false, version = "0.5.1" }
+cachet_memory = { path = "crates/cachet_memory", default-features = false, version = "0.2.1" }
 cachet_service = { path = "crates/cachet_service", default-features = false, version = "0.1.0" }
 cachet_tier = { path = "crates/cachet_tier", default-features = false, version = "0.1.0" }
 data_privacy = { path = "crates/data_privacy", default-features = false, version = "0.11.0" }

crates/cachet/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [0.5.1] - 2026-05-21
+
+- ✨ Features
+
+  - Add `get_or_insert_with` and `try_get_or_insert_with` methods that accept closures returning `CacheEntry<V>`, enabling per-entry TTL control on cache-miss computations.
+  - Add eviction telemetry via `cache.eviction` and `cache.expired`, opt-in through `InMemoryCacheBuilder::with_eviction_telemetry` together with the new `CacheBuilder::memory_with` helper.
+
 ## [0.5.0] - 2026-05-19
 
 - ✔️ Tasks

crates/cachet/Cargo.toml

@@ -4,7 +4,7 @@
 [package]
 name = "cachet"
 description = "A composable, customizable multi-tier caching library with rich feature support."
-version = "0.5.0"
+version = "0.5.1"
 readme = "README.md"
 keywords = ["oxidizer", "caching", "concurrency"]
 categories = ["caching", "concurrency"]
@@ -99,6 +99,10 @@ name = "refresh"
 harness = false
 required-features = ["test-util"]
 
+[[test]]
+name = "eviction"
+required-features = ["memory", "logs"]
+
 [[example]]
 name = "simple"
 required-features = ["memory"]

crates/cachet/README.md

@@ -256,7 +256,7 @@ See the `telemetry_subscriber` example for a complete demonstration.
 |Level|Events|
 |-----|------|
 |ERROR|`cache.get_error`, `cache.insert_error`, `cache.invalidate_error`, `cache.clear_error`|
-|INFO|`cache.expired`, `cache.refresh_miss`, `cache.inserted`, `cache.insert_rejected`, `cache.invalidated`, `cache.fallback`|
+|INFO|`cache.expired`, `cache.refresh_miss`, `cache.inserted`, `cache.insert_rejected`, `cache.invalidated`, `cache.fallback`, `cache.eviction`|
 |DEBUG|`cache.hit`, `cache.miss`, `cache.refresh_hit`, `cache.cleared`|
 
 
@@ -265,26 +265,26 @@ See the `telemetry_subscriber` example for a complete demonstration.
 This crate was developed as part of <a href="../..">The Oxidizer Project</a>. Browse this crate's <a href="https://github.com/microsoft/oxidizer/tree/main/crates/cachet">source code</a>.
 </sub>
 
- [__cargo_doc2readme_dependencies_info]: ggGkYW0CYXSEGy4k8ldDFPOhG2VNeXtD5nnKG6EPY6OfW5wBG8g18NOFNdxpYXKEG-n6c1asXb8uG6CeIkUqNVu-GxjETKbvQrZwG4I5xAXRHmeEYWSIgmhieXRlc2J1ZmUwLjUuMIJmY2FjaGV0ZTAuNS4wgm1jYWNoZXRfbWVtb3J5ZTAuMi4wgm5jYWNoZXRfc2VydmljZWUwLjEuMIJrY2FjaGV0X3RpZXJlMC4xLjCCZHRpY2tlMC4zLjCCZ3RyYWNpbmdmMC4xLjQ0gml1bmlmbGlnaHRlMC4yLjA
- [__link0]: https://docs.rs/cachet/0.5.0/cachet/?search=TimeToRefresh
+ [__cargo_doc2readme_dependencies_info]: ggGmYW0CYXZlMC43LjJhdIQbLiTyV0MU86EbZU15e0PmecoboQ9jo59bnAEbyDXw04U13GlhYvRhcoQbg_hDqE88LP4bMh0J5Y4y4Osb0zDJ1kwqOsoblCGrm49Rx2thZIiCaGJ5dGVzYnVmZTAuNS4wgmZjYWNoZXRlMC41LjGCbWNhY2hldF9tZW1vcnllMC4yLjGCbmNhY2hldF9zZXJ2aWNlZTAuMS4wgmtjYWNoZXRfdGllcmUwLjEuMIJkdGlja2UwLjMuMIJndHJhY2luZ2YwLjEuNDSCaXVuaWZsaWdodGUwLjIuMA
+ [__link0]: https://docs.rs/cachet/0.5.1/cachet/?search=TimeToRefresh
  [__link1]: https://crates.io/crates/uniflight/0.2.0
  [__link10]: https://docs.rs/cachet_tier/0.1.0/cachet_tier/?search=CacheTier
- [__link11]: https://docs.rs/cachet/0.5.0/cachet/?search=InsertPolicy
- [__link12]: https://docs.rs/cachet/0.5.0/cachet/?search=TimeToRefresh
+ [__link11]: https://docs.rs/cachet/0.5.1/cachet/?search=InsertPolicy
+ [__link12]: https://docs.rs/cachet/0.5.1/cachet/?search=TimeToRefresh
  [__link13]: https://docs.rs/cachet_tier/0.1.0/cachet_tier/?search=Error
  [__link14]: https://crates.io/crates/cachet_tier/0.1.0
- [__link15]: https://crates.io/crates/cachet_memory/0.2.0
+ [__link15]: https://crates.io/crates/cachet_memory/0.2.1
  [__link16]: https://docs.rs/moka
  [__link17]: https://crates.io/crates/cachet_service/0.1.0
- [__link18]: https://docs.rs/cachet/0.5.0/cachet/?search=telemetry::attributes
+ [__link18]: https://docs.rs/cachet/0.5.1/cachet/?search=telemetry::attributes
  [__link19]: https://docs.rs/bytesbuf/0.5.0/bytesbuf/?search=BytesView
- [__link2]: https://docs.rs/cachet/0.5.0/cachet/?search=CacheBuilder::stampede_protection
+ [__link2]: https://docs.rs/cachet/0.5.1/cachet/?search=CacheBuilder::stampede_protection
  [__link20]: https://crates.io/crates/tracing/0.1.44
- [__link21]: https://docs.rs/cachet/0.5.0/cachet/?search=telemetry::attributes
+ [__link21]: https://docs.rs/cachet/0.5.1/cachet/?search=telemetry::attributes
  [__link3]: https://docs.rs/cachet_tier/0.1.0/cachet_tier/?search=CacheTier
  [__link4]: https://docs.rs/cachet_tier/0.1.0/cachet_tier/?search=DynamicCache
- [__link5]: https://docs.rs/cachet/0.5.0/cachet/?search=InsertPolicy
+ [__link5]: https://docs.rs/cachet/0.5.1/cachet/?search=InsertPolicy
  [__link6]: https://docs.rs/tick/0.3.0/tick/?search=Clock
- [__link7]: https://docs.rs/cachet/0.5.0/cachet/?search=Cache
- [__link8]: https://docs.rs/cachet/0.5.0/cachet/?search=CacheBuilder
+ [__link7]: https://docs.rs/cachet/0.5.1/cachet/?search=Cache
+ [__link8]: https://docs.rs/cachet/0.5.1/cachet/?search=CacheBuilder
  [__link9]: https://docs.rs/cachet_tier/0.1.0/cachet_tier/?search=CacheEntry

crates/cachet/src/builder/buildable.rs

@@ -42,7 +42,12 @@ where
     }
 
     fn build_tier(self, clock: Clock, telemetry: CacheTelemetry) -> Self::TierOutput {
-        CacheWrapper::new(type_name::<CT>(self.name), self.storage, clock, self.ttl, telemetry, self.policy)
+        let name = type_name::<CT>(self.name);
+        #[cfg(feature = "memory")]
+        if let Some(hook) = &self.eviction_hook {
+            hook.init(telemetry.clone(), name);
+        }
+        CacheWrapper::new(name, self.storage, clock, self.ttl, telemetry, self.policy)
     }
 }
 

crates/cachet/src/builder/cache.rs

@@ -3,15 +3,19 @@
 
 use std::hash::Hash;
 use std::marker::PhantomData;
+#[cfg(feature = "memory")]
+use std::sync::Arc;
 use std::time::Duration;
 
 #[cfg(feature = "memory")]
-use cachet_memory::InMemoryCache;
+use cachet_memory::{InMemoryCache, InMemoryCacheBuilder};
 use tick::Clock;
 
 use super::buildable::Buildable;
 use super::fallback::FallbackBuilder;
 use super::sealed::{CacheTierBuilder, Sealed};
+#[cfg(feature = "memory")]
+use crate::eviction::EvictionHook;
 use crate::policy::InsertPolicy;
 use crate::telemetry::CacheTelemetry;
 use crate::{Cache, CacheTier};
@@ -44,6 +48,8 @@ pub struct CacheBuilder<K, V, CT = ()> {
     pub(crate) clock: Clock,
     pub(crate) telemetry: CacheTelemetry,
     pub(crate) stampede_protection: bool,
+    #[cfg(feature = "memory")]
+    pub(crate) eviction_hook: Option<Arc<EvictionHook>>,
     pub(crate) _phantom: PhantomData<(K, V)>,
 }
 
@@ -57,6 +63,8 @@ impl<K, V> CacheBuilder<K, V, ()> {
             clock,
             telemetry: CacheTelemetry::new(),
             stampede_protection: false,
+            #[cfg(feature = "memory")]
+            eviction_hook: None,
             _phantom: PhantomData,
         }
     }
@@ -90,6 +98,8 @@ impl<K, V> CacheBuilder<K, V, ()> {
             clock: self.clock,
             telemetry: self.telemetry,
             stampede_protection: self.stampede_protection,
+            #[cfg(feature = "memory")]
+            eviction_hook: self.eviction_hook,
             _phantom: PhantomData,
         }
     }
@@ -115,7 +125,50 @@ impl<K, V> CacheBuilder<K, V, ()> {
         K: Hash + Eq + Clone + Send + Sync + 'static,
         V: Clone + Send + Sync + 'static,
     {
-        self.storage(InMemoryCache::<K, V>::new())
+        self.memory_with(|b| b)
+    }
+
+    /// Configures the cache to use in-memory storage, exposing the inner
+    /// [`InMemoryCacheBuilder`] for additional configuration (capacity, TTL,
+    /// eviction policy, custom hasher, etc.).
+    ///
+    /// Call [`InMemoryCacheBuilder::with_eviction_telemetry`] inside the
+    /// closure to emit `cache.eviction` on capacity evictions and
+    /// `cache.expired` on background TTL/TTI expiry.
+    ///
+    /// # Panics
+    ///
+    /// Panics if the configured [`InMemoryCacheBuilder`] fails validation
+    /// (for example, `max_capacity < initial_capacity`).
+    ///
+    /// # Examples
+    ///
+    /// ```no_run
+    /// use cachet::Cache;
+    /// use tick::Clock;
+    ///
+    /// let clock = Clock::new_tokio();
+    /// let cache = Cache::builder::<String, i32>(clock)
+    ///     .memory_with(|b| b.max_capacity(1_000).with_eviction_telemetry())
+    ///     .build();
+    /// ```
+    #[cfg(feature = "memory")]
+    #[must_use]
+    pub fn memory_with<F>(mut self, configure: F) -> CacheBuilder<K, V, InMemoryCache<K, V>>
+    where
+        K: Hash + Eq + Clone + Send + Sync + 'static,
+        V: Clone + Send + Sync + 'static,
+        F: FnOnce(InMemoryCacheBuilder<K, V>) -> InMemoryCacheBuilder<K, V>,
+    {
+        let mut builder = configure(InMemoryCacheBuilder::<K, V>::new());
+        if builder.eviction_telemetry_enabled() {
+            let hook = Arc::new(EvictionHook::new());
+            let hook_for_listener = Arc::clone(&hook);
+            builder = builder.on_eviction(move |cause| hook_for_listener.handle(cause));
+            self.eviction_hook = Some(hook);
+        }
+        let storage = builder.build().expect("InMemoryCacheBuilder configuration must be valid");
+        self.storage(storage)
     }
 
     /// Configures the cache to use a service as the storage backend.