Files
clean-architecture-frontend…/tests/unit/cursor-pagination-runtime.test.ts
DongHyeonkaandClaude Opus 5.5 1d7ca9dcb8 fix(query-cache): measure pagination per page, reject bare W/" ETag, drop dead RPC helper (Q-6.3-12)
- cursor pagination re-serialized every accumulated item on each page
  (O(pages x total)) and used items.push(...page.items), which throws
  RangeError for a large page, so loadAll rejected instead of returning
  a Result. Each page is now measured once and summed (errs high by at
  most one byte per page), the item count is checked before copying,
  and items are appended one by one.
- conditional-validator-store accepted `W/"` as a weak ETag because its
  opening quote also satisfied endsWith('"'). The closing quote must now
  come after the opening one.
- browser-rpc-runtime's validTransportFailure had no callers, duplicated
  decodeTransportFailure and read properties directly, which RPC-RR-04
  forbids. Deleted (approved for this template).

Verified: new tests failed RED (18 serialized items instead of 6 because
the accumulated array was passed each time, RangeError for a 1,000,000
item page, `W/"` installed) and pass now. All lane gates pass except the
known removal-fixture test.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-24 13:41:45 +09:00

340 lines
9.2 KiB
TypeScript

import { describe, expect, it, vi } from "vitest";
import { createCursorPaginationRuntime } from "../../src/adapters/query-cache/index.ts";
const profile = {
profileId: "bounded-cursor-v1",
maxPages: 3,
maxTotalItems: 4,
maxEstimatedBytes: 1_024,
maxCursorBytes: 64,
allowSparsePage: false,
} as const;
describe("bounded cursor pagination runtime", () => {
it("returns PAGINATION_ABORTED when a non-cooperative page resolves after abort", async () => {
const controller = new AbortController();
let releasePage: ((page: unknown) => void) | undefined;
const loadPage = vi.fn(
() =>
new Promise((resolve) => {
releasePage = resolve as (page: unknown) => void;
}),
);
const runtime = createCursorPaginationRuntime({
definitionId: "bounded",
profile,
loadPage: loadPage as never,
});
const loading = runtime.loadAll({ signal: controller.signal });
await Promise.resolve();
controller.abort();
const result = await loading;
expect(result).toMatchObject({
ok: false,
error: { kind: "REQUEST_ABORTED", code: "PAGINATION_ABORTED" },
});
// The late page completion must be ignored, not accumulated.
releasePage?.({
ok: true,
value: {
items: ["late"],
nextCursor: null,
hasMore: false,
snapshotToken: "snapshot-1",
},
});
await Promise.resolve();
expect(loadPage).toHaveBeenCalledOnce();
});
it("loads a stable finite chain without exposing cursors in its value", async () => {
const loadPage = vi
.fn()
.mockResolvedValueOnce({
ok: true,
value: {
items: ["one"],
nextCursor: "cursor-2",
hasMore: true,
snapshotToken: "snapshot-a",
},
})
.mockResolvedValueOnce({
ok: true,
value: {
items: ["two"],
nextCursor: null,
hasMore: false,
snapshotToken: "snapshot-a",
},
});
const runtime = createCursorPaginationRuntime({
definitionId: "LIST_ALL",
profile,
loadPage,
});
await expect(runtime.loadAll({})).resolves.toEqual({
ok: true,
value: ["one", "two"],
});
expect(loadPage.mock.calls.map(([cursor]) => cursor)).toEqual([
null,
"cursor-2",
]);
});
it.each([
{
page: {
items: [],
nextCursor: "next",
hasMore: true,
snapshotToken: null,
},
code: "PAGINATION_PAGE_INVALID",
},
{
page: {
items: ["one"],
nextCursor: null,
hasMore: true,
snapshotToken: null,
},
code: "PAGINATION_PAGE_INVALID",
},
])("rejects invalid page invariants", async ({ page, code }) => {
const runtime = createCursorPaginationRuntime({
definitionId: "LIST_ALL",
profile,
loadPage: async () => ({ ok: true, value: page }),
});
await expect(runtime.loadAll({})).resolves.toMatchObject({
ok: false,
error: { kind: "PAGINATION_CONTRACT_VIOLATION", code },
});
});
it("rejects cursor loops and snapshot drift", async () => {
const loop = createCursorPaginationRuntime({
definitionId: "LIST_ALL",
profile,
loadPage: async () => ({
ok: true,
value: {
items: ["one"],
nextCursor: "same",
hasMore: true,
snapshotToken: null,
},
}),
});
await expect(loop.loadAll({})).resolves.toMatchObject({
ok: false,
error: { code: "PAGINATION_CURSOR_LOOP" },
});
let page = 0;
const drift = createCursorPaginationRuntime({
definitionId: "LIST_ALL",
profile,
loadPage: async () => ({
ok: true,
value: {
items: [String(page)],
nextCursor: page++ === 0 ? "next" : null,
hasMore: page === 1,
snapshotToken: page === 1 ? "snapshot-a" : "snapshot-b",
},
}),
});
await expect(drift.loadAll({})).resolves.toMatchObject({
ok: false,
error: { code: "PAGINATION_SNAPSHOT_CHANGED" },
});
});
// Q-6.3-12. The byte estimate serialized every accumulated item again on
// each page, and `push(...items)` spreads a page into call arguments.
it("serializes each page once", async () => {
const pages = [["a", "b"], ["c", "d"], ["e", "f"]];
const stringify = vi.spyOn(JSON, "stringify");
try {
const runtime = createCursorPaginationRuntime({
definitionId: "LIST_ALL",
profile: { ...profile, maxTotalItems: 6 },
loadPage: async (cursor) => {
const index = cursor === null ? 0 : Number(cursor);
const last = index === pages.length - 1;
return {
ok: true,
value: {
items: pages[index] ?? [],
nextCursor: last ? null : String(index + 1),
hasMore: !last,
snapshotToken: null,
},
};
},
});
const result = await runtime.loadAll({});
const serializedItems = stringify.mock.calls
.map(([value]) => (Array.isArray(value) ? value.length : 0))
.reduce((sum, length) => sum + length, 0);
stringify.mockRestore();
expect(result).toEqual({
ok: true,
value: ["a", "b", "c", "d", "e", "f"],
});
expect(serializedItems).toBe(6);
} finally {
stringify.mockRestore();
}
});
it("accepts a page larger than the call argument limit", async () => {
const large = new Array<number>(1_000_000).fill(0);
const bulk = createCursorPaginationRuntime({
definitionId: "LIST_ALL",
profile: {
...profile,
maxTotalItems: large.length,
maxEstimatedBytes: 4 * large.length,
},
loadPage: async () => ({
ok: true,
value: {
items: large,
nextCursor: null,
hasMore: false,
snapshotToken: null,
},
}),
});
const result = await bulk.loadAll({});
expect(result.ok && result.value.length).toBe(large.length);
});
});
/**
* NS-07. The profile was validated once and then re-read on every page, so
* raising `maxPages` after construction widened a cap that had already been
* checked — the runtime issued more requests and returned more items than the
* validated profile allowed.
*/
describe("NS-07 the caps are the ones that were validated", () => {
it("keeps the page cap captured at construction", async () => {
const mutable: {
profileId: string;
maxPages: number;
maxTotalItems: number;
maxEstimatedBytes: number;
maxCursorBytes: number;
allowSparsePage: boolean;
} = { ...profile, maxPages: 1 };
const loadPage = vi.fn(async () => ({
ok: true as const,
value: {
items: [1],
nextCursor: `cursor-${loadPage.mock.calls.length}`,
hasMore: true,
snapshotToken: "snapshot-a",
},
}));
const runtime = createCursorPaginationRuntime({
definitionId: "LIST_ALL",
profile: mutable,
loadPage,
});
mutable.maxPages = 3;
mutable.maxTotalItems = 99;
await expect(runtime.loadAll({})).resolves.toMatchObject({
ok: false,
error: { code: "PAGINATION_PAGE_LIMIT" },
});
expect(loadPage).toHaveBeenCalledTimes(1);
});
it("keeps the loader captured at construction", async () => {
const original = vi.fn(async () => ({
ok: true as const,
value: {
items: [1],
nextCursor: null,
hasMore: false,
snapshotToken: null,
},
}));
const replacement = vi.fn();
const dependencies = {
definitionId: "LIST_ALL",
profile,
loadPage: original,
};
const runtime = createCursorPaginationRuntime(dependencies);
dependencies.loadPage = replacement as never;
await expect(runtime.loadAll({})).resolves.toMatchObject({ ok: true });
expect(original).toHaveBeenCalledTimes(1);
expect(replacement).not.toHaveBeenCalled();
});
const hostileProfiles: readonly (readonly [string, () => unknown])[] = [
[
"an accessor cap",
() =>
Object.defineProperty({ ...profile }, "maxPages", {
enumerable: true,
get: () => 3,
}),
],
[
"an inherited cap",
() => Object.create({ ...profile }) as unknown,
],
["an extra own field", () => ({ ...profile, injected: true })],
[
"a symbol field",
() => ({ ...profile, [Symbol.for("injected")]: true }),
],
[
"a non-enumerable own field",
() =>
Object.defineProperty({ ...profile }, "injected", {
enumerable: false,
value: true,
}),
],
[
"a throwing ownKeys trap",
() =>
new Proxy(
{ ...profile },
{
ownKeys() {
throw new TypeError("hostile ownKeys trap");
},
},
),
],
];
for (const [label, build] of hostileProfiles) {
it(`refuses to build a runtime from ${label}`, () => {
expect(() =>
createCursorPaginationRuntime({
definitionId: "LIST_ALL",
profile: build() as never,
loadPage: vi.fn(),
}),
).toThrow(TypeError);
});
}
});