50 lines
2.2 KiB
Markdown
50 lines
2.2 KiB
Markdown
# 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
|
|
|
|
```sh
|
|
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
|
|
|
|
```sh
|
|
sqlx migrate add --source src/app_state/database/migrations <name>
|
|
sqlx migrate run --source src/app_state/database/migrations --database-url sqlite://db.sqlite3
|
|
```
|