vault-link/sync-server/README.md

Sync server

Document pushes (API v3)

The server stores immutable document versions. One compare-and-swap endpoint, PUT /vaults/:vault_id/documents/:document_id, handles every mutation. The client generates the document UUID; the JSON body contains:

• requestId: a UUID identifying this exact push.
• parentVersionId: null to create an absent document, otherwise its base version.
• relativePath: the desired filename.
• content: { "type": "Snapshot", "value": "<base64>" }, { "type": "Diff", "value": [3, "inserted text", -2] }, or { "type": "Delete" }.

All pushes return one of:

• Accepted: version metadata for the exact snapshot committed. A retry with the same request ID returns the original acknowledgement, even after a restart or subsequent updates. Clients must persist the ID with the unchanged request. A payload fingerprint rejects reusing that ID for a different mutation.
• StaleBase: the current version, including contentBase64. Nothing was written; the client merges locally and submits a new push with a new request ID.

The base check, path allocation, new version, and durable acknowledgement share one SQLite write transaction. A deleted document stays deleted; recreating a file uses a new document ID. Occupied paths receive an available numbered filename. Text updates accept reconcile-text transport diffs against the base version; the server only reconstructs snapshots and never merges concurrent edits.

Snapshot requests use base64, adding roughly one third to the raw file size. Server and reverse-proxy request limits apply to the encoded JSON body.

API v3 uses a fresh schema. Update clients together with the server and initialise new vault databases; compatibility with previous releases is not supported.

Creating/resetting the Database for development

rm -rf db.sqlite*
sqlx database create --database-url sqlite://db.sqlite3
sqlx migrate run --source src/app_state/database/migrations --database-url sqlite://db.sqlite3
cargo sqlx prepare --workspace

Updating the DB schema through a migration

sqlx migrate add --source src/app_state/database/migrations <name>
sqlx migrate run --source src/app_state/database/migrations --database-url sqlite://db.sqlite3