@specific.dev/spectest 0.89.0 → 0.90.0

package/dist/harness/sticky-consumer.js

@@ -0,0 +1,178 @@
+/** Docker/BuildKit policy for the generic sticky disk. No host publication API. */
+import { execFile } from "node:child_process";
+import { mkdir, readFile, statfs, writeFile } from "node:fs/promises";
+export const STICKY_CAPABILITY = "sticky-disks-v1";
+export const STICKY_COMPATIBILITY = "docker29-ctr21-buildkit032-overlayfs-256g-v2";
+export const STICKY_RUNTIME = "/run/spectest-sticky";
+function exec(program, args, timeout = 60_000) {
+    return new Promise((resolve, reject) => {
+        execFile(program, args, { timeout, maxBuffer: 8 * 1024 * 1024 }, (error, stdout, stderr) => {
+            if (error)
+                reject(new Error(`${program} failed: ${stderr || stdout || error.message}`));
+            else
+                resolve(stdout.trim());
+        });
+    });
+}
+async function ready(program, args) {
+    const deadline = Date.now() + 30_000;
+    let last;
+    do {
+        try {
+            await exec(program, args, 2000);
+            return;
+        }
+        catch (error) {
+            last = error;
+        }
+        await Bun.sleep(100);
+    } while (Date.now() < deadline);
+    throw last;
+}
+export function validateStickyConfig(config) {
+    if (config.path !== "/var/lib/spectest-sticky" || config.compatibility !== STICKY_COMPATIBILITY ||
+        !Number.isSafeInteger(config.capacityBytes) || config.capacityBytes <= 0 ||
+        !Number.isSafeInteger(config.headroomBytes) || config.headroomBytes < 16 * 1024 * 1024 ||
+        !Number.isSafeInteger(config.cacheTargetBytes) || config.cacheTargetBytes <= 0 ||
+        !Number.isSafeInteger(config.buildkitTargetBytes) || config.buildkitTargetBytes <= 0 ||
+        config.buildkitTargetBytes > config.cacheTargetBytes ||
+        config.cacheTargetBytes + config.headroomBytes >= config.capacityBytes) {
+        throw new Error("unsupported sticky consumer profile or budget");
+    }
+}
+export async function initializeStickyConsumer(config) {
+    validateStickyConfig(config);
+    await exec("mountpoint", ["-q", config.path]);
+    // The base must have stopped these before its RAM was captured. Refuse an
+    // unexpected writer rather than racing it for the standard daemon sockets.
+    for (const unit of ["docker.service", "docker.socket", "containerd.service"]) {
+        const state = await exec("systemctl", ["show", unit, "-p", "ActiveState", "--value"]);
+        if (!["inactive", "failed"].includes(state))
+            throw new Error(`sticky base has active legacy consumer: ${unit}: ${state}`);
+    }
+    for (const [program, version] of [["dockerd", "29.7.2"], ["containerd", "v2.1.5"], ["buildkitd", "v0.32.2"]]) {
+        if (!(await exec(program, ["--version"])).includes(version))
+            throw new Error(`unsupported ${program} version for sticky profile`);
+    }
+    await mkdir(STICKY_RUNTIME, { recursive: true });
+    for (const child of ["docker", "containerd", "buildkit"])
+        await mkdir(`${config.path}/${child}`, { recursive: true });
+    await writeFile(`${STICKY_RUNTIME}/consumer.json`, JSON.stringify(config));
+    await writeFile(`${STICKY_RUNTIME}/containerd.toml`, `version = 2
+root = "${config.path}/containerd"
+state = "/run/containerd"
+disabled_plugins = ["io.containerd.grpc.v1.cri"]
+[grpc]
+  address = "/run/containerd/containerd.sock"
+`);
+    const dockerConfig = JSON.parse(await readFile("/etc/docker/daemon.json", "utf8"));
+    dockerConfig["data-root"] = `${config.path}/docker`;
+    dockerConfig.features = { "containerd-snapshotter": true };
+    dockerConfig["storage-driver"] = "overlayfs";
+    await writeFile(`${STICKY_RUNTIME}/docker.json`, JSON.stringify(dockerConfig));
+    await writeFile(`${STICKY_RUNTIME}/buildkit.toml`, `root = "${config.path}/buildkit"
+[grpc]
+  address = ["tcp://127.0.0.1:1234"]
+[worker.oci]
+  enabled = false
+[worker.containerd]
+  enabled = true
+  address = "/run/containerd/containerd.sock"
+  namespace = "moby"
+  snapshotter = "overlayfs"
+  gc = true
+  reservedSpace = "1GB"
+  maxUsedSpace = ${config.buildkitTargetBytes}
+  minFreeSpace = ${config.headroomBytes}
+`);
+    const start = async (unit, program, args) => {
+        await exec("systemd-run", ["--quiet", "--unit", unit, "-p", "TimeoutStopSec=30",
+            // Pinned BuildKit 0.32.2 returns 1 after its normal first-SIGTERM
+            // shutdown (util/appcontext). A timeout/signal still fails the unit.
+            ...(unit === "spectest-sticky-buildkit" ? ["-p", "SuccessExitStatus=1"] : []),
+            program, ...args]);
+    };
+    await start("spectest-sticky-containerd", "containerd", ["--config", `${STICKY_RUNTIME}/containerd.toml`]);
+    await ready("ctr", ["version"]);
+    await start("spectest-sticky-docker", "dockerd", ["--config-file", `${STICKY_RUNTIME}/docker.json`,
+        "--host", "unix:///run/docker.sock", "--exec-root", "/run/docker", "--pidfile", "/run/docker.pid",
+        "--containerd", "/run/containerd/containerd.sock", "--containerd-namespace", "moby"]);
+    await ready("docker", ["info"]);
+    await start("spectest-sticky-buildkit", "buildkitd", ["--config", `${STICKY_RUNTIME}/buildkit.toml`]);
+    await ready("buildctl", ["--addr", "tcp://127.0.0.1:1234", "debug", "workers"]);
+    await exec("docker", ["buildx", "create", "--name", "spectest-local", "--driver", "remote", "tcp://127.0.0.1:1234"]);
+    await exec("docker", ["buildx", "inspect", "--bootstrap", "spectest-local"]);
+}
+/** Filesystem pressure takes precedence over cache age/BuildKit record sizes.
+ * Only called after runtime containers/volumes have been removed on the
+ * isolated publication clone. Never removes files behind the daemons' backs.
+ */
+export async function collectStickyCache(config, run = exec, usage = async () => {
+    const fs = await statfs(config.path);
+    return { freeBytes: fs.bavail * fs.bsize, totalBytes: fs.blocks * fs.bsize };
+}) {
+    validateStickyConfig(config);
+    const buildctl = ["--addr", "tcp://127.0.0.1:1234", "prune"];
+    await run("buildctl", [...buildctl, "--keep-duration", "168h"], 120_000);
+    await run("docker", ["image", "prune", "-af", "--filter", "until=168h"], 120_000);
+    const withinTarget = (fs) => fs.freeBytes >= config.headroomBytes && fs.totalBytes - fs.freeBytes <= config.cacheTargetBytes;
+    let fs = await usage();
+    // Always enforce the independent BuildKit target. Its accounting alone
+    // cannot bound shared images/content, so also request real filesystem space.
+    const pruneBuildkit = async () => {
+        await run("buildctl", [...buildctl, "--all", "--keep-storage",
+            String(Math.floor(config.buildkitTargetBytes / 1e6)), "--free-storage",
+            String(Math.ceil(Math.max(config.headroomBytes, fs.totalBytes - config.cacheTargetBytes) / 1e6))], 120_000);
+        fs = await usage();
+    };
+    await pruneBuildkit();
+    if (withinTarget(fs))
+        return;
+    // Pressure can be entirely in recent Docker images. Drop oldest images
+    // first, even within the age window, until the whole filesystem fits.
+    const ids = [...new Set((await run("docker", ["image", "ls", "-aq", "--no-trunc"])).split(/\s+/).filter(Boolean))];
+    const images = ids.length
+        ? JSON.parse(await run("docker", ["image", "inspect", ...ids])) : [];
+    images.sort((a, b) => a.Created.localeCompare(b.Created) || a.Id.localeCompare(b.Id));
+    for (const image of images) {
+        await run("docker", ["image", "rm", "-f", image.Id], 120_000);
+        await pruneBuildkit();
+        if (withinTarget(fs))
+            return;
+    }
+    // Containerd GC may lag reference removal; allow bounded additional passes.
+    for (let pass = 0; pass < 3 && !withinTarget(fs); pass++)
+        await pruneBuildkit();
+    if (!withinTarget(fs))
+        throw new Error("sticky cache cannot meet filesystem retention target and write headroom");
+}
+/** Only on an isolated maintenance clone; never on the live ready environment. */
+export async function prepareStickyConsumer(artifact = false) {
+    const config = JSON.parse(await readFile(`${STICKY_RUNTIME}/consumer.json`, "utf8"));
+    validateStickyConfig(config);
+    if (!artifact) {
+        const containers = (await exec("docker", ["ps", "-aq"])).split(/\s+/).filter(Boolean);
+        if (containers.length)
+            await exec("docker", ["rm", "-f", ...containers]);
+        const volumes = (await exec("docker", ["volume", "ls", "-q"])).split(/\s+/).filter(Boolean);
+        if (volumes.length)
+            await exec("docker", ["volume", "rm", ...volumes]);
+        await collectStickyCache(config);
+    }
+    const units = ["spectest-sticky-buildkit", "spectest-sticky-docker", "spectest-sticky-containerd"];
+    for (const unit of units) {
+        const active = await exec("systemctl", ["show", unit, "-p", "ActiveState", "--value"]);
+        if (active !== "active")
+            throw new Error(`consumer exited before sealing: ${unit}: ${active}`);
+        await exec("systemctl", ["stop", unit], 45_000);
+        const result = await exec("systemctl", ["show", unit, "-p", "Result", "--value"]);
+        if (result !== "success")
+            throw new Error(`unclean consumer shutdown: ${unit}: ${result}`);
+    }
+    const fs = await statfs(config.path);
+    const freeBytes = fs.bavail * fs.bsize;
+    if (freeBytes < config.headroomBytes)
+        throw new Error("sticky publication has insufficient write headroom");
+    // The supervisor verifies and unmounts; only the worker seals/publishes.
+    return { prepared: true, freeBytes };
+}

package/dist/harness/sticky-maintenance.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/harness/sticky-maintenance.js

@@ -0,0 +1,11 @@
+// Dedicated entry point: no daemon.ts, project modules, bootstrap or tests.
+import { prepareStickyConsumer } from "./sticky-consumer";
+if (import.meta.main) {
+    try {
+        console.log(JSON.stringify(await prepareStickyConsumer(process.argv.includes("--artifact"))));
+    }
+    catch (error) {
+        console.error(error);
+        process.exitCode = 1;
+    }
+}

package/dist/harness/ws-bridge.d.ts

@@ -0,0 +1,78 @@
+/**
+ * The ingress WebSocket bridge: one client WebSocket on an ingress
+ * listener, one upstream WebSocket to the service, frames copied in both
+ * directions.
+ *
+ * The handshake is the part that matters. A client that sends
+ * `Sec-WebSocket-Protocol: console, <ticket>` expects the upstream to see
+ * the full list, and expects to get back the one the upstream selected.
+ * The first version of this bridge opened the upstream with no protocols
+ * and no headers, so a ticket or a cookie that rode on the handshake never
+ * reached the service, and the service refused the connection after the
+ * client already saw a 101. So the bridge now opens the upstream FIRST,
+ * with the client's protocol list and forwardable headers, waits for the
+ * upstream handshake, and only then upgrades the client with the protocol
+ * the upstream selected. An upstream that refuses the handshake becomes a
+ * 502 to the client, the same as the HTTP proxy path.
+ *
+ * `daemon.ts` owns the listener and the route lookup; this module owns
+ * the handshake and the frame relay so the two can be tested on loopback
+ * without a VM.
+ */
+/** Per-bridge context stored on `ws.data` of the client socket. */
+export interface WsBridgeData {
+    upstreamUrl: string;
+    /** Open by the time the client socket exists: the handshake awaited it. */
+    upstream: WebSocket;
+}
+/** `Sec-WebSocket-Protocol` is a comma-separated list; each token is
+ *  trimmed, empty tokens are dropped, order is kept (RFC 6455 §4.1 lets
+ *  the server pick from the list, so order is the client's preference). */
+export declare function parseSubprotocols(header: string | null | undefined): string[];
+/**
+ * The headers the upstream handshake carries: everything forwardable from
+ * the client's request (cookies, authorization, origin, user-agent …),
+ * minus the client's own handshake fields, plus the proxy provenance
+ * headers and a Host that names the service.
+ */
+export declare function upstreamHandshakeHeaders(req: Headers, opts: {
+    service: string;
+    port: number;
+    proto: string;
+    clientIp?: string;
+}): Record<string, string>;
+export type UpstreamOpen = {
+    ok: true;
+    socket: WebSocket;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * Open the upstream WebSocket and wait for its handshake. Resolves once
+ * the socket is open, or once it failed; the handshake listeners are
+ * removed either way so a later close does not fire them again.
+ */
+export declare function openUpstreamWebSocket(url: string, opts: {
+    protocols: string[];
+    headers: Record<string, string>;
+    timeoutMs?: number;
+}): Promise<UpstreamOpen>;
+/** The minimum of Bun's ServerWebSocket that the relay uses. */
+interface ClientSocket {
+    data: WsBridgeData;
+    send(data: string | ArrayBuffer | Uint8Array): unknown;
+    close(code?: number, reason?: string): unknown;
+}
+/**
+ * The `websocket` handler set for `Bun.serve`. The upstream is already
+ * open when `open()` runs, so frames go straight through in both
+ * directions, and a close on either side closes the other with the same
+ * code and reason.
+ */
+export declare const WS_BRIDGE_HANDLERS: {
+    open(ws: ClientSocket): void;
+    message(ws: ClientSocket, message: string | Buffer): void;
+    close(ws: ClientSocket, code: number, reason: string): void;
+};
+export {};

package/dist/harness/ws-bridge.js

@@ -0,0 +1,180 @@
+/**
+ * The ingress WebSocket bridge: one client WebSocket on an ingress
+ * listener, one upstream WebSocket to the service, frames copied in both
+ * directions.
+ *
+ * The handshake is the part that matters. A client that sends
+ * `Sec-WebSocket-Protocol: console, <ticket>` expects the upstream to see
+ * the full list, and expects to get back the one the upstream selected.
+ * The first version of this bridge opened the upstream with no protocols
+ * and no headers, so a ticket or a cookie that rode on the handshake never
+ * reached the service, and the service refused the connection after the
+ * client already saw a 101. So the bridge now opens the upstream FIRST,
+ * with the client's protocol list and forwardable headers, waits for the
+ * upstream handshake, and only then upgrades the client with the protocol
+ * the upstream selected. An upstream that refuses the handshake becomes a
+ * 502 to the client, the same as the HTTP proxy path.
+ *
+ * `daemon.ts` owns the listener and the route lookup; this module owns
+ * the handshake and the frame relay so the two can be tested on loopback
+ * without a VM.
+ */
+import { forwardableHeaders } from "./http-proxy.js";
+/** Headers that belong to the client's own WebSocket handshake. Bun's
+ *  WebSocket client mints its own key and version, and the protocol list
+ *  goes through the constructor option, so these never travel as plain
+ *  headers. */
+const HANDSHAKE_HEADERS = new Set([
+    "sec-websocket-key",
+    "sec-websocket-version",
+    "sec-websocket-protocol",
+    "sec-websocket-extensions",
+    "sec-websocket-accept",
+]);
+/** `Sec-WebSocket-Protocol` is a comma-separated list; each token is
+ *  trimmed, empty tokens are dropped, order is kept (RFC 6455 §4.1 lets
+ *  the server pick from the list, so order is the client's preference). */
+export function parseSubprotocols(header) {
+    if (!header)
+        return [];
+    return header
+        .split(",")
+        .map((s) => s.trim())
+        .filter((s) => s.length > 0);
+}
+/**
+ * The headers the upstream handshake carries: everything forwardable from
+ * the client's request (cookies, authorization, origin, user-agent …),
+ * minus the client's own handshake fields, plus the proxy provenance
+ * headers and a Host that names the service.
+ */
+export function upstreamHandshakeHeaders(req, opts) {
+    const out = {};
+    forwardableHeaders(req).forEach((value, key) => {
+        if (HANDSHAKE_HEADERS.has(key))
+            return;
+        out[key] = value;
+    });
+    const priorXff = req.get("x-forwarded-for");
+    const xff = opts.clientIp
+        ? priorXff
+            ? `${priorXff}, ${opts.clientIp}`
+            : opts.clientIp
+        : priorXff;
+    if (xff)
+        out["x-forwarded-for"] = xff;
+    out["x-forwarded-proto"] = opts.proto;
+    const publicHost = req.get("host");
+    if (publicHost)
+        out["x-forwarded-host"] = publicHost;
+    out["host"] = `${opts.service}:${opts.port}`;
+    return out;
+}
+/**
+ * Open the upstream WebSocket and wait for its handshake. Resolves once
+ * the socket is open, or once it failed; the handshake listeners are
+ * removed either way so a later close does not fire them again.
+ */
+export function openUpstreamWebSocket(url, opts) {
+    const Ctor = WebSocket;
+    let socket;
+    try {
+        socket = new Ctor(url, { protocols: opts.protocols, headers: opts.headers });
+    }
+    catch (err) {
+        return Promise.resolve({ ok: false, reason: String(err) });
+    }
+    // ArrayBuffer so binary frames can be sent to the client verbatim.
+    socket.binaryType = "arraybuffer";
+    return new Promise((resolve) => {
+        let settled = false;
+        const timeoutMs = opts.timeoutMs ?? 30_000;
+        const timer = setTimeout(() => finish({ ok: false, reason: "upstream handshake timed out" }), timeoutMs);
+        const onOpen = () => finish({ ok: true, socket });
+        const onError = (ev) => {
+            const msg = ev.message;
+            finish({ ok: false, reason: msg ? `upstream handshake failed: ${msg}` : "upstream handshake failed" });
+        };
+        const onClose = (ev) => finish({ ok: false, reason: `upstream closed during handshake (${ev.code}${ev.reason ? ` ${ev.reason}` : ""})` });
+        const finish = (result) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            socket.removeEventListener("open", onOpen);
+            socket.removeEventListener("error", onError);
+            socket.removeEventListener("close", onClose);
+            if (!result.ok) {
+                try {
+                    socket.close();
+                }
+                catch {
+                    /* already closed */
+                }
+            }
+            resolve(result);
+        };
+        socket.addEventListener("open", onOpen);
+        socket.addEventListener("error", onError);
+        socket.addEventListener("close", onClose);
+    });
+}
+/**
+ * The `websocket` handler set for `Bun.serve`. The upstream is already
+ * open when `open()` runs, so frames go straight through in both
+ * directions, and a close on either side closes the other with the same
+ * code and reason.
+ */
+export const WS_BRIDGE_HANDLERS = {
+    open(ws) {
+        const { upstream } = ws.data;
+        upstream.addEventListener("message", (ev) => {
+            try {
+                ws.send(ev.data);
+            }
+            catch {
+                /* client gone */
+            }
+        });
+        upstream.addEventListener("close", (ev) => {
+            try {
+                ws.close(ev.code, ev.reason);
+            }
+            catch {
+                /* already closed */
+            }
+        });
+        upstream.addEventListener("error", () => {
+            try {
+                ws.close(1011, "upstream error");
+            }
+            catch {
+                /* already closed */
+            }
+        });
+        // The upstream can have closed between the handshake and this
+        // callback; the close listener above was not attached yet then.
+        if (upstream.readyState !== WebSocket.OPEN) {
+            try {
+                ws.close(1011, "upstream closed");
+            }
+            catch {
+                /* already closed */
+            }
+        }
+    },
+    message(ws, message) {
+        const { upstream } = ws.data;
+        const payload = typeof message === "string" ? message : new Uint8Array(message);
+        if (upstream.readyState === WebSocket.OPEN)
+            upstream.send(payload);
+    },
+    close(ws, code, reason) {
+        try {
+            ws.data.upstream.close(code, reason);
+        }
+        catch {
+            /* ignore */
+        }
+    },
+};

package/dist/index.d.ts

@@ -1,3 +1,5 @@
+import type { Android, AndroidApp } from "./android.js";
+export type { Android, AndroidApp, AndroidElement, AndroidRecordingOptions } from "./android.js";
 import { strict as nodeAssert } from "node:assert";
 export type { Carrier, Wrapped, WrappedObject, WrappedArray, WrappedHeaders, WrappedBuffer, WrappedBinaryView, WrappedBytes, WrappedBlob, WrappedFile, WrappedFormData, WrappedStream, WrappedReader, WrappedBYOBReader, WrappedReadResult, WrappedResponse, Provenanced, SpectestFetch, SpectestRequestInit, Unwrap, } from "./inspect.js";
 import type { Provenanced, SpectestFetch, Wrapped } from "./inspect.js";
@@ -1315,6 +1317,8 @@ export interface TestContext<P = undefined, S extends ServicesMap = ServicesMap,
      * like named desktop browsers.
      */
     mobile(app: MobileApp, name?: string): Promise<Mobile>;
+    /** Native Android via Appium. Recording is automatic for test cases; the app and session survive forks. */
+    android(app: AndroidApp): Promise<Android>;
     /** Drive a real Electron renderer window through locators and user input.
      * Acquires the app started by electron(); keeps its live state across forks.
      * Each test gets a self-contained graphical replay. Selecting another window

package/dist/recorder.d.ts

@@ -564,7 +564,7 @@ export interface EventReservation {
 }
 export declare function pauseRecording(): void;
 export declare function resumeRecording(): void;
-export declare function startRecording(): void;
+export declare function startRecording(startedAt?: number): void;
 export declare function stopRecording(): TestEvent[];
 export declare function isRecording(): boolean;
 /** Reserve an ordering slot at the start of an op so nested events it triggers

package/dist/recorder.js

@@ -11,9 +11,12 @@ import { clearPendingNullish } from "./inspect.js";
 import { scopeAllowsRecording } from "./harness/instrumentation-scope.js";
 const OUTPUT_SNIPPET_BYTES = 256 * 1024;
 class Recorder {
+    start;
     events = [];
     seq = 0;
-    start = Date.now();
+    constructor(start = Date.now()) {
+        this.start = start;
+    }
     /** Claim a seq + start offset now; pass the result to `push` at finish. */
     reserve() {
         return { seq: this.seq++, tOffsetMs: Date.now() - this.start };
@@ -120,8 +123,8 @@ export function resumeRecording() {
 function active() {
     return current !== null && paused === 0 && scopeAllowsRecording();
 }
-export function startRecording() {
-    current = new Recorder();
+export function startRecording(startedAt = Date.now()) {
+    current = new Recorder(startedAt);
     paused = 0;
 }
 export function stopRecording() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@specific.dev/spectest",
-  "version": "0.89.0",
+  "version": "0.90.0",
   "description": "Spectest SDK for defining test environments in TypeScript.",
   "type": "module",
   "main": "./dist/index.js",
@@ -49,7 +49,8 @@
   },
   "publishConfig": {
     "registry": "https://registry.npmjs.org",
-    "access": "public"
+    "access": "public",
+    "tag": "latest"
   },
   "dependencies": {
     "@kubernetes/client-node": "^1.0.0",
@@ -61,5 +62,8 @@
     "@types/dns-packet": "^5.6.5",
     "@types/bun": "^1.3.0",
     "typescript": "^5.6.3"
-  }
+  },
+  "spectestCapabilities": [
+    "sticky-disks-v1"
+  ]
 }