@tldraw/sync-core 5.2.0-canary.4a316fdfb2bb → 5.2.0-canary.4e00299c3e28

package/src/lib/SQLiteSyncStorage.test.ts

@@ -0,0 +1,239 @@
+import { DatabaseSync } from 'node:sqlite'
+import { DocumentRecordType, PageRecordType, TLDOCUMENT_ID, TLRecord } from '@tldraw/tlschema'
+import { ZERO_INDEX_KEY } from '@tldraw/utils'
+import { describe, expect, it } from 'vitest'
+import {
+	contractRecords,
+	contractSchema,
+	makeContractSnapshot,
+	makePage,
+	registerStorageContractTests,
+} from '../test/storageContractSuite'
+import { NodeSqliteWrapper } from './NodeSqliteWrapper'
+import { SQLiteSyncStorage } from './SQLiteSyncStorage'
+
+function createWrapper(config?: { tablePrefix?: string }) {
+	return new NodeSqliteWrapper(new DatabaseSync(':memory:'), config)
+}
+
+describe('SQLiteSyncStorage', () => {
+	registerStorageContractTests({
+		create: (opts) => new SQLiteSyncStorage<TLRecord>({ sql: createWrapper(), ...opts }),
+	})
+
+	describe('persistence and initialization', () => {
+		it('[SQ1] data persists across re-instantiation over the same database', () => {
+			const sql = createWrapper()
+			const storage = new SQLiteSyncStorage<TLRecord>({
+				sql,
+				snapshot: makeContractSnapshot(contractRecords),
+			})
+			const newPage = makePage('persisted')
+			storage.transaction((txn) => txn.set(newPage.id, newPage))
+
+			const reopened = new SQLiteSyncStorage<TLRecord>({ sql })
+			expect(reopened.getClock()).toBe(1)
+			expect(
+				reopened.getSnapshot().documents.find((d) => d.state.id === newPage.id)?.state
+			).toEqual(newPage)
+		})
+
+		it('[SQ1] honors the table prefix', () => {
+			const sql = createWrapper({ tablePrefix: 'tldraw_' })
+			const storage = new SQLiteSyncStorage<TLRecord>({
+				sql,
+				snapshot: makeContractSnapshot(contractRecords, { documentClock: 7 }),
+			})
+			expect(storage.getClock()).toBe(7)
+			// the prefixed tables exist; the unprefixed ones do not
+			expect(sql.prepare('SELECT count(*) as count FROM tldraw_documents').all()).toEqual([
+				{ count: 2 },
+			])
+			expect(() => sql.prepare('SELECT count(*) as count FROM documents').all()).toThrow()
+		})
+
+		it('[SQ2] a provided snapshot wipes and replaces existing data', () => {
+			const sql = createWrapper()
+			const storage = new SQLiteSyncStorage<TLRecord>({
+				sql,
+				snapshot: makeContractSnapshot(contractRecords, { documentClock: 10 }),
+			})
+			const extra = makePage('extra')
+			storage.transaction((txn) => txn.set(extra.id, extra))
+
+			const replacement = makeContractSnapshot([contractRecords[0]], { documentClock: 3 })
+			const reinitialized = new SQLiteSyncStorage<TLRecord>({ sql, snapshot: replacement })
+			expect(reinitialized.getClock()).toBe(3)
+			expect(reinitialized.getSnapshot().documents.map((d) => d.state.id)).toEqual([
+				contractRecords[0].id,
+			])
+		})
+
+		it('[SQ2] without a snapshot, pre-existing data is kept untouched', () => {
+			const sql = createWrapper()
+			new SQLiteSyncStorage<TLRecord>({
+				sql,
+				snapshot: makeContractSnapshot(contractRecords, { documentClock: 9 }),
+			})
+			const reopened = new SQLiteSyncStorage<TLRecord>({ sql })
+			expect(reopened.getClock()).toBe(9)
+			expect(reopened.getSnapshot().documents.length).toBe(2)
+		})
+
+		it('[SQ2] accepts a StoreSnapshot and converts it', () => {
+			const sql = createWrapper()
+			const storage = new SQLiteSyncStorage<TLRecord>({
+				sql,
+				snapshot: {
+					store: {
+						[TLDOCUMENT_ID]: contractRecords[0],
+						[contractRecords[1].id]: contractRecords[1],
+					} as any,
+					schema: contractSchema.serialize(),
+				},
+			})
+			const snapshot = storage.getSnapshot()
+			expect(snapshot.documentClock).toBe(0)
+			expect(snapshot.documents.length).toBe(2)
+			expect(snapshot.documents.every((d) => d.lastChangedClock === 0)).toBe(true)
+			expect(snapshot.tombstones).toEqual({})
+		})
+	})
+
+	describe('clock handling vs the in-memory implementation', () => {
+		it('[SQ3] takes documentClock verbatim, without clamping to lastChangedClock', () => {
+			const storage = new SQLiteSyncStorage<TLRecord>({
+				sql: createWrapper(),
+				snapshot: makeContractSnapshot(contractRecords, {
+					documents: [
+						{ state: contractRecords[0], lastChangedClock: 10 },
+						{ state: contractRecords[1], lastChangedClock: 3 },
+					],
+					documentClock: 3,
+				}),
+			})
+			expect(storage.getClock()).toBe(3)
+		})
+
+		it('[SQ3] takes tombstoneHistoryStartsAtClock verbatim and keeps tombstones with an empty history window', () => {
+			const storage = new SQLiteSyncStorage<TLRecord>({
+				sql: createWrapper(),
+				snapshot: makeContractSnapshot(contractRecords, {
+					tombstones: { 'shape:deleted1': 5 },
+					tombstoneHistoryStartsAtClock: 15,
+					documentClock: 15,
+				}),
+			})
+			const snapshot = storage.getSnapshot()
+			expect(snapshot.tombstoneHistoryStartsAtClock).toBe(15)
+			expect(snapshot.tombstones).toEqual({ 'shape:deleted1': 5 })
+		})
+	})
+
+	describe('static methods', () => {
+		it('[SQ4] hasBeenInitialized is false for an empty database and true once initialized', () => {
+			const sql = createWrapper()
+			expect(SQLiteSyncStorage.hasBeenInitialized(sql)).toBe(false)
+			new SQLiteSyncStorage<TLRecord>({ sql, snapshot: makeContractSnapshot(contractRecords) })
+			expect(SQLiteSyncStorage.hasBeenInitialized(sql)).toBe(true)
+		})
+
+		it('[SQ4] hasBeenInitialized respects the table prefix', () => {
+			const sql = createWrapper({ tablePrefix: 'test_' })
+			expect(SQLiteSyncStorage.hasBeenInitialized(sql)).toBe(false)
+			new SQLiteSyncStorage<TLRecord>({ sql, snapshot: makeContractSnapshot(contractRecords) })
+			expect(SQLiteSyncStorage.hasBeenInitialized(sql)).toBe(true)
+		})
+
+		it('[SQ5] getDocumentClock returns null when uninitialized, the persisted clock afterwards', () => {
+			const sql = createWrapper()
+			expect(SQLiteSyncStorage.getDocumentClock(sql)).toBe(null)
+
+			const storage = new SQLiteSyncStorage<TLRecord>({
+				sql,
+				snapshot: makeContractSnapshot(contractRecords, { documentClock: 42 }),
+			})
+			expect(SQLiteSyncStorage.getDocumentClock(sql)).toBe(42)
+
+			const newPage = makePage('test_page')
+			storage.transaction((txn) => txn.set(newPage.id, newPage))
+			expect(SQLiteSyncStorage.getDocumentClock(sql)).toBe(43)
+		})
+	})
+
+	describe('storage format migrations', () => {
+		it('[SQ6] stores document state as JSON-encoded BLOBs', () => {
+			const sql = createWrapper()
+			new SQLiteSyncStorage<TLRecord>({
+				sql,
+				snapshot: makeContractSnapshot(contractRecords),
+			})
+			const row = sql
+				.prepare<{ state: Uint8Array }>('SELECT state FROM documents WHERE id = ?')
+				.all(TLDOCUMENT_ID as any)[0]
+			// node:sqlite may hand back a Uint8Array from another realm, so avoid instanceof
+			expect(typeof row.state).not.toBe('string')
+			expect(ArrayBuffer.isView(row.state)).toBe(true)
+			expect(JSON.parse(new TextDecoder().decode(row.state))).toEqual(contractRecords[0])
+		})
+
+		it('[SQ6] migrates v1 databases (TEXT column) to BLOB, preserving data', () => {
+			// simulate a database created by the v1 schema
+			const db = new DatabaseSync(':memory:')
+			db.exec(`
+				CREATE TABLE documents (
+					id TEXT PRIMARY KEY,
+					state TEXT NOT NULL,
+					lastChangedClock INTEGER NOT NULL
+				);
+				CREATE INDEX idx_documents_lastChangedClock ON documents(lastChangedClock);
+				CREATE TABLE tombstones (
+					id TEXT PRIMARY KEY,
+					clock INTEGER NOT NULL
+				);
+				CREATE INDEX idx_tombstones_clock ON tombstones(clock);
+				CREATE TABLE metadata (
+					migrationVersion INTEGER NOT NULL,
+					documentClock INTEGER NOT NULL,
+					tombstoneHistoryStartsAtClock INTEGER NOT NULL,
+					schema TEXT NOT NULL
+				);
+				INSERT INTO metadata (migrationVersion, documentClock, tombstoneHistoryStartsAtClock, schema)
+				VALUES (1, 5, 0, '${JSON.stringify(contractSchema.serialize()).replace(/'/g, "''")}');
+			`)
+			const doc = DocumentRecordType.create({ id: TLDOCUMENT_ID })
+			const page = PageRecordType.create({
+				id: PageRecordType.createId('migrated_page'),
+				name: 'Migrated Page',
+				index: ZERO_INDEX_KEY,
+			})
+			const insert = db.prepare(
+				'INSERT INTO documents (id, state, lastChangedClock) VALUES (?, ?, ?)'
+			)
+			insert.run(doc.id, JSON.stringify(doc), 1)
+			insert.run(page.id, JSON.stringify(page), 2)
+			db.exec("INSERT INTO tombstones (id, clock) VALUES ('shape:deleted', 3)")
+
+			const storage = new SQLiteSyncStorage<TLRecord>({ sql: new NodeSqliteWrapper(db) })
+
+			const snapshot = storage.getSnapshot()
+			expect(snapshot.documentClock).toBe(5)
+			expect(snapshot.documents.map((d) => d.state.id).sort()).toEqual([doc.id, page.id].sort())
+			expect(snapshot.tombstones).toEqual({ 'shape:deleted': 3 })
+
+			// still writable after migration
+			const newPage = makePage('new_after_migration')
+			storage.transaction((txn) => txn.set(newPage.id, newPage))
+			expect(storage.getSnapshot().documents.length).toBe(3)
+		})
+
+		it('[SQ6] fresh databases start at migration version 2', () => {
+			const sql = createWrapper()
+			new SQLiteSyncStorage<TLRecord>({ sql, snapshot: makeContractSnapshot(contractRecords) })
+			const row = sql
+				.prepare<{ migrationVersion: number }>('SELECT migrationVersion FROM metadata')
+				.all()[0]
+			expect(row?.migrationVersion).toBe(2)
+		})
+	})
+})

package/src/lib/ServerSocketAdapter.test.ts

@@ -3,226 +3,87 @@ import { describe, expect, it, vi } from 'vitest'
 import { TLSocketServerSentEvent } from './protocol'
 import { ServerSocketAdapter, WebSocketMinimal } from './ServerSocketAdapter'
 
-// Mock WebSocket implementations for testing different scenarios
 class MockWebSocket implements WebSocketMinimal {
-	readyState: number = 1 // OPEN by default
+	readyState = 1 // OPEN
 	send = vi.fn()
 	close = vi.fn()
-	addEventListener = vi.fn()
-	removeEventListener = vi.fn()
 }
 
-class MinimalMockWebSocket implements WebSocketMinimal {
-	readyState: number = 1
-	send = vi.fn()
-	close = vi.fn()
-	// No addEventListener/removeEventListener
-}
+const pongMessage: TLSocketServerSentEvent<UnknownRecord> = { type: 'pong' }
 
 describe('ServerSocketAdapter', () => {
-	describe('sendMessage', () => {
-		it('should JSON stringify and send the message', () => {
-			const mockWs = new MockWebSocket()
-			const adapter = new ServerSocketAdapter({ ws: mockWs })
-
-			const message: TLSocketServerSentEvent<UnknownRecord> = {
-				type: 'connect',
-				hydrationType: 'wipe_all',
-				connectRequestId: 'test-request-123',
-				protocolVersion: 1,
-				schema: { schemaVersion: 1, storeVersion: 0, recordVersions: {} },
-				diff: {},
-				serverClock: 0,
-				isReadonly: false,
-			}
-
-			adapter.sendMessage(message)
-
-			expect(mockWs.send).toHaveBeenCalledTimes(1)
-			expect(mockWs.send).toHaveBeenCalledWith(JSON.stringify(message))
-		})
-
-		it('should call onBeforeSendMessage callback when provided', () => {
-			const mockWs = new MockWebSocket()
-			const onBeforeSendMessage = vi.fn()
-			const adapter = new ServerSocketAdapter({ ws: mockWs, onBeforeSendMessage })
-
-			const message: TLSocketServerSentEvent<UnknownRecord> = {
-				type: 'data',
-				data: [{ type: 'patch', diff: {}, serverClock: 1 }],
-			}
-
-			adapter.sendMessage(message)
-
-			expect(onBeforeSendMessage).toHaveBeenCalledTimes(1)
-			expect(onBeforeSendMessage).toHaveBeenCalledWith(message, JSON.stringify(message))
-			expect(mockWs.send).toHaveBeenCalledTimes(1)
-		})
-
-		it('should call onBeforeSendMessage before sending to WebSocket', () => {
-			const mockWs = new MockWebSocket()
-			const callOrder: string[] = []
-
-			const onBeforeSendMessage = vi.fn(() => {
-				callOrder.push('callback')
-			})
-
-			mockWs.send.mockImplementation(() => {
-				callOrder.push('websocket')
-			})
-
-			const adapter = new ServerSocketAdapter({ ws: mockWs, onBeforeSendMessage })
-
-			const message: TLSocketServerSentEvent<UnknownRecord> = {
-				type: 'pong',
-			}
-
-			adapter.sendMessage(message)
-
-			expect(callOrder).toEqual(['callback', 'websocket'])
-		})
+	it('[SA1] isOpen is true exactly when the wrapped socket readyState is 1', () => {
+		const ws = new MockWebSocket()
+		const adapter = new ServerSocketAdapter({ ws })
+
+		ws.readyState = 0 // CONNECTING
+		expect(adapter.isOpen).toBe(false)
+		ws.readyState = 1 // OPEN
+		expect(adapter.isOpen).toBe(true)
+		ws.readyState = 2 // CLOSING
+		expect(adapter.isOpen).toBe(false)
+		ws.readyState = 3 // CLOSED
+		expect(adapter.isOpen).toBe(false)
 	})
 
-	describe('close method', () => {
-		it('should call close on the underlying WebSocket with no parameters', () => {
-			const mockWs = new MockWebSocket()
-			const adapter = new ServerSocketAdapter({ ws: mockWs })
-
-			adapter.close()
-
-			expect(mockWs.close).toHaveBeenCalledTimes(1)
-			expect(mockWs.close).toHaveBeenCalledWith(undefined, undefined)
-		})
-
-		it('should call close on the underlying WebSocket with code only', () => {
-			const mockWs = new MockWebSocket()
-			const adapter = new ServerSocketAdapter({ ws: mockWs })
-
-			const closeCode = 1000
-			adapter.close(closeCode)
-
-			expect(mockWs.close).toHaveBeenCalledTimes(1)
-			expect(mockWs.close).toHaveBeenCalledWith(closeCode, undefined)
-		})
-
-		it('should call close on the underlying WebSocket with code and reason', () => {
-			const mockWs = new MockWebSocket()
-			const adapter = new ServerSocketAdapter({ ws: mockWs })
-
-			const closeCode = 1001
-			const closeReason = 'Going away'
-			adapter.close(closeCode, closeReason)
-
-			expect(mockWs.close).toHaveBeenCalledTimes(1)
-			expect(mockWs.close).toHaveBeenCalledWith(closeCode, closeReason)
-		})
+	it('[SA2] sendMessage JSON-stringifies the message and sends it', () => {
+		const ws = new MockWebSocket()
+		const adapter = new ServerSocketAdapter({ ws })
+
+		const message: TLSocketServerSentEvent<UnknownRecord> = {
+			type: 'connect',
+			hydrationType: 'wipe_all',
+			connectRequestId: 'test-request-123',
+			protocolVersion: 1,
+			schema: { schemaVersion: 1, storeVersion: 0, recordVersions: {} },
+			diff: {},
+			serverClock: 0,
+			isReadonly: false,
+		}
+
+		adapter.sendMessage(message)
+
+		expect(ws.send).toHaveBeenCalledTimes(1)
+		expect(ws.send).toHaveBeenCalledWith(JSON.stringify(message))
 	})
 
-	describe('Error handling', () => {
-		it('should handle WebSocket send errors gracefully', () => {
-			const mockWs = new MockWebSocket()
-			mockWs.send.mockImplementation(() => {
-				throw new Error('WebSocket send failed')
-			})
-
-			const adapter = new ServerSocketAdapter({ ws: mockWs })
-
-			const message: TLSocketServerSentEvent<UnknownRecord> = {
-				type: 'pong',
-			}
-
-			expect(() => adapter.sendMessage(message)).toThrow('WebSocket send failed')
+	it('[SA2] sendMessage invokes onBeforeSendMessage with the message and its stringified form before sending', () => {
+		const ws = new MockWebSocket()
+		const callOrder: string[] = []
+		const onBeforeSendMessage = vi.fn(() => {
+			callOrder.push('callback')
 		})
-
-		it('should handle WebSocket close errors gracefully', () => {
-			const mockWs = new MockWebSocket()
-			mockWs.close.mockImplementation(() => {
-				throw new Error('WebSocket close failed')
-			})
-
-			const adapter = new ServerSocketAdapter({ ws: mockWs })
-
-			expect(() => adapter.close()).toThrow('WebSocket close failed')
+		ws.send.mockImplementation(() => {
+			callOrder.push('send')
 		})
+		const adapter = new ServerSocketAdapter({ ws, onBeforeSendMessage })
 
-		it('should handle onBeforeSendMessage callback errors', () => {
-			const mockWs = new MockWebSocket()
-			const faultyCallback = vi.fn(() => {
-				throw new Error('Callback error')
-			})
-
-			const adapter = new ServerSocketAdapter({ ws: mockWs, onBeforeSendMessage: faultyCallback })
-
-			const message: TLSocketServerSentEvent<UnknownRecord> = {
-				type: 'pong',
-			}
+		adapter.sendMessage(pongMessage)
 
-			expect(() => adapter.sendMessage(message)).toThrow('Callback error')
-			expect(faultyCallback).toHaveBeenCalled()
-			// WebSocket send should not be called if callback throws
-			expect(mockWs.send).not.toHaveBeenCalled()
-		})
+		expect(onBeforeSendMessage).toHaveBeenCalledTimes(1)
+		expect(onBeforeSendMessage).toHaveBeenCalledWith(pongMessage, JSON.stringify(pongMessage))
+		expect(ws.send).toHaveBeenCalledTimes(1)
+		expect(callOrder).toEqual(['callback', 'send'])
 	})
 
-	describe('Integration scenarios', () => {
-		it('should work with different WebSocket implementations', () => {
-			const scenarios = [
-				{ name: 'Standard WebSocket', ws: new MockWebSocket() },
-				{ name: 'Minimal WebSocket', ws: new MinimalMockWebSocket() },
-			]
-
-			scenarios.forEach(({ name, ws }) => {
-				const adapter = new ServerSocketAdapter({ ws })
-
-				expect(adapter, `${name} should create adapter`).toBeInstanceOf(ServerSocketAdapter)
+	it('[SA3] close passes through to the wrapped socket without arguments', () => {
+		const ws = new MockWebSocket()
+		const adapter = new ServerSocketAdapter({ ws })
 
-				const message: TLSocketServerSentEvent<UnknownRecord> = {
-					type: 'pong',
-				}
+		adapter.close()
 
-				expect(
-					() => adapter.sendMessage(message),
-					`${name} should handle sendMessage`
-				).not.toThrow()
-				expect(() => adapter.close(), `${name} should handle close`).not.toThrow()
-			})
-		})
-
-		it('should handle rapid message sending', () => {
-			const mockWs = new MockWebSocket()
-			const onBeforeSendMessage = vi.fn()
-			const adapter = new ServerSocketAdapter({ ws: mockWs, onBeforeSendMessage })
-
-			// Send multiple messages rapidly
-			for (let i = 0; i < 100; i++) {
-				const message: TLSocketServerSentEvent<UnknownRecord> = {
-					type: 'pong',
-				}
-				adapter.sendMessage(message)
-			}
-
-			expect(mockWs.send).toHaveBeenCalledTimes(100)
-			expect(onBeforeSendMessage).toHaveBeenCalledTimes(100)
-		})
-
-		it('should maintain consistent behavior across state changes', () => {
-			const mockWs = new MockWebSocket()
-			const adapter = new ServerSocketAdapter({ ws: mockWs })
-
-			// Test behavior when WebSocket changes state
-			expect(adapter.isOpen).toBe(true)
-
-			mockWs.readyState = 0 // CONNECTING
-			expect(adapter.isOpen).toBe(false)
+		expect(ws.close).toHaveBeenCalledTimes(1)
+		expect(ws.close).toHaveBeenCalledWith(undefined, undefined)
+	})
 
-			mockWs.readyState = 2 // CLOSING
-			expect(adapter.isOpen).toBe(false)
+	it('[SA3] close passes through the code and reason to the wrapped socket', () => {
+		const ws = new MockWebSocket()
+		const adapter = new ServerSocketAdapter({ ws })
 
-			mockWs.readyState = 3 // CLOSED
-			expect(adapter.isOpen).toBe(false)
+		adapter.close(1000)
+		expect(ws.close).toHaveBeenLastCalledWith(1000, undefined)
 
-			mockWs.readyState = 1 // OPEN
-			expect(adapter.isOpen).toBe(true)
-		})
+		adapter.close(1001, 'Going away')
+		expect(ws.close).toHaveBeenLastCalledWith(1001, 'Going away')
 	})
 })

package/src/lib/TLSocketRoom.ts

@@ -427,7 +427,12 @@ export class TLSocketRoom<R extends UnknownRecord = UnknownRecord, SessionMeta =
 					}
 				}
 
-				this.room.handleMessage(sessionId, res.data as any)
+				// handleMessage is async but does not await internally; catch rejections
+				// so an error thrown while handling the message still rejects the session
+				this.room.handleMessage(sessionId, res.data as any).catch((error) => {
+					this.log?.error?.(error)
+					this.room.rejectSession(sessionId, TLSyncErrorCloseEventReason.UNKNOWN_ERROR)
+				})
 				this.room.pruneSessions()
 				this.scheduleDebouncedSnapshot(sessionId)
 			} else {