verstak
/
verstak-sync-server
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Document scoped ordered sync contract

This commit is contained in:
mirivlad 2026-07-17 04:11:04 +08:00
parent e68d057ec7
commit 487ede8e4f
1 changed files with 17 additions and 5 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

22
README.md
View File

@ -7,8 +7,8 @@ Standalone sync server for Verstak2 platform.
This server provides synchronization between devices running Verstak2. It handles: This server provides synchronization between devices running Verstak2. It handles:
- Device registration and authentication - Device registration and authentication
- Vault-scoped operation log sync with server sequence numbers and conflict detection - Vault-scoped, ordered operation-log relay with server sequence numbers
- Blob storage for attachments - Optional blob endpoints, not used by the current bounded Desktop file sync
- User management with email confirmation - User management with email confirmation
## Quick Start ## Quick Start
@ -108,8 +108,9 @@ sudo install -m 755 ./build/bin/verstak-sync-server /opt/verstak-sync-server/ver
sudo systemctl start verstak-server sudo systemctl start verstak-server
``` ```
Keep `--data` stable across upgrades. The data directory is the server's source Keep `--data` stable across upgrades. The data directory is the durable relay
of truth. log for connected devices; each Desktop vault remains the source of truth for
its local-first files and workspace state.
## Backup And Restore ## Backup And Restore
@ -192,7 +193,18 @@ Sync operations are generic records with `entity_type`, `entity_id`, `op_type`,
to one user and vault. The server derives the stored device ID and operation to one user and vault. The server derives the stored device ID and operation
scope from that token, ignores a caller-supplied `device_id` for authorization, scope from that token, ignores a caller-supplied `device_id` for authorization,
and returns only operations and cursors from the authenticated user/vault. and returns only operations and cursors from the authenticated user/vault.
Verstak desktop owns the v2 payload semantics. Operations are returned in increasing `server_sequence`; clients must stop at
the first operation they cannot apply and retry that sequence later. The server
does not merge files, resolve conflicts, or create replacement names.
The desktop pairing payload may supply an existing `vault_id` to add a new
empty local vault to that remote scope. The server treats that value only as a
scope selector: reconciliation, conflict detection, snapshots, and durable
workspace identity remain Desktop-core responsibilities. Current Desktop core
uses bounded inline file payloads (text or base64 up to 8 MB) and workspace
operations (`create`, `rename`, `trash`, `restore`). Blob transport, quotas,
pull pagination, and operation retention are a later milestone; the existing
blob endpoints must not be interpreted as enabled Desktop large-file sync.
New device enrollment requires a non-empty `vault_id`. The `legacy:` prefix is New device enrollment requires a non-empty `vault_id`. The `legacy:` prefix is
reserved for server-side migration of older records and cannot be selected by reserved for server-side migration of older records and cannot be selected by