A Linux desktop app that syncs a Proton Drive account into a local folder. Built as a MyGo (Go) desktop shell (mygo-shell/) driving a Go sync engine (engine-go/), which calls the official Proton Drive TypeScript SDK running in an embedded Node.js sidecar. (macOS and Windows were dropped in v0.2; the desktop app defaults to on-demand placeholders — the sync root is a FUSE view that hydrates on open — with a full materialized mirror available in Settings, see F5.)
Goals
- G1: One Proton account, one sync root folder.
- G2: Files copied into the folder upload automatically.
- G3: Files deleted locally are trashed remotely — conservatively, never irreversibly.
- G4: Pause / resume sync at any time, resumable transfers.
- G5: On-demand placeholder files (M3): near-zero SSD usage until a file is opened or pinned.
- G6: Event-based remote change detection (mandated by Proton's usage guidelines — no polling or recursive scans).
Non-goals (v1)
- macOS support, multiple accounts, multiple sync roots, share-link management, file versioning UI, mobile.
Three components:
| Component | Tech | Role |
|---|---|---|
| Host app (UI + orchestrator) | MyGo shell (mygo-shell/, Go; MyGo UI toolkit) |
Single main window, drives the engine over a JSON-line Unix socket, tray/autostart/single-instance |
| Sync engine | Go (engine-go/, binary pds-engine-go) |
Owns state DB, sync engine, upload/download queues, VFS store |
| SDK sidecar | Node.js + ProtonDriveApps/sdk (client module) |
All Drive traffic: auth session, listing, up/download, trash, event stream |
| VFS (M3 ✅) | Go, go-fuse (engine-go/internal/vfs/) |
Placeholder view of the remote tree — mounted at the sync root by the engine, or at a separate mountpoint by the shell; reads hydrate, writes queue uploads |
- IPC: shell ↔ engine over a JSON-line Unix socket; engine ↔ Node sidecar over JSON-RPC on stdio.
- State: SQLite in the engine — node map (local path ↔ Drive node UID), pins, tombstones, transfer queue, eviction metadata, event cursor (resume token).
- Auth: The SDK deliberately excludes login. The sidecar implements Proton auth (browser session-fork; SRP kept behind
PDS_AUTH=srp) against official endpoints, modeled on how first-party clients wire it. The session is a0600file (session.json) under$XDG_DATA_HOME/proton-drive-sync/. Login screen shows the mandated disclosure: "This is a third-party application not officially supported by Proton."
Why the sidecar: the official SDK is the only implementation guaranteed to track the 2026/27 cryptographic migration. Upgrading the sidecar's npm dependency is our migration strategy — no client-side crypto to rewrite.
Login (browser session-fork, 2FA supported) → sync root (default ~/ProtonDrive) → remote tree materializes → event cursor stored. First-run rule: an empty local folder is never interpreted as "delete everything."
Reserved names: .pds (engine state: SQLite DB, control socket) and .pds-vfs-backing (placeholder backing cache) at the sync root are engine-internal. The sync pipeline never uploads, trashes, or adopts them. If a user item uses either name it is left untouched and surfaced once as Skipped in Activity ("reserved engine-internal name"), never silently invisible.
Filesystem watcher reports create/close-write → hash → upload via sidecar (SDK handles block splitting/encryption) → SQLite mapping updated. Debounce rapid writes; retry with exponential backoff; resumable block uploads for large files. M4 ✅: exponential schedule verified (base·2ⁿ capped at 5 min, unit-tested); a server Retry-After hint (rate-limit 1003 → transfer.error.retryAfter) is honored in place of the computed schedule; explicit resume drops pending backoffs ("try now"); a terminally errored node heals on a fresh local edit.
Metadata fidelity (D6/D2): the upload carries the file's own mtime (not the wall clock at upload time), and the local row records it. Downloads apply the remote mtime to the local file in both mirror and placeholder modes, including after eviction/rehydration. POSIX permission bits are persisted locally only (nodes.mode, owner-exec included) and reapplied on download/hydration; Drive's node metadata has no mode field, so mode is never sent remotely. A timestamp-only setattr updates SQLite and the VFS snapshot but deliberately does not queue a revision — the content hash is unchanged, so uploading would be pure metadata churn; the stored mtime rides along on the next real content edit instead of being lost.
- Only propagate deletes for nodes previously confirmed synced (present in SQLite). Unknown/never-synced items deleted locally are simply removed locally.
- Remote action is always Trash (recoverable in Proton Drive), never permanent delete.
- Mass-deletion guard: >20 deletes or >25% of synced nodes within a short window → auto-pause + user confirmation dialog. The ratio limb is strict: one delete trips on a 2-node tree (1 > 0.5) but is allowed on a 4-node tree (1 > 1.0). The pause is durable (
meta.guard_paused): a restart comes back guard-paused and requires the same explicit resume before any queued tombstone drains, so a fresh in-memory window can never quietly finish a blocked deletion wave. - Offline deletes are recorded as tombstones and applied on resume/reconnect — same guard applies.
Pause: freezes upload + download queues mid-transfer (block-level resume), stops event application (cursor kept), watcher keeps buffering changes. Resume: drains tombstones (with guard), then uploads, then applies pending remote events.
- All remote items visible in the sync root at ~0 bytes locally.
- Desktop app (M3.4 ✅ 2026-10-30): placeholder mode is the default for new sync roots. The app mounts the FUSE view at the sync root itself (
~/ProtonDriveis the placeholder view), so users find files where they expect them. The engine's state (SQLite DB, backing cache) lives under$XDG_DATA_HOME/proton-drive-sync/roots/<hash>/, outside the root — a directory cannot serve both its real contents and a mount over it, and running the DB through the mount would risk corruption. The mount goes up only after the engine's initial sync (the first-run local scan must see the real folder). If FUSE is unavailable the app falls back to a materialized session and says so in Settings. A Settings → Sync mode toggle switches between On demand and Mirror (confirm dialog; the engine restarts into the new mode). Mode is persisted per root in the DB'smetatable (sync_mode);$PDS_SYNC_MODEoverrides for one session; roots with a legacy (pre-0.3) in-root state DB default to mirror so upgrades change nothing for existing users. - Conversion: switching modes moves existing content instead of re-transferring — mirror→placeholders moves every tracked file into the backing cache (hydrated, no download; untracked leftovers become dirty pending-uploads so nothing is stranded under the mount), placeholders→mirror moves hydrated files back into the root (never evicted content re-downloads via the normal materialization pass). Idempotent, crash-restartable, never deletes.
- Hydration: on file open (FUSE read), content is fetched on demand.
- Write-through (M3.2 ✅ 2026-10-29): files created through the mount upload on close (
release/fsync);mkdir/unlink/rmdirmirror remotely (trash path). Backing content lives in.pds-vfs-backing/; uploads reuse the standard engine machinery (F7 collision check, retries, pause buffering). The mount itself is RW. - Revision writes (M3.3 ✅ 2026-10-29): snapshot-backed files open RW through the mount; the open waits (bounded) for hydration, edits land on the backing file, and
release/fsyncupload the revision against the existingnode_uid(F7check_remote_headguards stale heads).O_TRUNC(e.g.fs::write) works: fuser does not negotiateATOMIC_O_TRUNC, so truncation arrives assetattr(size, fh)and defers to the open handle'srelease— one upload per write sequence, no empty intermediate.truncate(2)outside a handle queues the upload directly. - Pin/unpin (M3.2 ✅ 2026-10-29):
pds pin <folder> <path>marks the row pinned in the DB and hydrates it immediately; folder paths pin recursively. Pinned files are never evicted. - Eviction (M3.2 ✅ 2026-10-29): LRU cache with a configurable size cap. Never evicts pinned, dirty (un-uploaded), or open files, nor the file that just hydrated. Runs on the engine's idle path after hydrations; the snapshot flips
content_readyback so the placeholder reappears immediately. Cap (M3.5 ✅ 2026-10-30): configurable on three surfaces — a per-root persisted Settings choice (Settings → Sync mode → Local cache, presets 2/5/10/25 GB or Unlimited),$PDS_CACHE_CAP(session-only), andpds mount --cache-cap <SIZE>(one invocation) — with precedence flag > env > Settings > the 10 GiB default. Settings changes apply live viaCommand::SetEvictionCap(immediate eviction pass when the new cap is already exceeded);unlimiteddisables eviction on every surface. - POSIX semantics (Wave 5a ✅ 2026-11-04): open descriptors are authoritative.
mmapreads work for hydrated files and hydrate placeholders on the faulting read;O_APPEND, offset writes (pwrite), truncate-grow, rename-over-open, and unlink-while-open all follow POSIX: an fd keeps the inode it opened even after its path is replaced or removed, while the path converges on the new content and uploads exactly one revision.statvfsreports the backing filesystem's real non-zero capacity (walking to an existing ancestor, then the state dir, then a synthetic 1 TiB), never zeros. Special files are never followed, opened, hashed, or uploaded: symlinks, FIFOs, sockets, and device nodes are skipped and surfaced once per path asSkippedin the activity feed. Hardlinks (nlink > 1) are ordinary regular files: each name uploads as an independent node and the link relationship is not preserved.
M3 progress (2026-10-29): placeholder mount, hydration, write-through, pins, LRU eviction, and in-place revision writes all work end-to-end (engine tests + real-kernel FUSE E2E in the VM). M3 is complete; M4 (hardening) next.
Sidecar consumes the SDK event stream; host applies create/update/trash events to the local tree. Cursor persisted so restarts catch up without full scans.
Keep-both: the losing version is renamed name (conflict YYYY-MM-DD HHmm).ext; no silent overwrites in either direction. The timestamp is generated in UTC so a DST fold or a backwards clock correction cannot reuse a name; dedup is existence-based, so conflict copies from older local-time builds remain valid and are never overwritten. If the stamped name (or … (2), … (3), …) is already taken by a user file or another conflict copy, the next free sibling is used — the search advances monotonically and never reuses or overwrites an existing path, including when the conflicting item's own name already looks like a conflict copy.
The desktop app is the long-running sync service; there is no separate daemon.
- Start at login: an XDG autostart entry
(
$XDG_CONFIG_HOME/autostart/proton-drive-sync.desktop) launchesproton-drive-sync --minimizedafter the graphical session comes up. The dashboard window is not opened: the process runs with only its tray icon and creates the window on first use (tray click, menu action, or a second launch). Systemd user units are not used: the tray needs the session and the FUSE mount must share the process lifetime. Installed builds enable it on first run;Settings → Startuptoggles it, and the decision is persisted in$XDG_CONFIG_HOME/proton-drive-sync/app.confso a manual removal is never silently undone. TheExec=path preserves distribution wrappers (argv[0]) so Nix/Node environment injection survives. - Tray icon: StatusNotifierItem via
gpui-tray(zbus on Linux). The icon is drawn in code (no asset/theme dependency) with a status dot: running, paused, delete-guard, sign-in required, stopped. Menu: Open Dashboard, Pause/Resume, Open Sync Folder, Preferences…, Quit; primary activation opens the dashboard. - Window lifecycle: a login start (
--minimized) opens no dashboard window; it is created on first use. Closing it minimizes while the tray is usable (GPUI 0.2's Linux backend stops the event loop when the last window is destroyed, and exposes no unminimize); with no tray host the close quits and login start opens the dashboard instead of running windowless.Quitlives in the tray and in Settings. - Single instance: a later launch sends
showover$XDG_RUNTIME_DIR/proton-drive-sync.sockand exits, so two engines can never share one SQLite DB / FUSE mount. - Tray availability is probed over D-Bus (
org.kde.StatusNotifierWatcher). GNOME needs the AppIndicator extension; bare compositors need a panel (waybar etc.). The app degrades to "dashboard at login" without one. - Explicitly not done: syncing while nobody is logged in (no system daemon), multiple instances, and GNOME's built-in tray (it has none).
x-pm-appversion: external-drive-{name}@{semver}-{channel}— honest, non-spoofed.- Event-based sync only; SDK-grade caching, parallelism limits, exponential backoff.
- No Proton logos/branding; clearly unofficial; credential-prompt disclosure text.
One main window: sidebar navigation (Overview / Activity / Conflicts / Settings) · account + engine-state badge · big pause/resume toggle · activity/event log · conflicts + failed-uploads inbox (from the state DB) · settings for the sync root, the sync mode (on-demand placeholders ⇄ mirror, with a confirm dialog and one-time layout notices), and start at login. Browser-based sign-in with the mandated disclosure; sign-out confirmation modal. Keyboard-first: actions bound in crates/app/src/actions.rs.
A tray icon mirrors the engine state and offers Open Dashboard / Pause-Resume / Open Sync Folder / Preferences / Quit (F8). Closing the window keeps the service running; the dashboard is one click away.
- M0 — Spike: headless Node script proving auth + list/upload/download/trash + event stream via the SDK. Go/no-go gate. ✅ 2026-10-23.
- M1 — Headless sync engine (CLI): local folder ↔ Drive, F2/F3/F4/F7 with real files (no VFS yet), SQLite state. ✅ 2026-10-24 (live E2E).
- M2 — GPUI desktop shell (Linux): single-window app; login, overview, activity, conflicts, settings, sign-out. ✅ 2026-10-29 (rewritten from the v0.1 tray shell when the project went Linux-only).
- M3 — Linux VFS: FUSE mount, placeholders, hydration (M3.1 ✅ 2026-10-29), write-through + pins + LRU eviction (M3.2 ✅ 2026-10-29, E2E-proven in the VM), revision writes (M3.3 ✅ 2026-10-29), desktop integration: placeholder mode as the app default, mount at the sync root, external engine state, mode setting + safe conversion (M3.4 ✅ 2026-10-30).
- M4 — Hardening: conflict soak tests, backoff/rate-limit validation, SDK upgrade rehearsal (M4 ✅ 2026-10-30 — see
docs/sdk-upgrade-rehearsal.md; soak found + fixed the F7 remote-delete race, crash-interrupted transfers now recover on startup). - M5 — Background service, login start, tray (F8): ✅ 2026-10-31 — XDG autostart with a persisted toggle, StatusNotifierItem tray with status icon and actions, close-to-tray window lifecycle, single-instance socket, no-tray-host fallback.
- Auth is DIY — biggest unknown; de-risked in M0 (reference: first-party clients,
proton-sdk-rs2). - Crypto migration (end 2026/early 2027) — mitigated by pinning to the official SDK and tracking releases.
- SDK interface churn — isolate all SDK calls behind one sidecar module.
- GPUI on Linux — GPU drivers vary widely; the app must start (or degrade cleanly) under software rendering (llvmpipe); validated with Xvfb before each release.
FUSE mountpoint UX: M3.1 ships the parallel mount (Resolved (M3.4): the desktop app mounts the placeholder view at the sync root and keeps all engine state (SQLite, backing cache) inpds mount <folder> <mountpoint>); whether to also bind-mount into the real root is deferred until desktop-app UX decides where users look for files.$XDG_DATA_HOME/proton-drive-sync/roots/<hash>/outside it; the parallelpds mountremains for CLI use.FUSE write-through (M3.2): direct vs through-the-watcherResolved (M3.2): neither — the VFS queues writes in the engine↔VFSStore(record_write/record_mkdir/record_delete) and the engine's main loop drains them through the same upload/delete machinery the watcher uses (F7 precondition, retries, pause buffering). No watcher noise from the backing dir; no duplicate dedup logic in the FUSE layer.Local name/path fidelity: how to treat case-only renames and names the filesystem cannot holdResolved (TG-12/TG-14): a case-only local rename reuses the node identity (filesystem inode pairing), so it mirrors as a rename instead of trash + re-upload. Folder depth is not artificially capped; the OSPATH_MAX/NAME_MAXare the boundary, and a remote path beyond them is surfaced once as aSkippedactivity and left out of the mirror — no partial directory chain and no retry loop, while the rest of the sync continues.- Exact mass-deletion guard thresholds after real-world usage data.