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 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 keys = self.store.keys_with_prefix(&self.key(prefix)).await?;
let mut removed = 0;
for key in keys {
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())))
}
fn key(&self, path: &str) -> String {
format!("{}:{}", self.namespace, path)
}
}
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 std::hash::{Hash, Hasher};
let mut hasher = std::collections::hash_map::DefaultHasher::new();
html.hash(&mut hasher);
format!("\"krab-{:016x}\"", hasher.finish())
}
#[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:/broken", "not json", Duration::ZERO)
.await
.unwrap();
let cache = IsrCache::with_store(store);
assert!(cache.get("/broken").await.unwrap().is_none());
}
#[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);
}
}