chore(drive): address review feedback — quota counter, orphan reap, docs

Author: dazzling-no-more

README.md

@@ -336,6 +336,33 @@ Tune `drive_idle_timeout_secs` (default 300) upward if you tunnel long-poll HTTP
 
 > **Security note:** `mhrv-drive-node` is effectively an open TCP relay for whoever has read/write access to the shared Drive folder — anything that can drop a `req-…mux-…bin` file in there can open arbitrary `host:port` connections through the node. Keep the folder narrowly scoped (one OAuth account, no link sharing) and don't run the node on a machine you don't control.
 
+### Onboarding a non-technical user (Android)
+
+Once one device has finished OAuth, you can hand the configured state to another via QR or text — no Cloud Console steps required on the receiving end. In the Drive section: **Share Drive setup** → **Show QR + payload** → copy / send the `mhrv-rs-setup://...` link via WhatsApp / Telegram / SMS. The recipient pastes the link, scans the QR, picks the QR image from their gallery, or just taps the link if their messenger linkifies it. The bundle includes the OAuth refresh token, so they don't run their own consent flow — they share the sharer's Google identity for `drive.file` scope.
+
+Caveat: the **sharer** still needs an unfiltered path to `accounts.google.com` for the initial OAuth dance, since the consent page opens in their system browser. If your network blocks Google Accounts, do the initial OAuth on a different network (mobile data, friend's Wi-Fi) and then share the resulting setup. Recipients aren't bound by this — they get the refresh token via the QR.
+
+When the consent page warns _"Google hasn't verified this app"_, that's expected for personal Cloud projects in **Testing** publication status. Click **Advanced → Go to mhrv-drive (unsafe)** → grant the `drive.file` scope. Same flow as deploying an Apps Script for the existing modes.
+
+### Quota and reachability
+
+Google Drive's free-tier per-user quota is **1,000 requests per 100 seconds**. Default `drive_poll_ms = 100` plus `drive_flush_ms = 100` is comfortably below that even under heavy traffic, but if you turn polling down further or run a single OAuth identity across many devices you can blow it. The Rust side logs a `WARN` at 80% and `ERROR`s past 100% — watch for `Drive API rate climbing` in the logs. Bump `drive_poll_ms` / `drive_flush_ms` if you see them.
+
+Before deploying, sanity-check that your network can actually reach Drive's edge IPs. The most informative test (from the host that will run `mhrv-drive-node` or the client):
+
+```bash
+curl --resolve www.googleapis.com:443:216.239.38.120 \
+     -I https://www.googleapis.com/drive/v3/files
+```
+
+A 401 response (no auth) is success — it means TCP reached Google and the TLS handshake completed. A connect timeout, RST, or TLS error means the same DPI / RST-injection path that affects the Apps Script outbound also hits Drive's API endpoint, and this mode won't work better than the existing Apps Script ones on that network.
+
+### Garbage collection
+
+Both sides reap their own files via `cleanup_loop` (every 5 s, deletes own files older than `OLD_FILE_TTL = 60 s` using Drive's `createdTime` so cross-machine clock skew can't false-positive). The poll path also auto-deletes peer files older than `STARTUP_STALE_TTL = 5 min` that look like leftovers from a previous run, plus reaps orphan response files for our own client ID at the same TTL — covers the edge case where `mhrv-drive-node` dies mid-batch and can't run its own cleanup.
+
+If you ever notice `MHRV-Drive` accumulating files past these windows, check the Live logs / Docker logs on both sides for poll errors that prevent the cleanup loop from firing.
+
 ## Running on OpenWRT (or any musl distro)
 
 The `*-linux-musl-*` archives ship a fully static CLI that runs on OpenWRT, Alpine, and any libc-less Linux userland. Put the binary on the router and start it as a service:

src/drive_tunnel.rs

@@ -646,6 +646,42 @@ impl DriveEngine {
                     }
                 }
             }
+
+            // Reap orphan peer files. Normal flow has each side
+            // deleting its own files via `cleanup_loop` above plus the
+            // `processed`-then-delete path in `poll_once`. The edge
+            // case is the peer dying mid-batch: a `res-*` file it
+            // wrote remains in the folder, the dead node can't run
+            // its own cleanup, and our own cleanup above only
+            // touches files matching our `my_dir` prefix. Without
+            // the block below, those orphans accumulate forever.
+            //
+            // Scoped to `<peer_dir>-<my_client_id>-mux-` so a single
+            // client sharing a folder with several others doesn't
+            // touch their in-flight files. Uses STARTUP_STALE_TTL
+            // (5 min) — much longer than the per-file lifetime in
+            // normal operation, so this only fires on the orphan
+            // case; a slow round-trip won't trip it.
+            let orphan_prefix = format!(
+                "{}-{}-mux-",
+                self.peer_dir.as_str(),
+                self.client_id,
+            );
+            if !self.client_id.is_empty() {
+                if let Ok(orphans) = self.backend.list_query(&orphan_prefix).await {
+                    if let Some(orphan_cutoff) =
+                        SystemTime::now().checked_sub(STARTUP_STALE_TTL)
+                    {
+                        for file in orphans {
+                            if let Some(created) = file.created_time {
+                                if created < orphan_cutoff {
+                                    let _ = self.backend.delete(&file.name).await;
+                                }
+                            }
+                        }
+                    }
+                }
+            }
         }
     }
 }

src/google_drive.rs

@@ -9,9 +9,18 @@ use std::collections::HashMap;
 use std::fs;
 use std::io::Write;
 use std::path::PathBuf;
+use std::sync::atomic::{AtomicU64, Ordering};
 use std::sync::Arc;
 use std::time::{Duration, Instant, SystemTime, UNIX_EPOCH};
 
+/// Google Drive's free-tier quota is 1000 requests / 100 s / user. We
+/// surface a warning at 80% and an error past 100% so operators see
+/// quota pressure in logs before Drive starts handing back 403s. The
+/// per-project ceiling (10k / 100s / project) is shared across all
+/// users of an OAuth client and isn't observable from one client.
+const DRIVE_QUOTA_PER_USER_100S: u64 = 1000;
+const DRIVE_QUOTA_WARN_THRESHOLD: u64 = (DRIVE_QUOTA_PER_USER_100S * 80) / 100;
+
 use bytes::Bytes;
 use http_body_util::{BodyExt, Full};
 use hyper::client::conn::http2::SendRequest;
@@ -34,6 +43,90 @@ const GOOGLE_API_HOST: &str = "www.googleapis.com";
 const DRIVE_SCOPE: &str = "https://www.googleapis.com/auth/drive.file";
 const HTTP_TIMEOUT: Duration = Duration::from_secs(60);
 
+/// Lock-free counter of Drive REST calls within a 100-second sliding
+/// bucket. The bucket boundary is best-effort — a request right at the
+/// 100s mark may land in the previous or next window, which is fine
+/// since Google's quota is also approximate. Used purely for logging
+/// and the [`QuotaSnapshot`] surface; doesn't gate or rate-limit.
+#[derive(Debug)]
+pub struct QuotaTracker {
+    start: Instant,
+    bucket_start_secs: AtomicU64,
+    bucket_count: AtomicU64,
+    total: AtomicU64,
+}
+
+impl QuotaTracker {
+    fn new() -> Self {
+        Self {
+            start: Instant::now(),
+            bucket_start_secs: AtomicU64::new(0),
+            bucket_count: AtomicU64::new(0),
+            total: AtomicU64::new(0),
+        }
+    }
+
+    /// Bump on every Drive REST call. Returns the count for the
+    /// current 100-second window so callers can decide if the rate
+    /// looks scary. Logs a warning at 80% of the per-user quota and
+    /// an error past 100%, throttled to once per 50 calls past the
+    /// limit so we don't spam the log under sustained overrun.
+    fn record_call(&self) -> u64 {
+        let now_secs = self.start.elapsed().as_secs();
+        let bucket = self.bucket_start_secs.load(Ordering::Relaxed);
+        if now_secs.saturating_sub(bucket) >= 100 {
+            // Rolling window: stale bucket → reset. Race-prone in the
+            // strict sense (two threads can both reset) but the
+            // off-by-one calls don't matter for a logging counter.
+            self.bucket_start_secs.store(now_secs, Ordering::Relaxed);
+            self.bucket_count.store(0, Ordering::Relaxed);
+        }
+        let count = self.bucket_count.fetch_add(1, Ordering::Relaxed) + 1;
+        self.total.fetch_add(1, Ordering::Relaxed);
+        if count == DRIVE_QUOTA_WARN_THRESHOLD {
+            tracing::warn!(
+                "Drive API rate climbing: {}/100s — free-tier limit is {}/100s/user. \
+                 Consider increasing drive_poll_ms / drive_flush_ms to slow down.",
+                count,
+                DRIVE_QUOTA_PER_USER_100S,
+            );
+        } else if count >= DRIVE_QUOTA_PER_USER_100S && count.is_multiple_of(50) {
+            tracing::error!(
+                "Drive API rate {}/100s — exceeded free-tier per-user quota ({}/100s). \
+                 Expect 403/429 responses. Drive returns these with no Retry-After, so \
+                 the caller has to back off itself.",
+                count,
+                DRIVE_QUOTA_PER_USER_100S,
+            );
+        }
+        count
+    }
+
+    /// Snapshot of the live counters for UI display. Cheap (atomic
+    /// loads only, no allocation).
+    pub fn snapshot(&self) -> QuotaSnapshot {
+        QuotaSnapshot {
+            total: self.total.load(Ordering::Relaxed),
+            current_window: self.bucket_count.load(Ordering::Relaxed),
+            window_secs: 100,
+            quota_per_user: DRIVE_QUOTA_PER_USER_100S,
+        }
+    }
+}
+
+/// Read-only view of the quota counter for UI / status surfaces.
+/// `current_window` is the count of API calls in the most recent
+/// 100-second bucket; `quota_per_user` is the documented free-tier
+/// limit. Workspace / paid Cloud projects get higher ceilings, but
+/// without knowing the user's project tier we display the floor.
+#[derive(Clone, Copy, Debug, Default, serde::Serialize)]
+pub struct QuotaSnapshot {
+    pub total: u64,
+    pub current_window: u64,
+    pub window_secs: u64,
+    pub quota_per_user: u64,
+}
+
 #[derive(Debug, thiserror::Error)]
 pub enum DriveError {
     #[error("io: {0}")]
@@ -73,6 +166,10 @@ struct GoogleApiClient {
     /// The live HTTP/2 sender. `None` until first use, replaced if a
     /// request fails because the connection went away.
     sender: Mutex<Option<SendRequest<Full<Bytes>>>>,
+    /// Per-process Drive REST call counter. Wrapped in `Arc` so the
+    /// outer [`GoogleDriveBackend`] can hand snapshots to the UI
+    /// without holding a lock on this client.
+    quota: Arc<QuotaTracker>,
 }
 
 struct HttpResponse {
@@ -105,6 +202,7 @@ impl GoogleApiClient {
             host_header,
             tls_connector: TlsConnector::from(Arc::new(tls_config)),
             sender: Mutex::new(None),
+            quota: Arc::new(QuotaTracker::new()),
         }
     }
 
@@ -156,6 +254,12 @@ impl GoogleApiClient {
         headers: Vec<(String, String)>,
         body: &[u8],
     ) -> Result<HttpResponse, DriveError> {
+        // Tick the rate counter on every Drive REST call. This is what
+        // surfaces "you're about to hit the free-tier quota" warnings
+        // in the log without any UI work, and what feeds [`quota()`]
+        // for surfaces that want to display it.
+        self.quota.record_call();
+
         // Build the request once. The :authority pseudo-header is what
         // routes the request inside Google's HTTP/2 frontend; it must be
         // the API host even though we're connected via SNI=front_domain.
@@ -776,6 +880,14 @@ impl GoogleDriveBackend {
     pub fn credentials_path(&self) -> &PathBuf {
         &self.credentials_path
     }
+
+    /// Snapshot of the Drive API rate counter — total calls since
+    /// process start plus the count in the most recent 100-second
+    /// window. Used by stats / status surfaces that want to render a
+    /// quota meter; cheap (atomic loads only).
+    pub fn quota_snapshot(&self) -> QuotaSnapshot {
+        self.api.quota.snapshot()
+    }
 }
 
 fn http_error(resp: HttpResponse) -> DriveError {