diff --git a/crates/copper-cloud/migrations/0015_sync_doc_revisions.sql b/crates/copper-cloud/migrations/0015_sync_doc_revisions.sql new file mode 100644 index 0000000..086b5ad --- /dev/null +++ b/crates/copper-cloud/migrations/0015_sync_doc_revisions.sql @@ -0,0 +1,23 @@ +-- Recoverable sync docs (copper-cloud 0.12.0). The server cannot read a doc, so its guard is +-- keeping what a write replaced: every accepted overwrite of a sync_docs row first copies the +-- old row here, sealed bytes as they were (same AAD ":"). The last 20 per +-- (user, domain) are kept; a restore writes one back as a new version. +-- +-- client_build: the optional X-Copper-Build header of the write (NULL for older clients). + +ALTER TABLE sync_docs + ADD COLUMN client_build text CHECK (client_build IS NULL OR length(client_build) <= 64); + +CREATE TABLE sync_doc_revisions ( + user_id uuid NOT NULL REFERENCES users (id) ON DELETE CASCADE, + domain text NOT NULL CHECK (length(domain) BETWEEN 1 AND 64), + version bigint NOT NULL CHECK (version > 0), + device_id uuid, + client_build text CHECK (client_build IS NULL OR length(client_build) <= 64), + -- When this version was written; replaced_at = when a newer write archived it. + updated_at timestamptz NOT NULL, + replaced_at timestamptz NOT NULL DEFAULT now(), + payload bytea NOT NULL, + payload_bytes integer NOT NULL CHECK (payload_bytes >= 0), + PRIMARY KEY (user_id, domain, version) +); diff --git a/crates/copper-cloud/src/admin.rs b/crates/copper-cloud/src/admin.rs index 504ac2b..55bc6e5 100644 --- a/crates/copper-cloud/src/admin.rs +++ b/crates/copper-cloud/src/admin.rs @@ -15,8 +15,8 @@ use uuid::Uuid; use copper_cloud_core::intelligence; use crate::cli::{ - AdminCommand, HistoryCommand, HistoryDeleteArgs, IntegrationCommand, IntelligenceCommand, - SsoCommand, + AdminCommand, DocsCommand, HistoryCommand, HistoryDeleteArgs, IntegrationCommand, + IntelligenceCommand, SsoCommand, }; use copper_cloud_core::{agents, sso}; @@ -277,23 +277,56 @@ async fn dispatch(cfg: &Config, pool: &sqlx::PgPool, cmd: AdminCommand) -> anyho println!("deleted {entries} of {email}"); } } + AdminCommand::Docs(cmd) => docs_command(pool, cmd).await?, AdminCommand::Addons(cmd) => crate::admin_addons_cli::dispatch(cfg, pool, cmd).await?, } Ok(()) } -/// `admin history delete`: resolves `--user` (email or id) and deletes or, with `--dry-run`, -/// counts their history rows matching the metadata filter (`--since` / `--until` / -/// `--device`; none = everything). Wholesale only: no payload is opened and no data key is -/// unwrapped. Returns the user's email and the count. Running servers do not learn about it -/// (no `history_deleted` event); Coppers see fewer rows on their next pull. -pub async fn history_delete( - pool: &sqlx::PgPool, - args: &HistoryDeleteArgs, -) -> anyhow::Result<(String, u64)> { - use copper_cloud_core::sync::{HistoryFilter, HistorySelection}; - let filter = HistoryFilter::new(args.since, args.until, args.device).map_err(api)?; - let row: Option<(Uuid, String)> = match Uuid::parse_str(args.user.trim()) { +/// `admin docs …`: kept revisions of a user's sync doc (see `sync_doc_revisions`). +pub async fn docs_command(pool: &sqlx::PgPool, cmd: DocsCommand) -> anyhow::Result<()> { + use copper_cloud_core::sync::{self, Domain}; + match cmd { + DocsCommand::Revisions { user, domain } => { + let (user_id, email) = resolve_user(pool, &user).await?; + let domain = Domain::parse(&domain).map_err(api)?.as_str(); + let revs = sync::list_revisions(pool, user_id, &domain) + .await + .map_err(api)?; + if revs.is_empty() { + println!("no kept revisions of {domain} for {email}"); + } + for r in revs { + println!( + "v{}\twritten {}\treplaced {}\t{} bytes\tdevice {}\tbuild {}", + r.version, + fmt_time(r.updated_at), + fmt_time(r.replaced_at), + r.bytes, + r.device_id.map_or_else(|| "-".into(), |d| d.to_string()), + r.client_build.as_deref().unwrap_or("-"), + ); + } + } + DocsCommand::Restore { + user, + domain, + version, + } => { + let (user_id, email) = resolve_user(pool, &user).await?; + let domain = Domain::parse(&domain).map_err(api)?.as_str(); + let (new, _) = sync::restore_revision(pool, user_id, &domain, version, None) + .await + .map_err(|e| anyhow::anyhow!("restoring v{version} of {domain}: {e}"))?; + println!("restored {domain} v{version} of {email} as v{new}"); + } + } + Ok(()) +} + +/// `--user`: a user id or an email (case-insensitive) → (id, email). +async fn resolve_user(pool: &sqlx::PgPool, user: &str) -> anyhow::Result<(Uuid, String)> { + let row: Option<(Uuid, String)> = match Uuid::parse_str(user.trim()) { Ok(id) => { sqlx::query_as("SELECT id, email FROM users WHERE id = $1") .bind(id) @@ -302,12 +335,26 @@ pub async fn history_delete( } Err(_) => { sqlx::query_as("SELECT id, email FROM users WHERE lower(email) = lower($1)") - .bind(args.user.trim()) + .bind(user.trim()) .fetch_optional(pool) .await? } }; - let (user_id, email) = row.with_context(|| format!("no user {}", args.user))?; + row.with_context(|| format!("no user {user}")) +} + +/// `admin history delete`: resolves `--user` (email or id) and deletes or, with `--dry-run`, +/// counts their history rows matching the metadata filter (`--since` / `--until` / +/// `--device`; none = everything). Wholesale only: no payload is opened and no data key is +/// unwrapped. Returns the user's email and the count. Running servers do not learn about it +/// (no `history_deleted` event); Coppers see fewer rows on their next pull. +pub async fn history_delete( + pool: &sqlx::PgPool, + args: &HistoryDeleteArgs, +) -> anyhow::Result<(String, u64)> { + use copper_cloud_core::sync::{HistoryFilter, HistorySelection}; + let filter = HistoryFilter::new(args.since, args.until, args.device).map_err(api)?; + let (user_id, email) = resolve_user(pool, &args.user).await?; let n = copper_cloud_core::sync::delete_history( pool, user_id, diff --git a/crates/copper-cloud/src/admin_api.rs b/crates/copper-cloud/src/admin_api.rs index cbb7b0b..f299ebe 100644 --- a/crates/copper-cloud/src/admin_api.rs +++ b/crates/copper-cloud/src/admin_api.rs @@ -1165,11 +1165,15 @@ async fn delete_device( if users.is_empty() { return Err(ApiError::NotFound); } - sqlx::query("DELETE FROM sync_docs WHERE domain = $1 AND user_id = ANY($2)") + for table in ["sync_docs", "sync_doc_revisions"] { + sqlx::query(&format!( + "DELETE FROM {table} WHERE domain = $1 AND user_id = ANY($2)" + )) .bind(copper_cloud_core::sync::tabs_domain(id)) .bind(&users) .execute(&mut *tx) .await?; + } let detail = if let [user] = users.as_slice() { json!({ "user_id": user }) } else { diff --git a/crates/copper-cloud/src/cli.rs b/crates/copper-cloud/src/cli.rs index de5a7fa..45098bf 100644 --- a/crates/copper-cloud/src/cli.rs +++ b/crates/copper-cloud/src/cli.rs @@ -341,6 +341,9 @@ pub enum AdminCommand { /// A user's synced browsing history. #[command(subcommand)] History(HistoryCommand), + /// A user's synced docs (spaces, settings, bookmarks, tabs:): kept revisions. + #[command(subcommand)] + Docs(DocsCommand), /// Company single sign-on (Google or OIDC) for Coppers. #[command(subcommand)] Sso(SsoCommand), @@ -449,6 +452,30 @@ pub enum HistoryCommand { Delete(HistoryDeleteArgs), } +#[derive(Subcommand, Debug)] +pub enum DocsCommand { + /// List the kept revisions of one doc, newest first (metadata only; never opens a doc). + Revisions { + /// The user: email or user id. + #[arg(long, value_name = "EMAIL|UUID")] + user: String, + /// spaces, settings, bookmarks or tabs:. + #[arg(long)] + domain: String, + }, + /// Write a kept revision back as the doc's new version. Running servers send no event; + /// Coppers pick it up on their next pull. + Restore { + #[arg(long, value_name = "EMAIL|UUID")] + user: String, + #[arg(long)] + domain: String, + /// The revision's version (from `admin docs revisions`). + #[arg(long)] + version: i64, + }, +} + #[derive(Args, Debug, Clone)] pub struct HistoryDeleteArgs { /// The user: email or user id. diff --git a/crates/copper-cloud/tests/api.rs b/crates/copper-cloud/tests/api.rs index e62281d..f583024 100644 --- a/crates/copper-cloud/tests/api.rs +++ b/crates/copper-cloud/tests/api.rs @@ -1023,3 +1023,218 @@ async fn handler_panic_becomes_500() { .unwrap(); assert_eq!(r.status(), 200); } + +#[tokio::test] +async fn sync_doc_revisions() { + let s = start().await; + let (dev_a, dev_b) = (new_device(), new_device()); + let a = s.signup("revs@example.com", PASSWORD, &dev_a).await; + let b = common::session_from( + &s.login("revs@example.com", PASSWORD, &dev_b) + .await + .json() + .await + .unwrap(), + ); + let put = |who: &common::Session, base: i64, doc: String, build: Option<&str>| { + let mut rb = s + .authed(Method::PUT, "/v1/sync/docs/spaces", who) + .json(&json!({"base_version": base, "payload": b64(&doc)})); + if let Some(build) = build { + rb = rb.header("X-Copper-Build", build); + } + rb.send() + }; + let doc = |i: i64| format!(r#"{{"spaces":[{{"id":"s{i}"}}]}}"#); + let list = |who: &common::Session| { + let req = s.authed(Method::GET, "/v1/sync/docs/spaces/revisions", who); + async move { + req.send() + .await + .unwrap() + .json::>() + .await + .unwrap() + } + }; + + // The first write replaces nothing. + assert_eq!( + put(&a, 0, doc(1), Some("1.0.1")).await.unwrap().status(), + 200 + ); + assert_eq!(list(&a).await, Vec::::new()); + // A stale write is refused and archives nothing. + assert_eq!(put(&b, 7, doc(9), None).await.unwrap().status(), 409); + assert_eq!(list(&a).await, Vec::::new()); + // B (an older client: no build header) overwrites: A's v1 is kept, with A's build. + assert_eq!(put(&b, 1, doc(2), None).await.unwrap().status(), 200); + let revs = list(&a).await; + assert_eq!(revs.len(), 1); + assert_eq!(revs[0]["version"], 1); + assert_eq!(revs[0]["device_id"], dev_a.as_str()); + assert_eq!(revs[0]["client_build"], "1.0.1"); + assert_eq!(revs[0]["bytes"], doc(1).len()); + assert!(revs[0].get("payload").is_none()); + // Kept sealed, never in the clear. + let stored: Vec = sqlx::query_scalar("SELECT payload FROM sync_doc_revisions") + .fetch_one(&s.state.db) + .await + .unwrap(); + assert!(!stored.windows(6).any(|w| w == b"spaces")); + // A junk build header is dropped, not stored. + assert_eq!( + put(&a, 2, doc(3), Some(&"9".repeat(65))) + .await + .unwrap() + .status(), + 200 + ); + assert!(list(&a).await[0]["client_build"].is_null()); + + // Read one back before restoring it. + let got: Value = s + .authed(Method::GET, "/v1/sync/docs/spaces/revisions/1", &b) + .send() + .await + .unwrap() + .json() + .await + .unwrap(); + assert_eq!(got["version"], 1); + assert_eq!(unb64(&got["payload"]), doc(1)); + + // Restore v1: written back as v4, the replaced v3 is kept, every device gets the event. + let uid: uuid::Uuid = a.user_id.parse().unwrap(); + let mut events = s.state.events.subscribe(uid); + let r = s + .authed(Method::POST, "/v1/sync/docs/spaces/revisions/1/restore", &b) + .send() + .await + .unwrap(); + assert_eq!(r.status(), 200); + let r: Value = r.json().await.unwrap(); + assert_eq!(r["version"], 4); + assert_eq!(r["restored_from"], 1); + match events.try_recv().unwrap() { + copper_cloud_core::events::Event::Doc { + domain, + version, + device_id, + } => { + assert_eq!((domain.as_str(), version, device_id), ("spaces", 4, None)); + } + other => panic!("{other:?}"), + } + let cur: Value = s + .authed(Method::GET, "/v1/sync/docs/spaces", &a) + .send() + .await + .unwrap() + .json() + .await + .unwrap(); + assert_eq!(cur["version"], 4); + assert_eq!(unb64(&cur["payload"]), doc(1)); + let versions = |revs: &[Value]| { + revs.iter() + .map(|r| r["version"].as_i64().unwrap()) + .collect::>() + }; + assert_eq!(versions(&list(&a).await), [3, 2, 1]); + + // Unknown revision / domain; another user sees nothing. + let status = |m: Method, path: &str, who: &common::Session| { + let req = s.authed(m, path, who); + async move { req.send().await.unwrap().status() } + }; + assert_eq!( + status( + Method::POST, + "/v1/sync/docs/spaces/revisions/99/restore", + &a + ) + .await, + 404 + ); + assert_eq!( + status(Method::GET, "/v1/sync/docs/spaces/revisions/99", &a).await, + 404 + ); + assert_eq!( + status(Method::GET, "/v1/sync/docs/passwords/revisions", &a).await, + 400 + ); + let c = s + .signup("revs-other@example.com", PASSWORD, &new_device()) + .await; + assert_eq!(list(&c).await, Vec::::new()); + assert_eq!( + status(Method::GET, "/v1/sync/docs/spaces/revisions/1", &c).await, + 404 + ); + assert_eq!( + status(Method::POST, "/v1/sync/docs/spaces/revisions/1/restore", &c).await, + 404 + ); + + // Only the newest 20 are kept. + for v in 4..30 { + assert_eq!(put(&a, v, doc(v), None).await.unwrap().status(), 200); + } + let revs = list(&a).await; + assert_eq!(versions(&revs), (10..30).rev().collect::>()); + + // tabs: restoring another device's tabs is refused; deleting the device drops its revisions. + let tabs = format!("/v1/sync/docs/tabs:{dev_b}"); + for base in 0..2 { + let r = s + .authed(Method::PUT, &tabs, &b) + .json(&json!({"base_version": base, "payload": b64("{}")})) + .send() + .await + .unwrap(); + assert_eq!(r.status(), 200); + } + assert_eq!( + status(Method::POST, &format!("{tabs}/revisions/1/restore"), &a).await, + 403 + ); + s.authed(Method::DELETE, &format!("/v1/devices/{dev_b}"), &a) + .send() + .await + .unwrap(); + let left: i64 = + sqlx::query_scalar("SELECT count(*) FROM sync_doc_revisions WHERE domain LIKE 'tabs:%'") + .fetch_one(&s.state.db) + .await + .unwrap(); + assert_eq!(left, 0); + + // `copper-cloud admin docs restore` (straight against the database). + copper_cloud::admin::docs_command( + &s.state.db, + copper_cloud::cli::DocsCommand::Restore { + user: "REVS@example.com".into(), + domain: "spaces".into(), + version: 10, + }, + ) + .await + .unwrap(); + let cur: Value = s + .authed(Method::GET, "/v1/sync/docs/spaces", &a) + .send() + .await + .unwrap() + .json() + .await + .unwrap(); + assert_eq!(cur["version"], 31); + assert_eq!( + unb64(&cur["payload"]), + doc(9), + "v10 was written with doc(9)" + ); + assert!(cur["device_id"].is_null()); +} diff --git a/crates/core/src/app.rs b/crates/core/src/app.rs index 45a61df..f1d298f 100644 --- a/crates/core/src/app.rs +++ b/crates/core/src/app.rs @@ -46,6 +46,9 @@ pub const FEATURES: &[&str] = &[ "addons", // Canvases are served by a linked Canvas Cloud (0.11.0; see `canvas` in `/v1/info`). "canvas_link", + // `GET /v1/sync/docs/{domain}/revisions` (+ `/{version}`, `/{version}/restore`) and the + // optional `X-Copper-Build` header on doc writes (0.12.0). + "doc_revisions", ]; /// Core `/v1` routes (auth, pairing, devices, sync, intelligence, info). Paths are relative to `/v1`. diff --git a/crates/core/src/auth.rs b/crates/core/src/auth.rs index 13cba55..57f2b90 100644 --- a/crates/core/src/auth.rs +++ b/crates/core/src/auth.rs @@ -752,7 +752,8 @@ async fn rename_device( Ok(Json(device)) } -/// Remove a device: revokes its sessions (FK cascade) and deletes its `tabs:` doc. +/// Remove a device: revokes its sessions (FK cascade) and deletes its `tabs:` doc +/// and that doc's revisions. async fn delete_device( State(state): State, user: AuthUser, @@ -769,11 +770,15 @@ async fn delete_device( return Err(ApiError::NotFound); } let domain = crate::sync::tabs_domain(id); - sqlx::query("DELETE FROM sync_docs WHERE user_id = $1 AND domain = $2") + for table in ["sync_docs", "sync_doc_revisions"] { + sqlx::query(&format!( + "DELETE FROM {table} WHERE user_id = $1 AND domain = $2" + )) .bind(user.user_id) .bind(&domain) .execute(&mut *tx) .await?; + } tx.commit().await?; Ok(Json(json!({ "ok": true }))) } diff --git a/crates/core/src/sync.rs b/crates/core/src/sync.rs index 92bea87..516621e 100644 --- a/crates/core/src/sync.rs +++ b/crates/core/src/sync.rs @@ -21,7 +21,7 @@ use axum::extract::{Path, Query, Request, State}; use axum::http::{header, HeaderValue}; use axum::response::sse::{Event as SseEvent, KeepAlive, Sse}; use axum::response::{IntoResponse, Response}; -use axum::routing::get; +use axum::routing::{get, post}; use axum::{Json, Router}; use futures::Stream; use governor::{DefaultKeyedRateLimiter, Quota, RateLimiter}; @@ -44,6 +44,10 @@ pub const SHARED_DOMAINS: &[&str] = &["spaces", "settings", "bookmarks"]; /// Prefix of per-device open-tab domains: `tabs:`. pub const TABS_PREFIX: &str = "tabs:"; const HISTORY_AAD_DOMAIN: &str = "history"; +/// Replaced versions kept per (user, domain) in `sync_doc_revisions`. +pub const DOC_REVISIONS_KEPT: i64 = 20; +/// Optional request header naming the client build that wrote a doc (stored, never trusted). +pub const BUILD_HEADER: &str = "x-copper-build"; const DEFAULT_HISTORY_LIMIT: usize = 500; /// SSE keepalive comment interval. pub const SSE_KEEPALIVE: Duration = Duration::from_secs(15); @@ -54,6 +58,12 @@ pub(crate) fn routes() -> Router { Router::new() .route("/sync/docs", get(list_docs)) .route("/sync/docs/{domain}", get(get_doc).put(put_doc)) + .route("/sync/docs/{domain}/revisions", get(list_revisions_route)) + .route("/sync/docs/{domain}/revisions/{version}", get(get_revision)) + .route( + "/sync/docs/{domain}/revisions/{version}/restore", + post(restore_revision_route), + ) .route( "/sync/history", get(pull_history) @@ -224,6 +234,7 @@ async fn put_doc( } } let domain = parsed.as_str(); + let build = client_build(req.headers()); let max_blob = state.cfg.limits.max_blob_bytes; let limit = doc_body_limit(max_blob); check_content_length(&req, limit)?; @@ -250,8 +261,9 @@ async fn put_doc( let written: Option<(i64, OffsetDateTime)> = if base_version == 0 { sqlx::query_as( - "INSERT INTO sync_docs (user_id, domain, device_id, version, payload, payload_bytes) - VALUES ($1, $2, $3, 1, $4, $5) + "INSERT INTO sync_docs + (user_id, domain, device_id, version, payload, payload_bytes, client_build) + VALUES ($1, $2, $3, 1, $4, $5, $6) ON CONFLICT (user_id, domain) DO NOTHING RETURNING version, updated_at", ) @@ -260,24 +272,17 @@ async fn put_doc( .bind(device_id) .bind(&sealed) .bind(plain_len) + .bind(build.as_deref()) .fetch_optional(&state.db) .await? } else { - sqlx::query_as( - "UPDATE sync_docs - SET version = version + 1, payload = $4, payload_bytes = $5, device_id = $3, - updated_at = now() - WHERE user_id = $1 AND domain = $2 AND version = $6 - RETURNING version, updated_at", - ) - .bind(user_id) - .bind(domain.as_ref()) - .bind(device_id) - .bind(&sealed) - .bind(plain_len) - .bind(base_version) - .fetch_optional(&state.db) - .await? + let write = DocWrite { + device_id: Some(device_id), + client_build: build.as_deref(), + payload: &sealed, + payload_bytes: plain_len, + }; + replace_doc(&state.db, user_id, &domain, Some(base_version), &write).await? }; let Some((version, updated_at)) = written else { @@ -308,6 +313,241 @@ async fn put_doc( })) } +/// `X-Copper-Build` as sent (trimmed, printable ASCII, at most 64 chars), else `None`. +fn client_build(headers: &header::HeaderMap) -> Option { + let raw = headers.get(BUILD_HEADER)?.to_str().ok()?.trim(); + (!raw.is_empty() && raw.len() <= 64 && raw.bytes().all(|b| b.is_ascii_graphic() || b == b' ')) + .then(|| raw.to_owned()) +} + +// --------------------------------------------------------------------------------------------- +// Doc revisions +// +// The server cannot read a doc, so it cannot tell a good write from a bad one; it keeps what +// each write replaced instead. Every accepted overwrite copies the old row (sealed bytes as +// they were, same AAD) into `sync_doc_revisions`, keeping the newest [`DOC_REVISIONS_KEPT`] +// per (user, domain). A restore writes one back as a new version, so devices pull it like any +// other write. + +/// The new contents of a doc write. +pub struct DocWrite<'a> { + pub device_id: Option, + pub client_build: Option<&'a str>, + /// Sealed with the user's data key, AAD `":"`. + pub payload: &'a [u8], + pub payload_bytes: i32, +} + +/// Overwrite an existing doc (only if it is at `expected` when given), archiving the replaced +/// row and pruning old revisions, in one transaction. `None` = no such doc / stale `expected`. +async fn replace_doc( + db: &sqlx::PgPool, + user_id: Uuid, + domain: &str, + expected: Option, + write: &DocWrite<'_>, +) -> ApiResult> { + let mut tx = db.begin().await?; + // Locks the row, so the archived version is exactly the one this write replaces. + let archived = sqlx::query( + "INSERT INTO sync_doc_revisions + (user_id, domain, version, device_id, client_build, updated_at, payload, + payload_bytes) + SELECT user_id, domain, version, device_id, client_build, updated_at, payload, + payload_bytes + FROM (SELECT * FROM sync_docs + WHERE user_id = $1 AND domain = $2 AND ($3::bigint IS NULL OR version = $3) + FOR UPDATE) cur + ON CONFLICT (user_id, domain, version) DO NOTHING", + ) + .bind(user_id) + .bind(domain) + .bind(expected) + .execute(&mut *tx) + .await?; + let written: Option<(i64, OffsetDateTime)> = sqlx::query_as( + "UPDATE sync_docs + SET version = version + 1, payload = $4, payload_bytes = $5, device_id = $3, + client_build = $6, updated_at = now() + WHERE user_id = $1 AND domain = $2 AND ($7::bigint IS NULL OR version = $7) + RETURNING version, updated_at", + ) + .bind(user_id) + .bind(domain) + .bind(write.device_id) + .bind(write.payload) + .bind(write.payload_bytes) + .bind(write.client_build) + .bind(expected) + .fetch_optional(&mut *tx) + .await?; + if written.is_none() { + tx.rollback().await?; + return Ok(None); + } + if archived.rows_affected() > 0 { + sqlx::query( + "DELETE FROM sync_doc_revisions + WHERE user_id = $1 AND domain = $2 AND version < ( + SELECT min(version) FROM ( + SELECT version FROM sync_doc_revisions + WHERE user_id = $1 AND domain = $2 + ORDER BY version DESC LIMIT $3) kept)", + ) + .bind(user_id) + .bind(domain) + .bind(DOC_REVISIONS_KEPT) + .execute(&mut *tx) + .await?; + } + tx.commit().await?; + Ok(written) +} + +/// One kept revision (metadata only). +#[derive(Debug, Serialize, sqlx::FromRow)] +pub struct RevisionMeta { + pub version: i64, + pub device_id: Option, + pub client_build: Option, + /// When this version was written. + #[serde(with = "time::serde::rfc3339")] + pub updated_at: OffsetDateTime, + /// When a newer write replaced it. + #[serde(with = "time::serde::rfc3339")] + pub replaced_at: OffsetDateTime, + #[sqlx(rename = "payload_bytes")] + pub bytes: i32, +} + +/// `user_id`'s kept revisions of `domain`, newest first. Never opens a payload. +pub async fn list_revisions( + db: &sqlx::PgPool, + user_id: Uuid, + domain: &str, +) -> ApiResult> { + Ok(sqlx::query_as( + "SELECT version, device_id, client_build, updated_at, replaced_at, payload_bytes + FROM sync_doc_revisions WHERE user_id = $1 AND domain = $2 + ORDER BY version DESC", + ) + .bind(user_id) + .bind(domain) + .fetch_all(db) + .await?) +} + +/// Write revision `version` of `user_id`'s `domain` back as a new version (the current one is +/// archived like any overwrite). The sealed bytes are copied as they are: same user, same AAD, +/// no data key needed. Returns the new version and its time; `404` if the revision or the doc +/// is gone. The caller publishes the `doc` event. +pub async fn restore_revision( + db: &sqlx::PgPool, + user_id: Uuid, + domain: &str, + version: i64, + device_id: Option, +) -> ApiResult<(i64, OffsetDateTime)> { + let (payload, payload_bytes, client_build): (Vec, i32, Option) = sqlx::query_as( + "SELECT payload, payload_bytes, client_build FROM sync_doc_revisions + WHERE user_id = $1 AND domain = $2 AND version = $3", + ) + .bind(user_id) + .bind(domain) + .bind(version) + .fetch_optional(db) + .await? + .ok_or(ApiError::NotFound)?; + let write = DocWrite { + device_id, + client_build: client_build.as_deref(), + payload: &payload, + payload_bytes, + }; + replace_doc(db, user_id, domain, None, &write) + .await? + .ok_or(ApiError::NotFound) +} + +/// `GET /sync/docs/{domain}/revisions` → kept revisions, newest first (metadata only). +async fn list_revisions_route( + State(state): State, + user: AuthUser, + Path(domain): Path, +) -> ApiResult>> { + let domain = Domain::parse(&domain)?.as_str(); + Ok(Json( + list_revisions(&state.db, user.user_id, &domain).await?, + )) +} + +/// `GET /sync/docs/{domain}/revisions/{version}` → the revision in the `GET /sync/docs/{domain}` +/// shape, so a client can look before it restores. +async fn get_revision( + State(state): State, + user: KeyedUser, + Path((domain, version)): Path<(String, i64)>, +) -> ApiResult> { + let domain = Domain::parse(&domain)?.as_str(); + let row = sqlx::query_as::<_, DocRow>( + "SELECT version, updated_at, device_id, payload FROM sync_doc_revisions + WHERE user_id = $1 AND domain = $2 AND version = $3", + ) + .bind(user.user.user_id) + .bind(domain.as_ref()) + .bind(version) + .fetch_optional(&state.db) + .await? + .ok_or(ApiError::NotFound)?; + Ok(Json(decrypt_doc( + &user.data_key, + user.user.user_id, + &domain, + &row, + )?)) +} + +/// `POST /sync/docs/{domain}/revisions/{version}/restore` → `{version, updated_at, +/// restored_from}` and a `doc` event with no `device_id`, so every device (the caller's too) +/// pulls it. +async fn restore_revision_route( + State(state): State, + user: AuthUser, + Path((domain, version)): Path<(String, i64)>, +) -> ApiResult> { + let parsed = Domain::parse(&domain)?; + if let Domain::Tabs(owner) = parsed { + if owner != user.device_id { + return Err(ApiError::Forbidden); + } + } + let domain = parsed.as_str(); + let (new_version, updated_at) = restore_revision( + &state.db, + user.user_id, + &domain, + version, + Some(user.device_id), + ) + .await?; + tracing::info!(domain = %domain, from = version, to = new_version, "sync doc restored"); + state.events.publish( + user.user_id, + Event::Doc { + domain: domain.into_owned(), + version: new_version, + device_id: None, + }, + ); + Ok(Json(json!({ + "version": new_version, + "updated_at": updated_at + .format(&time::format_description::well_known::Rfc3339) + .map_err(anyhow::Error::from)?, + "restored_from": version, + }))) +} + // --------------------------------------------------------------------------------------------- // History diff --git a/docs/api.md b/docs/api.md index b9220b2..7bda9b1 100644 --- a/docs/api.md +++ b/docs/api.md @@ -497,6 +497,37 @@ Metadata only: Payload base64 may be standard or url-safe, padded or not. +Optional request header `X-Copper-Build: ` (printable ASCII, ≤ 64 chars; anything +else is ignored) is stored with the write and shown in its revision (below). Older clients just +leave it out. + +### Doc revisions (`features`: `doc_revisions`) + +The server cannot read a doc, so it keeps what each write replaced: every accepted overwrite +saves the old version (still encrypted) and the newest 20 per domain are kept. Use them to +recover from a bad write by any device. + +- `GET /v1/sync/docs/{domain}/revisions` → newest first, metadata only: + +```json +[ { "version": 6, "device_id": "uuid", "client_build": "1.0.20261028.3", "updated_at": "…", + "replaced_at": "…", "bytes": 5120 } ] +``` + + `updated_at` = when that version was written, `replaced_at` = when a newer write replaced + it, `client_build` = its `X-Copper-Build` (or `null`). +- `GET /v1/sync/docs/{domain}/revisions/{version}` → the revision in the + `GET /v1/sync/docs/{domain}` shape (with `payload`); `404` if not kept. +- `POST /v1/sync/docs/{domain}/revisions/{version}/restore` → writes it back as a new version + (the current one becomes a revision too): `200 {"version": 9, "updated_at": "…", + "restored_from": 6}` and an SSE `doc` event with `device_id: null`, so every device, the + caller's included, pulls it. `404` unknown revision; `403` another device's `tabs:` domain. + +Removing a device deletes its `tabs:` doc and that doc's revisions. Operators: +`copper-cloud admin docs revisions --user EMAIL --domain spaces` and +`copper-cloud admin docs restore --user EMAIL --domain spaces --version N` (no event; Coppers +pick it up on their next pull). + --- ## History 🔒