Inicio Explorar Axuda
Iniciar sesión
Apq
/
logseq
réplica de https://github.com/logseq/logseq.git
1
0
Fork 0
Ficheiros Incidencias 0 Wiki
Árbore: 1cb3158208
Ramas Etiquetas
logseq
/
docs
/
agent-guide
/
db-sync
/
protocol.md

protocol.md 7.4 KB
Histórico Raw

DB-Sync Client-Server Protocol

Transport

  • WebSocket ws(s) to /sync/:graph-id.
  • Client builds URL from config and appends ?token=... when available.
  • Encoding: JSON objects; tx payloads are Transit strings.
  • Note: keep this document in sync with the current implementation.

Client -> Server

  • {"type":"hello","client":"<repo-id>"}
    • Initial handshake from client.
  • {"type":"presence","editing-block-uuid":"<uuid|null>"}
    • Update current editing block for presence (omit or null to clear).
  • {"type":"pull","since":<t>}
    • Request txs after since (defaults to 0).
  • {"type":"tx/batch","t-before":<t>,"txs":[{"tx":"<tx-transit>","tx-id":"<uuid?>","outliner-op":"<keyword?>"}, ...]}
    • Upload a batch of txs based on t-before (required).
    • tx-id is optional but recommended for per-entry ack/reject mapping.
  • {"type":"ping"}
    • Optional keepalive; server replies pong.

Server -> Client

  • {"type":"hello","t":<t>,"checksum":"<hex>"}
    • Server hello with current t and entity checksum.
  • {"type":"online-users","online-users":[{"user-id":"...","email":"...","username":"...","name":"..."}...]}
    • Presence update
    • Optional editing-block-uuid indicates the block the user is editing.
  • {"type":"pull/ok","t":<t>,"checksum":"<hex>","txs":[{"t":<t>,"tx":"<tx-transit>","outliner-op":"<keyword?>"}...]}
    • Pull response with txs and post-apply entity checksum.
  • {"type":"tx/batch/ok","t":<t>,"checksum":"<hex>"}
    • Batch accepted; server advanced to t and returns the resulting entity checksum.
  • {"type":"changed","t":<t>}
    • Broadcast once after a handled tx/batch that advanced server state (t increased); client should pull.
  • {"type":"tx/reject","reason":"stale","t":<t>}
    • Client tx is based on stale t.
  • {"type":"tx/reject","reason":"db transact failed","t":<t>,"success-tx-ids":["<uuid>",...],"failed-tx-id":"<uuid>"}
    • Server-side transact/validation failed for one tx entry in the batch.
    • success-tx-ids are entries already applied before the failure.
    • failed-tx-id is the entry that failed.
    • Legacy servers may return data with rejected tx payload for debugging.
  • {"type":"tx/reject","reason":"empty tx data"|"invalid tx"|"invalid t-before"|"snapshot upload in progress"}
    • Invalid batch.
  • {"type":"pong"}
    • Keepalive response.
  • {"type":"error","message":"..."}
    • Invalid/unknown message. Current messages: "unknown type", "invalid request", "server error", "invalid since".

HTTP API

  • Auth: Bearer token via Authorization: Bearer <token> or ?token=....
  • JSON body/response unless noted.
  • Auth required for /graphs, /sync/:graph-id/*, and /assets/*. Expect 401 (unauthorized) or 403 (forbidden) on access failure.

Worker Health

  • GET /health
    • Worker health check. Response: {"ok":true}.

Graphs (index DO)

  • GET /graphs
    • List graphs the user owns. Response: {"graphs":[{graph-id, graph-name, schema-version?, graph-ready-for-use?, created-at, updated-at}...]}.
  • POST /graphs
    • Create graph. Body: {"graph-name":"...","schema-version":"<major>"} (schema-version optional). Response: {"graph-id":"...","graph-ready-for-use?":false}.
    • graph-ready-for-use? is persisted in the D1 graphs row. Existing graphs default to true; bootstrap uploads flip it to false until the final snapshot upload request completes.
  • GET /graphs/:graph-id/access
    • Access check. Response: {"ok":true}, 401 (unauthorized), 403 (forbidden), or 404 (not found).
  • GET /graphs/:graph-id/members
    • Graph members list. Response: {"members":[{user-id, graph-id, role, invited-by, created-at, email?, username?}...]}.
  • DELETE /graphs/:graph-id
    • Delete graph and reset data. Response: {"graph-id":"...","deleted":true} or 400 (missing graph id).

E2EE (index DO)

  • GET /e2ee/user-keys
    • Fetch current user's RSA key pair. Response: {"public-key":"<transit>","encrypted-private-key":"<transit>"} or {} when missing.
  • POST /e2ee/user-keys
    • Upsert current user's RSA key pair. Body: {"public-key":"<transit>","encrypted-private-key":"<transit>","reset-private-key":false?}.
    • Response mirrors the stored keys: {"public-key":"<transit>","encrypted-private-key":"<transit>"}.
  • GET /e2ee/user-public-key?email=<email>
    • Fetch a user's RSA public key by email. Response: {"public-key":"<transit>"} or {} when missing.
  • GET /e2ee/graphs/:graph-id/aes-key
    • Fetch current user's encrypted graph AES key. Response: {"encrypted-aes-key":"<transit>"} or {} when missing.
  • POST /e2ee/graphs/:graph-id/aes-key
    • Upsert current user's encrypted graph AES key. Body: {"encrypted-aes-key":"<transit>"}.
    • Response: {"encrypted-aes-key":"<transit>"}.
  • POST /e2ee/graphs/:graph-id/grant-access
    • Manager-only. Upsert encrypted graph AES keys for members.
    • Body: {"target-user-email+encrypted-aes-key-coll":[{"user/email":"<email>","encrypted-aes-key":"<transit>"}...]}.
    • Response: {"ok":true,"missing-users":["<email>", ...]?}.

Sync (per-graph DO, via /sync/:graph-id/...)

  • GET /sync/:graph-id/health
    • Health check. Response: {"ok":true}.
  • GET /sync/:graph-id/pull?since=<t>
    • Same as WS pull. Response: {"type":"pull/ok","t":<t>,"checksum":"<hex>","txs":[{"t":<t>,"tx":"<tx-transit>","outliner-op":"<keyword?>"}...]}.
    • Error response (400): {"error":"invalid since"}.
    • Error response (409): {"error":"graph not ready"} when bootstrap upload/import has not finished.
  • POST /sync/:graph-id/tx/batch
    • Same as WS tx/batch. Body: {"t-before":<t>,"txs":[{"tx":"<tx-transit>","tx-id":"<uuid?>","outliner-op":"<keyword?>"}, ...]}.
    • Response: {"type":"tx/batch/ok","t":<t>,"checksum":"<hex>"} or {"type":"tx/reject","reason":...}.
    • Error response (400): {"error":"missing body"|"invalid tx"}.
    • Error response (409): {"error":"graph not ready"} when bootstrap upload/import has not finished.
  • GET /sync/:graph-id/snapshot/download
    • Build a snapshot file in R2 and return a download URL.
    • Response: {"ok":true,"key":"<graph-id>/<uuid>.snapshot","url":"<origin>/assets/:graph-id/<uuid>.snapshot","content-encoding":"gzip"}.
    • Error response (409): {"error":"graph not ready"} when bootstrap upload/import has not finished.
    • The snapshot file stored in R2 is a framed Transit stream of sqlite kvs rows ([addr, content, addresses]), optionally gzip-compressed.
  • POST /sync/:graph-id/snapshot/upload?reset=true|false
    • Upload a snapshot stream for bootstrap import. Current upload format remains framed Transit JSON kvs rows, optionally gzip-compressed.
    • Request body: binary stream; headers should include content-type: application/transit+json and content-encoding: gzip when compressed.
    • Response: {"ok":true,"count":<n>,"key":"<graph-id>/<uuid>.snapshot"}.
    • Error response (400): {"error":"missing body"|"missing graph id"}.
  • DELETE /sync/:graph-id/admin/reset
    • Drop/recreate per-graph tables. Response: {"ok":true}.

Assets

  • GET /assets/:graph-id/:asset-uuid.:ext
    • Download asset (binary response, content-type set, x-asset-type header included).
  • PUT /assets/:graph-id/:asset-uuid.:ext
    • Upload asset (binary body). Size limit ~100MB. Response: {"ok":true}.
  • DELETE /assets/:graph-id/:asset-uuid.:ext
    • Delete asset. Response: {"ok":true}.
  • Asset error responses: {"error":"invalid asset path"} (400), {"error":"not found"} (404), {"error":"asset too large"} (413), {"error":"method not allowed"} (405), {"error":"missing assets bucket"} (500).