@specific.dev/spectest 0.115.1 → 0.116.1

package/src/harness/sticky-image-retention.test.ts

@@ -0,0 +1,59 @@
+import { expect, test } from "bun:test";
+import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { recordStickyImageUse } from "./sticky-image-retention";
+import { collectStickyCache, STICKY_COMPATIBILITY } from "./sticky-consumer";
+
+test("publication records container use before removal and carries it into the next generation", async () => {
+  const root = await mkdtemp(join(tmpdir(), "sticky-image-use-"));
+  try {
+    const now = Date.UTC(2026, 9, 13), GiB = 1024 ** 3;
+    const path = `${root}/.spectest-image-use.json`;
+    await writeFile(path, JSON.stringify({ schema: 1, images: {
+      postgres: now - 10 * 86400_000, unused: now - 9 * 86400_000, gone: now,
+    } }));
+    let containers = true;
+    const calls: string[][] = [];
+    const run = async (command: string, args: string[]) => {
+      calls.push([command, ...args]);
+      if (command === "docker" && args[0] === "image" && args[1] === "ls") return "postgres\nnew\nunused\npostgres";
+      if (command === "docker" && args[0] === "ps") return containers ? "db-container" : "";
+      if (command === "docker" && args[0] === "container" && args[1] === "inspect") return "postgres";
+      return "";
+    };
+    const first = await recordStickyImageUse(root, run, now);
+    expect(first.containers).toEqual(["db-container"]);
+    expect(first.protectedImages).toEqual(new Set(["postgres"]));
+    expect(JSON.parse(await readFile(path, "utf8"))).toEqual({ schema: 1,
+      images: { postgres: now, new: now, unused: now - 9 * 86400_000 } });
+    containers = false; // Publication removes the containers after recording use.
+    await collectStickyCache({ path: "/var/lib/spectest-sticky", capacityBytes: 256 * GiB,
+      headroomBytes: 32 * GiB,
+      compatibility: STICKY_COMPATIBILITY }, first, run,
+    async () => ({ totalBytes: 256 * GiB, freeBytes: 200 * GiB }));
+    expect(calls.filter(c => c[0] === "docker" && c[2] === "rm"))
+      .toEqual([["docker", "image", "rm", "-f", "unused"]]);
+    expect(calls.some(c => c.includes("until=168h"))).toBe(false);
+    const next = await recordStickyImageUse(root, run, now + 86400_000);
+    expect(next.images.find(image => image.id === "postgres")?.lastUsed).toBe(now);
+    expect(next.protectedImages.size).toBe(0);
+  } finally { await rm(root, { recursive: true, force: true }); }
+});
+
+test("legacy generations give unknown images a first observation instead of inferring publisher age", async () => {
+  const root = await mkdtemp(join(tmpdir(), "sticky-image-use-"));
+  try {
+    const state = await recordStickyImageUse(root, async (_, args) => args[1] === "ls" ? "old-published-image" : "", 1234);
+    expect(state.images).toEqual([{ id: "old-published-image", lastUsed: 1234 }]);
+  } finally { await rm(root, { recursive: true, force: true }); }
+});
+
+test("invalid image-use history fails publication rather than treating every image as expired", async () => {
+  const root = await mkdtemp(join(tmpdir(), "sticky-image-use-"));
+  try {
+    await writeFile(`${root}/.spectest-image-use.json`, JSON.stringify({ schema: 1, images: { postgres: "yesterday" } }));
+    await expect(recordStickyImageUse(root, async () => { throw new Error("must not reach Docker"); }))
+      .rejects.toThrow("invalid sticky image-use ledger");
+  } finally { await rm(root, { recursive: true, force: true }); }
+});

package/src/harness/sticky-image-retention.ts

@@ -0,0 +1,43 @@
+/** Image use belongs to the cache lineage, not the publisher's image clock. */
+import { randomUUID } from "node:crypto";
+import { readFile, rename, writeFile } from "node:fs/promises";
+import type { CacheCommand } from "./sticky-kubernetes.js";
+
+export interface StickyImageRetention {
+  images: { id: string; lastUsed: number }[];
+  protectedImages: Set<string>;
+  containers: string[];
+  observedAt: number;
+}
+
+/** Call before removing containers from the isolated publication clone.
+ * New/legacy images get a first observation; inherited unused images retain
+ * their previous timestamp. Rewriting from the inventory drops stale IDs.
+ */
+export async function recordStickyImageUse(
+  root: string, run: CacheCommand, now = Date.now(),
+): Promise<StickyImageRetention> {
+  const path = `${root}/.spectest-image-use.json`;
+  const saved = await readFile(path, "utf8").catch((error: NodeJS.ErrnoException) => {
+    if (error.code === "ENOENT") return undefined;
+    throw error;
+  });
+  const previous = saved === undefined ? { schema: 1, images: {} } : JSON.parse(saved);
+  if (previous.schema !== 1 || !previous.images || typeof previous.images !== "object" ||
+      Array.isArray(previous.images) || Object.values(previous.images).some(value =>
+        typeof value !== "number" || !Number.isSafeInteger(value) || value < 0)) {
+    throw new Error("invalid sticky image-use ledger");
+  }
+  const ids = [...new Set((await run("docker", ["image", "ls", "-aq", "--no-trunc"]))
+    .split(/\s+/).filter(Boolean))];
+  const containers = (await run("docker", ["ps", "-aq"])).split(/\s+/).filter(Boolean);
+  const protectedImages = new Set(containers.length
+    ? (await run("docker", ["container", "inspect", "--format", "{{.Image}}", ...containers]))
+      .split(/\s+/).filter(Boolean) : []);
+  const images = ids.map(id => ({ id, lastUsed: protectedImages.has(id) ? now : previous.images[id] ?? now }));
+  const temporary = `${path}.${randomUUID()}.tmp`;
+  await writeFile(temporary, JSON.stringify({ schema: 1,
+    images: Object.fromEntries(images.map(({ id, lastUsed }) => [id, lastUsed])) }));
+  await rename(temporary, path);
+  return { images, protectedImages, containers, observedAt: now };
+}

package/src/index.ts

@@ -1,3 +1,5 @@
+import type { InjectRule, SignConfig } from "./fake-upstream.js";
+export type { InjectRule, InjectMatch, StringMatch, SignConfig, AwsSigV4Sign } from "./fake-upstream.js";
 export type { Phone, PhoneOptions, CallOptions, SpeechOptions } from "./phone.js";
 import type { Phone, PhoneOptions } from "./phone.js";
 import type { Android, AndroidApp } from "./android.js";
@@ -2140,6 +2142,15 @@ export interface TestSuite<
 // Fakes — in-daemon HTTP servers that masquerade as external APIs.
 // ──────────────────────────────────────────────────────────────────────────
 
+/** Forward the entire fake to real HTTPS/WSS upstreams in interactive environments.
+ * Tests and shared baselines always use the scripted handlers. No traffic is recorded. */
+export interface FakeLiveOptions {
+  /** Same header injection rules as replayFake, applied to HTTP and WebSocket handshakes. */
+  inject?: InjectRule[];
+  /** Re-sign HTTP requests using brokered AWS credentials. Not supported for WebSockets. */
+  sign?: SignConfig;
+}
+
 /**
  * A fake server hosted in the harness. Use this to stand in for
  * external HTTP APIs (auth providers, payment gateways, …) that you can't
@@ -2177,6 +2188,10 @@ export interface FakeDefinition<
    * other fakes.
    */
   hostnames: readonly string[];
+  /** Opt in to forwarding all HTTP/WebSocket traffic to the declared real hosts
+   * over HTTPS/WSS (port 443) in interactive environments. Errors never fall back
+   * to scripted handlers. Omit to keep the fake scripted in every environment. */
+  live?: FakeLiveOptions;
   /** TCP port the fake listens on. Default `80`. */
   port?: number;
   /** Preserve handler/interceptor CORS policy by default. "permissive"
@@ -2231,7 +2246,7 @@ export interface FakeDefinition<
    */
   helpers?: (args: { name: string; state: S; ctx: FakeContext }) => H | Promise<H>;
   /**
-   * Internal. Platform secret references this fake needs at *record* time
+   * Internal. Platform secret references this fake needs for upstream access
    * (set by {@link replayFake}). The daemon reports the union of these to
    * the control plane, which resolves each via its `SecretResolver` and
    * supplies them for the environment lifetime, including snapshots. Values
@@ -2270,6 +2285,9 @@ export function defineFake<
       );
     }
   }
+  if (opts.live !== undefined && (!opts.live || typeof opts.live !== "object" || Array.isArray(opts.live))) {
+    throw new Error(`defineFake(${opts.name}): \`live\` must be an options object`);
+  }
   validateCorsMode(opts.cors);
   if (typeof opts.handler !== "function") {
     throw new Error(`defineFake(${opts.name}): \`handler\` is required`);

package/src/record-secrets.ts

@@ -1,9 +1,9 @@
-// Environment-lifetime credentials for record-mode fakes. The control plane
+// Environment-lifetime credentials for live and record-mode fakes. The control plane
 // resolves declared references from the owning project's Secrets store before
 // service startup and refreshes them on warm starts and interactive forks.
 // They persist across evals, background requests and memory snapshots, just
 // like other environment state. Test forks inherit their parent's credentials;
-// replay mode still uses cassettes and never forwards upstream.
+// test mode still uses scripted handlers or cassettes and never forwards upstream.
 // Values stay out of project files, config hashes and recorded cassettes.
 
 const SECRETS = new Map<string, string>();
@@ -14,7 +14,7 @@ export function setRecordSecrets(secrets: Record<string, string>): void {
   for (const [ref, value] of Object.entries(secrets)) SECRETS.set(ref, value);
 }
 
-/** Resolve a declared project secret for an outbound recording request. */
+/** Resolve a declared project secret for an outbound live or recording request. */
 export function getRecordSecret(ref: string): string | undefined {
   return SECRETS.get(ref);
 }

package/src/replay-mode.ts

@@ -1,6 +1,6 @@
 // Environment state: travels with memory snapshots, independently of the
-// per-case event recorder. Shared/warm baselines must never record upstream.
-// The control plane enables recording only on an interactive environment,
+// per-case event recorder. Shared/warm baselines must never forward upstream.
+// The control plane enables upstream access only on an interactive environment,
 // after capturing/restoring the shared baseline and before interactive setup.
 let mode: "test" | "interactive" = "test";
 
@@ -12,3 +12,8 @@ export function resolveReplayMode(requested: "auto" | "record" | "replay" = "aut
   // Even an explicit record option cannot send test traffic to real providers.
   return mode === "test" || requested === "replay" ? "replay" : "record";
 }
+
+/** Shared gate for live and replay fakes. Credentials never enable upstream access. */
+export function isInteractiveEnvironment(): boolean {
+  return mode === "interactive";
+}