@zenera/faker 1.1.9 → 1.1.11

package/README.md

@@ -60,13 +60,48 @@ for. `GET /users/12324` answering with somebody else's id validates perfectly
 and is still wrong.
 
 If it fails, the diagnostics go back to the model and it tries again, up to
-`--attempts`. If it passes, the file is cached under `~/.zenera/neo/faker` and
+`--attempts`. If it passes, the generator is kept in this machine's shared cache
+under `~/.zenera/neo/cache/faker-generator/`, keyed by the operation's shape, and
 every later request is just `podman exec python3 gen.py in.json out.json` — no
-model, no tokens.
+model, no tokens. The store is the machine's, so the same document served from
+another directory costs nothing the second time.
 
 Generators run in a container with **no network**, on an image baked once with
 `faker`, `exrex`, `jsonschema` and `python-dateutil`.
 
+## Pages that end
+
+A list endpoint is the one place a mock can hang a real client. Given
+`?cursor=abc`, the honest-looking answer is a body that validates, echoes
+nothing it shouldn't, and hands back `abc` again — so the client asks for the
+same page forever.
+
+The faker reads the document for this. Where an operation has a paging
+parameter (`cursor`, `page`, `offset`, `page_token`, …) and a response property
+that carries the next one (`next`, `next_cursor`, `has_more`, …), three things
+happen, all in the operation's own names:
+
+- the model is told to fabricate **three pages** in total, to build the token
+  out of the paging parameter rather than the seed, and to end the list — null,
+  absent, or `has_more: false` where the schema leaves no other room;
+- the generator is then **walked**: the faker calls it with no cursor, follows
+  the token it gets back, and rejects the file if the token repeats, cycles, or
+  never runs out. The diagnostics say which, and the model gets another go;
+- at request time a token identical to the one just sent is **cut** — nulled or
+  dropped, whichever the schema allows — and the request line says so. Nothing
+  is invented in its place; a generator written before this rule existed is
+  still cached, and a cache is not rebuilt because a rule changed.
+
+Only paginated operations are affected. Their cache keys changed once, so they
+are written again on first use; everything else keeps the key it had.
+`GET /__faker/routes` reports the shape that was recognised, per operation.
+
+Plenty of documents describe the envelope and never write down the parameter
+that reads it back. The first two steps cannot help there — nothing static can
+see a parameter that is not declared — but the cut still applies: it takes the
+paging parameter from the request itself, since a client only sends `?cursor=X`
+because a body handed it X.
+
 ## Commands
 
 ```
@@ -77,8 +112,8 @@ zen faker cache ls | clear   What has been generated, or throw it away.
 
 Useful options: `--port`, `--host` (reachable only from this machine by
 default), `--model`, `--seed` (same request, same answer), `--rebuild`,
-`--attempts`, `--concurrency`, `--timeout`, `--cache <dir>`, `--quiet`.
-`zen help faker` prints the full table.
+`--attempts`, `--concurrency`, `--timeout`, `--cache <dir>` (the container's
+workspace), `--quiet`. `zen help faker` prints the full table.
 
 `GET /__faker/routes` lists what is being served; `GET /__faker/health` is a
 health check.

package/dist/cache.d.ts

@@ -1,12 +1,23 @@
 import type { Model } from '@zenera/neo';
-import { type Box } from './box.ts';
+import type { Box } from './box.ts';
 import { BuildFailed } from './generate.ts';
 import type { Operation } from './spec.ts';
 import type { Checks } from './validate.ts';
+export declare const FAKER_KIND = "faker-generator";
+/** What is kept about a generator besides the code, for `zen faker cache ls`. */
+export interface GeneratorMeta {
+    operationId?: string;
+    method?: string;
+    path?: string;
+    source?: string;
+    model?: string;
+    attempts?: number;
+    createdAt?: string;
+}
 export interface Generator {
     key: string;
     source: string;
-    /** whether it came off disk rather than out of a model */
+    /** whether it came out of the cache rather than out of a model */
     cached: boolean;
 }
 export interface CacheEvent {
@@ -26,10 +37,12 @@ export interface CacheOptions {
      * on all of them.
      */
     concurrency?: number;
-    /** ignore what is on disk and write fresh */
+    /** ignore what is cached and write fresh */
     rebuild?: boolean;
     /** run generators but keep nothing */
     ephemeral?: boolean;
+    /** keep them somewhere other than the shared store */
+    cacheDir?: string;
     onStart?: (e: CacheEvent) => void;
     onAttempt?: (e: CacheEvent) => void;
     onReady?: (e: CacheEvent & {

package/dist/cache.js

@@ -1,12 +1,28 @@
-import { existsSync } from 'node:fs';
-import { readFile } from 'node:fs/promises';
-import { join } from 'node:path';
-import { writeJson } from '@zenera/cli/lib';
-import { GENERATORS } from "./box.js";
+import { Cache as Store } from '@zenera/cli/lib';
 import { build, BuildFailed } from "./generate.js";
+// ---------------------------------------------------------------------------
+// The cache
+//
+// Two layers over one identity. `Operation.key` is a function of the
+// operation's shape, so a spec edit produces a new key and the old artefact is
+// simply never asked for again — there is nothing to invalidate, which is the
+// part of a cache that is usually wrong.
+//
+// The generator itself lives in the machine's shared cache rather than beside
+// the container's workspace, so the same spec served from two directories is
+// written once. The box root is scratch: a hit is copied back into it, because
+// the container can only run what is under its mount.
+//
+// The in-flight map is the other half and matters more than it looks: ten
+// requests arriving together for an uncached operation must produce one build,
+// not ten. A failed build is remembered too, for the same reason — an operation
+// the model could not write for should not re-ask on every request.
+// ---------------------------------------------------------------------------
+export const FAKER_KIND = 'faker-generator';
 const DEFAULT_CONCURRENCY = 4;
 export class Cache {
     #opts;
+    #store;
     #live = new Map();
     #settled = new Set();
     #slots;
@@ -14,6 +30,7 @@ export class Cache {
     #running = 0;
     constructor(opts) {
         this.#opts = opts;
+        this.#store = new Store(FAKER_KIND, { dir: opts.cacheDir, mode: 0o600 });
         this.#slots = Math.max(1, opts.concurrency ?? DEFAULT_CONCURRENCY);
     }
     /**
@@ -51,7 +68,7 @@ export class Cache {
         const { box, model, checks, rebuild, ephemeral } = this.#opts;
         // Read before queueing: a cache hit costs nothing and must not wait
         // behind somebody else's model call.
-        const source = rebuild ? undefined : await read(box, operation.key);
+        const source = rebuild ? undefined : await this.#read(box, operation.key);
         if (source !== undefined) {
             this.#opts.onReady?.({ operation, cached: true, attempts: 0 });
             return { key: operation.key, source, cached: true };
@@ -67,17 +84,18 @@ export class Cache {
                 onAttempt: (attempt, diagnostics) => this.#opts.onAttempt?.({ operation, attempt, diagnostics }),
             });
             if (!ephemeral) {
-                writeJson(join(box.root, GENERATORS, operation.key, 'meta.json'), {
-                    version: 1,
-                    operationId: operation.operationId,
-                    method: operation.method,
-                    path: operation.path,
-                    source: operation.source,
-                    model: model.id,
-                    attempts: built.attempts,
-                    rebuilt: Boolean(rebuild),
-                    createdAt: new Date().toISOString(),
-                }, 0o644);
+                this.#store.put(operation.key, {
+                    source: built.source,
+                    meta: {
+                        operationId: operation.operationId,
+                        method: operation.method,
+                        path: operation.path,
+                        source: operation.source,
+                        model: model.id,
+                        attempts: built.attempts,
+                        createdAt: new Date().toISOString(),
+                    },
+                });
             }
             this.#opts.onReady?.({ operation, cached: false, attempts: built.attempts });
             return { key: operation.key, source: built.source, cached: false };
@@ -91,6 +109,25 @@ export class Cache {
             this.#leave();
         }
     }
+    /**
+     * A hit is written into the box before it is returned. The container runs
+     * files under its mount and nothing else, and the mount is scratch that any
+     * `cache clear` is free to delete.
+     */
+    async #read(box, key) {
+        const found = this.#store.get(key);
+        if (!found?.source?.trim()) {
+            return undefined;
+        }
+        try {
+            await box.write(key, found.source);
+        }
+        catch {
+            // The mount went away. Writing it again is the model's job.
+            return undefined;
+        }
+        return found.source;
+    }
     #enter() {
         if (this.#running < this.#slots) {
             this.#running++;
@@ -108,18 +145,5 @@ export class Cache {
         this.#running--;
     }
 }
-async function read(box, key) {
-    const path = box.sourceOf(key);
-    if (!existsSync(path)) {
-        return undefined;
-    }
-    try {
-        const source = await readFile(path, 'utf8');
-        return source.trim() ? source : undefined;
-    }
-    catch {
-        return undefined;
-    }
-}
 export { BuildFailed };
 //# sourceMappingURL=cache.js.map

package/dist/command.js

@@ -1,8 +1,8 @@
+import { bold, cacheItems, clearCache, CliError, cyan, dim, EXIT, green, json, note, ownedContainers, parse, paths, red, removeContainers, table, usageError, write, writeAll, yellow, } from '@zenera/cli/lib';
 import { rmSync } from 'node:fs';
-import { readdir, readFile } from 'node:fs/promises';
 import { join, relative, resolve } from 'node:path';
-import { bold, CliError, cyan, dim, EXIT, green, json, note, ownedContainers, parse, paths, red, removeContainers, table, usageError, write, writeAll, yellow, } from '@zenera/cli/lib';
 import { GENERATORS } from "./box.js";
+import { FAKER_KIND } from "./cache.js";
 import { reason } from "./generate.js";
 import { listen } from "./server.js";
 import { open } from "./setup.js";
@@ -53,7 +53,7 @@ export const command = {
             ['  --host <h>', dim('Default 127.0.0.1. Anything else is reachable off-machine.')],
             ['  --model <ref>', dim('Which model writes the generators.')],
             ['  --image <ref>', dim('Skip the baked image and use this one.')],
-            ['  --cache <dir>', dim('Where generators live. Default ~/.zenera/neo/faker.')],
+            ['  --cache <dir>', dim("The container's workspace. Default ~/.zenera/neo/faker.")],
             ['  --seed <n>', dim('Answer the same request the same way every time.')],
             ['  --attempts <n>', dim('Tries per generator before giving up. Default 3.')],
             ['  --concurrency <n>', dim('Generators written at once. Default 4.')],
@@ -190,7 +190,7 @@ async function cache(args, ctx) {
     const root = values.cache ? resolve(ctx.cwd, values.cache) : paths.faker();
     const sub = positionals[0] ?? 'ls';
     if (sub === 'ls') {
-        const entries = await listGenerators(root);
+        const entries = listGenerators();
         if (ctx.json) {
             json(entries);
             return;
@@ -211,6 +211,9 @@ async function cache(args, ctx) {
         return;
     }
     if (sub === 'clear') {
+        clearCache({ kind: FAKER_KIND });
+        // The workspace is scratch — whatever a hit was copied into it is
+        // written again from the cache, or by the model.
         rmSync(join(root, GENERATORS), { recursive: true, force: true });
         // The container is named after its configuration, so a stale one would
         // otherwise sit there stopped forever with nothing pointing at it.
@@ -219,30 +222,21 @@ async function cache(args, ctx) {
         if (mine.length > 0) {
             await removeContainers(mine.map((c) => c.name));
         }
-        note(`${green('cleared')} ${dim(root)}`);
+        note(`${green('cleared')} ${dim(paths.cache())}`);
         return;
     }
     throw usageError(`unknown cache command "${sub}"`, 'zen faker cache <ls|clear>');
 }
-async function listGenerators(root) {
-    let keys;
-    try {
-        keys = await readdir(join(root, GENERATORS));
-    }
-    catch {
-        return [];
-    }
-    const out = [];
-    for (const key of keys.sort()) {
-        try {
-            const meta = JSON.parse(await readFile(join(root, GENERATORS, key, 'meta.json'), 'utf8'));
-            out.push({ key, ...meta });
-        }
-        catch {
-            out.push({ key });
-        }
-    }
-    return out;
+/**
+ * The keys are the operation keys, written verbatim — which is why they can be
+ * listed at all. Anything the store cannot parse is left out rather than shown
+ * as a row with nothing in it.
+ */
+function listGenerators() {
+    const { rows } = cacheItems(FAKER_KIND);
+    return rows
+        .map((row) => ({ key: row.key, ...row.value?.meta }))
+        .sort((a, b) => a.key.localeCompare(b.key));
 }
 function summarize(operations) {
     const by = new Map();

package/dist/generate.js

@@ -1,4 +1,5 @@
-import { echoIssues, probesFor } from "./probe.js";
+import { tokenOf } from "./paging.js";
+import { echoIssues, nextPage, probesFor, walkStart } from "./probe.js";
 import { instruction, retry, SYSTEM } from "./prompt.js";
 import { describeIssues, issues } from "./validate.js";
 export class BuildFailed extends Error {
@@ -106,8 +107,57 @@ async function judge(operation, probes, response, box) {
             out.push(`- ${called}: ${describeIssues(echo)}.`);
         }
     }
+    // Only worth the container round trips once the file answers at all, and
+    // only for an operation that hands out a token somebody could follow.
+    if (out.length === 0 && operation.paging?.next) {
+        out.push(...(await walk(operation, operation.paging, response, box)));
+    }
     return out;
 }
+/** How many pages a mock may offer before it is simply not terminating. */
+const MAX_PAGES = 8;
+/**
+ * Follows the operation's own cursor and reports the ways that walk fails to
+ * end. A schema cannot express this and neither can any one response: the bug
+ * is a relation between two of them.
+ */
+async function walk(operation, paging, response, box) {
+    let input = walkStart(operation, paging);
+    const seen = new Set();
+    let sent;
+    for (let page = 1; page <= MAX_PAGES; page++) {
+        const outcome = await box.run(operation.key, input);
+        const called = `page ${page} of ${operation.method.toUpperCase()} ${operation.path}`;
+        if (!outcome.ok) {
+            return [`- ${called}: the file ${outcome.fault}.`];
+        }
+        if (response && !response(outcome.value)) {
+            return [
+                `- ${called}: the output does not match the response schema — ${describeIssues(issues('', response.errors))}.`,
+            ];
+        }
+        const token = tokenOf(outcome.value, paging);
+        if (token === undefined) {
+            return [];
+        }
+        if (token === sent) {
+            return [
+                `- ${called}: \`${paging.next}\` came back as ${JSON.stringify(token)}, the very token the request carried in \`${paging.param}\`. A client following it never advances. Build the token from \`${paging.param}\` so it counts up, and stop after three pages.`,
+            ];
+        }
+        if (seen.has(token)) {
+            return [
+                `- ${called}: the page tokens cycle — ${JSON.stringify(token)} was handed out earlier in this walk. Every page must offer a token no page has offered before, and the last one must offer none.`,
+            ];
+        }
+        seen.add(token);
+        sent = token;
+        input = nextPage(input, paging, token);
+    }
+    return [
+        `- ${operation.method.toUpperCase()} ${operation.path}: the pages never run out — after ${MAX_PAGES} of them \`${paging.next}\` is still set. Fabricate three pages in total and set it to null on the last.`,
+    ];
+}
 /**
  * Models fence code even when told not to, and a stray ```python line is a
  * syntax error rather than a bad answer — not worth a round trip.

package/dist/paging.d.ts

@@ -0,0 +1,51 @@
+import { type Schema } from './schema.ts';
+import type { ParamSpec } from './spec.ts';
+export type PagingStyle = 'cursor' | 'offset';
+export interface Paging {
+    style: PagingStyle;
+    /** the query parameter that turns the page */
+    param: string;
+    /** the page-size parameter, when the operation takes one */
+    size?: string;
+    /** the response property carrying the token for the page after this one */
+    next?: string;
+    /** whether `next` may be set to null */
+    nextNullable?: boolean;
+    /** whether the object declaring `next` lists it as required */
+    nextRequired?: boolean;
+    /** a boolean response property — `has_more` and friends */
+    more?: string;
+    /** the array of things being paged over */
+    items?: string;
+}
+/**
+ * The paging shape of an operation, or nothing when it does not page.
+ *
+ * A page-size parameter on its own is not pagination — plenty of endpoints cap
+ * a one-shot list — so a control that turns the page *and* a property that says
+ * where the next one is are both required.
+ */
+export declare function pagingOf(params: readonly ParamSpec[], schema: Schema | undefined): Paging | undefined;
+/**
+ * The paging an actual request reveals, for a document that declared none.
+ *
+ * Plenty of specs describe the response envelope — `cursor`, `has_more` — and
+ * never write down the parameter that reads it back. A client only sends
+ * `?cursor=X` because a body handed it X, so the exchange is pagination on the
+ * evidence even when the document is silent, and silence is exactly the case
+ * nothing else here can catch.
+ */
+export declare function pagingSeen(params: readonly ParamSpec[], schema: Schema | undefined, query: Iterable<[string, string]>): Paging | undefined;
+/** The token a body offers for the next page, or nothing when it offers none. */
+export declare function tokenOf(value: unknown, paging: Paging): string | undefined;
+/**
+ * A last line of defence, for the generator that is already on disk: a body
+ * offering the very token it was given is cut back to "no more pages".
+ *
+ * Deliberately timid. Nothing re-validates a generator's output on the way to
+ * the client, so writing `null` into a required, non-nullable property would
+ * trade a client that hangs for a mock that lies — and a hang is at least
+ * obvious. Where the schema leaves no room, this changes nothing and says so.
+ */
+export declare function cutLoop(value: unknown, paging: Paging, sent: string): boolean;
+//# sourceMappingURL=paging.d.ts.map

package/dist/paging.js

@@ -0,0 +1,209 @@
+import { properties } from "./schema.js";
+const squash = (name) => name.toLowerCase().replace(/[^a-z0-9]/g, '');
+const CURSOR_PARAMS = new Set([
+    'cursor',
+    'nextcursor',
+    'pagetoken',
+    'nextpagetoken',
+    'continuationtoken',
+    'nexttoken',
+    'pagecursor',
+    'after',
+    'marker',
+    'startkey',
+]);
+const OFFSET_PARAMS = new Set([
+    'offset',
+    'page',
+    'pagenumber',
+    'pageindex',
+    'start',
+    'startindex',
+    'skip',
+]);
+const SIZE_PARAMS = new Set([
+    'pagesize',
+    'perpage',
+    'limit',
+    'maxresults',
+    'maxitems',
+    'count',
+    'size',
+]);
+const NEXT_PROPS = new Set([
+    'nextcursor',
+    'nextpagetoken',
+    'nexttoken',
+    'nextoffset',
+    'nextpage',
+    'nextlink',
+    'nexturl',
+    'next',
+    'cursor',
+    'pagetoken',
+    'continuationtoken',
+    'marker',
+]);
+const MORE_PROPS = new Set([
+    'hasmore',
+    'hasnext',
+    'hasnextpage',
+    'more',
+    'islast',
+    'islastpage',
+    'istruncated',
+    'truncated',
+]);
+const ITEMS_PROPS = new Set([
+    'items',
+    'results',
+    'data',
+    'values',
+    'records',
+    'entries',
+    'objects',
+    'content',
+    'list',
+    'edges',
+]);
+/**
+ * The paging shape of an operation, or nothing when it does not page.
+ *
+ * A page-size parameter on its own is not pagination — plenty of endpoints cap
+ * a one-shot list — so a control that turns the page *and* a property that says
+ * where the next one is are both required.
+ */
+export function pagingOf(params, schema) {
+    if (!schema) {
+        return undefined;
+    }
+    const query = params.filter((p) => p.in === 'query');
+    const cursor = query.find((p) => CURSOR_PARAMS.has(squash(p.name)));
+    const offset = query.find((p) => OFFSET_PARAMS.has(squash(p.name)) && numeric(p.schema));
+    const param = cursor ?? offset;
+    if (!param) {
+        return undefined;
+    }
+    const declared = properties(schema);
+    const next = declared.find((d) => NEXT_PROPS.has(squash(d.name)));
+    const more = declared.find((d) => MORE_PROPS.has(squash(d.name)) && boolish(d.schema));
+    if (!next && !more) {
+        return undefined;
+    }
+    return {
+        style: cursor ? 'cursor' : 'offset',
+        param: param.name,
+        size: query.find((p) => SIZE_PARAMS.has(squash(p.name)))?.name,
+        next: next?.name,
+        nextNullable: next ? nullable(next.schema) : undefined,
+        nextRequired: next?.required,
+        more: more?.name,
+        items: itemsOf(declared),
+    };
+}
+/**
+ * The paging an actual request reveals, for a document that declared none.
+ *
+ * Plenty of specs describe the response envelope — `cursor`, `has_more` — and
+ * never write down the parameter that reads it back. A client only sends
+ * `?cursor=X` because a body handed it X, so the exchange is pagination on the
+ * evidence even when the document is silent, and silence is exactly the case
+ * nothing else here can catch.
+ */
+export function pagingSeen(params, schema, query) {
+    const declared = new Set(params.map((p) => p.name));
+    const extra = [];
+    for (const [name, value] of query) {
+        if (value !== '' && !declared.has(name)) {
+            declared.add(name);
+            extra.push({ name, in: 'query', required: false, schema: guess(value) });
+        }
+    }
+    return extra.length === 0 ? undefined : pagingOf([...params, ...extra], schema);
+}
+/** The token a body offers for the next page, or nothing when it offers none. */
+export function tokenOf(value, paging) {
+    if (!paging.next) {
+        return undefined;
+    }
+    const holder = holderOf(value, paging.next);
+    const token = holder?.[paging.next];
+    if (token === null || token === undefined || token === '') {
+        return undefined;
+    }
+    return typeof token === 'object' ? JSON.stringify(token) : String(token);
+}
+/**
+ * A last line of defence, for the generator that is already on disk: a body
+ * offering the very token it was given is cut back to "no more pages".
+ *
+ * Deliberately timid. Nothing re-validates a generator's output on the way to
+ * the client, so writing `null` into a required, non-nullable property would
+ * trade a client that hangs for a mock that lies — and a hang is at least
+ * obvious. Where the schema leaves no room, this changes nothing and says so.
+ */
+export function cutLoop(value, paging, sent) {
+    if (!paging.next || tokenOf(value, paging) !== sent) {
+        return false;
+    }
+    const holder = holderOf(value, paging.next);
+    if (!holder) {
+        return false;
+    }
+    if (paging.nextNullable) {
+        holder[paging.next] = null;
+    }
+    else if (!paging.nextRequired) {
+        delete holder[paging.next];
+    }
+    else {
+        return false;
+    }
+    const more = paging.more ? holderOf(value, paging.more) : undefined;
+    if (more && paging.more) {
+        more[paging.more] = false;
+    }
+    return true;
+}
+/** The nearest object carrying `name`; a real body nests its envelope. */
+function holderOf(value, name) {
+    const seen = new Set();
+    let level = [value];
+    while (level.length > 0) {
+        const next = [];
+        for (const node of level) {
+            if (typeof node !== 'object' || node === null || seen.has(node)) {
+                continue;
+            }
+            seen.add(node);
+            if (Array.isArray(node)) {
+                next.push(...node);
+                continue;
+            }
+            const record = node;
+            if (name in record) {
+                return record;
+            }
+            next.push(...Object.values(record));
+        }
+        level = next;
+    }
+    return undefined;
+}
+function itemsOf(declared) {
+    const named = declared.find((d) => ITEMS_PROPS.has(squash(d.name)) && listish(d.schema));
+    return (named ?? declared.find((d) => listish(d.schema)))?.name;
+}
+const types = (schema) => {
+    const type = schema.type;
+    return typeof type === 'string' ? [type] : Array.isArray(type) ? type : [];
+};
+const numeric = (schema) => types(schema).some((t) => t === 'integer' || t === 'number');
+const boolish = (schema) => types(schema).includes('boolean');
+const listish = (schema) => types(schema).includes('array') || schema.items !== undefined;
+const nullable = (schema) => types(schema).includes('null');
+/** An undeclared parameter has only its value to be typed by. */
+const guess = (value) => ({
+    type: /^-?\d+$/.test(value) ? 'integer' : 'string',
+});
+//# sourceMappingURL=paging.js.map

package/dist/probe.d.ts

@@ -1,7 +1,12 @@
 import type { GeneratorInput } from './envelope.ts';
-import type { Schema } from './schema.ts';
+import type { Paging } from './paging.ts';
+import { type Schema } from './schema.ts';
 import type { Operation } from './spec.ts';
 import type { Issue } from './validate.ts';
 export declare function probesFor(operation: Operation): GeneratorInput[];
+/** The first page: an ordinary probe with the paging control taken back off. */
+export declare function walkStart(operation: Operation, paging: Paging): GeneratorInput;
+/** The same request again, asking for whatever the last answer pointed at. */
+export declare function nextPage(previous: GeneratorInput, paging: Paging, token: string): GeneratorInput;
 export declare function echoIssues(input: GeneratorInput, value: unknown, schema: Schema | undefined): Issue[];
 //# sourceMappingURL=probe.d.ts.map

package/dist/probe.js

@@ -1,3 +1,4 @@
+import { propertyNames } from "./schema.js";
 // ---------------------------------------------------------------------------
 // Probes
 //
@@ -165,6 +166,30 @@ function text(schema, variant) {
     return base.length >= min ? base : base.padEnd(min, 'x');
 }
 // ---------------------------------------------------------------------------
+// The walk
+//
+// The probes above are independent, which is the right shape for everything one
+// response can be wrong about and the wrong shape for pagination: a cursor only
+// means anything in the answer it arrived with, so the pages have to be asked
+// for in order.
+//
+// The seed is held still across the whole walk on purpose. A generator that
+// mints its token out of `seed` rather than out of the request is the exact
+// mistake being looked for, and a still seed makes it a fixed point — visible
+// on the second page here instead of on somebody's client.
+// ---------------------------------------------------------------------------
+/** The first page: an ordinary probe with the paging control taken back off. */
+export function walkStart(operation, paging) {
+    const input = probesFor(operation)[0];
+    const query = { ...input.query };
+    delete query[paging.param];
+    return { ...input, query };
+}
+/** The same request again, asking for whatever the last answer pointed at. */
+export function nextPage(previous, paging, token) {
+    return { ...previous, query: { ...previous.query, [paging.param]: token } };
+}
+// ---------------------------------------------------------------------------
 // The echo rule
 //
 // `get_user_by_id(12324)` answering `{ user_id: 999 }` validates perfectly and
@@ -199,47 +224,6 @@ export function echoIssues(input, value, schema) {
     }
     return out;
 }
-/** Every property name the schema mentions, at any depth. */
-function propertyNames(schema) {
-    const out = new Set();
-    const seen = new Set();
-    const stack = [schema];
-    while (stack.length > 0) {
-        const node = stack.pop();
-        if (typeof node !== 'object' || node === null) {
-            continue;
-        }
-        if (Array.isArray(node)) {
-            stack.push(...node);
-            continue;
-        }
-        if (seen.has(node)) {
-            continue;
-        }
-        seen.add(node);
-        const record = node;
-        const properties = record.properties;
-        if (typeof properties === 'object' && properties !== null) {
-            for (const [name, sub] of Object.entries(properties)) {
-                out.add(name);
-                stack.push(sub);
-            }
-        }
-        // `$defs` holds schemas under arbitrary names, so its *values* are the
-        // subschemas — pushing the map itself would walk one level and stop,
-        // which is where every hoisted recursive schema lives.
-        for (const key of ['$defs', 'patternProperties']) {
-            const map = record[key];
-            if (typeof map === 'object' && map !== null) {
-                stack.push(...Object.values(map));
-            }
-        }
-        for (const key of ['items', 'allOf', 'anyOf', 'oneOf', 'prefixItems', 'not']) {
-            stack.push(record[key]);
-        }
-    }
-    return out;
-}
 /** Whether `name` anywhere in the value holds something equal to `expected`. */
 function carries(value, name, expected) {
     const stack = [value];

package/dist/prompt.js

@@ -37,7 +37,9 @@ export const SYSTEM = [
     '   with `user_id=12324` answers with `user_id` 12324, not a random one. Do',
     '   this generically, by looking the names up at run time. Do the same for a',
     '   query parameter where it plainly describes the content rather than',
-    '   controlling the call.',
+    '   controlling the call. A paging control — a cursor, page, offset or',
+    '   page-size parameter — is never content and must not be copied into the',
+    '   body; see PAGINATION below where the operation has one.',
     '3. Every required property must be present. Optional ones may be omitted',
     '   sometimes; that is what makes a mock useful.',
     '4. Values must suit their names, not just their types. Use `faker` for anything',
@@ -71,10 +73,62 @@ export function brief(operation) {
     if (operation.requestBody) {
         lines.push('', 'REQUEST BODY SCHEMA (arrives as `body`)', json(operation.requestBody.schema));
     }
+    if (operation.paging) {
+        lines.push('', ...pagination(operation.paging));
+    }
     lines.push('', `RESPONSE SCHEMA (status ${operation.success.status})`);
     lines.push(operation.success.schema ? json(operation.success.schema) : '  (no body)');
     return lines.join('\n');
 }
+/**
+ * Said only to the operations that page, and said in terms of their own
+ * property names. The rule that earns the paragraph is the third one: a body
+ * offering the token it was just given passes the schema, passes the echo rule,
+ * and hangs every client that walks the list.
+ */
+function pagination(paging) {
+    const advance = paging.style === 'cursor'
+        ? 'the base64 of a small JSON object holding the next page index, such as {"p": 2}'
+        : "the offset of the next page — this page's offset plus its size";
+    const lines = [
+        'PAGINATION',
+        `  This operation is paged. \`${paging.param}\` asks for a page;`,
+        '  absent or empty means the first one.',
+        '  - Fabricate three pages in total and no more.',
+    ];
+    if (paging.next) {
+        lines.push(`  - \`${paging.next}\` carries the token for the page after this one.`, `    Build it out of \`${paging.param}\`:`, `    ${advance}.`, '  - Never build it out of `seed`. Unpinned, the seed changes on every', '    request; pinned, it is a function of the query. A token made from it', '    either wanders or never changes.', '  - It must strictly advance. Answering with the token you were given is', '    the one failure that matters: a client following it loops forever.');
+    }
+    if (paging.more && !stuck(paging)) {
+        lines.push(`  - \`${paging.more}\` is false on the last page and true before it.`);
+    }
+    if (paging.next) {
+        lines.push(...last(paging));
+    }
+    lines.push('  - A token you cannot read, or one past the end, is the last page,', `    ended the same way and with ${paging.items ? `\`${paging.items}\` empty` : 'nothing listed'}.`, '    Never an error, and never the first page again.');
+    return lines;
+}
+/**
+ * How the last page says so. A token that is required and cannot be null has
+ * nowhere to put the ending, so the ending has to be said some other way —
+ * telling the model to null it anyway would only ask for an invalid body.
+ */
+const stuck = (paging) => !paging.nextNullable && paging.nextRequired === true;
+function last(paging) {
+    if (paging.nextNullable) {
+        return [`  - On the last page set \`${paging.next}\` to null.`];
+    }
+    if (!stuck(paging)) {
+        return [`  - On the last page leave \`${paging.next}\` out.`];
+    }
+    const otherwise = [paging.more && `\`${paging.more}\` false`, paging.items && 'nothing listed']
+        .filter(Boolean)
+        .join(' and ');
+    return [
+        `  - The schema requires \`${paging.next}\` on every page, so the last page`,
+        `    ends the list the other way: ${otherwise || 'an empty page'}.`,
+    ];
+}
 /**
  * Repeated in the file the model writes, so it is worth spelling out: the
  * schema it validates against must be the one it was shown, embedded, not

package/dist/schema.d.ts

@@ -5,4 +5,17 @@ export type Dialect = 'swagger-2.0' | 'openapi-3.0' | 'openapi-3.1';
  * than once into `$defs`. The result is acyclic and safe to stringify.
  */
 export declare function normalize(root: unknown, dialect: Dialect): Schema;
+export interface Declared {
+    name: string;
+    /** the property's own schema, with a `$defs` pointer already followed */
+    schema: Schema;
+    /** whether the object declaring it lists it in `required` */
+    required: boolean;
+    /** how many objects deep it sits; 0 is the top level */
+    depth: number;
+}
+/** Every property a schema declares, at any depth, nearest first. */
+export declare function properties(root: Schema): Declared[];
+/** Every property name a schema mentions, at any depth. */
+export declare const propertyNames: (root: Schema) => Set<string>;
 //# sourceMappingURL=schema.d.ts.map

package/dist/schema.js

@@ -218,4 +218,79 @@ function repeated(root) {
     }
     return twice;
 }
+/** Every property a schema declares, at any depth, nearest first. */
+export function properties(root) {
+    const out = [];
+    const seen = new Set();
+    let level = [root];
+    for (let depth = 0; level.length > 0; depth++) {
+        const next = [];
+        for (const raw of level) {
+            const node = resolve(raw, root);
+            if (node === undefined || seen.has(node)) {
+                continue;
+            }
+            seen.add(node);
+            const required = new Set(Array.isArray(node.required)
+                ? node.required.filter((n) => typeof n === 'string')
+                : []);
+            const props = node.properties;
+            if (isObject(props)) {
+                for (const [name, sub] of Object.entries(props)) {
+                    const target = resolve(sub, root);
+                    if (target === undefined) {
+                        continue;
+                    }
+                    out.push({ name, schema: target, required: required.has(name), depth });
+                    next.push(sub);
+                }
+            }
+            for (const key of ONE) {
+                next.push(node[key]);
+            }
+            for (const key of LIST) {
+                const value = node[key];
+                if (Array.isArray(value)) {
+                    next.push(...value);
+                }
+            }
+            for (const key of MAP) {
+                if (key === 'properties') {
+                    continue;
+                }
+                const value = node[key];
+                if (isObject(value)) {
+                    next.push(...Object.values(value));
+                }
+            }
+            const items = node.items;
+            next.push(...(Array.isArray(items) ? items : [items]));
+        }
+        level = next;
+    }
+    return out;
+}
+/** Every property name a schema mentions, at any depth. */
+export const propertyNames = (root) => new Set(properties(root).map((p) => p.name));
+/** A schema, with a local `#/$defs/...` pointer followed as far as it goes. */
+function resolve(value, root) {
+    let at = value;
+    for (let hop = 0; hop < MAX_HOPS; hop++) {
+        if (!isObject(at)) {
+            return undefined;
+        }
+        const ref = at.$ref;
+        if (typeof ref !== 'string' || !ref.startsWith(DEFS)) {
+            return at;
+        }
+        const defs = root.$defs;
+        if (!isObject(defs)) {
+            return at;
+        }
+        at = defs[ref.slice(DEFS.length)];
+    }
+    return undefined;
+}
+const DEFS = '#/$defs/';
+const MAX_HOPS = 8;
 //# sourceMappingURL=schema.js.map

package/dist/server.js

@@ -2,6 +2,7 @@ import { createHash, randomInt } from 'node:crypto';
 import { createServer } from 'node:http';
 import { BuildFailed } from "./cache.js";
 import { reason } from "./generate.js";
+import { cutLoop, pagingSeen } from "./paging.js";
 import { describeIssues, issues } from "./validate.js";
 // ---------------------------------------------------------------------------
 // The server
@@ -134,8 +135,24 @@ async function handle(req, res, opts) {
         say(502, 'generator faulted');
         return;
     }
+    const note = generator.cached ? 'hit' : 'miss';
+    const looped = cut(operation, outcome.value, url.searchParams);
     send(res, operation.success.status, outcome.value);
-    say(operation.success.status, generator.cached ? 'hit' : 'miss');
+    say(operation.success.status, looped ? `${note} · cut a looping page token` : note);
+}
+/**
+ * The generator on disk was written before the pagination rule existed, and a
+ * cache is not rebuilt just because the rule changed. A body offering back the
+ * token it was handed is therefore still possible, and it is the one bug here
+ * that costs the client rather than the mock: it hangs.
+ */
+function cut(operation, value, query) {
+    const paging = operation.paging ?? pagingSeen(operation.params, operation.success.schema, query);
+    if (!paging) {
+        return false;
+    }
+    const sent = query.get(paging.param);
+    return sent !== null && cutLoop(value, paging, sent);
 }
 function check(operation, checks, pathParams, query, body) {
     const compiled = checks.for(operation);
@@ -235,6 +252,7 @@ function introspect(pathname, res, opts) {
             operationId: o.operationId,
             status: o.success.status,
             body: Boolean(o.success.schema),
+            paging: o.paging,
             key: o.key,
             source: o.source,
         })));

package/dist/spec.d.ts

@@ -1,4 +1,5 @@
 import { CliError } from '@zenera/cli/lib';
+import { type Paging } from './paging.ts';
 import { type Schema } from './schema.ts';
 export declare const METHODS: readonly ["get", "put", "post", "delete", "patch", "head", "options"];
 export type Method = (typeof METHODS)[number];
@@ -31,6 +32,8 @@ export interface Operation {
         status: number;
         schema?: Schema;
     };
+    /** how the operation turns pages, when it turns pages at all */
+    paging?: Paging;
 }
 /** A `CliError` so an unreadable document exits 3 wherever it is raised. */
 export declare class SpecError extends CliError {

package/dist/spec.js

@@ -1,6 +1,7 @@
 import SwaggerParser from '@apidevtools/swagger-parser';
-import { createHash } from 'node:crypto';
 import { CliError, EXIT } from '@zenera/cli/lib';
+import { createHash } from 'node:crypto';
+import { pagingOf } from "./paging.js";
 import { normalize } from "./schema.js";
 // ---------------------------------------------------------------------------
 // Documents, flattened
@@ -103,6 +104,7 @@ function build(b) {
         params: b.params,
         requestBody: b.body,
         success,
+        paging: pagingOf(b.params, success.schema),
     };
     return { ...operation, key: keyOf(operation) };
 }
@@ -123,6 +125,12 @@ function keyOf(op) {
             .map((p) => [p.in, p.name, p.required, canonical(p.schema)]),
         body: op.requestBody ? [op.requestBody.required, canonical(op.requestBody.schema)] : null,
         success: [op.success.status, op.success.schema ? canonical(op.success.schema) : null],
+        // Derived from the two above, so it adds nothing to the identity — it is
+        // here to *change* it, once, for the operations whose generator now has
+        // a pagination rule to obey. Absent rather than null when there is no
+        // paging, so that everything else hashes to exactly what it did before
+        // and no one else is asked to rebuild.
+        ...(op.paging ? { paging: canonical(op.paging) } : {}),
     };
     return createHash('sha256').update(JSON.stringify(shape)).digest('hex').slice(0, 16);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@zenera/faker",
-    "version": "1.1.9",
+    "version": "1.1.11",
     "description": "Mock HTTP server for swagger/OpenAPI documents, with response bodies generated by a model.",
     "keywords": [
         "openapi",
@@ -45,7 +45,7 @@
         "@apidevtools/swagger-parser": "^12.0.0",
         "ajv": "^8.17.1",
         "ajv-formats": "^3.0.1",
-        "@zenera/cli": "^1.1.9",
-        "@zenera/neo": "^1.1.9"
+        "@zenera/cli": "^1.1.11",
+        "@zenera/neo": "^1.1.11"
     }
 }