@tldraw/sync-core 4.3.0 → 4.4.0-canary.15cff7ea86f8

package/src/lib/TLSyncClient.ts

@@ -5,16 +5,24 @@ import {
 	Store,
 	UnknownRecord,
 	reverseRecordsDiff,
-	squashRecordDiffs,
+	squashRecordDiffsMutable,
 } from '@tldraw/store'
 import {
+	FpsScheduler,
 	exhaustiveSwitchError,
-	fpsThrottle,
 	isEqual,
 	objectMapEntries,
+	structuredClone,
 	uniqueId,
 } from '@tldraw/utils'
-import { NetworkDiff, RecordOpType, applyObjectDiff, diffRecord, getNetworkDiff } from './diff'
+import {
+	NetworkDiff,
+	ObjectDiff,
+	RecordOpType,
+	applyObjectDiff,
+	diffRecord,
+	getNetworkDiff,
+} from './diff'
 import { interval } from './interval'
 import {
 	TLPushRequest,
@@ -35,6 +43,12 @@ import {
  */
 export type SubscribingFn<T> = (cb: (val: T) => void) => () => void
 
+/** Network sync frame rate when in solo mode (no collaborators) @internal */
+const SOLO_MODE_FPS = 1
+
+/** Network sync frame rate when in collaborative mode (with collaborators) @internal */
+const COLLABORATIVE_MODE_FPS = 30
+
 /**
  * WebSocket close code used by the server to signal a non-recoverable sync error.
  * This close code indicates that the connection is being terminated due to an error
@@ -275,6 +289,21 @@ const MAX_TIME_TO_WAIT_FOR_SERVER_INTERACTION_BEFORE_RESETTING_CONNECTION = PING
 
 // Should connect support chunking the response to allow for large payloads?
 
+function getPresenceOp<R extends UnknownRecord>(
+	lastPushedPresenceState: R | null,
+	nextPresence: R | null
+): [typeof RecordOpType.Patch, ObjectDiff] | [typeof RecordOpType.Put, R] | undefined {
+	if (!lastPushedPresenceState && nextPresence) {
+		return [RecordOpType.Put, nextPresence]
+	}
+	if (lastPushedPresenceState && nextPresence) {
+		const diff = diffRecord(lastPushedPresenceState, nextPresence)
+		if (!diff) return undefined
+		return [RecordOpType.Patch, diff]
+	}
+	return undefined
+}
+
 /**
  * Main client-side synchronization engine for collaborative tldraw applications.
  *
@@ -340,7 +369,11 @@ export class TLSyncClient<R extends UnknownRecord, S extends Store<R> = Store<R>
 	private lastServerInteractionTimestamp = Date.now()
 
 	/** The queue of in-flight push requests that have not yet been acknowledged by the server */
-	private pendingPushRequests: { request: TLPushRequest<R>; sent: boolean }[] = []
+	private pendingPushRequests: TLPushRequest<R>[] = []
+	private unsentChanges: {
+		nextDiff?: RecordsDiff<R>
+		nextPresence?: R | null
+	} = { nextDiff: undefined, nextPresence: undefined }
 
 	/**
 	 * The diff of 'unconfirmed', 'optimistic' changes that have been made locally by the user if we
@@ -355,6 +388,21 @@ export class TLSyncClient<R extends UnknownRecord, S extends Store<R> = Store<R>
 
 	private disposables: Array<() => void> = []
 
+	/** Separate scheduler instance for network sync operations */
+	private readonly fpsScheduler: FpsScheduler
+
+	/** Send any unsent push requests to the server */
+	private readonly sendUnsentChanges: {
+		(): void
+		cancel?(): void
+	}
+
+	/** Schedule a rebase operation */
+	private readonly scheduleRebase: {
+		(): void
+		cancel?(): void
+	}
+
 	/** @internal */
 	readonly store: S
 	/** @internal */
@@ -438,6 +486,54 @@ export class TLSyncClient<R extends UnknownRecord, S extends Store<R> = Store<R>
 
 		this.presenceType = config.store.scopedTypes.presence.values().next().value ?? null
 
+		// Create a separate throttle instance for network sync operations
+		// This ensures sync operations have their own queue separate from UI operations
+		this.fpsScheduler = new FpsScheduler(COLLABORATIVE_MODE_FPS)
+
+		// Initialize throttled methods after throttle instance is created
+		this.sendUnsentChanges = this.fpsScheduler.fpsThrottle(() => {
+			this.debug('sending unsent changes', {
+				isConnectedToRoom: this.isConnectedToRoom,
+				unsentChanges: this.unsentChanges,
+			})
+			if (!this.isConnectedToRoom || this.store.isPossiblyCorrupted()) {
+				return
+			}
+			if (!this.unsentChanges.nextDiff && !this.unsentChanges.nextPresence) {
+				return
+			}
+			const diff = this.unsentChanges.nextDiff
+				? (getNetworkDiff(this.unsentChanges.nextDiff) ?? undefined)
+				: undefined
+			const presence = this.unsentChanges.nextPresence
+				? getPresenceOp<R>(this.lastPushedPresenceState, this.unsentChanges.nextPresence)
+				: undefined
+
+			if (!diff && !presence) {
+				return
+			}
+
+			const pushRequest: TLPushRequest<R> = {
+				type: 'push',
+				clientClock: this.clientClock,
+				diff,
+				presence,
+			}
+
+			this.debug('sending push request', pushRequest)
+			this.socket.sendMessage(pushRequest)
+
+			if (this.unsentChanges.nextPresence) {
+				this.lastPushedPresenceState = this.unsentChanges.nextPresence
+			}
+			this.clientClock++
+			this.pendingPushRequests.push(pushRequest)
+			this.unsentChanges.nextDiff = undefined
+			this.unsentChanges.nextPresence = undefined
+		})
+
+		this.scheduleRebase = this.fpsScheduler.fpsThrottle(this.rebase)
+
 		if (typeof window !== 'undefined') {
 			;(window as any).tlsync = this
 		}
@@ -528,6 +624,7 @@ export class TLSyncClient<R extends UnknownRecord, S extends Store<R> = Store<R>
 				react('pushPresence', () => {
 					if (this.didCancel?.()) return this.close()
 					const mode = this.presenceMode?.get()
+					this.fpsScheduler.updateTargetFps(this.getSyncFps())
 					if (mode !== 'full') return
 					this.pushPresence(this.presenceState!.get())
 				})
@@ -581,6 +678,8 @@ export class TLSyncClient<R extends UnknownRecord, S extends Store<R> = Store<R>
 		this.isConnectedToRoom = false
 		this.pendingPushRequests = []
 		this.incomingDiffBuffer = []
+		this.unsentChanges.nextDiff = undefined
+		this.unsentChanges.nextPresence = undefined
 		if (this.socket.connectionStatus === 'online') {
 			this.socket.restart()
 		}
@@ -645,9 +744,11 @@ export class TLSyncClient<R extends UnknownRecord, S extends Store<R> = Store<R>
 
 				// now re-apply the speculative changes creating a new push request with the
 				// appropriate diff
+				const networkDiff = getNetworkDiff(stashedChanges)
+				if (!networkDiff) return
 				const speculativeChanges = this.store.filterChangesByScope(
 					this.store.extractingChanges(() => {
-						this.store.applyDiff(stashedChanges)
+						this.applyNetworkDiff(networkDiff, true)
 					}),
 					'document'
 				)
@@ -723,7 +824,7 @@ export class TLSyncClient<R extends UnknownRecord, S extends Store<R> = Store<R>
 	close() {
 		this.debug('closing')
 		this.disposables.forEach((dispose) => dispose())
-		this.flushPendingPushRequests.cancel?.()
+		this.sendUnsentChanges.cancel?.()
 		this.scheduleRebase.cancel?.()
 	}
 
@@ -738,100 +839,28 @@ export class TLSyncClient<R extends UnknownRecord, S extends Store<R> = Store<R>
 			return
 		}
 
-		let presence: TLPushRequest<any>['presence'] = undefined
-		if (!this.lastPushedPresenceState && nextPresence) {
-			// we don't have a last presence state, so we need to push the full state
-			presence = [RecordOpType.Put, nextPresence]
-		} else if (this.lastPushedPresenceState && nextPresence) {
-			// we have a last presence state, so we need to push a diff if there is one
-			const diff = diffRecord(this.lastPushedPresenceState, nextPresence)
-			if (diff) {
-				presence = [RecordOpType.Patch, diff]
-			}
-		}
-
-		if (!presence) return
-		this.lastPushedPresenceState = nextPresence
-
-		// if there is a pending push that has not been sent and does not already include a presence update,
-		// then add this presence update to it
-		const lastPush = this.pendingPushRequests.at(-1)
-		if (lastPush && !lastPush.sent && !lastPush.request.presence) {
-			lastPush.request.presence = presence
-			return
-		}
-
-		// otherwise, create a new push request
-		const req: TLPushRequest<R> = {
-			type: 'push',
-			clientClock: this.clientClock++,
-			presence,
-		}
-
-		if (req) {
-			this.pendingPushRequests.push({ request: req, sent: false })
-			this.flushPendingPushRequests()
-		}
+		this.unsentChanges.nextPresence = nextPresence
+		this.sendUnsentChanges()
 	}
 
 	/** Push a change to the server, or stash it locally if we're offline */
 	private push(change: RecordsDiff<any>) {
 		this.debug('push', change)
-		// the Store doesn't do deep equality checks when making changes
-		// so it's possible that the diff passed in here is actually a no-op.
-		// either way, we also don't want to send whole objects over the wire if
-		// only small parts of them have changed, so we'll do a shallow-ish diff
-		// which also uses deep equality checks to see if the change is actually
-		// a no-op.
-		const diff = getNetworkDiff(change)
-		if (!diff) return
-
-		// the change is not a no-op so we'll send it to the server
-		// but first let's merge the records diff into the speculative changes
-		this.speculativeChanges = squashRecordDiffs([this.speculativeChanges, change])
-
-		if (!this.isConnectedToRoom) {
-			// don't sent push requests or even store them up while offline
-			// when we come back online we'll generate another push request from
-			// scratch based on the speculativeChanges diff
-			return
-		}
-
-		const pushRequest: TLPushRequest<R> = {
-			type: 'push',
-			diff,
-			clientClock: this.clientClock++,
+		squashRecordDiffsMutable(this.speculativeChanges, [change])
+		// in offline mode, we only accumulate in speculativeChanges
+		if (!this.isConnectedToRoom) return
+		if (!this.unsentChanges.nextDiff) {
+			this.unsentChanges.nextDiff = structuredClone(change)
+		} else {
+			squashRecordDiffsMutable(this.unsentChanges.nextDiff, [change])
 		}
-
-		this.pendingPushRequests.push({ request: pushRequest, sent: false })
-
-		// immediately calling .send on the websocket here was causing some interaction
-		// slugishness when e.g. drawing or translating shapes. Seems like it blocks
-		// until the send completes. So instead we'll schedule a send to happen on some
-		// tick in the near future.
-		this.flushPendingPushRequests()
+		this.sendUnsentChanges()
 	}
 
-	/** Send any unsent push requests to the server */
-	private flushPendingPushRequests = fpsThrottle(() => {
-		this.debug('flushing pending push requests', {
-			isConnectedToRoom: this.isConnectedToRoom,
-			pendingPushRequests: this.pendingPushRequests,
-		})
-		if (!this.isConnectedToRoom || this.store.isPossiblyCorrupted()) {
-			return
-		}
-		for (const pendingPushRequest of this.pendingPushRequests) {
-			if (!pendingPushRequest.sent) {
-				if (this.socket.connectionStatus !== 'online') {
-					// we went offline, so don't send anything
-					return
-				}
-				this.socket.sendMessage(pendingPushRequest.request)
-				pendingPushRequest.sent = true
-			}
-		}
-	})
+	/** Get the target FPS for network operations based on presence mode */
+	private getSyncFps(): number {
+		return this.presenceMode?.get() === 'solo' ? SOLO_MODE_FPS : COLLABORATIVE_MODE_FPS
+	}
 
 	/**
 	 * Applies a 'network' diff to the store this does value-based equality checking so that if the
@@ -899,7 +928,7 @@ export class TLSyncClient<R extends UnknownRecord, S extends Store<R> = Store<R>
 					if (this.pendingPushRequests.length === 0) {
 						throw new Error('Received push_result but there are no pending push requests')
 					}
-					if (this.pendingPushRequests[0].request.clientClock !== diff.clientClock) {
+					if (this.pendingPushRequests[0].clientClock !== diff.clientClock) {
 						throw new Error(
 							'Received push_result for a push request that is not at the front of the queue'
 						)
@@ -907,7 +936,7 @@ export class TLSyncClient<R extends UnknownRecord, S extends Store<R> = Store<R>
 					if (diff.action === 'discard') {
 						this.pendingPushRequests.shift()
 					} else if (diff.action === 'commit') {
-						const { request } = this.pendingPushRequests.shift()!
+						const request = this.pendingPushRequests.shift()!
 						if ('diff' in request && request.diff) {
 							this.applyNetworkDiff(request.diff, true)
 						}
@@ -919,10 +948,14 @@ export class TLSyncClient<R extends UnknownRecord, S extends Store<R> = Store<R>
 				// update the speculative diff while re-applying pending changes
 				try {
 					this.speculativeChanges = this.store.extractingChanges(() => {
-						for (const { request } of this.pendingPushRequests) {
+						for (const request of this.pendingPushRequests) {
 							if (!('diff' in request) || !request.diff) continue
 							this.applyNetworkDiff(request.diff, true)
 						}
+						if (!this.unsentChanges.nextDiff) return
+						const diff = getNetworkDiff(this.unsentChanges.nextDiff)
+						if (!diff) return
+						this.applyNetworkDiff(diff, true)
 					})
 				} catch (e) {
 					console.error(e)
@@ -938,6 +971,4 @@ export class TLSyncClient<R extends UnknownRecord, S extends Store<R> = Store<R>
 			this.resetConnection()
 		}
 	}
-
-	private scheduleRebase = fpsThrottle(this.rebase)
 }