John O'Keefe
a431dfa10b
Owner-flagged after the dev-docs audit: BroadcastProgressUpdate, BroadcastAnnotationUpdate, and BroadcastConflictNotification fanned out through the untargeted Broadcast, delivering one user's book progress, conflict notices, and — worst — annotation payloads (which can carry note/highlight text) to EVERY connected client on the instance. A family-lens violation of exactly the kind the RLS move eliminated for database reads: user B's client received events for user A's books, including books in libraries hidden from B. Fix is the RLS philosophy applied to the fan-out layer: enforcement at one choke point. The untargeted Broadcast method and its channel/loop machinery are deleted — BroadcastToUser is now the only door, and the compiler forces every future emitter to name its audience instead of relying on review. The three helpers take the acting user's ID; the four sync call sites (progress.go x2, annotations.go x2) already had the acting user in scope. Scan events were already per-triggering- identity and collections already per-user — unchanged. Logging is untouched: the only log line in the diff is the deleted method's own, so docker logs remains the complete administrator audit trail. TestBroadcastIsPerUser pins the invariant (alice's two devices receive her three events; bob's client receives nothing — any message there is a cross-user leak). Both websocket docs updated in the same commit: the wire doc's fan-out section now states per-user delivery and the chokepoint, and the gated endpoint doc's intro matches. Full make test 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 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
- Every event is delivered only to the acting user's connections. Progress, annotation, and conflict events go to the user whose sync activity produced them; scan events go to the identity that triggered the job; collection events to the collection's owner. The ConnectionManager has no untargeted broadcast — the compiler enforces an audience on every emitter (2026-11-02, after cross-user delivery was found and fixed).
- Every connection has a bounded send queue. If a client falls behind,
messages for that connection are skipped, not queued. 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.