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