@loopingai/core 0.1.2 → 0.3.0

package/dist/testing/vcr-store.js

@@ -0,0 +1,192 @@
+/**
+ * Cassette load / match / write. **Node realm** (`node:fs`, `node:crypto`), no
+ * network and no `undici` — the recorder that drives this lives in `vcr.ts`.
+ *
+ * ## Why this replaced undici's `SnapshotAgent`
+ *
+ * `SnapshotAgent` keys every entry on a hash of method + URL + *every
+ * non-excluded request header*. In a Worker test those headers are runtime
+ * artifacts: a cassette recorded through the pool carries `user-agent: undici`,
+ * `cf-worker: vitest-pool-workers-runner-.example.com`, `sec-fetch-mode` and
+ * `accept-encoding`. Bump miniflare or workerd, any one of them changes, and
+ * every entry in every committed cassette misses at once — a whole suite going
+ * red with `No snapshot found` and nothing to point at.
+ *
+ * So the key here is **method + URL + request body**, and nothing else. Headers
+ * are still stored (minus secrets, see {@link CassetteOptions.excludeHeaders})
+ * because they are useful to read in a diff, but they cannot break a replay.
+ *
+ * The on-disk format is deliberately unchanged from `SnapshotAgent`'s, so
+ * cassettes recorded before this rewrite replay untouched — see {@link load}.
+ */
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import path from "node:path";
+/**
+ * Headers that describe how a body was framed on the wire, which is not how it
+ * is framed on replay: bodies are stored decoded and are handed back whole, so
+ * replaying `transfer-encoding: chunked` or a stale `content-length` mis-frames
+ * the response, and `content-encoding: gzip` makes the consumer try to inflate
+ * plaintext. Stripped on the way out, kept in the file.
+ */
+const HOP_BY_HOP = new Set([
+    "connection",
+    "content-encoding",
+    "content-length",
+    "keep-alive",
+    "proxy-authenticate",
+    "proxy-authorization",
+    "te",
+    "trailer",
+    "transfer-encoding",
+    "upgrade"
+]);
+/** `${METHOD}\n${url}\n${sha256(body)}` — the whole matching rule. */
+export function requestKey(method, url, body) {
+    const digest = createHash("sha256").update(body, "utf8").digest("base64url");
+    return `${method.toUpperCase()}\n${url}\n${digest}`;
+}
+function filterHeaders(headers, exclude) {
+    const kept = {};
+    for (const [name, value] of Object.entries(headers)) {
+        if (!exclude.has(name.toLowerCase()))
+            kept[name.toLowerCase()] = value;
+    }
+    return kept;
+}
+/**
+ * Turn a stored response into the pieces a `Response` is built from: body
+ * decoded from base64, headers flattened (a repeated header such as
+ * `set-cookie` becomes one entry per value) and {@link HOP_BY_HOP} dropped.
+ *
+ * Used on both paths, so a response served straight after recording is framed
+ * exactly as the same response will be on replay.
+ */
+export function replayable(response) {
+    const headers = [];
+    for (const [name, value] of Object.entries(response.headers)) {
+        if (HOP_BY_HOP.has(name.toLowerCase()))
+            continue;
+        for (const one of Array.isArray(value) ? value : [value]) {
+            headers.push([name, one]);
+        }
+    }
+    return {
+        status: response.statusCode,
+        headers,
+        body: Buffer.from(response.body, "base64")
+    };
+}
+/**
+ * One cassette file, loaded lazily and written only when it has changed.
+ *
+ * Playback is **read-only**: nothing here mutates on a replay, which is what
+ * stops a plain `npm test` from dirtying committed cassettes. `SnapshotAgent`
+ * persisted its `callCount` and re-saved on close, so every run left the files
+ * modified; the equivalent counter here ({@link #calls}) is in memory and dies
+ * with the process.
+ */
+export class Cassette {
+    #file;
+    #exclude;
+    /** Insertion-ordered, keyed by {@link requestKey}. */
+    #entries = new Map();
+    /** How many times each key has been replayed *this run*. Never persisted. */
+    #calls = new Map();
+    #dirty = false;
+    constructor(file, options = {}) {
+        this.#file = file;
+        this.#exclude = new Set((options.excludeHeaders ?? []).map((h) => h.toLowerCase()));
+    }
+    get file() {
+        return this.#file;
+    }
+    /** Every request in the file, as `METHOD url`, for error messages. */
+    get recorded() {
+        return [...this.#entries.values()].map((e) => `${e.request.method} ${e.request.url}`);
+    }
+    /**
+     * Read the file into memory. Tolerates both shapes: `SnapshotAgent` wrapped
+     * each entry in `{ hash, snapshot: { request, responses } }`, this writes the
+     * same wrapper (so a re-record diffs cleanly against an old cassette) but
+     * ignores `hash`, `callCount` and `timestamp` — all three were volatile
+     * bookkeeping and none is needed to replay.
+     *
+     * Entries are re-keyed on load rather than trusted, which is the point of the
+     * rewrite. Two legacy entries that differed *only* by a request header now
+     * collapse onto one key; their responses are concatenated in file order,
+     * which is exactly the sequential-response semantics {@link match} walks.
+     */
+    load() {
+        if (!existsSync(this.#file))
+            return;
+        const raw = JSON.parse(readFileSync(this.#file, "utf8"));
+        if (!Array.isArray(raw)) {
+            throw new Error(`VCR cassette ${this.#file} is not a JSON array`);
+        }
+        for (const item of raw) {
+            const entry = (item.snapshot ??
+                item);
+            const { request, responses } = entry;
+            const key = requestKey(request.method, request.url, request.body ?? "");
+            const existing = this.#entries.get(key);
+            if (existing)
+                existing.responses.push(...responses);
+            else
+                this.#entries.set(key, { request, responses: [...responses] });
+        }
+    }
+    /**
+     * The next recorded response for this request, or `null` if it was never
+     * recorded.
+     *
+     * Repeated identical requests walk `responses` in order and then **hold on
+     * the last one**, matching what `SnapshotAgent` did
+     * (`responses[min(callCount, length - 1)]`). A recording that captured one
+     * response therefore replays it for every call, which is what a poll loop
+     * needs.
+     */
+    match(method, url, body) {
+        const key = requestKey(method, url, body);
+        const entry = this.#entries.get(key);
+        if (!entry)
+            return null;
+        const call = this.#calls.get(key) ?? 0;
+        this.#calls.set(key, call + 1);
+        return replayable(entry.responses[Math.min(call, entry.responses.length - 1)]);
+    }
+    /** Append a live response. Repeats of a request extend its `responses`. */
+    record(request, response) {
+        const key = requestKey(request.method, request.url, request.body);
+        const stored = {
+            ...response,
+            headers: filterHeaders(response.headers, this.#exclude)
+        };
+        const entry = this.#entries.get(key);
+        if (entry) {
+            entry.responses.push(stored);
+        }
+        else {
+            this.#entries.set(key, {
+                request: {
+                    ...request,
+                    headers: filterHeaders(request.headers, this.#exclude)
+                },
+                responses: [stored]
+            });
+        }
+        this.#dirty = true;
+    }
+    /** Write if anything was recorded since the last flush. A no-op in playback. */
+    flush() {
+        if (!this.#dirty)
+            return;
+        mkdirSync(path.dirname(this.#file), { recursive: true });
+        const entries = [...this.#entries.values()].map((snapshot) => ({
+            snapshot
+        }));
+        writeFileSync(this.#file, `${JSON.stringify(entries, null, 2)}\n`);
+        this.#dirty = false;
+    }
+}
+//# sourceMappingURL=vcr-store.js.map

package/dist/testing/vcr-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vcr-store.js","sourceRoot":"","sources":["../../src/testing/vcr-store.ts"],"names":[],"mappings":"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"}

package/dist/testing/vcr.d.ts

@@ -1,81 +1,118 @@
-import { MockAgent, type Dispatcher } from "undici";
-export interface CreateVcrAgentOptions {
-    /** Absolute path of the cassettes directory (test/snapshots/). */
+/**
+ * The **Node realm** half of the VCR harness: a Miniflare `outboundService`.
+ *
+ * ## Why `outboundService` and not `fetchMock`
+ *
+ * Miniflare 4 implemented `fetchMock` as one line of sugar over this same hook —
+ * `outboundService = (req) => fetch(req, { dispatcher: fetchMock })` — and
+ * Miniflare 5 dropped `fetchMock` entirely, keeping only `outboundService`.
+ * `@cloudflare/vitest-pool-workers` 0.20 removed it from its override options to
+ * match, saying so in as many words: *"`fetchMock`: you should use
+ * `outboundService` instead"*. Targeting the hook rather than the sugar is what
+ * lets one harness serve pool 0.18 through 0.20+.
+ *
+ * It also drops two constraints that had nothing to do with recording:
+ *
+ *  - **No `undici` peer.** `fetchMock` was validated with
+ *    `z.instanceof(MockAgent)` against *Miniflare's own* undici, so a second copy
+ *    in `node_modules` failed with `Input not instance of MockAgent` and the peer
+ *    range had to track Miniflare's exact pin. `outboundService` has no
+ *    `instanceof` check in either direction — a foreign `Response` is re-wrapped.
+ *  - **No silent no-op.** An unknown key in the `miniflare` options is ignored,
+ *    which is how a harness wired to `fetchMock` on pool 0.20 failed: every
+ *    request escaped to the real network and died as `internal error;
+ *    reference = …`, naming nothing. `setupRecording()` now proves the recorder
+ *    answered before a test runs — see {@link VCR_MARKER_HEADER}.
+ *
+ * ## How a request is routed
+ *
+ * Every outbound `fetch()` from workerd arrives here as a standard `Request`,
+ * with the true target URL already restored by Miniflare, and is dispatched on
+ * host alone:
+ *
+ *  - **The control channel** ({@link VCR_CONTROL_ORIGIN}) — specs run in workerd
+ *    and have no filesystem, so an in-band `fetch` is the only way to say which
+ *    cassette the current test is using. See `setupRecording` (vcr-spec.ts).
+ *  - **A {@link VcrOptions.handlers} host** — a consumer-supplied stub, for
+ *    things that are fixtures rather than recordings (a gateway JWKS).
+ *  - **An {@link VcrOptions.allowNetworkHosts} host** — the real network, always.
+ *  - **Anything else, cassette active** — recorded or replayed against it.
+ *  - **Anything else, no cassette** — blocked. A test that was never wired for
+ *    recording cannot reach the network by accident.
+ */
+/** Minimal shape of the `Request` Miniflare hands an outbound service. */
+export interface VcrRequestHeaders {
+    forEach(callback: (value: string, name: string) => void): void;
+    get(name: string): string | null;
+}
+/** Minimal shape of the `Request` Miniflare hands an outbound service. */
+export interface VcrRequest {
+    readonly url: string;
+    readonly method: string;
+    readonly headers: VcrRequestHeaders;
+    arrayBuffer(): Promise<ArrayBuffer>;
+}
+/**
+ * Structural on purpose: core does not depend on `miniflare`, and this type
+ * assigns to `WorkerOptions["outboundService"]` under both Miniflare 4 and 5.
+ */
+export type VcrOutboundService = (request: VcrRequest) => Promise<Response>;
+export interface VcrOptions {
+    /** Absolute path of the cassettes directory. */
     snapshotsDir: string;
     /**
-     * true → every activated cassette records real traffic, unconditionally
-     * overwriting whatever was there (undici's `"record"` mode never loads or
-     * matches existing entries, unlike `"update"` — see {@link VcrAgent.agentFor}).
-     * false → replay.
+     * true → every activated cassette captures live traffic, replacing whatever
+     * was there. Recording never loads the existing file first, so a recording run
+     * always reflects the live API rather than half of a stale one.
+     * false → replay, and no request ever leaves the machine.
      */
     record: boolean;
-    /** Hosts served by ordinary MockAgent interceptors, never VCR'd (the gateway JWKS). */
-    passthroughHosts: string[];
-    /** Request headers never written to a cassette (secrets: API keys, auth). */
+    /** Hosts answered by a stub instead of a cassette (e.g. a gateway JWKS). */
+    handlers?: Record<string, (request: VcrRequest) => Response | Promise<Response>>;
+    /** Hosts that always reach the real network, recorded or not. */
+    allowNetworkHosts?: string[];
+    /** Request *and* response headers never written to a cassette (API keys, auth). */
     excludeHeaders?: string[];
-    /** Headers stored but excluded from request matching (e.g. session cookies). */
-    ignoreHeaders?: string[];
+}
+export interface Vcr {
+    /** Hand this to `cloudflareTest({ miniflare: { outboundService } })`. */
+    readonly outboundService: VcrOutboundService;
+    /** Flush every cassette. Safe to call more than once. */
+    close(): Promise<void>;
 }
 /**
- * The single agent Miniflare accepts as `fetchMock` (it allows only one), fanning
- * outbound worker requests out by role:
+ * Build the recorder and register it for {@link closeVcr}.
  *
- *  - **Control channel** ({@link VCR_CONTROL_ORIGIN}) → ordinary MockAgent
- *    interceptors whose reply callbacks flip the *active cassette*. This is how a
- *    spec running in workerd (no filesystem) tells this Node-side agent which
- *    test is running — see `setupRecording` (vcr-spec.ts).
- *  - **Passthrough hosts** (the gateway JWKS) → ordinary MockAgent interceptors,
- *    unchanged from before VCR existed.
- *  - **Everything else, while a cassette is active** → that cassette's undici
- *    {@link SnapshotAgent} record/replay. In playback a request with no matching
- *    recording throws `No snapshot found` — offline, never the network.
- *  - **Everything else, with no active cassette** → ordinary MockAgent behavior
- *    (`disableNetConnect()` → offline error). A non-recorded test never reaches
- *    the network.
+ * ```ts
+ * // vitest.config.ts
+ * const vcr = createVcr({
+ *   snapshotsDir: path.resolve(import.meta.dirname, "test/snapshots"),
+ *   record: recordFromEnv(),
+ *   excludeHeaders: ["x-api-key", "authorization", "cookie", "set-cookie"]
+ * });
  *
- * There is **no registry**: cassettes are keyed per test (file + describe + test
- * name) by the spec helper, activated one at a time over the control channel. A
- * new recorded spec touches only its own `.spec` file.
+ * export default defineConfig({
+ *   plugins: [cloudflareTest({ miniflare: { outboundService: vcr.outboundService } })],
+ *   test: { globalSetup: ["@loopingai/core/testing/vcr-global-setup"] }
+ * });
+ * ```
+ */
+export declare function createVcr(options: VcrOptions): Vcr;
+/**
+ * Whether this run records, from `RECORD`.
  *
- * Why `VcrAgent extends MockAgent` rather than `SnapshotAgent`: a `SnapshotAgent`'s
- * `dispatch` fully overrides `MockAgent`'s (it never falls back to the interceptor
- * path), so one `SnapshotAgent` cannot also serve the control/interceptor fixtures
- * — and cannot serve more than one cassette. Keeping one internal `SnapshotAgent`
- * per cassette and dispatching to the active one, with an ordinary
- * `MockAgent.dispatch` fallback for control/passthrough/offline, leaves the
- * interceptor path exactly as it always worked. Miniflare validates `fetchMock`
- * with `instanceof MockAgent`, which `VcrAgent` satisfies directly.
+ * Compared against `"1"` rather than tested for truthiness, because every
+ * non-empty string is truthy: `RECORD=0` and `RECORD=false` — the two things
+ * someone reaches for to turn recording *off* — would otherwise turn it on and
+ * overwrite committed cassettes with live traffic. The opposite mistake
+ * (`RECORD=true` not recording) fails loudly on the next assertion and costs
+ * nothing.
  */
-export declare class VcrAgent extends MockAgent {
-    #private;
-    constructor(options: CreateVcrAgentOptions);
-    dispatch(opts: Dispatcher.DispatchOptions, handler: Dispatcher.DispatchHandler): boolean;
-    /**
-     * Closes every cassette's `SnapshotAgent`, then this agent.
-     *
-     * Record mode: `SnapshotAgent.close()` saves each cassette, stops its
-     * recorder's auto-flush timer, and closes its real sockets — all required (see
-     * {@link closeVcr}). We then {@link stripVolatileFields} from each saved file
-     * so the committed cassette carries no `callCount`/`timestamp`.
-     *
-     * Playback mode: undici's `SnapshotAgent.close()` *unconditionally* re-saves
-     * the cassette, writing back the `callCount` its recorder mutates on every
-     * replay — the side effect that dirtied cassettes on a plain `npm test`. There
-     * is nothing to save and no real socket in playback, so we skip that save
-     * entirely and only stop each recorder's timers.
-     */
-    close(): Promise<void>;
-}
-export declare function createVcrAgent(options: CreateVcrAgentOptions): VcrAgent;
+export declare function recordFromEnv(): boolean;
 /**
- * Flush and close the active VCR agent (all its cassettes). In record mode,
- * undici's recorder arms a self-refreshing, non-`unref`ed auto-flush timer and
- * the real `SnapshotAgent` keeps sockets open — both keep the process alive
- * after tests finish and trip Vitest's "close timed out" at teardown. Calling
- * this (from a Vitest `globalSetup` teardown, which runs before Vite closes its
- * own server) stops them. A no-op if no agent was created, and in playback only
- * stops recorder timers — {@link VcrAgent.close} deliberately does not re-save
- * the cassette there (see its doc).
+ * Flush every cassette. Cassettes are already written when each one is
+ * released, so this is a safety net for a run that ended without releasing —
+ * and a no-op if no recorder was created.
  */
 export declare function closeVcr(): Promise<void>;
 //# sourceMappingURL=vcr.d.ts.map

package/dist/testing/vcr.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"vcr.d.ts","sourceRoot":"","sources":["../../src/testing/vcr.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAiB,KAAK,UAAU,EAAE,MAAM,QAAQ,CAAC;AAmCnE,MAAM,WAAW,qBAAqB;IACpC,kEAAkE;IAClE,YAAY,EAAE,MAAM,CAAC;IACrB;;;;;OAKG;IACH,MAAM,EAAE,OAAO,CAAC;IAChB,uFAAuF;IACvF,gBAAgB,EAAE,MAAM,EAAE,CAAC;IAC3B,6EAA6E;IAC7E,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,gFAAgF;IAChF,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;CAC1B;AAID;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,qBAAa,QAAS,SAAQ,SAAS;;gBAWzB,OAAO,EAAE,qBAAqB;IA6E1C,QAAQ,CACN,IAAI,EAAE,UAAU,CAAC,eAAe,EAChC,OAAO,EAAE,UAAU,CAAC,eAAe,GAClC,OAAO;IAWV;;;;;;;;;;;;;OAaG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAW7B;AAED,wBAAgB,cAAc,CAAC,OAAO,EAAE,qBAAqB,GAAG,QAAQ,CAIvE;AAOD;;;;;;;;;GASG;AACH,wBAAsB,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC,CAM9C"}
+{"version":3,"file":"vcr.d.ts","sourceRoot":"","sources":["../../src/testing/vcr.ts"],"names":[],"mappings":"AAeA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AAEH,0EAA0E;AAC1E,MAAM,WAAW,iBAAiB;IAChC,OAAO,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,IAAI,GAAG,IAAI,CAAC;IAC/D,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;CAClC;AAED,0EAA0E;AAC1E,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,iBAAiB,CAAC;IACpC,WAAW,IAAI,OAAO,CAAC,WAAW,CAAC,CAAC;CACrC;AAED;;;GAGG;AACH,MAAM,MAAM,kBAAkB,GAAG,CAAC,OAAO,EAAE,UAAU,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;AAE5E,MAAM,WAAW,UAAU;IACzB,gDAAgD;IAChD,YAAY,EAAE,MAAM,CAAC;IACrB;;;;;OAKG;IACH,MAAM,EAAE,OAAO,CAAC;IAChB,4EAA4E;IAC5E,QAAQ,CAAC,EAAE,MAAM,CACf,MAAM,EACN,CAAC,OAAO,EAAE,UAAU,KAAK,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,CACtD,CAAC;IACF,iEAAiE;IACjE,iBAAiB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC7B,mFAAmF;IACnF,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;CAC3B;AAED,MAAM,WAAW,GAAG;IAClB,yEAAyE;IACzE,QAAQ,CAAC,eAAe,EAAE,kBAAkB,CAAC;IAC7C,yDAAyD;IACzD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAgPD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,UAAU,GAAG,GAAG,CAQlD;AAED;;;;;;;;;GASG;AACH,wBAAgB,aAAa,IAAI,OAAO,CAEvC;AAOD;;;;GAIG;AACH,wBAAsB,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC,CAM9C"}