clone/logseq
1
0
Fork 0
mirror of https://github.com/logseq/logseq.git synced 2026-04-24 22:25:01 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs(worker-sync): add guide and protocol

Browse Source
This commit is contained in:
rcmerci
2026-01-10 16:41:13 +08:00
parent c06a63b03a
commit 5219d928d1
3 changed files with 58 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files

3
AGENTS.md
View File

@@ -32,4 +32,5 @@
## Agent-Specific Notes
- Review notes live in `@prompts/review.md`; check them when preparing changes.
- Worker-sync feature guide for AI agents: `docs/agent-guide/worker-sync.md`.
- Worker-sync feature guide for AI agents: `docs/agent-guide/worker-sync/worker-sync-guide.md`.
- Worker-sync protocol reference: `docs/agent-guide/worker-sync/protocol.md`.

37
docs/agent-guide/worker-sync/protocol.md Normal file
View File

@@ -0,0 +1,37 @@
# Worker-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":"pull","since":<t>}`
- Request txs after `since` (defaults to 0).
- `{"type":"tx/batch","t_before":<t>,"txs":["<tx-transit>", ...]}`
- Upload a batch of txs based on `t_before`.
- `{"type":"ping"}`
- Optional keepalive; server replies `pong`.
## Server -> Client
- `{"type":"hello","t":<t>}`
- Server hello with current t.
- `{"type":"pull/ok","t":<t>,"txs":[{"t":<t>,"tx":"<tx-transit>"}...]}`
- Pull response with txs.
- `{"type":"tx/batch/ok","t":<t>}`
- Batch accepted; server advanced to t.
- `{"type":"changed","t":<t>}`
- Broadcast that server state advanced; client should pull.
- `{"type":"tx/reject","reason":"stale","t":<t>}`
- Client tx is based on stale t.
- `{"type":"tx/reject","reason":"cycle","data":"<transit {:attr <kw> :server_values ...}>"}`
- Cycle detected with server values.
- `{"type":"tx/reject","reason":"empty tx data"|"invalid tx"}`
- Invalid batch.
- `{"type":"pong"}`
- Keepalive response.
- `{"type":"error","message":"..."}`
- Invalid/unknown message.

19
docs/agent-guide/worker-sync.md → docs/agent-guide/worker-sync/worker-sync-guide.md
View File

@@ -22,6 +22,25 @@ This guide helps AI agents implement and review worker-sync features consistentl
- Use existing `:worker-sync/*` keywords; add new keywords via `logseq.common.defkeywords/defkeyword`.
- When adding persisted fields, ensure any migration or index logic is updated on both client and worker.
## Client-Server Message Protocol (WebSocket)
- 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.
- Client -> Server:
- `{"type":"hello","client":"<repo-id>"}`: initial hello; server responds with `t`.
- `{"type":"pull","since":<t>}`: request txs after `since` (defaults to 0).
- `{"type":"tx/batch","t_before":<t>,"txs":["<tx-transit>", ...]}`: upload batch.
- `{"type":"ping"}`: optional keepalive; server replies `pong`.
- Server -> Client:
- `{"type":"hello","t":<t>}`: server hello with current t.
- `{"type":"pull/ok","t":<t>,"txs":[{"t":<t>,"tx":"<tx-transit>"}...]}`: pull response.
- `{"type":"tx/batch/ok","t":<t>}`: batch accepted.
- `{"type":"changed","t":<t>}`: broadcast that server state advanced; client should `pull`.
- `{"type":"tx/reject","reason":"stale","t":<t>}`: client tx based on stale t.
- `{"type":"tx/reject","reason":"cycle","data":"<transit {:attr <kw> :server_values ...}>"}`: cycle detected with server values.
- `{"type":"tx/reject","reason":"empty tx data"|"invalid tx"}`: invalid batch.
- `{"type":"pong"}`: keepalive response.
- `{"type":"error","message":"..."}`: invalid/unknown message.
## Testing & Verification
- Local dev(client+server): `bb dev:worker-sync-start` runs the worker-sync watcher, `wrangler dev`, and `yarn watch` with `ENABLE_WORKER_SYNC_LOCAL=true`
- Unit tests: `bb dev:lint-and-test`