Skip to content

websocket.md

Latest commit

 

History

History
42 lines (25 loc) · 2.16 KB

websocket.md

File metadata and controls

42 lines (25 loc) · 2.16 KB

WebSocket protocol (BrowserBox)

Transport

Request envelope (client → server)

JSON messages include:

  • id — non-empty string, correlates to the reply.
  • op — operation name; constants in lib/ws-ops.ts.
  • payload — optional, op-specific.
  • authToken — optional JWT; sent on each message when a session exists (see lib/ws-client.ts, key browserbox_session_token in sessionStorage).

Reply envelope (server → client)

  • Success: { id, ok: true, data }
  • Failure: { id, ok: false, error, code }

Operations

Authoritative routing and per-op broadcastKind (none | todos | textFiles) live in lib/server/ws-ops-registry.ts. lib/server/ws-dispatch.ts resolves the session from authToken / socket state, dispatches the op, then—when broadcastKind is not none—calls broadcastAfterMutationForKind so subscribers receive the right push events after mutations.

Server push events

String constants in lib/realtime-push-events.ts. The browser bridge is lib/realtime-bridge.ts.

Security note

The session JWT is stored in sessionStorage and is readable if script runs on your origin (XSS). Mitigate with CSP, input sanitization, and a sensible JWT TTL (SESSION_MAX_AGE_SEC in lib/auth-constants.ts).

Typed client helpers

Higher-level calls that wrap browserboxWsCall + DTO mapping:

Session token read/write helpers live in lib/ws-session-token.ts (re-exported from lib/ws-client.ts for convenience).