@tldraw/sync-core 4.1.0-next.b6dfe9bccde9 → 4.1.0-next.b9999db71010

package/src/lib/ClientWebSocketAdapter.ts

@@ -41,7 +41,37 @@ function debug(...args: any[]) {
 //       they don't seem to be surfaced in browser APIs and can't be relied on. Therefore,
 //       pings need to be implemented one level up, on the application API side, which for our
 //       codebase means whatever code that uses ClientWebSocketAdapter.
-/** @internal */
+/**
+ * A WebSocket adapter that provides persistent connection management for tldraw synchronization.
+ * This adapter handles connection establishment, reconnection logic, and message routing between
+ * the sync client and server. It implements automatic reconnection with exponential backoff
+ * and supports connection loss detection.
+ *
+ * Note: This adapter requires users to implement their own connection loss detection (e.g., pings)
+ * as browser WebSocket APIs don't reliably surface protocol-level ping/pong frames.
+ *
+ * @internal
+ * @example
+ * ```ts
+ * // Create a WebSocket adapter with connection URI
+ * const adapter = new ClientWebSocketAdapter(() => 'ws://localhost:3000/sync')
+ *
+ * // Listen for connection status changes
+ * adapter.onStatusChange((status) => {
+ *   console.log('Connection status:', status)
+ * })
+ *
+ * // Listen for incoming messages
+ * adapter.onReceiveMessage((message) => {
+ *   console.log('Received:', message)
+ * })
+ *
+ * // Send a message when connected
+ * if (adapter.connectionStatus === 'online') {
+ *   adapter.sendMessage({ type: 'ping' })
+ * }
+ * ```
+ */
 export class ClientWebSocketAdapter implements TLPersistentClientSocket<TLRecord> {
 	_ws: WebSocket | null = null
 
@@ -50,6 +80,11 @@ export class ClientWebSocketAdapter implements TLPersistentClientSocket<TLRecord
 	/** @internal */
 	readonly _reconnectManager: ReconnectManager
 
+	/**
+	 * Permanently closes the WebSocket adapter and disposes of all resources.
+	 * Once closed, the adapter cannot be reused and should be discarded.
+	 * This method is idempotent - calling it multiple times has no additional effect.
+	 */
 	// TODO: .close should be a project-wide interface with a common contract (.close()d thing
 	//       can only be garbage collected, and can't be used anymore)
 	close() {
@@ -59,6 +94,14 @@ export class ClientWebSocketAdapter implements TLPersistentClientSocket<TLRecord
 		this._ws?.close()
 	}
 
+	/**
+	 * Creates a new ClientWebSocketAdapter instance.
+	 *
+	 * @param getUri - Function that returns the WebSocket URI to connect to.
+	 *                 Can return a string directly or a Promise that resolves to a string.
+	 *                 This function is called each time a connection attempt is made,
+	 *                 allowing for dynamic URI generation (e.g., for authentication tokens).
+	 */
 	constructor(getUri: () => Promise<string> | string) {
 		this._reconnectManager = new ReconnectManager(this, getUri)
 	}
@@ -189,12 +232,31 @@ export class ClientWebSocketAdapter implements TLPersistentClientSocket<TLRecord
 		'initial'
 	)
 
+	/**
+	 * Gets the current connection status of the WebSocket.
+	 *
+	 * @returns The current connection status: 'online', 'offline', or 'error'
+	 */
 	// eslint-disable-next-line no-restricted-syntax
 	get connectionStatus(): TLPersistentClientSocketStatus {
 		const status = this._connectionStatus.get()
 		return status === 'initial' ? 'offline' : status
 	}
 
+	/**
+	 * Sends a message to the server through the WebSocket connection.
+	 * Messages are automatically chunked if they exceed size limits.
+	 *
+	 * @param msg - The message to send to the server
+	 *
+	 * @example
+	 * ```ts
+	 * adapter.sendMessage({
+	 *   type: 'push',
+	 *   diff: { 'shape:abc123': [2, { x: [1, 150] }] }
+	 * })
+	 * ```
+	 */
 	sendMessage(msg: TLSocketClientSentEvent<TLRecord>) {
 		assert(!this.isDisposed, 'Tried to send message on a disposed socket')
 
@@ -210,6 +272,29 @@ export class ClientWebSocketAdapter implements TLPersistentClientSocket<TLRecord
 	}
 
 	private messageListeners = new Set<(msg: TLSocketServerSentEvent<TLRecord>) => void>()
+	/**
+	 * Registers a callback to handle incoming messages from the server.
+	 *
+	 * @param cb - Callback function that will be called with each received message
+	 * @returns A cleanup function to remove the message listener
+	 *
+	 * @example
+	 * ```ts
+	 * const unsubscribe = adapter.onReceiveMessage((message) => {
+	 *   switch (message.type) {
+	 *     case 'connect':
+	 *       console.log('Connected to room')
+	 *       break
+	 *     case 'data':
+	 *       console.log('Received data:', message.diff)
+	 *       break
+	 *   }
+	 * })
+	 *
+	 * // Later, remove the listener
+	 * unsubscribe()
+	 * ```
+	 */
 	onReceiveMessage(cb: (val: TLSocketServerSentEvent<TLRecord>) => void) {
 		assert(!this.isDisposed, 'Tried to add message listener on a disposed socket')
 
@@ -220,6 +305,26 @@ export class ClientWebSocketAdapter implements TLPersistentClientSocket<TLRecord
 	}
 
 	private statusListeners = new Set<TLSocketStatusListener>()
+	/**
+	 * Registers a callback to handle connection status changes.
+	 *
+	 * @param cb - Callback function that will be called when the connection status changes
+	 * @returns A cleanup function to remove the status listener
+	 *
+	 * @example
+	 * ```ts
+	 * const unsubscribe = adapter.onStatusChange((status) => {
+	 *   if (status.status === 'error') {
+	 *     console.error('Connection error:', status.reason)
+	 *   } else {
+	 *     console.log('Status changed to:', status.status)
+	 *   }
+	 * })
+	 *
+	 * // Later, remove the listener
+	 * unsubscribe()
+	 * ```
+	 */
 	onStatusChange(cb: TLSocketStatusListener) {
 		assert(!this.isDisposed, 'Tried to add status listener on a disposed socket')
 
@@ -229,6 +334,19 @@ export class ClientWebSocketAdapter implements TLPersistentClientSocket<TLRecord
 		}
 	}
 
+	/**
+	 * Manually restarts the WebSocket connection.
+	 * This closes the current connection (if any) and attempts to establish a new one.
+	 * Useful for implementing connection loss detection and recovery.
+	 *
+	 * @example
+	 * ```ts
+	 * // Restart connection after detecting it's stale
+	 * if (lastPongTime < Date.now() - 30000) {
+	 *   adapter.restart()
+	 * }
+	 * ```
+	 */
 	restart() {
 		assert(!this.isDisposed, 'Tried to restart a disposed socket')
 		debug('restarting')
@@ -238,21 +356,78 @@ export class ClientWebSocketAdapter implements TLPersistentClientSocket<TLRecord
 	}
 }
 
-// Those constants are exported primarily for tests
-// ACTIVE_ means the tab is active, document.hidden is false
+/**
+ * Minimum reconnection delay in milliseconds when the browser tab is active and focused.
+ *
+ * @internal
+ */
 export const ACTIVE_MIN_DELAY = 500
+
+/**
+ * Maximum reconnection delay in milliseconds when the browser tab is active and focused.
+ *
+ * @internal
+ */
 export const ACTIVE_MAX_DELAY = 2000
-// Correspondingly, here document.hidden is true. It's intended to reduce the load and battery drain
-// on client devices somewhat when they aren't looking at the tab. We don't disconnect completely
-// to minimise issues with reconnection/sync when the tab becomes visible again
+
+/**
+ * Minimum reconnection delay in milliseconds when the browser tab is inactive or hidden.
+ * This longer delay helps reduce battery drain and server load when users aren't actively viewing the tab.
+ *
+ * @internal
+ */
 export const INACTIVE_MIN_DELAY = 1000
+
+/**
+ * Maximum reconnection delay in milliseconds when the browser tab is inactive or hidden.
+ * Set to 5 minutes to balance between maintaining sync and conserving resources.
+ *
+ * @internal
+ */
 export const INACTIVE_MAX_DELAY = 1000 * 60 * 5
+
+/**
+ * Exponential backoff multiplier for calculating reconnection delays.
+ * Each failed connection attempt increases the delay by this factor until max delay is reached.
+ *
+ * @internal
+ */
 export const DELAY_EXPONENT = 1.5
-// this is a tradeoff between quickly detecting connections stuck in the CONNECTING state and
-// not needlessly reconnecting if the connection is just slow to establish
+
+/**
+ * Maximum time in milliseconds to wait for a connection attempt before considering it failed.
+ * This helps detect connections stuck in the CONNECTING state and retry with fresh attempts.
+ *
+ * @internal
+ */
 export const ATTEMPT_TIMEOUT = 1000
 
-/** @internal */
+/**
+ * Manages automatic reconnection logic for WebSocket connections with intelligent backoff strategies.
+ * This class handles connection attempts, tracks connection state, and implements exponential backoff
+ * with different delays based on whether the browser tab is active or inactive.
+ *
+ * The ReconnectManager responds to various browser events like network status changes,
+ * tab visibility changes, and connection events to optimize reconnection timing and
+ * minimize unnecessary connection attempts.
+ *
+ * @internal
+ *
+ * @example
+ * ```ts
+ * const manager = new ReconnectManager(
+ *   socketAdapter,
+ *   () => 'ws://localhost:3000/sync'
+ * )
+ *
+ * // Manager automatically handles:
+ * // - Initial connection
+ * // - Reconnection on disconnect
+ * // - Exponential backoff on failures
+ * // - Tab visibility-aware delays
+ * // - Network status change responses
+ * ```
+ */
 export class ReconnectManager {
 	private isDisposed = false
 	private disposables: (() => void)[] = [
@@ -268,6 +443,12 @@ export class ReconnectManager {
 	intendedDelay: number = ACTIVE_MIN_DELAY
 	private state: 'pendingAttempt' | 'pendingAttemptResult' | 'delay' | 'connected'
 
+	/**
+	 * Creates a new ReconnectManager instance.
+	 *
+	 * socketAdapter - The ClientWebSocketAdapter instance to manage
+	 * getUri - Function that returns the WebSocket URI for connection attempts
+	 */
 	constructor(
 		private socketAdapter: ClientWebSocketAdapter,
 		private getUri: () => Promise<string> | string
@@ -356,6 +537,22 @@ export class ReconnectManager {
 		}
 	}
 
+	/**
+	 * Checks if reconnection should be attempted and initiates it if appropriate.
+	 * This method is called in response to network events, tab visibility changes,
+	 * and other hints that connectivity may have been restored.
+	 *
+	 * The method intelligently handles various connection states:
+	 * - Already connected: no action needed
+	 * - Currently connecting: waits or retries based on attempt age
+	 * - Disconnected: initiates immediate reconnection attempt
+	 *
+	 * @example
+	 * ```ts
+	 * // Called automatically on network/visibility events, but can be called manually
+	 * manager.maybeReconnected()
+	 * ```
+	 */
 	maybeReconnected() {
 		debug('ReconnectManager.maybeReconnected')
 		// It doesn't make sense to have another check scheduled if we're already checking it now.
@@ -409,6 +606,22 @@ export class ReconnectManager {
 		this.disconnected()
 	}
 
+	/**
+	 * Handles disconnection events and schedules reconnection attempts with exponential backoff.
+	 * This method is called when the WebSocket connection is lost or fails to establish.
+	 *
+	 * It implements intelligent delay calculation based on:
+	 * - Previous attempt timing
+	 * - Current tab visibility (active vs inactive delays)
+	 * - Exponential backoff for repeated failures
+	 *
+	 * @example
+	 * ```ts
+	 * // Called automatically when connection is lost
+	 * // Schedules reconnection with appropriate delay
+	 * manager.disconnected()
+	 * ```
+	 */
 	disconnected() {
 		debug('ReconnectManager.disconnected')
 		// This either means we're freshly disconnected, or the last connection attempt failed;
@@ -458,6 +671,19 @@ export class ReconnectManager {
 		}
 	}
 
+	/**
+	 * Handles successful connection events and resets reconnection state.
+	 * This method is called when the WebSocket successfully connects to the server.
+	 *
+	 * It clears any pending reconnection attempts and resets the delay back to minimum
+	 * for future connection attempts.
+	 *
+	 * @example
+	 * ```ts
+	 * // Called automatically when WebSocket opens successfully
+	 * manager.connected()
+	 * ```
+	 */
 	connected() {
 		debug('ReconnectManager.connected')
 		// this notification could've been delayed, recheck synchronously
@@ -469,6 +695,11 @@ export class ReconnectManager {
 		}
 	}
 
+	/**
+	 * Permanently closes the reconnection manager and cleans up all resources.
+	 * This stops all pending reconnection attempts and removes event listeners.
+	 * Once closed, the manager cannot be reused.
+	 */
 	close() {
 		this.disposables.forEach((d) => d())
 		this.isDisposed = true

package/src/lib/RoomSession.test.ts

@@ -0,0 +1,97 @@
+import { SerializedSchema } from '@tldraw/store'
+import { TLRecord } from '@tldraw/tlschema'
+import { describe, expect, it, vi } from 'vitest'
+import {
+	RoomSession,
+	RoomSessionState,
+	SESSION_IDLE_TIMEOUT,
+	SESSION_REMOVAL_WAIT_TIME,
+	SESSION_START_WAIT_TIME,
+} from './RoomSession'
+import { TLRoomSocket } from './TLSyncRoom'
+
+// Mock socket implementation for testing
+const createMockSocket = (): TLRoomSocket<TLRecord> => ({
+	isOpen: true,
+	sendMessage: vi.fn(),
+	close: vi.fn(),
+})
+
+// Mock serialized schema for testing
+const mockSerializedSchema: SerializedSchema = {
+	schemaVersion: 1,
+	storeVersion: 1,
+	recordVersions: {},
+}
+
+describe('RoomSession timeout constants', () => {
+	it('should have logical timeout ordering for session management', () => {
+		// This test ensures the timeout constants have a logical relationship
+		// that supports proper session lifecycle management:
+		// - Quick cleanup for disconnected sessions
+		// - Reasonable wait time for initial connections
+		// - Patient timeout for active sessions
+		expect(SESSION_REMOVAL_WAIT_TIME).toBeLessThan(SESSION_START_WAIT_TIME)
+		expect(SESSION_START_WAIT_TIME).toBeLessThan(SESSION_IDLE_TIMEOUT)
+	})
+})
+
+describe('RoomSession state transitions', () => {
+	const baseSessionData = {
+		sessionId: 'test-session-id',
+		presenceId: 'test-presence-id',
+		socket: createMockSocket(),
+		meta: { userId: 'test-user' },
+		isReadonly: false,
+		requiresLegacyRejection: false,
+	}
+
+	it('should support complete session lifecycle', () => {
+		// Test that sessions can progress through their full lifecycle
+		// This validates the discriminated union works correctly for state management
+
+		// Start in awaiting state
+		const initialSession: RoomSession<TLRecord, { userId: string }> = {
+			state: RoomSessionState.AwaitingConnectMessage,
+			sessionStartTime: Date.now(),
+			...baseSessionData,
+		}
+
+		// Progress to connected state (simulates successful connection)
+		const connectedSession: RoomSession<TLRecord, { userId: string }> = {
+			state: RoomSessionState.Connected,
+			sessionId: initialSession.sessionId,
+			presenceId: initialSession.presenceId,
+			socket: initialSession.socket,
+			meta: initialSession.meta,
+			isReadonly: initialSession.isReadonly,
+			requiresLegacyRejection: initialSession.requiresLegacyRejection,
+			serializedSchema: mockSerializedSchema,
+			lastInteractionTime: Date.now(),
+			debounceTimer: null,
+			outstandingDataMessages: [],
+		}
+
+		// End in awaiting removal state (simulates disconnection)
+		const removalSession: RoomSession<TLRecord, { userId: string }> = {
+			state: RoomSessionState.AwaitingRemoval,
+			sessionId: connectedSession.sessionId,
+			presenceId: connectedSession.presenceId,
+			socket: connectedSession.socket,
+			meta: connectedSession.meta,
+			isReadonly: connectedSession.isReadonly,
+			requiresLegacyRejection: connectedSession.requiresLegacyRejection,
+			cancellationTime: Date.now(),
+		}
+
+		// Verify session ID remains consistent across state changes
+		// This is critical for tracking sessions through their lifecycle
+		expect(initialSession.sessionId).toBe(connectedSession.sessionId)
+		expect(connectedSession.sessionId).toBe(removalSession.sessionId)
+
+		// Verify state-specific properties are present when expected
+		expect(initialSession.state).toBe(RoomSessionState.AwaitingConnectMessage)
+		expect(connectedSession.state).toBe(RoomSessionState.Connected)
+		expect(removalSession.state).toBe(RoomSessionState.AwaitingRemoval)
+	})
+})

package/src/lib/RoomSession.ts

@@ -2,52 +2,154 @@ import { SerializedSchema, UnknownRecord } from '@tldraw/store'
 import { TLRoomSocket } from './TLSyncRoom'
 import { TLSocketServerSentDataEvent } from './protocol'
 
-/** @internal */
+/**
+ * Enumeration of possible states for a room session during its lifecycle.
+ *
+ * Room sessions progress through these states as clients connect, authenticate,
+ * and disconnect from collaborative rooms.
+ *
+ * @internal
+ */
 export const RoomSessionState = {
+	/** Session is waiting for the initial connect message from the client */
 	AwaitingConnectMessage: 'awaiting-connect-message',
+	/** Session is disconnected but waiting for final cleanup before removal */
 	AwaitingRemoval: 'awaiting-removal',
+	/** Session is fully connected and actively synchronizing */
 	Connected: 'connected',
 } as const
 
-/** @internal */
+/**
+ * Type representing the possible states a room session can be in.
+ *
+ * @example
+ * ```ts
+ * const sessionState: RoomSessionState = RoomSessionState.Connected
+ * if (sessionState === RoomSessionState.AwaitingConnectMessage) {
+ *   console.log('Session waiting for connect message')
+ * }
+ * ```
+ *
+ * @internal
+ */
 export type RoomSessionState = (typeof RoomSessionState)[keyof typeof RoomSessionState]
 
+/**
+ * Maximum time in milliseconds to wait for a connect message after socket connection.
+ *
+ * If a client connects but doesn't send a connect message within this time,
+ * the session will be terminated.
+ *
+ * @public
+ */
 export const SESSION_START_WAIT_TIME = 10000
+
+/**
+ * Time in milliseconds to wait before completely removing a disconnected session.
+ *
+ * This grace period allows for quick reconnections without losing session state,
+ * which is especially helpful for brief network interruptions.
+ *
+ * @public
+ */
 export const SESSION_REMOVAL_WAIT_TIME = 5000
+
+/**
+ * Maximum time in milliseconds a connected session can remain idle before cleanup.
+ *
+ * Sessions that don't receive any messages or interactions for this duration
+ * may be considered for cleanup to free server resources.
+ *
+ * @public
+ */
 export const SESSION_IDLE_TIMEOUT = 20000
 
-/** @internal */
+/**
+ * Represents a client session within a collaborative room, tracking the connection
+ * state, permissions, and synchronization details for a single user.
+ *
+ * Each session corresponds to one WebSocket connection and progresses through
+ * different states during its lifecycle. The session type is a discriminated union
+ * based on the current state, ensuring type safety when accessing state-specific properties.
+ *
+ * @example
+ * ```ts
+ * // Check session state and access appropriate properties
+ * function handleSession(session: RoomSession<MyRecord, UserMeta>) {
+ *   switch (session.state) {
+ *     case RoomSessionState.AwaitingConnectMessage:
+ *       console.log(`Session ${session.sessionId} started at ${session.sessionStartTime}`)
+ *       break
+ *     case RoomSessionState.Connected:
+ *       console.log(`Connected session has ${session.outstandingDataMessages.length} pending messages`)
+ *       break
+ *     case RoomSessionState.AwaitingRemoval:
+ *       console.log(`Session will be removed at ${session.cancellationTime}`)
+ *       break
+ *   }
+ * }
+ * ```
+ *
+ * @internal
+ */
 export type RoomSession<R extends UnknownRecord, Meta> =
 	| {
+			/** Current state of the session */
 			state: typeof RoomSessionState.AwaitingConnectMessage
+			/** Unique identifier for this session */
 			sessionId: string
+			/** Presence identifier for live cursor/selection tracking, if available */
 			presenceId: string | null
+			/** WebSocket connection wrapper for this session */
 			socket: TLRoomSocket<R>
+			/** Timestamp when the session was created */
 			sessionStartTime: number
+			/** Custom metadata associated with this session */
 			meta: Meta
+			/** Whether this session has read-only permissions */
 			isReadonly: boolean
+			/** Whether this session requires legacy protocol rejection handling */
 			requiresLegacyRejection: boolean
 	  }
 	| {
+			/** Current state of the session */
 			state: typeof RoomSessionState.AwaitingRemoval
+			/** Unique identifier for this session */
 			sessionId: string
+			/** Presence identifier for live cursor/selection tracking, if available */
 			presenceId: string | null
+			/** WebSocket connection wrapper for this session */
 			socket: TLRoomSocket<R>
+			/** Timestamp when the session was marked for removal */
 			cancellationTime: number
+			/** Custom metadata associated with this session */
 			meta: Meta
+			/** Whether this session has read-only permissions */
 			isReadonly: boolean
+			/** Whether this session requires legacy protocol rejection handling */
 			requiresLegacyRejection: boolean
 	  }
 	| {
+			/** Current state of the session */
 			state: typeof RoomSessionState.Connected
+			/** Unique identifier for this session */
 			sessionId: string
+			/** Presence identifier for live cursor/selection tracking, if available */
 			presenceId: string | null
+			/** WebSocket connection wrapper for this session */
 			socket: TLRoomSocket<R>
+			/** Serialized schema information for this connected session */
 			serializedSchema: SerializedSchema
+			/** Timestamp of the last interaction or message from this session */
 			lastInteractionTime: number
+			/** Timer for debouncing operations, if active */
 			debounceTimer: ReturnType<typeof setTimeout> | null
+			/** Queue of data messages waiting to be sent to this session */
 			outstandingDataMessages: TLSocketServerSentDataEvent<R>[]
+			/** Custom metadata associated with this session */
 			meta: Meta
+			/** Whether this session has read-only permissions */
 			isReadonly: boolean
+			/** Whether this session requires legacy protocol rejection handling */
 			requiresLegacyRejection: boolean
 	  }