Struct DiskCache 

pub struct DiskCache {
    pub(super) cache_dir: PathBuf,
    pub(super) write_gc_lock: Arc<RwLock<()>>,
    pub(crate) index_walk: Arc<Semaphore>,
}

Content-addressable disk cache.

Fields

cache_dir: PathBuf

write_gc_lock: Arc<RwLock<()>>

index_walk: Arc<Semaphore>

One remove_by_key_prefix at a time, process-wide.

The removal walks the whole index twice, and the second walk holds write_gc_lock.write_owned() for its duration. tokio’s RwLock is write-preferring, so overlapping removals starve every cache write in the process, and a walk costs exactly the same for a key nothing was ever stored under. Lives on the cache, not on Admission, so every caller gets the bound without learning it exists, and the permit is carried INTO both blocking closures the same way the GC guard is: a permit held by the async fn would be released when a client drops the request mid-walk, while the walk itself runs on.

Implementations

impl DiskCache

pub async fn new(cache_dir: &str) -> Self

Create a new cache in the specified directory.

pub fn generate_key(data: &[u8]) -> String

Generate a cache key from file content (SHA256 hash).

pub async fn get<T: DeserializeOwned>( &self, key: &str, ) -> Result<Option<T>, ApiError>

Get a cached value by key.

pub async fn set<T: Serialize>( &self, key: &str, value: &T, ) -> Result<(), ApiError>

Set a cached value.

Serializes and then delegates to Self::set_bytes, so there is exactly one body that takes the write_gc_lock read guard around a cacache::write – the invariant cannot drift between the two entry points.

pub async fn has(&self, key: &str) -> Result<bool, ApiError>

Whether the index holds an entry for key. An index lookup only: the content is not read, so this is the cheap pre-filter, never the decision a reader acts on.

Ok(false) is “absent”; a lookup that FAILS is an error, not an absence, so a caller answering 404 on false still answers a broken cache store with 500 CACHE_ERROR (#5750 review). cacache::metadata answers Ok(None) for a key it has no entry for.

pub async fn remove(&self, key: &str) -> Result<(), ApiError>

Remove a cached entry.

pub async fn clear(&self) -> Result<(), ApiError>

Clear all cached entries.

pub async fn get_bytes(&self, key: &str) -> Result<Option<Vec<u8>>, ApiError>

Get raw bytes from cache (for Parquet responses).

pub async fn set_bytes(&self, key: &str, data: &[u8]) -> Result<(), ApiError>

Set raw bytes in cache.

pub async fn stats(&self) -> Result<CacheStats, ApiError>

Cache-wide entry count and total content size in bytes, for the /api/v1/metrics gauges (issue #3636). Sums Metadata::size across every index entry; entries sharing a deduplicated content blob are each counted once (as stored), matching what remove_by_key_prefix treats as “still referenced”.

impl DiskCache

pub async fn remove_by_key_prefix( &self, key_prefix: &str, ) -> Result<usize, ApiError>

Remove every index entry whose key is key_prefix itself or starts with "{key_prefix}-" (issue #3636). One source file fans out into several entries under the same hash prefix – the plain request key, the -json-v2, -parquet-vN, -parquet-metadata-v4 and -symbolic-v1 variants, each combination of opening-filter and quality suffix – and DELETE /api/v1/cache/{key} (handed the file hash its cache_key resolves to) is meant to drop all of them for that file in one call.

The underlying store is content-addressable: two different source files can produce byte-identical output (the issue’s example is two different IFCs that both emit an empty symbolic-data payload) and then share one content blob across two index entries. So this removes INDEX ENTRIES first – an index-only removal (cacache::remove) is exactly the operation the issue’s own hand-pruning experiment found safe: leaving a blob temporarily orphaned makes it unreachable but never makes a surviving entry read as corrupt, whereas removing a blob a live index entry still points at does (their write-up reproduced the resulting 500s). Only once every matching index entry is gone does this walk the remaining index and drop content blobs that nothing references any more; a blob still referenced by an unrelated entry is left alone.

Returns the number of index entries removed. Zero is a normal, successful result for a prefix nothing was ever cached under, or that already had its entries removed – deleting an absent entry is a no-op, not an error, so a retried or duplicate DELETE stays safe.

Trait Implementations

impl Clone for DiskCache

fn clone(&self) -> DiskCache

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for DiskCache

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.