Replace folder sync with an HTTP sync server, keeping the app offline-first

Folder sync left too much to the user's sync tool: platform file access
(the Android SAF plugin), choosing the document, merging conflict copies —
and its merge base could fall out of step with the document (absorbing
conflict copies, "forget", picking a new Android folder), reading every
difference as a deletion.

The new mtgc-server crate stores one versioned library per user and accepts
a write only when it names the version it replaces. It never merges: devices
still do that with merge3, through a new sync cycle over a `Remote` trait in
mtgc-core. The base advances only on knowledge — to what was read, or to a
write the server confirmed — and is stored with the server and account it
belongs to, so a different account starts from an empty ancestor instead of
deleting. The working copy is only rewritten under the app-state lock, and
sync commands now run off the main thread.

Sign-in happens in the browser on the server's pages, via the owner's OIDC
provider and/or local username/password accounts (Argon2id, managed with
`mtgc-server user ...`), and returns a per-device revocable token to the app
by PKCE-protected code: a loopback port on desktop, the mtgc:// scheme on
Android.

The Info tab gains sign-in, the first-sync combine/replace choice, the
account's devices, and JSON export/import; the top bar shows sync state.
Includes a Dockerfile, Compose/Caddy example, and scripts to build and push
${DOCKER_REGISTRY}/mtgc/sync-server.
This commit is contained in:
2026-10-08 22:32:08 -05:00
parent df2cbb372a
commit de55fc634a
41 changed files with 6365 additions and 1662 deletions

View File

@@ -1,11 +1,12 @@
//! The library as a portable JSON document, and the merge that reconciles two
//! copies of it.
//!
//! The document is what the user actually keeps: it lives in whatever folder
//! they sync, and it is the only file they ever see. The SQLite database is an
//! internal working copy that can always be rebuilt by merging a document into
//! an empty one — which is why "first run", "cache was cleared", and "the
//! document changed elsewhere" are all the same code path.
//! The document is the library's shape for exchange: what a sync server stores
//! (see [`remote`]), what a backup export writes, and what an import reads. On
//! each device the library lives in an internal SQLite working copy, which can
//! always be rebuilt by merging a document into an empty one — so "first
//! sync", "imported a backup", and "changed on another device" are all the same
//! code path.
//!
//! # Why a three-way merge
//!
@@ -18,13 +19,14 @@
//!
//! # The one subtle rule
//!
//! The stored ancestor must be **the remote document as last read**, never the
//! result we last published. If a publish is lost — the sync tool dropped it,
//! the process died, the drive was unplugged — the remote is still what we last
//! The stored ancestor must be **the remote document as last known**, never
//! the result we last *tried* to publish. If a publish is lost — the
//! connection dropped, the process died — the remote is still what we last
//! read, so the next merge sees our edits as ours and republishes them.
//! Recording the merged result instead would make us believe those edits were
//! already shared, and the next merge would read their absence from the remote
//! as a deletion and destroy them.
//! Recording the attempted result instead would make us believe those edits
//! were already shared, and the next merge would read their absence from the
//! remote as a deletion and destroy them. (A publish the server *confirmed* is
//! known, so the ancestor may advance to it — see [`remote::sync_cycle`].)
//!
//! # Conflicts
//!
@@ -43,6 +45,9 @@ use serde::{Deserialize, Serialize};
use crate::error::Result;
pub mod account;
pub mod remote;
/// Bumped only for a breaking change to the document shape. Readers reject
/// anything newer rather than silently misreading it.
pub const DOC_VERSION: u32 = 1;
@@ -480,6 +485,23 @@ pub fn apply_doc(conn: &Connection, doc: &LibraryDoc) -> Result<()> {
Ok(())
}
/// Merge `theirs` into the working copy against `base`, and return the result.
///
/// The working copy is only rewritten when the merge changed it, so the common
/// nothing-happened sync costs one read.
pub fn merge_into(
conn: &Connection,
base: &LibraryDoc,
theirs: &LibraryDoc,
) -> Result<(LibraryDoc, MergeReport)> {
let ours = read_doc(conn)?;
let (merged, report) = merge3(base, &ours, theirs);
if merged != ours {
apply_doc(conn, &merged)?;
}
Ok((merged, report))
}
/// Render keys as a JSON array, for `json_each` to expand inside a query —
/// SQLite has no array parameter, and this avoids building SQL by
/// concatenation.