@tldraw/sync-core 5.3.0-canary.ecf14a605aef → 5.3.0-internal.d205573d66cb

package/src/test/objectStore.test.ts

@@ -0,0 +1,387 @@
+import { BaseRecord, RecordId, StoreSchema, createRecordType } from '@tldraw/store'
+import { vi, type Mock } from 'vitest'
+import { RecordOpType, ValueOpType } from '../lib/diff'
+import { InMemorySyncStorage } from '../lib/InMemorySyncStorage'
+import {
+	TLConnectRequest,
+	TLPushRequest,
+	TLSocketServerSentEvent,
+	getTlsyncProtocolVersion,
+} from '../lib/protocol'
+import { TLSyncErrorCloseEventCode, TLSyncErrorCloseEventReason } from '../lib/TLSyncClient'
+import { RoomSnapshot, TLRoomSocket, TLSyncRoom } from '../lib/TLSyncRoom'
+
+// A generic object-lane test schema: `doc` records live in the document lane, `note` records are
+// served through the object-store lane (see `objectTypes` below). Deliberately not comment-shaped —
+// the lane is a generic primitive.
+
+interface DocRecord extends BaseRecord<'doc', RecordId<DocRecord>> {
+	title: string
+}
+interface NoteRecord extends BaseRecord<'note', RecordId<NoteRecord>> {
+	text: string
+}
+interface PresenceRecord extends BaseRecord<'presence', RecordId<PresenceRecord>> {
+	name: string
+}
+
+const Doc = createRecordType<DocRecord>('doc', {
+	scope: 'document',
+	validator: { validate: (value) => value as DocRecord },
+})
+const Note = createRecordType<NoteRecord>('note', {
+	scope: 'document',
+	validator: { validate: (value) => value as NoteRecord },
+})
+const Presence = createRecordType<PresenceRecord>('presence', {
+	scope: 'presence',
+	validator: { validate: (value) => value as PresenceRecord },
+})
+
+type R = DocRecord | NoteRecord | PresenceRecord
+
+const schema = StoreSchema.create<R>({ doc: Doc, note: Note, presence: Presence })
+
+type MockSocket = TLRoomSocket<any> & {
+	__messages: TLSocketServerSentEvent<any>[]
+	sendMessage: Mock
+	close: Mock
+}
+
+function makeSocket(): MockSocket {
+	const socket: MockSocket = {
+		__messages: [],
+		// cloning because the room reuses/clears message objects after sending
+		sendMessage: vi.fn((msg: TLSocketServerSentEvent<any>) => {
+			socket.__messages.push(structuredClone(msg))
+		}),
+		close: vi.fn(() => {
+			socket.isOpen = false
+		}),
+		isOpen: true,
+	}
+	return socket
+}
+
+function sentDataMessages(socket: MockSocket): any[] {
+	return socket.__messages.flatMap((msg: any) => (msg.type === 'data' ? msg.data : []))
+}
+
+function clearSocket(socket: MockSocket) {
+	socket.sendMessage.mockClear()
+	socket.__messages.length = 0
+}
+
+const disposables: Array<() => void> = []
+afterEach(() => {
+	for (const dispose of disposables) dispose()
+	disposables.length = 0
+})
+
+function makeRoom(
+	opts: {
+		snapshot?: RoomSnapshot
+		objectTypes?: readonly string[]
+		onCommittedChanges?(args: { diff: any; documentClock: number }): void
+	} = {}
+) {
+	const storage = new InMemorySyncStorage<R>({
+		snapshot: opts.snapshot ?? {
+			documents: [],
+			clock: 0,
+			documentClock: 0,
+			schema: schema.serialize(),
+		},
+		// keep the storage partition in step with the room's object lane
+		objectTypes: opts.objectTypes,
+	})
+	const room = new TLSyncRoom<R, undefined>({
+		schema,
+		storage,
+		objectTypes: opts.objectTypes,
+		onCommittedChanges: opts.onCommittedChanges,
+	})
+	disposables.push(() => room.close())
+	return { storage, room }
+}
+
+function connectSession(
+	room: TLSyncRoom<any, any>,
+	sessionId: string,
+	opts: {
+		isReadonly?: boolean
+		objectAccess?: 'read' | 'write'
+		clear?: boolean
+	} = {}
+): MockSocket {
+	const socket = makeSocket()
+	room.handleNewSession({
+		sessionId,
+		socket,
+		meta: undefined,
+		isReadonly: opts.isReadonly ?? false,
+		objectAccess: opts.objectAccess,
+	})
+	room.handleMessage(sessionId, {
+		type: 'connect',
+		connectRequestId: 'connect-' + sessionId,
+		lastServerClock: 0,
+		protocolVersion: getTlsyncProtocolVersion(),
+		schema: room.serializedSchema,
+	} satisfies TLConnectRequest)
+	if (opts.clear !== false) {
+		clearSocket(socket)
+	}
+	return socket
+}
+
+function push(
+	room: TLSyncRoom<any, any>,
+	sessionId: string,
+	diff: TLPushRequest<any>['diff'],
+	clientClock = 1
+) {
+	room.handleMessage(sessionId, { type: 'push', clientClock, diff } satisfies TLPushRequest<any>)
+}
+
+function lastPushResult(socket: MockSocket) {
+	return sentDataMessages(socket)
+		.filter((m) => m.type === 'push_result')
+		.at(-1)
+}
+
+function storedIds(storage: InMemorySyncStorage<R>) {
+	// span both partitions: the document snapshot no longer contains object-lane records
+	return [...storage.getSnapshot().documents, ...storage.getObjectsSnapshot()]
+		.map((d) => d.state.id)
+		.sort()
+}
+
+describe('object store lane', () => {
+	describe('type partition', () => {
+		it('excludes object types from documentTypes and exposes them via objectTypes', () => {
+			const { room } = makeRoom({ objectTypes: ['note'] })
+			expect(room.documentTypes.has('doc')).toBe(true)
+			expect(room.documentTypes.has('note')).toBe(false)
+			expect(room.objectTypes.has('note')).toBe(true)
+		})
+
+		it('keeps documentTypes intact when no objectTypes are configured', () => {
+			const { room } = makeRoom()
+			expect(room.documentTypes.has('doc')).toBe(true)
+			expect(room.documentTypes.has('note')).toBe(true)
+			expect(room.objectTypes.size).toBe(0)
+		})
+
+		it('rejects object types that are not registered in the schema', () => {
+			expect(() => makeRoom({ objectTypes: ['nonexistent'] })).toThrow(
+				"object type 'nonexistent' is not registered"
+			)
+		})
+
+		it('rejects object types that are not document-scoped', () => {
+			expect(() => makeRoom({ objectTypes: ['presence'] })).toThrow(
+				"object type 'presence' must have scope 'document'"
+			)
+		})
+	})
+
+	describe('object writes', () => {
+		it('commits object puts, broadcasts them, and hydrates them on connect', () => {
+			const { room, storage } = makeRoom({ objectTypes: ['note'] })
+			const writer = connectSession(room, 'writer')
+			const observer = connectSession(room, 'observer')
+
+			const note = Note.create({ text: 'hello' })
+			push(room, 'writer', { [note.id]: [RecordOpType.Put, note] })
+
+			expect(lastPushResult(writer)).toMatchObject({ action: 'commit' })
+			expect(storedIds(storage)).toEqual([note.id])
+
+			// broadcast to the other session
+			room._flushDataMessages('observer')
+			expect(
+				sentDataMessages(observer).find(
+					(m) => m.type === 'patch' && m.diff[note.id]?.[0] === RecordOpType.Put
+				)
+			).toBeDefined()
+
+			// a fresh connect hydrates the object record
+			const late = connectSession(room, 'late', { clear: false })
+			const connectMsg = late.__messages.find((m: any) => m.type === 'connect') as any
+			expect(connectMsg.diff[note.id]).toEqual([RecordOpType.Put, note])
+		})
+
+		it('still rejects unknown record types for writable sessions', () => {
+			const { room } = makeRoom({ objectTypes: ['note'] })
+			const socket = connectSession(room, 'writer')
+
+			push(room, 'writer', {
+				'mystery:1': [RecordOpType.Put, { id: 'mystery:1', typeName: 'mystery' } as any],
+			})
+
+			expect(socket.close).toHaveBeenCalledWith(
+				TLSyncErrorCloseEventCode,
+				TLSyncErrorCloseEventReason.INVALID_RECORD
+			)
+		})
+
+		it('skips unknown record types for denied sessions without rejecting (legacy readonly behavior)', () => {
+			const { room, storage } = makeRoom({ objectTypes: ['note'] })
+			const socket = connectSession(room, 'reader', { isReadonly: true })
+
+			push(room, 'reader', {
+				'mystery:1': [RecordOpType.Put, { id: 'mystery:1', typeName: 'mystery' } as any],
+			})
+
+			expect(socket.close).not.toHaveBeenCalled()
+			expect(lastPushResult(socket)).toMatchObject({ action: 'discard' })
+			expect(storedIds(storage)).toEqual([])
+		})
+	})
+
+	describe('permission axes', () => {
+		it('lets a readonly session with object write access write objects but not documents', () => {
+			const { room, storage } = makeRoom({ objectTypes: ['note'] })
+			// "can comment but not edit"
+			const socket = connectSession(room, 'commenter', {
+				isReadonly: true,
+				objectAccess: 'write',
+			})
+
+			const doc = Doc.create({ title: 'nope' })
+			const note = Note.create({ text: 'yep' })
+			push(room, 'commenter', {
+				[doc.id]: [RecordOpType.Put, doc],
+				[note.id]: [RecordOpType.Put, note],
+			})
+
+			// only the object op survives, so the client is rebased onto it
+			expect(lastPushResult(socket)).toMatchObject({
+				action: { rebaseWithDiff: { [note.id]: [RecordOpType.Put, note] } },
+			})
+			expect(storedIds(storage)).toEqual([note.id])
+		})
+
+		it('blocks object writes for objectAccess: read while document writes still commit', () => {
+			const { room, storage } = makeRoom({ objectTypes: ['note'] })
+			const socket = connectSession(room, 'editor', { objectAccess: 'read' })
+
+			const doc = Doc.create({ title: 'yep' })
+			const note = Note.create({ text: 'nope' })
+			push(room, 'editor', {
+				[doc.id]: [RecordOpType.Put, doc],
+				[note.id]: [RecordOpType.Put, note],
+			})
+
+			expect(lastPushResult(socket)).toMatchObject({
+				action: { rebaseWithDiff: { [doc.id]: [RecordOpType.Put, doc] } },
+			})
+			expect(storedIds(storage)).toEqual([doc.id])
+		})
+
+		it('discards object-only pushes entirely for objectAccess: read', () => {
+			const { room, storage } = makeRoom({ objectTypes: ['note'] })
+			const socket = connectSession(room, 'reader', { objectAccess: 'read' })
+
+			const note = Note.create({ text: 'nope' })
+			push(room, 'reader', { [note.id]: [RecordOpType.Put, note] })
+
+			expect(lastPushResult(socket)).toMatchObject({ action: 'discard' })
+			expect(storedIds(storage)).toEqual([])
+		})
+
+		it('gates object patches and removes by objectAccess', () => {
+			const note = Note.create({ text: 'original' })
+			const { room, storage } = makeRoom({
+				objectTypes: ['note'],
+				snapshot: {
+					documents: [{ state: note, lastChangedClock: 0 }],
+					clock: 0,
+					documentClock: 0,
+					schema: schema.serialize(),
+				},
+			})
+			const reader = connectSession(room, 'reader', { objectAccess: 'read' })
+
+			push(room, 'reader', {
+				[note.id]: [RecordOpType.Patch, { text: [ValueOpType.Put, 'tampered'] }],
+			})
+			expect(lastPushResult(reader)).toMatchObject({ action: 'discard' })
+
+			push(room, 'reader', { [note.id]: [RecordOpType.Remove] }, 2)
+			expect(lastPushResult(reader)).toMatchObject({ action: 'discard' })
+			expect(storedIds(storage)).toEqual([note.id])
+
+			// a readonly-but-object-writable session can remove the object record
+			connectSession(room, 'commenter', { isReadonly: true, objectAccess: 'write' })
+			push(room, 'commenter', { [note.id]: [RecordOpType.Remove] })
+			expect(storedIds(storage)).toEqual([])
+		})
+	})
+
+	describe('storage partition', () => {
+		it('keeps object records out of the document snapshot but in the objects snapshot', () => {
+			const { room, storage } = makeRoom({ objectTypes: ['note'] })
+			connectSession(room, 'writer')
+
+			const doc = Doc.create({ title: 'canvas' })
+			const note = Note.create({ text: 'annotation' })
+			push(room, 'writer', {
+				[doc.id]: [RecordOpType.Put, doc],
+				[note.id]: [RecordOpType.Put, note],
+			})
+
+			// the document snapshot is pure-document by construction
+			expect(storage.getSnapshot().documents.map((d) => d.state.id)).toEqual([doc.id])
+			// the object lane is persisted separately
+			expect(storage.getObjectsSnapshot().map((d) => d.state.id)).toEqual([note.id])
+
+			// but a fresh connect still hydrates both (shared clock + change feed)
+			const late = connectSession(room, 'late', { clear: false })
+			const connectMsg = late.__messages.find((m: any) => m.type === 'connect') as any
+			expect(Object.keys(connectMsg.diff).sort()).toEqual([doc.id, note.id].sort())
+		})
+	})
+
+	describe('connect message', () => {
+		it('carries the session objectAccess', () => {
+			const { room } = makeRoom({ objectTypes: ['note'] })
+
+			const writer = connectSession(room, 'writer', { clear: false })
+			const writerConnect = writer.__messages.find((m: any) => m.type === 'connect') as any
+			expect(writerConnect.objectAccess).toBe('write')
+
+			const reader = connectSession(room, 'reader', { objectAccess: 'read', clear: false })
+			const readerConnect = reader.__messages.find((m: any) => m.type === 'connect') as any
+			expect(readerConnect.objectAccess).toBe('read')
+		})
+	})
+
+	describe('onCommittedChanges projection hook', () => {
+		it('fires with the committed object diff', async () => {
+			const onCommittedChanges = vi.fn()
+			const { room } = makeRoom({ objectTypes: ['note'], onCommittedChanges })
+			connectSession(room, 'writer')
+
+			const note = Note.create({ text: 'hello' })
+			push(room, 'writer', { [note.id]: [RecordOpType.Put, note] })
+			await Promise.resolve() // the hook fires on a microtask
+
+			expect(onCommittedChanges).toHaveBeenCalledTimes(1)
+			expect(onCommittedChanges.mock.calls[0][0].diff.puts[note.id]).toEqual(note)
+		})
+
+		it('does not fire when every op in the push was denied', async () => {
+			const onCommittedChanges = vi.fn()
+			const { room } = makeRoom({ objectTypes: ['note'], onCommittedChanges })
+			connectSession(room, 'reader', { objectAccess: 'read' })
+
+			const note = Note.create({ text: 'nope' })
+			push(room, 'reader', { [note.id]: [RecordOpType.Put, note] })
+			await Promise.resolve()
+
+			expect(onCommittedChanges).not.toHaveBeenCalled()
+		})
+	})
+})

package/src/test/storageContractSuite.ts

@@ -41,6 +41,7 @@ export function makePage(id: string, name = id, index = 'a2') {
 export interface StorageContractFactory {
 	create(opts?: {
 		snapshot?: RoomSnapshot
+		objectTypes?: readonly string[]
 		onChange?(arg: TLSyncStorageOnChangeCallbackProps): void
 	}): TLSyncStorage<TLRecord>
 }
@@ -61,6 +62,84 @@ export function registerStorageContractTests(factory: StorageContractFactory) {
 			expect(snapshot.documents.map((d) => d.lastChangedClock)).toEqual([0, 0])
 		})
 
+		describe('object-store lane partition', () => {
+			// the storage doesn't care about record semantics, so 'page' stands in as a
+			// generic object-lane type here
+			const createPartitioned = (snapshot?: RoomSnapshot) =>
+				factory.create({ snapshot, objectTypes: ['page'] })
+
+			it('partitions object-lane records out of getSnapshot into getObjectsSnapshot', () => {
+				const storage = createPartitioned(
+					makeContractSnapshot(contractRecords, { documentClock: 5 })
+				)
+				const snapshot = storage.getSnapshot!()
+				expect(snapshot.documents.map((d) => d.state.typeName)).toEqual(['document'])
+				// clock + schema are unaffected by the partition
+				expect(snapshot.documentClock).toBe(5)
+
+				expect(storage.getObjectsSnapshot!().map((d) => d.state.typeName)).toEqual(['page'])
+			})
+
+			it('returns an empty objects snapshot when no objectTypes are configured', () => {
+				const storage = create(makeContractSnapshot(contractRecords))
+				expect(storage.getSnapshot!().documents.length).toBe(2)
+				expect(storage.getObjectsSnapshot!()).toEqual([])
+			})
+
+			it('routes writes by type and shares the clock, tombstones, and change feed', () => {
+				const storage = createPartitioned(makeContractSnapshot(contractRecords))
+				const newPage = makePage('lane')
+				storage.transaction((txn) => txn.set(newPage.id, newPage))
+
+				// the write landed in the object partition, not the document snapshot
+				expect(storage.getSnapshot!().documents.map((d) => d.state.id)).toEqual([TLDOCUMENT_ID])
+				expect(storage.getObjectsSnapshot!().map((d) => d.state.id)).toContain(newPage.id)
+
+				// reads and the change feed span both partitions
+				storage.transaction((txn) => {
+					expect(txn.get(newPage.id)).toEqual(newPage)
+					expect(txn.getChangesSince(0)!.diff.puts[newPage.id]).toEqual(newPage)
+				})
+
+				// deleting an object-lane record writes a shared tombstone
+				const clockBeforeDelete = storage.getClock()
+				storage.transaction((txn) => txn.delete(newPage.id))
+				expect(storage.getObjectsSnapshot!().map((d) => d.state.id)).not.toContain(newPage.id)
+				storage.transaction((txn) => {
+					expect(txn.getChangesSince(clockBeforeDelete)!.diff.deletes).toContain(newPage.id)
+				})
+			})
+
+			it('iterates both partitions so schema migrations cover object-lane records', () => {
+				const storage = createPartitioned(makeContractSnapshot(contractRecords))
+				storage.transaction((txn) => {
+					const ids = Array.from(txn.keys()).sort()
+					expect(ids).toEqual(contractRecords.map((r) => r.id).sort())
+					expect(
+						Array.from(txn.values())
+							.map((r) => r.id)
+							.sort()
+					).toEqual(ids)
+					expect(
+						Array.from(txn.entries())
+							.map(([id]) => id)
+							.sort()
+					).toEqual(ids)
+				})
+			})
+
+			it('round-trips through a merged snapshot (persist lanes separately, re-seed together)', () => {
+				const storage = createPartitioned(makeContractSnapshot(contractRecords))
+				const merged = {
+					...storage.getSnapshot!(),
+					documents: [...storage.getSnapshot!().documents, ...storage.getObjectsSnapshot!()],
+				}
+				const reseeded = createPartitioned(merged)
+				expect(reseeded.getSnapshot!().documents.map((d) => d.state.typeName)).toEqual(['document'])
+				expect(reseeded.getObjectsSnapshot!().map((d) => d.state.typeName)).toEqual(['page'])
+			})
+		})
+
 		describe('transactions', () => {
 			it('[SS2] returns the callback result along with clock metadata', () => {
 				const storage = create(makeContractSnapshot(contractRecords, { documentClock: 7 }))

package/src/test/upgradeDowngrade.test.ts

@@ -2,6 +2,7 @@ import { computed } from '@tldraw/state'
 import {
 	BaseRecord,
 	RecordId,
+	SerializedSchema,
 	Store,
 	StoreSchema,
 	UnknownRecord,
@@ -10,6 +11,7 @@ import {
 	createRecordMigrationSequence,
 	createRecordType,
 } from '@tldraw/store'
+import { commentSchemaRecords, createTLSchema } from '@tldraw/tlschema'
 import { vi, type Mock } from 'vitest'
 import { RecordOpType, ValueOpType } from '../lib/diff'
 import { TLSocketServerSentEvent, getTlsyncProtocolVersion } from '../lib/protocol'
@@ -218,6 +220,47 @@ class TestInstance {
 	}
 }
 
+describe('record types unknown to older clients', () => {
+	// Mirrors a deploy that adds the comment record types: stale tabs still run a schema
+	// without them, while the server registers them and serves rooms that may contain them. The
+	// comment types ship guard migrations (retroactive, no `down`), so the server must reject
+	// stale sessions with CLIENT_TOO_OLD (prompting a refresh) rather than sending them record
+	// types their store cannot represent.
+	const schemaWithComments = createTLSchema({ records: commentSchemaRecords })
+	const schemaWithoutComments = createTLSchema()
+
+	function connectWith(server: TestServer<any>, schema: SerializedSchema) {
+		const id = 'stale-tab'
+		const socket = mockSocket()
+		server.room.handleNewSession({ sessionId: id, socket, meta: undefined, isReadonly: false })
+		server.room.handleMessage(id, {
+			type: 'connect',
+			connectRequestId: 'test',
+			lastServerClock: 0,
+			protocolVersion: getTlsyncProtocolVersion(),
+			schema,
+		})
+		return socket
+	}
+
+	it('[HS3] rejects sessions whose schema predates the comment types', () => {
+		const server = new TestServer(schemaWithComments as any, undefined, {
+			objectTypes: ['comment', 'comment-thread'],
+		})
+		const socket = connectWith(server, schemaWithoutComments.serialize())
+		expect(socket.close).toHaveBeenCalledWith(4099, TLSyncErrorCloseEventReason.CLIENT_TOO_OLD)
+	})
+
+	it('[HS3] accepts sessions whose schema registers the comment types', () => {
+		const server = new TestServer(schemaWithComments as any, undefined, {
+			objectTypes: ['comment', 'comment-thread'],
+		})
+		const socket = connectWith(server, schemaWithComments.serialize())
+		expect(socket.close).not.toHaveBeenCalled()
+		expect((socket.sendMessage as Mock).mock.calls[0][0]).toMatchObject({ type: 'connect' })
+	})
+})
+
 it('[MG2] the server can handle receiving v1 stuff from the client', () => {
 	const t = new TestInstance()
 	t.oldSocketPair.connect()
@@ -568,6 +611,7 @@ describe('when the client is too old', () => {
 			schema: schemaV2.serialize(),
 			serverClock: 10,
 			isReadonly: false,
+			objectAccess: 'write',
 		} satisfies TLSocketServerSentEvent<RV2>)
 
 		expect(v1SendMessage).toHaveBeenCalledWith({
@@ -579,6 +623,7 @@ describe('when the client is too old', () => {
 			schema: schemaV2.serialize(),
 			serverClock: 10,
 			isReadonly: false,
+			objectAccess: 'write',
 		} satisfies TLSocketServerSentEvent<RV2>)
 
 		v2SendMessage.mockClear()
@@ -1100,6 +1145,7 @@ describe('when the client is the same version', () => {
 			schema: schemaV2.serialize(),
 			serverClock: 10,
 			isReadonly: false,
+			objectAccess: 'write',
 		} satisfies TLSocketServerSentEvent<RV2>)
 
 		expect(bSocket.sendMessage).toHaveBeenCalledWith({
@@ -1111,6 +1157,7 @@ describe('when the client is the same version', () => {
 			schema: schemaV2.serialize(),
 			serverClock: 10,
 			isReadonly: false,
+			objectAccess: 'write',
 		} satisfies TLSocketServerSentEvent<RV2>)
 		;(aSocket.sendMessage as Mock).mockClear()
 		;(bSocket.sendMessage as Mock).mockClear()