init

crates/pdfs-core/src/auth.rs

@@ -35,7 +35,7 @@ pub struct StoredSession {
 }
 
 impl StoredSession {
-    fn into_params(&self) -> ResumeParameters {
+    fn to_params(&self) -> ResumeParameters {
         ResumeParameters {
             session_id: self.session_id.clone().into(),
             username: self.username.clone(),
@@ -122,11 +122,25 @@ pub fn logout() -> Result<()> {
 
 /// Resume a persisted session and build an authenticated Drive client.
 ///
-/// Re-persists tokens afterward in case the refresh path rotated them. Returns
-/// `Error::NotLoggedIn` when no session has been saved.
+/// Returns `Error::NotLoggedIn` when no session has been saved. The caller is
+/// responsible for persisting rotated tokens over the session's lifetime via
+/// [`persist`] — Proton refresh tokens are single-use, so a refresh that is not
+/// written back leaves the keyring holding a stale (now-invalid) refresh token,
+/// and the next resume fails with `InvalidRefreshToken`.
 pub async fn resume_client() -> Result<(ProtonDriveClient, ProtonApiSession)> {
     let stored = load()?;
-    let session = ProtonApiSession::resume(client_config(), stored.into_params())?;
+    let session = ProtonApiSession::resume(client_config(), stored.to_params())?;
     let client = ProtonDriveClient::new(&session, stored.mailbox_password.clone().into_bytes());
     Ok((client, session))
 }
+
+/// Write the session's current tokens back to the keyring.
+///
+/// The session does not carry the mailbox password (it is only needed to rebuild
+/// the key chain on resume), so it is re-read from the existing stored blob and
+/// preserved. Call whenever the session may have rotated its tokens through the
+/// 401-refresh path so a later [`resume_client`] presents a live refresh token.
+pub async fn persist(session: &ProtonApiSession) -> Result<()> {
+    let mailbox_password = load()?.mailbox_password;
+    save(session, &mailbox_password).await
+}

crates/pdfs-core/src/cache.rs

@@ -0,0 +1,549 @@
+//! On-disk content cache and pin registry.
+//!
+//! Files-On-Demand keeps file *content* off local disk by default: a `read`
+//! hydrates the requested byte range straight from the remote. Two things make
+//! that cache-worthy:
+//!
+//! * **Pinning** — the user marks a file "always keep on this device". Its full
+//!   plaintext is downloaded once and stored under [`AppDirs::cache_dir`]; every
+//!   later `read` is served from disk with no network.
+//! * **Validation** — Proton does not hand us a stable revision id on the public
+//!   [`Node`], so a cached blob is validated against the node's
+//!   `(modification_time, plaintext_size)` pair. A new revision changes at least
+//!   the mtime, so a stale blob is detected and ignored (and the event poller
+//!   evicts it eagerly anyway).
+//!
+//! [`AppDirs::cache_dir`]: crate::config::AppDirs::cache_dir
+//! [`Node`]: proton_drive_rs::Node
+
+use std::collections::{BTreeMap, HashSet};
+use std::io::{Read, Seek, SeekFrom};
+use std::path::{Path, PathBuf};
+use std::time::SystemTime;
+
+use proton_drive_rs::proton_sdk::ids::NodeUid;
+use serde::{Deserialize, Serialize};
+use sha2::{Digest, Sha256};
+
+use crate::error::Result;
+
+/// Validity tag stored alongside a cached blob. A blob is fresh only if both
+/// fields still match the node's current metadata.
+#[derive(Serialize, Deserialize, Clone, Copy, PartialEq, Eq)]
+struct Meta {
+    /// Node modification time, epoch seconds.
+    mtime: i64,
+    /// Plaintext size in bytes.
+    size: u64,
+}
+
+/// One pinned file, as persisted to the pin registry.
+#[derive(Serialize, Deserialize, Clone, Debug)]
+pub struct Pin {
+    /// Node uid in `volume~link` display form.
+    pub uid: String,
+    /// Last path the file was pinned under, for display in `status`. Advisory
+    /// only — the uid is the identity.
+    pub path: String,
+}
+
+/// The pin registry, persisted as JSON. Keyed by uid display string so a pin
+/// survives renames/moves of the node.
+#[derive(Serialize, Deserialize, Default)]
+struct PinFile {
+    pins: BTreeMap<String, Pin>,
+}
+
+/// Content cache rooted at a directory, with a sibling pin-registry file.
+pub struct ContentCache {
+    /// Directory holding `<key>` blobs and `<key>.meta` tags.
+    content_dir: PathBuf,
+    /// Subdirectory holding cached thumbnails (`<key>.t<n>` + `.meta`). Kept out
+    /// of `content_dir` so the budget scan never sees thumbnail files.
+    thumb_dir: PathBuf,
+    /// JSON pin registry path.
+    pins_path: PathBuf,
+    /// Soft cap on total blob bytes. Exceeded only transiently: a `store`
+    /// evicts least-recently-used *unpinned* blobs back under the cap. `0`
+    /// disables the cap. Pinned blobs are never evicted, so pins alone may push
+    /// the cache over budget.
+    max_bytes: u64,
+}
+
+impl ContentCache {
+    /// Open (and create) a cache under `content_dir`, with the pin registry at
+    /// `pins_path` and a `max_bytes` size cap (`0` = unlimited). Both parent
+    /// directories are created if missing.
+    pub fn open(content_dir: PathBuf, pins_path: PathBuf, max_bytes: u64) -> Result<Self> {
+        std::fs::create_dir_all(&content_dir)?;
+        let thumb_dir = content_dir.join("thumbs");
+        std::fs::create_dir_all(&thumb_dir)?;
+        if let Some(parent) = pins_path.parent() {
+            std::fs::create_dir_all(parent)?;
+        }
+        Ok(Self { content_dir, thumb_dir, pins_path, max_bytes })
+    }
+
+    /// Filesystem-safe, fixed-length cache key for a uid display string: the
+    /// SHA-256 of `s`, hex-encoded (64 chars). A plain hex of the uid would
+    /// *double* its length, and Proton's `volume~link` ids are long enough
+    /// (each half can be 60+ chars) that the doubled key overflows `NAME_MAX`
+    /// (255) — `store` then fails with ENAMETOOLONG. Hashing bounds the key at
+    /// 64 chars; reversibility is not needed and collisions are negligible.
+    fn key_str(s: &str) -> String {
+        let digest = Sha256::digest(s.as_bytes());
+        let mut out = String::with_capacity(digest.len() * 2);
+        for b in digest {
+            out.push(char::from_digit((b >> 4) as u32, 16).unwrap());
+            out.push(char::from_digit((b & 0xf) as u32, 16).unwrap());
+        }
+        out
+    }
+
+    /// Filesystem-safe cache key for `uid`.
+    fn key(uid: &NodeUid) -> String {
+        Self::key_str(&uid.to_string())
+    }
+
+    fn blob_path(&self, uid: &NodeUid) -> PathBuf {
+        self.content_dir.join(Self::key(uid))
+    }
+
+    fn meta_path(&self, uid: &NodeUid) -> PathBuf {
+        self.content_dir.join(format!("{}.meta", Self::key(uid)))
+    }
+
+    /// The validated blob path for `uid`, or `None` if absent or stale against
+    /// `(mtime, size)`.
+    fn valid_blob(&self, uid: &NodeUid, mtime: i64, size: u64) -> Option<PathBuf> {
+        let want = Meta { mtime, size };
+        let meta: Meta = serde_json::from_slice(&std::fs::read(self.meta_path(uid)).ok()?).ok()?;
+        if meta != want {
+            return None;
+        }
+        let blob = self.blob_path(uid);
+        // Guard against a torn write: the blob must match the recorded size.
+        match std::fs::metadata(&blob) {
+            Ok(m) if m.len() == size => Some(blob),
+            _ => None,
+        }
+    }
+
+    /// Whether a fresh cached blob exists for `uid`.
+    pub fn is_cached(&self, uid: &NodeUid, mtime: i64, size: u64) -> bool {
+        self.valid_blob(uid, mtime, size).is_some()
+    }
+
+    /// Serve `len` bytes from `offset` out of the cached blob, or `None` on a
+    /// miss/stale entry. Reads only the requested window off disk.
+    pub fn read_range(
+        &self,
+        uid: &NodeUid,
+        mtime: i64,
+        size: u64,
+        offset: u64,
+        len: u64,
+    ) -> Option<Vec<u8>> {
+        let blob = self.valid_blob(uid, mtime, size)?;
+        // Record the access for LRU: bump the blob's mtime to now. Best effort —
+        // a failed touch only makes eviction order slightly less accurate.
+        let mut f = std::fs::File::open(&blob).ok()?;
+        let _ = f.set_times(std::fs::FileTimes::new().set_modified(SystemTime::now()));
+        if offset >= size {
+            return Some(Vec::new());
+        }
+        let end = offset.saturating_add(len).min(size);
+        let want = (end - offset) as usize;
+        f.seek(SeekFrom::Start(offset)).ok()?;
+        let mut buf = vec![0u8; want];
+        f.read_exact(&mut buf).ok()?;
+        Some(buf)
+    }
+
+    /// Store `bytes` as the cached content for `uid`, tagged with `(mtime,
+    /// size)`. The blob is written to a temp file then renamed so a concurrent
+    /// reader never sees a partial blob; the meta tag is written last so a
+    /// crash mid-store fails validation rather than serving truncated data.
+    pub fn store(&self, uid: &NodeUid, mtime: i64, size: u64, bytes: &[u8]) -> Result<()> {
+        let blob = self.blob_path(uid);
+        let tmp = blob.with_extension("tmp");
+        std::fs::write(&tmp, bytes)?;
+        std::fs::rename(&tmp, &blob)?;
+        let meta = serde_json::to_vec(&Meta { mtime, size })?;
+        std::fs::write(self.meta_path(uid), meta)?;
+        self.enforce_budget();
+        Ok(())
+    }
+
+    /// Remove any cached blob + meta for `uid`, including its thumbnails (best
+    /// effort; absence is fine). Thumbnails are tied to the revision, so a
+    /// content eviction must drop them too.
+    pub fn evict(&self, uid: &NodeUid) {
+        let _ = std::fs::remove_file(self.blob_path(uid));
+        let _ = std::fs::remove_file(self.meta_path(uid));
+        for ttype in [1, 2] {
+            let _ = std::fs::remove_file(self.thumb_blob(uid, ttype));
+            let _ = std::fs::remove_file(self.thumb_meta(uid, ttype));
+        }
+    }
+
+    fn thumb_blob(&self, uid: &NodeUid, ttype: i32) -> PathBuf {
+        self.thumb_dir.join(format!("{}.t{ttype}", Self::key(uid)))
+    }
+
+    fn thumb_meta(&self, uid: &NodeUid, ttype: i32) -> PathBuf {
+        self.thumb_dir.join(format!("{}.t{ttype}.meta", Self::key(uid)))
+    }
+
+    /// Serve a cached thumbnail of `ttype` for `uid`, or `None` on miss/stale.
+    /// Validated by node `mtime` alone: a new revision (which is what changes the
+    /// thumbnail) bumps the mtime, so a stale thumbnail is detected. Thumbnails
+    /// are small, so the whole blob is read at once.
+    pub fn read_thumbnail(&self, uid: &NodeUid, ttype: i32, mtime: i64) -> Option<Vec<u8>> {
+        let recorded: i64 =
+            serde_json::from_slice(&std::fs::read(self.thumb_meta(uid, ttype)).ok()?).ok()?;
+        if recorded != mtime {
+            return None;
+        }
+        std::fs::read(self.thumb_blob(uid, ttype)).ok()
+    }
+
+    /// On-disk path of the cached content blob for `uid`, validated against
+    /// `(mtime, size)`; `None` on miss/stale. Lets a front-end open the blob
+    /// directly instead of streaming its bytes back over the control socket.
+    pub fn cached_content_path(&self, uid: &NodeUid, mtime: i64, size: u64) -> Option<PathBuf> {
+        self.valid_blob(uid, mtime, size)
+    }
+
+    /// On-disk path where `uid`'s content blob lives once stored (the file may
+    /// not exist yet, or may be stale — pair with [`store`](Self::store)).
+    pub fn content_path(&self, uid: &NodeUid) -> PathBuf {
+        self.blob_path(uid)
+    }
+
+    /// On-disk path of the cached `ttype` thumbnail for `uid`, fresh against
+    /// `tag` (the validity tag last passed to [`store_thumbnail`](Self::store_thumbnail));
+    /// `None` on miss/stale. For Drive files the tag is the node mtime; for
+    /// photos it is the capture time.
+    pub fn cached_thumbnail_path(&self, uid: &NodeUid, ttype: i32, tag: i64) -> Option<PathBuf> {
+        let recorded: i64 =
+            serde_json::from_slice(&std::fs::read(self.thumb_meta(uid, ttype)).ok()?).ok()?;
+        if recorded != tag {
+            return None;
+        }
+        let blob = self.thumb_blob(uid, ttype);
+        blob.exists().then_some(blob)
+    }
+
+    /// On-disk path where `uid`'s `ttype` thumbnail lives once stored.
+    pub fn thumbnail_path(&self, uid: &NodeUid, ttype: i32) -> PathBuf {
+        self.thumb_blob(uid, ttype)
+    }
+
+    /// Cache `bytes` as the `ttype` thumbnail for `uid`, tagged with `mtime`.
+    /// Blob written to a temp file then renamed; the meta tag is written last so
+    /// a crash mid-store fails validation rather than serving a torn thumbnail.
+    pub fn store_thumbnail(
+        &self,
+        uid: &NodeUid,
+        ttype: i32,
+        mtime: i64,
+        bytes: &[u8],
+    ) -> Result<()> {
+        let blob = self.thumb_blob(uid, ttype);
+        let tmp = blob.with_extension("tmp");
+        std::fs::write(&tmp, bytes)?;
+        std::fs::rename(&tmp, &blob)?;
+        std::fs::write(self.thumb_meta(uid, ttype), serde_json::to_vec(&mtime)?)?;
+        Ok(())
+    }
+
+    /// Evict least-recently-used *unpinned* blobs until total blob bytes fit the
+    /// configured `max_bytes` cap. No-op when the cap is disabled (`0`) or the
+    /// cache already fits. Pinned blobs are skipped, so a cache held entirely by
+    /// pins can legitimately stay over budget.
+    fn enforce_budget(&self) {
+        if self.max_bytes == 0 {
+            return;
+        }
+        // Pinned blobs (by cache key) are exempt from eviction.
+        let pinned: HashSet<String> =
+            self.load_pins().pins.keys().map(|uid| Self::key_str(uid)).collect();
+
+        // Scan blobs (the `<key>` files; skip `.meta`/`.tmp` siblings), record
+        // size + last-access (mtime) for each.
+        let mut total: u64 = 0;
+        let mut blobs: Vec<(PathBuf, u64, SystemTime)> = Vec::new();
+        let Ok(rd) = std::fs::read_dir(&self.content_dir) else {
+            return;
+        };
+        for entry in rd.flatten() {
+            let path = entry.path();
+            let Some(name) = path.file_name().and_then(|n| n.to_str()) else {
+                continue;
+            };
+            if name.ends_with(".meta") || name.ends_with(".tmp") {
+                continue;
+            }
+            let Ok(meta) = entry.metadata() else { continue };
+            if !meta.is_file() {
+                continue;
+            }
+            total += meta.len();
+            if pinned.contains(name) {
+                continue; // counts toward total but is never a victim
+            }
+            let atime = meta.modified().unwrap_or(SystemTime::UNIX_EPOCH);
+            blobs.push((path, meta.len(), atime));
+        }
+        if total <= self.max_bytes {
+            return;
+        }
+        // Oldest access first.
+        blobs.sort_by_key(|(_, _, atime)| *atime);
+        for (path, len, _) in blobs {
+            if total <= self.max_bytes {
+                break;
+            }
+            let _ = std::fs::remove_file(&path);
+            let _ = std::fs::remove_file(path.with_extension("meta"));
+            total = total.saturating_sub(len);
+        }
+    }
+
+    fn load_pins(&self) -> PinFile {
+        std::fs::read(&self.pins_path)
+            .ok()
+            .and_then(|b| serde_json::from_slice(&b).ok())
+            .unwrap_or_default()
+    }
+
+    fn save_pins(&self, pins: &PinFile) -> Result<()> {
+        std::fs::write(&self.pins_path, serde_json::to_vec_pretty(pins)?)?;
+        Ok(())
+    }
+
+    /// Whether `uid` is pinned (independent of whether its blob is currently
+    /// cached).
+    pub fn is_pinned(&self, uid: &NodeUid) -> bool {
+        self.load_pins().pins.contains_key(&uid.to_string())
+    }
+
+    /// Record `uid` as pinned under `path`. The caller is responsible for having
+    /// already cached the content via [`store`](Self::store).
+    pub fn add_pin(&self, uid: &NodeUid, path: &Path) -> Result<()> {
+        let mut file = self.load_pins();
+        let key = uid.to_string();
+        file.pins.insert(
+            key.clone(),
+            Pin { uid: key, path: path.display().to_string() },
+        );
+        self.save_pins(&file)
+    }
+
+    /// Drop `uid` from the pin registry and evict its blob. No-op if not pinned.
+    pub fn remove_pin(&self, uid: &NodeUid) -> Result<()> {
+        let mut file = self.load_pins();
+        if file.pins.remove(&uid.to_string()).is_some() {
+            self.save_pins(&file)?;
+        }
+        self.evict(uid);
+        Ok(())
+    }
+
+    /// All pinned files, ordered by uid.
+    pub fn list_pins(&self) -> Vec<Pin> {
+        self.load_pins().pins.into_values().collect()
+    }
+
+    /// Total bytes of cached content blobs (pinned + unpinned), matching what
+    /// [`enforce_budget`](Self::enforce_budget) weighs against the cap.
+    /// Thumbnails live in a sibling dir and are not counted. Cheap directory
+    /// scan, safe to call from a front-end for a usage read-out.
+    pub fn usage(&self) -> u64 {
+        let Ok(rd) = std::fs::read_dir(&self.content_dir) else {
+            return 0;
+        };
+        let mut total = 0u64;
+        for entry in rd.flatten() {
+            let Some(name) = entry.file_name().to_str().map(str::to_owned) else {
+                continue;
+            };
+            if name.ends_with(".meta") || name.ends_with(".tmp") {
+                continue;
+            }
+            if let Ok(meta) = entry.metadata()
+                && meta.is_file()
+            {
+                total += meta.len();
+            }
+        }
+        total
+    }
+
+    /// Configured soft byte cap (`0` = unlimited), for display alongside
+    /// [`usage`](Self::usage).
+    pub fn budget(&self) -> u64 {
+        self.max_bytes
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use proton_drive_rs::proton_sdk::ids::{LinkId, VolumeId};
+
+    fn uid(link: &str) -> NodeUid {
+        NodeUid::new(VolumeId::from("vol"), LinkId::from(link))
+    }
+
+    /// A unique temp directory removed on drop; avoids a dev-dependency.
+    struct TempDir(PathBuf);
+    impl TempDir {
+        fn new() -> Self {
+            use std::sync::atomic::{AtomicU64, Ordering};
+            static N: AtomicU64 = AtomicU64::new(0);
+            let p = std::env::temp_dir().join(format!(
+                "pdfs-cache-{}-{}",
+                std::process::id(),
+                N.fetch_add(1, Ordering::Relaxed)
+            ));
+            std::fs::create_dir_all(&p).unwrap();
+            TempDir(p)
+        }
+        fn path(&self) -> &Path {
+            &self.0
+        }
+    }
+    impl Drop for TempDir {
+        fn drop(&mut self) {
+            let _ = std::fs::remove_dir_all(&self.0);
+        }
+    }
+
+    fn cache() -> (ContentCache, TempDir) {
+        cache_capped(0)
+    }
+
+    fn cache_capped(max_bytes: u64) -> (ContentCache, TempDir) {
+        let dir = TempDir::new();
+        let c = ContentCache::open(
+            dir.path().join("content"),
+            dir.path().join("pins.json"),
+            max_bytes,
+        )
+        .unwrap();
+        (c, dir)
+    }
+
+    #[test]
+    fn store_then_read_range() {
+        let (c, _d) = cache();
+        let u = uid("a");
+        let data = b"hello world";
+        c.store(&u, 100, data.len() as u64, data).unwrap();
+        assert!(c.is_cached(&u, 100, data.len() as u64));
+        assert_eq!(
+            c.read_range(&u, 100, data.len() as u64, 6, 5).unwrap(),
+            b"world"
+        );
+        // Offset past EOF yields an empty slice, not a miss.
+        assert_eq!(
+            c.read_range(&u, 100, data.len() as u64, 100, 5).unwrap(),
+            b""
+        );
+    }
+
+    #[test]
+    fn stale_metadata_is_a_miss() {
+        let (c, _d) = cache();
+        let u = uid("a");
+        c.store(&u, 100, 3, b"abc").unwrap();
+        // A newer mtime (new revision) invalidates the cached blob.
+        assert!(!c.is_cached(&u, 101, 3));
+        assert!(c.read_range(&u, 101, 3, 0, 3).is_none());
+        // A size mismatch also invalidates it.
+        assert!(c.read_range(&u, 100, 4, 0, 3).is_none());
+    }
+
+    #[test]
+    fn pin_lifecycle_evicts_on_unpin() {
+        let (c, _d) = cache();
+        let u = uid("a");
+        c.store(&u, 100, 3, b"abc").unwrap();
+        c.add_pin(&u, Path::new("docs/a.txt")).unwrap();
+        assert!(c.is_pinned(&u));
+        assert_eq!(c.list_pins().len(), 1);
+        assert_eq!(c.list_pins()[0].path, "docs/a.txt");
+
+        c.remove_pin(&u).unwrap();
+        assert!(!c.is_pinned(&u));
+        assert!(c.list_pins().is_empty());
+        // Unpin evicts the cached content.
+        assert!(!c.is_cached(&u, 100, 3));
+    }
+
+    #[test]
+    fn budget_evicts_lru_unpinned() {
+        // Cap fits two 4-byte blobs but not three.
+        let (c, _d) = cache_capped(8);
+        let (a, b, d) = (uid("a"), uid("b"), uid("d"));
+
+        c.store(&a, 1, 4, b"aaaa").unwrap();
+        // Distinct mtimes so LRU order is deterministic (oldest = a).
+        std::thread::sleep(std::time::Duration::from_millis(10));
+        c.store(&b, 1, 4, b"bbbb").unwrap();
+        // Touch `a` so `b` becomes the least-recently-used.
+        std::thread::sleep(std::time::Duration::from_millis(10));
+        assert!(c.read_range(&a, 1, 4, 0, 4).is_some());
+
+        // Third store pushes over budget → evicts LRU unpinned (`b`).
+        std::thread::sleep(std::time::Duration::from_millis(10));
+        c.store(&d, 1, 4, b"dddd").unwrap();
+        assert!(c.is_cached(&a, 1, 4), "recently-read blob survives");
+        assert!(!c.is_cached(&b, 1, 4), "LRU blob evicted");
+        assert!(c.is_cached(&d, 1, 4), "newest blob survives");
+    }
+
+    #[test]
+    fn budget_never_evicts_pinned() {
+        let (c, _d) = cache_capped(8);
+        let (a, b, d) = (uid("a"), uid("b"), uid("d"));
+
+        c.store(&a, 1, 4, b"aaaa").unwrap();
+        c.add_pin(&a, Path::new("a")).unwrap();
+        std::thread::sleep(std::time::Duration::from_millis(10));
+        c.store(&b, 1, 4, b"bbbb").unwrap();
+        // Over budget: `a` is pinned (oldest) so `b` must be the victim.
+        std::thread::sleep(std::time::Duration::from_millis(10));
+        c.store(&d, 1, 4, b"dddd").unwrap();
+        assert!(c.is_cached(&a, 1, 4), "pinned blob never evicted");
+        assert!(!c.is_cached(&b, 1, 4), "unpinned LRU blob evicted");
+        assert!(c.is_cached(&d, 1, 4));
+    }
+
+    #[test]
+    fn thumbnail_store_read_and_evict() {
+        let (c, _d) = cache();
+        let u = uid("a");
+        c.store_thumbnail(&u, 1, 100, b"thumb1").unwrap();
+        c.store_thumbnail(&u, 2, 100, b"preview2").unwrap();
+        assert_eq!(c.read_thumbnail(&u, 1, 100).unwrap(), b"thumb1");
+        assert_eq!(c.read_thumbnail(&u, 2, 100).unwrap(), b"preview2");
+        // A newer revision (mtime bump) invalidates the cached thumbnail.
+        assert!(c.read_thumbnail(&u, 1, 101).is_none());
+        // Content eviction drops thumbnails too.
+        c.evict(&u);
+        assert!(c.read_thumbnail(&u, 1, 100).is_none());
+        assert!(c.read_thumbnail(&u, 2, 100).is_none());
+    }
+
+    #[test]
+    fn evict_removes_blob() {
+        let (c, _d) = cache();
+        let u = uid("a");
+        c.store(&u, 1, 3, b"abc").unwrap();
+        c.evict(&u);
+        assert!(!c.is_cached(&u, 1, 3));
+    }
+}

crates/pdfs-core/src/config.rs

@@ -14,6 +14,10 @@ pub const USER_AGENT: &str = "proton-drive-linux/0.1.0";
 /// Keyring service name; one entry per credential kind keyed by username.
 pub const KEYRING_SERVICE: &str = "proton-drive-linux";
 
+/// Default soft cap on the on-disk content cache (5 GiB). LRU-evicts unpinned
+/// blobs back under this; pinned files are exempt. See [`crate::cache`].
+pub const DEFAULT_CACHE_BUDGET_BYTES: u64 = 5 * 1024 * 1024 * 1024;
+
 /// Resolved XDG locations for state, cache, and the default mountpoint.
 pub struct AppDirs {
     dirs: ProjectDirs,
@@ -40,6 +44,21 @@ impl AppDirs {
         self.dirs.cache_dir().to_path_buf()
     }
 
+    /// Directory holding cached file-content blobs (pinned files).
+    pub fn content_cache_dir(&self) -> PathBuf {
+        self.cache_dir().join("content")
+    }
+
+    /// JSON pin registry, in persistent state (not the evictable cache).
+    pub fn pins_path(&self) -> PathBuf {
+        self.state_dir().join("pins.json")
+    }
+
+    /// Unix domain socket the mount daemon listens on for CLI control commands.
+    pub fn control_socket(&self) -> PathBuf {
+        self.state_dir().join("control.sock")
+    }
+
     /// Default mountpoint when the user does not pass one explicitly.
     pub fn default_mountpoint(&self) -> PathBuf {
         directories::UserDirs::new()

crates/pdfs-core/src/control.rs

@@ -0,0 +1,125 @@
+//! IPC protocol between the CLI and a running mount daemon.
+//!
+//! The daemon listens on a Unix domain socket under the state dir; the CLI
+//! (`pdfs pin` / `unpin` / `status`) connects, sends one [`Request`] as a single
+//! JSON line, and reads one JSON-line [`Response`]. Keeping the wire format
+//! line-delimited JSON makes the socket trivially scriptable.
+
+use std::io::{BufRead, BufReader, Write};
+use std::os::unix::net::UnixStream;
+use std::path::Path;
+use std::time::Duration;
+
+use serde::{Deserialize, Serialize};
+
+use crate::cache::Pin;
+use crate::error::Result;
+
+/// Cap on the *write* half of a round-trip. A crashed daemon can leave its
+/// listening socket in the kernel (e.g. as a `<defunct>` zombie): `connect`
+/// then succeeds but no one ever replies. A short write bound trips fast when
+/// the daemon is wedged before it has read anything.
+const WRITE_TIMEOUT: Duration = Duration::from_secs(2);
+
+/// Cap on the *read* half. Some requests make the daemon do real work before it
+/// replies — `PhotosTimeline` downloads a page of thumbnails, `OpenFile`
+/// downloads whole-file content — which easily takes more than a couple of
+/// seconds. A 2s read bound timed those out and the GUI mistook the timeout for
+/// "no daemon" (showing "Mount Proton Drive…" on a live mount). Give reads a
+/// generous bound that still protects against a daemon that accepts but never
+/// answers.
+const READ_TIMEOUT: Duration = Duration::from_secs(120);
+
+/// A command sent from the CLI to the daemon.
+#[derive(Serialize, Deserialize, Debug)]
+pub enum Request {
+    /// Report mount status (account, mountpoint, pin count).
+    Status,
+    /// Pin a file (path relative to the mountpoint, or absolute under it).
+    Pin { path: String },
+    /// Unpin a file, evicting its cached content.
+    Unpin { path: String },
+    /// List pinned files.
+    ListPins,
+    /// List a directory for the in-app file browser. `path` is
+    /// mountpoint-relative (empty or "." = the mount root).
+    ListDir { path: String },
+    /// Fetch a page of the photos timeline, newest first. Thumbnails for the
+    /// page are fetched into the cache and their on-disk paths returned.
+    PhotosTimeline { offset: usize, limit: usize },
+    /// Download a photo's full content into the cache; replies with its path.
+    OpenPhoto { uid: String },
+    /// Download a Drive file's full content into the cache; replies with the
+    /// on-disk path so the front-end can open it with the default app. `path`
+    /// is mountpoint-relative.
+    OpenFile { path: String },
+}
+
+/// One entry in a [`Request::ListDir`] listing.
+#[derive(Serialize, Deserialize, Debug, Clone)]
+pub struct DirEntry {
+    /// Decrypted node name.
+    pub name: String,
+    pub is_dir: bool,
+    /// Plaintext size in bytes (0 for folders).
+    pub size: u64,
+    /// Modification time, epoch seconds.
+    pub modified: i64,
+    /// Whether the file is pinned to this device.
+    pub pinned: bool,
+    /// Node uid in `volume~link` form, for follow-up requests.
+    pub uid: String,
+}
+
+/// One photo in a [`Request::PhotosTimeline`] page.
+#[derive(Serialize, Deserialize, Debug, Clone)]
+pub struct PhotoItem {
+    /// Node uid in `volume~link` form.
+    pub uid: String,
+    /// Capture time, epoch seconds (the timeline is newest-first).
+    pub capture_time: i64,
+    /// On-disk path to the cached thumbnail, if one was available/fetched.
+    pub thumb_path: Option<String>,
+}
+
+/// The daemon's reply to a [`Request`].
+#[derive(Serialize, Deserialize, Debug)]
+pub enum Response {
+    /// Current mount status.
+    Status {
+        username: String,
+        mountpoint: String,
+        pinned: usize,
+    },
+    /// A human-readable success message.
+    Ok { message: String },
+    /// The pin registry.
+    Pins { pins: Vec<Pin> },
+    /// A directory listing (reply to [`Request::ListDir`]).
+    Entries { entries: Vec<DirEntry> },
+    /// A page of the photos timeline. `available` is false when the account
+    /// has no photos volume.
+    Photos { available: bool, items: Vec<PhotoItem> },
+    /// An on-disk path the front-end can open (e.g. a downloaded photo).
+    FilePath { path: String },
+    /// The request failed.
+    Error { message: String },
+}
+
+/// Send one [`Request`] to the daemon listening on `socket` and read its
+/// [`Response`]. Errors (e.g. [`Error::Io`]) if no daemon is listening.
+///
+/// Shared by the CLI and GUI so both speak the wire format identically.
+pub fn send(socket: &Path, req: &Request) -> Result<Response> {
+    let mut stream = UnixStream::connect(socket)?;
+    stream.set_read_timeout(Some(READ_TIMEOUT))?;
+    stream.set_write_timeout(Some(WRITE_TIMEOUT))?;
+    let mut line = serde_json::to_vec(req)?;
+    line.push(b'\n');
+    stream.write_all(&line)?;
+    stream.flush()?;
+    let mut reader = BufReader::new(stream);
+    let mut resp = String::new();
+    reader.read_line(&mut resp)?;
+    Ok(serde_json::from_str(resp.trim())?)
+}

crates/pdfs-core/src/lib.rs

@@ -3,7 +3,9 @@
 //! front-end (CLI today, daemon + GUI later) shares.
 
 pub mod auth;
+pub mod cache;
 pub mod config;
+pub mod control;
 pub mod error;
 
 pub use error::{Error, Result};