@specific.dev/spectest 0.24.0 → 0.27.0

package/dist/recorder.js

@@ -0,0 +1,219 @@
+// Per-test event recorder. The daemon installs a fresh recorder before
+// running a test case and drains it afterwards. While a recorder is
+// active, instrumented sites (the SDK's `expect`, the daemon's wrapped
+// `ctx.exec`, and the test-scoped `fetch` wrapper) push structured
+// events into it.
+//
+// When no test is running (production code paths, eval, etc.) the
+// current recorder is `null` and the `record*` helpers are no-ops, so
+// callers can invoke them unconditionally.
+import { clearPendingNullish } from "./inspect.js";
+const OUTPUT_SNIPPET_BYTES = 256 * 1024;
+class Recorder {
+    events = [];
+    seq = 0;
+    start = Date.now();
+    /** Claim a seq + start offset now; pass the result to `push` at finish. */
+    reserve() {
+        return { seq: this.seq++, tOffsetMs: Date.now() - this.start };
+    }
+    push(ev, reservation) {
+        // A new op invalidates any pending nullish-leaf note: a note must not
+        // survive past the op it belongs to and get adopted by a later, unrelated
+        // `expect`. The assertion event itself is exempt — its `expect()` already
+        // adopted (and consumed) the note before recording.
+        if (ev.kind !== "assertion")
+            clearPendingNullish();
+        const seq = reservation?.seq ?? this.seq++;
+        this.events.push({
+            ...ev,
+            seq,
+            tOffsetMs: reservation?.tOffsetMs ?? Date.now() - this.start,
+        });
+        return seq;
+    }
+    drain() {
+        return this.events;
+    }
+    /** Index of the next event that would be pushed. Use with `truncate`
+     *  to drop everything pushed since this index. The seq counter does
+     *  not roll back — discarded seqs leave gaps. */
+    eventCount() {
+        return this.events.length;
+    }
+    /** Drop events with index >= `toLen`. The seq counter is unaffected
+     *  (so seqs already handed out remain unique even though the events
+     *  they named are gone). */
+    truncate(toLen) {
+        if (toLen < this.events.length) {
+            this.events.length = toLen;
+        }
+    }
+    /** Stamp `parentSeq` onto every event at index >= `startIdx`. Used
+     *  by `ctx.poll` to group the kept iteration's events under the
+     *  resulting wait event. */
+    markChildren(startIdx, parentSeq) {
+        for (let i = startIdx; i < this.events.length; i++) {
+            const ev = this.events[i];
+            if (ev.seq === parentSeq)
+                continue;
+            ev.parentSeq = parentSeq;
+        }
+    }
+    /** Shallow-merge `patch` into the already-recorded event with this
+     *  `seq`. Lets an instrumentation site enrich or reclassify an event
+     *  after the fact — e.g. the k3s component upgrades the generic `http`
+     *  event its API call produced into a Kubernetes-specific `kube` event
+     *  once it has parsed the request. Searches from the end since the
+     *  target is almost always the most recent event. No-op when no event
+     *  carries that seq. */
+    annotate(seq, patch) {
+        for (let i = this.events.length - 1; i >= 0; i--) {
+            const ev = this.events[i];
+            if (ev.seq === seq) {
+                Object.assign(ev, patch);
+                return;
+            }
+        }
+    }
+    /** Drop the single event carrying this `seq`. Used to retract an event
+     *  that an instrumentation site recorded but then decided is noise — e.g.
+     *  the dynamic kube client's internal discovery GET. Caller must ensure
+     *  nothing references the seq (no child events/assertions hang off it).
+     *  The seq counter does not roll back, so the seq stays retired. Searches
+     *  from the end since the target is almost always the most recent event. */
+    remove(seq) {
+        for (let i = this.events.length - 1; i >= 0; i--) {
+            if (this.events[i].seq === seq) {
+                this.events.splice(i, 1);
+                return;
+            }
+        }
+    }
+}
+let current = null;
+// Counter-based pause: `pauseRecording`/`resumeRecording` nest safely
+// (a nested `ctx.poll` inside another `ctx.poll`'s predicate stays
+// suppressed until its own resume balances out). Active record* sites
+// no-op while `paused > 0`, so http/exec/db/etc. inside a paused
+// region produce no events and the returned seq is `undefined` —
+// which means the daemon's fetch wrapper also skips installing the
+// inspector proxy on the Response.
+let paused = 0;
+export function pauseRecording() {
+    paused += 1;
+}
+export function resumeRecording() {
+    paused = Math.max(0, paused - 1);
+}
+function active() {
+    return current !== null && paused === 0;
+}
+export function startRecording() {
+    current = new Recorder();
+    paused = 0;
+}
+export function stopRecording() {
+    if (!current)
+        return [];
+    const evs = current.drain();
+    current = null;
+    paused = 0;
+    return evs;
+}
+export function isRecording() {
+    return current !== null;
+}
+/** Reserve an ordering slot at the start of an op so nested events it triggers
+ *  (which finish — and record — first) still sort after it. Hand the returned
+ *  reservation to the matching `record*` call at op finish. Returns `undefined`
+ *  when nothing is recording, in which case `record*` falls back to allocating
+ *  the seq at record time. */
+export function reserveEvent() {
+    return active() ? current.reserve() : undefined;
+}
+export function recordExec(ev, reservation) {
+    return active() ? current.push({ kind: "exec", ...ev }, reservation) : undefined;
+}
+export function recordAssertion(ev) {
+    return active() ? current.push({ kind: "assertion", ...ev }) : undefined;
+}
+export function recordHttp(ev, reservation) {
+    return active() ? current.push({ kind: "http", ...ev }, reservation) : undefined;
+}
+export function recordBrowser(ev, reservation) {
+    return active() ? current.push({ kind: "browser", ...ev }, reservation) : undefined;
+}
+export function recordDb(ev, reservation) {
+    return active() ? current.push({ kind: "db", ...ev }, reservation) : undefined;
+}
+export function recordRedis(ev, reservation) {
+    return active() ? current.push({ kind: "redis", ...ev }, reservation) : undefined;
+}
+export function recordS3(ev, reservation) {
+    return active() ? current.push({ kind: "s3", ...ev }, reservation) : undefined;
+}
+export function recordTerminal(ev, reservation) {
+    return active() ? current.push({ kind: "terminal", ...ev }, reservation) : undefined;
+}
+export function recordTerminalStep(ev, reservation) {
+    return active() ? current.push({ kind: "terminal-step", ...ev }, reservation) : undefined;
+}
+export function recordFake(ev, reservation) {
+    return active() ? current.push({ kind: "fake", ...ev }, reservation) : undefined;
+}
+export function recordEnv(ev, reservation) {
+    return active() ? current.push({ kind: "env", ...ev }, reservation) : undefined;
+}
+export function recordEmail(ev, reservation) {
+    return active() ? current.push({ kind: "email", ...ev }, reservation) : undefined;
+}
+export function recordWait(ev, reservation) {
+    // Use `current` directly (not `active()`) so a `recordWait` at the
+    // end of a `ctx.poll` block lands even though the surrounding code
+    // just resumed from `paused`. Pushing this event is the whole point
+    // of the poll primitive.
+    return current?.push({ kind: "wait", ...ev }, reservation);
+}
+/** Number of events the active recorder has accumulated. Returns 0
+ *  when no recorder is active. */
+export function recorderEventCount() {
+    return current?.eventCount() ?? 0;
+}
+/** Drop events with index >= `toLen` from the active recorder. */
+export function recorderTruncate(toLen) {
+    current?.truncate(toLen);
+}
+/** Stamp `parentSeq` onto every event from `startIdx` onward, so the
+ *  UI groups them under the parent in the timeline. */
+export function recorderMarkChildren(startIdx, parentSeq) {
+    current?.markChildren(startIdx, parentSeq);
+}
+/** Shallow-merge `patch` into the active recorder's event with this
+ *  `seq` (enrich/reclassify after the fact). No-op when nothing is
+ *  recording or no event carries that seq. */
+export function recorderAnnotate(seq, patch) {
+    current?.annotate(seq, patch);
+}
+/** Retract the active recorder's event with this `seq` (an instrumentation
+ *  site recorded it, then decided it's noise). No-op when nothing is
+ *  recording or no event carries that seq. */
+export function recorderRemove(seq) {
+    current?.remove(seq);
+}
+/** Best-effort JSON-safe deep clone; falls back to `String(v)`. */
+export function safeSerialize(v) {
+    if (v === undefined)
+        return undefined;
+    try {
+        return JSON.parse(JSON.stringify(v));
+    }
+    catch {
+        return String(v);
+    }
+}
+export function truncateUtf8(s) {
+    if (s.length <= OUTPUT_SNIPPET_BYTES)
+        return { value: s, truncated: false };
+    return { value: s.slice(0, OUTPUT_SNIPPET_BYTES), truncated: true };
+}

package/dist/redis.d.ts

@@ -0,0 +1,54 @@
+import type { Wrapped } from "./inspect.js";
+/**
+ * Structural type for the parts of `Bun.RedisClient` we use, declared locally
+ * so user projects don't need `@types/bun`. The real implementation comes from
+ * Bun at runtime via `globalThis.Bun.RedisClient`. Commands resolve to their
+ * reply; lifecycle methods (`connect`/`close`/`subscribe`/…) are passed through
+ * un-instrumented.
+ */
+interface RawRedisClient {
+    send(command: string, args: string[]): Promise<unknown>;
+    close?(): void;
+    [method: string]: unknown;
+}
+/** The instrumented Redis surface — same shape as `Bun.RedisClient`, but every
+ *  command resolves to a {@link Wrapped} reply recorded as a `redis` event.
+ *  Indexable so every Bun command method is reachable without re-declaring the
+ *  whole (large) surface; the common ones are typed for ergonomics. */
+export interface RedisClientLike {
+    get(key: string): Promise<Wrapped<string | null>>;
+    set(key: string, value: string): Promise<Wrapped<string>>;
+    del(...keys: string[]): Promise<Wrapped<number>>;
+    exists(...keys: string[]): Promise<Wrapped<number>>;
+    incr(key: string): Promise<Wrapped<number>>;
+    hgetall(key: string): Promise<Wrapped<Record<string, string>>>;
+    /** Run an arbitrary command — `client.send("SET", ["k", "v"])`. */
+    send(command: string, args: string[]): Promise<Wrapped<unknown>>;
+    close(): void;
+    [method: string]: (...args: any[]) => any;
+}
+/** Options accepted by the {@link RedisClient} constructor beyond Bun's own. */
+export interface RedisOptions {
+    /** Label shown on each recorded `redis` event (the timeline step's tag).
+     *  Defaults to the connection URL's host (usually the service name). */
+    label?: string;
+}
+interface RedisConstructor {
+    new (url?: string, opts?: RedisOptions): RedisClientLike;
+    (url?: string, opts?: RedisOptions): RedisClientLike;
+}
+/**
+ * Open an instrumented Redis client against `url` (default: Bun's own
+ * `REDIS_URL`/`VALKEY_URL`). Usable with or without `new`. Requires the Bun
+ * runtime — it runs inside the spectest daemon.
+ */
+export declare const RedisClient: RedisConstructor;
+/**
+ * Proxy a `Bun.RedisClient` so each command method (and `send(...)`) emits a
+ * `redis` event when its promise settles and resolves to a {@link Wrapped}
+ * reply. Lifecycle methods and non-function properties pass through.
+ *
+ * Exported so a client built another way can opt into the same instrumentation.
+ */
+export declare function instrumentRedis(raw: RawRedisClient, label: string): RedisClientLike;
+export {};

package/dist/redis.js

@@ -0,0 +1,126 @@
+// `RedisClient` — a drop-in for `Bun.RedisClient` (`Bun.redis`) that records
+// every command on the test event log and returns its reply inspect-wrapped,
+// so `expect(await client.get("k"))` links the assertion back to the command in
+// the timeline (same provenance mechanism as the wrapped `fetch` / `SQL`). Swap
+// `new Bun.RedisClient(url)` → `new RedisClient(url)` and nothing else changes
+// at the call site; replies come back `Wrapped<T>` (that wrapper is what carries
+// provenance), so `.unwrap()` before a `===` or before feeding a value onward.
+//
+// Reach for it in service `helpers` when you stand up a redis/valkey yourself,
+// or directly in a test against a connection string a fake handed back.
+import { recordRedis, reserveEvent, safeSerialize } from "./recorder.js";
+import { wrap } from "./inspect.js";
+// Long-lived / connection-management methods that don't map to a single
+// request→reply step — passed straight through, never recorded.
+const REDIS_PASSTHROUGH = new Set([
+    "connect",
+    "close",
+    "disconnect",
+    "duplicate",
+    "subscribe",
+    "unsubscribe",
+    "psubscribe",
+    "punsubscribe",
+    "ssubscribe",
+    "sunsubscribe",
+    "onclose",
+    "ref",
+    "unref",
+]);
+const MAX_RESULT_BYTES = 2048;
+/**
+ * Open an instrumented Redis client against `url` (default: Bun's own
+ * `REDIS_URL`/`VALKEY_URL`). Usable with or without `new`. Requires the Bun
+ * runtime — it runs inside the spectest daemon.
+ */
+export const RedisClient = function RedisClient(url, opts) {
+    const bun = globalThis.Bun;
+    if (!bun?.RedisClient) {
+        throw new Error("RedisClient requires the Bun runtime (Bun >= 1.2.9) — it runs inside the spectest daemon.");
+    }
+    const raw = url !== undefined ? new bun.RedisClient(url, opts) : new bun.RedisClient();
+    return instrumentRedis(raw, opts?.label ?? hostLabel(url));
+};
+function hostLabel(url) {
+    if (!url)
+        return "redis";
+    try {
+        return new URL(url).hostname || "redis";
+    }
+    catch {
+        return "redis";
+    }
+}
+/**
+ * Proxy a `Bun.RedisClient` so each command method (and `send(...)`) emits a
+ * `redis` event when its promise settles and resolves to a {@link Wrapped}
+ * reply. Lifecycle methods and non-function properties pass through.
+ *
+ * Exported so a client built another way can opt into the same instrumentation.
+ */
+export function instrumentRedis(raw, label) {
+    const run = (command, key, extra, invoke) => {
+        const started = Date.now();
+        const resv = reserveEvent();
+        return Promise.resolve(invoke()).then((value) => {
+            const { preview, truncated } = capValue(value);
+            const seq = recordRedis({
+                service: label,
+                command,
+                key,
+                args: extra.length > 0 ? extra.map(safeSerialize) : undefined,
+                result: preview,
+                resultTruncated: truncated,
+                durationMs: Date.now() - started,
+            }, resv);
+            return wrap(value, seq);
+        }, (err) => {
+            const e = err;
+            recordRedis({
+                service: label,
+                command,
+                key,
+                args: extra.length > 0 ? extra.map(safeSerialize) : undefined,
+                durationMs: Date.now() - started,
+                error: e?.message ?? String(err),
+            }, resv);
+            throw err;
+        });
+    };
+    const handler = {
+        get(target, prop, receiver) {
+            if (typeof prop !== "string")
+                return Reflect.get(target, prop, receiver);
+            const v = Reflect.get(target, prop, receiver);
+            if (typeof v !== "function")
+                return v;
+            const fn = v;
+            if (REDIS_PASSTHROUGH.has(prop))
+                return fn.bind(target);
+            // `send(command, args)` carries the real command in its first arg.
+            if (prop === "send") {
+                return (command, args = []) => run(String(command).toUpperCase(), args[0], args.slice(1), () => fn.call(target, command, args));
+            }
+            return (...args) => run(prop.toUpperCase(), typeof args[0] === "string" ? args[0] : undefined, args.slice(1), () => fn.apply(target, args));
+        },
+    };
+    return new Proxy(raw, handler);
+}
+/** Best-effort JSON-safe preview of a reply, capped at {@link MAX_RESULT_BYTES}. */
+function capValue(value) {
+    if (value === null || value === undefined)
+        return {};
+    const safe = safeSerialize(value);
+    const json = (() => {
+        try {
+            return JSON.stringify(safe);
+        }
+        catch {
+            return undefined;
+        }
+    })();
+    if (json !== undefined && json.length > MAX_RESULT_BYTES) {
+        return { preview: `${json.slice(0, MAX_RESULT_BYTES)}…`, truncated: true };
+    }
+    return { preview: safe };
+}

package/dist/replay-bundle.d.ts

@@ -0,0 +1,38 @@
+/** Token an extracted asset is replaced with. Still a syntactically valid
+ * data: URI so anything that merely carries it along stays well-formed;
+ * it never renders (the viewer rehydrates before the events reach rrweb). */
+export declare function assetToken(hash: string): string;
+/**
+ * Serialize `sessions` and pull every large base64 data: URI out into a
+ * content-addressed asset table. Returns the deduplicated sessions as a
+ * JSON *string* (already serialized — splice it into the bundle document
+ * verbatim) plus the asset table.
+ */
+export declare function extractReplayAssets(sessions: unknown): {
+    sessionsJson: string;
+    assets: Record<string, string>;
+};
+/**
+ * Encode a case's sessions as the gzipped replay-bundle document the
+ * control plane archives to S3 verbatim:
+ * `{ caseId, sessions: [...], assets: { <hash>: <dataUri> } }` — the
+ * shape of `storage.rs::CaseReplayBundle`.
+ */
+export declare function encodeReplayBundle(caseId: string, sessions: unknown): Buffer;
+/** Per-chunk raw-byte ceiling for `/replay-chunk` replies. Base64 inflates
+ * 4/3× and the JSON reply must clear the vm-agent's 16 MB response cap
+ * with headroom. The control plane's `fetch_replay_bundle` requests
+ * exactly this much per round trip. */
+export declare const REPLAY_CHUNK_MAX_BYTES: number;
+/**
+ * One `/replay-chunk` reply: base64 of `gz[offset, offset+limit)`, with
+ * offset/limit clamped to sane values (never more than
+ * `REPLAY_CHUNK_MAX_BYTES` raw bytes). An out-of-range offset yields an
+ * empty `b64`, which the control plane treats as an error — it only ever
+ * asks for offsets below the advertised total.
+ */
+export declare function replayChunk(gz: Buffer, offsetIn: unknown, limitIn: unknown): {
+    total: number;
+    offset: number;
+    b64: string;
+};

package/{src/replay-bundle.ts → dist/replay-bundle.js}

@@ -19,72 +19,58 @@
 // `web/case_viewer.rs::rehydrateAssets`). Only base64 URIs are extracted:
 // their charset needs no JSON escaping, so plain text substitution in
 // either direction cannot corrupt the surrounding JSON document.
-
 import { createHash } from "node:crypto";
 import { gzipSync } from "node:zlib";
-
 /** Minimum data: URI payload length (chars) worth extracting. Below this
  * the token + asset-table overhead rivals the URI itself. */
 const ASSET_MIN_BASE64_CHARS = 1024;
-
 /** Base64 `data:` URIs, ≥1 KiB of payload. Mediatype + parameters are
  * restricted to charsets that never need JSON escaping — a match taken
  * from serialized JSON text is therefore byte-identical to the logical
  * string value it sits inside. */
-const ASSET_RX = new RegExp(
-  "data:[A-Za-z0-9.+-]+/[A-Za-z0-9.+-]+(?:;[A-Za-z0-9.=+-]+)*;base64," +
-    `[A-Za-z0-9+/=]{${ASSET_MIN_BASE64_CHARS},}`,
-  "g",
-);
-
+const ASSET_RX = new RegExp("data:[A-Za-z0-9.+-]+/[A-Za-z0-9.+-]+(?:;[A-Za-z0-9.=+-]+)*;base64," +
+    `[A-Za-z0-9+/=]{${ASSET_MIN_BASE64_CHARS},}`, "g");
 /** Token an extracted asset is replaced with. Still a syntactically valid
  * data: URI so anything that merely carries it along stays well-formed;
  * it never renders (the viewer rehydrates before the events reach rrweb). */
-export function assetToken(hash: string): string {
-  return `data:x-spectest-asset/${hash}`;
+export function assetToken(hash) {
+    return `data:x-spectest-asset/${hash}`;
 }
-
 /**
  * Serialize `sessions` and pull every large base64 data: URI out into a
  * content-addressed asset table. Returns the deduplicated sessions as a
  * JSON *string* (already serialized — splice it into the bundle document
  * verbatim) plus the asset table.
  */
-export function extractReplayAssets(sessions: unknown): {
-  sessionsJson: string;
-  assets: Record<string, string>;
-} {
-  const assets: Record<string, string> = {};
-  const raw = JSON.stringify(sessions);
-  const sessionsJson = raw.replace(ASSET_RX, (uri) => {
-    // 16 hex chars (64 bits) of SHA-256: collision-safe at replay-asset
-    // scale (dozens of assets per case), and short enough that a token is
-    // negligible next to the URI it replaces.
-    const hash = createHash("sha256").update(uri).digest("hex").slice(0, 16);
-    assets[hash] = uri;
-    return assetToken(hash);
-  });
-  return { sessionsJson, assets };
+export function extractReplayAssets(sessions) {
+    const assets = {};
+    const raw = JSON.stringify(sessions);
+    const sessionsJson = raw.replace(ASSET_RX, (uri) => {
+        // 16 hex chars (64 bits) of SHA-256: collision-safe at replay-asset
+        // scale (dozens of assets per case), and short enough that a token is
+        // negligible next to the URI it replaces.
+        const hash = createHash("sha256").update(uri).digest("hex").slice(0, 16);
+        assets[hash] = uri;
+        return assetToken(hash);
+    });
+    return { sessionsJson, assets };
 }
-
 /**
  * Encode a case's sessions as the gzipped replay-bundle document the
  * control plane archives to S3 verbatim:
  * `{ caseId, sessions: [...], assets: { <hash>: <dataUri> } }` — the
  * shape of `storage.rs::CaseReplayBundle`.
  */
-export function encodeReplayBundle(caseId: string, sessions: unknown): Buffer {
-  const { sessionsJson, assets } = extractReplayAssets(sessions);
-  const doc = `{"caseId":${JSON.stringify(caseId)},"sessions":${sessionsJson},"assets":${JSON.stringify(assets)}}`;
-  return gzipSync(Buffer.from(doc));
+export function encodeReplayBundle(caseId, sessions) {
+    const { sessionsJson, assets } = extractReplayAssets(sessions);
+    const doc = `{"caseId":${JSON.stringify(caseId)},"sessions":${sessionsJson},"assets":${JSON.stringify(assets)}}`;
+    return gzipSync(Buffer.from(doc));
 }
-
 /** Per-chunk raw-byte ceiling for `/replay-chunk` replies. Base64 inflates
  * 4/3× and the JSON reply must clear the vm-agent's 16 MB response cap
  * with headroom. The control plane's `fetch_replay_bundle` requests
  * exactly this much per round trip. */
 export const REPLAY_CHUNK_MAX_BYTES = 6 * 1024 * 1024;
-
 /**
  * One `/replay-chunk` reply: base64 of `gz[offset, offset+limit)`, with
  * offset/limit clamped to sane values (never more than
@@ -92,17 +78,13 @@ export const REPLAY_CHUNK_MAX_BYTES = 6 * 1024 * 1024;
  * empty `b64`, which the control plane treats as an error — it only ever
  * asks for offsets below the advertised total.
  */
-export function replayChunk(
-  gz: Buffer,
-  offsetIn: unknown,
-  limitIn: unknown,
-): { total: number; offset: number; b64: string } {
-  const offset = Math.max(0, Math.floor(Number(offsetIn) || 0));
-  const wanted = Math.floor(Number(limitIn) || REPLAY_CHUNK_MAX_BYTES);
-  const limit = Math.min(Math.max(1, wanted), REPLAY_CHUNK_MAX_BYTES);
-  return {
-    total: gz.length,
-    offset,
-    b64: gz.subarray(offset, offset + limit).toString("base64"),
-  };
+export function replayChunk(gz, offsetIn, limitIn) {
+    const offset = Math.max(0, Math.floor(Number(offsetIn) || 0));
+    const wanted = Math.floor(Number(limitIn) || REPLAY_CHUNK_MAX_BYTES);
+    const limit = Math.min(Math.max(1, wanted), REPLAY_CHUNK_MAX_BYTES);
+    return {
+        total: gz.length,
+        offset,
+        b64: gz.subarray(offset, offset + limit).toString("base64"),
+    };
 }

package/dist/resolver.d.ts

@@ -0,0 +1 @@
+export {};