@specific.dev/spectest 0.89.1 → 0.90.0

package/src/harness/sticky-consumer.ts

@@ -0,0 +1,176 @@
+/** 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";
+export interface StickyConsumerConfig {
+  path: string;
+  capacityBytes: number;
+  headroomBytes: number;
+  cacheTargetBytes: number;
+  buildkitTargetBytes: number;
+  compatibility: string;
+}
+
+function exec(program: string, args: string[], timeout = 60_000): Promise<string> {
+  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: string, args: string[]): Promise<void> {
+  const deadline = Date.now() + 30_000;
+  let last: unknown;
+  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: StickyConsumerConfig): void {
+  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: StickyConsumerConfig): Promise<void> {
+  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: string, program: string, args: string[]) => {
+    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: StickyConsumerConfig,
+  run: typeof exec = exec,
+  usage = async (): Promise<{ freeBytes: number; totalBytes: number }> => {
+    const fs = await statfs(config.path);
+    return { freeBytes: fs.bavail * fs.bsize, totalBytes: fs.blocks * fs.bsize };
+  },
+): Promise<void> {
+  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: { freeBytes: number; totalBytes: number }) =>
+    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: { Id: string; Created: string }[] = 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): Promise<{ prepared: true; freeBytes: number }> {
+  const config: StickyConsumerConfig = 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/src/harness/sticky-maintenance.ts

@@ -0,0 +1,7 @@
+// 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/src/index.ts

@@ -1,3 +1,5 @@
+import type { Android, AndroidApp } from "./android.js";
+export type { Android, AndroidApp, AndroidElement, AndroidRecordingOptions } from "./android.js";
 // Spectest SDK. The user's single `spectest/index.ts` calls
 // `defineEnvironment({ name, services })` once, defines test cases via
 // the returned `env.test(...)`, and default-exports `env.project([...])`.
@@ -1967,6 +1969,8 @@ export interface TestContext<
    * 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/src/recorder.ts

@@ -632,7 +632,7 @@ export interface EventReservation {
 class Recorder {
   private events: TestEvent[] = [];
   private seq = 0;
-  private readonly start = Date.now();
+  constructor(private readonly start = Date.now()) {}
 
   /** Claim a seq + start offset now; pass the result to `push` at finish. */
   reserve(): EventReservation {
@@ -753,8 +753,8 @@ function active(): boolean {
   return current !== null && paused === 0 && scopeAllowsRecording();
 }
 
-export function startRecording(): void {
-  current = new Recorder();
+export function startRecording(startedAt = Date.now()): void {
+  current = new Recorder(startedAt);
   paused = 0;
 }