Collaboration API

Base path: /api/collab/:ref_id/signal

This endpoint powers realtime, multi-author editing of a single document (ref_id). It carries presence, block locks, and WebRTC signaling. All of its state is short-lived by design — presence, locks, and pending signals are stored in the cache/KV service with a short TTL, so nothing here needs durable storage.

Access control is delegated to the collaboration repository; the cache is injected too, keeping the route free of the app’s database and session layer.

Endpoints

  • GET /api/collab/:ref_id/signal — heartbeat. Refreshes the caller’s presence, returns the current peers, the held locks, and any pending signals addressed to the caller.

    • Query: peer_id (the caller’s peer id), held_locks (comma-separated block ids the caller currently holds).
    • Returns: { "peers": [...], "signals": [...], "locks": [...] }.

  • POST /api/collab/:ref_id/signal — broadcast an event: acquire or release a block lock, relay a transaction, or send a WebRTC signaling message to a peer.

  • DELETE /api/collab/:ref_id/signal — leave the session: drop the peer’s presence and release any locks it held.

Usage pattern

  1. On open, POST to announce the peer, then poll GET on an interval as a heartbeat.
  2. Acquire a lock with POST before editing a block; release it when done.
  3. Relay peer-to-peer signaling and transactions through POST.
  4. On close (or when the heartbeat lapses), DELETE to clean up.

Because every entry is TTL-based, a peer that disconnects without calling DELETE is cleaned up automatically once its presence expires.