@specific.dev/spectest 0.32.1 → 0.34.0

package/dist/components/aws.d.ts

@@ -0,0 +1,112 @@
+import type { ServiceSetupContext } from "../index.js";
+export interface AwsOptions {
+    /**
+     * Lambda functions to deploy from the project's own source, keyed by
+     * function name — the name the app (or a state machine) invokes.
+     *
+     * ```ts
+     * lambdas: {
+     *   add:      { source: "lambda/add" },
+     *   resize:   { source: "lambda/resize", runtime: "python3.12", timeoutSecs: 60 },
+     * }
+     * ```
+     *
+     * Each is packaged and deployed during environment bring-up, so it is part
+     * of the warm-template snapshot: a warm start restores the deployed
+     * function instead of deploying it again.
+     */
+    lambdas?: Record<string, LambdaOptions>;
+}
+export interface LambdaOptions {
+    /**
+     * The function's code, as a path in your repository — either a directory
+     * (packaged whole, recursively, with its contents at the root of the
+     * package) or a single file. Relative paths resolve against the project
+     * root, so `"lambda/add"` is the repo's own `lambda/add/`.
+     *
+     * The code is taken from the repository on purpose: the function you test
+     * is the function you ship. Anything the handler imports at runtime —
+     * including its dependencies — must be inside this path, exactly as a real
+     * deployment package requires.
+     */
+    source: string;
+    /** Entry point, as AWS spells it: `<file>.<exported function>`. Default
+     *  `"index.handler"`. */
+    handler?: string;
+    /** Lambda runtime identifier. Default `"nodejs20.x"`. */
+    runtime?: string;
+    /** Environment variables for the function. */
+    env?: Record<string, string>;
+    /** Function timeout in seconds. Default `30`. */
+    timeoutSecs?: number;
+    /** Execution-role ARN. Defaults to a fixed placeholder — the emulator does
+     *  not enforce IAM. Set it only when the code reads the ARN itself. */
+    role?: string;
+}
+/**
+ * The AWS cloud APIs, emulated in the environment and answering at their real
+ * endpoints. Drop into `environment.services`:
+ *
+ * ```ts
+ * import { aws } from "@specific.dev/spectest/components";
+ *
+ * services: {
+ *   aws: aws({
+ *     lambdas: {
+ *       add:      { source: "lambda/add" },
+ *       subtract: { source: "lambda/subtract" },
+ *     },
+ *   }),
+ *   app: {
+ *     image: { type: "dockerfile", content: appDockerfile },
+ *     // Whatever the app already reads in production. An AWS SDK needs a
+ *     // region and credentials; the emulator accepts any credential value.
+ *     env: {
+ *       AWS_REGION: "us-east-1",
+ *       AWS_ACCESS_KEY_ID: "test",
+ *       AWS_SECRET_ACCESS_KEY: "test",
+ *     },
+ *     dependsOn: ["aws"],
+ *   },
+ * }
+ * ```
+ *
+ * The app keeps its production configuration — `new SFNClient({})`, no
+ * endpoint — because the component owns DNS and TLS for the AWS domains. It
+ * answers for **every region**, so an app that talks to two of them, or that
+ * reads its region from configuration, needs nothing declared here.
+ *
+ * Tests reach the same cloud with the AWS CLI, which the emulator's image
+ * ships as `awslocal` (the CLI, already pointed at it):
+ *
+ * ```ts
+ * const listed = await ctx.exec("aws", "awslocal stepfunctions list-state-machines");
+ * expect(listed.exitCode).toBe(0);
+ * const machines = listed.stdout.transform("machines", (out) =>
+ *   (JSON.parse(out) as { stateMachines: unknown[] }).stateMachines,
+ * );
+ * expect(machines).toHaveLength(1);
+ * ```
+ *
+ * For S3, prefer the `s3()` component and give it the endpoint your app uses
+ * (`s3({ hosts: ["s3.us-east-1.amazonaws.com"] })`). An exact hostname always
+ * beats this component's wildcard, so the two compose without further
+ * configuration.
+ */
+export declare function aws(opts?: AwsOptions): {
+    setup?: (({ name, projectRoot }: ServiceSetupContext) => Promise<void>) | undefined;
+    image: {
+        type: "registry";
+        reference: string;
+    };
+    env: {
+        AWS_DEFAULT_REGION: string;
+    };
+    ports: number[];
+    readyCheck: {
+        type: "http";
+        port: number;
+        path: string;
+        timeoutSecs: number;
+    };
+};

package/dist/components/aws.js

@@ -0,0 +1,397 @@
+// `aws()` — the AWS cloud APIs, emulated inside the environment, answering
+// at their **real** endpoints.
+//
+// The component runs one emulator container and claims the AWS domains for
+// it: DNS, a leaf certificate minted from the in-VM root CA, and a
+// TLS-terminating reverse proxy. An AWS SDK in the app under test therefore
+// resolves `https://states.us-east-1.amazonaws.com` the way it does in
+// production and reaches the emulator — the app needs no endpoint override,
+// no test-only branch, and no knowledge that it is under test.
+//
+// Lambda functions are declared next to the services and deployed from the
+// project's own source. Deployment happens in the service `setup` hook, which
+// runs before the warm-template snapshot, so a warm start restores functions
+// that are already deployed, already active, and already warm.
+//
+// ── Internal notes (deliberately not in the user-facing docs) ──────────────
+//
+// The backing image is MiniStack (MIT, github.com/ministackorg/ministack),
+// pinned rather than floated. It replaced LocalStack, which folded its
+// Apache-2.0 Community edition into one paid product in March 2026 (current
+// images demand a LOCALSTACK_AUTH_TOKEN). MiniStack also suits fork-per-test
+// far better: ~270 MB against ~1 GB, a ~2 s boot, and Lambda on an in-process
+// warm worker pool instead of sibling containers — so no docker socket is
+// bind-mounted and there is no host-architecture workaround on Graviton.
+//
+// Like `email()`'s mail server, the product name stays out of every
+// user-facing surface (docs, examples, error messages). Users get "the AWS
+// emulator"; `image` swaps it.
+//
+// The emulator ignores SigV4 and does not check that a role exists, both
+// verified on 1.4.8. That is what lets this component deploy over plain
+// unsigned HTTP from the daemon and skip IAM entirely.
+import { readFile, readdir, stat } from "node:fs/promises";
+import path from "node:path";
+import { deflateRawSync } from "node:zlib";
+import { certificate, provides, proxy, SELF_SERVICE_TOKEN } from "../index.js";
+import { pauseRecording, resumeRecording } from "../recorder.js";
+/** Backing image, pinned internally (not part of the documented surface). */
+const AWS_IMAGE = "ministackorg/ministack:1.4.8";
+/** Port the emulator serves every AWS API on. Internal: callers reach the
+ *  emulator through the AWS hostnames, never through this port. */
+const AWS_PORT = 4566;
+// Every AWS region, so the component can answer for all of them and the user
+// never has to declare which ones the app uses. Enumeration is forced by TLS,
+// not by routing: a wildcard *route* matches any depth, but a wildcard
+// *certificate* covers exactly one label (RFC 6125, enforced by every
+// client), so `*.amazonaws.com` cannot serve `states.us-east-1.amazonaws.com`
+// — each region needs its own `*.<region>.amazonaws.com` name. They all ride
+// ONE certificate as SANs and one shared upstream, so the list costs a few
+// route-table entries, not a key generation each.
+//
+// Sourced from AWS's own published `ip-ranges.json` (2026-07-31). A region
+// added later is simply not claimed: its endpoints fail to resolve, which
+// says plainly what happened — add it here.
+const AWS_REGIONS = [
+    "af-south-1", "ap-east-1", "ap-east-2", "ap-northeast-1", "ap-northeast-2",
+    "ap-northeast-3", "ap-south-1", "ap-south-2", "ap-southeast-1", "ap-southeast-2",
+    "ap-southeast-3", "ap-southeast-4", "ap-southeast-5", "ap-southeast-6",
+    "ap-southeast-7", "ca-central-1", "ca-west-1", "eu-central-1", "eu-central-2",
+    "eu-north-1", "eu-south-1", "eu-south-2", "eu-west-1", "eu-west-2", "eu-west-3",
+    "eusc-de-east-1", "il-central-1", "me-central-1", "me-south-1", "me-west-1",
+    "mx-central-1", "sa-east-1", "sa-west-1", "us-east-1", "us-east-2",
+    "us-gov-east-1", "us-gov-west-1", "us-south-1", "us-west-1", "us-west-2",
+];
+/** China is a separate partition on its own domain suffix. */
+const AWS_CN_REGIONS = ["cn-north-1", "cn-northwest-1"];
+/** Every hostname pattern the emulator answers to: the two partitions' global
+ *  endpoints (`sts.amazonaws.com`, `iam.amazonaws.com`) plus one per region
+ *  for the regional ones (`states.us-east-1.amazonaws.com`). */
+const AWS_HOST_PATTERNS = [
+    "*.amazonaws.com",
+    ...AWS_REGIONS.map((r) => `*.${r}.amazonaws.com`),
+    "*.amazonaws.com.cn",
+    ...AWS_CN_REGIONS.map((r) => `*.${r}.amazonaws.com.cn`),
+];
+/** Region the emulator's own tools default to — the AWS CLI refuses to run
+ *  without one. Only the *container's* default; it constrains nothing about
+ *  the app, and every region is served regardless. A `setup` hook that drives
+ *  the CLI against another region passes `--region`. */
+const CONTAINER_DEFAULT_REGION = "us-east-1";
+/** Role every declared function is created with. The emulator does not
+ *  enforce IAM, so this only has to be a well-formed ARN — which is why the
+ *  component creates no role and takes no IAM options. A project that wants a
+ *  real-looking role can create one itself and set `role` on the function. */
+const DEFAULT_ROLE_ARN = "arn:aws:iam::000000000000:role/spectest-lambda";
+/** Ready-check budget. The emulator boots in a couple of seconds; the slow
+ *  part is a cold image pull on a machine that has never run it. */
+const READY_TIMEOUT_SECS = 120;
+/** Memory every declared function is created with. Kept at what this
+ *  component has always used, rather than the emulator's own default, so the
+ *  removal of the `memoryMb` option changed no behaviour. */
+const MEMORY_MB = 512;
+/**
+ * The AWS cloud APIs, emulated in the environment and answering at their real
+ * endpoints. Drop into `environment.services`:
+ *
+ * ```ts
+ * import { aws } from "@specific.dev/spectest/components";
+ *
+ * services: {
+ *   aws: aws({
+ *     lambdas: {
+ *       add:      { source: "lambda/add" },
+ *       subtract: { source: "lambda/subtract" },
+ *     },
+ *   }),
+ *   app: {
+ *     image: { type: "dockerfile", content: appDockerfile },
+ *     // Whatever the app already reads in production. An AWS SDK needs a
+ *     // region and credentials; the emulator accepts any credential value.
+ *     env: {
+ *       AWS_REGION: "us-east-1",
+ *       AWS_ACCESS_KEY_ID: "test",
+ *       AWS_SECRET_ACCESS_KEY: "test",
+ *     },
+ *     dependsOn: ["aws"],
+ *   },
+ * }
+ * ```
+ *
+ * The app keeps its production configuration — `new SFNClient({})`, no
+ * endpoint — because the component owns DNS and TLS for the AWS domains. It
+ * answers for **every region**, so an app that talks to two of them, or that
+ * reads its region from configuration, needs nothing declared here.
+ *
+ * Tests reach the same cloud with the AWS CLI, which the emulator's image
+ * ships as `awslocal` (the CLI, already pointed at it):
+ *
+ * ```ts
+ * const listed = await ctx.exec("aws", "awslocal stepfunctions list-state-machines");
+ * expect(listed.exitCode).toBe(0);
+ * const machines = listed.stdout.transform("machines", (out) =>
+ *   (JSON.parse(out) as { stateMachines: unknown[] }).stateMachines,
+ * );
+ * expect(machines).toHaveLength(1);
+ * ```
+ *
+ * For S3, prefer the `s3()` component and give it the endpoint your app uses
+ * (`s3({ hosts: ["s3.us-east-1.amazonaws.com"] })`). An exact hostname always
+ * beats this component's wildcard, so the two compose without further
+ * configuration.
+ */
+export function aws(opts = {}) {
+    const lambdas = opts.lambdas ?? {};
+    const service = {
+        image: { type: "registry", reference: AWS_IMAGE },
+        env: { AWS_DEFAULT_REGION: CONTAINER_DEFAULT_REGION },
+        ports: [AWS_PORT],
+        readyCheck: {
+            type: "http",
+            port: AWS_PORT,
+            path: "/_ministack/health",
+            timeoutSecs: READY_TIMEOUT_SECS,
+        },
+        ...(Object.keys(lambdas).length > 0
+            ? {
+                setup: async ({ name, projectRoot }) => {
+                    for (const [fn, spec] of Object.entries(lambdas)) {
+                        await deployLambda(name, projectRoot, fn, spec);
+                    }
+                },
+            }
+            : {}),
+    };
+    // The low-level primitives rather than the `tls` field, for one reason:
+    // `tls` mints a separate leaf certificate per entry, and this component
+    // claims several dozen names. One `certificate(...)` decl carries them all
+    // as SANs of a single leaf — one key generation at bring-up instead of
+    // dozens — while the proxies are just route-table entries.
+    return provides(service, [
+        certificate(AWS_HOST_PATTERNS),
+        ...AWS_HOST_PATTERNS.map((hostname) => proxy(hostname, { service: SELF_SERVICE_TOKEN, port: AWS_PORT })),
+    ]);
+}
+// ──────────────────────────────────────────────────────────────────────────
+// Talking to the emulator directly
+//
+// The emulator ignores request signatures, so the daemon reaches its APIs
+// over plain unsigned HTTP. That keeps deployment independent of what tools
+// the image happens to ship, and keeps a poll loop cheap.
+// ──────────────────────────────────────────────────────────────────────────
+/** One JSON-protocol AWS call (Step Functions, DynamoDB, …), by target. */
+async function request(service, method, urlPath, init = {}) {
+    // Never let the component's own traffic land on the timeline: these calls
+    // are bring-up and polling, not something a test asked for.
+    pauseRecording();
+    try {
+        const res = await fetch(`http://${service}:${AWS_PORT}${urlPath}`, {
+            method,
+            headers: { "content-type": "application/json", ...(init.headers ?? {}) },
+            ...(init.body !== undefined ? { body: init.body } : {}),
+        });
+        // Coerced rather than read directly: `fetch` is wrapped during a test, so
+        // `res.status` is a provenance carrier there and a plain number elsewhere.
+        const status = Number(res.status);
+        const text = String(await res.text());
+        if (status >= 400) {
+            const err = new Error(`aws: ${method} ${urlPath} failed: HTTP ${status} ${text.slice(0, 400)}`);
+            err.status = status;
+            throw err;
+        }
+        return text === "" ? undefined : JSON.parse(text);
+    }
+    finally {
+        resumeRecording();
+    }
+}
+// ──────────────────────────────────────────────────────────────────────────
+// Lambda deployment
+// ──────────────────────────────────────────────────────────────────────────
+/** Refuse a package that no real deployment would accept either. */
+const MAX_PACKAGE_BYTES = 64 * 1024 * 1024;
+async function deployLambda(service, projectRoot, name, spec) {
+    if (typeof spec?.source !== "string" || spec.source.trim() === "") {
+        throw new Error(`aws: lambda "${name}" needs a \`source\` path to its code`);
+    }
+    const zipped = await packageSource(projectRoot, name, spec.source);
+    if (zipped.length > MAX_PACKAGE_BYTES) {
+        throw new Error(`aws: lambda "${name}" packages to ${Math.round(zipped.length / 1e6)} MB from ` +
+            `${spec.source} — over the ${MAX_PACKAGE_BYTES / 1e6} MB limit. Point \`source\` at ` +
+            `the function's own directory, not a whole repository.`);
+    }
+    const code = Buffer.from(zipped).toString("base64");
+    const config = {
+        Runtime: spec.runtime ?? "nodejs20.x",
+        Handler: spec.handler ?? "index.handler",
+        Role: spec.role ?? DEFAULT_ROLE_ARN,
+        Timeout: spec.timeoutSecs ?? 30,
+        // Fixed, and not an option: the emulated cloud runs handlers in a shared
+        // worker pool rather than a memory-capped sandbox, so the number changes
+        // nothing about how a function behaves here.
+        MemorySize: MEMORY_MB,
+        ...(spec.env ? { Environment: { Variables: spec.env } } : {}),
+    };
+    try {
+        await request(service, "POST", "/2015-03-31/functions", {
+            body: JSON.stringify({ FunctionName: name, Code: { ZipFile: code }, ...config }),
+        });
+    }
+    catch (err) {
+        // Already there: a re-run of bring-up against an emulator that kept its
+        // state. Update instead, so the deployed code always matches the repo.
+        if (err.status !== 409)
+            throw err;
+        await request(service, "PUT", `/2015-03-31/functions/${encodeURIComponent(name)}/code`, {
+            body: JSON.stringify({ ZipFile: code }),
+        });
+        await request(service, "PUT", `/2015-03-31/functions/${encodeURIComponent(name)}/configuration`, {
+            body: JSON.stringify(config),
+        });
+    }
+    await waitActive(service, name);
+    // One invoke with an empty event, purely to leave a warm worker behind in
+    // the snapshot, so no test pays a cold start. The handler may well reject
+    // the event — that is fine, the worker is started either way.
+    try {
+        await request(service, "POST", `/2015-03-31/functions/${encodeURIComponent(name)}/invocations`, {
+            body: "{}",
+        });
+    }
+    catch {
+        // Ignored on purpose: warming is an optimisation, never a gate.
+    }
+}
+/** Wait for a newly created function to leave `Pending`, exactly as a real
+ *  deployment must. Tolerates an emulator that reports no state at all. */
+async function waitActive(service, name, timeoutMs = 60_000) {
+    const deadline = Date.now() + timeoutMs;
+    for (;;) {
+        const cfg = (await request(service, "GET", `/2015-03-31/functions/${encodeURIComponent(name)}/configuration`));
+        const state = cfg?.State;
+        if (state === undefined || state === "Active")
+            return;
+        if (state === "Failed") {
+            throw new Error(`aws: lambda "${name}" failed to deploy: ${cfg?.StateReason ?? "no reason given"}`);
+        }
+        if (Date.now() > deadline) {
+            throw new Error(`aws: lambda "${name}" was still ${state} after ${timeoutMs} ms`);
+        }
+        await new Promise((resolve) => setTimeout(resolve, 100));
+    }
+}
+async function packageSource(projectRoot, fnName, source) {
+    const root = path.isAbsolute(source) ? source : path.join(projectRoot, source);
+    let info;
+    try {
+        info = await stat(root);
+    }
+    catch {
+        throw new Error(`aws: lambda "${fnName}" has no code at ${source} (looked in ${root}). ` +
+            `\`source\` is a path in your repository, relative to its root.`);
+    }
+    const entries = [];
+    if (info.isDirectory()) {
+        await collect(root, "", entries);
+        if (entries.length === 0) {
+            throw new Error(`aws: lambda "${fnName}" has no files in ${source}`);
+        }
+    }
+    else {
+        entries.push({ name: path.basename(root), data: await readFile(root) });
+    }
+    // Sorted so the same source always packages to the same bytes.
+    entries.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+    return buildZip(entries);
+}
+async function collect(dir, prefix, out) {
+    for (const entry of await readdir(dir, { withFileTypes: true })) {
+        const full = path.join(dir, entry.name);
+        const rel = prefix === "" ? entry.name : `${prefix}/${entry.name}`;
+        if (entry.isDirectory()) {
+            await collect(full, rel, out);
+        }
+        else if (entry.isFile()) {
+            out.push({ name: rel, data: await readFile(full) });
+        }
+        // Symlinks and everything else are skipped: a deployment package holds
+        // regular files.
+    }
+}
+function crc32(buf) {
+    let crc = 0xffffffff;
+    for (let i = 0; i < buf.length; i++) {
+        let c = (crc ^ buf[i]) & 0xff;
+        for (let k = 0; k < 8; k++)
+            c = c & 1 ? (c >>> 1) ^ 0xedb88320 : c >>> 1;
+        crc = (crc >>> 8) ^ c;
+    }
+    return (crc ^ 0xffffffff) >>> 0;
+}
+/**
+ * Build a zip archive. Entries are deflated (method 8), or stored (method 0)
+ * when deflating makes them no smaller. Timestamps are fixed, so identical
+ * sources always produce identical bytes.
+ */
+function buildZip(entries) {
+    const encoder = new TextEncoder();
+    const local = [];
+    const central = [];
+    let offset = 0;
+    for (const entry of entries) {
+        const nameBytes = encoder.encode(entry.name);
+        const crc = crc32(entry.data);
+        const deflated = new Uint8Array(deflateRawSync(entry.data));
+        const stored = deflated.length >= entry.data.length;
+        const payload = stored ? entry.data : deflated;
+        const method = stored ? 0 : 8;
+        const header = new DataView(new ArrayBuffer(30));
+        header.setUint32(0, 0x04034b50, true); // local file header
+        header.setUint16(4, 20, true); // version needed
+        header.setUint16(6, 0, true); // flags
+        header.setUint16(8, method, true);
+        header.setUint16(10, 0, true); // time — fixed
+        header.setUint16(12, 0x21, true); // date — fixed (1 Jan 1980)
+        header.setUint32(14, crc, true);
+        header.setUint32(18, payload.length, true);
+        header.setUint32(22, entry.data.length, true);
+        header.setUint16(26, nameBytes.length, true);
+        header.setUint16(28, 0, true); // extra length
+        const headerBytes = new Uint8Array(header.buffer);
+        local.push(headerBytes, nameBytes, payload);
+        const dirEntry = new DataView(new ArrayBuffer(46));
+        dirEntry.setUint32(0, 0x02014b50, true); // central directory header
+        dirEntry.setUint16(4, 20, true); // version made by
+        dirEntry.setUint16(6, 20, true); // version needed
+        dirEntry.setUint16(8, 0, true); // flags
+        dirEntry.setUint16(10, method, true);
+        dirEntry.setUint16(12, 0, true);
+        dirEntry.setUint16(14, 0x21, true);
+        dirEntry.setUint32(16, crc, true);
+        dirEntry.setUint32(20, payload.length, true);
+        dirEntry.setUint32(24, entry.data.length, true);
+        dirEntry.setUint16(28, nameBytes.length, true);
+        // Permissions in the high half of the external attributes: 0644 for a
+        // regular file, which is what a Lambda runtime expects to find.
+        dirEntry.setUint32(38, 0o100644 << 16, true);
+        dirEntry.setUint32(42, offset, true);
+        central.push(new Uint8Array(dirEntry.buffer), nameBytes);
+        offset += headerBytes.length + nameBytes.length + payload.length;
+    }
+    const centralSize = central.reduce((n, part) => n + part.length, 0);
+    const end = new DataView(new ArrayBuffer(22));
+    end.setUint32(0, 0x06054b50, true); // end of central directory
+    end.setUint16(8, entries.length, true);
+    end.setUint16(10, entries.length, true);
+    end.setUint32(12, centralSize, true);
+    end.setUint32(16, offset, true);
+    const parts = [...local, ...central, new Uint8Array(end.buffer)];
+    const total = parts.reduce((n, part) => n + part.length, 0);
+    const zipped = new Uint8Array(total);
+    let cursor = 0;
+    for (const part of parts) {
+        zipped.set(part, cursor);
+        cursor += part.length;
+    }
+    return zipped;
+}

package/dist/components/index.d.ts

@@ -5,4 +5,5 @@ export { k3s, type K3sOptions, type K3sHelpers, type K3sClient, type TaggedObjec
 export { expo, type ExpoOptions, type ExpoHelpers, } from "./expo.js";
 export { supabase, type SupabaseOptions, type SupabaseHelpers, type SupabaseStack, } from "./supabase.js";
 export { email, type EmailOptions, type EmailHelpers, type EmailMessage, type EmailSummary, type EmailMatch, type EmailAttachment, } from "./email.js";
+export { aws, type AwsOptions, type LambdaOptions, } from "./aws.js";
 export { replayFake, type ReplayFakeOptions, type ReplayMatch, type InjectRule, type InjectMatch, type StringMatch, type SignConfig, type AwsSigV4Sign, type ReplayHelpers, type ReplaySummary, type Cassette, type CassetteInteraction, type CassetteRequest, type CassetteResponse, type CassetteState, } from "./replayFake.js";

package/dist/components/index.js

@@ -15,4 +15,5 @@ export { k3s, } from "./k3s.js";
 export { expo, } from "./expo.js";
 export { supabase, } from "./supabase.js";
 export { email, } from "./email.js";
+export { aws, } from "./aws.js";
 export { replayFake, } from "./replayFake.js";

package/dist/daemon.js

@@ -511,6 +511,17 @@ async function recordAbsoluteVolumeDir(host) {
     ABS_VOLUME_DIRS.add(host);
     await fs.writeFile(VOLUME_DIRS_MANIFEST, [...ABS_VOLUME_DIRS].join("\n") + "\n");
 }
+/// True when `p` exists and is not a directory (a socket, a regular file,
+/// a device). Used to tell "a volume dir we must create" from "a VM-host
+/// object the service asked to bind-mount as-is".
+async function isExistingNonDirectory(p) {
+    try {
+        return !(await fs.lstat(p)).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
 async function ensureVolumes(svc) {
     const flags = [];
     if (!svc.volumes || svc.volumes.length === 0)
@@ -522,9 +533,18 @@ async function ensureVolumes(svc) {
             throw new Error(`service "${svc.name}" volume for ${JSON.stringify(vol.target)} sets both \`name\` and \`source\``);
         }
         const host = resolveHostPath(svc.name, vol);
-        await fs.mkdir(host, { recursive: true });
-        if (vol.source?.startsWith("/") && !host.startsWith("/var/cache/spectest/")) {
-            await recordAbsoluteVolumeDir(host);
+        // An absolute `source` can name something that already exists and is
+        // NOT a directory — the canonical case is the VM's docker socket
+        // (`/var/run/docker.sock`), bind-mounted into a service that drives
+        // docker itself (LocalStack's Lambda executor, dind-style builders).
+        // `mkdir -p` fails on those with EEXIST. They are also VM-host
+        // infrastructure rather than environment state, so they are neither
+        // created here nor recorded for the delta-restore wipe.
+        if (!(await isExistingNonDirectory(host))) {
+            await fs.mkdir(host, { recursive: true });
+            if (vol.source?.startsWith("/") && !host.startsWith("/var/cache/spectest/")) {
+                await recordAbsoluteVolumeDir(host);
+            }
         }
         flags.push(`--volume=${host}:${vol.target}${vol.readOnly ? ":ro" : ""}`);
     }
@@ -1575,17 +1595,22 @@ async function startIngress() {
             routes.set(p.hostname, { kind: "proxy", service: p.service, port: p.port });
         }
     }
-    // The :443 route table mirrors every certificated hostname's handler.
+    // The :443 route table mirrors every handler whose hostname a cert
+    // covers — exactly, or through a wildcard SAN, so `*.example.com` in a
+    // service's `tls` also puts an unrelated exact `api.example.com` route on
+    // HTTPS. Proxies are applied after fakes so a proxy wins a shared host.
     if (HTTPS_CERT_BY_HOST.size > 0) {
         const httpsRoutes = ensurePort(INGRESS_HTTPS_PORT);
-        for (const h of HTTPS_CERT_BY_HOST.keys()) {
-            for (const fake of FAKES.values()) {
-                if (fake.hostnames.includes(h))
+        for (const fake of FAKES.values()) {
+            for (const h of fake.hostnames) {
+                if (certCovers(h))
                     httpsRoutes.set(h, { kind: "fake", fake });
             }
-            const proxy = LOWERED.proxies.find((p) => p.hostname === h);
-            if (proxy)
-                httpsRoutes.set(h, { kind: "proxy", service: proxy.service, port: proxy.port });
+        }
+        for (const p of LOWERED.proxies) {
+            if (certCovers(p.hostname)) {
+                httpsRoutes.set(p.hostname, { kind: "proxy", service: p.service, port: p.port });
+            }
         }
     }
     // ── HTTP listeners (one per non-443 port).
@@ -1649,12 +1674,26 @@ function rebindHttpsListener(Bun) {
     // eslint-disable-next-line no-console
     console.log(`[ingress] https :${INGRESS_HTTPS_PORT} for ${[...routes.keys()].join(", ")}`);
 }
+/**
+ * RFC 6125 wildcard match: `*.example.com` covers `api.example.com` but NOT
+ * `a.b.example.com`. Deliberately stricter than {@link matchIngressRoute}'s
+ * suffix matching — this one has to agree with the TLS *client*, and every
+ * client stops at one label. Claiming a deeper name is covered would skip
+ * minting the leaf it actually needs and hand it a cert it rejects.
+ */
+function wildcardCoversHost(pattern, hostname) {
+    const suffix = wildcardSuffix(pattern); // "*.example.com" → ".example.com"
+    if (!hostname.endsWith(suffix))
+        return false;
+    const label = hostname.slice(0, -suffix.length);
+    return label.length > 0 && !label.includes(".");
+}
 /** True if an exact or wildcard cert already covers `hostname` for SNI. */
 function certCovers(hostname) {
     if (HTTPS_CERT_BY_HOST.has(hostname))
         return true;
     for (const serverName of HTTPS_CERT_BY_HOST.keys()) {
-        if (isWildcard(serverName) && hostname.endsWith(wildcardSuffix(serverName))) {
+        if (isWildcard(serverName) && wildcardCoversHost(serverName, hostname)) {
             return true;
         }
     }
@@ -1706,8 +1745,16 @@ async function bindRuntimeTls(hostname, service, port) {
         rebindHttpsListener(Bun);
     }
     // Resolve the hostname to the daemon gateway (where :443/:80 listen).
+    // A wildcard can only live in the resolver's suffix table.
     const gw = await bridgeGatewayIp();
-    REGISTRY.hosts[host] = gw;
+    if (isWildcard(host)) {
+        const suffix = wildcardSuffix(host);
+        REGISTRY.wildcards = REGISTRY.wildcards.filter((w) => w.suffix !== suffix);
+        REGISTRY.wildcards.push({ suffix, ip: gw });
+    }
+    else {
+        REGISTRY.hosts[host] = gw;
+    }
     await writeRegistry();
     // eslint-disable-next-line no-console
     console.log(`[ingress] runtime https ${host} -> ${service}:${port}`);
@@ -1722,7 +1769,14 @@ async function unbindRuntimeTls(hostname) {
     const host = hostname.toLowerCase();
     INGRESS_ROUTES_BY_PORT.get(INGRESS_HTTP_PORT)?.delete(host);
     INGRESS_ROUTES_BY_PORT.get(INGRESS_HTTPS_PORT)?.delete(host);
-    if (host in REGISTRY.hosts) {
+    if (isWildcard(host)) {
+        const suffix = wildcardSuffix(host);
+        const before = REGISTRY.wildcards.length;
+        REGISTRY.wildcards = REGISTRY.wildcards.filter((w) => w.suffix !== suffix);
+        if (REGISTRY.wildcards.length !== before)
+            await writeRegistry();
+    }
+    else if (host in REGISTRY.hosts) {
         delete REGISTRY.hosts[host];
         await writeRegistry();
     }
@@ -1838,6 +1892,35 @@ Bun, port, byHost, listenerLabel, tlsEntries) {
         opts.tls = tlsEntries;
     return Bun.serve(opts);
 }
+/**
+ * Resolve a Host header to a route: an exact entry first, then the longest
+ * matching `*.suffix` wildcard. Same precedence the resolver applies to DNS
+ * (exact beats wildcard, longest suffix beats shorter), so a name that DNS
+ * pointed at the ingress finds the route that claimed it.
+ *
+ * A wildcard *route* matches any depth of subdomain, while a wildcard
+ * *cert* covers exactly one label ({@link wildcardCoversHost} — RFC 6125,
+ * what TLS clients enforce). So `a.b.example.com` under a `*.example.com`
+ * proxy reverse-proxies over `http://` but needs its own `tls` entry to
+ * present a valid cert over `https://`.
+ */
+function matchIngressRoute(byHost, host) {
+    const exact = byHost.get(host);
+    if (exact)
+        return exact;
+    let best;
+    let bestLen = -1;
+    for (const [pattern, route] of byHost) {
+        if (!isWildcard(pattern))
+            continue;
+        const suffix = wildcardSuffix(pattern);
+        if (host.endsWith(suffix) && suffix.length > bestLen) {
+            best = route;
+            bestLen = suffix.length;
+        }
+    }
+    return best;
+}
 /**
  * Per-request dispatch shared by every ingress listener. Looks up the
  * Route by Host header (port stripped) and either:
@@ -1852,7 +1935,7 @@ server, byHost, listenerLabel, proto) {
         .toLowerCase()
         .split(":")[0]
         .trim();
-    const route = byHost.get(host);
+    const route = matchIngressRoute(byHost, host);
     if (!route) {
         return new Response(`spectest-daemon: no ingress route bound to Host=${JSON.stringify(host)} on ${listenerLabel}\n`, { status: 404, headers: { "content-type": "text/plain" } });
     }

package/dist/index.d.ts

@@ -72,6 +72,11 @@ export interface ServiceConfig {
      * instead — those names terminate TLS in the daemon and reverse-proxy
      * to the service's HTTP port.
      *
+     * A `*.suffix` wildcard (e.g. `"*.example.com"`) points a whole domain
+     * at this service. Wildcards are answered by spectest-resolver only —
+     * they never land in a container's `/etc/hosts` — which peer containers
+     * still reach, since Docker forwards unknown names to that resolver.
+     *
      * The `.internal` TLD is reserved: every service automatically
      * answers to `<name>.internal` in addition to its bare `<name>`, and
      * user-supplied hostnames may not end in `.internal`.
@@ -92,6 +97,15 @@ export interface ServiceConfig {
      * tests and from peer services. Hostname rules match {@link hostnames}:
      * multi-label, lowercase, no `.internal` suffix, no collision with
      * services, other service TLS hostnames, or fakes.
+     *
+     * A `*.suffix` wildcard claims a whole domain with one entry — e.g.
+     * `{ hostname: "*.us-east-1.amazonaws.com", port: 4566 }` puts every
+     * AWS regional endpoint on one emulator container, so an unmodified SDK
+     * reaches it at its production URL. The leaf cert gets a wildcard SAN,
+     * which (as in every TLS client) covers exactly **one** label: declare
+     * a separate entry for anything deeper. An exact `tls` hostname always
+     * beats a wildcard, so a single endpoint can be split off to another
+     * service.
      */
     tls?: readonly ServiceTls[];
     /** Bind-mounted volumes for state that survives snapshot/fork. */
@@ -625,6 +639,12 @@ export interface VolumeMount {
     /**
      * Host path. Relative paths resolve under
      * `.spectest/volumes/<service>/`. Defaults to a path derived from `target`.
+     *
+     * An absolute path that already exists and is not a directory is
+     * bind-mounted as-is — the way to hand a service the VM's docker socket
+     * (`source: "/var/run/docker.sock"`), which LocalStack's Lambda executor
+     * and dind-style builders need. Such a mount is VM-host infrastructure,
+     * so unlike a volume directory it is never created or wiped by spectest.
      */
     source?: string;
     /** Container path. */

package/dist/index.js

@@ -31,6 +31,7 @@ import { describeUrlPattern, matchesUrl } from "./url-match.js";
 // `tls` / `hostnames` fields and `defineFake(...)` are built on. See
 // `ingress.ts`.
 export { certificate, dnsName, proxy, provides, lowerIngress, isWildcard, SELF_SERVICE_TOKEN, } from "./ingress.js";
+import { isWildcard as isWildcardHost } from "./ingress.js";
 // ──────────────────────────────────────────────────────────────────────────
 // Service groups — one services-map entry that expands to several services.
 //
@@ -234,8 +235,8 @@ function validateEnvironmentConfig(config) {
         }
         for (const raw of svc.hostnames ?? []) {
             const h = raw.toLowerCase();
-            if (!HOSTNAME_RE.test(h)) {
-                throw new Error(`service "${name}" declares invalid hostname ${JSON.stringify(raw)} — must be a multi-label DNS name (e.g. "api.stripe.com")`);
+            if (!HOSTNAME_RE.test(hostPatternBody(h))) {
+                throw new Error(`service "${name}" declares invalid hostname ${JSON.stringify(raw)} — must be a multi-label DNS name or a wildcard (e.g. "api.stripe.com", "*.stripe.com")`);
             }
             if (h === "internal" || h.endsWith(".internal")) {
                 throw new Error(`service "${name}" declares hostname ${JSON.stringify(raw)} — the ".internal" TLD is reserved; every service already answers to "<name>.internal" automatically`);
@@ -247,8 +248,8 @@ function validateEnvironmentConfig(config) {
                 throw new Error(`service "${name}" tls entry must be { hostname: string, port: number }; got ${JSON.stringify(entry)}`);
             }
             const h = entry.hostname.toLowerCase();
-            if (!HOSTNAME_RE.test(h)) {
-                throw new Error(`service "${name}" tls hostname ${JSON.stringify(entry.hostname)} is not a multi-label DNS name (e.g. "app.test")`);
+            if (!HOSTNAME_RE.test(hostPatternBody(h))) {
+                throw new Error(`service "${name}" tls hostname ${JSON.stringify(entry.hostname)} is not a multi-label DNS name or wildcard (e.g. "app.test", "*.us-east-1.amazonaws.com")`);
             }
             if (h === "internal" || h.endsWith(".internal")) {
                 throw new Error(`service "${name}" tls hostname ${JSON.stringify(entry.hostname)} ends in reserved ".internal" TLD`);
@@ -263,6 +264,13 @@ function validateEnvironmentConfig(config) {
 // Multi-label hostname: at least one dot, each label 1–63 chars of
 // [a-z0-9-], no leading/trailing hyphen.
 const HOSTNAME_RE = /^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?(\.[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?)+$/;
+/** The part of a declared name that must be a valid hostname: a `*.suffix`
+ *  wildcard is checked by its suffix, so `*.example.com` passes but `*.com`
+ *  (single-label, too broad) and `*` do not. Keeps the `.internal` checks
+ *  honest too — `*.foo.internal` reduces to `foo.internal`. */
+function hostPatternBody(lowercased) {
+    return isWildcardHost(lowercased) ? lowercased.slice(2) : lowercased;
+}
 /**
  * Define a fake. `defineFake({ ... })` is a thin wrapper that pins the
  * generic `S` and `H` so `helpers`/`handler` see the inferred state type

package/dist/ingress.d.ts

@@ -38,6 +38,11 @@ export declare function isWildcard(hostname: string): boolean;
  * `hostnames`. The daemon binds it on the HTTPS ingress (:443, SNI per
  * hostname). Pairs with a `proxy(...)` (TLS-terminated reverse proxy) or a
  * fake handler; on its own it just makes those hostnames serve HTTPS.
+ *
+ * A `*.suffix` wildcard is allowed and becomes a wildcard SAN, so one cert
+ * covers a whole domain (`*.us-east-1.amazonaws.com`). As in any TLS
+ * client, a wildcard SAN covers exactly **one** label — `*.example.com`
+ * matches `api.example.com`, not `a.b.example.com`.
  */
 export declare function certificate(hostnames: string[]): CertificateDecl;
 /**
@@ -54,6 +59,12 @@ export declare function dnsName(hostname: string, target: DnsTarget): DnsDecl;
  * Implies the hostname resolves to the daemon ingress, so containers reach
  * it without any extra `dnsName(...)`. Add a `certificate([hostname])` to
  * serve it over HTTPS as well as HTTP.
+ *
+ * `hostname` may be a `*.suffix` wildcard, which sends every name under
+ * that domain to the same upstream — one route for a whole API surface
+ * (`*.us-east-1.amazonaws.com` → a LocalStack container). Exact routes
+ * always win over wildcards, and the longest wildcard suffix wins among
+ * wildcards.
  */
 export declare function proxy(hostname: string, upstream: {
     service: string;

package/dist/ingress.js

@@ -53,13 +53,18 @@ function assertNameOrWildcard(h, ctx) {
  * `hostnames`. The daemon binds it on the HTTPS ingress (:443, SNI per
  * hostname). Pairs with a `proxy(...)` (TLS-terminated reverse proxy) or a
  * fake handler; on its own it just makes those hostnames serve HTTPS.
+ *
+ * A `*.suffix` wildcard is allowed and becomes a wildcard SAN, so one cert
+ * covers a whole domain (`*.us-east-1.amazonaws.com`). As in any TLS
+ * client, a wildcard SAN covers exactly **one** label — `*.example.com`
+ * matches `api.example.com`, not `a.b.example.com`.
  */
 export function certificate(hostnames) {
     if (!Array.isArray(hostnames) || hostnames.length === 0) {
         throw new Error("certificate(): at least one hostname is required");
     }
     for (const h of hostnames)
-        assertHostname(h, "certificate()");
+        assertNameOrWildcard(h, "certificate()");
     return { kind: "certificate", hostnames: hostnames.map((h) => h.toLowerCase()) };
 }
 /**
@@ -82,9 +87,15 @@ export function dnsName(hostname, target) {
  * Implies the hostname resolves to the daemon ingress, so containers reach
  * it without any extra `dnsName(...)`. Add a `certificate([hostname])` to
  * serve it over HTTPS as well as HTTP.
+ *
+ * `hostname` may be a `*.suffix` wildcard, which sends every name under
+ * that domain to the same upstream — one route for a whole API surface
+ * (`*.us-east-1.amazonaws.com` → a LocalStack container). Exact routes
+ * always win over wildcards, and the longest wildcard suffix wins among
+ * wildcards.
  */
 export function proxy(hostname, upstream) {
-    assertHostname(hostname, "proxy()");
+    assertNameOrWildcard(hostname, "proxy()");
     if (!upstream || typeof upstream.service !== "string" || typeof upstream.port !== "number") {
         throw new Error(`proxy(${JSON.stringify(hostname)}): upstream must be { service: string, port: number }`);
     }
@@ -153,8 +164,15 @@ export function lowerIngress(project) {
             case "proxy": {
                 const service = resolveSelf(decl.upstream.service, selfKey);
                 proxies.push({ hostname: decl.hostname, service, port: decl.upstream.port });
-                // A proxied hostname must route to the daemon.
-                ingressSet.add(decl.hostname);
+                // A proxied hostname must route to the daemon. A wildcard one can
+                // only be answered by the resolver (there is no `--add-host` for a
+                // pattern), so it goes in the wildcard table pointed at the ingress.
+                if (isWildcard(decl.hostname)) {
+                    wildcards.push({ pattern: decl.hostname, target: { ingress: true } });
+                }
+                else {
+                    ingressSet.add(decl.hostname);
+                }
                 break;
             }
             case "dns": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@specific.dev/spectest",
-  "version": "0.32.1",
+  "version": "0.34.0",
   "description": "Spectest SDK for defining test environments in TypeScript.",
   "type": "module",
   "main": "./dist/index.js",