@ai-development-environment/server 0.0.30 → 0.0.32

package/standalone/src/services/builds/artifact-cache.test.ts

@@ -0,0 +1,271 @@
+import {
+  readFile,
+  readdir,
+  rm,
+  stat,
+  utimes,
+  writeFile,
+} from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { afterEach, beforeEach, describe, expect, test, vi } from "vitest";
+
+const getServerServices = vi.fn();
+vi.mock("@/services/server-services", () => ({
+  getServerServices: () => getServerServices(),
+}));
+
+const fsMocks = vi.hoisted(() => ({ rename: vi.fn() }));
+vi.mock("node:fs/promises", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("node:fs/promises")>();
+  fsMocks.rename.mockImplementation(actual.rename);
+  return { ...actual, rename: fsMocks.rename };
+});
+
+import { receiveArtifactTransfer } from "./artifact-transfer";
+
+// Isolated per process so concurrent runs cannot evict each other's entries.
+const CACHE_DIRECTORY = join(
+  tmpdir(),
+  `ade-artifact-cache-test-${process.pid}`,
+);
+process.env.ARTIFACT_CACHE_DIRECTORY = CACHE_DIRECTORY;
+
+type ArtifactRow = {
+  id: string;
+  kind: string;
+  relativePath: string;
+  sizeBytes: number | null;
+  checksum: string | null;
+  createdAt: string;
+  metadata: Record<string, unknown>;
+};
+
+let artifactRow: ArtifactRow;
+let downloads: number;
+let uploadBody: string;
+/** Resolves once prepareArtifactDownload has been entered, per call. */
+let downloadStarted: (() => void)[];
+
+function services() {
+  return {
+    buildsService: {
+      artifactForInstall: vi.fn(async () => artifactRow),
+      getBuild: vi.fn(async () => ({ id: "build-1", agentId: "agent-1" })),
+      prepareArtifactDownload: vi.fn(
+        async (
+          _buildId: string,
+          _artifactId: string,
+          uploadId: string,
+        ): Promise<void> => {
+          downloads += 1;
+          downloadStarted.shift()?.();
+          // Stand in for the agent posting the bytes back to the control plane.
+          await receiveArtifactTransfer(
+            uploadId,
+            "agent-1",
+            new Request("http://control.test/upload", {
+              method: "POST",
+              body: uploadBody,
+              headers: {
+                "content-length": String(uploadBody.length),
+                "content-type": "application/octet-stream",
+                "x-artifact-filename": encodeURIComponent("App.ipa"),
+              },
+            }),
+          );
+        },
+      ),
+    },
+  };
+}
+
+async function importCache() {
+  return import("./artifact-cache");
+}
+
+beforeEach(async () => {
+  vi.resetModules();
+  downloads = 0;
+  downloadStarted = [];
+  uploadBody = "ipa-bytes";
+  artifactRow = {
+    id: "artifact-1",
+    kind: "IPA",
+    relativePath: "exports/export-1/App.ipa",
+    sizeBytes: 9,
+    checksum: "checksum-1",
+    createdAt: "2026-07-19T00:00:00.000Z",
+    metadata: {},
+  };
+  getServerServices.mockImplementation(services);
+  fsMocks.rename.mockClear();
+  await rm(CACHE_DIRECTORY, { recursive: true, force: true });
+});
+
+afterEach(async () => {
+  await rm(CACHE_DIRECTORY, { recursive: true, force: true });
+});
+
+describe("materializeArtifact", () => {
+  test("transfers from the agent on a miss and serves the bytes", async () => {
+    const { materializeArtifact } = await importCache();
+    const artifact = await materializeArtifact("build-1", "artifact-1");
+
+    expect(downloads).toBe(1);
+    expect(artifact).toMatchObject({
+      filename: "App.ipa",
+      contentType: "application/octet-stream",
+      size: 9,
+    });
+    await expect(readFile(artifact.path, "utf8")).resolves.toBe("ipa-bytes");
+  });
+
+  test("copies across filesystems and removes transfer staging files", async () => {
+    fsMocks.rename.mockRejectedValueOnce(
+      Object.assign(new Error("Cross-device link"), { code: "EXDEV" }),
+    );
+    const { materializeArtifact } = await importCache();
+    const artifact = await materializeArtifact("build-1", "artifact-1");
+    const source = String(fsMocks.rename.mock.calls[0]?.[0]);
+
+    await expect(readFile(artifact.path, "utf8")).resolves.toBe("ipa-bytes");
+    await expect(stat(source)).rejects.toThrow();
+    await expect(readdir(CACHE_DIRECTORY)).resolves.not.toContainEqual(
+      expect.stringContaining(".incoming"),
+    );
+  });
+
+  test("serves a second request from cache without contacting the agent", async () => {
+    const { materializeArtifact } = await importCache();
+    const first = await materializeArtifact("build-1", "artifact-1");
+    const second = await materializeArtifact("build-1", "artifact-1");
+
+    expect(downloads).toBe(1);
+    expect(second.path).toBe(first.path);
+    expect(second.etag).toBe(first.etag);
+    await expect(readFile(second.path, "utf8")).resolves.toBe("ipa-bytes");
+  });
+
+  test("collapses concurrent requests into a single transfer", async () => {
+    const { materializeArtifact } = await importCache();
+    const entered = new Promise<void>((resolve) => {
+      downloadStarted.push(resolve);
+    });
+
+    const first = materializeArtifact("build-1", "artifact-1");
+    await entered;
+    const second = materializeArtifact("build-1", "artifact-1");
+    const [left, right] = await Promise.all([first, second]);
+
+    expect(downloads).toBe(1);
+    expect(right.path).toBe(left.path);
+  });
+
+  test("re-transfers when the checksum changes", async () => {
+    const { materializeArtifact } = await importCache();
+    await materializeArtifact("build-1", "artifact-1");
+
+    artifactRow = { ...artifactRow, checksum: "checksum-2" };
+    uploadBody = "new-bytes";
+    artifactRow.sizeBytes = uploadBody.length;
+    const updated = await materializeArtifact("build-1", "artifact-1");
+
+    expect(downloads).toBe(2);
+    await expect(readFile(updated.path, "utf8")).resolves.toBe("new-bytes");
+  });
+
+  test("falls back to createdAt when the artifact has no checksum", async () => {
+    artifactRow = { ...artifactRow, checksum: null };
+    const { materializeArtifact } = await importCache();
+    await materializeArtifact("build-1", "artifact-1");
+    await materializeArtifact("build-1", "artifact-1");
+
+    expect(downloads).toBe(1);
+  });
+
+  test("re-transfers when the cached body no longer matches its sidecar", async () => {
+    const { materializeArtifact } = await importCache();
+    const artifact = await materializeArtifact("build-1", "artifact-1");
+
+    // A truncated body must not be served as if it were complete.
+    await writeFile(artifact.path, "short");
+    await materializeArtifact("build-1", "artifact-1");
+
+    expect(downloads).toBe(2);
+  });
+
+  test("re-transfers when the sidecar is missing", async () => {
+    const { materializeArtifact } = await importCache();
+    const artifact = await materializeArtifact("build-1", "artifact-1");
+
+    await rm(`${artifact.path}.json`, { force: true });
+    await materializeArtifact("build-1", "artifact-1");
+
+    expect(downloads).toBe(2);
+  });
+
+  test("evicts the least recently used entries past the size budget", async () => {
+    process.env.ARTIFACT_CACHE_MAX_BYTES = "12";
+    try {
+      vi.resetModules();
+      const { materializeArtifact } = await importCache();
+      const first = await materializeArtifact("build-1", "artifact-1");
+
+      // Age the first entry so the prune sees it as least recently used.
+      const old = new Date(Date.now() - 60_000);
+      await utimes(first.path, old, old);
+
+      artifactRow = { ...artifactRow, checksum: "checksum-2" };
+      await materializeArtifact("build-1", "artifact-1");
+
+      await expect(stat(first.path)).rejects.toThrow();
+    } finally {
+      delete process.env.ARTIFACT_CACHE_MAX_BYTES;
+    }
+  });
+
+  test("rejects when the artifact does not exist", async () => {
+    getServerServices.mockImplementation(() => ({
+      buildsService: {
+        ...services().buildsService,
+        artifactForInstall: vi.fn(async () => null),
+      },
+    }));
+    const { materializeArtifact } = await importCache();
+    await expect(materializeArtifact("build-1", "missing")).rejects.toThrow(
+      "not found",
+    );
+  });
+
+  test("does not leave a failed transfer in flight", async () => {
+    getServerServices.mockImplementation(() => ({
+      buildsService: {
+        ...services().buildsService,
+        prepareArtifactDownload: vi.fn(async () => {
+          throw new Error("Build agent is offline");
+        }),
+      },
+    }));
+    const { materializeArtifact } = await importCache();
+
+    await expect(materializeArtifact("build-1", "artifact-1")).rejects.toThrow(
+      "offline",
+    );
+    // A retry must be attempted rather than resolving the rejected promise again.
+    await expect(materializeArtifact("build-1", "artifact-1")).rejects.toThrow(
+      "offline",
+    );
+  });
+});
+
+describe("cache directory", () => {
+  test("is created with restrictive permissions", async () => {
+    const { materializeArtifact } = await importCache();
+    await materializeArtifact("build-1", "artifact-1");
+
+    const information = await stat(CACHE_DIRECTORY);
+    expect(information.mode & 0o777).toBe(0o700);
+  });
+});

package/standalone/src/services/builds/artifact-cache.ts

@@ -0,0 +1,272 @@
+import "server-only";
+
+import { createHash, randomUUID } from "node:crypto";
+import {
+  copyFile,
+  mkdir,
+  readdir,
+  readFile,
+  rename,
+  rm,
+  stat,
+  utimes,
+  writeFile,
+} from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import {
+  cancelArtifactTransfer,
+  expectArtifactTransfer,
+} from "./artifact-transfer";
+import { getServerServices } from "@/services/server-services";
+
+export type MaterializedArtifact = {
+  path: string;
+  filename: string;
+  contentType: string;
+  size: number;
+  etag: string;
+};
+
+type Sidecar = {
+  filename: string;
+  contentType: string;
+  size: number;
+};
+
+// Overridable so the cache can be pointed at a volume with room for large
+// packages, rather than whatever the temporary directory happens to allow.
+const CACHE_DIRECTORY =
+  process.env.ARTIFACT_CACHE_DIRECTORY?.trim() ||
+  join(tmpdir(), "ade-build-artifact-cache");
+const MAX_CACHE_BYTES =
+  Number(process.env.ARTIFACT_CACHE_MAX_BYTES) || 5 * 1024 ** 3;
+const MAX_CACHE_AGE_MS = 6 * 60 * 60 * 1_000;
+
+const globalCache = globalThis as typeof globalThis & {
+  buildArtifactMaterializations?: Map<string, Promise<MaterializedArtifact>>;
+};
+const inFlight =
+  globalCache.buildArtifactMaterializations ??
+  (globalCache.buildArtifactMaterializations = new Map());
+
+/**
+ * Transfers are billed against wall-clock time on a link we do not control, so
+ * the ceiling scales with the artifact: two minutes of overhead plus roughly a
+ * second per megabyte, capped so a stalled agent cannot hold a request forever.
+ */
+function transferTimeout(sizeBytes: number | null): number {
+  return Math.min(30 * 60_000, 120_000 + (sizeBytes ?? 0) / 1_000);
+}
+
+/**
+ * Uses an atomic rename when possible. A configured cache volume can live on a
+ * different filesystem from the upload receiver's temporary directory, in
+ * which case the bytes are staged on the cache filesystem before the final
+ * rename.
+ */
+async function moveIntoCache(source: string, destination: string) {
+  try {
+    await rename(source, destination);
+    return;
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "EXDEV") throw error;
+  }
+
+  const staging = `${destination}.${randomUUID()}.incoming`;
+  try {
+    await copyFile(source, staging);
+    await rename(staging, destination);
+    await rm(source, { force: true });
+  } finally {
+    await rm(staging, { force: true }).catch(() => {});
+  }
+}
+
+function cacheKey(artifactId: string, identity: string): string {
+  return createHash("sha1").update(`${artifactId}:${identity}`).digest("hex");
+}
+
+async function readSidecar(path: string): Promise<Sidecar | null> {
+  try {
+    const parsed: unknown = JSON.parse(await readFile(path, "utf8"));
+    if (!parsed || typeof parsed !== "object") return null;
+    const { filename, contentType, size } = parsed as Record<string, unknown>;
+    if (
+      typeof filename !== "string" ||
+      typeof contentType !== "string" ||
+      typeof size !== "number"
+    ) {
+      return null;
+    }
+    return { filename, contentType, size };
+  } catch {
+    return null;
+  }
+}
+
+async function readCached(key: string): Promise<MaterializedArtifact | null> {
+  const path = join(CACHE_DIRECTORY, key);
+  const sidecar = await readSidecar(`${path}.json`);
+  if (!sidecar) return null;
+  try {
+    const information = await stat(path);
+    if (!information.isFile() || information.size !== sidecar.size) return null;
+    const now = new Date();
+    await utimes(path, now, now).catch(() => {});
+    return { path, etag: `"${key}"`, ...sidecar };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Drops the least recently used entries once the cache exceeds its budget, and
+ * anything past the maximum age. Entries are several hundred megabytes each, so
+ * skipping this would fill the temporary directory within a handful of builds.
+ *
+ * `keep` is the entry the caller is about to serve. It is exempt so that an
+ * artifact larger than the whole budget is still returned rather than deleted
+ * out from under the response that just fetched it.
+ */
+async function prune(keep: string): Promise<void> {
+  let entries;
+  try {
+    entries = await readdir(CACHE_DIRECTORY);
+  } catch {
+    return;
+  }
+  const files: {
+    path: string;
+    size: number;
+    mtimeMs: number;
+    keep: boolean;
+  }[] = [];
+  const expired = Date.now() - MAX_CACHE_AGE_MS;
+  for (const entry of entries) {
+    if (entry.endsWith(".json")) continue;
+    const path = join(CACHE_DIRECTORY, entry);
+    try {
+      const information = await stat(path);
+      if (!information.isFile()) continue;
+      // Cross-filesystem moves are copied into these staging files. Ignore an
+      // active copy, but clean up one left behind by a terminated process.
+      if (entry.endsWith(".incoming")) {
+        if (information.mtimeMs < expired) {
+          await rm(path, { force: true }).catch(() => {});
+        }
+        continue;
+      }
+      files.push({
+        path,
+        size: information.size,
+        mtimeMs: information.mtimeMs,
+        keep: entry === keep,
+      });
+    } catch {
+      continue;
+    }
+  }
+  files.sort((left, right) => left.mtimeMs - right.mtimeMs);
+  // The kept entry counts against the budget but is never a deletion candidate.
+  let total = files.reduce((sum, file) => sum + file.size, 0);
+  for (const file of files) {
+    if (file.keep) continue;
+    if (total <= MAX_CACHE_BYTES && file.mtimeMs >= expired) continue;
+    await rm(file.path, { force: true }).catch(() => {});
+    await rm(`${file.path}.json`, { force: true }).catch(() => {});
+    total -= file.size;
+  }
+}
+
+async function transfer(
+  buildId: string,
+  artifactId: string,
+  key: string,
+  sizeBytes: number | null,
+): Promise<MaterializedArtifact> {
+  const uploadId = randomUUID();
+  const services = getServerServices();
+  const build = await services.buildsService.getBuild(buildId);
+  if (!build?.agentId) throw new Error("Build agent is unavailable");
+
+  const timeoutMs = transferTimeout(sizeBytes);
+  let receivedPath: string | null = null;
+  try {
+    const [received] = await Promise.all([
+      expectArtifactTransfer(uploadId, build.agentId, timeoutMs),
+      services.buildsService.prepareArtifactDownload(
+        buildId,
+        artifactId,
+        uploadId,
+        timeoutMs,
+      ),
+    ]);
+    receivedPath = received.path;
+    await mkdir(CACHE_DIRECTORY, { recursive: true, mode: 0o700 });
+    const path = join(CACHE_DIRECTORY, key);
+    await moveIntoCache(received.path, path);
+    receivedPath = null;
+    const size = (await stat(path)).size;
+    const sidecar: Sidecar = {
+      // The agent chooses the filename — it appends .tar.gz when it packages a
+      // directory — so that decision has to survive into later cache hits.
+      filename: received.filename,
+      contentType: received.contentType,
+      size,
+    };
+    // Written after the rename so a torn write cannot leave a valid-looking entry.
+    await writeFile(`${path}.json`, JSON.stringify(sidecar), { mode: 0o600 });
+    // Awaited so the budget actually holds by the time the response is served;
+    // a directory scan is negligible next to the transfer that just finished.
+    await prune(key).catch(() => {});
+    return { path, etag: `"${key}"`, ...sidecar };
+  } catch (error) {
+    cancelArtifactTransfer(uploadId, error);
+    if (receivedPath) {
+      await rm(receivedPath, { force: true }).catch(() => {});
+    }
+    throw error;
+  }
+}
+
+/**
+ * Returns a local copy of a build artifact, fetching it from the agent only when
+ * it is not already cached.
+ *
+ * The agent holds the only copy, and every fetch costs a full upload of the
+ * whole file. iOS issues a probe plus several ranged requests per install, so
+ * serving those directly from the relay would re-transfer the package several
+ * times over. Caching first makes range requests answerable at all, and collapses
+ * concurrent requests for the same artifact into one transfer.
+ */
+export async function materializeArtifact(
+  buildId: string,
+  artifactId: string,
+): Promise<MaterializedArtifact> {
+  const services = getServerServices();
+  const artifact = await services.buildsService.artifactForInstall(
+    buildId,
+    artifactId,
+  );
+  if (!artifact) throw new Error("Build artifact not found");
+
+  const key = cacheKey(artifactId, artifact.checksum ?? artifact.createdAt);
+  const cached = await readCached(key);
+  if (cached) return cached;
+
+  const existing = inFlight.get(key);
+  if (existing) return existing;
+
+  const pending = transfer(
+    buildId,
+    artifactId,
+    key,
+    artifact.sizeBytes,
+  ).finally(() => {
+    inFlight.delete(key);
+  });
+  inFlight.set(key, pending);
+  return pending;
+}

package/standalone/src/services/builds/artifact-transfer.ts

@@ -31,12 +31,13 @@ const transfers =
 export function expectArtifactTransfer(
   uploadId: string,
   agentId: string,
+  timeoutMs = 170_000,
 ): Promise<ArtifactTransfer> {
   return new Promise((resolve, reject) => {
     const timeout = setTimeout(() => {
       transfers.delete(uploadId);
       reject(new Error("The agent did not upload the artifact in time"));
-    }, 170_000);
+    }, timeoutMs);
     timeout.unref();
     transfers.set(uploadId, { agentId, resolve, reject, timeout });
   });