fix(cli): reject pagination cursor cycles

Author: TheodoreSpeaks

apps/docs/content/docs/cli/output.mdx

@@ -31,7 +31,7 @@ Paginated lists include the rows under `data` and the continuation cursor under
 `nextCursor`. A `null` cursor means no pages remain:
 
 ```json
-{ "data": [{ "runId": "run_1" }], "nextCursor": null }
+{ "data": [{ "runId": "9c4f0b7e-2d81-4a35-b6e9-70f1c8a2d543" }], "nextCursor": null }
 ```
 
 Read list rows with `jq '.data[]'` and check for more pages with `jq '.nextCursor'`.

packages/sim-cli/src/http/client.test.ts

@@ -81,6 +81,23 @@ describe('cursor pagination', () => {
     })
   })
 
+  it.each([{ cursors: ['c1', 'c1'] }, { cursors: ['c1', 'c2', 'c1'] }])(
+    'rejects cursor cycles $cursors before making another request',
+    async ({ cursors }) => {
+      const request = vi.fn().mockRejectedValue(new Error('Pagination did not stop at the cycle'))
+      for (const nextCursor of cursors) {
+        request.mockResolvedValueOnce({ data: ['item'], nextCursor })
+      }
+
+      await expect(
+        requestAllPages<string>({ request } as Pick<SimClient, 'request'>, '/api/v2/items', {
+          pageSize: 100,
+        })
+      ).rejects.toThrow('repeated pagination cursor')
+      expect(request).toHaveBeenCalledTimes(cursors.length)
+    }
+  )
+
   it('reports progress on stderr once a second page is coming, then clears the line', async () => {
     const request = vi
       .fn()

packages/sim-cli/src/http/client.ts

@@ -763,6 +763,15 @@ export function pageProgress(): PageProgress {
   }
 }
 
+/** Rejects cursor cycles before a pager repeats requests or returns an unusable continuation. */
+export function assertCursorAdvances(cursor: string | null, seenCursors: Set<string>): void {
+  if (cursor === null) return
+  if (seenCursors.has(cursor)) {
+    throw new SimApiError('The API returned a repeated pagination cursor; cannot continue.', 0)
+  }
+  seenCursors.add(cursor)
+}
+
 /** Follows a standard v2 cursor envelope without duplicating pagination loops. */
 export async function requestAllPages<T>(
   client: Pick<SimClient, 'request'>,
@@ -774,6 +783,7 @@ export async function requestAllPages<T>(
   if (limit <= 0) return []
 
   const items: T[] = []
+  const seenCursors = new Set<string>()
   const progress = pageProgress()
   let cursor: string | null = null
   // `finally`, because a page that throws part-way through would otherwise skip
@@ -789,6 +799,7 @@ export async function requestAllPages<T>(
           cursor,
         },
       })
+      assertCursorAdvances(page.nextCursor, seenCursors)
       items.push(...page.data)
       cursor = page.nextCursor
 

packages/sim-cli/src/runtime/build.test.ts

@@ -1324,6 +1324,31 @@ describe('contract-selected list rendering', () => {
 })
 
 describe('pagination slot', () => {
+  it.each([
+    { argv: ['files', 'list'], cursors: ['c1', 'c1'] },
+    { argv: ['files', 'list'], cursors: ['c1', 'c2', 'c1'] },
+    { argv: ['tables', 'rows', 'query', 'tbl_1', '--limit', '0'], cursors: ['c1', 'c1'] },
+    { argv: ['logs', 'list', '--cursor', 'c1'], cursors: ['c1'] },
+    { argv: ['tables', 'rows', 'query', 'tbl_1', '--cursor', 'c1'], cursors: ['c1'] },
+  ])(
+    'rejects cursor cycles in $argv without printing partial results',
+    async ({ argv, cursors }) => {
+      mockRequest.mockReset()
+      mockRequest.mockRejectedValue(new Error('Pagination did not stop at the cycle'))
+      for (const nextCursor of cursors) {
+        mockRequest.mockResolvedValueOnce({ data: [{ id: 'r1' }], nextCursor })
+      }
+      const printed = vi.spyOn(console, 'log').mockImplementation(() => {})
+      printed.mockClear()
+
+      await expect(program().parseAsync(['node', 'sim', ...argv])).rejects.toThrow(
+        'repeated pagination cursor'
+      )
+      expect(mockRequest).toHaveBeenCalledTimes(cursors.length)
+      expect(printed).not.toHaveBeenCalled()
+    }
+  )
+
   it.each([
     ['files', 'list'],
     ['tables', 'list'],

packages/sim-cli/src/runtime/execute.ts

@@ -2,7 +2,7 @@ import type { Command } from 'commander'
 import { clientFrom } from '../context'
 import type { CommandSpec } from '../contract/types'
 import type { V2OperationName } from '../generated/v2-api'
-import { pageProgress, SimApiError, type V2Page } from '../http/client'
+import { assertCursorAdvances, pageProgress, SimApiError, type V2Page } from '../http/client'
 import { safeOneLine } from '../output/render'
 import { camel } from './derive'
 import { DEFAULT_PAGE_SIZE, defaultListLimit } from './options'
@@ -402,6 +402,7 @@ export async function executeOperation(
     }
     const limit = pagedLimit === 0 ? Number.POSITIVE_INFINITY : pagedLimit
     const rows: unknown[] = []
+    const seenCursors = new Set<string>(initialCursor ? [initialCursor] : [])
     const progress = pageProgress()
     let cursor: string | null = initialCursor ?? null
     /** The first page's envelope: where a fact about the whole query is stated. */
@@ -428,6 +429,7 @@ export async function executeOperation(
             0
           )
         }
+        assertCursorAdvances(page.nextCursor, seenCursors)
         envelope = foldPageEnvelope(envelope, page)
         rows.push(...page.data)
         cursor = page.nextCursor