Skip to content

Native iCloud apps for Windows and Linux, built in Rust. Notes, Reminders, Calendar, Contacts, Drive and Photos, offline and in sync with your iPhone.

quince-vfs: iCloud Drive as a folder, engine and read-only Linux mount

Yashwanth Kamireddie5046eae440b
diff --git a/Cargo.lock b/Cargo.lock
index 50baeb6..6da164e 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -1333,6 +1333,26 @@ version = "0.4.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "795cbfc56d419a7ce47ccbb7504dd9a5b7c484c083c356e797de08bd988d9629"
+[[package]]
+name = "fuser"
+version = "0.18.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b82b6597d216503555ead6b358f341ef748869bf5c6fbae6a0cb9dd231baecfd"
+dependencies = [
+ "bitflags 2.13.2",
+ "libc",
+ "log",
+ "memchr",
+ "nix 0.31.3",
+ "num_enum",
+ "page_size",
+ "parking_lot",
+ "pkg-config",
+ "ref-cast",
+ "smallvec",
+ "zerocopy",
+]
+
[[package]]
name = "futures"
version = "0.3.34"
@@ -2865,6 +2885,19 @@ dependencies = [
"memoffset",
]
+[[package]]
+name = "nix"
+version = "0.31.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cf20d2fde8ff38632c426f1165ed7436270b44f199fc55284c38276f9db47c3d"
+dependencies = [
+ "bitflags 2.13.2",
+ "cfg-if",
+ "cfg_aliases",
+ "libc",
+ "memoffset",
+]
+
[[package]]
name = "notify-rust"
version = "4.18.1"
@@ -3227,6 +3260,16 @@ dependencies = [
"pin-project-lite",
]
+[[package]]
+name = "page_size"
+version = "0.6.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "30d5b2194ed13191c1999ae0704b7839fb18384fa22e49b57eeaa97d79ce40da"
+dependencies = [
+ "libc",
+ "winapi",
+]
+
[[package]]
name = "pango"
version = "0.18.3"
@@ -3691,6 +3734,17 @@ dependencies = [
"uuid",
]
+[[package]]
+name = "quince-vfs"
+version = "0.1.0"
+dependencies = [
+ "fuser",
+ "libc",
+ "quince-core",
+ "tempfile",
+ "tokio",
+]
+
[[package]]
name = "quinn"
version = "0.11.11"
@@ -6610,7 +6664,7 @@ dependencies = [
"futures-sink",
"futures-util",
"hex",
- "nix",
+ "nix 0.29.0",
"ordered-stream",
"rand 0.8.8",
"serde",
diff --git a/Cargo.toml b/Cargo.toml
index e2848b2..accf1fc 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -1,6 +1,6 @@
[workspace]
resolver = "2"
-members = ["probe", "crates/quince-auth", "crates/quince-core", "crates/quince-icloud", "crates/quince-media", "src-tauri"]
+members = ["probe", "crates/quince-auth", "crates/quince-core", "crates/quince-icloud", "crates/quince-media", "crates/quince-vfs", "src-tauri"]
[workspace.package]
edition = "2021"
diff --git a/crates/quince-vfs/Cargo.toml b/crates/quince-vfs/Cargo.toml
new file mode 100644
index 0000000..0064fea
--- /dev/null
+++ b/crates/quince-vfs/Cargo.toml
@@ -0,0 +1,19 @@
+[package]
+name = "quince-vfs"
+version = "0.1.0"
+edition.workspace = true
+rust-version.workspace = true
+license.workspace = true
+
+[dependencies]
+quince-core = { path = "../quince-core" }
+tokio = { workspace = true, features = ["sync", "rt", "time"] }
+libc = "0.2"
+
+[target.'cfg(target_os = "linux")'.dependencies]
+fuser = { version = "0.18", default-features = false }
+
+[dev-dependencies]
+tempfile = "3"
+libc = "0.2"
+tokio = { workspace = true, features = ["sync", "rt", "macros", "rt-multi-thread"] }
diff --git a/crates/quince-vfs/src/fuse.rs b/crates/quince-vfs/src/fuse.rs
new file mode 100644
index 0000000..520f5ed
--- /dev/null
+++ b/crates/quince-vfs/src/fuse.rs
@@ -0,0 +1,278 @@
+//! The engine as a Linux folder, through FUSE (fuser).
+//!
+//! Read-only for now. Names, sizes and dates come from the library, never the network, so a
+//! file manager browsing is never kept waiting; a folder never opened before is fetched once.
+//! A file's bytes come from the cache, each part fetched from Apple the first time it is read.
+
+use crate::{is_thumbnailer, named, Cache, Inodes, Remote, Store};
+use fuser::{
+ Config, Errno, FileAttr, FileHandle, FileType, Filesystem, FopenFlags, Generation, INodeNo,
+ LockOwner, MountOption, OpenAccMode, OpenFlags, ReplyAttr, ReplyData, ReplyDirectory,
+ ReplyEntry, ReplyOpen, ReplyStatfs, Request,
+};
+use quince_core::drive::DriveItem;
+use std::ffi::OsStr;
+use std::path::Path;
+use std::sync::{Arc, Mutex};
+use std::time::{Duration, UNIX_EPOCH};
+
+/// How long the kernel may keep what it was told about a name or a file. Short, as rclone's
+/// is: a file changed on another device must not be read with its old length.
+const TTL: Duration = Duration::from_secs(1);
+
+/// How long a folder never opened before may take to come from Apple before the file manager
+/// is told it could not be read (and can ask again).
+const LIST_WAIT: Duration = Duration::from_secs(30);
+
+pub struct DriveFs {
+ remote: Arc<dyn Remote>,
+ store: Arc<dyn Store>,
+ cache: Arc<Cache>,
+ inodes: Mutex<Inodes>,
+ rt: tokio::runtime::Handle,
+ uid: u32,
+ gid: u32,
+}
+
+impl DriveFs {
+ #[must_use]
+ pub fn new(
+ remote: Arc<dyn Remote>,
+ store: Arc<dyn Store>,
+ cache: Arc<Cache>,
+ rt: tokio::runtime::Handle,
+ ) -> Self {
+ // SAFETY: getuid and getgid cannot fail and touch no memory.
+ let (uid, gid) = unsafe { (libc::getuid(), libc::getgid()) };
+ Self {
+ remote,
+ store,
+ cache,
+ inodes: Mutex::new(Inodes::new()),
+ rt,
+ uid,
+ gid,
+ }
+ }
+
+ fn item(&self, ino: INodeNo) -> Option<DriveItem> {
+ self.inodes
+ .lock()
+ .unwrap_or_else(std::sync::PoisonError::into_inner)
+ .item(ino.0)
+ .cloned()
+ }
+
+ fn attr(&self, ino: u64, item: &DriveItem) -> FileAttr {
+ let secs = |s: Option<i64>| {
+ UNIX_EPOCH + Duration::from_secs(u64::try_from(s.unwrap_or(0)).unwrap_or(0))
+ };
+ let dir = item.is_container();
+ let size = if dir {
+ 0
+ } else {
+ u64::try_from(item.size.unwrap_or(0)).unwrap_or(0)
+ };
+ FileAttr {
+ ino: INodeNo(ino),
+ size,
+ blocks: size.div_ceil(512),
+ atime: secs(item.modified_at),
+ mtime: secs(item.modified_at),
+ ctime: secs(item.modified_at),
+ crtime: secs(item.created_at.or(item.modified_at)),
+ kind: if dir {
+ FileType::Directory
+ } else {
+ FileType::RegularFile
+ },
+ perm: if dir { 0o555 } else { 0o444 },
+ nlink: if dir { 2 } else { 1 },
+ uid: self.uid,
+ gid: self.gid,
+ rdev: 0,
+ blksize: 4096,
+ flags: 0,
+ }
+ }
+
+ /// A folder's items with their names and inodes: from the library, or — never opened
+ /// before — from Apple, once.
+ fn children(&self, ino: INodeNo) -> Result<Vec<(String, u64, DriveItem)>, Errno> {
+ let item = self.item(ino).ok_or(Errno::ENOENT)?;
+ if !item.is_container() {
+ return Err(Errno::ENOTDIR);
+ }
+ let stored = self.store.children(&item.drivewsid);
+ // A folder Apple says has things in it, with nothing stored, was never listed.
+ let listed = stored.filter(|s| !s.is_empty() || item.child_count == Some(0));
+ let items = match listed {
+ Some(items) => items,
+ None => {
+ let remote = Arc::clone(&self.remote);
+ let id = item.drivewsid.clone();
+ self.rt
+ .block_on(
+ async move { tokio::time::timeout(LIST_WAIT, remote.list(&id)).await },
+ )
+ .map_err(|_| Errno::ETIMEDOUT)?
+ .map_err(|_| Errno::EIO)?
+ }
+ };
+ let mut inodes = self
+ .inodes
+ .lock()
+ .unwrap_or_else(std::sync::PoisonError::into_inner);
+ Ok(named(&items)
+ .into_iter()
+ .map(|(name, it)| (name, inodes.ino(&it), it))
+ .collect())
+ }
+}
+
+impl Filesystem for DriveFs {
+ fn lookup(&self, _req: &Request, parent: INodeNo, name: &OsStr, reply: ReplyEntry) {
+ match self.children(parent) {
+ Ok(children) => match children.into_iter().find(|(n, ..)| OsStr::new(n) == name) {
+ Some((_, ino, item)) => reply.entry(&TTL, &self.attr(ino, &item), Generation(0)),
+ None => reply.error(Errno::ENOENT),
+ },
+ Err(e) => reply.error(e),
+ }
+ }
+
+ fn getattr(&self, _req: &Request, ino: INodeNo, _fh: Option<FileHandle>, reply: ReplyAttr) {
+ match self.item(ino) {
+ Some(item) => reply.attr(&TTL, &self.attr(ino.0, &item)),
+ None => reply.error(Errno::ENOENT),
+ }
+ }
+
+ fn readdir(
+ &self,
+ _req: &Request,
+ ino: INodeNo,
+ _fh: FileHandle,
+ offset: u64,
+ mut reply: ReplyDirectory,
+ ) {
+ let children = match self.children(ino) {
+ Ok(c) => c,
+ Err(e) => return reply.error(e),
+ };
+ let parent = self
+ .item(ino)
+ .and_then(|i| i.parent_id)
+ .and_then(|p| self.inodes.lock().ok().and_then(|n| n.ino_of(&p)))
+ .unwrap_or(1);
+ let mut all: Vec<(u64, FileType, String)> = vec![
+ (ino.0, FileType::Directory, ".".into()),
+ (parent, FileType::Directory, "..".into()),
+ ];
+ all.extend(children.into_iter().map(|(name, i, item)| {
+ (
+ i,
+ if item.is_container() {
+ FileType::Directory
+ } else {
+ FileType::RegularFile
+ },
+ name,
+ )
+ }));
+ for (n, (i, kind, name)) in all
+ .into_iter()
+ .enumerate()
+ .skip(usize::try_from(offset).unwrap_or(0))
+ {
+ if reply.add(INodeNo(i), n as u64 + 1, kind, name) {
+ break;
+ }
+ }
+ reply.ok();
+ }
+
+ fn open(&self, req: &Request, ino: INodeNo, flags: OpenFlags, reply: ReplyOpen) {
+ let Some(item) = self.item(ino) else {
+ return reply.error(Errno::ENOENT);
+ };
+ if item.is_container() {
+ return reply.error(Errno::EISDIR);
+ }
+ if flags.acc_mode() != OpenAccMode::O_RDONLY {
+ return reply.error(Errno::EROFS);
+ }
+ // A thumbnailer is not let download a file only to draw it small (see is_thumbnailer).
+ let pid = req.pid();
+ let comm = std::fs::read_to_string(format!("/proc/{pid}/comm")).unwrap_or_default();
+ let cmdline = std::fs::read(format!("/proc/{pid}/cmdline"))
+ .map(|b| String::from_utf8_lossy(&b).into_owned())
+ .unwrap_or_default();
+ if is_thumbnailer(&comm, &cmdline) && !self.cache.whole(&item) {
+ return reply.error(Errno::EACCES);
+ }
+ reply.opened(FileHandle(0), FopenFlags::empty());
+ }
+
+ fn read(
+ &self,
+ _req: &Request,
+ ino: INodeNo,
+ _fh: FileHandle,
+ offset: u64,
+ size: u32,
+ _flags: OpenFlags,
+ _lock: Option<LockOwner>,
+ reply: ReplyData,
+ ) {
+ let Some(item) = self.item(ino) else {
+ return reply.error(Errno::ENOENT);
+ };
+ let (cache, remote) = (Arc::clone(&self.cache), Arc::clone(&self.remote));
+ // Answered when the bytes are here, without holding up the folder's other requests.
+ self.rt.spawn(async move {
+ match cache
+ .read(remote.as_ref(), &item, offset, u64::from(size))
+ .await
+ {
+ Ok(bytes) => reply.data(&bytes),
+ Err(_) => reply.error(Errno::EIO),
+ }
+ });
+ }
+
+ fn statfs(&self, _req: &Request, _ino: INodeNo, reply: ReplyStatfs) {
+ // Read-only: nothing free to write into, as a mounted disc says.
+ reply.statfs(0, 0, 0, 0, 0, 4096, 255, 4096);
+ }
+}
+
+/// The folder mounted at `at`, served on its own threads until the returned session is
+/// dropped. A mount left behind by a crash ("Transport endpoint is not connected") is let go
+/// of first.
+///
+/// # Errors
+/// When the folder cannot be made or FUSE refuses the mount.
+pub fn mount(fs: DriveFs, at: &Path) -> std::io::Result<fuser::BackgroundSession> {
+ if let Err(e) = std::fs::metadata(at) {
+ if e.raw_os_error() == Some(libc::ENOTCONN) {
+ let _ = std::process::Command::new("fusermount3")
+ .arg("-uz")
+ .arg(at)
+ .status();
+ }
+ }
+ std::fs::create_dir_all(at)?;
+ let mut config = Config::default();
+ config.mount_options = vec![
+ MountOption::FSName("quince".into()),
+ MountOption::Subtype("quince".into()),
+ MountOption::RO,
+ MountOption::NoSuid,
+ MountOption::NoDev,
+ MountOption::NoAtime,
+ MountOption::DefaultPermissions,
+ ];
+ config.n_threads = Some(4);
+ fuser::spawn_mount(fs, at, &config)
+}
diff --git a/crates/quince-vfs/src/lib.rs b/crates/quince-vfs/src/lib.rs
new file mode 100644
index 0000000..8573611
--- /dev/null
+++ b/crates/quince-vfs/src/lib.rs
@@ -0,0 +1,465 @@
+//! iCloud Drive as a folder other apps can use, on demand.
+//!
+//! The platform-free engine: which item an inode is, what a folder holds, and a file's bytes
+//! read in chunks into a sparse cache on disk — only the parts an app actually reads, each
+//! fetched once (Apple's download links answer byte ranges; proven live). The platform's
+//! own front end ([`fuse`] on Linux) asks it and never waits on the network for what the
+//! library already knows. Design: docs/mount-design.md.
+
+#[cfg(target_os = "linux")]
+pub mod fuse;
+
+use quince_core::drive::DriveItem;
+use std::collections::HashMap;
+use std::future::Future;
+use std::path::{Path, PathBuf};
+use std::pin::Pin;
+use std::sync::{Arc, Mutex};
+
+/// A future the engine waits on, as the app's own async code gives it.
+pub type Fut<T> = Pin<Box<dyn Future<Output = Result<T, String>> + Send>>;
+
+/// Apple's side, as the app reaches it with the signed-in session.
+pub trait Remote: Send + Sync + 'static {
+ /// A folder's items, fetched from Apple (and kept in the library by the app).
+ fn list(&self, folder: &str) -> Fut<Vec<DriveItem>>;
+ /// `len` bytes of a file from `offset` (fewer only at its end).
+ fn read(&self, item: &DriveItem, offset: u64, len: u64) -> Fut<Vec<u8>>;
+}
+
+/// What the library already knows, read without the network.
+pub trait Store: Send + Sync + 'static {
+ /// A folder's items as last stored; `None` when it has never been listed.
+ fn children(&self, folder: &str) -> Option<Vec<DriveItem>>;
+}
+
+/// The root of iCloud Drive, as Apple names it.
+pub const ROOT: &str = "FOLDER::com.apple.CloudDocs::root";
+
+/// Inode numbers for Apple's items, the same for an item for as long as the folder is
+/// mounted. 1 is the root, as FUSE requires.
+#[derive(Default)]
+pub struct Inodes {
+ by_ino: HashMap<u64, DriveItem>,
+ by_id: HashMap<String, u64>,
+ next: u64,
+}
+
+impl Inodes {
+ #[must_use]
+ pub fn new() -> Self {
+ let mut me = Self {
+ next: 2,
+ ..Self::default()
+ };
+ let root = DriveItem {
+ drivewsid: ROOT.into(),
+ parent_id: None,
+ name: "iCloud Drive".into(),
+ extension: None,
+ kind: "FOLDER".into(),
+ size: None,
+ child_count: None,
+ created_at: None,
+ modified_at: None,
+ etag: None,
+ };
+ me.by_ino.insert(1, root);
+ me.by_id.insert(ROOT.into(), 1);
+ me
+ }
+
+ /// The inode of an item, given one the first time it is seen; its details kept fresh.
+ pub fn ino(&mut self, item: &DriveItem) -> u64 {
+ if let Some(&ino) = self.by_id.get(&item.drivewsid) {
+ if ino != 1 {
+ self.by_ino.insert(ino, item.clone());
+ }
+ return ino;
+ }
+ let ino = self.next;
+ self.next += 1;
+ self.by_id.insert(item.drivewsid.clone(), ino);
+ self.by_ino.insert(ino, item.clone());
+ ino
+ }
+
+ /// The inode an item already has, by Apple's id.
+ #[must_use]
+ pub fn ino_of(&self, id: &str) -> Option<u64> {
+ self.by_id.get(id).copied()
+ }
+
+ #[must_use]
+ pub fn item(&self, ino: u64) -> Option<&DriveItem> {
+ self.by_ino.get(&ino)
+ }
+}
+
+/// A folder's items as names a file manager shows: the name with its extension, NFC as Apple
+/// keeps them. Two that would share a name (Apple's names differ by case or by a character a
+/// path cannot hold) are told apart, never one hiding the other.
+#[must_use]
+pub fn named(items: &[DriveItem]) -> Vec<(String, DriveItem)> {
+ let mut taken: HashMap<String, usize> = HashMap::new();
+ let mut out = Vec::with_capacity(items.len());
+ for item in items {
+ // "/" cannot be in a name on Linux, and NUL nowhere: Apple allows the first.
+ let base: String = item
+ .display_name()
+ .chars()
+ .map(|c| match c {
+ '/' => '∕',
+ '\0' => '�',
+ c => c,
+ })
+ .collect();
+ let base = if base == "." || base == ".." || base.is_empty() {
+ format!("{base}_")
+ } else {
+ base
+ };
+ let n = taken.entry(base.clone()).or_insert(0);
+ *n += 1;
+ let name = if *n == 1 {
+ base
+ } else {
+ // "Report (2).pdf": the second of two with the same name.
+ match base.rsplit_once('.') {
+ Some((stem, ext)) if !item.is_container() && !stem.is_empty() => {
+ format!("{stem} ({n}).{ext}")
+ }
+ _ => format!("{base} ({n})"),
+ }
+ };
+ out.push((name, item.clone()));
+ }
+ out
+}
+
+/// How much of a file is fetched at a time: a picture or a page in one request, a film in a
+/// few. Each chunk is fetched once and kept.
+pub const CHUNK: u64 = 4 * 1024 * 1024;
+
+/// A file's bytes kept on disk as they are read: a sparse file the file's own size, and which
+/// of its chunks are there. Keyed by the item and its version (Apple's etag), so a file
+/// changed on another device is never served from an older copy.
+pub struct Cache {
+ dir: PathBuf,
+ have: Mutex<HashMap<PathBuf, Vec<bool>>>,
+ fetching: Mutex<HashMap<PathBuf, Arc<tokio::sync::Mutex<()>>>>,
+}
+
+impl Cache {
+ /// # Errors
+ /// When the folder cannot be made.
+ pub fn new(dir: &Path) -> std::io::Result<Self> {
+ std::fs::create_dir_all(dir)?;
+ Ok(Self {
+ dir: dir.to_path_buf(),
+ have: Mutex::new(HashMap::new()),
+ fetching: Mutex::new(HashMap::new()),
+ })
+ }
+
+ fn path(&self, item: &DriveItem) -> PathBuf {
+ let safe = |s: &str| -> String {
+ s.chars()
+ .map(|c| if c.is_ascii_alphanumeric() { c } else { '_' })
+ .collect()
+ };
+ self.dir.join(format!(
+ "{}~{}",
+ safe(&item.drivewsid),
+ safe(item.etag.as_deref().unwrap_or("-"))
+ ))
+ }
+
+ fn chunks(size: u64) -> usize {
+ usize::try_from(size.div_ceil(CHUNK)).unwrap_or(0)
+ }
+
+ /// Which chunks are there, from memory or the file kept beside the bytes.
+ fn present(&self, path: &Path, size: u64) -> Vec<bool> {
+ let mut have = self
+ .have
+ .lock()
+ .unwrap_or_else(std::sync::PoisonError::into_inner);
+ have.entry(path.to_path_buf())
+ .or_insert_with(|| {
+ let n = Self::chunks(size);
+ let mut v = vec![false; n];
+ if let Ok(bytes) = std::fs::read(path.with_extension("have")) {
+ for (i, b) in bytes.iter().take(n).enumerate() {
+ v[i] = *b == 1;
+ }
+ }
+ v
+ })
+ .clone()
+ }
+
+ fn mark(&self, path: &Path, chunk: usize, size: u64) -> std::io::Result<()> {
+ let mut have = self
+ .have
+ .lock()
+ .unwrap_or_else(std::sync::PoisonError::into_inner);
+ let v = have
+ .entry(path.to_path_buf())
+ .or_insert_with(|| vec![false; Self::chunks(size)]);
+ if chunk < v.len() {
+ v[chunk] = true;
+ }
+ let bytes: Vec<u8> = v.iter().map(|&b| u8::from(b)).collect();
+ // Written beside, after the bytes themselves: a chunk is never claimed before it is
+ // on disk, so a crash between the two only costs fetching it again.
+ let part = path.with_extension("have.part");
+ std::fs::write(&part, bytes)?;
+ std::fs::rename(&part, path.with_extension("have"))
+ }
+
+ /// Whether every byte of a file is on disk already.
+ #[must_use]
+ pub fn whole(&self, item: &DriveItem) -> bool {
+ let size = u64::try_from(item.size.unwrap_or(0)).unwrap_or(0);
+ size == 0 || self.present(&self.path(item), size).iter().all(|&b| b)
+ }
+
+ /// `len` bytes of a file from `offset`: from disk, each chunk missing fetched once.
+ ///
+ /// # Errors
+ /// When Apple cannot be reached for a missing chunk, or the disk refuses.
+ pub async fn read(
+ &self,
+ remote: &dyn Remote,
+ item: &DriveItem,
+ offset: u64,
+ len: u64,
+ ) -> Result<Vec<u8>, String> {
+ let size = u64::try_from(item.size.unwrap_or(0)).unwrap_or(0);
+ if offset >= size || len == 0 {
+ return Ok(Vec::new());
+ }
+ let end = (offset + len).min(size);
+ let path = self.path(item);
+ let lock = {
+ let mut f = self
+ .fetching
+ .lock()
+ .unwrap_or_else(std::sync::PoisonError::into_inner);
+ Arc::clone(f.entry(path.clone()).or_default())
+ };
+ {
+ // One fetch at a time for a file: two readers of the same part wait for one fetch.
+ let _one = lock.lock().await;
+ let first = usize::try_from(offset / CHUNK).unwrap_or(0);
+ let last = usize::try_from((end - 1) / CHUNK).unwrap_or(0);
+ for chunk in first..=last {
+ if self
+ .present(&path, size)
+ .get(chunk)
+ .copied()
+ .unwrap_or(false)
+ {
+ continue;
+ }
+ let from = chunk as u64 * CHUNK;
+ let want = CHUNK.min(size - from);
+ let bytes = remote.read(item, from, want).await?;
+ if bytes.len() as u64 != want {
+ return Err(format!("Apple sent {} of {want} bytes", bytes.len()));
+ }
+ let p = path.clone();
+ tokio::task::spawn_blocking(move || put(&p, from, &bytes, size))
+ .await
+ .map_err(|e| e.to_string())?
+ .map_err(|e| e.to_string())?;
+ self.mark(&path, chunk, size).map_err(|e| e.to_string())?;
+ }
+ }
+ let p = path.clone();
+ tokio::task::spawn_blocking(move || get(&p, offset, end - offset))
+ .await
+ .map_err(|e| e.to_string())?
+ .map_err(|e| e.to_string())
+ }
+}
+
+/// Bytes written at `at` in the sparse file, made its full size first.
+fn put(path: &Path, at: u64, bytes: &[u8], size: u64) -> std::io::Result<()> {
+ use std::os::unix::fs::FileExt;
+ let file = std::fs::OpenOptions::new()
+ .create(true)
+ .truncate(false)
+ .write(true)
+ .open(path)?;
+ if file.metadata()?.len() != size {
+ file.set_len(size)?;
+ }
+ file.write_all_at(bytes, at)?;
+ file.sync_data()
+}
+
+fn get(path: &Path, at: u64, len: u64) -> std::io::Result<Vec<u8>> {
+ use std::os::unix::fs::FileExt;
+ let file = std::fs::File::open(path)?;
+ let mut out = vec![0u8; usize::try_from(len).unwrap_or(0)];
+ file.read_exact_at(&mut out, at)?;
+ Ok(out)
+}
+
+/// Whether the program asking is a file manager's thumbnailer. Reading a whole file only to
+/// draw a small picture of it would download every file a folder shows: such a read of a
+/// file not on this computer is refused, and the file manager draws its plain icon instead.
+/// (GLib treats a FUSE folder as local — glocalfile.c's is_remote_fs_type — so GNOME Files
+/// thumbnails everything in it.)
+///
+/// Named exactly, never broadly: a viewer opening a picture (Loupe's glycin loaders), a
+/// Flatpak app (bwrap) or KDE copying a file (a kioworker) must still read it. KDE's thumbnail
+/// worker is a kioworker running thumbnail.so, told apart by its command line.
+#[must_use]
+pub fn is_thumbnailer(comm: &str, cmdline: &str) -> bool {
+ let comm = comm.trim();
+ let named = [
+ "gnome-thumbnail",
+ "totem-video-thu",
+ "evince-thumbnai",
+ "ffmpegthumbnail",
+ "gst-video-thumb",
+ "gdk-pixbuf-thum",
+ "tumblerd",
+ "papers-thumbnai",
+ ]
+ .iter()
+ .any(|t| comm.starts_with(t));
+ named || (comm == "kioworker" && cmdline.contains("thumbnail"))
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+
+ fn item(
+ id: &str,
+ name: &str,
+ ext: Option<&str>,
+ kind: &str,
+ size: i64,
+ etag: &str,
+ ) -> DriveItem {
+ DriveItem {
+ drivewsid: id.into(),
+ parent_id: Some(ROOT.into()),
+ name: name.into(),
+ extension: ext.map(Into::into),
+ kind: kind.into(),
+ size: Some(size),
+ child_count: None,
+ created_at: None,
+ modified_at: None,
+ etag: Some(etag.into()),
+ }
+ }
+
+ #[test]
+ fn names_are_never_lost_to_each_other() {
+ let items = [
+ item("a", "Report", Some("pdf"), "FILE", 1, "e"),
+ item("b", "Report", Some("pdf"), "FILE", 1, "e"),
+ item("c", "a/b", None, "FOLDER", 0, "e"),
+ item("d", "..", None, "FOLDER", 0, "e"),
+ ];
+ let names: Vec<String> = named(&items).into_iter().map(|(n, _)| n).collect();
+ assert_eq!(names, ["Report.pdf", "Report (2).pdf", "a∕b", ".._"]);
+ }
+
+ #[test]
+ fn inodes_are_stable() {
+ let mut inodes = Inodes::new();
+ let a = item("FILE::x::1", "a", None, "FILE", 1, "e");
+ let first = inodes.ino(&a);
+ assert_eq!(inodes.ino(&a), first);
+ assert_ne!(first, 1);
+ assert_eq!(inodes.item(1).map(|i| i.drivewsid.as_str()), Some(ROOT));
+ }
+
+ struct Bytes(Vec<u8>, Mutex<Vec<(u64, u64)>>);
+ impl Remote for Bytes {
+ fn list(&self, _: &str) -> Fut<Vec<DriveItem>> {
+ Box::pin(async { Ok(Vec::new()) })
+ }
+ fn read(&self, _: &DriveItem, offset: u64, len: u64) -> Fut<Vec<u8>> {
+ self.1.lock().unwrap().push((offset, len));
+ let out = self.0
+ [usize::try_from(offset).unwrap()..usize::try_from(offset + len).unwrap()]
+ .to_vec();
+ Box::pin(async move { Ok(out) })
+ }
+ }
+
+ /// Only the chunks read are fetched, each once; the bytes are the file's; a new version
+ /// of the file is never served from the old one's copy.
+ #[tokio::test]
+ async fn reads_fetch_each_chunk_once() {
+ let dir = tempfile::tempdir().unwrap();
+ let cache = Cache::new(dir.path()).unwrap();
+ let size = CHUNK * 2 + 100;
+ let data: Vec<u8> = (0..size).map(|i| (i % 251) as u8).collect();
+ let remote = Bytes(data.clone(), Mutex::new(Vec::new()));
+ let f = item(
+ "FILE::x::1",
+ "film",
+ Some("mov"),
+ "FILE",
+ i64::try_from(size).unwrap(),
+ "v1",
+ );
+ let got = cache.read(&remote, &f, CHUNK - 10, 20).await.unwrap();
+ assert_eq!(
+ got,
+ data[usize::try_from(CHUNK - 10).unwrap()..usize::try_from(CHUNK + 10).unwrap()]
+ );
+ assert_eq!(
+ remote.1.lock().unwrap().clone(),
+ vec![(0, CHUNK), (CHUNK, CHUNK)],
+ "the two chunks it spans"
+ );
+ cache.read(&remote, &f, 5, 5).await.unwrap();
+ assert_eq!(remote.1.lock().unwrap().len(), 2, "kept, not fetched again");
+ let tail = cache.read(&remote, &f, size - 50, 500).await.unwrap();
+ assert_eq!(tail.len(), 50, "cut at the end of the file");
+ assert!(cache.whole(&f));
+ // Kept across a restart: a new cache over the same folder knows what is there.
+ let again = Cache::new(dir.path()).unwrap();
+ assert!(again.whole(&f));
+ // Changed on another device: a new version is fetched afresh.
+ let f2 = item(
+ "FILE::x::1",
+ "film",
+ Some("mov"),
+ "FILE",
+ i64::try_from(size).unwrap(),
+ "v2",
+ );
+ assert!(!again.whole(&f2));
+ }
+
+ #[test]
+ fn thumbnailers_are_known() {
+ assert!(is_thumbnailer("gnome-thumbnail", ""));
+ assert!(is_thumbnailer("totem-video-thu\n", ""));
+ assert!(is_thumbnailer(
+ "kioworker",
+ "/usr/lib/kf6/kioworker /usr/lib/qt6/plugins/kf6/kio/thumbnail.so"
+ ));
+ assert!(!is_thumbnailer(
+ "kioworker",
+ "/usr/lib/kf6/kioworker /usr/lib/qt6/plugins/kf6/kio/file.so"
+ ));
+ assert!(
+ !is_thumbnailer("glycin-image-rs", ""),
+ "a viewer opening a picture"
+ );
+ assert!(!is_thumbnailer("libreoffice", ""));
+ }
+}
diff --git a/crates/quince-vfs/tests/mount.rs b/crates/quince-vfs/tests/mount.rs
new file mode 100644
index 0000000..559d80a
--- /dev/null
+++ b/crates/quince-vfs/tests/mount.rs
@@ -0,0 +1,184 @@
+//! A real FUSE mount of a made-up iCloud Drive, used the way any program uses a folder:
+//! listing, stat, reading whole files and parts of them, a folder never listed fetched once,
+//! and writes refused (read-only for now). Skipped where FUSE is not available.
+#![cfg(target_os = "linux")]
+
+use quince_core::drive::DriveItem;
+use quince_vfs::{fuse, Cache, Fut, Remote, Store, CHUNK, ROOT};
+use std::collections::HashMap;
+use std::sync::{Arc, Mutex};
+
+fn item(id: &str, parent: &str, name: &str, ext: Option<&str>, kind: &str, size: i64) -> DriveItem {
+ DriveItem {
+ drivewsid: id.into(),
+ parent_id: Some(parent.into()),
+ name: name.into(),
+ extension: ext.map(Into::into),
+ kind: kind.into(),
+ size: Some(size),
+ child_count: None,
+ created_at: Some(1_700_000_000),
+ modified_at: Some(1_700_000_100),
+ etag: Some("e1".into()),
+ }
+}
+
+struct Apple {
+ folders: HashMap<String, Vec<DriveItem>>,
+ files: HashMap<String, Vec<u8>>,
+ lists: Mutex<Vec<String>>,
+ reads: Mutex<Vec<(u64, u64)>>,
+}
+impl Remote for Apple {
+ fn list(&self, folder: &str) -> Fut<Vec<DriveItem>> {
+ self.lists.lock().unwrap().push(folder.to_string());
+ let out = self.folders.get(folder).cloned().unwrap_or_default();
+ Box::pin(async move { Ok(out) })
+ }
+ fn read(&self, item: &DriveItem, offset: u64, len: u64) -> Fut<Vec<u8>> {
+ self.reads.lock().unwrap().push((offset, len));
+ let data = &self.files[&item.drivewsid];
+ let out = data[offset as usize..(offset + len) as usize].to_vec();
+ Box::pin(async move { Ok(out) })
+ }
+}
+/// The library: the root is known, "Work" never listed.
+struct Library(HashMap<String, Vec<DriveItem>>);
+impl Store for Library {
+ fn children(&self, folder: &str) -> Option<Vec<DriveItem>> {
+ self.0.get(folder).cloned()
+ }
+}
+
+#[test]
+fn a_mounted_drive_reads_like_a_folder() {
+ if !std::path::Path::new("/dev/fuse").exists() {
+ eprintln!("no FUSE here; skipped");
+ return;
+ }
+ let film: Vec<u8> = (0..(CHUNK * 2 + 1234)).map(|i| (i % 253) as u8).collect();
+ let note = b"hello from iCloud\n".to_vec();
+ let mut work = item("FOLDER::z::work", ROOT, "Work", None, "FOLDER", 0);
+ work.child_count = Some(1);
+ let root = vec![
+ work,
+ item(
+ "FILE::z::note",
+ ROOT,
+ "Note",
+ Some("txt"),
+ "FILE",
+ note.len() as i64,
+ ),
+ item(
+ "FILE::z::film",
+ ROOT,
+ "Film",
+ Some("mov"),
+ "FILE",
+ film.len() as i64,
+ ),
+ ];
+ let deck = item(
+ "FILE::z::deck",
+ "FOLDER::z::work",
+ "Deck",
+ Some("key"),
+ "FILE",
+ 5,
+ );
+ let apple = Arc::new(Apple {
+ folders: HashMap::from([("FOLDER::z::work".to_string(), vec![deck.clone()])]),
+ files: HashMap::from([
+ ("FILE::z::note".to_string(), note.clone()),
+ ("FILE::z::film".to_string(), film.clone()),
+ ("FILE::z::deck".to_string(), b"slide".to_vec()),
+ ]),
+ lists: Mutex::new(Vec::new()),
+ reads: Mutex::new(Vec::new()),
+ });
+ let library = Arc::new(Library(HashMap::from([(ROOT.to_string(), root)])));
+ let rt = tokio::runtime::Runtime::new().unwrap();
+ let cache_dir = tempfile::tempdir().unwrap();
+ let at = tempfile::tempdir().unwrap();
+ let fs = fuse::DriveFs::new(
+ apple.clone(),
+ library,
+ Arc::new(Cache::new(cache_dir.path()).unwrap()),
+ rt.handle().clone(),
+ );
+ let session = fuse::mount(fs, at.path()).expect("mounted");
+
+ let mut names: Vec<String> = std::fs::read_dir(at.path())
+ .unwrap()
+ .map(|e| e.unwrap().file_name().into_string().unwrap())
+ .collect();
+ names.sort();
+ assert_eq!(
+ names,
+ ["Film.mov", "Note.txt", "Work"],
+ "the root, from the library"
+ );
+ assert!(
+ apple.lists.lock().unwrap().is_empty(),
+ "nothing asked of Apple to list a known folder"
+ );
+
+ let meta = std::fs::metadata(at.path().join("Film.mov")).unwrap();
+ assert_eq!(meta.len(), film.len() as u64);
+ assert!(
+ apple.reads.lock().unwrap().is_empty(),
+ "a stat downloads nothing"
+ );
+
+ assert_eq!(
+ std::fs::read(at.path().join("Note.txt")).unwrap(),
+ note,
+ "a small file reads whole"
+ );
+
+ // A part of a large file: only the chunk it is in is fetched.
+ use std::io::{Read, Seek, SeekFrom};
+ let mut f = std::fs::File::open(at.path().join("Film.mov")).unwrap();
+ f.seek(SeekFrom::Start(CHUNK + 10)).unwrap();
+ let mut buf = [0u8; 100];
+ f.read_exact(&mut buf).unwrap();
+ assert_eq!(
+ &buf[..],
+ &film[(CHUNK + 10) as usize..(CHUNK + 110) as usize]
+ );
+ assert!(
+ apple.reads.lock().unwrap().contains(&(CHUNK, CHUNK))
+ && !apple.reads.lock().unwrap().contains(&(0, CHUNK)),
+ "only the chunk read was fetched: {:?}",
+ apple.reads.lock().unwrap()
+ );
+ assert_eq!(
+ std::fs::read(at.path().join("Film.mov")).unwrap(),
+ film,
+ "and the whole film reads right"
+ );
+
+ // A folder never listed: fetched once from Apple, then known.
+ let inner: Vec<String> = std::fs::read_dir(at.path().join("Work"))
+ .unwrap()
+ .map(|e| e.unwrap().file_name().into_string().unwrap())
+ .collect();
+ assert_eq!(inner, ["Deck.key"]);
+ assert_eq!(
+ std::fs::read(at.path().join("Work/Deck.key")).unwrap(),
+ b"slide"
+ );
+
+ // Read-only, for now: a write is refused, never half-done.
+ let err = std::fs::write(at.path().join("Note.txt"), b"x").unwrap_err();
+ assert_eq!(err.raw_os_error(), Some(libc::EROFS), "{err}");
+ assert_eq!(std::fs::read(at.path().join("Note.txt")).unwrap(), note);
+
+ drop(session);
+ assert_eq!(
+ std::fs::read_dir(at.path()).unwrap().count(),
+ 0,
+ "unmounted when the session ends"
+ );
+}