@specific.dev/spectest 0.9.0 → 0.11.0

package/src/recorder.ts

@@ -19,6 +19,8 @@ export type TestEvent =
   | KubeEvent
   | BrowserEvent
   | DbEvent
+  | RedisEvent
+  | S3Event
   | TerminalEvent
   | TerminalStepEvent
   | WaitEvent
@@ -124,6 +126,67 @@ export interface DbEvent extends BaseEvent {
   error?: string;
 }
 
+/**
+ * One Redis/Valkey command issued through the instrumented {@link
+ * "../redis".RedisClient} (a drop-in for `Bun.RedisClient` / `Bun.redis`).
+ *
+ * The return value is `wrap()`ped against this event's seq, so a later
+ * `expect(...)` that drills into it nests under this step in the timeline
+ * (same mechanism as http/db).
+ */
+export interface RedisEvent extends BaseEvent {
+  kind: "redis";
+  /** Label for the connection — the URL host (often the service name). */
+  service: string;
+  /** Command name, upper-cased (`GET`, `SET`, `HGETALL`, `PUBLISH`, …). */
+  command: string;
+  /** First argument — almost always the key the command targets. Surfaced
+   *  separately so the UI can read `GET session:42` at a glance. */
+  key?: string;
+  /** Remaining arguments (best-effort JSON-safe; large/binary stringified).
+   *  Omitted when there are none. */
+  args?: unknown[];
+  /** Reply, best-effort JSON-safe and capped. Omitted when the command threw
+   *  or returned `null`/`undefined`. */
+  result?: unknown;
+  resultTruncated?: boolean;
+  durationMs: number;
+  /** Set if the command threw. */
+  error?: string;
+}
+
+/**
+ * One object-storage operation through the instrumented {@link
+ * "../s3".S3Client} (a drop-in for `Bun.S3Client` / `Bun.s3`), covering both
+ * client-level calls (`write`/`delete`/`exists`/`list`/`presign`/`stat`) and
+ * the `S3File` handle `.file(path)` returns (`text`/`json`/`write`/…).
+ *
+ * The return value is `wrap()`ped against this event's seq, so `expect(...)`
+ * drilling into it nests under this step (same mechanism as http/db).
+ */
+export interface S3Event extends BaseEvent {
+  kind: "s3";
+  /** Operation: `write` | `read` | `delete` | `exists` | `list` |
+   *  `presign` | `stat`. */
+  op: string;
+  /** Bucket, when the client/handle knows it. */
+  bucket?: string;
+  /** Object key (path) the op targeted. Omitted for bucket-wide `list`. */
+  key?: string;
+  /** Bytes written or read, when known. */
+  size?: number;
+  /** Content type, when known (read/write/stat). */
+  contentType?: string;
+  /** Small text preview of the body (read/write of text), capped. */
+  preview?: string;
+  previewTruncated?: boolean;
+  /** For `list`: number of keys returned. */
+  count?: number;
+  durationMs: number;
+  /** Set if the op threw. */
+  error?: string;
+}
+
 export interface HttpEvent extends BaseEvent {
   kind: "http";
   method: string;
@@ -556,6 +619,20 @@ export function recordDb(
   return active() ? current!.push({ kind: "db", ...ev }, reservation) : undefined;
 }
 
+export function recordRedis(
+  ev: Omit<RedisEvent, "seq" | "tOffsetMs" | "kind">,
+  reservation?: EventReservation,
+): number | undefined {
+  return active() ? current!.push({ kind: "redis", ...ev }, reservation) : undefined;
+}
+
+export function recordS3(
+  ev: Omit<S3Event, "seq" | "tOffsetMs" | "kind">,
+  reservation?: EventReservation,
+): number | undefined {
+  return active() ? current!.push({ kind: "s3", ...ev }, reservation) : undefined;
+}
+
 export function recordTerminal(
   ev: Omit<TerminalEvent, "seq" | "tOffsetMs" | "kind">,
   reservation?: EventReservation,

package/src/redis.ts

@@ -0,0 +1,202 @@
+// `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";
+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 BunGlobal {
+  RedisClient: new (url?: string, options?: unknown) => RawRedisClient;
+}
+
+interface RedisConstructor {
+  new (url?: string, opts?: RedisOptions): RedisClientLike;
+  (url?: string, opts?: RedisOptions): RedisClientLike;
+}
+
+// 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?: string,
+  opts?: RedisOptions,
+): RedisClientLike {
+  const bun = (globalThis as unknown as { Bun?: BunGlobal }).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));
+} as unknown as RedisConstructor;
+
+function hostLabel(url?: string): string {
+  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: RawRedisClient, label: string): RedisClientLike {
+  const run = (
+    command: string,
+    key: string | undefined,
+    extra: unknown[],
+    invoke: () => unknown,
+  ): Promise<unknown> => {
+    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 as Error;
+        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: ProxyHandler<RawRedisClient> = {
+    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 as (...a: unknown[]) => unknown;
+      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: string, args: string[] = []) =>
+          run(String(command).toUpperCase(), args[0], args.slice(1), () =>
+            fn.call(target, command, args),
+          );
+      }
+      return (...args: unknown[]) =>
+        run(
+          prop.toUpperCase(),
+          typeof args[0] === "string" ? args[0] : undefined,
+          args.slice(1),
+          () => fn.apply(target, args),
+        );
+    },
+  };
+  return new Proxy(raw, handler) as unknown as RedisClientLike;
+}
+
+/** Best-effort JSON-safe preview of a reply, capped at {@link MAX_RESULT_BYTES}. */
+function capValue(value: unknown): { preview?: unknown; truncated?: boolean } {
+  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/src/s3.ts

@@ -0,0 +1,333 @@
+// `S3Client` — a drop-in for `Bun.S3Client` (`Bun.s3`) that records every
+// object-storage operation on the test event log and returns its result
+// inspect-wrapped, so `expect(await client.file("k").json())` links the
+// assertion back to the read in the timeline (same provenance mechanism as the
+// wrapped `fetch` / `SQL` / `RedisClient`). Swap `new Bun.S3Client(opts)` →
+// `new S3Client(opts)` and nothing else changes at the call site.
+//
+// Instrumentation covers both the client-level ops (`write`/`delete`/`exists`/
+// `list`/`presign`/`stat`/`size`) and the lazy `S3File` handle that
+// `.file(path)` returns (`text`/`json`/`arrayBuffer`/`bytes`/`write`/…). Reach
+// for it whenever you stand up S3-compatible storage (MinIO, real S3, R2) in a
+// service `helpers` factory or a test.
+
+import { recordS3, reserveEvent } from "./recorder.js";
+import { wrap } from "./inspect.js";
+import type { Wrapped } from "./inspect.js";
+
+/** Structural types for the parts of `Bun.S3Client` we use, declared locally so
+ *  user projects don't need `@types/bun`. The real implementation comes from
+ *  Bun at runtime via `globalThis.Bun.S3Client`. */
+interface RawS3File {
+  name?: string;
+  bucket?: string;
+  size?: number;
+  type?: string;
+  text(): Promise<string>;
+  json<T = unknown>(): Promise<T>;
+  arrayBuffer(): Promise<ArrayBuffer>;
+  bytes(): Promise<Uint8Array>;
+  write(data: unknown, options?: unknown): Promise<number>;
+  exists(): Promise<boolean>;
+  delete(): Promise<void>;
+  unlink?(): Promise<void>;
+  stat(): Promise<unknown>;
+  presign(options?: unknown): string;
+  [m: string]: unknown;
+}
+
+interface RawS3Client {
+  file(path: string, options?: unknown): RawS3File;
+  write(path: string, data: unknown, options?: unknown): Promise<number>;
+  delete(path: string, options?: unknown): Promise<void>;
+  unlink?(path: string, options?: unknown): Promise<void>;
+  exists(path: string, options?: unknown): Promise<boolean>;
+  size?(path: string, options?: unknown): Promise<number>;
+  stat(path: string, options?: unknown): Promise<unknown>;
+  presign(path: string, options?: unknown): string;
+  list(input?: unknown, options?: unknown): Promise<unknown>;
+  [m: string]: unknown;
+}
+
+/** A lazy S3 object handle (Bun's `S3File`), wrapped so each read/write records
+ *  an `s3` event and returns a {@link Wrapped} result. */
+export interface S3File {
+  readonly name?: string;
+  readonly bucket?: string;
+  readonly size?: number;
+  text(): Promise<Wrapped<string>>;
+  json<T = unknown>(): Promise<Wrapped<T>>;
+  arrayBuffer(): Promise<Wrapped<ArrayBuffer>>;
+  bytes(): Promise<Wrapped<Uint8Array>>;
+  write(data: unknown, options?: unknown): Promise<Wrapped<number>>;
+  exists(): Promise<Wrapped<boolean>>;
+  delete(): Promise<Wrapped<void>>;
+  stat(): Promise<Wrapped<unknown>>;
+  presign(options?: unknown): string;
+}
+
+/** The instrumented S3 surface — same shape as `Bun.S3Client`, but every op
+ *  records an `s3` event and resolves to a {@link Wrapped} result. */
+export interface S3ClientLike {
+  file(path: string, options?: unknown): S3File;
+  write(path: string, data: unknown, options?: unknown): Promise<Wrapped<number>>;
+  delete(path: string, options?: unknown): Promise<Wrapped<void>>;
+  exists(path: string, options?: unknown): Promise<Wrapped<boolean>>;
+  stat(path: string, options?: unknown): Promise<Wrapped<unknown>>;
+  list(input?: unknown, options?: unknown): Promise<Wrapped<unknown>>;
+  presign(path: string, options?: unknown): string;
+  [m: string]: (...args: any[]) => any;
+}
+
+/** Options accepted by the {@link S3Client} constructor — Bun's own plus a
+ *  recording `label`. Passed through to `Bun.S3Client` verbatim. */
+export interface S3Options {
+  accessKeyId?: string;
+  secretAccessKey?: string;
+  sessionToken?: string;
+  bucket?: string;
+  region?: string;
+  endpoint?: string;
+  [opt: string]: unknown;
+}
+
+interface BunGlobal {
+  S3Client: new (options?: S3Options) => RawS3Client;
+}
+
+interface S3Constructor {
+  new (options?: S3Options): S3ClientLike;
+  (options?: S3Options): S3ClientLike;
+}
+
+const MAX_PREVIEW = 512;
+
+/**
+ * Open an instrumented S3 client. Usable with or without `new`. Requires the
+ * Bun runtime — it runs inside the spectest daemon.
+ */
+export const S3Client = function S3Client(options?: S3Options): S3ClientLike {
+  const bun = (globalThis as unknown as { Bun?: BunGlobal }).Bun;
+  if (!bun?.S3Client) {
+    throw new Error(
+      "S3Client requires the Bun runtime (Bun >= 1.1) — it runs inside the spectest daemon.",
+    );
+  }
+  return instrumentS3(new bun.S3Client(options), options?.bucket);
+} as unknown as S3Constructor;
+
+/** Record an awaitable S3 op, wrapping its settled result for provenance. */
+function runS3<T>(
+  base: { op: string; bucket?: string; key?: string },
+  invoke: () => PromiseLike<T>,
+  describe?: (value: T) => Partial<{
+    size: number;
+    contentType: string;
+    preview: string;
+    previewTruncated: boolean;
+    count: number;
+  }>,
+): Promise<T> {
+  const started = Date.now();
+  const resv = reserveEvent();
+  return Promise.resolve(invoke()).then(
+    (value) => {
+      const seq = recordS3(
+        { ...base, ...(describe?.(value) ?? {}), durationMs: Date.now() - started },
+        resv,
+      );
+      return wrap(value, seq) as T;
+    },
+    (err) => {
+      const e = err as Error;
+      recordS3(
+        { ...base, durationMs: Date.now() - started, error: e?.message ?? String(err) },
+        resv,
+      );
+      throw err;
+    },
+  );
+}
+
+/** Record a synchronous op (`presign`) — no result wrapping (returns a URL). */
+function runS3Sync<T>(base: { op: string; bucket?: string; key?: string }, invoke: () => T): T {
+  const started = Date.now();
+  try {
+    const value = invoke();
+    recordS3({ ...base, durationMs: Date.now() - started }, undefined);
+    return value;
+  } catch (err) {
+    const e = err as Error;
+    recordS3(
+      { ...base, durationMs: Date.now() - started, error: e?.message ?? String(err) },
+      undefined,
+    );
+    throw err;
+  }
+}
+
+/**
+ * Proxy a `Bun.S3Client` so each op records an `s3` event. `file(path)` returns
+ * a wrapped {@link S3File}; unknown methods pass through.
+ *
+ * Exported so a client built another way can opt into the same instrumentation.
+ */
+export function instrumentS3(raw: RawS3Client, bucket?: string): S3ClientLike {
+  const handler: ProxyHandler<RawS3Client> = {
+    get(target, prop, receiver) {
+      if (typeof prop !== "string") return Reflect.get(target, prop, receiver);
+      switch (prop) {
+        case "file":
+          return (path: string, options?: unknown) =>
+            instrumentS3File(target.file(path, options), path, bucket);
+        case "write":
+          return (path: string, data: unknown, options?: unknown) =>
+            runS3({ op: "write", bucket, key: path }, () => target.write(path, data, options), () =>
+              describeData(data),
+            );
+        case "delete":
+        case "unlink":
+          return (path: string, options?: unknown) =>
+            runS3({ op: "delete", bucket, key: path }, () => target.delete(path, options));
+        case "exists":
+          return (path: string, options?: unknown) =>
+            runS3({ op: "exists", bucket, key: path }, () => target.exists(path, options));
+        case "size":
+          return (path: string, options?: unknown) =>
+            runS3({ op: "stat", bucket, key: path }, () => target.size!(path, options), (n) => ({
+              size: typeof n === "number" ? n : undefined,
+            }));
+        case "stat":
+          return (path: string, options?: unknown) =>
+            runS3({ op: "stat", bucket, key: path }, () => target.stat(path, options), describeStat);
+        case "list":
+          return (input?: unknown, options?: unknown) =>
+            runS3({ op: "list", bucket }, () => target.list(input, options), (r) => ({
+              count: listCount(r),
+            }));
+        case "presign":
+          return (path: string, options?: unknown) =>
+            runS3Sync({ op: "presign", bucket, key: path }, () => target.presign(path, options));
+        default: {
+          const v = Reflect.get(target, prop, receiver);
+          return typeof v === "function" ? (v as (...a: unknown[]) => unknown).bind(target) : v;
+        }
+      }
+    },
+  };
+  return new Proxy(raw, handler) as unknown as S3ClientLike;
+}
+
+function instrumentS3File(raw: RawS3File, key: string, bucket?: string): S3File {
+  const b = raw.bucket ?? bucket;
+  const handler: ProxyHandler<RawS3File> = {
+    get(target, prop, receiver) {
+      if (typeof prop !== "string") return Reflect.get(target, prop, receiver);
+      switch (prop) {
+        case "text":
+          return () => runS3({ op: "read", bucket: b, key }, () => target.text(), describeData);
+        case "json":
+          return () => runS3({ op: "read", bucket: b, key }, () => target.json(), describeData);
+        case "arrayBuffer":
+          return () =>
+            runS3({ op: "read", bucket: b, key }, () => target.arrayBuffer(), describeData);
+        case "bytes":
+          return () => runS3({ op: "read", bucket: b, key }, () => target.bytes(), describeData);
+        case "write":
+          return (data: unknown, options?: unknown) =>
+            runS3({ op: "write", bucket: b, key }, () => target.write(data, options), () =>
+              describeData(data),
+            );
+        case "exists":
+          return () => runS3({ op: "exists", bucket: b, key }, () => target.exists());
+        case "delete":
+        case "unlink":
+          return () => runS3({ op: "delete", bucket: b, key }, () => target.delete());
+        case "stat":
+          return () => runS3({ op: "stat", bucket: b, key }, () => target.stat(), describeStat);
+        case "presign":
+          return (options?: unknown) =>
+            runS3Sync({ op: "presign", bucket: b, key }, () => target.presign(options));
+        default: {
+          const v = Reflect.get(target, prop, receiver);
+          return typeof v === "function" ? (v as (...a: unknown[]) => unknown).bind(target) : v;
+        }
+      }
+    },
+  };
+  return new Proxy(raw, handler) as unknown as S3File;
+}
+
+/** Byte size + small text preview of a written/read body. */
+function describeData(value: unknown): Partial<{
+  size: number;
+  contentType: string;
+  preview: string;
+  previewTruncated: boolean;
+}> {
+  if (typeof value === "string") {
+    const truncated = value.length > MAX_PREVIEW;
+    return {
+      size: byteLength(value),
+      preview: truncated ? value.slice(0, MAX_PREVIEW) : value,
+      previewTruncated: truncated || undefined,
+    };
+  }
+  if (value && typeof value === "object" && !isBinary(value)) {
+    // A parsed JSON body (from `.json()`): preview a capped serialization.
+    try {
+      const json = JSON.stringify(value);
+      const truncated = json.length > MAX_PREVIEW;
+      return {
+        contentType: "application/json",
+        preview: truncated ? `${json.slice(0, MAX_PREVIEW)}…` : json,
+        previewTruncated: truncated || undefined,
+      };
+    } catch {
+      /* fall through to size-only */
+    }
+  }
+  const size = byteLength(value);
+  return size !== undefined ? { size } : {};
+}
+
+function describeStat(stat: unknown): Partial<{ size: number; contentType: string }> {
+  if (stat && typeof stat === "object") {
+    const s = stat as { size?: unknown; type?: unknown; contentType?: unknown };
+    return {
+      size: typeof s.size === "number" ? s.size : undefined,
+      contentType:
+        typeof s.type === "string"
+          ? s.type
+          : typeof s.contentType === "string"
+            ? s.contentType
+            : undefined,
+    };
+  }
+  return {};
+}
+
+function listCount(result: unknown): number | undefined {
+  if (result && typeof result === "object") {
+    const r = result as { contents?: unknown[]; keyCount?: unknown };
+    if (Array.isArray(r.contents)) return r.contents.length;
+    if (typeof r.keyCount === "number") return r.keyCount;
+  }
+  return undefined;
+}
+
+function isBinary(value: unknown): boolean {
+  return (
+    value instanceof ArrayBuffer ||
+    ArrayBuffer.isView(value) ||
+    (typeof Blob !== "undefined" && value instanceof Blob)
+  );
+}
+
+function byteLength(value: unknown): number | undefined {
+  if (typeof value === "string") return Buffer.byteLength(value);
+  if (value instanceof ArrayBuffer) return value.byteLength;
+  if (ArrayBuffer.isView(value)) return value.byteLength;
+  if (typeof Blob !== "undefined" && value instanceof Blob) return value.size;
+  return undefined;
+}