@specific.dev/spectest 0.24.0 → 0.27.0

package/dist/components/postgres.d.ts

@@ -0,0 +1,93 @@
+import { type SqlClient } from "../sql.js";
+export interface PostgresOptions {
+    /** Image tag for the official `postgres` image. Default `"18-alpine"`.
+     *  Ignored when {@link image} is set. */
+    version?: string;
+    /**
+     * Full image reference, overriding the default `postgres:<version>`. For a
+     * Bun-SQL-/wire-compatible image (timescaledb, postgis, pgvector, …) you
+     * still get the instrumented client on `ctx.svc.<name>.client`.
+     */
+    image?: string;
+    /** Database created on first boot. */
+    database: string;
+    /** Superuser name created on first boot. */
+    user: string;
+    /** Superuser password. */
+    password: string;
+    /**
+     * Whether postgres data persists across container restarts via a bind
+     * mount under `.spectest/volumes/<name>/`. Default `true`.
+     * Snapshots/forks always preserve state regardless of this flag — the
+     * volume just means a plain `docker rm`/`docker run` cycle keeps data.
+     */
+    persistent?: boolean;
+    /** TCP port the container listens on. Default `5432`. */
+    port?: number;
+    /**
+     * CMD args appended after the image entrypoint (keeps the entrypoint, unlike
+     * `command`). For extension tuning, e.g.
+     * `["postgres", "-c", "timescaledb.max_background_workers=0"]`.
+     */
+    args?: string[];
+    /** Extra environment variables forwarded to the container. */
+    env?: Record<string, string>;
+}
+/** Helpers a `postgres(...)` service exposes on `ctx.svc.<name>`. */
+export interface PostgresHelpers {
+    /** An instrumented Bun SQL client — each query lands on the test event log
+     *  alongside http/exec/assertion events, and its rows come back
+     *  inspect-wrapped so `expect(...)` on them links to the query. See
+     *  {@link SQL}. */
+    client: SqlClient;
+}
+/**
+ * A ready-to-use Postgres service. Drop into `environment.services`:
+ *
+ * ```ts
+ * services: {
+ *   db: postgres({ database: "todos", user: "todos", password: "todos" }),
+ *   ...
+ * }
+ * ```
+ *
+ * Peer services reach it at `<key>:<port>` (e.g. `db:5432` for the
+ * example above). Tests get a wired-up Bun SQL client at
+ * `ctx.svc.<key>.client` — `await ctx.svc.db.client\`SELECT 1\`` — with
+ * every query recorded on the test event log.
+ *
+ * Point it at a wire-compatible image with `image`/`args`:
+ *
+ * ```ts
+ * db: postgres({
+ *   image: "timescale/timescaledb:latest-pg17",
+ *   args: ["postgres", "-c", "timescaledb.max_background_workers=0"],
+ *   database: "app", user: "app", password: "app",
+ * }),
+ * ```
+ */
+export declare function postgres(opts: PostgresOptions): {
+    env: {
+        POSTGRES_DB: string;
+        POSTGRES_USER: string;
+        POSTGRES_PASSWORD: string;
+        PGDATA: string;
+    };
+    volumes: {
+        target: string;
+    }[];
+    ports: number[];
+    readyCheck: {
+        type: "tcp";
+        port: number;
+        timeoutSecs: number;
+    };
+    helpers: ({ name }: {
+        name: string;
+    }) => PostgresHelpers;
+    args?: string[] | undefined;
+    image: {
+        type: "registry";
+        reference: string;
+    };
+};

package/dist/components/postgres.js

@@ -0,0 +1,58 @@
+import { SQL } from "../sql.js";
+/**
+ * A ready-to-use Postgres service. Drop into `environment.services`:
+ *
+ * ```ts
+ * services: {
+ *   db: postgres({ database: "todos", user: "todos", password: "todos" }),
+ *   ...
+ * }
+ * ```
+ *
+ * Peer services reach it at `<key>:<port>` (e.g. `db:5432` for the
+ * example above). Tests get a wired-up Bun SQL client at
+ * `ctx.svc.<key>.client` — `await ctx.svc.db.client\`SELECT 1\`` — with
+ * every query recorded on the test event log.
+ *
+ * Point it at a wire-compatible image with `image`/`args`:
+ *
+ * ```ts
+ * db: postgres({
+ *   image: "timescale/timescaledb:latest-pg17",
+ *   args: ["postgres", "-c", "timescaledb.max_background_workers=0"],
+ *   database: "app", user: "app", password: "app",
+ * }),
+ * ```
+ */
+export function postgres(opts) {
+    const version = opts.version ?? "18-alpine";
+    const reference = opts.image ?? `postgres:${version}`;
+    const port = opts.port ?? 5432;
+    const persistent = opts.persistent ?? true;
+    // `satisfies` (instead of a return-type annotation) preserves the
+    // literal type — in particular, the `helpers` factory's return shape.
+    // The mapped type in `ServiceHandlesFor<S>` reads that to type
+    // `ctx.svc.<name>` as `{ client: SqlClient }`.
+    return {
+        image: { type: "registry", reference },
+        ...(opts.args ? { args: opts.args } : {}),
+        env: {
+            POSTGRES_DB: opts.database,
+            POSTGRES_USER: opts.user,
+            POSTGRES_PASSWORD: opts.password,
+            // PGDATA lives in a subdir so postgres can initialise inside a bind
+            // mount that may not be empty on first boot.
+            PGDATA: "/var/lib/postgresql/data/pgdata",
+            ...(opts.env ?? {}),
+        },
+        volumes: persistent ? [{ target: "/var/lib/postgresql/data" }] : [],
+        ports: [port],
+        readyCheck: { type: "tcp", port, timeoutSecs: 60 },
+        helpers: ({ name }) => {
+            const url = `postgres://${encodeURIComponent(opts.user)}` +
+                `:${encodeURIComponent(opts.password)}` +
+                `@${name}:${port}/${encodeURIComponent(opts.database)}`;
+            return { client: new SQL(url, { label: name }) };
+        },
+    };
+}

package/dist/components/replayFake.d.ts

@@ -0,0 +1,169 @@
+import type { FakeDefinition } from "../index.js";
+/** Which parts of a request define a match against the cassette. */
+export interface ReplayMatch {
+    /** Match on HTTP method. Default `true`. */
+    method?: boolean;
+    /** Match on path (no query). Default `true`. */
+    path?: boolean;
+    /** Match on normalized query string. Default `true`. */
+    query?: boolean;
+    /** Match on body: `true` = exact decoded body, `"hash"` = sha256 only.
+     *  Default off. */
+    body?: boolean | "hash";
+    /** Header names (lowercase) to include in the match. Default none. */
+    headers?: string[];
+}
+/** Match one request dimension. A bare string is an exact match; the
+ *  object forms cover prefix and regex matching. */
+export type StringMatch = string | {
+    exact: string;
+} | {
+    startsWith: string;
+} | {
+    regex: string;
+};
+/** Request matchers for a credential-injection rule. A rule applies only
+ *  when EVERY specified dimension matches; omit `match` to always apply. */
+export interface InjectMatch {
+    /** Match the request path (no query). */
+    path?: StringMatch;
+    /** HTTP method(s) — any one matching satisfies it. */
+    method?: string | string[];
+    /** Query-param matchers (ANDed); each key's value(s) must match. */
+    query?: Record<string, StringMatch>;
+    /** Header matchers (ANDed; header names case-insensitive). */
+    headers?: Record<string, StringMatch>;
+}
+/** One credential-brokering rule. When it matches a request, these headers
+ *  are SET on the egress forward — overwriting whatever the app sent (so app
+ *  code can't smuggle a different value past the broker). Header VALUES may
+ *  embed `{{secret:REF}}` tokens; each `REF` is resolved server-side from the
+ *  project's Secrets store and pushed eval-scoped — the real value never
+ *  enters project code, the
+ *  tarball, the warm-cache hash, or a cassette (it's redacted, fail-closed). */
+export interface InjectRule {
+    match?: InjectMatch;
+    headers: Record<string, string>;
+}
+/** SigV4 request-signing broker. Unlike `inject` (which SETs a static header
+ *  value), this RE-SIGNS the outbound request: the app signs with throwaway
+ *  dummy credentials, we strip that signature and re-sign the exact outbound
+ *  request with the real credentials — the only way to broker AWS auth, whose
+ *  signature is a keyed HMAC over the whole request, not a static token.
+ *
+ *  The three fields are **secret refs, resolved directly** from the project's
+ *  Secrets store (NOT `{{secret:}}` templates) — same eval-scoped push and
+ *  fail-closed redaction as `inject`. Region + service are inferred from the
+ *  incoming request (its credential scope, else the host); the app never
+ *  configures them. */
+export interface AwsSigV4Sign {
+    type: "awsSigv4";
+    /** Secret ref for the AWS access key id. */
+    accessKeyId: string;
+    /** Secret ref for the AWS secret access key. */
+    secretAccessKey: string;
+    /** Optional secret ref for a session token (temporary credentials). */
+    sessionToken?: string;
+}
+export type SignConfig = AwsSigV4Sign;
+export interface ReplayFakeOptions {
+    /** Stable name — the `ctx.fakes` key. */
+    name: string;
+    /** The REAL host to fake, e.g. `"api.stripe.com"`. The fake answers for
+     *  this name on both `http://` (:80) and `https://` (:443), and the same
+     *  name is forwarded to the real upstream in record mode (over HTTPS,
+     *  resolved via an external DNS server — see the module header). Your
+     *  app points at this real host directly; no separate stand-in. */
+    host: string;
+    /** What defines a request match. Default `{ method, path, query }`. */
+    match?: ReplayMatch;
+    /** Per-fake credential brokering. Rules are evaluated in
+     *  order; the first whose `match` matches wins (a rule without `match`
+     *  matches everything and shadows later rules). Applied at the
+     *  record-mode egress forward; resolved secret values are redacted from
+     *  the cassette (fail-closed). */
+    inject?: InjectRule[];
+    /** SigV4 request signing (AWS). When set, the record-mode forward strips the
+     *  app's dummy signature and re-signs the outbound request with the brokered
+     *  credentials. Point your AWS SDK at the real host with any dummy static
+     *  creds (e.g. `AWS_ACCESS_KEY_ID=test`) — the dummies are stripped and the
+     *  real ones live only on the outbound wire (redacted from the cassette). */
+    sign?: SignConfig;
+    /** Extra substrings/patterns to scrub from stored request/response
+     *  bodies and queries (every injected secret value is always scrubbed). */
+    redactPatterns?: (string | RegExp)[];
+    /** `"auto"` (default) records under eval and replays under test;
+     *  `"record"` / `"replay"` force a mode. */
+    mode?: "auto" | "record" | "replay";
+}
+export interface CassetteRequest {
+    method: string;
+    path: string;
+    /** Normalized: keys + repeated values sorted, so matching is order-free. */
+    query: Record<string, string[]>;
+    /** Matched/readable header subset only — never `authorization`/`cookie`. */
+    headers: Record<string, string>;
+    bodyHash?: string;
+    /** Request body (omitted when empty): decoded + redacted UTF-8 text, or
+     *  base64 for binary payloads (S3 object PUTs, protobuf, …). */
+    body?: string;
+    /** Encoding of `body`. Absent = `"utf8"` (back-compat with old cassettes). */
+    bodyEncoding?: "utf8" | "base64";
+}
+export interface CassetteResponse {
+    status: number;
+    headers: Record<string, string>;
+    /** Decoded + redacted response body. */
+    body: string;
+    bodyEncoding: "utf8" | "base64";
+}
+export interface CassetteInteraction {
+    request: CassetteRequest;
+    response: CassetteResponse;
+}
+export interface Cassette {
+    version: 1;
+    fake: string;
+    /** The real host this cassette mirrors (e.g. `api.stripe.com`). */
+    host: string;
+    interactions: CassetteInteraction[];
+}
+/** Forked-per-test state for one replay fake. */
+export interface CassetteState {
+    cassette: Cassette;
+    /** Per-match-signature replay cursor (call-order sequencing). */
+    cursor: Map<string, number>;
+    /** Interactions captured this record session. */
+    recorded: CassetteInteraction[];
+    dirty: boolean;
+}
+/** What `replay(...)` returns — a small summary that surfaces in the test
+ *  timeline (recorded as a `fake` event) so the run shows exactly which
+ *  cassette a test loaded and how many interactions it carried. */
+export interface ReplaySummary {
+    /** Filename loaded (under `spectest/recordings/`) or `"(inline)"`. */
+    cassette: string;
+    /** The real host the cassette mirrors. */
+    host: string;
+    /** Number of interactions now available for replay. */
+    interactions: number;
+}
+export interface ReplayHelpers extends Record<string, unknown> {
+    /** Load a cassette into THIS fork's replay set and replay from it,
+     *  replacing whatever was loaded before and resetting the replay cursor.
+     *  Cassettes are NOT auto-loaded — call this at the top of a test. Pass a
+     *  path relative to `spectest/tests/` (e.g. `"recordings/stripe.json"`; it
+     *  must stay under `spectest/tests/`) or a cassette object; a missing file
+     *  throws. The returned summary is recorded as a step, so the UI timeline
+     *  shows what was loaded. */
+    replay(file: string | Cassette): ReplaySummary;
+    /** Full cassette JSON (loaded interactions + newly recorded, redacted)
+     *  — the MVP delivery channel: `export default ctx.fakes.<name>.dump()`,
+     *  then write the result to `spectest/recordings/<name>.json`. */
+    dump(): Cassette;
+    /** Interactions captured this record session. */
+    recorded(): CassetteInteraction[];
+    /** Count of interactions captured this record session. */
+    count(): number;
+}
+export declare function replayFake(opts: ReplayFakeOptions): FakeDefinition<CassetteState, ReplayHelpers>;