arama_cache/
types.rs

1//! Public types of the `arama-cache` facade.
2
3use std::path::{Path, PathBuf};
4
5use crate::Result;
6
7/// Result of a cache lookup.
8#[derive(Debug)]
9pub enum LookupResult<T> {
10    /// Cache hit: the file is unchanged and a payload was stored.
11    Hit(T),
12    /// The file changed since it was cached. The stored payload is no
13    /// longer valid and will be replaced on the next upsert.
14    Invalidated,
15    /// The file is not registered in the cache.
16    Miss,
17}
18
19/// Read-side capability shared by the image and video readers.
20pub trait CacheRead {
21    /// `true` when the cache entry for `path` exists and is fresh.
22    fn check(&self, path: &Path) -> Result<bool>;
23    /// Batch variant of [`check`](CacheRead::check), parallelized.
24    fn check_all(&self, paths: &[&Path]) -> Vec<(PathBuf, Result<bool>)>;
25    /// Canonicalized paths of every registered entry.
26    fn list_paths(&self) -> Result<Vec<String>>;
27}
28
29/// Per-directory aggregate of cached entries, for cache-management UIs
30/// (RFC 004).
31#[derive(Debug, Clone)]
32pub struct DirCacheSummary {
33    /// Canonical path of the directory containing the cached files.
34    pub dir_path: String,
35    /// Number of cached files directly in this directory.
36    pub file_count: usize,
37    /// Sum of the cached files' recorded sizes, in bytes.
38    pub total_size: u64,
39    /// Newest `updated_at` among the entries (unix seconds).
40    pub latest_cached_at: i64,
41}
42
43// ---------------------------------------------------------------------------
44// Images
45// ---------------------------------------------------------------------------
46
47/// Write request for the image cache.
48#[derive(Debug)]
49pub struct UpsertImageRequest {
50    pub path: PathBuf,
51    /// CLIP feature vector (one per image). `None` preserves the stored
52    /// value.
53    pub clip_vector: Option<Vec<f32>>,
54}
55
56/// An image cache entry.
57#[derive(Clone, Debug)]
58pub struct ImageCacheEntry {
59    /// Canonicalized path as stored in the database.
60    pub path: String,
61    /// Thumbnail file path. `None` when not generated.
62    pub thumbnail_path: Option<String>,
63    /// Feature vectors. `None` when not registered.
64    pub features: Option<ImageFeatures>,
65}
66
67#[derive(Clone, Debug, PartialEq)]
68pub struct ImageFeatures {
69    pub clip_vector: Vec<f32>,
70}
71
72// ---------------------------------------------------------------------------
73// Videos
74// ---------------------------------------------------------------------------
75
76/// Write request for the video cache.
77#[derive(Debug)]
78pub struct UpsertVideoRequest {
79    pub path: PathBuf,
80    /// Frame-averaged CLIP feature vector. `None` preserves the stored
81    /// value.
82    pub clip_vector: Option<Vec<f32>>,
83    /// Scene-averaged wav2vec2 feature vector. `None` preserves the
84    /// stored value.
85    pub wav2vec2_vector: Option<Vec<f32>>,
86}
87
88/// A video cache entry.
89#[derive(Debug)]
90pub struct VideoCacheEntry {
91    pub path: String,
92    pub thumbnail_path: Option<String>,
93    pub features: Option<VideoFeatures>,
94}
95
96#[derive(Debug, PartialEq)]
97pub struct VideoFeatures {
98    /// Frame-averaged CLIP feature vector.
99    pub clip_vector: Option<Vec<f32>>,
100    /// Scene-averaged wav2vec2 feature vector.
101    pub wav2vec2_vector: Option<Vec<f32>>,
102}
arama_cache/types.rs

arama_cache/
types.rs
