John O'Keefe
e40be80e78
The Feb-era 700-line page documented client->server JSON messages the
server never acted on (handleMessage logs only), a wrong ping/pong
exchange, and missed every message type added since. Rewritten tight
(~100 lines), every claim pinned: dual auth (JWT ?token= or device
Bearer header), initial_state on connect under the connecting
identity's RLS scope, the full 12-type message catalog (including
collection_updated, found per-user-targeted in the collections handler
and defined as a raw string outside the sync constants), WS-frame
keepalive (30s server ping, 90s read deadline — browsers answer
automatically), and the backpressure contract clients must honor:
bounded per-connection queues skip messages when full, so the socket
is a hint and REST refetch + fresh initial_state is the gap-healer.
Fan-out documented precisely: sync/scan events instance-wide,
collection events per-user.
Also corrected the gated endpoint doc (api/websocket/protocol.md):
its 'client sends {type:ping}, server responds pong' section
contradicted the handler; replaced with the true keepalive story.
Route pin untouched — the drift gates stay green.
4.0 KiB
WebSocket API (real-time events)
One channel, one direction: /ws/sync is a server → client push feed
for sync and scan events. It is not a command channel — clients do all
reading and writing through the REST API, and the server logs (but does
not act on) anything a client sends. The one client obligation is the
standard WebSocket pong, below.
Connecting
WS /ws/sync — two accepted identities:
| Method | How |
|---|---|
| User (JWT) | ?token=<jwt> query parameter |
| Device (KOReader, Kobo) | Authorization: Bearer <device-token> header |
No token → 401. On connect the server immediately sends one
initial_state message: the connecting identity's media items for
sync, read under that identity's own data visibility.
Message envelope
Every server message is a JSON object:
{
"type": "progress_update",
"timestamp": "2026-11-02T12:00:00Z",
"data": { "...": "..." },
"source_device": { "id": "…", "name": "Living-room Kobo", "type": "kobo" }
}
source_device is present on events that originate from a device
(progress and annotation updates), so clients can ignore their own echo.
Message catalog
All ten types defined by internal/sync/websocket.go:
| Type | Emitted | data carries |
|---|---|---|
initial_state |
Once, on connect | The connecting user's media items for sync |
progress_update |
On any device's progress save | book_id, percentage |
annotation_update |
On annotation changes (highlights, notes, bookmarks) | book_id, annotation_type, payload |
conflict |
When a sync conflict is detected | book_id, notification_type, conflict_id |
scan_progress |
During scan jobs | Job progress for the admin scan panel |
scan_complete |
When a scan job finishes | Job summary |
scan_error |
When a scan job fails | Job error |
scan_cancelled |
When a scan job is cancelled | Job identity |
collection_updated |
When books are added to / removed from one of your collections | collection_id, action (books_added / book_removed / books_removed), affected book ids |
heartbeat |
Defined, not currently emitted | — |
sync_complete |
Defined, not currently emitted | — |
(collection_updated is the one per-user-targeted event — it's emitted
with the connecting user's id directly. It's also currently the only
message type defined as a raw string in the collections handler rather
than in the sync package's constants block.)
Keepalive
The server sends a WebSocket ping frame every 30 seconds and expects the standard pong within a 90-second read deadline. Browsers and every mainstream WebSocket library answer pings automatically — there is nothing to implement. A connection that stops answering is removed.
Fan-out and backpressure — read this before building a client
- Sync and scan events fan out instance-wide: every connected client
receives progress, annotation, conflict, and scan events. The
exception is
collection_updated, which is targeted to one user's connections. (A per-user targeting helper exists and is used for collections only — the sync/scan emitters do not use it.) - Every connection has a bounded send queue. If a client falls behind,
messages for that connection are skipped, not queued (and the global
broadcast ring drops messages when saturated). Clients must therefore
treat the socket as a hint — on reconnect (or any gap), refetch real
state over REST. The fresh
initial_stateon reconnect is designed to be that gap-healer.