Make storage pluggable, and prove it with a folder backend

`RemoteBackend` existed from the first release and bought nothing it was designed for. Seven files in `dr-ui` constructed a `NextcloudBackend` directly, an account *was* a server URL beside a DAV user id, the local cache directory was named after a hostname, and the launch screen knew that signing in meant a browser handshake. The trait was real; the seam was documentation. A trait over operations is only a quarter of it. Pluggable storage needs four things, and this adds the other three: - **Capabilities** — already there, and the reason the engine can drive two backends at the speed each actually runs at. - **Configuration** — `dr_sync::Account`: where a library lives, in whatever form its connector addresses, with no server in it. Loads every existing config unchanged (`backend` defaults to `nextcloud`, `endpoint` is stored under its historical `server` key), and `Account::namespace()` reproduces the old catalog directory byte for byte, because changing it would abandon a catalog, its thumbnail shards, and the sidecars holding unsynced offline work. - **Registration** — `BackendProvider` and `BackendRegistry`. `ui/dr-ui/src/remote.rs` is now the only file above `dr-sync` that names a connector. `Connection` (an account plus an optional `Secret`) replaces the credentials-and-user-id pair that was threaded through fifteen signatures in an order that could be swapped. `Secret`'s inner string is reachable only through `expose()` and its `Debug` prints `Secret(***)`, so the indirect leak — a `{:?}` on anything holding one — no longer compiles into a leak. Nextcloud is unchanged and keeps every peculiarity: propagating ETags, chunked upload v2, `oc:fileid`, the `oc:permissions` probe on a refused PUT, the 423 retry classification, Login Flow v2. Those are what the capability model exists to serve, not something to hide. `dr-sync-folder` is the second connector: a local disk, a network mount, an external drive, or a folder a Nextcloud client already syncs. No account, no credential — the route that works where no secrets daemon does. It declares `LocalEtags` rather than claiming propagation a POSIX directory cannot provide, which costs nothing because 50k `stat` calls are not 50k PROPFINDs. Identity is a path hash, not an inode: an inode survives a rename but differs between devices and is reused after a delete, so two machines would disagree about which photograph a thumbnail belonged to. Re-deriving a thumbnail is a cost; showing the wrong one is a bug. docs/storage.md is the contract — the traits, the four steps to add a backend, and what each connector declares. ARCH §8.0 and §8.4a, and FR-NC-13, say why.
2026-08-29 09:57:52 +02:00
parent 1b8b7998a2
commit f12aece07e
40 changed files with 3617 additions and 960 deletions
@@ -0,0 +1,174 @@
+// TRACES: FR-NC-12 | FR-NC-1
+//! Registering Nextcloud as a storage backend.
+//!
+//! The account model this connector used to own now lives in
+//! [`dr_sync::account`], where it has no server in it. What is left here is
+//! the part that genuinely is Nextcloud: an endpoint is an HTTPS URL, an
+//! account is established through Login Flow v2, and the credential is an app
+//! password.
+//!
+//! Nothing above `dr_ui::remote` refers to this type.
+
+use dr_sync::{
+    Account, BackendProvider, Connection, RemoteBackend, RemoteError, SignIn, LEGACY_BACKEND,
+};
+
+use crate::{AppCredentials, NextcloudBackend};
+
+/// The id written to [`Account::backend`] for a Nextcloud account.
+///
+/// The same string [`dr_sync::LEGACY_BACKEND`] freezes, because every account
+/// configured before there was a choice is one of these and must keep the
+/// catalog directory it already has.
+pub const BACKEND_ID: &str = LEGACY_BACKEND;
+
+/// Registers the Nextcloud connector.
+pub struct NextcloudProvider;
+
+impl NextcloudProvider {
+    /// The account a completed login flow describes.
+    ///
+    /// `user_id` is the DAV path segment, which is not always the login name:
+    /// a login can be an email address while the user id is something else,
+    /// and building `/remote.php/dav/files/<login>/` from the wrong one 404s
+    /// every request.
+    pub fn account_from(creds: &AppCredentials, user_id: impl Into<String>) -> Account {
+        Account::new(BACKEND_ID, creds.server.trim_end_matches('/'))
+            .with_login(creds.login_name.clone(), user_id)
+    }
+
+    /// The credentials a stored account plus its secret amount to.
+    ///
+    /// [`AppCredentials`] stays the connector's own type rather than becoming
+    /// something general: an app password, an OAuth token and a bucket key
+    /// pair have no useful common shape, and inventing one would produce a
+    /// wrong answer confidently. The general form is [`Connection`]; this is
+    /// the translation into what one protocol needs.
+    pub fn credentials(conn: &Connection) -> Result<AppCredentials, RemoteError> {
+        Ok(AppCredentials {
+            server: conn.account.endpoint.clone(),
+            login_name: conn.account.login.clone(),
+            app_password: conn.require_secret()?.expose().to_string(),
+        })
+    }
+}
+
+impl BackendProvider for NextcloudProvider {
+    fn id(&self) -> &'static str {
+        BACKEND_ID
+    }
+
+    fn display_name(&self) -> &'static str {
+        "Nextcloud"
+    }
+
+    fn endpoint_label(&self) -> &'static str {
+        "Server"
+    }
+
+    fn endpoint_placeholder(&self) -> &'static str {
+        "https://cloud.example.com"
+    }
+
+    fn sign_in(&self) -> SignIn {
+        SignIn::Browser
+    }
+
+    /// Normalise a server address typed by hand.
+    ///
+    /// Users type `cloud.example.com`, not a URL. Assume HTTPS rather than
+    /// failing, and never silently accept plain HTTP — NFR-SEC-3 requires TLS,
+    /// and an unencrypted default would be a security decision made on the
+    /// user's behalf without telling them.
+    fn normalise_endpoint(&self, input: &str) -> Result<String, String> {
+        let s = input.trim().trim_end_matches('/');
+        if s.is_empty() {
+            return Err("Enter the address of your Nextcloud server.".into());
+        }
+        if s.starts_with("https://") {
+            Ok(s.to_string())
+        } else if let Some(rest) = s.strip_prefix("http://") {
+            // Upgrade rather than accept. If the server genuinely has no TLS
+            // the connection fails loudly, which is the correct outcome.
+            Ok(format!("https://{rest}"))
+        } else {
+            Ok(format!("https://{s}"))
+        }
+    }
+
+    fn connect(&self, conn: &Connection) -> Result<Box<dyn RemoteBackend>, RemoteError> {
+        let creds = Self::credentials(conn)?;
+        Ok(Box::new(NextcloudBackend::new(
+            &creds,
+            &conn.account.user_id,
+        )?))
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn creds() -> AppCredentials {
+        AppCredentials {
+            server: "https://cloud.example/".into(),
+            login_name: "duncan@example.com".into(),
+            app_password: "token".into(),
+        }
+    }
+
+    #[test]
+    fn an_address_typed_by_hand_becomes_an_https_url() {
+        let p = NextcloudProvider;
+        assert_eq!(
+            p.normalise_endpoint("cloud.example.com/").unwrap(),
+            "https://cloud.example.com"
+        );
+        // Upgraded, never accepted: NFR-SEC-3.
+        assert_eq!(
+            p.normalise_endpoint("http://cloud.example.com").unwrap(),
+            "https://cloud.example.com"
+        );
+        assert!(p.normalise_endpoint("  ").is_err());
+    }
+
+    #[test]
+    fn the_account_keeps_the_dav_user_id_apart_from_the_login() {
+        // A login can be an email address while the user id is something
+        // else; building the DAV path from the wrong one 404s everything.
+        let a = NextcloudProvider::account_from(&creds(), "duncan");
+        assert_eq!(a.login, "duncan@example.com");
+        assert_eq!(a.user_id, "duncan");
+        assert_eq!(a.endpoint, "https://cloud.example");
+    }
+
+    #[test]
+    fn a_nextcloud_account_keeps_its_historical_catalog_directory() {
+        // Frozen: this names the directory holding the catalog, the thumbnail
+        // shards and un-uploaded sidecars.
+        let a = NextcloudProvider::account_from(&creds(), "duncan");
+        assert_eq!(a.namespace(), "cloud-example-duncan");
+    }
+
+    #[test]
+    fn connecting_without_a_credential_is_unauthenticated_not_a_crash() {
+        // A cleared keyring or a revoked app password arrives here as an
+        // account with no secret. The caller re-runs the login flow.
+        let account = NextcloudProvider::account_from(&creds(), "duncan");
+        match NextcloudProvider.connect(&Connection::new(account, None)) {
+            Err(RemoteError::Unauthenticated) => {}
+            Err(e) => panic!("wrong error: {e:?}"),
+            Ok(b) => panic!("connected without a credential as {}", b.name()),
+        }
+    }
+
+    #[test]
+    fn a_stored_account_and_its_secret_rebuild_the_credentials() {
+        let account = NextcloudProvider::account_from(&creds(), "duncan");
+        let conn = Connection::new(account, Some(dr_sync::Secret::new("token")));
+        let rebuilt = NextcloudProvider::credentials(&conn).unwrap();
+        assert_eq!(rebuilt.server, "https://cloud.example");
+        assert_eq!(rebuilt.login_name, "duncan@example.com");
+        assert_eq!(rebuilt.app_password, "token");
+    }
+}