Docs Snapshot Endpoint

Internal worker → Convex sync endpoint. Not part of the public REST API — included here for operators integrating a self-hosted docs collaboration worker.

Purpose

The docs collaboration worker stores the binary Y.Doc as the source of truth for live editing. On a 2-second idle debounce (10-second maximum wait), the worker derives the Plate JSON view and posts it here so search, public-share rendering, and previews stay current. Only one worker runtime serves this contract:

workers/wiki-collab-do/ — raw y-websocket on Cloudflare Workers + Durable Objects

Plate JSON in Convex is read-only derived state — it is never used to rehydrate the Y.Doc on client connect. Binary Y.Doc state lives in the DO worker’s storage.

Endpoint

POST /internal/wiki/snapshot

Hosted at the Convex deployment URL.

Authentication

HMAC-SHA256 over ${timestamp}.${rawBody} using the shared secret WIKI_COLLAB_INTERNAL_SECRET, sent as a hex string in the X-Wiki-Collab-Signature header. The same timestamp (ms epoch) is also sent in X-Wiki-Collab-Timestamp and must be within ±5 minutes of server time. Requests with a missing or mismatched signature, a stale timestamp, or a previously seen signature are rejected with 401/409.

Request body

{
  "pageId":      "<wikiPages id>",      // required
  "content":     <Plate JSON value>,    // required
  "editedBy":    "<users id>",          // required
  "forceVersion": false                  // optional — true to write a wikiPageVersions row even within the throttle window
}

Response

200 OK with body {"ok": true} on success. 401 on signature failure or stale timestamp, 409 on a replayed signature within the freshness window, 400 on malformed body, 503 when WIKI_COLLAB_INTERNAL_SECRETis unset.

Operator notes

The endpoint calls the internal mutation internal.wikiPages.snapshotFromCollab, which throttles version snapshots to one per minute per page unless forceVersion is set.
Soft-deleted or archived pages silently no-op; the worker need not check page state before posting.
Failed posts should be retried by the worker. There is no server-side queue.