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.
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.
BREAKING CHANGE: Documentation URLs have changed
New structure:
- user/ - End-user documentation (device setup, sync guides, frontend)
- developer/ - Developer documentation (API reference, protocols, specs)
- operations/ - Operations documentation (deployment, troubleshooting)
- contributing/ - Contribution guides
Changes:
- Created portal INDEX.md files for each audience section
- Moved device guides to user/devices/ (kobo-setup.md, koreader-setup.md)
- Moved API docs to developer/ (api-reference.md, collections-api.md)
- Moved sync guide to user/sync-guide.md
- Moved troubleshooting to operations/troubleshooting.md
- Moved all split API docs to developer/api/
- Renamed protocol files (kobo-protocol.md, koreader-protocol.md)
- Added placeholder user guides (frontend, user-areas, settings, admin)
- Updated all internal links to new paths
- Updated Go code (http_handler.go, navigation.go) for new paths
- Updated main INDEX.md for audience-based navigation
Benefits:
- Clear separation of user and developer documentation
- Scalable structure for future user guide expansion
- Better organization and discoverability
- Audience-specific landing pages
Related to DOCS_IMPLEMENTATION_PLAN.md Phase 2 completion
John O'Keefe
john-okeefe