@zenera/faker 1.1.10 → 1.1.11

package/README.md

@@ -60,9 +60,11 @@ 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`.
@@ -88,7 +90,7 @@ happen, all in the operation's own names:
 - 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 on disk, and a cache is not rebuilt because a rule changed.
+  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.
@@ -110,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/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@zenera/faker",
-    "version": "1.1.10",
+    "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.10",
-        "@zenera/neo": "^1.1.10"
+        "@zenera/cli": "^1.1.11",
+        "@zenera/neo": "^1.1.11"
     }
 }