Files
clean-architecture-frontend…/src/adapters/query-cache/cursor-pagination-runtime.ts
T
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

241 lines
8.0 KiB
TypeScript
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
import type { Result } from "../../contracts/result.ts";
import type {
CursorPage,
CursorPaginationProfile,
CursorPaginationRuntime,
} from "./cursor-pagination-contract.ts";
import { createFailure } from "../../contracts/errors.ts";
import { snapshotExactObject } from "../../contracts/exact-snapshot.ts";
const ABORTED = Symbol("PAGINATION_ABORTED");
/**
* Resolves as soon as the operation settles or the signal aborts, whichever
* comes first. A late operation result is observed and discarded, never thrown
* as an unhandled rejection.
*
* OPT-NET-01. A loader rejection is *not* an abort. The presence of a signal
* says nothing about why the loader failed, so a rejection is re-thrown exactly
* as it would be with no signal at all; only a signal that has actually
* aborted classifies the outcome as cancellation.
*/
async function raceAbort<Value>(
operation: Promise<Value>,
signal: AbortSignal | undefined,
): Promise<Value | typeof ABORTED> {
operation.catch(() => {});
if (!signal) return await operation;
if (signal.aborted) return ABORTED;
return await new Promise<Value | typeof ABORTED>((resolve, reject) => {
const onAbort = () => resolve(ABORTED);
signal.addEventListener("abort", onAbort, { once: true });
operation.then(
(value) => {
signal.removeEventListener("abort", onAbort);
resolve(value);
},
(reason: unknown) => {
signal.removeEventListener("abort", onAbort);
if (signal.aborted) {
resolve(ABORTED);
return;
}
reject(reason);
},
);
});
}
export function createCursorPaginationRuntime<Value>(dependencies: Readonly<{
definitionId: string;
profile: CursorPaginationProfile;
loadPage(
cursor: string | null,
context: Readonly<{ signal?: AbortSignal }>,
): Promise<Result<CursorPage<Value>>>;
}>): CursorPaginationRuntime<Value> {
// NS-07. The caps are captured once, here. Validating the caller's profile and
// then reading it again on every page let a `maxPages` of 1 become 3 after
// construction, so the request count, item total and byte ceiling that were
// checked were not the ones the loop enforced. The collaborators are captured
// for the same reason.
const profile = snapshotProfile(dependencies.profile);
const definitionId = dependencies.definitionId;
const loadPage = dependencies.loadPage;
if (typeof definitionId !== "string" || typeof loadPage !== "function") {
throw new TypeError("Invalid cursor pagination dependencies.");
}
return Object.freeze({
async loadAll(context) {
const items: Value[] = [];
let pageBytes = 0;
const cursors = new Set<string>();
let cursor: string | null = null;
let snapshot: string | null | undefined;
for (
let pageIndex = 0;
pageIndex < profile.maxPages;
pageIndex += 1
) {
if (context.signal?.aborted) {
return failure("REQUEST_ABORTED", "PAGINATION_ABORTED");
}
// N-10. A non-cooperative loader may never settle, or may settle after
// abort. Race the signal so `loadAll` is bounded, and re-check before
// observing the page so a late completion is ignored rather than
// accumulated into a successful result.
const raced: Result<CursorPage<Value>> | typeof ABORTED =
await raceAbort<Result<CursorPage<Value>>>(
loadPage(cursor, context),
context.signal,
);
if (raced === ABORTED || context.signal?.aborted) {
return failure("REQUEST_ABORTED", "PAGINATION_ABORTED");
}
const result: Result<CursorPage<Value>> = raced;
if (!result.ok) return result;
const page: CursorPage<Value> = result.value;
if (!isValidPage(page, profile)) {
return failure(
"PAGINATION_CONTRACT_VIOLATION",
"PAGINATION_PAGE_INVALID",
);
}
if (snapshot === undefined) {
snapshot = page.snapshotToken;
} else if (snapshot !== page.snapshotToken) {
return failure(
"PAGINATION_CONTRACT_VIOLATION",
"PAGINATION_SNAPSHOT_CHANGED",
);
}
// Q-6.3-12. Each page is measured once (the sum errs high by at most
// one byte per page) and appended item by item: re-serializing the
// accumulated items was O(pages × total), and `push(...items)`
// throws a RangeError for a large page.
pageBytes += estimatedBytes(page.items);
if (
items.length + page.items.length > profile.maxTotalItems ||
pageBytes > profile.maxEstimatedBytes
) {
return failure(
"RESULT_LIMIT_EXCEEDED",
"PAGINATION_RESULT_LIMIT",
);
}
for (const item of page.items) items.push(item);
if (!page.hasMore) return { ok: true, value: Object.freeze(items) };
const nextCursor: string | null = page.nextCursor;
if (!nextCursor || cursors.has(nextCursor)) {
return failure(
"PAGINATION_CONTRACT_VIOLATION",
"PAGINATION_CURSOR_LOOP",
);
}
cursors.add(nextCursor);
cursor = nextCursor;
}
return failure(
"RESULT_LIMIT_EXCEEDED",
"PAGINATION_PAGE_LIMIT",
);
},
});
function failure(
kind:
| "PAGINATION_CONTRACT_VIOLATION"
| "RESULT_LIMIT_EXCEEDED"
| "REQUEST_ABORTED",
code: string,
) {
return {
ok: false as const,
error: createFailure(kind, definitionId, 0, { code }),
};
}
}
/**
* NS-07. Copies the profile into an owned frozen record, reading every field
* exactly once, and validates that copy. An accessor, an inherited or extra
* field, a symbol key or a Proxy trap fails closed rather than becoming a cap
* that can change after it was checked.
*/
function snapshotProfile(source: unknown): CursorPaginationProfile {
const profile = snapshotExactObject(source, {
allowed: [
"profileId",
"maxPages",
"maxTotalItems",
"maxEstimatedBytes",
"maxCursorBytes",
"allowSparsePage",
],
required: [
"profileId",
"maxPages",
"maxTotalItems",
"maxEstimatedBytes",
"maxCursorBytes",
"allowSparsePage",
],
}) as CursorPaginationProfile | null;
if (profile === null || typeof profile.allowSparsePage !== "boolean") {
throw new TypeError("Invalid cursor pagination profile.");
}
validateProfile(profile);
return profile;
}
function validateProfile(profile: CursorPaginationProfile): void {
if (
typeof profile.profileId !== "string" ||
!profile.profileId ||
!Number.isSafeInteger(profile.maxPages) ||
profile.maxPages < 1 ||
profile.maxPages > 100 ||
!Number.isSafeInteger(profile.maxTotalItems) ||
profile.maxTotalItems < 1 ||
!Number.isSafeInteger(profile.maxEstimatedBytes) ||
profile.maxEstimatedBytes < 1 ||
!Number.isSafeInteger(profile.maxCursorBytes) ||
profile.maxCursorBytes < 1 ||
profile.maxCursorBytes > 4_096
) {
throw new TypeError("Invalid cursor pagination profile.");
}
}
function isValidPage<Value>(
page: CursorPage<Value>,
profile: CursorPaginationProfile,
): boolean {
const encoder = new TextEncoder();
return (
Boolean(page) &&
Array.isArray(page.items) &&
typeof page.hasMore === "boolean" &&
page.hasMore === (page.nextCursor !== null) &&
(page.nextCursor === null ||
(typeof page.nextCursor === "string" &&
page.nextCursor.length > 0 &&
encoder.encode(page.nextCursor).byteLength <=
profile.maxCursorBytes)) &&
(page.snapshotToken === null ||
(typeof page.snapshotToken === "string" &&
page.snapshotToken.length > 0 &&
encoder.encode(page.snapshotToken).byteLength <=
profile.maxCursorBytes)) &&
(profile.allowSparsePage || !page.hasMore || page.items.length > 0)
);
}
function estimatedBytes(value: unknown): number {
try {
return new TextEncoder().encode(JSON.stringify(value)).byteLength;
} catch {
return Number.POSITIVE_INFINITY;
}
}