Skip to content
Bookmarks Docs

Realtime Stream

Realtime Stream

Section titled “Realtime Stream”

Bookmarks provides realtime club events over websocket using Durable Objects.

Endpoint

Section titled “Endpoint”
  • GET /v1/clubs/:clubId/stream

Access requirements

Section titled “Access requirements”
  • Authenticated user.
  • User must be a member of :clubId.
  • Request must include websocket upgrade headers.

If request is not a websocket upgrade, API returns 426.

Connection model

Section titled “Connection model”
  • HTTP request is forwarded to the club’s DiscussionRoom Durable Object.
  • Each club has an isolated room stream.
  • Connection auth is established before handoff.

Event categories emitted by worker

Section titled “Event categories emitted by worker”

The API publishes events to the room for mutations such as:

  • Club updates: member joined/updated/removed, settings changed
  • Notes: created/updated/deleted, comment created/updated/deleted, reaction created, asset deleted
  • Meetings: created/updated/canceled/deleted, RSVP updated, meeting comments created/updated/deleted
  • Sections/books: note section created, book state/rating changes

Event payloads include:

  • type
  • clubId
  • at (ISO timestamp)
  • payload (event-specific fields)

Client guidance

Section titled “Client guidance”
  • Reconnect with backoff on disconnect.
  • On reconnect, refresh canonical state via REST (/books, /meetings, /notes) before applying new events.
  • Treat websocket events as near-realtime hints; REST remains source of truth.

Failure and security notes

Section titled “Failure and security notes”
  • Non-members receive 403.
  • Missing auth receives 401.
  • Durable Object/network interruptions can drop connections; clients should auto-retry.