Add safety limits and diagnostics for ORDER BY + LIMIT infinite loops

.changeset/fix-infinite-loop-orderby-limit.md

@@ -0,0 +1,23 @@
+---
+'@tanstack/db': patch
+'@tanstack/db-ivm': patch
+---
+
+Add safety limits to prevent app freezes from excessive iterations in ORDER BY + LIMIT queries.
+
+**The problem**: ORDER BY + LIMIT queries can cause excessive iterations when WHERE filters out most data - the TopK keeps asking for more data that doesn't exist.
+
+**The fix**: Added iteration safety limits that gracefully break out of loops and continue with available data:
+
+- D2 graph: 100,000 iterations
+- maybeRunGraph: 10,000 iterations
+- requestLimitedSnapshot: 10,000 iterations
+
+When limits are hit, a warning is logged with:
+
+- **Iteration breakdown**: Shows where the loop spent time (e.g., "iterations 1-5: [TopK, Filter], 6-10000: [TopK]")
+- Diagnostic info: collection IDs, query structure, cursor position, etc.
+
+The query **continues normally** with the data it has - no error state, no app breakage.
+
+The iteration breakdown makes it easy to see the stuck pattern in the state machine. Please report any warnings to https://github.com/TanStack/db/issues

packages/db-ivm/src/d2.ts

@@ -1,4 +1,5 @@
 import { DifferenceStreamWriter } from './graph.js'
+import { createIterationLimitChecker } from './iteration-tracker.js'
 import type {
   BinaryOperator,
   DifferenceStreamReader,
@@ -57,7 +58,37 @@ export class D2 implements ID2 {
   }
 
   run(): void {
+    // Safety limit to prevent infinite loops in case of circular data flow
+    // or other bugs that cause operators to perpetually produce output.
+    const checkLimit = createIterationLimitChecker({
+      maxSameState: 10000,
+      maxTotal: 100000,
+    })
+
     while (this.pendingWork()) {
+      // Use count of operators with pending work as state key
+      const operatorsWithWorkCount = this.#operators.filter((op) =>
+        op.hasPendingWork(),
+      ).length
+
+      if (
+        checkLimit(() => {
+          // Only compute diagnostics when limit is exceeded (lazy)
+          const operatorsWithWork = this.#operators
+            .filter((op) => op.hasPendingWork())
+            .map((op) => ({ id: op.id, type: op.constructor.name }))
+          return {
+            context: `D2 graph execution`,
+            diagnostics: {
+              operatorsWithPendingWork: operatorsWithWork,
+              totalOperators: this.#operators.length,
+            },
+          }
+        }, operatorsWithWorkCount)
+      ) {
+        break
+      }
+
       this.step()
     }
   }

packages/db-ivm/src/index.ts

@@ -1,4 +1,5 @@
 export * from './d2.js'
+export * from './iteration-tracker.js'
 export * from './multiset.js'
 export * from './operators/index.js'
 export * from './types.js'

packages/db-ivm/src/iteration-tracker.ts

@@ -0,0 +1,95 @@
+/**
+ * Creates an iteration counter with limit checks based on state changes.
+ *
+ * Tracks both total iterations AND iterations without state change. This catches:
+ * - True infinite loops (same state repeating)
+ * - Slow progress that exceeds total limit
+ *
+ * @example
+ * ```ts
+ * const checkLimit = createIterationLimitChecker({
+ *   maxSameState: 10000,  // Max iterations without state change
+ *   maxTotal: 100000,     // Hard cap regardless of state changes
+ * })
+ *
+ * while (pendingWork()) {
+ *   const stateKey = operators.filter(op => op.hasPendingWork()).length
+ *   if (checkLimit(() => ({
+ *     context: 'D2 graph execution',
+ *     diagnostics: { totalOperators: operators.length }
+ *   }), stateKey)) {
+ *     break
+ *   }
+ *   step()
+ * }
+ * ```
+ */
+
+export type LimitExceededInfo = {
+  context: string
+  diagnostics?: Record<string, unknown>
+}
+
+export type IterationLimitOptions = {
+  /** Max iterations without state change before triggering (default: 10000) */
+  maxSameState?: number
+  /** Hard cap on total iterations regardless of state changes (default: 100000) */
+  maxTotal?: number
+}
+
+/**
+ * Creates an iteration limit checker that logs a warning when limits are exceeded.
+ *
+ * @param options - Configuration for iteration limits
+ * @returns A function that checks limits and returns true if exceeded
+ */
+export function createIterationLimitChecker(
+  options: IterationLimitOptions = {},
+): (getInfo: () => LimitExceededInfo, stateKey?: string | number) => boolean {
+  const maxSameState = options.maxSameState ?? 10000
+  const maxTotal = options.maxTotal ?? 100000
+
+  let totalIterations = 0
+  let sameStateIterations = 0
+  let lastStateKey: string | number | undefined
+
+  return function checkLimit(
+    getInfo: () => LimitExceededInfo,
+    stateKey?: string | number,
+  ): boolean {
+    totalIterations++
+
+    // Track same-state iterations
+    if (stateKey !== undefined && stateKey !== lastStateKey) {
+      // State changed - reset same-state counter
+      sameStateIterations = 0
+      lastStateKey = stateKey
+    }
+    sameStateIterations++
+
+    const sameStateExceeded = sameStateIterations > maxSameState
+    const totalExceeded = totalIterations > maxTotal
+
+    if (sameStateExceeded || totalExceeded) {
+      const { context, diagnostics } = getInfo()
+
+      const reason = sameStateExceeded
+        ? `${sameStateIterations} iterations without state change (limit: ${maxSameState})`
+        : `${totalIterations} total iterations (limit: ${maxTotal})`
+
+      const diagnosticSection = diagnostics
+        ? `\nDiagnostic info: ${JSON.stringify(diagnostics, null, 2)}\n`
+        : `\n`
+
+      console.warn(
+        `[TanStack DB] ${context} exceeded iteration limit: ${reason}. ` +
+          `Continuing with available data.` +
+          diagnosticSection +
+          `Please report this issue at https://github.com/TanStack/db/issues`,
+      )
+      return true
+    }
+
+    return false
+  }
+}

packages/db-ivm/tests/iteration-tracker.test.ts

@@ -0,0 +1,144 @@
+import { describe, expect, it, vi } from 'vitest'
+import { createIterationLimitChecker } from '../src/iteration-tracker.js'
+
+describe(`createIterationLimitChecker`, () => {
+  it(`should not exceed limit on normal iteration counts`, () => {
+    const checkLimit = createIterationLimitChecker({ maxSameState: 100 })
+
+    for (let i = 0; i < 50; i++) {
+      expect(checkLimit(() => ({ context: `test` }))).toBe(false)
+    }
+  })
+
+  it(`should return true when same-state limit is exceeded`, () => {
+    const checkLimit = createIterationLimitChecker({ maxSameState: 10 })
+
+    for (let i = 0; i < 10; i++) {
+      expect(checkLimit(() => ({ context: `test` }))).toBe(false)
+    }
+
+    // 11th iteration exceeds the limit
+    const consoleSpy = vi.spyOn(console, `warn`).mockImplementation(() => {})
+    expect(checkLimit(() => ({ context: `test` }))).toBe(true)
+    consoleSpy.mockRestore()
+  })
+
+  it(`should reset same-state counter when state key changes`, () => {
+    const checkLimit = createIterationLimitChecker({
+      maxSameState: 5,
+      maxTotal: 100,
+    })
+    const consoleSpy = vi.spyOn(console, `warn`).mockImplementation(() => {})
+
+    // 5 iterations with state key 1 - should not exceed
+    for (let i = 0; i < 5; i++) {
+      expect(checkLimit(() => ({ context: `test` }), 1)).toBe(false)
+    }
+
+    // Change state key to 2 - counter resets
+    // 5 more iterations should not exceed
+    for (let i = 0; i < 5; i++) {
+      expect(checkLimit(() => ({ context: `test` }), 2)).toBe(false)
+    }
+
+    // Change state key to 3 - counter resets again
+    // 5 more iterations should not exceed
+    for (let i = 0; i < 5; i++) {
+      expect(checkLimit(() => ({ context: `test` }), 3)).toBe(false)
+    }
+
+    // Total is 15, but no same-state limit exceeded
+    expect(consoleSpy).not.toHaveBeenCalled()
+    consoleSpy.mockRestore()
+  })
+
+  it(`should trigger on total limit even with state changes`, () => {
+    const checkLimit = createIterationLimitChecker({
+      maxSameState: 10,
+      maxTotal: 20,
+    })
+    const consoleSpy = vi.spyOn(console, `warn`).mockImplementation(() => {})
+
+    // Alternate state keys to avoid same-state limit
+    for (let i = 0; i < 20; i++) {
+      expect(checkLimit(() => ({ context: `test` }), i % 2)).toBe(false)
+    }
+
+    // 21st iteration exceeds total limit
+    expect(checkLimit(() => ({ context: `test` }), 0)).toBe(true)
+    expect(consoleSpy).toHaveBeenCalledTimes(1)
+    expect(consoleSpy.mock.calls[0]![0]).toContain(`total iterations`)
+    consoleSpy.mockRestore()
+  })
+
+  it(`should only call getInfo when limit is exceeded (lazy evaluation)`, () => {
+    const checkLimit = createIterationLimitChecker({ maxSameState: 5 })
+    const getInfo = vi.fn(() => ({ context: `test` }))
+
+    // First 5 iterations should not call getInfo
+    for (let i = 0; i < 5; i++) {
+      checkLimit(getInfo)
+    }
+    expect(getInfo).not.toHaveBeenCalled()
+
+    // 6th iteration exceeds limit and should call getInfo
+    const consoleSpy = vi.spyOn(console, `warn`).mockImplementation(() => {})
+    checkLimit(getInfo)
+    expect(getInfo).toHaveBeenCalledTimes(1)
+    consoleSpy.mockRestore()
+  })
+
+  it(`should log warning with context and diagnostics`, () => {
+    const checkLimit = createIterationLimitChecker({ maxSameState: 2 })
+    const consoleSpy = vi.spyOn(console, `warn`).mockImplementation(() => {})
+
+    checkLimit(() => ({ context: `test` }))
+    checkLimit(() => ({ context: `test` }))
+    checkLimit(() => ({
+      context: `D2 graph execution`,
+      diagnostics: {
+        totalOperators: 8,
+        operatorsWithWork: [`TopK`, `Filter`],
+      },
+    }))
+
+    expect(consoleSpy).toHaveBeenCalledTimes(1)
+    const warning = consoleSpy.mock.calls[0]![0]
+    expect(warning).toContain(`[TanStack DB] D2 graph execution`)
+    expect(warning).toContain(`iterations without state change`)
+    expect(warning).toContain(`Continuing with available data`)
+    expect(warning).toContain(`"totalOperators": 8`)
+    expect(warning).toContain(`TopK`)
+    expect(warning).toContain(`https://github.com/TanStack/db/issues`)
+
+    consoleSpy.mockRestore()
+  })
+
+  it(`should log warning without diagnostics when not provided`, () => {
+    const checkLimit = createIterationLimitChecker({ maxSameState: 1 })
+    const consoleSpy = vi.spyOn(console, `warn`).mockImplementation(() => {})
+
+    checkLimit(() => ({ context: `test` }))
+    checkLimit(() => ({ context: `Graph execution` }))
+
+    expect(consoleSpy).toHaveBeenCalledTimes(1)
+    const warning = consoleSpy.mock.calls[0]![0]
+    expect(warning).toContain(`[TanStack DB] Graph execution`)
+    expect(warning).not.toContain(`Diagnostic info:`)
+
+    consoleSpy.mockRestore()
+  })
+
+  it(`should use default limits when not specified`, () => {
+    const checkLimit = createIterationLimitChecker({})
+    const consoleSpy = vi.spyOn(console, `warn`).mockImplementation(() => {})
+
+    // Default maxSameState is 10000 - should not trigger
+    for (let i = 0; i < 1000; i++) {
+      expect(checkLimit(() => ({ context: `test` }))).toBe(false)
+    }
+
+    expect(consoleSpy).not.toHaveBeenCalled()
+    consoleSpy.mockRestore()
+  })
+})