Skip to content

Where agent teams gather. Cross-platform team chat where AI agents are first-class teammates — with cloud or bring-your-own (Claude Code / Codex) brains.

TypeScript

fix(ws): bound document authorization fanout (#256)

OKNOTOKdbf86589d2cd
diff --git a/server/src/__integration__/ws-doc-authorization.test.ts b/server/src/__integration__/ws-doc-authorization.test.ts
new file mode 100644
index 0000000..572a8f0
--- /dev/null
+++ b/server/src/__integration__/ws-doc-authorization.test.ts
@@ -0,0 +1,604 @@
+/**
+ * Real WebSocket/document authorization regressions.
+ *
+ * These tests deliberately use createWsTicket + attachWebSocket, PostgreSQL
+ * row/table locks, and an observer Client outside the application's max=20
+ * pool. The document room persists asynchronously, so fan-out is triggered
+ * through the exported awareness path when the test is interested in the
+ * authorization boundary itself.
+ */
+import assert from 'node:assert/strict'
+import { randomUUID } from 'node:crypto'
+import { createServer, type Server } from 'node:http'
+import { after, afterEach, before, beforeEach, test } from 'node:test'
+import { setTimeout as delay } from 'node:timers/promises'
+import { Client } from 'pg'
+import WebSocket from 'ws'
+import * as Y from 'yjs'
+import { createWsTicket } from '../auth.js'
+import { pool } from '../db/pool.js'
+import { broadcastAwareness, evictDocumentRoom } from '../documents/rooms.js'
+import { attachWebSocket } from '../ws.js'
+import {
+ buildApiTestApp,
+ ensureSchemaOnce,
+ resetAllTables,
+ seedUserMembership,
+ teardownAll,
+} from './_helpers.js'
+
+type Frame = Record<string, unknown>
+
+interface SocketHarness {
+ socket: WebSocket
+ messages: Frame[]
+}
+
+interface DocumentFixture {
+ companyId: string
+ documentId: string
+ users: string[]
+}
+
+const ACTOR_ID = 'z-ws-doc-actor'
+const OBSERVER_QUERY_TIMEOUT_MS = 5_000
+const FRAME_TIMEOUT_MS = 6_000
+
+let server: Server
+let baseUrl = ''
+let wsUrl = ''
+let wss: ReturnType<typeof attachWebSocket>
+const openSockets = new Set<SocketHarness>()
+const fixtureDocumentIds = new Set<string>()
+
+function databaseUrl(): string {
+ const url = process.env.DATABASE_URL ?? process.env.INTEGRATION_DATABASE_URL
+ assert.ok(url, 'integration database URL is required')
+ return url
+}
+
+async function within<T>(promise: Promise<T>, label: string, timeoutMs = OBSERVER_QUERY_TIMEOUT_MS): Promise<T> {
+ let timer: ReturnType<typeof setTimeout> | undefined
+ // A timed-out operation can still settle later. Attach a rejection handler
+ // so a deliberately failed barrier does not become an unhandled rejection
+ // while the test cleans up its connections.
+ void promise.catch(() => {})
+ try {
+ return await Promise.race([
+ promise,
+ new Promise<T>((_resolve, reject) => {
+ timer = setTimeout(() => reject(new Error(`timed out waiting for ${label}`)), timeoutMs)
+ }),
+ ])
+ } finally {
+ if (timer) clearTimeout(timer)
+ }
+}
+
+function parseFrame(raw: WebSocket.RawData): Frame | null {
+ try {
+ const parsed: unknown = JSON.parse(raw.toString())
+ return parsed && typeof parsed === 'object' ? parsed as Frame : null
+ } catch {
+ return null
+ }
+}
+
+async function waitForFrame(
+ harness: SocketHarness,
+ predicate: (frame: Frame) => boolean,
+ label: string,
+ timeoutMs = FRAME_TIMEOUT_MS,
+): Promise<Frame> {
+ const start = harness.messages.length
+ const deadline = Date.now() + timeoutMs
+ while (Date.now() < deadline) {
+ const found = harness.messages.slice(start).find(predicate)
+ if (found) return found
+ await delay(5)
+ }
+ throw new Error(`timed out waiting for ${label}`)
+}
+
+async function waitForBlockedQuery(
+ observer: Client,
+ pattern: string,
+ minimum = 1,
+ timeoutMs = OBSERVER_QUERY_TIMEOUT_MS,
+): Promise<void> {
+ const deadline = Date.now() + timeoutMs
+ while (Date.now() < deadline) {
+ const { rows } = await observer.query<{ count: number }>(
+ `SELECT COUNT(*)::int AS count
+ FROM pg_stat_activity
+ WHERE datname = current_database()
+ AND pid <> pg_backend_pid()
+ AND wait_event_type = 'Lock'
+ AND query ILIKE $1`,
+ [pattern],
+ )
+ if ((rows[0]?.count ?? 0) >= minimum) return
+ await delay(10)
+ }
+ throw new Error(`query never reached ${minimum} blocked session(s): ${pattern}`)
+}
+
+async function openSocket(userId: string): Promise<SocketHarness> {
+ const { ticket } = await createWsTicket(userId)
+ const socket = new WebSocket(`${wsUrl}?t=${encodeURIComponent(ticket)}`)
+ const harness: SocketHarness = { socket, messages: [] }
+ socket.on('message', (raw) => {
+ const frame = parseFrame(raw)
+ if (frame) harness.messages.push(frame)
+ })
+ openSockets.add(harness)
+
+ await within(new Promise<void>((resolve, reject) => {
+ const onOpen = () => {
+ cleanup()
+ resolve()
+ }
+ const onError = (error: Error) => {
+ cleanup()
+ reject(error)
+ }
+ const cleanup = () => {
+ socket.off('open', onOpen)
+ socket.off('error', onError)
+ }
+ socket.once('open', onOpen)
+ socket.once('error', onError)
+ }), `WebSocket open for ${userId}`)
+ await waitForFrame(harness, (frame) => frame.type === 'hello', `${userId} hello`)
+ return harness
+}
+
+async function subscribeSocket(harness: SocketHarness, documentId: string, replaySupported = true, omitCapability = false): Promise<void> {
+ const frame: Record<string, unknown> = { type: 'doc.subscribe', documentId }
+ if (!omitCapability) frame.replaySupported = replaySupported
+ harness.socket.send(JSON.stringify(frame))
+ await waitForFrame(
+ harness,
+ (frame) => frame.type === 'doc.sync' && frame.documentId === documentId,
+ `doc.sync for ${documentId}`,
+ )
+}
+
+async function openDocSocket(userId: string, documentId: string): Promise<SocketHarness> {
+ const harness = await openSocket(userId)
+ await subscribeSocket(harness, documentId)
+ return harness
+}
+
+async function closeSocket(harness: SocketHarness): Promise<void> {
+ openSockets.delete(harness)
+ if (harness.socket.readyState === WebSocket.CLOSED) return
+ await within(new Promise<void>((resolve) => {
+ const finish = () => {
+ harness.socket.off('close', finish)
+ resolve()
+ }
+ harness.socket.once('close', finish)
+ harness.socket.close()
+ if (harness.socket.readyState === WebSocket.CLOSED) finish()
+ }), 'WebSocket close')
+}
+
+async function waitForClosed(harness: SocketHarness, timeoutMs = 2_000): Promise<void> {
+ const deadline = Date.now() + timeoutMs
+ while (harness.socket.readyState !== WebSocket.CLOSED && Date.now() < deadline) {
+ await delay(10)
+ }
+ assert.equal(harness.socket.readyState, WebSocket.CLOSED, 'socket did not close after auth exhaustion')
+}
+
+async function closeAllSockets(): Promise<void> {
+ await Promise.allSettled([...openSockets].map(closeSocket))
+}
+
+async function seedDocumentFixture(viewerCount: number): Promise<DocumentFixture> {
+ const companyId = `ws-doc-company-${randomUUID().replace(/-/g, '').slice(0, 14)}`
+ const documentId = `doc_${randomUUID().replace(/-/g, '').slice(0, 16)}`
+ const users = [
+ ACTOR_ID,
+ ...Array.from(
+ { length: Math.max(0, viewerCount - 1) },
+ (_, index) => `a-ws-doc-viewer-${index}-${randomUUID().slice(0, 6)}`,
+ ),
+ ]
+ await pool.query(
+ `INSERT INTO companies (id, name, slug, owner_user_id)
+ VALUES ($1, 'WS document authorization', $2, $3)`,
+ [companyId, companyId, ACTOR_ID],
+ )
+ for (const userId of users) await seedUserMembership(userId, companyId)
+ await pool.query(
+ `UPDATE company_members
+ SET role = CASE WHEN user_id = $2 THEN 'owner' ELSE 'member' END
+ WHERE company_id = $1`,
+ [companyId, ACTOR_ID],
+ )
+ await pool.query(
+ `INSERT INTO documents (id, company_id, title, created_by)
+ VALUES ($1, $2, 'WS authorization fixture', $3)`,
+ [documentId, companyId, ACTOR_ID],
+ )
+ fixtureDocumentIds.add(documentId)
+ return { companyId, documentId, users }
+}
+
+async function beginUserLock(client: Client, userId: string): Promise<void> {
+ await client.query('BEGIN')
+ await client.query(
+ `SELECT id FROM users WHERE id = $1 FOR UPDATE`,
+ [userId],
+ )
+}
+
+async function revokeMembership(userId: string, companyId: string): Promise<void> {
+ const client = await pool.connect()
+ try {
+ await client.query('BEGIN')
+ await client.query(
+ `UPDATE participants
+ SET departed_at = NOW(), status = 'resting', status_updated_at = NOW()
+ WHERE id = $1 AND company_id = $2 AND kind = 'human'`,
+ [userId, companyId],
+ )
+ await client.query(
+ `DELETE FROM company_members WHERE company_id = $1 AND user_id = $2`,
+ [companyId, userId],
+ )
+ await client.query('COMMIT')
+ } catch (error) {
+ await client.query('ROLLBACK').catch(() => {})
+ throw error
+ } finally {
+ client.release()
+ }
+}
+
+async function emitAwareness(
+ fixture: DocumentFixture,
+ originId: string,
+ size = 32,
+): Promise<void> {
+ await broadcastAwareness(
+ fixture.documentId,
+ fixture.companyId,
+ originId,
+ new Uint8Array(size).fill(7),
+ )
+}
+
+async function deleteDocument(fixture: DocumentFixture): Promise<void> {
+ const response = await fetch(`${baseUrl}/api/documents/${fixture.documentId}`, {
+ method: 'DELETE',
+ headers: {
+ 'content-type': 'application/json',
+ 'x-company-id': fixture.companyId,
+ },
+ })
+ const body = await response.text()
+ assert.equal(response.status, 200, body)
+}
+
+before(async () => {
+ await ensureSchemaOnce()
+ const app = await buildApiTestApp(ACTOR_ID)
+ server = createServer(app)
+ wss = attachWebSocket(server)
+ await new Promise<void>((resolve) => {
+ server.listen(0, '127.0.0.1', () => {
+ const address = server.address()
+ assert.ok(address && typeof address === 'object')
+ baseUrl = `http://127.0.0.1:${address.port}`
+ wsUrl = `ws://127.0.0.1:${address.port}/ws`
+ resolve()
+ })
+ })
+})
+
+beforeEach(async () => {
+ await resetAllTables()
+})
+
+afterEach(() => {
+ // rooms.ts intentionally keeps empty rooms for a 60s reconnect grace
+ // period. Tests own these document ids, so evicting them here cancels those
+ // timers and keeps this focused integration file from holding the runner
+ // open for a full grace window.
+ for (const documentId of fixtureDocumentIds) evictDocumentRoom(documentId)
+ fixtureDocumentIds.clear()
+})
+
+after(async () => {
+ await closeAllSockets()
+ // Let the Redis workspace events emitted by the lock-order case finish
+ // their local fan-out before teardown closes the shared application pool.
+ await delay(250)
+ for (const socket of wss.clients) socket.terminate()
+ await new Promise<void>((resolve) => wss.close(() => resolve()))
+ await teardownAll(server)
+})
+
+test('a contended peer is detached without discarding a valid peer', async () => {
+ const fixture = await seedDocumentFixture(3)
+ const [actor, target, peer] = await Promise.all(
+ fixture.users.map((userId) => openDocSocket(userId, fixture.documentId)),
+ )
+ const barrier = new Client({ connectionString: databaseUrl() })
+ await barrier.connect()
+ try {
+ await beginUserLock(barrier, fixture.users[1]!)
+ const originId = `contended-${randomUUID()}`
+ const targetBefore = target.messages.length
+ const actorBefore = actor.messages.length
+ const peerBefore = peer.messages.length
+ const fanout = emitAwareness(fixture, originId)
+ await Promise.all([
+ waitForFrame(actor, (frame) => frame.type === 'doc.awareness' && frame.originId === originId, 'valid actor frame'),
+ waitForFrame(peer, (frame) => frame.type === 'doc.awareness' && frame.originId === originId, 'valid peer frame'),
+ ])
+ await fanout
+ await delay(100)
+ assert.ok(actor.messages.slice(actorBefore).some((frame) => frame.originId === originId))
+ assert.ok(peer.messages.slice(peerBefore).some((frame) => frame.originId === originId))
+ assert.equal(
+ target.messages.slice(targetBefore).some((frame) => frame.originId === originId),
+ false,
+ 'a NOWAIT-contended peer received a frame from the mixed batch',
+ )
+ assert.equal(actor.socket.readyState, WebSocket.OPEN, 'a valid actor was detached with the contended peer')
+ assert.equal(peer.socket.readyState, WebSocket.OPEN, 'a valid peer was detached with the contended peer')
+ await waitForClosed(target)
+ } finally {
+ await barrier.query('ROLLBACK').catch(() => {})
+ await barrier.end().catch(() => {})
+ await Promise.allSettled([actor, target, peer].map(closeSocket))
+ }
+})
+
+test('legacy subscribers retry contention without a forced disconnect', async () => {
+ const fixture = await seedDocumentFixture(2)
+ const actor = await openDocSocket(fixture.users[0]!, fixture.documentId)
+ const legacy = await openSocket(fixture.users[1]!)
+ // Omit replaySupported entirely: this is the pre-capability client shape.
+ await subscribeSocket(legacy, fixture.documentId, false, true)
+ const barrier = new Client({ connectionString: databaseUrl() })
+ await barrier.connect()
+ try {
+ await beginUserLock(barrier, fixture.users[1]!)
+ const originId = `legacy-contention-${randomUUID()}`
+ const fanout = emitAwareness(fixture, originId)
+ const local = new Y.Doc()
+ local.getText('content').insert(0, 'legacy optimistic edit')
+ const updateB64 = Buffer.from(Y.encodeStateAsUpdate(local)).toString('base64')
+ legacy.socket.send(JSON.stringify({
+ type: 'doc.update', documentId: fixture.documentId, updateB64,
+ }))
+ // The legacy path has a longer bounded NOWAIT retry window. Releasing
+ // inside it proves an old client survives ordinary row contention.
+ await delay(250)
+ await barrier.query('ROLLBACK')
+ await fanout
+ await waitForFrame(legacy, (frame) => frame.type === 'doc.awareness' && frame.originId === originId, 'legacy peer frame')
+ assert.equal(legacy.socket.readyState, WebSocket.OPEN)
+ assert.equal(actor.socket.readyState, WebSocket.OPEN)
+ const persistDeadline = Date.now() + 5_000
+ let persistedText = ''
+ while (Date.now() < persistDeadline && persistedText !== 'legacy optimistic edit') {
+ const { rows } = await pool.query<{ update_bytes: Buffer }>(
+ `SELECT update_bytes
+ FROM document_updates
+ WHERE document_id = $1 AND author_id = $2
+ ORDER BY id DESC LIMIT 1`,
+ [fixture.documentId, fixture.users[1]],
+ )
+ if (rows[0]) {
+ const persisted = new Y.Doc()
+ Y.applyUpdate(persisted, new Uint8Array(rows[0].update_bytes))
+ persistedText = persisted.getText('content').toString()
+ }
+ if (persistedText !== 'legacy optimistic edit') await delay(25)
+ }
+ assert.equal(persistedText, 'legacy optimistic edit', 'legacy optimistic update was lost during contention')
+ } finally {
+ await barrier.query('ROLLBACK').catch(() => {})
+ await barrier.end().catch(() => {})
+ await Promise.allSettled([actor, legacy].map(closeSocket))
+ }
+})
+
+test('revocation committed before a retried authorization prevents the queued send', async () => {
+ const fixture = await seedDocumentFixture(3)
+ const [actor, target, peer] = await Promise.all(
+ fixture.users.map((userId) => openDocSocket(userId, fixture.documentId)),
+ )
+ const barrier = new Client({ connectionString: databaseUrl() })
+ await barrier.connect()
+ try {
+ const beforeOrigin = `before-revoke-${randomUUID()}`
+ await emitAwareness(fixture, beforeOrigin)
+ await waitForFrame(target, (frame) => frame.type === 'doc.awareness' && frame.originId === beforeOrigin, 'pre-revoke frame')
+
+ // NOWAIT makes this a deterministic retry barrier: the outbound batch
+ // cannot lock this user, while the revoke transaction can commit because it
+ // changes the participant/membership rows rather than users.
+ await beginUserLock(barrier, fixture.users[1]!)
+ const afterOrigin = `after-revoke-${randomUUID()}`
+ const targetBefore = target.messages.length
+ const fanout = emitAwareness(fixture, afterOrigin)
+ await revokeMembership(fixture.users[1]!, fixture.companyId)
+ await barrier.query('ROLLBACK')
+ await fanout
+ await waitForFrame(peer, (frame) => frame.type === 'doc.awareness' && frame.originId === afterOrigin, 'valid peer after revoke')
+ await delay(100)
+ assert.equal(
+ target.messages.slice(targetBefore).some((frame) => frame.originId === afterOrigin),
+ false,
+ 'a queued send crossed a committed membership revoke',
+ )
+ } finally {
+ await barrier.query('ROLLBACK').catch(() => {})
+ await barrier.end().catch(() => {})
+ await Promise.allSettled([actor, target, peer].map(closeSocket))
+ }
+})
+
+test('a queued authorization item cannot newly deliver after document deletion commits', async () => {
+ const fixture = await seedDocumentFixture(3)
+ const [actor, target, peer] = await Promise.all(
+ fixture.users.map((userId) => openDocSocket(userId, fixture.documentId)),
+ )
+ const barrier = new Client({ connectionString: databaseUrl() })
+ await barrier.connect()
+ try {
+ // The users row is part of the live authorization lock set, while the
+ // document-delete transaction does not need that row. NOWAIT therefore
+ // keeps the exact marker queued/contended while deletion can commit.
+ await beginUserLock(barrier, fixture.users[1]!)
+ const originId = `queued-delete-${randomUUID()}`
+ const targetCursor = target.messages.length
+ const fanout = emitAwareness(fixture, originId)
+ // emitAwareness enqueues the local room item synchronously before its
+ // Redis publish await. The delete begins only after that item exists.
+ await deleteDocument(fixture)
+ const { rows } = await pool.query<{ count: string }>(
+ `SELECT COUNT(*)::text AS count FROM documents WHERE id = $1`,
+ [fixture.documentId],
+ )
+ assert.equal(rows[0]?.count, '0')
+ await barrier.query('ROLLBACK')
+ await fanout
+ await delay(200)
+ assert.equal(
+ target.messages.slice(targetCursor).some((frame) => frame.originId === originId),
+ false,
+ 'the queued target item delivered after document deletion committed',
+ )
+ // Any actor/peer frame that was authorized before the delete commit is
+ // allowed; this assertion deliberately says nothing about network arrival
+ // order for those already-authorized sends.
+ } finally {
+ await barrier.query('ROLLBACK').catch(() => {})
+ await barrier.end().catch(() => {})
+ await Promise.allSettled([actor, target, peer].map(closeSocket))
+ }
+})
+
+test('close and unsubscribe during blocked hydration do not leave active subscriptions', async () => {
+ const closeFixture = await seedDocumentFixture(1)
+ const closeSocketHarness = await openSocket(ACTOR_ID)
+ const observer = new Client({ connectionString: databaseUrl() })
+ const closeBarrier = new Client({ connectionString: databaseUrl() })
+ await observer.connect()
+ await closeBarrier.connect()
+ try {
+ await closeBarrier.query('BEGIN')
+ await closeBarrier.query('LOCK TABLE document_snapshots IN ACCESS EXCLUSIVE MODE')
+ const closeCursor = closeSocketHarness.messages.length
+ closeSocketHarness.socket.send(JSON.stringify({ type: 'doc.subscribe', documentId: closeFixture.documentId }))
+ await waitForBlockedQuery(observer, '%FROM document_snapshots%')
+ await closeSocket(closeSocketHarness)
+ await closeBarrier.query('COMMIT')
+ await delay(150)
+ assert.equal(
+ closeSocketHarness.messages.slice(closeCursor).some((frame) => frame.type === 'doc.sync'),
+ false,
+ 'closed socket completed a blocked subscription',
+ )
+ } finally {
+ await closeBarrier.query('ROLLBACK').catch(() => {})
+ await closeBarrier.end().catch(() => {})
+ await observer.end().catch(() => {})
+ await closeSocket(closeSocketHarness)
+ }
+
+ const unsubscribeFixture = await seedDocumentFixture(1)
+ const unsubscribeSocket = await openSocket(ACTOR_ID)
+ const unsubscribeBarrier = new Client({ connectionString: databaseUrl() })
+ const unsubscribeObserver = new Client({ connectionString: databaseUrl() })
+ await unsubscribeBarrier.connect()
+ await unsubscribeObserver.connect()
+ try {
+ await unsubscribeBarrier.query('BEGIN')
+ await unsubscribeBarrier.query('LOCK TABLE document_snapshots IN ACCESS EXCLUSIVE MODE')
+ unsubscribeSocket.socket.send(JSON.stringify({ type: 'doc.subscribe', documentId: unsubscribeFixture.documentId }))
+ await waitForBlockedQuery(unsubscribeObserver, '%FROM document_snapshots%')
+ // FIFO handling must run this only after the blocked subscribe finishes.
+ unsubscribeSocket.socket.send(JSON.stringify({ type: 'doc.unsubscribe', documentId: unsubscribeFixture.documentId }))
+ await unsubscribeBarrier.query('COMMIT')
+
+ // A second subscribe proves the queued unsubscribe actually ran. The
+ // first sync may be dropped legitimately: FIFO can run the queued
+ // unsubscribe immediately after hydration, before the sync's outbound
+ // authorization batch gets its turn.
+ unsubscribeSocket.socket.send(JSON.stringify({ type: 'doc.subscribe', documentId: unsubscribeFixture.documentId }))
+ await waitForFrame(
+ unsubscribeSocket,
+ (frame) => frame.type === 'doc.sync' && frame.documentId === unsubscribeFixture.documentId,
+ 'second sync after queued unsubscribe',
+ )
+ unsubscribeSocket.socket.send(JSON.stringify({ type: 'doc.unsubscribe', documentId: unsubscribeFixture.documentId }))
+ await delay(50)
+ const originId = `after-unsubscribe-${randomUUID()}`
+ const cursor = unsubscribeSocket.messages.length
+ await emitAwareness(unsubscribeFixture, originId)
+ await delay(200)
+ assert.equal(
+ unsubscribeSocket.messages.slice(cursor).some((frame) => frame.originId === originId),
+ false,
+ 'queued unsubscribe left an active room subscription',
+ )
+ } finally {
+ await unsubscribeBarrier.query('ROLLBACK').catch(() => {})
+ await unsubscribeBarrier.end().catch(() => {})
+ await unsubscribeObserver.end().catch(() => {})
+ await closeSocket(unsubscribeSocket)
+ }
+})
+
+test('opposite actor/recipient lock pressure completes without deadlock', async () => {
+ const fixture = await seedDocumentFixture(3)
+ const target = fixture.users[1]!
+ const sockets = await Promise.all(fixture.users.map((userId) => openDocSocket(userId, fixture.documentId)))
+ const observer = new Client({ connectionString: databaseUrl() })
+ const barrier = new Client({ connectionString: databaseUrl() })
+ await observer.connect()
+ await barrier.connect()
+ try {
+ // The actor is deliberately lexically after the recipient. The API path
+ // locks actor membership first, then recipient participant; the fan-out
+ // query sees the same rows in its recipient set. NOWAIT + per-item retry
+ // must make this a bounded contention case, never a deadlock.
+ await barrier.query('BEGIN')
+ await barrier.query(
+ `SELECT id FROM participants WHERE id = $1 AND company_id = $2 FOR UPDATE`,
+ [target, fixture.companyId],
+ )
+ const removePromise = fetch(`${baseUrl}/api/companies/${fixture.companyId}/members/${target}`, {
+ method: 'DELETE',
+ headers: {
+ 'content-type': 'application/json',
+ 'x-company-id': fixture.companyId,
+ },
+ })
+ await waitForBlockedQuery(observer, '%FROM participants%FOR UPDATE%')
+ const originId = `lock-order-${randomUUID()}`
+ const fanoutPromise = emitAwareness(fixture, originId)
+ await barrier.query('COMMIT')
+ const [removeResponse] = await within(Promise.all([removePromise, fanoutPromise]), 'actor/recipient lock-order completion')
+ const body = await removeResponse.text()
+ assert.equal(removeResponse.status, 200, body)
+ // Valid-peer survival under a mixed contended batch is covered above. This
+ // case intentionally focuses on the opposing actor/recipient lock order:
+ // both operations must complete, even if NOWAIT causes this fan-out item
+ // to be dropped while the revoke owns the participant lock.
+ } finally {
+ await barrier.query('ROLLBACK').catch(() => {})
+ await barrier.end().catch(() => {})
+ await observer.end().catch(() => {})
+ await Promise.allSettled(sockets.map(closeSocket))
+ }
+})
diff --git a/server/src/__integration__/ws-doc-fanout.test.ts b/server/src/__integration__/ws-doc-fanout.test.ts
new file mode 100644
index 0000000..2e2c524
--- /dev/null
+++ b/server/src/__integration__/ws-doc-fanout.test.ts
@@ -0,0 +1,243 @@
+import assert from 'node:assert/strict'
+import { randomUUID } from 'node:crypto'
+import { createServer, type Server } from 'node:http'
+import { after, before, beforeEach, test } from 'node:test'
+import { setTimeout as delay } from 'node:timers/promises'
+import { Client } from 'pg'
+import WebSocket from 'ws'
+import * as Y from 'yjs'
+import { createWsTicket } from '../auth.js'
+import { broadcastAwareness as docBroadcastAwareness } from '../documents/rooms.js'
+import { attachWebSocket } from '../ws.js'
+import { pool } from '../db/pool.js'
+import {
+ ensureSchemaOnce, resetAllTables, seedUserMembership, teardownAll,
+} from './_helpers.js'
+
+interface SocketHarness {
+ socket: WebSocket
+ messages: Array<Record<string, unknown>>
+ next: (predicate: (message: Record<string, unknown>) => boolean, timeoutMs?: number) => Promise<Record<string, unknown>>
+}
+
+const USER_COUNT = 20
+let server: Server
+let wsUrl = ''
+let wss: ReturnType<typeof attachWebSocket>
+
+async function withTimeout<T>(promise: Promise<T>, label: string, timeoutMs = 2_000): Promise<T> {
+ let timer: ReturnType<typeof setTimeout> | undefined
+ void promise.catch(() => {})
+ try {
+ return await Promise.race([
+ promise,
+ new Promise<T>((_resolve, reject) => {
+ timer = setTimeout(() => reject(new Error(`timed out waiting for ${label}`)), timeoutMs)
+ }),
+ ])
+ } finally {
+ if (timer) clearTimeout(timer)
+ }
+}
+
+function waitForMessage(socket: WebSocket, messages: Array<Record<string, unknown>>, predicate: (message: Record<string, unknown>) => boolean, timeoutMs = 5_000): Promise<Record<string, unknown>> {
+ const existing = messages.find(predicate)
+ if (existing) return Promise.resolve(existing)
+ return new Promise((resolve, reject) => {
+ const timer = setTimeout(() => reject(new Error('timed out waiting for document frame')), timeoutMs)
+ const onMessage = (raw: WebSocket.RawData) => {
+ let message: Record<string, unknown>
+ try { message = JSON.parse(raw.toString()) as Record<string, unknown> } catch { return }
+ messages.push(message)
+ if (!predicate(message)) return
+ clearTimeout(timer)
+ socket.off('message', onMessage)
+ resolve(message)
+ }
+ socket.on('message', onMessage)
+ })
+}
+
+async function openDocSocket(userId: string, documentId: string): Promise<SocketHarness> {
+ const { ticket } = await createWsTicket(userId)
+ const socket = new WebSocket(`${wsUrl}?t=${encodeURIComponent(ticket)}`)
+ const messages: Array<Record<string, unknown>> = []
+ socket.on('message', (raw: WebSocket.RawData) => {
+ try { messages.push(JSON.parse(raw.toString()) as Record<string, unknown>) } catch { /* ignore */ }
+ })
+ await new Promise<void>((resolve, reject) => {
+ socket.once('open', () => resolve())
+ socket.once('error', reject)
+ })
+ const next = (predicate: (message: Record<string, unknown>) => boolean, timeoutMs = 5_000) =>
+ waitForMessage(socket, messages, predicate, timeoutMs)
+ await next((message) => message.type === 'hello')
+ socket.send(JSON.stringify({ type: 'doc.subscribe', documentId, replaySupported: true }))
+ await next((message) => message.type === 'doc.sync' && message.documentId === documentId)
+ return { socket, messages, next }
+}
+
+async function closeSocket(harness: SocketHarness): Promise<void> {
+ if (harness.socket.readyState === WebSocket.CLOSED) return
+ await new Promise<void>((resolve) => {
+ harness.socket.once('close', () => resolve())
+ harness.socket.close()
+ })
+}
+
+beforeEach(async () => {
+ await resetAllTables()
+})
+
+before(async () => {
+ await ensureSchemaOnce()
+ server = createServer()
+ wss = attachWebSocket(server)
+ await new Promise<void>((resolve) => {
+ server.listen(0, '127.0.0.1', () => {
+ const address = server.address()
+ if (!address || typeof address === 'string') throw new Error('WS test server did not bind')
+ wsUrl = `ws://127.0.0.1:${address.port}/ws`
+ resolve()
+ })
+ })
+})
+
+after(async () => {
+ await new Promise<void>((resolve) => wss.close(() => resolve()))
+ // onHumanDisconnect publishes presence asynchronously; let those callbacks
+ // finish before teardown closes the shared pool used by the Redis fan-out.
+ await delay(250)
+ await teardownAll(server)
+})
+
+test('20-user document fan-out batches auth work and preserves immediate revoke', async () => {
+ const companyId = `ws-doc-company-${randomUUID().slice(0, 8)}`
+ const documentId = `doc_${randomUUID().replace(/-/g, '').slice(0, 16)}`
+ const users = Array.from({ length: USER_COUNT }, (_, index) => `ws-doc-user-${index}-${randomUUID().slice(0, 6)}`)
+ await pool.query(
+ `INSERT INTO companies (id, name, slug, owner_user_id)
+ VALUES ($1, 'WS document fan-out', $2, $3)`,
+ [companyId, companyId, users[0]],
+ )
+ for (const userId of users) await seedUserMembership(userId, companyId)
+ await pool.query(
+ `INSERT INTO documents (id, company_id, title, created_by)
+ VALUES ($1, $2, 'WS fan-out', $3)`,
+ [documentId, companyId, users[0]],
+ )
+
+ const sockets = await Promise.all(users.map((userId) => openDocSocket(userId, documentId)))
+ try {
+ const local = new Y.Doc()
+ local.getText('content').insert(0, 'first update')
+ sockets[0].socket.send(JSON.stringify({
+ type: 'doc.update', documentId,
+ updateB64: Buffer.from(Y.encodeStateAsUpdate(local)).toString('base64'),
+ }))
+ await Promise.all(sockets.slice(1).map((harness) =>
+ harness.next((message) => message.type === 'doc.update' && message.documentId === documentId)))
+
+ // Direct room emission bypasses inbound auth and makes the outbound pool
+ // budget observable while the document rows are locked. A relation lock is
+ // deliberate: NOWAIT only changes tuple-lock handling, while this forces
+ // the real outbound authorization SELECT into pg_stat_activity's Lock wait
+ // state for both the old per-viewer path and the new batched path.
+ const databaseUrl = process.env.INTEGRATION_DATABASE_URL ?? process.env.DATABASE_URL
+ assert.ok(databaseUrl)
+ const barrier = new Client({ connectionString: databaseUrl })
+ const observer = new Client({ connectionString: databaseUrl })
+ await barrier.connect()
+ await observer.connect()
+ try {
+ await barrier.query('BEGIN')
+ await barrier.query('LOCK TABLE documents IN ACCESS EXCLUSIVE MODE')
+ const budgetOrigin = `budget-${randomUUID()}`
+ const budgetFanout = docBroadcastAwareness(documentId, companyId, budgetOrigin, new Uint8Array([1, 2, 3, 4]))
+ const { rows: observerPidRows } = await observer.query<{ pid: number }>('SELECT pg_backend_pid() AS pid')
+ const observerPid = observerPidRows[0]?.pid
+ assert.ok(observerPid, 'observer must expose a PostgreSQL backend pid')
+ let maximumBusy = 0
+ let observedAuthWait = false
+ const deadline = Date.now() + 5_000
+ while (Date.now() < deadline) {
+ const { rows } = await observer.query<{ count: number }>(
+ `SELECT COUNT(*)::int AS count
+ FROM pg_stat_activity
+ WHERE datname = current_database()
+ AND pid <> $1
+ AND state <> 'idle'
+ AND wait_event_type = 'Lock'
+ AND query ILIKE '%FROM documents%'
+ AND query ILIKE '%JOIN company_members cm%'
+ AND query ILIKE '%FOR SHARE%'`,
+ [observerPid],
+ )
+ const waitingAuth = rows[0]?.count ?? 0
+ if (waitingAuth > 0) observedAuthWait = true
+ maximumBusy = Math.max(maximumBusy, pool.totalCount - pool.idleCount)
+ if (observedAuthWait && maximumBusy > 4) break
+ await delay(10)
+ }
+ assert.equal(observedAuthWait, true, 'never observed a real outbound authorization query waiting on the document lock')
+ assert.ok(maximumBusy <= 4, `document auth exceeded the global semaphore bound: ${maximumBusy}`)
+ await withTimeout(pool.query('SELECT 1'), 'a new application-pool query while auth is locked')
+ await barrier.query('COMMIT')
+ await budgetFanout
+ await Promise.all(sockets.map((harness) =>
+ harness.next((message) => message.type === 'doc.awareness'
+ && message.documentId === documentId
+ && message.originId === budgetOrigin)))
+ } finally {
+ await barrier.query('ROLLBACK').catch(() => {})
+ await barrier.end().catch(() => {})
+ await observer.end().catch(() => {})
+ }
+
+ const revoked = sockets[1]
+ const revokedBefore = revoked.messages.length
+ await pool.query(
+ `UPDATE participants SET departed_at = NOW() WHERE id = $1 AND company_id = $2`,
+ [users[1], companyId],
+ )
+ const next = new Y.Doc()
+ next.getText('content').insert(0, 'after revoke marker')
+ const revokedUpdateB64 = Buffer.from(Y.encodeStateAsUpdate(next)).toString('base64')
+ sockets[0].socket.send(JSON.stringify({
+ type: 'doc.update', documentId,
+ updateB64: revokedUpdateB64,
+ }))
+ await Promise.all(sockets.slice(2).map((harness) =>
+ harness.next((message) => message.type === 'doc.update'
+ && message.documentId === documentId
+ && message.updateB64 === revokedUpdateB64)))
+ await delay(150)
+ assert.equal(
+ revoked.messages.slice(revokedBefore).some((message) =>
+ message.type === 'doc.update' && message.updateB64 === revokedUpdateB64),
+ false,
+ 'revoked subscriber received a post-commit document frame',
+ )
+
+ const fifoTarget = sockets[2]
+ const beforeFifo = await pool.query<{ count: number }>(
+ `SELECT COUNT(*)::int AS count FROM document_updates WHERE document_id = $1 AND author_id = $2`,
+ [documentId, users[2]],
+ )
+ fifoTarget.socket.send(JSON.stringify({ type: 'doc.unsubscribe', documentId }))
+ const fifoUpdate = new Y.Doc()
+ fifoUpdate.getText('content').insert(0, 'must not pass unsubscribe')
+ fifoTarget.socket.send(JSON.stringify({
+ type: 'doc.update', documentId,
+ updateB64: Buffer.from(Y.encodeStateAsUpdate(fifoUpdate)).toString('base64'),
+ }))
+ await delay(200)
+ const afterFifo = await pool.query<{ count: number }>(
+ `SELECT COUNT(*)::int AS count FROM document_updates WHERE document_id = $1 AND author_id = $2`,
+ [documentId, users[2]],
+ )
+ assert.equal(afterFifo.rows[0]?.count, beforeFifo.rows[0]?.count, 'unsubscribe/update order was not FIFO')
+ } finally {
+ await Promise.all(sockets.map(closeSocket))
+ }
+})
diff --git a/server/src/ws.ts b/server/src/ws.ts
index 7ea0c68..d629a57 100644
--- a/server/src/ws.ts
+++ b/server/src/ws.ts
@@ -23,6 +23,7 @@ import {
broadcastAwareness as docBroadcastAwareness,
type DocSubscriber,
} from './documents/rooms.js'
+import { Semaphore } from './concurrency.js'
import { randomUUID } from 'node:crypto'
interface AuthedSocket {
@@ -36,6 +37,12 @@ interface AuthedSocket {
companies: Set<string>
/** Active doc subscriptions on this socket. Released on close. */
docSubs: Map<string, DocSubscriber>
+ /** Document protocol frames are handled FIFO per socket. This keeps an
+ * async subscribe/hydration from racing a later unsubscribe or update. */
+ docFrameQueue: Promise<void>
+ pendingDocFrames: number
+ pendingDocBytes: number
+ closed: boolean
/** Heartbeat liveness flag. Set true on every received pong; the periodic
* ping loop flips it to false right before sending the next ping. If the
* next round still sees false, the socket is half-open and we terminate
@@ -58,6 +65,39 @@ const redisFanoutQueues = new Map<string, Promise<void>>()
const WS_MAX_BUFFERED_BYTES = 2 * 1024 * 1024 // 2 MB
const WS_TERMINATE_BUFFERED_BYTES = 8 * 1024 * 1024 // 8 MB
const DOC_SYNC_MAX_BYTES = 32 * 1024 * 1024 // bounded one-shot snapshot
+const DOC_AUTH_CONCURRENCY = 4
+const DOC_AUTH_MAX_PENDING_FRAMES = 512
+const DOC_AUTH_MAX_PENDING_BYTES = 64 * 1024 * 1024
+const DOC_AUTH_MAX_BATCH_FRAMES = 64
+const DOC_AUTH_MAX_BATCH_BYTES = 512 * 1024
+const DOC_AUTH_LOCK_RETRY_LIMIT = 2
+// Keep legacy clients inside the same bounded window as pool.ts's 60s
+// statement timeout. New clients use the short reconnect-safe retry window.
+const DOC_AUTH_LEGACY_DEADLINE_MS = 60_000
+const DOC_AUTH_RETRY_DELAY_MS = 50
+
+/** Authorization is deliberately below the pg pool size. Admission is
+ * bounded separately because Semaphore itself has an unbounded waiter list. */
+const docAuthSemaphore = new Semaphore(DOC_AUTH_CONCURRENCY)
+const docReplaySupport = new WeakMap<DocSubscriber, boolean>()
+let pendingDocAuthFrames = 0
+let pendingDocAuthBytes = 0
+
+function reserveDocAuth(bytes: number): boolean {
+ const bounded = Math.max(1, bytes)
+ if (
+ pendingDocAuthFrames >= DOC_AUTH_MAX_PENDING_FRAMES
+ || pendingDocAuthBytes + bounded > DOC_AUTH_MAX_PENDING_BYTES
+ ) return false
+ pendingDocAuthFrames++
+ pendingDocAuthBytes += bounded
+ return true
+}
+
+function releaseDocAuth(bytes: number): void {
+ pendingDocAuthFrames = Math.max(0, pendingDocAuthFrames - 1)
+ pendingDocAuthBytes = Math.max(0, pendingDocAuthBytes - Math.max(1, bytes))
+}
/** Open WS connections per user. Drives real human presence:
* - 0 → 1 : user is now online, flip participant status to 'avail'.
@@ -267,108 +307,441 @@ export async function resolveWsEventRecipientUserIds(
* Returns null when the doc doesn't exist OR the caller can't see it —
* same opaque posture the chat handlers use to avoid leaking existence. */
async function docCompanyFor(documentId: string, userId: string): Promise<string | null> {
- const { rows } = await pool.query<{ company_id: string }>(
- `SELECT d.company_id
- FROM documents d
- JOIN company_members m ON m.company_id = d.company_id AND m.user_id = $2
- JOIN users u ON u.id = m.user_id AND u.deleted_at IS NULL
- JOIN participants p
- ON p.id = m.user_id
- AND p.company_id = d.company_id
- AND p.kind = 'human'
- AND p.departed_at IS NULL
- WHERE d.id = $1
- LIMIT 1`,
- [documentId, userId],
- )
- return rows[0]?.company_id ?? null
-}
-
-/** Deliver one document frame while holding share locks on every row whose
- * mutation can revoke access. A concurrent delete/offboard waits until the
- * synchronous ws.send has happened; once revocation commits, the next lookup
- * fails closed and detaches the stale room subscription. */
-async function sendAuthorizedDocFrame(
- c: AuthedSocket,
- documentId: string,
- subRec: DocSubscriber,
- payload: unknown,
-): Promise<boolean> {
- const client = await pool.connect()
- try {
- await client.query('BEGIN')
- const authorized = await client.query(
- `SELECT d.id
+ return docAuthSemaphore.run(async () => {
+ const { rows } = await pool.query<{ company_id: string }>(
+ `SELECT d.company_id
FROM documents d
- JOIN company_members cm ON cm.company_id = d.company_id AND cm.user_id = $2
- JOIN users u ON u.id = cm.user_id AND u.deleted_at IS NULL
+ JOIN company_members m ON m.company_id = d.company_id AND m.user_id = $2
+ JOIN users u ON u.id = m.user_id AND u.deleted_at IS NULL
JOIN participants p
- ON p.id = cm.user_id
+ ON p.id = m.user_id
AND p.company_id = d.company_id
AND p.kind = 'human'
AND p.departed_at IS NULL
WHERE d.id = $1
- FOR SHARE OF d, cm, u, p`,
- [documentId, c.userId],
+ LIMIT 1`,
+ [documentId, userId],
)
- if (!authorized.rowCount || c.docSubs.get(documentId) !== subRec) {
- await client.query('ROLLBACK')
- detachDocSubscription(c, documentId, subRec)
- return false
+ return rows[0]?.company_id ?? null
+ })
+}
+
+interface DocFanoutItem {
+ c: AuthedSocket
+ documentId: string
+ subRec: DocSubscriber
+ payload: string
+ bytes: number
+ replaySupported: boolean
+ released: boolean
+ onDone?: () => void
+}
+
+interface DocFanoutQueue {
+ items: DocFanoutItem[]
+ running: boolean
+ scheduled: boolean
+}
+
+const docFanoutQueues = new Map<string, DocFanoutQueue>()
+
+function isLockNotAvailable(error: unknown): boolean {
+ const code = (error as { code?: unknown } | null)?.code
+ return code === '55P03' || code === '40P01'
+}
+
+function isTransientDocAuthError(error: unknown): boolean {
+ if (isLockNotAvailable(error)) return true
+ const message = error instanceof Error ? error.message : String(error)
+ return /timeout|ECONNREFUSED|ECONNRESET|connection|terminated|EOF/i.test(message)
+}
+
+function detachAndTerminate(item: DocFanoutItem): void {
+ const current = item.c.docSubs.get(item.documentId) === item.subRec
+ detachDocSubscription(item.c, item.documentId, item.subRec)
+ if (current && !item.c.closed) {
+ try { item.c.ws.terminate() } catch { /* ignore */ }
+ }
+}
+
+function itemIsCurrent(item: DocFanoutItem): boolean {
+ const { c, documentId, subRec } = item
+ return !c.closed
+ && c.docSubs.get(documentId) === subRec
+ && c.ws.readyState === c.ws.OPEN
+}
+
+function itemIsLive(item: DocFanoutItem): boolean {
+ return itemIsCurrent(item) && item.c.ws.bufferedAmount <= WS_MAX_BUFFERED_BYTES
+}
+
+function sendSerialized(ws: WebSocket, payload: string): boolean {
+ if (ws.readyState !== ws.OPEN) return false
+ try {
+ ws.send(payload)
+ return true
+ } catch {
+ return false
+ }
+}
+
+function finalizeDocFanoutItem(item: DocFanoutItem): void {
+ if (item.released) return
+ item.released = true
+ item.onDone?.()
+ releaseDocAuth(item.bytes)
+}
+
+/** Authorize one item after a contended batch has been split. The semaphore
+ * is acquired here only after the batch transaction has released its permit. */
+type SingleDocAuthOutcome = 'sent' | 'revoked' | 'busy' | 'failed'
+
+async function sendAuthorizedDocFrame(item: DocFanoutItem): Promise<SingleDocAuthOutcome> {
+ let sideEffectStarted = false
+ if (!itemIsCurrent(item)) return 'failed'
+ return docAuthSemaphore.run(async () => {
+ if (!itemIsCurrent(item)) return 'failed'
+ const client = await pool.connect()
+ try {
+ if (!itemIsCurrent(item)) return 'failed'
+ await client.query('BEGIN')
+ const authorized = await client.query(
+ `SELECT d.id
+ FROM documents d
+ JOIN company_members cm ON cm.company_id = d.company_id AND cm.user_id = $2
+ JOIN users u ON u.id = cm.user_id AND u.deleted_at IS NULL
+ JOIN participants p
+ ON p.id = cm.user_id
+ AND p.company_id = d.company_id
+ AND p.kind = 'human'
+ AND p.departed_at IS NULL
+ WHERE d.id = $1
+ FOR SHARE OF d, cm, u, p NOWAIT`,
+ [item.documentId, item.c.userId],
+ )
+ if (!authorized.rowCount) {
+ await client.query('ROLLBACK')
+ detachDocSubscription(item.c, item.documentId, item.subRec)
+ return 'revoked'
+ }
+ if (!itemIsLive(item)) {
+ await client.query('ROLLBACK')
+ detachAndTerminate(item)
+ return 'failed'
+ }
+ sideEffectStarted = true
+ if (!sendSerialized(item.c.ws, item.payload)) {
+ await client.query('ROLLBACK')
+ detachAndTerminate(item)
+ return 'failed'
+ }
+ await client.query('COMMIT')
+ return 'sent'
+ } catch (error) {
+ await client.query('ROLLBACK').catch(() => {})
+ if (!sideEffectStarted && isTransientDocAuthError(error)) return 'busy'
+ throw error
+ } finally {
+ client.release()
}
- if (c.ws.readyState !== c.ws.OPEN || c.ws.bufferedAmount > WS_MAX_BUFFERED_BYTES) {
- await client.query('ROLLBACK')
- detachDocSubscription(c, documentId, subRec)
- try { c.ws.terminate() } catch { /* ignore */ }
+ }).catch((error) => {
+ console.warn(`[ws] document authorization lookup failed for ${item.documentId}`, error)
+ if (sideEffectStarted) {
+ detachAndTerminate(item)
+ return 'failed' as const
+ }
+ if (isTransientDocAuthError(error)) return 'busy' as const
+ detachAndTerminate(item)
+ return 'failed' as const
+ })
+}
+
+interface DocBatchResult {
+ contended: boolean
+ fallback: DocFanoutItem[]
+}
+
+/** Authorize all distinct recipients for one document in one transaction.
+ * Invalid recipients are detached individually; they never discard valid
+ * peers in the same frame batch. NOWAIT keeps a writer from pinning every
+ * recipient behind one lock; the caller retries, then splits the batch. */
+async function authorizeDocBatch(items: DocFanoutItem[]): Promise<DocBatchResult> {
+ const initial = items.filter((item) => itemIsCurrent(item))
+ if (initial.length === 0) return { contended: false, fallback: [] }
+ return docAuthSemaphore.run(async () => {
+ if (!initial.some((item) => itemIsCurrent(item))) return { contended: false, fallback: [] }
+ const client = await pool.connect()
+ let sideEffectStarted = false
+ let eligible: DocFanoutItem[] = []
+ try {
+ eligible = initial.filter((item) => itemIsCurrent(item))
+ if (eligible.length === 0) return { contended: false, fallback: [] }
+ await client.query('BEGIN')
+ const userIds = [...new Set(eligible.map((item) => item.c.userId))]
+ const { rows } = await client.query<{ user_id: string }>(
+ `SELECT cm.user_id
+ FROM documents d
+ JOIN company_members cm
+ ON cm.company_id = d.company_id
+ AND cm.user_id = ANY($2::text[])
+ JOIN users u ON u.id = cm.user_id AND u.deleted_at IS NULL
+ JOIN participants p
+ ON p.id = cm.user_id
+ AND p.company_id = d.company_id
+ AND p.kind = 'human'
+ AND p.departed_at IS NULL
+ WHERE d.id = $1
+ FOR SHARE OF d, cm, u, p NOWAIT`,
+ [eligible[0]?.documentId, userIds],
+ )
+ const authorized = new Set(rows.map((row) => row.user_id))
+ for (const item of eligible) {
+ if (!authorized.has(item.c.userId)) {
+ detachDocSubscription(item.c, item.documentId, item.subRec)
+ continue
+ }
+ if (!itemIsLive(item)) {
+ detachAndTerminate(item)
+ continue
+ }
+ // The lock is held until COMMIT, immediately after this synchronous
+ // send. A revocation cannot commit between auth and delivery.
+ sideEffectStarted = true
+ if (!sendSerialized(item.c.ws, item.payload)) detachAndTerminate(item)
+ }
+ await client.query('COMMIT')
+ return { contended: false, fallback: [] }
+ } catch (error) {
+ await client.query('ROLLBACK').catch(() => {})
+ if (!sideEffectStarted && isTransientDocAuthError(error)) return { contended: true, fallback: eligible }
+ for (const item of eligible) {
+ detachAndTerminate(item)
+ }
+ console.warn(`[ws] document authorization batch failed for ${items[0]?.documentId ?? 'unknown'}`, error)
+ return { contended: false, fallback: [] }
+ } finally {
+ client.release()
+ }
+ })
+}
+
+async function processDocBatch(items: DocFanoutItem[]): Promise<void> {
+ const active = items.filter((item) => {
+ if (!itemIsCurrent(item)) return false
+ if (item.c.ws.bufferedAmount > WS_MAX_BUFFERED_BYTES) {
+ detachAndTerminate(item)
return false
}
- sendJson(c.ws, payload)
- await client.query('COMMIT')
return true
+ })
+ try {
+ if (active.length === 0) return
+ let result: DocBatchResult = { contended: true, fallback: active }
+ for (let attempt = 0; attempt <= DOC_AUTH_LOCK_RETRY_LIMIT && result.contended; attempt++) {
+ result = await authorizeDocBatch(active)
+ if (result.contended && attempt < DOC_AUTH_LOCK_RETRY_LIMIT) {
+ await new Promise((resolve) => setTimeout(resolve, 5 * (attempt + 1)))
+ }
+ }
+ if (!result.contended) return
+ // The batch permit and client have been released before this split. Each
+ // item gets an independent NOWAIT authorization so a contended/revoked
+ // peer cannot discard healthy peers or deadlock through nested acquisition.
+ const groups = new Map<DocSubscriber, DocFanoutItem[]>()
+ for (const item of result.fallback) {
+ const group = groups.get(item.subRec) ?? []
+ group.push(item)
+ groups.set(item.subRec, group)
+ }
+ // Different subscribers can make progress in parallel (the semaphore
+ // still caps DB work), but each subscriber's frames remain FIFO.
+ await Promise.all([...groups.values()].map(async (group) => {
+ const item = group[0]!
+ const deadline = Date.now() + (item.replaySupported
+ ? DOC_AUTH_RETRY_DELAY_MS * (DOC_AUTH_LOCK_RETRY_LIMIT + 1)
+ : DOC_AUTH_LEGACY_DEADLINE_MS)
+ for (const current of group) {
+ let outcome: SingleDocAuthOutcome = 'busy'
+ let attempt = 0
+ while (outcome === 'busy') {
+ outcome = await sendAuthorizedDocFrame(current)
+ if (outcome === 'busy') {
+ const remaining = deadline - Date.now()
+ if (remaining <= 0) break
+ const backoff = item.replaySupported
+ ? 5 * (attempt + 1)
+ : Math.min(DOC_AUTH_RETRY_DELAY_MS * (attempt + 1), 1_000)
+ await new Promise((resolve) => setTimeout(resolve, Math.min(backoff, remaining)))
+ attempt++
+ }
+ }
+ if (outcome === 'busy') detachAndTerminate(current)
+ }
+ }))
} catch (error) {
- await client.query('ROLLBACK').catch(() => {})
- throw error
+ console.warn(`[ws] document authorization batch failed for ${items[0]?.documentId ?? 'unknown'}`, error)
+ for (const item of items) detachAndTerminate(item)
} finally {
- client.release()
+ for (const item of items) finalizeDocFanoutItem(item)
+ }
+}
+
+function scheduleDocFanout(documentId: string): void {
+ const queue = docFanoutQueues.get(documentId)
+ if (!queue || queue.scheduled || queue.running) return
+ queue.scheduled = true
+ queueMicrotask(() => {
+ queue.scheduled = false
+ void drainDocFanout(documentId, queue)
+ })
+}
+
+async function drainDocFanout(documentId: string, queue: DocFanoutQueue): Promise<void> {
+ if (queue.running) return
+ queue.running = true
+ try {
+ while (queue.items.length > 0) {
+ const batch: DocFanoutItem[] = []
+ let bytes = 0
+ while (queue.items.length > 0 && batch.length < DOC_AUTH_MAX_BATCH_FRAMES) {
+ const next = queue.items[0]!
+ if (batch.length > 0 && bytes + next.bytes > DOC_AUTH_MAX_BATCH_BYTES) break
+ queue.items.shift()
+ batch.push(next)
+ bytes += next.bytes
+ }
+ await processDocBatch(batch)
+ }
+ } catch (error) {
+ console.warn(`[ws] document fan-out failed for ${documentId}`, error)
+ for (const item of queue.items.splice(0)) {
+ detachDocSubscription(item.c, item.documentId, item.subRec)
+ finalizeDocFanoutItem(item)
+ }
+ } finally {
+ queue.running = false
+ if (queue.items.length > 0) scheduleDocFanout(documentId)
+ else if (docFanoutQueues.get(documentId) === queue) docFanoutQueues.delete(documentId)
}
}
+function removeQueuedDocItems(c: AuthedSocket): void {
+ for (const [documentId, queue] of docFanoutQueues) {
+ const retained: DocFanoutItem[] = []
+ for (const item of queue.items) {
+ if (item.c === c) finalizeDocFanoutItem(item)
+ else retained.push(item)
+ }
+ queue.items = retained
+ if (!queue.running && !queue.scheduled && queue.items.length === 0) {
+ docFanoutQueues.delete(documentId)
+ }
+ }
+}
+
+function enqueueAuthorizedDocFrame(
+ c: AuthedSocket,
+ documentId: string,
+ subRec: DocSubscriber,
+ payload: unknown,
+ byteLength: number,
+ replaySupported: boolean,
+ onDone?: () => void,
+): void {
+ if (c.closed || c.docSubs.get(documentId) !== subRec) {
+ onDone?.()
+ return
+ }
+ const serialized = JSON.stringify(payload)
+ const bytes = Math.max(1, Buffer.byteLength(serialized))
+ if (!reserveDocAuth(bytes)) {
+ const rejected: DocFanoutItem = {
+ c, documentId, subRec, payload: serialized, bytes, replaySupported, released: true, onDone,
+ }
+ onDone?.()
+ detachAndTerminate(rejected)
+ return
+ }
+ // byteLength remains an explicit argument at call sites so a future caller
+ // cannot accidentally omit payload-size admission when its binary source is
+ // not yet serialized. The serialized size is the bound used for memory.
+ void byteLength
+ const item: DocFanoutItem = {
+ c, documentId, subRec, payload: serialized, bytes, replaySupported, released: false, onDone,
+ }
+ let queue = docFanoutQueues.get(documentId)
+ if (!queue) {
+ queue = { items: [], running: false, scheduled: false }
+ docFanoutQueues.set(documentId, queue)
+ }
+ queue.items.push(item)
+ scheduleDocFanout(documentId)
+}
+
async function withAuthorizedDocOperation(
c: AuthedSocket,
documentId: string,
subRec: DocSubscriber,
task: (companyId: string, client: import('pg').PoolClient) => Promise<void>,
): Promise<boolean> {
- const client = await pool.connect()
- try {
- await client.query('BEGIN')
- const { rows } = await client.query<{ company_id: string }>(
- `SELECT d.company_id
- FROM documents d
- JOIN company_members cm ON cm.company_id = d.company_id AND cm.user_id = $2
- JOIN users u ON u.id = cm.user_id AND u.deleted_at IS NULL
- JOIN participants p
- ON p.id = cm.user_id
- AND p.company_id = d.company_id
- AND p.kind = 'human'
- AND p.departed_at IS NULL
- WHERE d.id = $1
- FOR SHARE OF d, cm, u, p`,
- [documentId, c.userId],
- )
- if (!rows[0] || c.docSubs.get(documentId) !== subRec) {
- await client.query('ROLLBACK')
- detachDocSubscription(c, documentId, subRec)
- return false
+ const replaySupported = docReplaySupport.get(subRec) === true
+ const deadline = Date.now() + (replaySupported
+ ? DOC_AUTH_RETRY_DELAY_MS * (DOC_AUTH_LOCK_RETRY_LIMIT + 1)
+ : DOC_AUTH_LEGACY_DEADLINE_MS)
+ let attempt = 0
+ while (true) {
+ if (c.closed || c.docSubs.get(documentId) !== subRec) return false
+ let taskStarted = false
+ try {
+ return await docAuthSemaphore.run(async () => {
+ if (c.closed || c.docSubs.get(documentId) !== subRec) return false
+ const client = await pool.connect()
+ try {
+ if (c.closed || c.docSubs.get(documentId) !== subRec) return false
+ await client.query('BEGIN')
+ const { rows } = await client.query<{ company_id: string }>(
+ `SELECT d.company_id
+ FROM documents d
+ JOIN company_members cm ON cm.company_id = d.company_id AND cm.user_id = $2
+ JOIN users u ON u.id = cm.user_id AND u.deleted_at IS NULL
+ JOIN participants p
+ ON p.id = cm.user_id
+ AND p.company_id = d.company_id
+ AND p.kind = 'human'
+ AND p.departed_at IS NULL
+ WHERE d.id = $1
+ FOR SHARE OF d, cm, u, p NOWAIT`,
+ [documentId, c.userId],
+ )
+ if (!rows[0] || c.closed || c.docSubs.get(documentId) !== subRec) {
+ await client.query('ROLLBACK')
+ detachDocSubscription(c, documentId, subRec)
+ return false
+ }
+ taskStarted = true
+ await task(rows[0].company_id, client)
+ await client.query('COMMIT')
+ return true
+ } catch (error) {
+ await client.query('ROLLBACK').catch(() => {})
+ throw error
+ } finally {
+ client.release()
+ }
+ })
+ } catch (error) {
+ if (!taskStarted && isTransientDocAuthError(error)) {
+ const remaining = deadline - Date.now()
+ if (remaining <= 0) throw error
+ const backoff = replaySupported
+ ? 5 * (attempt + 1)
+ : Math.min(DOC_AUTH_RETRY_DELAY_MS * (attempt + 1), 1_000)
+ await new Promise((resolve) => setTimeout(resolve, Math.min(backoff, remaining)))
+ attempt++
+ continue
+ }
+ throw error
}
- await task(rows[0].company_id, client)
- await client.query('COMMIT')
- return true
- } catch (error) {
- await client.query('ROLLBACK').catch(() => {})
- throw error
- } finally {
- client.release()
}
}
@@ -385,6 +758,7 @@ function detachDocSubscription(
if (c.docSubs.get(documentId) !== subRec) return
docUnsubscribe(documentId, subRec)
c.docSubs.delete(documentId)
+ docReplaySupport.delete(subRec)
}
async function handleDocFrame(c: AuthedSocket, msg: Record<string, unknown>): Promise<void> {
@@ -393,20 +767,21 @@ async function handleDocFrame(c: AuthedSocket, msg: Record<string, unknown>): Pr
if (!documentId) return
if (type === 'doc.subscribe') {
- if (c.docSubs.has(documentId)) return // idempotent
+ if (c.closed || c.docSubs.has(documentId)) return // idempotent
const companyId = await docCompanyFor(documentId, c.userId)
+ if (c.closed) return
if (!companyId) {
sendJson(c.ws, { type: 'doc.error', documentId, error: 'not found' })
return
}
- let outboundQueue = Promise.resolve()
+ let subRec: DocSubscriber
+ const replaySupported = msg.replaySupported === true
let pendingOutboundBytes = 0
let pendingOutboundFrames = 0
- let subRec: DocSubscriber
const enqueueAuthorizedFrame = (
payload: unknown,
byteLength: number,
- pendingByteLimit: number = WS_TERMINATE_BUFFERED_BYTES,
+ pendingByteLimit = WS_TERMINATE_BUFFERED_BYTES,
): void => {
const estimatedBytes = Math.max(1, Math.ceil(byteLength * 4 / 3) + 256)
if (
@@ -417,19 +792,11 @@ async function handleDocFrame(c: AuthedSocket, msg: Record<string, unknown>): Pr
try { c.ws.terminate() } catch { /* ignore */ }
return
}
+ pendingOutboundFrames++
pendingOutboundBytes += estimatedBytes
- pendingOutboundFrames += 1
- const current = outboundQueue.catch(() => {}).then(async () => {
- if (c.docSubs.get(documentId) !== subRec) return
- await sendAuthorizedDocFrame(c, documentId, subRec, payload)
- }).finally(() => {
- pendingOutboundBytes = Math.max(0, pendingOutboundBytes - estimatedBytes)
+ enqueueAuthorizedDocFrame(c, documentId, subRec, payload, byteLength, replaySupported, () => {
pendingOutboundFrames = Math.max(0, pendingOutboundFrames - 1)
- })
- outboundQueue = current
- void current.catch((error) => {
- console.warn(`[ws] document authorization lookup failed for ${documentId}`, error)
- detachDocSubscription(c, documentId, subRec)
+ pendingOutboundBytes = Math.max(0, pendingOutboundBytes - estimatedBytes)
})
}
subRec = {
@@ -451,8 +818,21 @@ async function handleDocFrame(c: AuthedSocket, msg: Record<string, unknown>): Pr
}, update.byteLength)
},
}
- const { initialState } = await docSubscribe(documentId, companyId, subRec)
c.docSubs.set(documentId, subRec)
+ docReplaySupport.set(subRec, replaySupported)
+ let initialState: Uint8Array
+ try {
+ ({ initialState } = await docSubscribe(documentId, companyId, subRec))
+ } catch (error) {
+ detachDocSubscription(c, documentId, subRec)
+ throw error
+ }
+ if (c.closed || c.docSubs.get(documentId) !== subRec) {
+ docUnsubscribe(documentId, subRec)
+ if (c.docSubs.get(documentId) === subRec) c.docSubs.delete(documentId)
+ docReplaySupport.delete(subRec)
+ return
+ }
if (initialState.byteLength > DOC_SYNC_MAX_BYTES) {
detachDocSubscription(c, documentId, subRec)
sendJson(c.ws, {
@@ -474,12 +854,12 @@ async function handleDocFrame(c: AuthedSocket, msg: Record<string, unknown>): Pr
if (type === 'doc.unsubscribe') {
const subRec = c.docSubs.get(documentId)
if (!subRec) return
- docUnsubscribe(documentId, subRec)
- c.docSubs.delete(documentId)
+ detachDocSubscription(c, documentId, subRec)
return
}
if (type === 'doc.update') {
+ if (c.closed) return
const subRec = c.docSubs.get(documentId)
if (!subRec) return // must subscribe first
const updateB64 = typeof msg.updateB64 === 'string' ? msg.updateB64 : ''
@@ -492,6 +872,7 @@ async function handleDocFrame(c: AuthedSocket, msg: Record<string, unknown>): Pr
}
if (type === 'doc.awareness') {
+ if (c.closed) return
const subRec = c.docSubs.get(documentId)
if (!subRec) return
const updateB64 = typeof msg.updateB64 === 'string' ? msg.updateB64 : ''
@@ -504,12 +885,13 @@ async function handleDocFrame(c: AuthedSocket, msg: Record<string, unknown>): Pr
}
if (type === 'doc.mention.notify') {
+ if (c.closed) return
const rawIds = msg.mentionedIds
if (!Array.isArray(rawIds) || rawIds.length === 0) return
const requestedIds = rawIds.filter((x): x is string => typeof x === 'string')
if (requestedIds.length === 0) return
const companyId = await docCompanyFor(documentId, c.userId)
- if (!companyId) return
+ if (!companyId || c.closed) return
await processDocMention({
documentId, companyId, mentionerId: c.userId, requestedIds,
})
@@ -829,6 +1211,14 @@ export function attachWebSocket(httpServer: Server) {
wss.on('connection', async (ws, req) => {
const ip = req.socket.remoteAddress
+ let earlyClosed = false
+ const onEarlyClose = () => { earlyClosed = true }
+ const onEarlyError = () => { earlyClosed = true }
+ // Install lifecycle observers before ticket/member lookups. A client can
+ // close during either await; otherwise hydration could finish and attach a
+ // subscription to a socket whose close event was already missed.
+ ws.once('close', onEarlyClose)
+ ws.once('error', onEarlyError)
// The WS connect URL carries a SHORT-LIVED one-shot ticket
// (?t=<ws-ticket>), not the session token. Tickets are minted via
// POST /auth/ws-ticket and consumed atomically here. This keeps
@@ -845,20 +1235,42 @@ export function attachWebSocket(httpServer: Server) {
try { ws.close(4401, 'missing ws ticket') } catch { /* ignore */ }
return
}
- const session = await consumeWsTicket(ticket)
+ let session: Awaited<ReturnType<typeof consumeWsTicket>>
+ try {
+ session = await consumeWsTicket(ticket)
+ } catch (error) {
+ console.warn(`[ws] ticket lookup failed (${ip})`, error)
+ try { ws.close(1011, 'ticket lookup failed') } catch { /* ignore */ }
+ return
+ }
if (!session) {
console.log(`[ws] rejecting bad/expired/used ticket (${ip})`)
try { ws.close(4401, 'invalid ws ticket') } catch { /* ignore */ }
return
}
- const companies = await loadMemberships(session.userId)
+ if (earlyClosed) return
+ let companies: Set<string>
+ try {
+ companies = await loadMemberships(session.userId)
+ } catch (error) {
+ console.warn(`[ws] membership lookup failed (${ip})`, error)
+ try { ws.close(1011, 'membership lookup failed') } catch { /* ignore */ }
+ return
+ }
+ if (earlyClosed) return
+ ws.off('close', onEarlyClose)
+ ws.off('error', onEarlyError)
const c: AuthedSocket = {
ws,
userId: session.userId,
originId: randomUUID(),
companies,
docSubs: new Map(),
+ docFrameQueue: Promise.resolve(),
+ pendingDocFrames: 0,
+ pendingDocBytes: 0,
+ closed: false,
isAlive: true,
}
clients.add(c)
@@ -875,7 +1287,12 @@ export function attachWebSocket(httpServer: Server) {
const release = () => {
if (released) return
released = true
- for (const [docId, subRec] of c.docSubs) docUnsubscribe(docId, subRec)
+ c.closed = true
+ removeQueuedDocItems(c)
+ for (const [docId, subRec] of c.docSubs) {
+ docUnsubscribe(docId, subRec)
+ docReplaySupport.delete(subRec)
+ }
c.docSubs.clear()
clients.delete(c)
void onHumanDisconnect(session.userId)
@@ -885,15 +1302,44 @@ export function attachWebSocket(httpServer: Server) {
ws.send(JSON.stringify({ type: 'hello', instanceId: env.INSTANCE_ID, ts: Date.now() }))
} catch { /* ignore */ }
+ const enqueueInboundDocFrame = (msg: Record<string, unknown>, rawBytes: number): void => {
+ if (c.closed) return
+ const bytes = Math.max(1, rawBytes)
+ if (
+ c.pendingDocFrames >= 128
+ || c.pendingDocBytes + bytes > 4 * 1024 * 1024
+ || !reserveDocAuth(bytes)
+ ) {
+ try { c.ws.terminate() } catch { /* ignore */ }
+ return
+ }
+ c.pendingDocFrames++
+ c.pendingDocBytes += bytes
+ const current = c.docFrameQueue.catch(() => {}).then(async () => {
+ if (c.closed) return
+ await handleDocFrame(c, msg)
+ }).finally(() => {
+ c.pendingDocFrames = Math.max(0, c.pendingDocFrames - 1)
+ c.pendingDocBytes = Math.max(0, c.pendingDocBytes - bytes)
+ releaseDocAuth(bytes)
+ })
+ c.docFrameQueue = current
+ void current.catch((error) => {
+ if (c.closed) return
+ console.warn('[ws] doc frame error', error)
+ // A doc.update may be optimistic in the browser. Closing forces a
+ // fresh hello/doc.sync cycle, where yjsClient replays local state the
+ // server snapshot did not contain; a doc.error alone would strand it.
+ try { c.ws.terminate() } catch { /* ignore */ }
+ })
+ }
+
ws.on('message', (raw) => {
let msg: Record<string, unknown>
try { msg = JSON.parse(raw.toString()) as Record<string, unknown> } catch { return }
const type = typeof msg.type === 'string' ? msg.type : ''
if (type.startsWith('doc.')) {
- void handleDocFrame(c, msg).catch((e) => {
- console.warn('[ws] doc frame error', e)
- sendJson(ws, { type: 'doc.error', documentId: msg.documentId, error: 'server error' })
- })
+ enqueueInboundDocFrame(msg, Buffer.byteLength(raw.toString()))
}
// Other inbound types (ping etc.) would land here later; today the
// chat protocol is pure REST + broadcast so there's nothing else.
diff --git a/src/components/DocumentEditor.tsx b/src/components/DocumentEditor.tsx
index cd87e84..7704054 100644
--- a/src/components/DocumentEditor.tsx
+++ b/src/components/DocumentEditor.tsx
@@ -127,6 +127,7 @@ export function DocumentEditor({ documentId, variant = 'full', onClose, onOpenFu
const sessionRef = useRef<YDocSession | null>(null)
const [session, setSession] = useState<YDocSession | null>(null)
const [synced, setSynced] = useState(false)
+ const [syncError, setSyncError] = useState(false)
const [titleDraft, setTitleDraft] = useState(doc?.title ?? '')
useEffect(() => { setTitleDraft(doc?.title ?? '') }, [doc?.id, doc?.title])
@@ -136,16 +137,23 @@ export function DocumentEditor({ documentId, variant = 'full', onClose, onOpenFu
const s = openDocument({
documentId,
user: { id: user.id, name: user.name, color: colorForId(user.id) },
+ onSyncState: (error) => {
+ setSyncError(Boolean(error))
+ if (error) setSynced(false)
+ else setSynced(true)
+ },
})
sessionRef.current = s
setSession(s)
setSynced(false)
+ setSyncError(false)
void s.synced.then(() => setSynced(true))
return () => {
s.destroy()
sessionRef.current = null
setSession(null)
setSynced(false)
+ setSyncError(false)
}
}, [documentId, user])
@@ -237,6 +245,7 @@ export function DocumentEditor({ documentId, variant = 'full', onClose, onOpenFu
<CollaborativeEditor
session={session}
synced={synced}
+ syncError={syncError}
userName={user.name}
userColor={colorForId(user.id)}
documentId={documentId}
@@ -249,13 +258,14 @@ export function DocumentEditor({ documentId, variant = 'full', onClose, onOpenFu
interface CollaborativeEditorProps {
session: YDocSession
synced: boolean
+ syncError: boolean
userName: string
userColor: string
documentId: string
variant: 'full' | 'peek'
}
-function CollaborativeEditor({ session, synced, userName, userColor, documentId, variant }: CollaborativeEditorProps) {
+function CollaborativeEditor({ session, synced, syncError, userName, userColor, documentId, variant }: CollaborativeEditorProps) {
const t = useT()
const refreshingImagesRef = useRef(new Set<string>())
// Memoize the awareness object reference for the cursor extension —
@@ -396,6 +406,11 @@ function CollaborativeEditor({ session, synced, userName, userColor, documentId,
return (
<div className="flex-1 min-h-0 flex flex-col">
+ {syncError && (
+ <div role="alert" className="border-b border-amber-200 bg-amber-50 px-4 py-2 text-xs text-amber-900">
+ {t('docEdit.syncError')}
+ </div>
+ )}
<Toolbar editor={editor} disabled={!synced} />
<div className="flex-1 overflow-y-auto">
<EditorContent editor={editor} className="h-full" />
diff --git a/src/lib/yjsClient.ts b/src/lib/yjsClient.ts
index 42e6e6e..e7b382f 100644
--- a/src/lib/yjsClient.ts
+++ b/src/lib/yjsClient.ts
@@ -14,6 +14,7 @@
import * as Y from 'yjs'
import { Awareness, applyAwarenessUpdate, encodeAwarenessUpdate, removeAwarenessStates } from 'y-protocols/awareness'
import { ws, type WsEvent } from '@/api/client'
+import { applyServerSyncAndGetLocalReplay, replayFitsDocFrame } from './yjsSync'
function bytesToB64(bytes: Uint8Array): string {
let binary = ''
@@ -48,6 +49,9 @@ export interface OpenDocumentOptions {
/** Free-form identity stamped on awareness so peers can render
* "<name> is editing". Typically the user's display name. */
user: { id: string; name: string; color: string }
+ /** Called when local state cannot fit in one authorized replay frame, and
+ * again with null after a later sync recovers. */
+ onSyncState?: (error: Error | null) => void
}
export function openDocument(opts: OpenDocumentOptions): YDocSession {
@@ -94,7 +98,7 @@ export function openDocument(opts: OpenDocumentOptions): YDocSession {
const subscribe = () => {
// The server replies with `doc.sync` carrying the encoded state.
if (ws.isOpen()) {
- ws.send({ type: 'doc.subscribe', documentId })
+ ws.send({ type: 'doc.subscribe', documentId, replaySupported: true })
}
}
@@ -113,7 +117,19 @@ export function openDocument(opts: OpenDocumentOptions): YDocSession {
return
}
if (e.type === 'doc.sync' && e.documentId === documentId) {
- Y.applyUpdate(doc, b64ToBytes(e.stateB64), 'remote')
+ const replay = applyServerSyncAndGetLocalReplay(doc, b64ToBytes(e.stateB64))
+ if (!replayFitsDocFrame(replay, documentId)) {
+ opts.onSyncState?.(new Error('document replay exceeds the sync frame limit'))
+ return
+ }
+ if (replay.byteLength > 0) {
+ ws.send({
+ type: 'doc.update',
+ documentId,
+ updateB64: bytesToB64(replay),
+ })
+ }
+ opts.onSyncState?.(null)
resolveSynced()
return
}
diff --git a/src/lib/yjsSync.ts b/src/lib/yjsSync.ts
new file mode 100644
index 0000000..7f17711
--- /dev/null
+++ b/src/lib/yjsSync.ts
@@ -0,0 +1,25 @@
+import * as Y from 'yjs'
+
+/** The server's WebSocket maxPayload. Replay checks the serialized envelope,
+ * including base64/JSON framing, instead of guessing a raw Yjs byte budget. */
+export const DOC_WS_MAX_PAYLOAD_BYTES = 4 * 1024 * 1024
+
+export function replayFitsDocFrame(update: Uint8Array, documentId: string): boolean {
+ const base64Bytes = Math.ceil(update.byteLength / 3) * 4
+ const envelopeBytes = new TextEncoder().encode(JSON.stringify({
+ type: 'doc.update', documentId, updateB64: '',
+ })).byteLength
+ return envelopeBytes + base64Bytes <= DOC_WS_MAX_PAYLOAD_BYTES
+}
+
+/** Apply a server snapshot and return local state that the snapshot did not
+ * contain. The caller sends the returned update through the normal authorized
+ * doc.update path. Yjs may encode a no-op as a non-empty update; callers must
+ * inspect byteLength rather than assume an empty state is zero bytes. */
+export function applyServerSyncAndGetLocalReplay(doc: Y.Doc, serverState: Uint8Array): Uint8Array {
+ const localUpdate = Y.encodeStateAsUpdate(doc)
+ const serverVector = Y.encodeStateVectorFromUpdate(serverState)
+ const replay = Y.diffUpdate(localUpdate, serverVector)
+ Y.applyUpdate(doc, serverState, 'remote')
+ return replay
+}
diff --git a/src/locales/en.ts b/src/locales/en.ts
index 7a735d6..c3bf56d 100644
--- a/src/locales/en.ts
+++ b/src/locales/en.ts
@@ -377,6 +377,7 @@ export const en = {
'docEdit.linkPrompt': 'Link URL (leave empty to unlink):',
'docEdit.link': 'Link',
'docEdit.syncing': 'syncing…',
+ 'docEdit.syncError': 'Local edits exceed the one-frame sync limit. Copy your unsynced content before closing this document.',
'docEdit.onlyYou': 'only you',
// ─── image viewer overlay ─────────────────────────────────────────
'imageView.zoomOut': 'Zoom out (−)',
diff --git a/src/locales/zh-CN.ts b/src/locales/zh-CN.ts
index 9d63bc0..7574c6a 100644
--- a/src/locales/zh-CN.ts
+++ b/src/locales/zh-CN.ts
@@ -379,6 +379,7 @@ export const zhCN: Partial<Record<keyof typeof en, string>> = {
'docEdit.linkPrompt': '链接地址(留空可取消链接):',
'docEdit.link': '链接',
'docEdit.syncing': '同步中…',
+ 'docEdit.syncError': '本地编辑内容超过单帧同步限制。请先复制未同步的内容,再关闭文档。',
'docEdit.onlyYou': '只有你',
// ─── 图片查看器浮层 ────────────────────────────────────────────
'imageView.zoomOut': '缩小(−)',
diff --git a/tests/yjs-sync.test.ts b/tests/yjs-sync.test.ts
new file mode 100644
index 0000000..b27cc8a
--- /dev/null
+++ b/tests/yjs-sync.test.ts
@@ -0,0 +1,60 @@
+import assert from 'node:assert/strict'
+import { test } from 'node:test'
+import * as Y from 'yjs'
+import { applyServerSyncAndGetLocalReplay, DOC_WS_MAX_PAYLOAD_BYTES, replayFitsDocFrame } from '../src/lib/yjsSync'
+
+test('server sync replays local optimistic edits that the snapshot lacks', () => {
+ const server = new Y.Doc()
+ server.getText('content').insert(0, 'server')
+ const serverState = Y.encodeStateAsUpdate(server)
+
+ const local = new Y.Doc()
+ local.getText('content').insert(0, 'local')
+ const replay = applyServerSyncAndGetLocalReplay(local, serverState)
+
+ assert.ok(replay.byteLength > 0)
+ const converged = new Y.Doc()
+ Y.applyUpdate(converged, serverState)
+ Y.applyUpdate(converged, replay)
+ assert.equal(converged.getText('content').toString(), local.getText('content').toString())
+})
+
+test('server deletions are applied and replay is idempotent', () => {
+ const server = new Y.Doc()
+ const serverText = server.getText('content')
+ serverText.insert(0, 'obsolete')
+ const base = Y.encodeStateAsUpdate(server)
+ serverText.delete(0, serverText.length)
+ const deleted = Y.encodeStateAsUpdate(server)
+
+ const local = new Y.Doc()
+ Y.applyUpdate(local, base)
+ local.getText('content').insert(0, 'local')
+ const replay = applyServerSyncAndGetLocalReplay(local, deleted)
+
+ const converged = new Y.Doc()
+ Y.applyUpdate(converged, deleted)
+ Y.applyUpdate(converged, replay)
+ Y.applyUpdate(converged, replay)
+ assert.equal(converged.getText('content').toString(), local.getText('content').toString())
+})
+
+test('oversized local replay stays in the Y.Doc for the client sync-limit guard', () => {
+ const server = new Y.Doc()
+ const serverState = Y.encodeStateAsUpdate(server)
+ const local = new Y.Doc()
+ const original = 'x'.repeat(DOC_WS_MAX_PAYLOAD_BYTES)
+ local.getText('content').insert(0, original)
+
+ const replay = applyServerSyncAndGetLocalReplay(local, serverState)
+ assert.ok(replay.byteLength > 0)
+ assert.equal(replayFitsDocFrame(replay, 'doc-large'), false)
+ assert.equal(local.getText('content').toString(), original)
+})
+
+test('a smaller replay fits the serialized doc.update envelope', () => {
+ const doc = new Y.Doc()
+ doc.getText('content').insert(0, 'small local edit')
+ const replay = Y.encodeStateAsUpdate(doc)
+ assert.equal(replayFitsDocFrame(replay, 'doc-small'), true)
+})