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

package/src/lib/ServerSocketAdapter.test.ts

@@ -0,0 +1,228 @@
+import { UnknownRecord } from '@tldraw/store'
+import { describe, expect, it, vi } from 'vitest'
+import { ServerSocketAdapter, WebSocketMinimal } from './ServerSocketAdapter'
+import { TLSocketServerSentEvent } from './protocol'
+
+// Mock WebSocket implementations for testing different scenarios
+class MockWebSocket implements WebSocketMinimal {
+	readyState: number = 1 // OPEN by default
+	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
+}
+
+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'])
+		})
+	})
+
+	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)
+		})
+	})
+
+	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('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')
+		})
+
+		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',
+			}
+
+			expect(() => adapter.sendMessage(message)).toThrow('Callback error')
+			expect(faultyCallback).toHaveBeenCalled()
+			// WebSocket send should not be called if callback throws
+			expect(mockWs.send).not.toHaveBeenCalled()
+		})
+	})
+
+	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)
+
+				const message: TLSocketServerSentEvent<UnknownRecord> = {
+					type: 'pong',
+				}
+
+				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)
+
+			mockWs.readyState = 2 // CLOSING
+			expect(adapter.isOpen).toBe(false)
+
+			mockWs.readyState = 3 // CLOSED
+			expect(adapter.isOpen).toBe(false)
+
+			mockWs.readyState = 1 // OPEN
+			expect(adapter.isOpen).toBe(true)
+		})
+	})
+})

package/src/lib/ServerSocketAdapter.ts

@@ -3,49 +3,168 @@ import { TLRoomSocket } from './TLSyncRoom'
 import { TLSocketServerSentEvent } from './protocol'
 
 /**
- * Minimal server-side WebSocket interface that is compatible with
+ * Minimal server-side WebSocket interface that is compatible with various WebSocket implementations.
+ * This interface abstracts over different WebSocket libraries and platforms to provide a consistent
+ * API for the ServerSocketAdapter.
  *
- * - The standard WebSocket interface (cloudflare, deno, some node setups)
- * - The 'ws' WebSocket interface (some node setups)
+ * Supports:
+ * - The standard WebSocket interface (Cloudflare, Deno, some Node.js setups)
+ * - The 'ws' WebSocket interface (Node.js ws library)
  * - The Bun.serve socket implementation
  *
  * @public
+ * @example
+ * ```ts
+ * // Standard WebSocket
+ * const standardWs: WebSocketMinimal = new WebSocket('ws://localhost:8080')
+ *
+ * // Node.js 'ws' library WebSocket
+ * import WebSocket from 'ws'
+ * const nodeWs: WebSocketMinimal = new WebSocket('ws://localhost:8080')
+ *
+ * // Bun WebSocket (in server context)
+ * // const bunWs: WebSocketMinimal = server.upgrade(request)
+ * ```
  */
 export interface WebSocketMinimal {
+	/**
+	 * Optional method to add event listeners for WebSocket events.
+	 * Not all WebSocket implementations provide this method.
+	 *
+	 * @param type - The event type to listen for
+	 * @param listener - The event handler function
+	 */
 	// eslint-disable-next-line @typescript-eslint/method-signature-style
 	addEventListener?: (type: 'message' | 'close' | 'error', listener: (event: any) => void) => void
+
+	/**
+	 * Optional method to remove event listeners for WebSocket events.
+	 * Not all WebSocket implementations provide this method.
+	 *
+	 * @param type - The event type to stop listening for
+	 * @param listener - The event handler function to remove
+	 */
 	// eslint-disable-next-line @typescript-eslint/method-signature-style
 	removeEventListener?: (
 		type: 'message' | 'close' | 'error',
 		listener: (event: any) => void
 	) => void
+
+	/**
+	 * Sends a string message through the WebSocket connection.
+	 *
+	 * @param data - The string data to send
+	 */
 	// eslint-disable-next-line @typescript-eslint/method-signature-style
 	send: (data: string) => void
+
+	/**
+	 * Closes the WebSocket connection.
+	 *
+	 * @param code - Optional close code (default: 1000 for normal closure)
+	 * @param reason - Optional human-readable close reason
+	 */
 	// eslint-disable-next-line @typescript-eslint/method-signature-style
 	close: (code?: number, reason?: string) => void
+
+	/**
+	 * The current state of the WebSocket connection.
+	 * - 0: CONNECTING
+	 * - 1: OPEN
+	 * - 2: CLOSING
+	 * - 3: CLOSED
+	 */
 	readyState: number
 }
 
-/** @internal */
+/**
+ * Configuration options for creating a ServerSocketAdapter instance.
+ *
+ * @internal
+ */
 export interface ServerSocketAdapterOptions<R extends UnknownRecord> {
+	/** The underlying WebSocket connection to wrap */
 	readonly ws: WebSocketMinimal
+
+	/**
+	 * Optional callback invoked before each message is sent to the client.
+	 * Useful for logging, metrics, or message transformation.
+	 *
+	 * @param msg - The message object being sent
+	 * @param stringified - The JSON stringified version of the message
+	 */
 	// eslint-disable-next-line @typescript-eslint/method-signature-style
 	readonly onBeforeSendMessage?: (msg: TLSocketServerSentEvent<R>, stringified: string) => void
 }
 
-/** @internal */
+/**
+ * Server-side adapter that wraps various WebSocket implementations to provide a consistent
+ * TLRoomSocket interface for the TLSyncRoom. This adapter handles the differences between
+ * WebSocket libraries and platforms, allowing sync-core to work across different server
+ * environments.
+ *
+ * The adapter implements the TLRoomSocket interface, providing methods for sending messages,
+ * checking connection status, and closing connections.
+ *
+ * @internal
+ * @example
+ * ```ts
+ * import { ServerSocketAdapter } from '@tldraw/sync-core'
+ *
+ * // Wrap a standard WebSocket
+ * const adapter = new ServerSocketAdapter({
+ *   ws: webSocketConnection,
+ *   onBeforeSendMessage: (msg, json) => {
+ *     console.log('Sending:', msg.type)
+ *   }
+ * })
+ *
+ * // Use with TLSyncRoom
+ * room.handleNewSession({
+ *   sessionId: 'session-123',
+ *   socket: adapter,
+ *   isReadonly: false
+ * })
+ * ```
+ */
 export class ServerSocketAdapter<R extends UnknownRecord> implements TLRoomSocket<R> {
+	/**
+	 * Creates a new ServerSocketAdapter instance.
+	 *
+	 * opts - Configuration options for the adapter
+	 */
 	constructor(public readonly opts: ServerSocketAdapterOptions<R>) {}
+
+	/**
+	 * Checks if the underlying WebSocket connection is currently open and ready to send messages.
+	 *
+	 * @returns True if the connection is open (readyState === 1), false otherwise
+	 */
 	// eslint-disable-next-line no-restricted-syntax
 	get isOpen(): boolean {
 		return this.opts.ws.readyState === 1 // ready state open
 	}
+
+	/**
+	 * Sends a sync protocol message to the connected client. The message is JSON stringified
+	 * before being sent through the WebSocket. If configured, the onBeforeSendMessage callback
+	 * is invoked before sending.
+	 *
+	 * @param msg - The sync protocol message to send
+	 */
 	// see TLRoomSocket for details on why this accepts a union and not just arrays
 	sendMessage(msg: TLSocketServerSentEvent<R>) {
 		const message = JSON.stringify(msg)
 		this.opts.onBeforeSendMessage?.(msg, message)
 		this.opts.ws.send(message)
 	}
+
+	/**
+	 * Closes the WebSocket connection with an optional close code and reason.
+	 *
+	 * @param code - Optional close code (default: 1000 for normal closure)
+	 * @param reason - Optional human-readable reason for closing
+	 */
 	close(code?: number, reason?: string) {
 		this.opts.ws.close(code, reason)
 	}

package/src/lib/TLRemoteSyncError.ts

@@ -1,8 +1,57 @@
 import { TLSyncErrorCloseEventReason } from './TLSyncClient'
 
-/** @public */
+/**
+ * Specialized error class for synchronization-related failures in tldraw collaboration.
+ *
+ * This error is thrown when the sync client encounters fatal errors that prevent
+ * successful synchronization with the server. It captures both the error message
+ * and the specific reason code that triggered the failure.
+ *
+ * Common scenarios include schema version mismatches, authentication failures,
+ * network connectivity issues, and server-side validation errors.
+ *
+ * @example
+ * ```ts
+ * import { TLRemoteSyncError, TLSyncErrorCloseEventReason } from '@tldraw/sync-core'
+ *
+ * // Handle sync errors in your application
+ * syncClient.onSyncError((error) => {
+ *   if (error instanceof TLRemoteSyncError) {
+ *     switch (error.reason) {
+ *       case TLSyncErrorCloseEventReason.NOT_AUTHENTICATED:
+ *         // Redirect user to login
+ *         break
+ *       case TLSyncErrorCloseEventReason.CLIENT_TOO_OLD:
+ *         // Show update required message
+ *         break
+ *       default:
+ *         console.error('Sync error:', error.message)
+ *     }
+ *   }
+ * })
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Server-side: throwing a sync error
+ * if (!hasPermission(userId, roomId)) {
+ *   throw new TLRemoteSyncError(TLSyncErrorCloseEventReason.FORBIDDEN)
+ * }
+ * ```
+ *
+ * @public
+ */
 export class TLRemoteSyncError extends Error {
 	override name = 'RemoteSyncError'
+
+	/**
+	 * Creates a new TLRemoteSyncError with the specified reason.
+	 *
+	 * reason - The specific reason code or custom string describing why the sync failed.
+	 *                 When using predefined reasons from TLSyncErrorCloseEventReason, the client
+	 *                 can handle specific error types appropriately. Custom strings allow for
+	 *                 application-specific error details.
+	 */
 	constructor(public readonly reason: TLSyncErrorCloseEventReason | string) {
 		super(`sync error: ${reason}`)
 	}