290 lines
9.5 KiB
Rust
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"
|
|
);
|
|
}
|
|
}
|