@specific.dev/spectest 0.38.0 → 0.41.0

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 `S3Options`,
+ *  passed through to `Bun.S3Client` verbatim. */
+export interface S3ClientOptions {
+  accessKeyId?: string;
+  secretAccessKey?: string;
+  sessionToken?: string;
+  bucket?: string;
+  region?: string;
+  endpoint?: string;
+  [opt: string]: unknown;
+}
+
+interface BunGlobal {
+  S3Client: new (options?: S3ClientOptions) => RawS3Client;
+}
+
+interface S3Constructor {
+  new (options?: S3ClientOptions): S3ClientLike;
+  (options?: S3ClientOptions): 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?: S3ClientOptions): 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;
+}

package/src/sql.ts

@@ -0,0 +1,243 @@
+// `SQL` — a drop-in for `Bun.SQL` that records every query on the test event
+// log and returns its rows inspect-wrapped, so `expect(rows[0]!.id)` links the
+// assertion back to the query in the timeline (same provenance mechanism as
+// `fetch`). Swap `new Bun.SQL(url)` → `new SQL(url)` and nothing else changes
+// at the call site; query *results* come back `Wrapped<T[]>` instead of raw
+// `T[]` (that wrapper is what carries provenance), so `.unwrap()` before feeding
+// a row value to another real client or a `===` — exactly the rule that already
+// holds for `ctx.svc.<postgres>.client`.
+//
+// This is the core primitive; the `postgres(...)` component is a thin user of
+// it (its `helpers.client` is `new SQL(url, { label })`). Open one yourself
+// whenever you stand up a database without the component — a Bun-native image
+// like timescaledb/postgis, or a connection string a fake handed back after
+// provisioning a DB at runtime.
+
+import { recordDb, reserveEvent, safeSerialize } from "./recorder.js";
+import { wrap } from "./inspect.js";
+import type { Wrapped } from "./inspect.js";
+
+/**
+ * Minimal structural type for the parts of `Bun.SQL` we use. Declared locally
+ * so user projects don't need `@types/bun` for type-checking to follow the SDK
+ * through to the daemon. The real type comes from Bun at runtime via
+ * `globalThis.Bun.SQL`.
+ */
+interface RawSqlClient {
+  <T = unknown>(strings: TemplateStringsArray, ...values: unknown[]): Promise<T[]>;
+  unsafe<T = unknown>(text: string, params?: unknown[]): Promise<T[]>;
+  close?(opts?: { timeout?: number }): Promise<void>;
+  end(opts?: { timeout?: number }): Promise<void>;
+}
+
+interface SqlClientBase {
+  close?(opts?: { timeout?: number }): Promise<void>;
+  /** Close the connection / drain the pool (Bun's `SQL.end`). */
+  end(opts?: { timeout?: number }): Promise<void>;
+}
+
+/**
+ * The instrumented SQL surface. Same shape as `Bun.SQL` — callable as a tagged
+ * template (`` sql`SELECT 1` ``) with an `unsafe(text, params?)` escape hatch —
+ * but each query resolves to a **wrapped** row array ({@link Wrapped}): every
+ * settle is recorded as a `db` event and the wrapper carries provenance back to
+ * it. That's why `expect(rows)` / `expect(rows[0]!.id)` link under the query in
+ * the timeline with no cast — and why you `.unwrap()` before feeding a row value
+ * to a real client or a `===`.
+ *
+ * Generic in the row type, so callers name the shape once at the call site
+ * instead of casting: `` await client<TodoRow>`SELECT * FROM todos` `` is
+ * `Promise<Wrapped<TodoRow[]>>`.
+ */
+export interface SqlClient extends SqlClientBase {
+  <T = unknown>(strings: TemplateStringsArray, ...values: unknown[]): Promise<Wrapped<T[]>>;
+  unsafe<T = unknown>(text: string, params?: unknown[]): Promise<Wrapped<T[]>>;
+}
+
+/** Options accepted by the {@link SQL} constructor beyond Bun's own. */
+export interface SqlOptions {
+  /**
+   * Label shown on each recorded `db` event (the timeline step's service tag).
+   * Defaults to the connection URL's host — e.g. `db` for
+   * `postgres://…@db:5432/app` — which is usually the service name.
+   */
+  label?: string;
+}
+
+interface BunGlobal {
+  SQL: new (url: string) => RawSqlClient;
+}
+
+interface SqlConstructor {
+  new (url: string, opts?: SqlOptions): SqlClient;
+  (url: string, opts?: SqlOptions): SqlClient;
+}
+
+/**
+ * Open an instrumented SQL client against `url`. Usable with or without `new`
+ * (`new SQL(url)` mirrors `new Bun.SQL(url)`; a constructor that returns an
+ * object yields that object). Requires the Bun runtime — it runs inside the
+ * spectest daemon.
+ */
+export const SQL = function SQL(url: string, opts?: SqlOptions): SqlClient {
+  const bun = (globalThis as { Bun?: BunGlobal }).Bun;
+  if (!bun?.SQL) {
+    throw new Error(
+      "SQL(url) requires the Bun runtime (Bun >= 1.2) — it runs inside the spectest daemon.",
+    );
+  }
+  return instrumentSql(new bun.SQL(url), opts?.label ?? hostLabel(url));
+} as unknown as SqlConstructor;
+
+/** Derive a default event label from a connection URL's host. */
+function hostLabel(url: string): string {
+  try {
+    return new URL(url).hostname || "db";
+  } catch {
+    return "db";
+  }
+}
+
+/**
+ * Proxy a `Bun.SQL` instance so each tagged-template call and each
+ * `unsafe(...)` call emits a `db` event into the active recorder when its
+ * promise settles, and resolves to a {@link Wrapped} result. Other `Bun.SQL`
+ * methods (`.transaction`, `.array`, `.file`, …) pass through unwrapped.
+ *
+ * Exported so a client built some other way (e.g. a pool you already hold) can
+ * opt into the same instrumentation without going through {@link SQL}.
+ */
+export function instrumentSql(raw: RawSqlClient, label: string): SqlClient {
+  const wrapResult = <T>(
+    result: PromiseLike<T>,
+    query: string,
+    params: unknown[],
+  ): Promise<T> => {
+    const started = Date.now();
+    const resv = reserveEvent();
+    return Promise.resolve(result).then(
+      (value) => {
+        const { rows, rowsTruncated, columns } = captureRows(value);
+        const seq = recordDb(
+          {
+            service: label,
+            query,
+            params: params.length > 0 ? params.map(safeSerialize) : undefined,
+            rowCount: rowCountOf(value),
+            rowsAffected: isAffectedCount(query, value) || undefined,
+            rows,
+            rowsTruncated,
+            columns,
+            durationMs: Date.now() - started,
+          },
+          resv,
+        );
+        return wrap(value, seq) as T;
+      },
+      (err) => {
+        const e = err as Error;
+        recordDb(
+          {
+            service: label,
+            query,
+            params: params.length > 0 ? params.map(safeSerialize) : undefined,
+            durationMs: Date.now() - started,
+            error: e?.message ?? String(err),
+          },
+          resv,
+        );
+        throw err;
+      },
+    );
+  };
+
+  const handler: ProxyHandler<RawSqlClient> = {
+    apply(target, thisArg, args) {
+      const [strings, ...values] = args as [TemplateStringsArray, ...unknown[]];
+      const query = reconstructSqlTemplate(strings, values.length);
+      const result = Reflect.apply(
+        target as unknown as (...a: unknown[]) => PromiseLike<unknown>,
+        thisArg,
+        args,
+      );
+      return wrapResult(result, query, values);
+    },
+    get(target, prop, receiver) {
+      if (prop === "unsafe") {
+        return (text: string, params?: unknown[]) => {
+          const result = (
+            target.unsafe as (t: string, p?: unknown[]) => PromiseLike<unknown>
+          ).call(target, text, params);
+          return wrapResult(result, text, params ?? []);
+        };
+      }
+      const v = Reflect.get(target, prop, receiver);
+      return typeof v === "function" ? v.bind(target) : v;
+    },
+  };
+  return new Proxy(raw, handler) as unknown as SqlClient;
+}
+
+/** Rebuild a parameterized SQL string from a tagged-template's pieces.
+ * Bun.SQL substitutes `${value}` for `$1`, `$2`, …; we do the same so
+ * the recorded query matches what the server sees. */
+function reconstructSqlTemplate(
+  strings: TemplateStringsArray,
+  valueCount: number,
+): string {
+  let out = strings[0] ?? "";
+  for (let i = 0; i < valueCount; i++) {
+    out += `$${i + 1}` + (strings[i + 1] ?? "");
+  }
+  return out.trim();
+}
+
+function rowCountOf(value: unknown): number | undefined {
+  if (value && typeof value === "object") {
+    const obj = value as { count?: unknown; rowCount?: unknown };
+    // Bun.SQL (postgres.js semantics): `.count` is rows RETURNED for
+    // SELECT/RETURNING queries and rows AFFECTED for other writes — where
+    // the result array itself is empty. Check it before `.length`, or a
+    // non-RETURNING `UPDATE` that touched 3 rows records a misleading 0.
+    if (typeof obj.count === "number") return obj.count;
+    if (typeof obj.rowCount === "number") return obj.rowCount;
+  }
+  if (Array.isArray(value)) return value.length;
+  return undefined;
+}
+
+/** True when the recorded count means "rows affected" rather than "rows
+ *  returned" — a write with no result set. Lets the dashboard render
+ *  `3 affected` instead of `3 rows` (and keeps `UPDATE … (0 rows)` from
+ *  reading as "nothing updated"). */
+function isAffectedCount(query: string, value: unknown): boolean {
+  if (Array.isArray(value) && value.length > 0) return false; // rows came back
+  const q = query.trimStart().slice(0, 8).toUpperCase();
+  return (
+    q.startsWith("INSERT") ||
+    q.startsWith("UPDATE") ||
+    q.startsWith("DELETE") ||
+    q.startsWith("MERGE")
+  );
+}
+
+const MAX_DB_ROWS = 50;
+
+function captureRows(value: unknown): {
+  rows?: unknown[];
+  rowsTruncated?: boolean;
+  columns?: string[];
+} {
+  if (!Array.isArray(value) || value.length === 0) return {};
+  const slice = value.slice(0, MAX_DB_ROWS).map(safeSerialize);
+  const first = slice[0];
+  const columns =
+    first && typeof first === "object" && !Array.isArray(first)
+      ? Object.keys(first as Record<string, unknown>)
+      : undefined;
+  return {
+    rows: slice,
+    rowsTruncated: value.length > MAX_DB_ROWS ? true : undefined,
+    columns,
+  };
+}