@stesura/collab-adapter-server

Plugins for the EditorState applyServerEdit builds on docs of this schema; their appendTransactions run on every server edit. Only plugins whose state derives from the doc alone (numbering, note order), never DOM/layout/UI ones. Default: none.

Document/commit persistence (e.g. postgresStore).

Pub/sub + presence (e.g. redisBroadcast).

The empty document createRoomDoc seeds a doc of a non-default schema with when it gets no initialContent (the store seeds default-schema docs itself). Default: schema.topNodeType.createAndFill().

What reading a docId with no row does.

• "seed" (default): create an empty document.
• "reject": reads return null (routes answer 410) and server edits never seed. Use it when docs are created explicitly via createRoomDoc, so a deleted doc isn’t resurrected by the next poll. Requires store.peekDoc. receiveCommit itself still seeds; the routes gate it.

Commits retained per document. Older ones only serve clients catching up, and an unbounded log lets a forged low version force full-history scans under the doc lock.

Pruned inside the commit transaction every COMMIT_PRUNE_INTERVAL versions (requires store.pruneCommits). A client behind the window gets StaleVersionError (412) and re-hydrates and rebases its unconfirmed steps across the gap with the commits’ step maps (CreateCollabBackendConfig.commitMapRetention). Infinity disables. Default 1024.

How long the step maps of pruned commits are kept, in milliseconds: a client offline for up to this long rebases its edits across what it missed instead of losing them. Pruned by created_at at the commit prune cadence (requires store.pruneCommitMaps). Infinity keeps them. Default DEFAULT_COMMIT_MAP_RETENTION_MS (30 days).

Byte cap on client JSON: createRoomDoc’s initialContent, and every route request body (the routes read it off the backend). Bounds the cost of one request; volume is the rate limiter’s job. Default DEFAULT_MAX_CONTENT_BYTES; Infinity disables.

Steps one commit may carry, a batch step counted by what it costs to apply (core’s commitStepWeight); a larger one throws CommitTooLargeError (routes: 413) before any transaction. Bounds the apply, which holds the doc’s row lock. Default core’s MAX_COMMIT_STEPS, which Replace All stays under; Infinity disables.

Where a commit applies: from workerSteps steps on, in a worker thread with a heap and time budget, so a large apply blocks no other room and a runaway one is rejected (CommitApplyBudgetError , routes: 413) instead of stalling or crashing the process. At most maxWorkers run at once; a commit that waits past maxWaitMs is refused (CommitApplyBusyError , routes: 429) and resent by the client. Defaults: DEFAULT_COMMIT_APPLY .

Byte cap on one thread write’s request body, applied by the routes on top of maxContentBytes (the smaller wins). Default DEFAULT_MAX_THREAD_BYTES; Infinity disables.

Comment threads one document may hold. Creating one more throws ThreadLimitError; updating an existing thread is always allowed. Checked outside a transaction, so concurrent creations can overshoot it slightly. Requires store.getThread. Default DEFAULT_MAX_THREADS_PER_DOC; Infinity disables.

In-process cache of the latest document per docId. Upstream’s receiveCommit reads the whole document on every commit; with the cache, the lock is taken via store.lockDoc (version only) and the document is served from memory when version and incarnation match, falling back to a full read. Requires store.lockDoc. maxBytes: 0 disables.

Version history (requires store.snapshots; without it history is off). An automatic snapshot is written inside the commit transaction every every versions, and version 0 is captured on a doc’s first commit, as the anchor exact reconstruction replays from. every: 0 turns the automatic ones off; named versions and restores still work.

Sink for failures handled internally (a throwing mention hook, a Redis error, a failed commit), called in addition to the console log. The routes report through it too.

Plugins for the EditorState applyServerEdit builds on docs of this schema; their appendTransactions run on every server edit. Only plugins whose state derives from the doc alone (numbering, note order), never DOM/layout/UI ones. Default: none.

The ingest byte cap (Infinity when disabled), which transports apply to raw bodies.

The thread-write byte cap (Infinity when disabled), which transports apply to raw bodies.

The default schema: the only one, unless the backend was given schemas.

Every schema served, by name.

The schema serving a doc: the one it was created under, else the default (also for a doc with no row yet). Transports dry-parse client steps with it first: a step that throws inside the authority surfaces as contention (a 409 retried forever), not a 400. Cached per doc; the cache is checked against the row on every commit, but not on reads, so a doc created under another schema through another instance can read stale here. refresh re-reads the store: transports do so before refusing a client, since a refusal is terminal for it.

CreateCollabBackendConfig.onError, wrapped with the console log.

Upstream’s receiveCommit (reimplemented: bounded apply, own retries), plus content gates and the commit’s actor.

Whether the store keeps step maps (store.getCommitMaps).

The step maps of every commit in (from, to], one entry per version in order, with the commits’ refs. What a client further behind than the retained commits rebases across. Requires store.getCommitMaps.

Hydration read. Null only under missingDocBehavior: "reject" with no doc row.

The doc’s current version, or null when it has no row; never seeds. The starting point for following store.getCommitLog(docId, afterVersion) or checking staleness. One indexed read with store.getDocVersion; without it, a full document read.

CollabBackend.getInitialDoc in the cheapest form this request accepts. acceptEncoding is the request’s Accept-Encoding header; null forces plain JSON.

“gone” when missingDocBehavior: "reject" and the doc row is absent. Always “ok” in “seed” mode, without a store read.

Applies a programmatic edit: runs build on a fresh EditorState (with serverPlugins) and submits the steps as a commit, rebased against concurrent ones and retried on contention. See ServerEditBuildFn for the purity requirement; check droppedSteps on the result.

applyServerEdit over many docs, with per-edit results. Never throws; no cross-document atomicity.

Creates the room if absent, storing meta (opaque host data, e.g. its kind or tenant). A room that already exists keeps its first meta. Requires store.rooms.

The room and its meta, or null. Requires store.rooms.

A room’s manifest (docs + change ref). Requires store.rooms.

Long-poll for manifest changes since knownRef. Requires store.rooms.

Adds a doc to a room (creating the room if absent), seeded with initialContent or an empty document, and bumps the manifest ref. schemaName picks the schema the doc keeps for good; absent, the default. Requires store.rooms.

Removes a doc from a room, purging its rows (doc, commits, threads), and bumps the manifest ref. Requires store.rooms.

The room a doc belongs to, or null. For doc-route authorize: resolve the room, then check the app’s own membership.

Live presence indicators of a document, keyed by clientId.

Stores a client’s indicator, stamping movedAt with server time when moved.

Live room presence, keyed by clientId.

Stores a client’s room indicator, stamping updatedAt with server time.

Long-poll for room presence changes against the refs the client holds. A member whose indicator expired (TTL) counts as a change.

Upserts one thread blob (whole-blob, last write wins).

Deletes every thread of a document and wakes thread polls. Requires store.deleteThreads.

One thread record, or null. Requires store.getThread.

Creates a thread with one comment and anchors it in the document: the blob is saved first (through CollabBackend.saveThread), then the anchor lands via applyServerEdit. When the anchor can’t be placed (see anchorError) or the edit fails, the thread is removed again (hard delete when the store has deleteThread, else a soft delete). A target the current doc already rejects writes nothing. Requires store.getThread.

Read-modify-write of one thread through CollabBackend.saveThread (caps, wakes, mention events). Not transactional: a concurrent write in between is overwritten (last write wins, as for client writes). Resolves the saved blob, or null when the thread doesn’t exist. Requires store.getThread.

Sets resolved via CollabBackend.updateThread.

Soft delete by default: sets deletedAt via CollabBackend.updateThread, anchors kept (as the client’s delete, which an undo reverts). hard removes the row (requires store.deleteThread), wakes thread polls, then removes the thread’s anchors with applyServerEdit.

Whether the store keeps version history (store.snapshots).

A doc’s history, newest first, without content. Requires store.snapshots, as every history method does.

One history version with its document, or null.

Names the doc’s current version (renames it when already named), under the doc lock.

Makes a history version the current content, as an ordinary commit through applyServerEdit, so collaborators receive it live and it lands in history itself (restoredFrom). The head it replaces is snapshotted in the same transaction, so a restore can always be undone from history. Resolves the new head; unchanged when the content already matched.

The document exactly as it was at version: the newest snapshot at or below it, plus the commits after it replayed. Null when no snapshot precedes it or the commits are pruned (commitRetention bounds how far back replay reaches).

Drops the cached document for docId (all docs when omitted). Required after rewriting a doc outside the engine without bumping its version, since the cache trusts version equality; otherwise it only frees memory.

Fired after a thread save whose blob has (commentId, mentionedUserId) pairs the stored blob lacked. Not awaited; errors go to onError and never fail the save. Requires store.getThread. The pre-save read isn’t transactional, so concurrent saves of one thread can rarely double-fire or miss a mention.

Fired after a thread save that created, resolved, reopened, deleted or restored the thread, or added, edited or deleted a comment, and after a hard deleteThread. Not for clearThreads nor removeRoomDoc. Same guarantees as onThreadMentionsCreated: not awaited, errors go to onError, requires store.getThread, and concurrent saves of one thread can rarely double-fire or miss a change.

Fired once per persisted commit (client commits and server edits), after its transaction and broadcast. Not for resent, rejected or noop commits, nor createRoomDoc. Not awaited; errors go to onError and never fail the commit. Per process: other instances don’t see it, so keep store.getCommitLog for cross-instance catch-up.

Fired after createRoom (or createRoomDoc) creates a room that didn’t exist, createRoomDoc adds a doc, or removeRoomDoc removes one; never for a no-op. Not awaited; errors go to onError. Per process, like onCommit: writes through another instance aren’t seen.

Editor fragment the thread belongs to (main doc, footnote, …).

thread.metadata as stored (client-owned).

One entry per comment that gained mentions in this save.

Editor fragment the thread belongs to (main doc, footnote, …).

thread.metadata as stored (client-owned).

The writer’s authenticated identity (the routes’ resolveAuthor). Null for backend calls made without one (updateThread, createThread, deleteThread…).

Never empty.

The version the commit produced.

As stored on the commit row.

receiveCommit, or applyServerEdit / applyServerEditMany.

Author of the comment containing the mentions.

Deduped; excludes the author (the authenticated one when known, else the blob’s).

Return not-found instead of seeding a missing doc. Default false; always on under missingDocBehavior: "reject".

Retries after contention before throwing ServerEditContentionError, with full-jitter backoff. Each attempt already makes up to 5 transaction attempts upstream. Default 5.

Stored with the commit, e.g. { kind: "system", causedBy: userCommitRef }.

The thread’s first comment. author is trusted as given: the host vouches for it.

Stored as thread.metadata; editorId is always overwritten.

Defaults to a random UUID.

Root editor the thread belongs to. Default DEFAULT_THREAD_EDITOR_ID.

Stored with the anchor commit.

The anchor edit. The thread exists only when applied; otherwise it was removed again. As with any server edit, droppedSteps > 0 means a concurrent commit dropped (part of) the anchor.

Why the anchor couldn’t be placed (edit is then noop), else null.

Remove the row and the thread’s anchors instead of setting deletedAt. Default false.

Stored with the anchor-removal commit (hard only).

Whether the thread existed.

The anchor-removal edit; null for a soft delete.

Postgres connection string. For Supabase, use the transaction pooler (Supavisor, port 6543) connection string.

Builds the empty document seeded on first access (schema.topNodeType.createAndFill()).

Override the seeded empty document (e.g. default sections/styles).

How content is compressed at rest. Default "brotli" (level 4): ~95% smaller rows for ~12 ms of async encode per commit. Pass a DocCodec for your own. Changing it never invalidates stored rows: each row records the codec that wrote it.

Brotli 0–11 (default 4) or gzip 1–9 (default 6); ignored otherwise. Keep it low: encoding runs on the commit path, and brotli 11 takes seconds on a large document.

Cap on one stored document in uncompressed bytes, enforced on write and as the decompression bound on read. Default DEFAULT_MAX_STORED_DOC_BYTES.

Override the table names if you namespace them.

Forwarded to the postgres driver. prepare: false is the default (the Supavisor transaction pooler requires it) unless overridden here.

ProseMirror schema used to build the initial empty document.

Optional override for the initial empty document (see postgresStore).

Run fn inside one atomic database transaction.

Read the document, taking the row lock when tx is present. Seeds an empty document when the row is absent, so it never returns null.

Optional: take the same row lock as getDoc but return only version and timestamp, never content. Null when the row is absent (no seeding; the engine then falls back to getDoc).

Enables the engine’s doc cache: the per-commit document read becomes a version and incarnation check. Without it, every commit reads the full content. getDoc must return the same incarnation, or the cache never hits.

A single commit by ref, or null (the idempotency check).

All commits with version strictly greater than version, ascending.

Optional: version of the oldest retained commit after version, or undefined. Pool-level. Used by the commit path’s staleness pre-flight; without it the engine reads the whole getCommits tail, steps included, on every write. Implement as select version … limit 1.

Persist the materialized document. Implementations should stamp the current time: the authority passes back the timestamp it read, so storing it freezes the row’s seed time.

Insert a commit. MUST throw if version or ref is already taken for docId — that is how contention and duplicate resends reach the authority. actor is stored with it when given; maps (one per step) too, for CollabStore.getCommitMaps.

Optional: who committed what after afterVersion, ascending, without the steps. Pool-level. Backs audit reads (“who changed this since the last publish”).

Optional: the doc’s current version without its content, or null when the row is absent. Pool-level, never seeds. Backs CollabBackend.getDocVersion, which otherwise reads and decodes the whole document.

Optional: delete commits up to and including throughVersion. Called inside the commit transaction to enforce commitRetention; without it the commit log grows unboundedly. A store with CollabStore.getCommitMaps first keeps their step maps and refs, in one row per call, in the same transaction.

Optional: delete the step maps pruneCommits kept more than retentionMs ago. Called inside the commit transaction at the prune cadence, to enforce commitMapRetention.

Optional: the step maps of the commits in (afterVersion, throughVersion], live and pruned, ascending, one entry per version held (a version held by neither is absent). Pool-level. Backs the maps route a client rebases across a gap with; without it that route answers 404.

Hydration read (GET doc route). Pool-level, no lock. Seeds when the row is absent.

Optional: read without seeding; null when the row is absent. Pool-level. Required by applyServerEdit’s mustExist and missingDocBehavior: "reject". For existence checks use CollabStore.docExists.

Optional: CollabStore.getInitialDoc undecoded, so the GET-doc route can send the stored compressed bytes as-is. Seeds when the row is absent. Without it the backend decodes and answers plain JSON.

Optional: CollabStore.getInitialDocEncoded without seeding; null when the row is absent. Used in missingDocBehavior: "reject" mode — implement both or neither.

Optional: does the doc row exist? Pool-level. Runs on every request in reject mode, so implement it as a probe (select 1 ... where id = $1), never as a content read. The backend falls back to peekDoc when absent.

Optional: the doc’s DocSnapshot.schemaName, or null for the default schema or no row. Required by a backend serving more than one schema. A probe, never a content read.

Optional: room manifests (suite = room). Required by the backend’s room operations, which throw without it. Membership/ACLs are not stored here: the host app checks them in the route authorize callback.

Optional: version-history checkpoints, one per (doc, version). Required by the backend’s history operations, which throw without it. Rows go with their document.

Opaque value that changes whenever this document’s threads change; only equality is meaningful. Clients long-poll on it. It must be derived from the durable write, not the broadcast layer, so a lost broadcast costs one poll cycle instead of hiding the change.

All comment threads of a document. Pool-level.

Optional: one thread, or null. Pool-level. Required by events.onThreadMentionsCreated (the pre-save baseline for the mention diff).

Optional: how many threads a document holds. Pool-level. Backs maxThreadsPerDoc; without it the engine counts getThreads, reading every blob.

Optional: delete every thread of a document. Pool-level. Backs CollabBackend.clearThreads.

Optional: delete one thread; a no-op when absent. Pool-level. Backs CollabBackend.deleteThread’s hard mode and createThread’s rollback.

Insert-or-replace one thread (last write wins). Pool-level. Must reject when the doc row is absent (the shipped schema’s FK).

Optional: close pooled connections on shutdown.

Envelope codec id. 0–2 are reserved for none/gzip/brotli; custom codecs pick 16–255.

HTTP content-coding (“gzip”, “br”) when the bytes are exactly what a browser decodes under it, else null. Only then can stored bytes be streamed straight to a client.

MUST reject with a RangeError once the output would exceed maxBytes, without buffering past it (decompression bomb guard).

Redis/Valkey connection string (e.g. an Upstash rediss:// TCP URL).

Max time (ms) a long-poll listener waits for a change. Default 5000.

Seconds an indicator survives without a refresh, for clients that vanished without leaving. Idle cursors fade after this and return on the next selection change. Default 30. Requires Redis >= 7.4 (hash-field TTLs).

Seconds a room presence indicator survives without a refresh. Clients heartbeat every 10s, so a closed tab drops out within this. Default 30. Requires Redis >= 7.4.

Seconds a proofread cache bucket survives without a write. Default 30 days.

Deprecated: Ignored: thread and room-manifest bumps are publish-only and store no key.

Namespace for every key/channel this adapter owns, so backends sharing one Redis don’t collide. Default: none.

Sink for driver failures (socket resets, failed reconnects, unparseable hash fields). Usually the same reporter as createCollabBackend’s onError.

Commit fan-out for the long-polls.

Presence storage + fan-out.

Room presence storage + fan-out.

Comment-thread change notifications (keyed by docId).

Room-manifest change notifications (keyed by roomId).

Shared proofread-result cache.

Open all connections. The engine memoizes it but calls again after a failure, so it must be retryable when only some connections opened.

Optional: release every connection. Call it on shutdown and in test teardown.

Authorization gate run before every handler. Return true to allow, false for a plain 403, or a Response (e.g. a 401 with a body) to answer with it. Required unless CreateCollabRoutesOptions.allowUnauthenticated is set.

When docs belong to rooms, resolve membership through the room:

The authenticated author of a thread write. Mention events are stamped with this instead of the forgeable author in the client’s blob — wire it whenever events.onThreadMentionsCreated feeds notifications.

The authenticated user behind a presence update. userId is otherwise body input driving every peer’s name, colour and “this is me” filter, so any member could impersonate another. Returning null answers 403.

Who a commit is from, stored with it (collab_commit.actor_*). Returning null answers 403. Without it commits carry no actor.

Per-actor throttle on the write routes: commit POST, presence POST/DELETE, thread PUT and proofread POST.

Long-polls one actor may hold open at once, across commits, presence and threads; above it the poll answers 429. A concurrency cap rather than a rate, since a held poll is meant to be slow — its cost is the subscription and the open request.

The actor is rateLimit.identify when wired, else the adapter’s client address. With neither (e.g. /next without identify), only CreateCollabRoutesOptions.maxConcurrentPollsPerDoc applies. A tab holds three; keyed on an address, one NAT’d office shares the budget.

Long-polls held on one document across all callers — the guard that still applies when no per-actor key exists.

Mount without an authorize gate, so every caller can read and write every docId. For local development; without it, a missing authorize throws.

Answer hydration with the stored compressed bytes and a matching Content-Encoding when the request accepts that coding and the store can supply them. Turn it off for a host that re-encodes or strips Content-Encoding; the plain-JSON fallback is always correct, only larger.

Authorization gate run before every handler; same contract as the doc routes’. Required unless allowUnauthenticated is set.

The authenticated user behind a room presence update; the body’s userId otherwise. Returning null answers 403.

Per-actor throttle on doc create and delete and on presence updates; the default actor is the roomId (plus client address when known). Creating a doc parses up to maxContentBytes through the schema, so this is the costliest route to leave unmetered.

Manifest and presence long-polls one actor may hold open at once; same actor rules as the doc routes’ CreateCollabRoutesOptions.maxConcurrentPolls, with a budget of its own.

Manifest and presence long-polls held on one room across all callers.

Mount without an authorize gate, so every caller can enumerate, create and delete every room’s documents. For local development; without it, a missing authorize throws.

Already percent-decoded. Ids are opaque and host-chosen, but must be percent-encoded on the wire and at most 256 characters decoded; longer ones are a 400 before authorize runs.

Path segments after the docId, e.g. ["commits"] or ["presence", clientId].

Already percent-decoded.

Path segments after the roomId, e.g. ["listen"] or ["docs", docId].

Sustained requests per second per actor.

Burst capacity in requests. Defaults to ratePerSecond.

The actor a bucket belongs to. Defaults to the doc/room id plus the client address when the adapter supplies one, else the id alone. Never a clientId or threadId: those are client-chosen, so a bucket keyed on them is bypassable. Collaborators behind one address share the default bucket — wire this to the session user for per-user fairness.

Doc routes. Omit to serve only the room API; at least one of docs/rooms is required.

Room-manifest routes. Omit to serve only the doc API.

Answers GET with an empty 200 (other methods 405), before auth and any store access. Null disables it.

Browser origins allowed to call this server (CORS with credentials): exact origins, https://*.example.com for one subdomain label, or a predicate (see AllowedOrigins ). Other origins get no CORS headers.

Reverse proxies whose X-Forwarded-For / X-Forwarded-Proto entries are trusted: the client address and scheme are the entries this many hops from the right, 0 uses the socket. Too low and every caller behind the proxy shares one address; too high and a client can pick its own.

Sent as x-doc-version.

Sent as x-doc-updated-at.

Sent as x-doc-schema when given. Collab docs always name theirs; a host’s own docs may not.

The body’s Content-Encoding, for stored compressed bytes sent as-is.

Commit fan-out for the long-polls.

Presence storage + fan-out.

Room presence storage + fan-out.

Comment-thread change notifications (keyed by docId).

Room-manifest change notifications (keyed by roomId).

Shared proofread-result cache.

Open all connections. The engine memoizes it but calls again after a failure, so it must be retryable when only some connections opened.

Optional: release every connection. Call it on shutdown and in test teardown.

Every commit handed to broadcastCommit, in order.