Skip to content
Merged
Prev Previous commit
fix(devtool): an inventory read that never stops paging ends as a fai…
…led read (FIX-1502)

A server that keeps returning a nextCursor would have held the
Inventory tab in its loading state forever. The read now stops at the
same 1000-page bound the shipped panel readers use, and on a cursor it
has already seen, and the section names why instead of showing rows or
an empty list.

Co-Authored-By: Claude <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016qaz1VpRK4wCQzxpjzZ4Hz
  • Loading branch information
claude committed Sep 24, 2026
commit b81acf5ca802e73d76de9e9d69a4442d15bc7409
19 changes: 19 additions & 0 deletions packages/devtool/src/react/lib/inventory.ts
Original file line number Diff line number Diff line change
Expand Up @@ -45,6 +45,16 @@ export type InventoryDeclarations = Record<InventoryCollection, InventoryDeclara
/** Page size for every read — the collection route's maximum. */
const INVENTORY_PAGE_SIZE = 200;

/**
* The most pages one collection read follows — the same bound the shipped
* panel readers use (`MAX_PAGES` in `@flow-state-dev/react`'s panel reads),
* 200,000 rows at this page size. A guard against a transport that hands back
* a `nextCursor` forever, not a size anyone is expected to reach; hitting it,
* or seeing one cursor twice, ends the read as failed rather than loading
* forever or showing a list that looks whole.
*/
const INVENTORY_MAX_PAGES = 1000;

/**
* Find the three collections in a session's manifest, by pattern.
*
Expand Down Expand Up @@ -108,17 +118,26 @@ export async function readEveryPage(
ref: string,
): Promise<InventoryRead> {
const rows: unknown[] = [];
const seen = new Set<string>();
let pagesRead = 0;
let cursor: string | undefined;
const stopped = (message: string): InventoryRead => ({ status: "failed", message, pagesRead, rowsRead: rows.length });
try {
do {
if (pagesRead >= INVENTORY_MAX_PAGES) {
return stopped(`the server kept returning more pages after ${INVENTORY_MAX_PAGES}, so the read stopped`);
}
const page = await client.listCollectionItems(sessionId, ref, {
limit: INVENTORY_PAGE_SIZE,
...(cursor === undefined ? {} : { cursor }),
});
rows.push(...page.items.map((item) => item.clientData));
pagesRead += 1;
cursor = page.nextCursor;
if (cursor !== undefined) {
if (seen.has(cursor)) return stopped(`the server returned the same page cursor twice, so the read stopped`);
seen.add(cursor);
}
} while (cursor !== undefined);
Comment thread
jhoffner marked this conversation as resolved.
Resolved
} catch (error) {
return { status: "failed", ...describeFailure(error), pagesRead, rowsRead: rows.length };
Expand Down
69 changes: 69 additions & 0 deletions packages/devtool/test/inventory-view.test.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,11 @@
* must not use: expected [ 'Open' ] to deeply equal []`. The first cut of
* this scan read `textContent` and stayed GREEN under that mutation, because
* it glues "eng.queue" onto "Open" and the word boundary never fires.
* - The pagination guard removed (no page bound, no repeated-cursor check) →
* `expected 'the read never stopped' to match /same page cursor twice/`,
* `… to match /after 1000/`, and in the tab `expected 'Registered
* seatsThe seats read failed…' to contain 'same page cursor twice'` — the
* stubs' own backstops stop the loop, so the red state cannot hang the suite.
* - BR-9/BR-10: a failed read returned as an empty one → the 403 and the
* later-page cases fail with `expected 'loaded' to be 'failed'`, the 404 case
* with `expected 'Registered channels0No channels regis…' to contain '(404)'`.
Expand All @@ -35,6 +40,7 @@ import {
InventoryTabTrigger,
} from "../src/react/components/workspace/inventory-view";
import { Tabs, TabsList, TabsTrigger } from "../src/react/components/ui/tabs";
import { readEveryPage } from "../src/react/lib/inventory";

const SESSION = "eng.queue";
const TOKEN = "tok-inventory";
Expand Down Expand Up @@ -85,6 +91,10 @@ function serve(server: Server) {
const ref = decodeURIComponent(read[1]!);
const cursor = new URLSearchParams(read[2]).get("cursor");
const pages = server.pages[ref] ?? [];
// A backstop for a reader with no pagination guard: without it that
// reader loops on resolved promises and never yields to a timeout.
const asked = seen.filter((s) => s.url.includes(`/resources/${encodeURIComponent(ref)}?`)).length;
if (asked > 2_000) return json(500, { error: "the stub stopped answering after 2000 pages" });
const index = cursor === null ? 0 : Number(cursor.replace("page-", ""));
const page = pages[index] ?? { items: [] };
if (page.status !== undefined) return json(page.status, { error: page.error ?? "failed" });
Expand Down Expand Up @@ -358,6 +368,65 @@ describe("V3 · reading every page, and failing out loud (BR-9, BR-10, BR-11)",
});
});

describe("V3 · a cursor that never ends is a failed read, not a hang (BR-9, BR-24)", () => {
// A bounded timeout on each case, so the red state (no guard) fails here
// instead of hanging the suite.
it("ends as failed when the server returns the same cursor twice", { timeout: 5_000 }, async () => {
let calls = 0;
const read = await readEveryPage(
{
listCollectionItems: async () => {
calls += 1;
if (calls > 5_000) throw new Error("the read never stopped");
return { items: [{ topic: `t${calls}`, clientData: { id: `s${calls}` } }], nextCursor: "stuck" };
},
},
SESSION,
REFS.seats,
);
expect(read.status, JSON.stringify(read)).toBe("failed");
expect(read.status === "failed" && read.message).toMatch(/same page cursor twice/);
expect(calls, "pages asked for").toBe(2);
});

it("ends as failed after the page bound when every cursor is new", { timeout: 5_000 }, async () => {
let calls = 0;
const read = await readEveryPage(
{
listCollectionItems: async () => {
calls += 1;
if (calls > 5_000) throw new Error("the read never stopped");
return { items: [], nextCursor: `c${calls}` };
},
},
SESSION,
REFS.seats,
);
expect(read.status, JSON.stringify(read).slice(0, 200)).toBe("failed");
expect(read.status === "failed" && read.message).toMatch(/after 1000/);
expect(calls, "pages asked for").toBe(1000);
});

it("shows the stuck read in the tab as a failure, never loading or empty", { timeout: 5_000 }, async () => {
serve({
manifest: ALL_THREE,
pages: {
// Page 0 points at page 0 again: the same cursor, forever.
[REFS.seats]: [{ items: [SEATS[0]], nextCursor: "page-0" }],
[REFS.channels]: [{ items: [CHANNEL] }],
[REFS.memberships]: [{ items: MEMBERSHIPS }],
},
});
renderWorkspace();
await openPanel();
const seats = section("seats");
expect(seats.dataset.inventoryStatus).toBe("failed");
expect(seats.textContent).toContain("same page cursor twice");
expect(seats.textContent).not.toMatch(EMPTY_TEXT);
expect(seats.querySelector("table")).toBeNull();
});
});

describe("V3 · where the tab appears (BR-7)", () => {
it("does not appear on a session whose flow declares none of the three", async () => {
serve({
Expand Down
Loading