use crate::store::{DistributedStore, MemoryStore};
use anyhow::{Context, Result};
use serde::{Deserialize, Serialize};
use std::sync::Arc;
use std::time::{Duration, SystemTime};
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub enum IsrPolicy {
Static,
Revalidate {
max_age: Duration,
},
OnDemand,
}
impl IsrPolicy {
pub fn revalidate(max_age: Duration) -> Self {
Self::Revalidate { max_age }
}
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct IsrEntry {
pub html: String,
pub generated_at: SystemTime,
pub policy: IsrPolicy,
pub etag: String,
}
impl IsrEntry {
pub fn new(html: impl Into<String>, policy: IsrPolicy) -> Self {
let html = html.into();
let etag = compute_etag(&html);
Self {
html,
generated_at: SystemTime::now(),
policy,
etag,
}
}
pub fn is_stale(&self) -> bool {
match &self.policy {
IsrPolicy::Static => false,
IsrPolicy::Revalidate { max_age } => self.age() > *max_age,
IsrPolicy::OnDemand => true,
}
}
pub fn is_fresh(&self) -> bool {
!self.is_stale()
}
pub fn age(&self) -> Duration {
self.generated_at.elapsed().unwrap_or(Duration::ZERO)
}
}
const DEFAULT_NAMESPACE: &str = "krab:isr";
const KEY_SEPARATOR: char = '\u{1}';
const LEASE_SEPARATOR: char = '\u{2}';
const RENDER_LEASE_TTL: Duration = Duration::from_secs(10);
const STALE_RETENTION_FACTOR: u32 = 10;
const MIN_RETENTION: Duration = Duration::from_secs(3600);
#[derive(Clone)]
pub struct IsrCache {
store: Arc<dyn DistributedStore>,
namespace: String,
}
impl std::fmt::Debug for IsrCache {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
f.debug_struct("IsrCache")
.field("namespace", &self.namespace)
.finish_non_exhaustive()
}
}
impl Default for IsrCache {
fn default() -> Self {
Self::new()
}
}
impl IsrCache {
pub fn new() -> Self {
Self::with_store(Arc::new(MemoryStore::new()))
}
pub fn with_store(store: Arc<dyn DistributedStore>) -> Self {
Self {
store,
namespace: DEFAULT_NAMESPACE.to_string(),
}
}
pub fn with_namespace(mut self, namespace: impl Into<String>) -> Self {
self.namespace = namespace.into();
self
}
pub async fn put(&self, path: &str, html: impl Into<String>, policy: IsrPolicy) -> Result<()> {
let entry = IsrEntry::new(html, policy);
let ttl = retention_for(&entry.policy);
let encoded = serde_json::to_string(&entry).context("failed to encode ISR entry")?;
self.store
.set(&self.key(path), &encoded, ttl)
.await
.with_context(|| format!("failed to cache ISR entry for {path}"))
}
pub async fn get(&self, path: &str) -> Result<Option<IsrEntry>> {
let Some(raw) = self.store.get(&self.key(path)).await? else {
return Ok(None);
};
match serde_json::from_str::<IsrEntry>(&raw) {
Ok(entry) => Ok(Some(entry)),
Err(error) => {
tracing::warn!(
event = "isr_entry_decode_failed",
path,
%error,
"discarding an ISR entry written in an incompatible format"
);
Ok(None)
}
}
}
pub async fn invalidate(&self, path: &str) -> Result<bool> {
self.store.delete(&self.key(path)).await
}
pub async fn invalidate_prefix(&self, prefix: &str) -> Result<usize> {
let full_prefix = self.key(prefix);
let keys = self.store.keys_with_prefix(&full_prefix).await?;
let boundary_exempt = prefix.is_empty() || prefix.ends_with('/');
let mut removed = 0;
for key in keys {
if !boundary_exempt {
let on_segment_boundary = key
.strip_prefix(&full_prefix)
.map(|rest| rest.is_empty() || rest.starts_with('/'))
.unwrap_or(false);
if !on_segment_boundary {
continue;
}
}
if self.store.delete(&key).await? {
removed += 1;
}
}
Ok(removed)
}
pub async fn invalidate_all(&self) -> Result<usize> {
self.invalidate_prefix("").await
}
pub async fn len(&self) -> Result<usize> {
Ok(self.store.keys_with_prefix(&self.key("")).await?.len())
}
pub async fn is_empty(&self) -> Result<bool> {
Ok(self.len().await? == 0)
}
pub async fn stale_paths(&self) -> Result<Vec<String>> {
let prefix = self.key("");
let mut stale = Vec::new();
for key in self.store.keys_with_prefix(&prefix).await? {
let Some(path) = key.strip_prefix(&prefix) else {
continue;
};
if let Some(entry) = self.get(path).await? {
if entry.is_stale() {
stale.push(path.to_string());
}
}
}
Ok(stale)
}
pub async fn serve(&self, path: &str) -> Result<Option<(String, bool)>> {
Ok(self
.get(path)
.await?
.map(|entry| (entry.html.clone(), entry.is_stale())))
}
pub async fn serve_or_lease(&self, path: &str) -> Result<IsrServeOutcome> {
if let Some(entry) = self.get(path).await? {
return Ok(IsrServeOutcome::Hit(entry));
}
match self
.store
.set_if_absent(&self.lease_key(path), "1", RENDER_LEASE_TTL)
.await
{
Ok(true) => Ok(IsrServeOutcome::MissAcquired),
Ok(false) => Ok(IsrServeOutcome::MissLocked),
Err(error) => {
tracing::warn!(
event = "isr_render_lease_failed",
path,
%error,
"lease store unavailable; failing open to render"
);
Ok(IsrServeOutcome::MissAcquired)
}
}
}
pub async fn release_lease(&self, path: &str) -> Result<bool> {
self.store.delete(&self.lease_key(path)).await
}
fn key(&self, path: &str) -> String {
format!("{}{}{}", self.namespace, KEY_SEPARATOR, path)
}
fn lease_key(&self, path: &str) -> String {
format!("{}{}{}", self.namespace, LEASE_SEPARATOR, path)
}
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum IsrServeOutcome {
Hit(IsrEntry),
MissAcquired,
MissLocked,
}
fn retention_for(policy: &IsrPolicy) -> Duration {
match policy {
IsrPolicy::Static => Duration::ZERO,
IsrPolicy::Revalidate { max_age } => max_age
.saturating_mul(STALE_RETENTION_FACTOR)
.max(MIN_RETENTION),
IsrPolicy::OnDemand => MIN_RETENTION,
}
}
fn compute_etag(html: &str) -> String {
use sha2::{Digest, Sha256};
let digest = Sha256::digest(html.as_bytes());
let hex = format!("{:x}", digest);
format!("\"krab-{}\"", &hex[..16])
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn static_policy_never_stale() {
let entry = IsrEntry::new("<h1>Home</h1>", IsrPolicy::Static);
assert!(entry.is_fresh());
assert!(!entry.is_stale());
}
#[test]
fn on_demand_policy_always_stale() {
let entry = IsrEntry::new("<h1>Home</h1>", IsrPolicy::OnDemand);
assert!(entry.is_stale());
assert!(!entry.is_fresh());
}
#[test]
fn revalidate_policy_staleness() {
let entry = IsrEntry::new(
"<h1>Home</h1>",
IsrPolicy::revalidate(Duration::from_millis(1)),
);
std::thread::sleep(Duration::from_millis(5));
assert!(entry.is_stale());
}
#[test]
fn etag_computed() {
let entry = IsrEntry::new("<h1>Hello</h1>", IsrPolicy::Static);
assert!(entry.etag.starts_with("\"krab-"));
assert!(entry.etag.ends_with("\""));
}
#[test]
fn an_entry_from_the_future_reports_zero_age_rather_than_underflowing() {
let entry = IsrEntry {
html: "<h1>Home</h1>".to_string(),
generated_at: SystemTime::now() + Duration::from_secs(60),
policy: IsrPolicy::revalidate(Duration::from_secs(1)),
etag: "\"krab-0\"".to_string(),
};
assert_eq!(entry.age(), Duration::ZERO);
assert!(entry.is_fresh());
}
#[tokio::test]
async fn cache_put_get_invalidate() {
let cache = IsrCache::new();
assert!(cache.is_empty().await.unwrap());
cache
.put("/", "<h1>Home</h1>", IsrPolicy::Static)
.await
.unwrap();
cache
.put("/about", "<h1>About</h1>", IsrPolicy::Static)
.await
.unwrap();
assert_eq!(cache.len().await.unwrap(), 2);
let entry = cache.get("/").await.unwrap().unwrap();
assert_eq!(entry.html, "<h1>Home</h1>");
assert!(cache.invalidate("/").await.unwrap());
assert_eq!(cache.len().await.unwrap(), 1);
assert!(cache.get("/").await.unwrap().is_none());
}
#[tokio::test]
async fn cache_invalidate_prefix() {
let cache = IsrCache::new();
cache.put("/blog/a", "A", IsrPolicy::Static).await.unwrap();
cache.put("/blog/b", "B", IsrPolicy::Static).await.unwrap();
cache
.put("/about", "About", IsrPolicy::Static)
.await
.unwrap();
assert_eq!(cache.invalidate_prefix("/blog").await.unwrap(), 2);
assert_eq!(cache.len().await.unwrap(), 1);
assert!(cache.get("/about").await.unwrap().is_some());
}
#[tokio::test]
async fn cache_invalidate_all() {
let cache = IsrCache::new();
cache.put("/a", "A", IsrPolicy::Static).await.unwrap();
cache.put("/b", "B", IsrPolicy::Static).await.unwrap();
assert_eq!(cache.invalidate_all().await.unwrap(), 2);
assert!(cache.is_empty().await.unwrap());
}
#[tokio::test]
async fn serve_stale_while_revalidate() {
let cache = IsrCache::new();
cache
.put(
"/page",
"<h1>Page</h1>",
IsrPolicy::revalidate(Duration::from_millis(1)),
)
.await
.unwrap();
let (html, _needs_reval) = cache.serve("/page").await.unwrap().unwrap();
assert_eq!(html, "<h1>Page</h1>");
std::thread::sleep(Duration::from_millis(5));
let (html2, needs_reval2) = cache.serve("/page").await.unwrap().unwrap();
assert_eq!(html2, "<h1>Page</h1>", "stale content is still served");
assert!(needs_reval2, "and flagged for revalidation");
}
#[tokio::test]
async fn stale_paths_collection() {
let cache = IsrCache::new();
cache.put("/static", "S", IsrPolicy::Static).await.unwrap();
cache
.put("/dynamic", "D", IsrPolicy::OnDemand)
.await
.unwrap();
let stale = cache.stale_paths().await.unwrap();
assert!(stale.contains(&"/dynamic".to_string()));
assert!(!stale.contains(&"/static".to_string()));
}
#[tokio::test]
async fn two_caches_sharing_a_store_agree() {
let store = Arc::new(MemoryStore::new());
let pod_a = IsrCache::with_store(store.clone());
let pod_b = IsrCache::with_store(store);
pod_a.put("/blog/x", "v1", IsrPolicy::Static).await.unwrap();
let seen = pod_b.get("/blog/x").await.unwrap().unwrap();
assert_eq!(seen.html, "v1");
assert_eq!(pod_b.invalidate_prefix("/blog").await.unwrap(), 1);
assert!(
pod_a.get("/blog/x").await.unwrap().is_none(),
"invalidation on one replica must clear the shared entry, not a local copy"
);
}
#[tokio::test]
async fn namespaces_isolate_caches_on_a_shared_store() {
let store = Arc::new(MemoryStore::new());
let site = IsrCache::with_store(store.clone()).with_namespace("krab:isr:site");
let docs = IsrCache::with_store(store).with_namespace("krab:isr:docs");
site.put("/index", "site", IsrPolicy::Static).await.unwrap();
docs.put("/index", "docs", IsrPolicy::Static).await.unwrap();
assert_eq!(site.get("/index").await.unwrap().unwrap().html, "site");
assert_eq!(docs.get("/index").await.unwrap().unwrap().html, "docs");
site.invalidate_all().await.unwrap();
assert!(site.is_empty().await.unwrap());
assert_eq!(
docs.len().await.unwrap(),
1,
"clearing one namespace must not touch another"
);
}
#[tokio::test]
async fn an_entry_survives_a_round_trip_through_the_store() {
let cache = IsrCache::new();
let policy = IsrPolicy::revalidate(Duration::from_secs(30));
cache
.put("/round-trip", "<p>hi</p>", policy.clone())
.await
.unwrap();
let entry = cache.get("/round-trip").await.unwrap().unwrap();
assert_eq!(entry.html, "<p>hi</p>");
assert_eq!(entry.policy, policy);
assert!(entry.etag.starts_with("\"krab-"));
assert!(entry.is_fresh());
}
#[tokio::test]
async fn an_undecodable_stored_value_is_treated_as_a_miss() {
let store = Arc::new(MemoryStore::new());
store
.set("krab:isr\u{1}/broken", "not json", Duration::ZERO)
.await
.unwrap();
let cache = IsrCache::with_store(store);
assert!(cache.get("/broken").await.unwrap().is_none());
}
#[tokio::test]
async fn invalidate_all_leaves_sibling_namespaces_untouched() {
let store = Arc::new(MemoryStore::new());
let default_ns = IsrCache::with_store(store.clone());
let site = IsrCache::with_store(store).with_namespace("krab:isr:site");
default_ns.put("/a", "A", IsrPolicy::Static).await.unwrap();
site.put("/a", "site-A", IsrPolicy::Static).await.unwrap();
assert_eq!(default_ns.invalidate_all().await.unwrap(), 1);
assert!(default_ns.is_empty().await.unwrap());
assert_eq!(
site.len().await.unwrap(),
1,
"invalidating namespace \"krab:isr\" must not reach \"krab:isr:site\""
);
assert_eq!(site.get("/a").await.unwrap().unwrap().html, "site-A");
}
#[tokio::test]
async fn invalidate_prefix_respects_path_segment_boundaries() {
let cache = IsrCache::new();
cache
.put("/blog", "index", IsrPolicy::Static)
.await
.unwrap();
cache.put("/blog/a", "A", IsrPolicy::Static).await.unwrap();
cache
.put("/blog-archive", "old", IsrPolicy::Static)
.await
.unwrap();
assert_eq!(
cache.invalidate_prefix("/blog").await.unwrap(),
2,
"only /blog and /blog/a sit on the /blog segment boundary"
);
assert!(
cache.get("/blog-archive").await.unwrap().is_some(),
"/blog-archive merely shares characters with /blog and must survive"
);
}
#[tokio::test]
async fn invalidate_prefix_with_trailing_slash_keeps_plain_prefix_semantics() {
let cache = IsrCache::new();
cache.put("/blog/a", "A", IsrPolicy::Static).await.unwrap();
cache
.put("/blog/ab", "AB", IsrPolicy::Static)
.await
.unwrap();
assert_eq!(cache.invalidate_prefix("/blog/a").await.unwrap(), 1);
assert!(cache.get("/blog/ab").await.unwrap().is_some());
assert_eq!(cache.invalidate_prefix("/blog/").await.unwrap(), 1);
assert!(cache.is_empty().await.unwrap());
}
#[tokio::test]
async fn concurrent_cold_serves_run_the_renderer_once() {
use std::sync::atomic::{AtomicUsize, Ordering};
let cache = IsrCache::with_store(Arc::new(MemoryStore::new()));
let renders = Arc::new(AtomicUsize::new(0));
let mut tasks = Vec::new();
for _ in 0..16 {
let cache = cache.clone();
let renders = renders.clone();
tasks.push(tokio::spawn(async move {
match cache.serve_or_lease("/cold").await.unwrap() {
IsrServeOutcome::Hit(entry) => entry.html,
IsrServeOutcome::MissAcquired => {
renders.fetch_add(1, Ordering::SeqCst);
cache
.put("/cold", "<h1>rendered</h1>", IsrPolicy::Static)
.await
.unwrap();
cache.release_lease("/cold").await.unwrap();
"<h1>rendered</h1>".to_string()
}
IsrServeOutcome::MissLocked => {
for _ in 0..100 {
tokio::time::sleep(Duration::from_millis(5)).await;
if let Some(entry) = cache.get("/cold").await.unwrap() {
return entry.html;
}
}
panic!("winner never populated the cache");
}
}
}));
}
for task in tasks {
assert_eq!(task.await.unwrap(), "<h1>rendered</h1>");
}
assert_eq!(
renders.load(Ordering::SeqCst),
1,
"a cold-miss burst must render exactly once"
);
}
#[tokio::test]
async fn releasing_the_lease_lets_the_next_miss_acquire_it() {
let cache = IsrCache::new();
assert_eq!(
cache.serve_or_lease("/x").await.unwrap(),
IsrServeOutcome::MissAcquired
);
assert_eq!(
cache.serve_or_lease("/x").await.unwrap(),
IsrServeOutcome::MissLocked
);
assert!(cache.release_lease("/x").await.unwrap());
assert_eq!(
cache.serve_or_lease("/x").await.unwrap(),
IsrServeOutcome::MissAcquired
);
}
#[tokio::test]
async fn render_leases_do_not_appear_as_cache_entries() {
let cache = IsrCache::new();
assert_eq!(
cache.serve_or_lease("/leased").await.unwrap(),
IsrServeOutcome::MissAcquired
);
assert!(cache.is_empty().await.unwrap());
assert!(cache.stale_paths().await.unwrap().is_empty());
assert_eq!(cache.invalidate_all().await.unwrap(), 0);
assert_eq!(
cache.serve_or_lease("/leased").await.unwrap(),
IsrServeOutcome::MissLocked
);
}
#[tokio::test]
async fn serve_or_lease_returns_hit_after_populate() {
let cache = IsrCache::new();
cache
.put("/warm", "<p>warm</p>", IsrPolicy::Static)
.await
.unwrap();
match cache.serve_or_lease("/warm").await.unwrap() {
IsrServeOutcome::Hit(entry) => {
assert_eq!(entry.html, "<p>warm</p>");
assert!(!entry.is_stale());
}
other => panic!("expected a hit, got {other:?}"),
}
}
#[test]
fn retention_outlives_max_age_so_stale_entries_can_still_be_served() {
let max_age = Duration::from_secs(600);
let retention = retention_for(&IsrPolicy::revalidate(max_age));
assert!(
retention > max_age,
"expiring at max_age would make every revalidation a cache miss"
);
assert_eq!(retention, max_age * STALE_RETENTION_FACTOR);
}
#[test]
fn static_entries_are_stored_without_expiry() {
assert_eq!(retention_for(&IsrPolicy::Static), Duration::ZERO);
}
#[test]
fn short_max_age_still_gets_a_usable_retention_floor() {
let retention = retention_for(&IsrPolicy::revalidate(Duration::from_secs(1)));
assert_eq!(retention, MIN_RETENTION);
}
}
#[cfg(test)]
mod etag_stability_tests {
use super::*;
#[test]
fn etag_is_a_pinned_function_of_the_content() {
assert_eq!(compute_etag("<h1>hello</h1>"), "\"krab-4db7ef630005c462\"");
assert_eq!(compute_etag(""), "\"krab-e3b0c44298fc1c14\"");
}
#[test]
fn etag_differs_for_different_content_and_repeats_for_the_same() {
assert_eq!(compute_etag("<p>a</p>"), compute_etag("<p>a</p>"));
assert_ne!(compute_etag("<p>a</p>"), compute_etag("<p>b</p>"));
}
#[test]
fn etag_keeps_its_rendered_shape() {
let etag = compute_etag("anything");
assert!(etag.starts_with("\"krab-"));
assert!(etag.ends_with('"'));
assert_eq!(etag.len(), 23);
assert!(etag["\"krab-".len()..etag.len() - 1]
.chars()
.all(|c| c.is_ascii_hexdigit()));
}
}