Files
arr/crates/arr-meta/src/cache.rs
T

290 lines
9.5 KiB
Rust

//! A time-to-live cache over raw response bodies, backed by files on disk.
//!
//! Keyed on a logical request key rather than the URL, so the API key never
//! becomes part of a cache key (see `client::request_url`). The key is
//! hashed into the filename rather than embedded verbatim, so a search
//! query or a title id never becomes readable in a directory listing.
//!
//! Bounded two ways: an entry older than `ttl` is dropped whether or not
//! anyone reads it, and the directory as a whole is capped at `max_bytes` —
//! age alone does not stop a busy day filling the disk. Both are enforced by
//! [`Cache::sweep`], which runs after every write and is also safe to call
//! on a schedule (the daily metadata tick, DESIGN.md §8).
//!
//! File IO here is synchronous. Bodies are TMDB JSON responses — at most a
//! few hundred KB — and this runs once per miss, not in a hot loop, so
//! blocking the calling task briefly is a fair trade for not pulling an
//! async-fs dependency into a crate that otherwise doesn't need one.
use std::fs;
use std::io;
use std::path::PathBuf;
use std::sync::atomic::{AtomicU64, Ordering};
use std::sync::Arc;
use std::time::{Duration, SystemTime};
const FILE_EXT: &str = "tmdb-cache";
#[derive(Debug)]
pub(crate) struct Cache {
dir: PathBuf,
ttl: Duration,
max_bytes: u64,
/// Whether this cache created `dir` itself (the default, process-unique
/// temp directory) rather than being pointed at one the caller owns. Only
/// a directory we created is ours to delete.
owns_dir: bool,
}
impl Cache {
pub(crate) fn new(
dir: PathBuf,
ttl: Duration,
max_bytes: u64,
owns_dir: bool,
) -> io::Result<Self> {
fs::create_dir_all(&dir)?;
Ok(Self {
dir,
ttl,
max_bytes,
owns_dir,
})
}
/// The cached body for `key`, if one is present and still fresh.
pub(crate) fn get(&self, key: &str) -> Option<Arc<str>> {
let path = self.path_for(key);
let metadata = fs::metadata(&path).ok()?;
let age = metadata.modified().ok()?.elapsed().unwrap_or_default();
if age >= self.ttl {
let _ = fs::remove_file(&path);
return None;
}
fs::read_to_string(&path).ok().map(Arc::from)
}
/// Write `body` for `key`, atomically: a temp file plus a rename, so a
/// killed process can never leave a half-written body that later reads
/// as valid JSON.
pub(crate) fn insert(&self, key: &str, body: &str) {
let path = self.path_for(key);
let tmp = self.tmp_path();
if fs::write(&tmp, body).is_err() {
return;
}
if fs::rename(&tmp, &path).is_err() {
let _ = fs::remove_file(&tmp);
return;
}
self.sweep();
}
pub(crate) fn remove(&self, key: &str) {
let _ = fs::remove_file(self.path_for(key));
}
/// Drop everything. The daily metadata refresh does not need this —
/// entries expire on their own — but a forced refresh from the UI does.
pub(crate) fn clear(&self) {
self.for_each_entry(|path, _modified, _len| {
let _ = fs::remove_file(path);
});
}
/// Evict every expired entry, then, if the directory is still over
/// `max_bytes`, the oldest survivors until it is not.
pub(crate) fn sweep(&self) {
let mut survivors = Vec::new();
self.for_each_entry(|path, modified, len| {
if modified.elapsed().unwrap_or_default() >= self.ttl {
let _ = fs::remove_file(&path);
} else {
survivors.push((path, modified, len));
}
});
let mut total: u64 = survivors.iter().map(|(_, _, len)| len).sum();
if total <= self.max_bytes {
return;
}
// Oldest first, so the size sweep behaves like the age one: the most
// recently fetched title is the one that survives.
survivors.sort_by_key(|(_, modified, _)| *modified);
for (path, _, len) in survivors {
if total <= self.max_bytes {
break;
}
if fs::remove_file(&path).is_ok() {
total = total.saturating_sub(len);
}
}
}
fn for_each_entry(&self, mut visit: impl FnMut(PathBuf, SystemTime, u64)) {
let Ok(read_dir) = fs::read_dir(&self.dir) else {
return;
};
for entry in read_dir.flatten() {
let path = entry.path();
if path.extension().is_none_or(|ext| ext != FILE_EXT) {
continue;
}
let Ok(metadata) = entry.metadata() else {
continue;
};
let Ok(modified) = metadata.modified() else {
continue;
};
visit(path, modified, metadata.len());
}
}
fn path_for(&self, key: &str) -> PathBuf {
self.dir
.join(format!("{:016x}.{FILE_EXT}", fnv1a64(key.as_bytes())))
}
fn tmp_path(&self) -> PathBuf {
static COUNTER: AtomicU64 = AtomicU64::new(0);
let unique = COUNTER.fetch_add(1, Ordering::Relaxed);
self.dir
.join(format!("{}-{unique}.{FILE_EXT}.tmp", std::process::id()))
}
}
impl Drop for Cache {
fn drop(&mut self) {
if self.owns_dir {
let _ = fs::remove_dir_all(&self.dir);
}
}
}
/// FNV-1a, 64-bit. Not cryptographic — it only needs to pick a filename —
/// but unlike `std`'s `DefaultHasher` it is stable across runs, so a
/// restarted process still hits its own cache from before.
fn fnv1a64(bytes: &[u8]) -> u64 {
const OFFSET_BASIS: u64 = 0xcbf2_9ce4_8422_2325;
const PRIME: u64 = 0x0000_0100_0000_01b3;
bytes.iter().fold(OFFSET_BASIS, |hash, &byte| {
(hash ^ u64::from(byte)).wrapping_mul(PRIME)
})
}
#[cfg(test)]
mod tests {
use super::Cache;
use std::time::Duration;
fn cache(ttl: Duration, max_bytes: u64) -> (tempfile::TempDir, Cache) {
let dir = tempfile::tempdir().expect("tempdir");
let cache = Cache::new(dir.path().to_owned(), ttl, max_bytes, false).expect("cache");
(dir, cache)
}
#[test]
fn hit_returns_what_was_inserted() {
let (_dir, cache) = cache(Duration::from_secs(60), 1024);
cache.insert("movie/1", "hello");
assert_eq!(cache.get("movie/1").as_deref(), Some("hello"));
}
#[test]
fn miss_is_none() {
let (_dir, cache) = cache(Duration::from_secs(60), 1024);
assert_eq!(cache.get("movie/absent"), None);
}
#[test]
fn an_expired_entry_is_deleted_from_disk_not_just_hidden() {
let (dir, cache) = cache(Duration::from_millis(1), 1024);
cache.insert("movie/1", "hello");
std::thread::sleep(Duration::from_millis(50));
assert_eq!(cache.get("movie/1"), None, "a stale entry must not hit");
let files: Vec<_> = std::fs::read_dir(dir.path())
.expect("read dir")
.filter_map(Result::ok)
.collect();
assert!(
files.is_empty(),
"expired entry should have been removed from disk, found {files:?}"
);
}
#[test]
fn sweep_evicts_expired_entries_without_being_read() {
let (dir, cache) = cache(Duration::from_millis(1), 1024);
cache.insert("movie/1", "hello");
std::thread::sleep(Duration::from_millis(50));
cache.sweep();
let count = std::fs::read_dir(dir.path())
.expect("read dir")
.filter_map(Result::ok)
.count();
assert_eq!(count, 0, "sweep should have deleted the expired entry");
}
#[test]
fn over_the_size_budget_evicts_the_oldest_entry_first() {
// A generous TTL, so only the size budget can be doing the evicting.
let (dir, cache) = cache(Duration::from_secs(60), 12);
cache.insert("movie/old", "0123456789"); // 10 bytes, written first
std::thread::sleep(Duration::from_millis(10));
cache.insert("movie/new", "0123456789"); // pushes total to 20 > 12
assert_eq!(
cache.get("movie/old"),
None,
"the older entry should have been evicted to stay under budget"
);
assert_eq!(
cache.get("movie/new").as_deref(),
Some("0123456789"),
"the newer entry should survive"
);
let total: u64 = std::fs::read_dir(dir.path())
.expect("read dir")
.filter_map(Result::ok)
.map(|entry| entry.metadata().expect("metadata").len())
.sum();
assert!(
total <= 12,
"directory should be back under budget, was {total}"
);
}
#[test]
fn dropping_an_owned_cache_removes_its_directory() {
let dir = tempfile::tempdir().expect("tempdir");
let owned_subdir = dir.path().join("owned");
let cache =
Cache::new(owned_subdir.clone(), Duration::from_secs(60), 1024, true).expect("cache");
cache.insert("movie/1", "hello");
drop(cache);
assert!(
!owned_subdir.exists(),
"an owned cache directory should be cleaned up on drop"
);
}
#[test]
fn dropping_a_borrowed_cache_leaves_its_directory() {
let (dir, cache) = cache(Duration::from_secs(60), 1024);
cache.insert("movie/1", "hello");
drop(cache);
assert!(
dir.path().exists(),
"a caller-supplied cache directory must survive the client that used it"
);
}
}