Skip to content

gitflarePublicPartly agent-ready50

cf-durable-whiteboard

Realtime collaborative whiteboard on Cloudflare Durable Objects: presence cursors, WebSocket hibernation, SQLite storage, undo, PNG export.

Keep board zoom and pan stable across reloads6eb4fbd
Markdown16 lines1.7 KB

Architecture

The Worker (src/index.ts) routes /health, /api/boards/:id and /ws/:id; everything else is served from public/ via the ASSETS binding. A WebSocket upgrade is forwarded to the Board Durable Object named by the board id, so each board is a single-writer, serialised actor.

Hibernation

The DO accepts sockets with ctx.acceptWebSocket(server) and implements webSocketMessage, webSocketClose and webSocketError. Per-socket identity { userId, name, colour } is stored with serializeAttachment, so after the DO is evicted and rewoken it recovers identity from ctx.getWebSockets() without in-memory state. Idle boards cost no duration.

Storage and op log

SQLite tables: shapes(id, kind, data, z, author, updated_at) hold current state; ops(seq, user_id, op, inverse, at) is an append-only log. Each accepted op gets a monotonically increasing seq and is broadcast as op{seq, op, by}. Only the last 500 ops are kept; older rows are pruned after insert. Cursors are relayed and never stored.

Inverse ops

When an op is applied (add|update|delete|clear) the pure module src/lib/ops.ts computes its inverse from prior state (add↔delete, update restores previous fields, clear restores all deleted shapes). Undo pops the user's own entry, applies its inverse as a new op and broadcasts it, so all peers see the change; redo reverses that. A new op by a user clears their redo stack. Undo reaches only ops still in the retained log.

Rate limiting

src/lib/ratelimit.ts implements a token bucket per socket: 60 tokens/s refill, burst 120. Messages over 32 KB or failing validation (src/lib/validate.ts) are rejected with an error. Repeated abuse closes the socket with code 1008.