@specific.dev/spectest 0.32.0 → 0.33.0

package/dist/browser.js

@@ -32,7 +32,7 @@ import { readFileSync } from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { generateId } from "./ids.js";
-import { recordBrowser, reserveEvent, truncateUtf8 } from "./recorder.js";
+import { recordBrowser, reserveBackdated, reserveEvent, truncateUtf8 } from "./recorder.js";
 import { wrap } from "./inspect.js";
 import { describeUrlPattern, matchesUrl } from "./url-match.js";
 import { attachBrowserProbe, DEFAULT_ACTION_TIMEOUT_MS, desktopStrategy, makeLocator, mobileStrategy, } from "./locator.js";
@@ -1407,7 +1407,9 @@ function buildBackend(holder, recorder, buildOpts) {
             // No page work — the matcher already read the value via silentRead. We
             // only mint the timeline anchor: the seq the assertion nests under, plus
             // `sessionTimestamp` (post-settle wall clock) so the dashboard seeks the
-            // replay to the frame the assertion observed.
+            // replay to the frame the assertion observed. The offset is backdated to
+            // where the matcher started polling, since that's what `tOffsetMs` means
+            // everywhere else (the ops that reserve up front stamp their start).
             const endT = Date.now();
             const seq = recordBrowser({
                 action,
@@ -1417,7 +1419,7 @@ function buildBackend(holder, recorder, buildOpts) {
                     : {}),
                 durationMs: waitedMs,
                 ...(error ? { error } : {}),
-            });
+            }, reserveBackdated(waitedMs));
             // Drain the rrweb the page buffered while the matcher waited into this
             // step's chunk, so `settledTarget` has bounds to seek into.
             await drain(action);

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/dist/recorder.d.ts

@@ -5,8 +5,11 @@ interface BaseEvent {
      *  before it does still sorts ahead of them. Ops that don't reserve get
      *  their seq at record (= finish) time. */
     seq: number;
-    /** Milliseconds since the recorder started, captured when the op began
-     *  (reserved) or, absent a reservation, when it was recorded. */
+    /** Milliseconds since the recorder started, captured when the op *began* —
+     *  either reserved up front, or backdated at record time by an op that could
+     *  only reserve at finish (`reserveBackdated`). Consumers read the step's
+     *  completion time as `tOffsetMs + durationMs`, so an op that stamps a bare
+     *  finish offset while also reporting a duration will render late. */
     tOffsetMs: number;
     /**
      * Optional grouping pointer. When set, this event was emitted inside
@@ -475,6 +478,14 @@ export declare function isRecording(): boolean;
  *  when nothing is recording, in which case `record*` falls back to allocating
  *  the seq at record time. */
 export declare function reserveEvent(): EventReservation | undefined;
+/** Reserve at op *finish* but backdate the offset by `elapsedMs` — for ops that
+ *  can't reserve up front because they only know they were an op once they're
+ *  done (the locator matchers: they poll silently and emit one settled step at
+ *  the end). Keeps `tOffsetMs` meaning "when the op started" for every kind,
+ *  which is what lets the dashboard render `tOffsetMs + durationMs` as the
+ *  step's completion time. Ordering is unaffected — the caller records
+ *  immediately, so the seq is the one it would have got anyway. */
+export declare function reserveBackdated(elapsedMs: number): EventReservation | undefined;
 export declare function recordExec(ev: Omit<ExecEvent, "seq" | "tOffsetMs" | "kind">, reservation?: EventReservation): number | undefined;
 export declare function recordAssertion(ev: Omit<AssertionEvent, "seq" | "tOffsetMs" | "kind">): number | undefined;
 export declare function recordHttp(ev: Omit<HttpEvent, "seq" | "tOffsetMs" | "kind">, reservation?: EventReservation): number | undefined;

package/dist/recorder.js

@@ -132,6 +132,19 @@ export function isRecording() {
 export function reserveEvent() {
     return active() ? current.reserve() : undefined;
 }
+/** Reserve at op *finish* but backdate the offset by `elapsedMs` — for ops that
+ *  can't reserve up front because they only know they were an op once they're
+ *  done (the locator matchers: they poll silently and emit one settled step at
+ *  the end). Keeps `tOffsetMs` meaning "when the op started" for every kind,
+ *  which is what lets the dashboard render `tOffsetMs + durationMs` as the
+ *  step's completion time. Ordering is unaffected — the caller records
+ *  immediately, so the seq is the one it would have got anyway. */
+export function reserveBackdated(elapsedMs) {
+    const resv = reserveEvent();
+    if (!resv)
+        return undefined;
+    return { seq: resv.seq, tOffsetMs: Math.max(0, resv.tOffsetMs - Math.max(0, elapsedMs)) };
+}
 export function recordExec(ev, reservation) {
     return active() ? current.push({ kind: "exec", ...ev }, reservation) : undefined;
 }

package/package.json

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