@tldraw/sync-core 4.5.2 → 4.6.0-canary.00a8c03b5687

package/src/lib/TLSocketRoom.ts

@@ -1,5 +1,5 @@
-import type { StoreSchema, UnknownRecord } from '@tldraw/store'
-import { createTLSchema, TLStoreSnapshot } from '@tldraw/tlschema'
+import type { SerializedSchema, StoreSchema, UnknownRecord } from '@tldraw/store'
+import { createTLSchema, TLInstancePresence, TLStoreSnapshot } from '@tldraw/tlschema'
 import { getOwnProperty, hasOwnProperty, isEqual, structuredClone } from '@tldraw/utils'
 import { DEFAULT_INITIAL_SNAPSHOT, InMemorySyncStorage } from './InMemorySyncStorage'
 import { RoomSessionState } from './RoomSession'
@@ -14,6 +14,22 @@ import {
 import { JsonChunkAssembler } from './chunk'
 import { TLSocketServerSentEvent } from './protocol'
 
+/**
+ * Strip potentially large fields from a tldraw instance_presence record so the
+ * snapshot stays small when stored in WebSocket attachments (e.g. for hibernation).
+ * Keeps cursor, selection, page, and user identity; clears scribbles, chatMessage, brush.
+ */
+function stripPresenceForSnapshot(record: UnknownRecord): UnknownRecord {
+	if (record.typeName !== 'instance_presence') return record
+	const stripped = { ...record } as TLInstancePresence
+	stripped.scribbles = []
+	stripped.chatMessage = ''
+	stripped.selectedShapeIds = []
+	stripped.brush = null
+
+	return stripped as unknown as UnknownRecord
+}
+
 /**
  * Logging interface for TLSocketRoom operations. Provides optional methods
  * for warning and error logging during synchronization operations.
@@ -43,6 +59,24 @@ export interface TLSyncLog {
 	error?(...args: any[]): void
 }
 
+/**
+ * A snapshot of per-session state that can be persisted and used to resume a session
+ * after the server restarts (e.g., after Cloudflare Durable Object hibernation).
+ *
+ * Obtain via {@link TLSocketRoom.getSessionSnapshot} and restore via
+ * {@link TLSocketRoom.handleSocketResume}.
+ *
+ * @public
+ */
+export interface SessionStateSnapshot {
+	serializedSchema: SerializedSchema
+	isReadonly: boolean
+	presenceId: string | null
+	presenceRecord: UnknownRecord | null
+	requiresLegacyRejection: boolean
+	supportsStringAppend: boolean
+}
+
 /**
  * Base options for TLSocketRoom.
  * @public
@@ -62,13 +96,13 @@ export interface TLSocketRoomOptions<R extends UnknownRecord, SessionMeta> {
 	clientTimeout?: number
 	log?: TLSyncLog
 	// a callback that is called when a client is disconnected
-	// eslint-disable-next-line @typescript-eslint/method-signature-style
+	// eslint-disable-next-line tldraw/method-signature-style
 	onSessionRemoved?: (
 		room: TLSocketRoom<R, SessionMeta>,
 		args: { sessionId: string; numSessionsRemaining: number; meta: SessionMeta }
 	) => void
 	// a callback that is called whenever a message is sent
-	// eslint-disable-next-line @typescript-eslint/method-signature-style
+	// eslint-disable-next-line tldraw/method-signature-style
 	onBeforeSendMessage?: (args: {
 		sessionId: string
 		/** @internal keep the protocol private for now */
@@ -76,7 +110,7 @@ export interface TLSocketRoomOptions<R extends UnknownRecord, SessionMeta> {
 		stringified: string
 		meta: SessionMeta
 	}) => void
-	// eslint-disable-next-line @typescript-eslint/method-signature-style
+	// eslint-disable-next-line tldraw/method-signature-style
 	onAfterReceiveMessage?: (args: {
 		sessionId: string
 		/** @internal keep the protocol private for now */
@@ -86,6 +120,14 @@ export interface TLSocketRoomOptions<R extends UnknownRecord, SessionMeta> {
 	}) => void
 	/** @internal */
 	onPresenceChange?(): void
+	/**
+	 * When set, the room will call {@link TLSocketRoom.getSessionSnapshot} after
+	 * no message activity for a session for 5s and pass the result to this callback.
+	 * Use for persisting snapshots to WebSocket attachments (e.g. Cloudflare hibernation).
+	 * The room clears any pending snapshot when the session closes.
+	 */
+	// eslint-disable-next-line tldraw/method-signature-style
+	onSessionSnapshot?: (sessionId: string, snapshot: SessionStateSnapshot) => void
 }
 
 /**
@@ -152,7 +194,7 @@ export class TLSocketRoom<R extends UnknownRecord = UnknownRecord, SessionMeta =
 	private room: TLSyncRoom<R, SessionMeta>
 	private readonly sessions = new Map<
 		string,
-		// eslint-disable-next-line @typescript-eslint/method-signature-style
+		// eslint-disable-next-line tldraw/method-signature-style
 		{ assembler: JsonChunkAssembler; socket: WebSocketMinimal; unlisten: () => void }
 	>()
 	readonly log?: TLSyncLog
@@ -160,6 +202,7 @@ export class TLSocketRoom<R extends UnknownRecord = UnknownRecord, SessionMeta =
 	public storage: TLSyncStorage<R>
 
 	private disposables = new Set<() => void>()
+	private readonly snapshotTimers = new Map<string, ReturnType<typeof setTimeout>>()
 
 	/**
 	 * Creates a new TLSocketRoom instance for managing collaborative document synchronization.
@@ -203,9 +246,11 @@ export class TLSocketRoom<R extends UnknownRecord = UnknownRecord, SessionMeta =
 			schema: opts.schema ?? (createTLSchema() as any),
 			log: opts.log,
 			storage,
+			clientTimeout: opts.clientTimeout,
 		})
 		this.storage = storage
 		this.room.events.on('session_removed', (args) => {
+			this.clearSnapshotTimer(args.sessionId)
 			this.sessions.delete(args.sessionId)
 			if (this.opts.onSessionRemoved) {
 				this.opts.onSessionRemoved(this, {
@@ -306,6 +351,27 @@ export class TLSocketRoom<R extends UnknownRecord = UnknownRecord, SessionMeta =
 		socket.addEventListener?.('error', handleSocketError)
 	}
 
+	private clearSnapshotTimer(sessionId: string) {
+		const t = this.snapshotTimers.get(sessionId)
+		if (t) {
+			clearTimeout(t)
+			this.snapshotTimers.delete(sessionId)
+		}
+	}
+
+	private scheduleDebouncedSnapshot(sessionId: string) {
+		if (!this.opts.onSessionSnapshot) return
+		this.clearSnapshotTimer(sessionId)
+		this.snapshotTimers.set(
+			sessionId,
+			setTimeout(() => {
+				this.snapshotTimers.delete(sessionId)
+				const snapshot = this.getSessionSnapshot(sessionId)
+				if (snapshot) this.opts.onSessionSnapshot!(sessionId, snapshot)
+			}, 5000)
+		)
+	}
+
 	/**
 	 * Processes a message received from a client WebSocket. Use this method in server
 	 * environments where WebSocket event listeners cannot be attached directly to socket
@@ -362,6 +428,8 @@ export class TLSocketRoom<R extends UnknownRecord = UnknownRecord, SessionMeta =
 				}
 
 				this.room.handleMessage(sessionId, res.data as any)
+				this.room.pruneSessions()
+				this.scheduleDebouncedSnapshot(sessionId)
 			} else {
 				this.log?.error?.('Error assembling message', res.error)
 				// close the socket to reset the connection
@@ -391,6 +459,7 @@ export class TLSocketRoom<R extends UnknownRecord = UnknownRecord, SessionMeta =
 	 * ```
 	 */
 	handleSocketError(sessionId: string) {
+		this.clearSnapshotTimer(sessionId)
 		this.room.handleClose(sessionId)
 	}
 
@@ -410,9 +479,124 @@ export class TLSocketRoom<R extends UnknownRecord = UnknownRecord, SessionMeta =
 	 * ```
 	 */
 	handleSocketClose(sessionId: string) {
+		this.clearSnapshotTimer(sessionId)
 		this.room.handleClose(sessionId)
 	}
 
+	/**
+	 * Resumes a previously-connected session directly into `Connected` state, bypassing
+	 * the connect handshake. Use this after server hibernation (e.g., Cloudflare Durable
+	 * Object hibernation) when WebSocket connections survived but all in-memory state was lost.
+	 *
+	 * The session is restored using a {@link SessionStateSnapshot} previously obtained
+	 * via {@link TLSocketRoom.getSessionSnapshot}. The client is unaware the server restarted and
+	 * continues sending messages normally.
+	 *
+	 * Unlike {@link TLSocketRoom.handleSocketConnect}, this method does NOT attach WebSocket event
+	 * listeners. In hibernation environments, events are delivered via class methods
+	 * (e.g., `webSocketMessage`) rather than `addEventListener`.
+	 *
+	 * @param opts - Resume options
+	 *   - sessionId - Unique identifier for the client session
+	 *   - socket - WebSocket-like object for client communication
+	 *   - snapshot - Session state snapshot from {@link TLSocketRoom.getSessionSnapshot}
+	 *   - meta - Additional session metadata (required if SessionMeta is not void)
+	 *
+	 * @example
+	 * ```ts
+	 * // After Cloudflare DO hibernation wake
+	 * for (const ws of ctx.getWebSockets()) {
+	 *   const data = ws.deserializeAttachment()
+	 *   room.handleSocketResume({
+	 *     sessionId: data.sessionId,
+	 *     socket: ws,
+	 *     snapshot: data.snapshot,
+	 *   })
+	 * }
+	 * ```
+	 */
+	handleSocketResume(
+		opts: {
+			sessionId: string
+			socket: WebSocketMinimal
+			snapshot: SessionStateSnapshot
+		} & (SessionMeta extends void ? object : { meta: SessionMeta })
+	) {
+		const { sessionId, socket, snapshot } = opts
+
+		this.sessions.set(sessionId, {
+			assembler: new JsonChunkAssembler(),
+			socket,
+			unlisten: () => {
+				// no-op: hibernation environments use class methods, not addEventListener
+			},
+		})
+
+		this.room.handleResumedSession({
+			sessionId,
+			isReadonly: snapshot.isReadonly,
+			serializedSchema: snapshot.serializedSchema,
+			presenceId: snapshot.presenceId,
+			presenceRecord: snapshot.presenceRecord,
+			requiresLegacyRejection: snapshot.requiresLegacyRejection,
+			supportsStringAppend: snapshot.supportsStringAppend,
+			socket: new ServerSocketAdapter({
+				ws: socket,
+				onBeforeSendMessage: this.opts.onBeforeSendMessage
+					? (message, stringified) =>
+							this.opts.onBeforeSendMessage!({
+								sessionId,
+								message,
+								stringified,
+								meta: this.room.sessions.get(sessionId)?.meta as SessionMeta,
+							})
+					: undefined,
+			}),
+			meta: 'meta' in opts ? (opts.meta as any) : undefined,
+		})
+	}
+
+	/**
+	 * Returns a snapshot of a connected session's state that can be persisted and later
+	 * used with {@link TLSocketRoom.handleSocketResume} to restore the session after hibernation.
+	 *
+	 * Returns `null` if the session doesn't exist or isn't in the `Connected` state.
+	 *
+	 * @param sessionId - The session to snapshot
+	 *
+	 * @example
+	 * ```ts
+	 * // Store snapshot in a Cloudflare WebSocket attachment
+	 * const snapshot = room.getSessionSnapshot(sessionId)
+	 * if (snapshot) {
+	 *   ws.serializeAttachment({ sessionId, snapshot })
+	 * }
+	 * ```
+	 */
+	getSessionSnapshot(sessionId: string): SessionStateSnapshot | null {
+		const session = this.room.sessions.get(sessionId)
+		if (!session || session.state !== RoomSessionState.Connected) {
+			return null
+		}
+
+		let presenceRecord: UnknownRecord | null = null
+		if (session.presenceId) {
+			const record = this.room.presenceStore.get(session.presenceId)
+			if (record) {
+				presenceRecord = stripPresenceForSnapshot(record as UnknownRecord)
+			}
+		}
+
+		return {
+			serializedSchema: session.serializedSchema,
+			isReadonly: session.isReadonly,
+			presenceId: session.presenceId,
+			presenceRecord,
+			requiresLegacyRejection: session.requiresLegacyRejection,
+			supportsStringAppend: session.supportsStringAppend,
+		}
+	}
+
 	/**
 	 * Returns the current document clock value. The clock is a monotonically increasing
 	 * integer that increments with each document change, providing a consistent ordering
@@ -702,6 +886,9 @@ export class TLSocketRoom<R extends UnknownRecord = UnknownRecord, SessionMeta =
 	 */
 	close() {
 		this.room.close()
+		for (const sessionId of this.snapshotTimers.keys()) {
+			this.clearSnapshotTimer(sessionId)
+		}
 		this.disposables.forEach((d) => d())
 		this.disposables.clear()
 	}

package/src/lib/TLSyncClient.test.ts

@@ -30,13 +30,10 @@ const protocolVersion = getTlsyncProtocolVersion()
 type TestRecord = TLRecord
 
 // Mock socket implementation for testing
-class MockSocket
-	implements
-		TLPersistentClientSocket<
-			TLSocketClientSentEvent<TestRecord>,
-			TLSocketServerSentEvent<TestRecord>
-		>
-{
+class MockSocket implements TLPersistentClientSocket<
+	TLSocketClientSentEvent<TestRecord>,
+	TLSocketServerSentEvent<TestRecord>
+> {
 	connectionStatus: 'online' | 'offline' | 'error' = 'offline'
 	private messageListeners: Array<(msg: TLSocketServerSentEvent<TestRecord>) => void> = []
 	private statusListeners: Array<(event: TLSocketStatusChangeEvent) => void> = []

package/src/lib/TLSyncClient.ts

@@ -903,7 +903,7 @@ export class TLSyncClient<R extends UnknownRecord, S extends Store<R> = Store<R>
 		}
 	}
 
-	// eslint-disable-next-line local/prefer-class-methods
+	// eslint-disable-next-line tldraw/prefer-class-methods
 	private rebase = () => {
 		// need to make sure that our speculative changes are in sync with the actual store instance before
 		// proceeding, to avoid inconsistency bugs.

package/src/lib/TLSyncRoom.ts

@@ -15,6 +15,7 @@ import {
 	isNativeStructuredClone,
 	objectMapEntriesIterable,
 	Result,
+	throttle,
 } from '@tldraw/utils'
 import { createNanoEvents } from 'nanoevents'
 import {
@@ -150,12 +151,17 @@ export class TLSyncRoom<R extends UnknownRecord, SessionMeta> {
 
 	private lastDocumentClock = 0
 
-	// eslint-disable-next-line local/prefer-class-methods
-	pruneSessions = () => {
+	private pruneTimer: ReturnType<typeof setTimeout> | null = null
+
+	pruneSessions = throttle(() => {
+		if (this.pruneTimer) {
+			clearTimeout(this.pruneTimer)
+			this.pruneTimer = null
+		}
 		for (const client of this.sessions.values()) {
 			switch (client.state) {
 				case RoomSessionState.Connected: {
-					const hasTimedOut = timeSince(client.lastInteractionTime) > SESSION_IDLE_TIMEOUT
+					const hasTimedOut = timeSince(client.lastInteractionTime) > this.sessionIdleTimeout
 					if (hasTimedOut || !client.socket.isOpen) {
 						this.cancelSession(client.sessionId)
 					}
@@ -166,6 +172,8 @@ export class TLSyncRoom<R extends UnknownRecord, SessionMeta> {
 					if (hasTimedOut || !client.socket.isOpen) {
 						// remove immediately
 						this.removeSession(client.sessionId)
+					} else {
+						this.scheduleFollowUpPrune()
 					}
 					break
 				}
@@ -173,6 +181,8 @@ export class TLSyncRoom<R extends UnknownRecord, SessionMeta> {
 					const hasTimedOut = timeSince(client.cancellationTime) > SESSION_REMOVAL_WAIT_TIME
 					if (hasTimedOut) {
 						this.removeSession(client.sessionId)
+					} else {
+						this.scheduleFollowUpPrune()
 					}
 					break
 				}
@@ -181,11 +191,16 @@ export class TLSyncRoom<R extends UnknownRecord, SessionMeta> {
 				}
 			}
 		}
+	}, 1000)
+
+	private scheduleFollowUpPrune() {
+		if (this.pruneTimer) return
+		this.pruneTimer = setTimeout(this.pruneSessions, SESSION_REMOVAL_WAIT_TIME + 100)
 	}
 
 	readonly presenceStore = new PresenceStore<R>()
 
-	private disposables: Array<() => void> = [interval(this.pruneSessions, 2000)]
+	private disposables: Array<() => void> = []
 
 	private _isClosed = false
 
@@ -225,17 +240,20 @@ export class TLSyncRoom<R extends UnknownRecord, SessionMeta> {
 	private log?: TLSyncLog
 	public readonly schema: StoreSchema<R, any>
 	private onPresenceChange?(): void
+	private readonly sessionIdleTimeout: number
 
 	constructor(opts: {
 		log?: TLSyncLog
 		schema: StoreSchema<R, any>
 		onPresenceChange?(): void
 		storage: TLSyncStorage<R>
+		clientTimeout?: number
 	}) {
 		this.schema = opts.schema
 		this.log = opts.log
 		this.onPresenceChange = opts.onPresenceChange
 		this.storage = opts.storage
+		this.sessionIdleTimeout = opts.clientTimeout ?? SESSION_IDLE_TIMEOUT
 
 		assert(
 			isNativeStructuredClone,
@@ -277,6 +295,24 @@ export class TLSyncRoom<R extends UnknownRecord, SessionMeta> {
 				}
 			})
 		)
+
+		this.disposables.push(() => {
+			this.pruneSessions.cancel()
+			if (this.pruneTimer) {
+				clearTimeout(this.pruneTimer)
+				this.pruneTimer = null
+			}
+		})
+
+		// When clientTimeout is finite, run periodic pruning so idle sessions are
+		// cleaned up even with no traffic. When Infinity or 0 we skip the interval
+		// (e.g. for hibernation); without it, pruning only runs on message or when
+		// socket close/error triggers cancelSession, so pruning idle sessions
+		// reliably depends on the runtime delivering those events.
+		if (Number.isFinite(this.sessionIdleTimeout) && this.sessionIdleTimeout > 0) {
+			const pruneIntervalMs = Math.min(2000, Math.floor(this.sessionIdleTimeout / 4))
+			this.disposables.push(interval(() => this.pruneSessions(), pruneIntervalMs))
+		}
 	}
 	private broadcastExternalStorageChanges() {
 		this.storage.transaction((txn) => {
@@ -412,6 +448,8 @@ export class TLSyncRoom<R extends UnknownRecord, SessionMeta> {
 		} catch {
 			// noop, calling .close() multiple times is fine
 		}
+
+		this.scheduleFollowUpPrune()
 	}
 
 	readonly internalTxnId = 'TLSyncRoom.txn'
@@ -529,6 +567,60 @@ export class TLSyncRoom<R extends UnknownRecord, SessionMeta> {
 		return this
 	}
 
+	/**
+	 * Resume a previously-connected session directly into `Connected` state, bypassing the
+	 * connect handshake. Used after server hibernation when the WebSocket is still alive but
+	 * all in-memory state has been lost.
+	 *
+	 * @internal
+	 */
+	handleResumedSession(opts: {
+		sessionId: string
+		socket: TLRoomSocket<R>
+		meta: SessionMeta
+		isReadonly: boolean
+		serializedSchema: SerializedSchema
+		presenceId: string | null
+		presenceRecord: UnknownRecord | null
+		requiresLegacyRejection: boolean
+		supportsStringAppend: boolean
+	}) {
+		const {
+			sessionId,
+			socket,
+			meta,
+			isReadonly,
+			serializedSchema,
+			presenceId,
+			presenceRecord,
+			requiresLegacyRejection,
+			supportsStringAppend,
+		} = opts
+
+		const migrations = this.schema.getMigrationsSince(serializedSchema)
+		const requiresDownMigrations = migrations.ok ? migrations.value.length > 0 : false
+
+		this.sessions.set(sessionId, {
+			state: RoomSessionState.Connected,
+			sessionId,
+			socket,
+			presenceId: presenceId ?? this.presenceType?.createId() ?? null,
+			serializedSchema,
+			requiresDownMigrations,
+			lastInteractionTime: Date.now(),
+			debounceTimer: null,
+			outstandingDataMessages: [],
+			meta,
+			isReadonly,
+			requiresLegacyRejection,
+			supportsStringAppend,
+		})
+
+		if (presenceRecord && presenceId) {
+			this.presenceStore.set(presenceId, presenceRecord as R)
+		}
+	}
+
 	/**
 	 * Checks if all connected sessions support string append operations (protocol version 8+).
 	 * If any client is on an older version, returns false to enable legacy append mode.

package/src/lib/protocol.ts

@@ -69,8 +69,10 @@ export const TLIncompatibilityReason = {
  * @internal
  * @deprecated replaced by websocket .close status/reason
  */
+/* eslint-disable @typescript-eslint/no-deprecated */
 export type TLIncompatibilityReason =
 	(typeof TLIncompatibilityReason)[keyof typeof TLIncompatibilityReason]
+/* eslint-enable @typescript-eslint/no-deprecated */
 
 /**
  * Union type representing all possible message types that can be sent from server to client.

package/src/test/RandomSource.ts

@@ -19,7 +19,7 @@ export class RandomSource {
 	}
 
 	randomAction<Result>(
-		// eslint-disable-next-line @typescript-eslint/method-signature-style
+		// eslint-disable-next-line tldraw/method-signature-style
 		choices: Array<(() => Result) | { weight: number; do: () => any }>,
 		randomWeights?: boolean
 	): Result {