WebSocket API
Real-time collaboration runs over a separate API Gateway WebSocket API, handled by the
collab_handler Lambda. It carries Yjs document updates, awareness (cursors/presence), and
heartbeats between editors of the same post.
Routes
| Route | Handler | Description |
|---|---|---|
$connect | collab_handler.connect_handler | Authenticate (JWT) and join the document room |
$disconnect | collab_handler.disconnect_handler | Leave the document room |
$default | collab_handler.default_handler | Yjs updates + awareness + heartbeat |
Connecting
Clients connect to the WebSocket URL and authenticate with their Cognito token on
$connect. The handler validates the token, joins the client to the room for the target
post, and records the connection in the connections table (with a TTL so stale sockets
are cleaned up automatically).
Messages
$default messages are typed — they carry either a Yjs update (a CRDT change to the
document), an awareness update (cursor position / presence), or a heartbeat to keep
the connection alive. The handler broadcasts updates to the other connections in the same
room and persists document state so late joiners receive the current version.
See Real-Time Collaboration for the full picture, including Yjs state persistence and compaction.