Skip to content
Source
Sign inSign up
TanStack/db
Open History to see the last commit

TransactionExecutor.ts

435 lines12.5 KB

1import { createTransaction } from '@tanstack/db'
2import { DefaultRetryPolicy } from '../retry/RetryPolicy'
3import { NonRetriableError } from '../types'
4import { withNestedSpan } from '../telemetry/tracer'
5import type { KeyScheduler } from './KeyScheduler'
6import type { OutboxManager } from '../outbox/OutboxManager'
7import type {
8 OfflineConfig,
9 OfflineTransaction,
10 TransactionSignaler,
11} from '../types'
12​
13const HANDLED_EXECUTION_ERROR = Symbol(`HandledExecutionError`)
14​
15export class TransactionExecutor {
16 private scheduler: KeyScheduler
17 private outbox: OutboxManager
18 private config: OfflineConfig
19 private retryPolicy: DefaultRetryPolicy
20 private isExecuting = false
21 private executionPromise: Promise<void> | null = null
22 private offlineExecutor: TransactionSignaler
23 private retryTimer: ReturnType<typeof setTimeout> | null = null
24​
25 constructor(
26 scheduler: KeyScheduler,
27 outbox: OutboxManager,
28 config: OfflineConfig,
29 offlineExecutor: TransactionSignaler,
30 ) {
31 this.scheduler = scheduler
32 this.outbox = outbox
33 this.config = config
34 this.retryPolicy = new DefaultRetryPolicy(
35 Number.POSITIVE_INFINITY,
36 config.jitter ?? true,
37 )
38 this.offlineExecutor = offlineExecutor
39 }
40​
41 async execute(transaction: OfflineTransaction): Promise<void> {
42 this.scheduler.schedule(transaction)
43 await this.executeAll()
44 }
45​
46 async executeAll(): Promise<void> {
47 if (this.isExecuting) {
48 return this.executionPromise!
49 }
50​
51 this.isExecuting = true
52 this.executionPromise = this.runExecution()
53​
54 try {
55 await this.executionPromise
56 } finally {
57 this.isExecuting = false
58 this.executionPromise = null
59 this.scheduleNextRetry()
60 }
61 }
62​
63 private async runExecution(): Promise<void> {
64 while (this.scheduler.getPendingCount() > 0) {
65 if (!this.canExecute()) {
66 break
67 }
68​
69 const transaction = this.scheduler.getNext()
70​
71 if (!transaction) {
72 break
73 }
74​
75 await this.executeTransaction(transaction)
76 }
77 }
78​
79 private async executeTransaction(
80 transaction: OfflineTransaction,
81 ): Promise<void> {
82 try {
83 await withNestedSpan(
84 `transaction.execute`,
85 {
86 'transaction.id': transaction.id,
87 'transaction.mutationFnName': transaction.mutationFnName,
88 'transaction.retryCount': transaction.retryCount,
89 'transaction.keyCount': transaction.keys.length,
90 },
91 async (span) => {
92 this.scheduler.markStarted(transaction)
93​
94 if (transaction.retryCount > 0) {
95 span.setAttribute(`retry.attempt`, transaction.retryCount)
96 }
97​
98 let result: void
99 try {
100 result = await this.runMutationFn(transaction)
101 } catch (error) {
102 const err =
103 error instanceof Error ? error : new Error(String(error))
104​
105 span.setAttribute(`result`, `error`)
106​
107 await this.handleError(transaction, err)
108 ;(err as any)[HANDLED_EXECUTION_ERROR] = true
109 throw err
110 }
111​
112 let removalError: unknown
113 try {
114 // Replay can still see this ID until durable deletion settles.
115 await this.outbox.remove(transaction.id)
116 } catch (error) {
117 removalError = error
118 } finally {
119 this.scheduler.markCompleted(transaction)
120 }
121​
122 span.setAttribute(`result`, `success`)
123 this.offlineExecutor.resolveTransaction(transaction.id, result)
124 if (removalError !== undefined) throw removalError
125 },
126 )
127 } catch (error) {
128 if (
129 error instanceof Error &&
130 (error as any)[HANDLED_EXECUTION_ERROR] === true
131 ) {
132 return
133 }
134​
135 throw error
136 }
137 }
138​
139 private async runMutationFn(transaction: OfflineTransaction): Promise<void> {
140 const mutationFn = this.config.mutationFns[transaction.mutationFnName]
141​
142 if (!mutationFn) {
143 const errorMessage = `Unknown mutation function: ${transaction.mutationFnName}`
144​
145 if (this.config.onUnknownMutationFn) {
146 this.config.onUnknownMutationFn(transaction.mutationFnName, transaction)
147 }
148​
149 throw new NonRetriableError(errorMessage)
150 }
151​
152 // Mutations are already PendingMutation objects with collections attached
153 // from the deserializer, so we can use them directly
154 const transactionWithMutations = {
155 id: transaction.id,
156 mutations: transaction.mutations,
157 metadata: transaction.metadata ?? {},
158 }
159​
160 await mutationFn({
161 transaction: transactionWithMutations as any,
162 idempotencyKey: transaction.idempotencyKey,
163 })
164 }
165​
166 private async handleError(
167 transaction: OfflineTransaction,
168 error: Error,
169 ): Promise<void> {
170 return withNestedSpan(
171 `transaction.handleError`,
172 {
173 'transaction.id': transaction.id,
174 'error.name': error.name,
175 'error.message': error.message,
176 },
177 async (span) => {
178 const shouldRetry = this.retryPolicy.shouldRetry(
179 error,
180 transaction.retryCount,
181 )
182​
183 span.setAttribute(`shouldRetry`, shouldRetry)
184​
185 if (!shouldRetry) {
186 let removalError: unknown
187 try {
188 await this.outbox.remove(transaction.id)
189 } catch (cleanupError) {
190 removalError = cleanupError
191 } finally {
192 this.scheduler.markCompleted(transaction)
193 }
194 console.warn(
195 `Transaction ${transaction.id} failed permanently:`,
196 error,
197 )
198​
199 span.setAttribute(`result`, `permanent_failure`)
200 // Signal permanent failure to the waiting transaction
201 this.offlineExecutor.rejectTransaction(transaction.id, error)
202 if (removalError !== undefined) throw removalError
203 return
204 }
205​
206 const delay = Math.max(
207 0,
208 this.retryPolicy.calculateDelay(transaction.retryCount),
209 )
210 const updatedTransaction: OfflineTransaction = {
211 ...transaction,
212 retryCount: transaction.retryCount + 1,
213 nextAttemptAt: Date.now() + delay,
214 lastError: {
215 name: error.name,
216 message: error.message,
217 stack: error.stack,
218 },
219 }
220​
221 span.setAttribute(`retryDelay`, delay)
222 span.setAttribute(`nextRetryCount`, updatedTransaction.retryCount)
223​
224 this.scheduler.updateTransaction(updatedTransaction)
225​
226 try {
227 await this.outbox.update(transaction.id, updatedTransaction)
228 span.setAttribute(`result`, `scheduled_retry`)
229 } catch (persistError) {
230 span.recordException(persistError as Error)
231 span.setAttribute(`result`, `persist_failed`)
232 throw persistError
233 } finally {
234 this.scheduler.markFailed(transaction)
235 }
236 },
237 )
238 }
239​
240 async loadPendingTransactions(): Promise<void> {
241 let removedIds: Array<string> = []
242 await this.outbox.withAll((transactions) => {
243 const { isOfflineEnabled } = this.offlineExecutor
244 if (!isOfflineEnabled) return
245 let filteredTransactions = transactions
246​
247 if (this.config.beforeRetry) {
248 filteredTransactions = this.config.beforeRetry(transactions)
249 }
250​
251 // The retry hook is user code and may synchronously revoke replay rights.
252 if (!this.offlineExecutor.isOfflineEnabled) return
253​
254 const newlyLoaded = filteredTransactions.filter((transaction) =>
255 this.scheduler.schedule(transaction),
256 )
257​
258 removedIds = transactions
259 .filter(
260 (tx) =>
261 !filteredTransactions.some((filtered) => filtered.id === tx.id),
262 )
263 .map(({ id }) => id)
264 removedIds = this.scheduler.removePendingTransactions(removedIds)
265​
266 // Restore optimistic state for loaded transactions
267 // This ensures the UI shows the optimistic data while transactions are pending
268 this.restoreOptimisticState(newlyLoaded)
269​
270 // Reset retry delays for all loaded transactions so they can run immediately
271 this.resetRetryDelays()
272​
273 // Schedule retry timer for loaded transactions
274 this.scheduleNextRetry()
275 })
276​
277 if (removedIds.length > 0) {
278 const error = new NonRetriableError(`Transaction excluded by beforeRetry`)
279 await Promise.all(
280 removedIds.map(async (id) => {
281 try {
282 await this.outbox.remove(id)
283 this.offlineExecutor.rejectTransaction(id, error)
284 } catch (cleanupError) {
285 console.warn(
286 `Failed to remove transaction excluded by beforeRetry:`,
287 id,
288 cleanupError,
289 )
290 }
291 }),
292 )
293 }
294 }
295​
296 /**
297 * Restore optimistic state from loaded transactions.
298 * Creates internal transactions to hold the mutations so the collection's
299 * state manager can show optimistic data while waiting for sync.
300 */
301 private restoreOptimisticState(
302 transactions: Array<OfflineTransaction>,
303 ): void {
304 for (const offlineTx of transactions) {
305 if (offlineTx.mutations.length === 0) {
306 continue
307 }
308​
309 try {
310 // Create a restoration transaction that holds mutations for optimistic state display.
311 // It will never commit - the real mutation is handled by the offline executor.
312 const restorationTx = createTransaction({
313 id: offlineTx.id,
314 autoCommit: false,
315 mutationFn: async () => {},
316 })
317​
318 // Prevent unhandled promise rejection when cleanup calls rollback()
319 // We don't care about this promise - it's just for holding mutations
320 restorationTx.isPersisted.promise.catch(() => {
321 // Intentionally ignored - restoration transactions are cleaned up
322 // via cleanupRestorationTransaction, not through normal commit flow
323 })
324​
325 restorationTx.applyMutations(offlineTx.mutations)
326​
327 // Register with each affected collection's state manager
328 const touchedCollections = new Set<string>()
329 for (const mutation of offlineTx.mutations) {
330 // Defensive check for corrupted deserialized data
331 // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
332 if (!mutation.collection) {
333 continue
334 }
335 const collectionId = mutation.collection.id
336 if (touchedCollections.has(collectionId)) {
337 continue
338 }
339 touchedCollections.add(collectionId)
340​
341 mutation.collection._state.transactions.set(
342 restorationTx.id,
343 restorationTx,
344 )
345 mutation.collection._state.recomputeOptimisticState(true)
346 }
347​
348 this.offlineExecutor.registerRestorationTransaction(
349 offlineTx.id,
350 restorationTx,
351 )
352 } catch (error) {
353 console.warn(
354 `Failed to restore optimistic state for transaction ${offlineTx.id}:`,
355 error,
356 )
357 }
358 }
359 }
360​
361 clear(): void {
362 this.scheduler.clear()
363 this.clearRetryTimer()
364 }
365​
366 pause(): void {
367 // Retain queued work and let the issued call finish its acknowledgment.
368 this.clearRetryTimer()
369 }
370​
371 getPendingCount(): number {
372 return this.scheduler.getPendingCount()
373 }
374​
375 private scheduleNextRetry(): void {
376 // Clear existing timer
377 this.clearRetryTimer()
378​
379 if (!this.canExecute()) {
380 return
381 }
382​
383 const nextRetryTime = this.getNextRetryTime()
384​
385 if (nextRetryTime === null) {
386 return // No transactions pending retry
387 }
388​
389 const delay = Math.max(0, nextRetryTime - Date.now())
390​
391 this.retryTimer = setTimeout(() => {
392 this.executeAll().catch((error) => {
393 console.warn(`Failed to execute retry batch:`, error)
394 })
395 }, delay)
396 }
397​
398 private getNextRetryTime(): number | null {
399 const allTransactions = this.scheduler.getAllPendingTransactions()
400​
401 if (allTransactions.length === 0) {
402 return null
403 }
404​
405 // Later transactions cannot overtake the FIFO head, even if they are ready.
406 return allTransactions[0]!.nextAttemptAt
407 }
408​
409 private clearRetryTimer(): void {
410 if (this.retryTimer) {
411 clearTimeout(this.retryTimer)
412 this.retryTimer = null
413 }
414 }
415​
416 private canExecute(): boolean {
417 return (
418 this.offlineExecutor.isOfflineEnabled && this.offlineExecutor.isOnline()
419 )
420 }
421​
422 getRunningCount(): number {
423 return this.scheduler.getRunningCount()
424 }
425​
426 resetRetryDelays(): void {
427 const allTransactions = this.scheduler.getAllPendingTransactions()
428 const updatedTransactions = allTransactions.map((transaction) => ({
429 ...transaction,
430 nextAttemptAt: Date.now(),
431 }))
432​
433 this.scheduler.updateTransactions(updatedTransactions)
434 }