@akanjs/devkit 2.4.1-rc.2 → 2.4.1-rc.3

package/incrementalBuilder/buildBatchRunner.ts

@@ -0,0 +1,85 @@
+import path from "node:path";
+import { Logger } from "akanjs/common";
+import type { BuilderMessage } from "akanjs/server";
+import type { BuildBatchMessage, BuildBatchRequest, BuildBatchResult } from "./buildBatchProtocol";
+
+/**
+ * Runs one `BuildBatchRequest` in a fresh process and resolves with what it produced.
+ *
+ * The watcher serializes every batch through its own work queue, so this deliberately has no pool: one
+ * worker exists at a time, and it exits before the next one starts. That is the whole point — the
+ * bundler arenas `Bun.build` never frees go back to the OS with the process.
+ *
+ * A worker that dies without reporting is not fatal. Every need it was given comes back as an error, the
+ * watcher reports a red build-status for that generation, and the last-good artifact keeps serving —
+ * the same contract a failed in-process build had. It must never take the watcher down with it: the
+ * watcher is the dev server's file watcher, so nothing would notice the fix.
+ */
+export class BuildBatchRunner {
+  static readonly #entryCandidates = (workspaceRoot: string) => [
+    path.join(workspaceRoot, "pkgs/@akanjs/devkit/incrementalBuilder/buildBatch.proc.ts"),
+    path.join(workspaceRoot, "node_modules/@akanjs/devkit/incrementalBuilder/buildBatch.proc.ts"),
+    path.join(import.meta.dir, "buildBatch.proc.js"),
+    path.join(import.meta.dir, "buildBatch.proc.ts"),
+  ];
+  #logger = new Logger("BuildBatchRunner");
+  #entry: string | null = null;
+  #workspaceRoot: string;
+  #cwd: string;
+  constructor({ workspaceRoot, cwd }: { workspaceRoot: string; cwd: string }) {
+    this.#workspaceRoot = workspaceRoot;
+    this.#cwd = cwd;
+  }
+
+  async #resolveEntry(): Promise<string> {
+    if (this.#entry) return this.#entry;
+    const candidates = BuildBatchRunner.#entryCandidates(this.#workspaceRoot);
+    for (const candidate of candidates) {
+      if (!(await Bun.file(candidate).exists())) continue;
+      this.#entry = candidate;
+      return candidate;
+    }
+    throw new Error(`[build-batch] worker entry not found; looked in: ${candidates.join(", ")}`);
+  }
+
+  /**
+   * `onMessage` receives everything the worker streams as it goes — `pages-updated`, `css-updated`,
+   * `build-status` — so the watcher can relay each one the moment it is produced instead of holding a
+   * page reload until the whole batch is done.
+   */
+  async run(
+    request: BuildBatchRequest,
+    onMessage: (message: BuilderMessage) => void = () => undefined,
+  ): Promise<BuildBatchResult> {
+    const started = Date.now();
+    const entry = await this.#resolveEntry();
+    let result: BuildBatchResult | null = null;
+    // The request travels in argv rather than over IPC so the worker can start on its first tick
+    // instead of waiting for a handshake it would have to synchronize against.
+    const proc = Bun.spawn(["bun", entry, JSON.stringify(request)], {
+      cwd: this.#cwd,
+      env: process.env,
+      stdio: ["ignore", "inherit", "inherit"],
+      serialization: "advanced",
+      ipc: (message: BuildBatchMessage | BuilderMessage) => {
+        if (!message || typeof message !== "object") return;
+        if (message.type === "build-batch-result") result = message.data;
+        else onMessage(message);
+      },
+    });
+    const exitCode = await proc.exited;
+    if (result) {
+      this.#logger.verbose(
+        `[build-batch] generation=${request.generation} needs=${request.needs.join(",")} done in ${Date.now() - started}ms`,
+      );
+      return result;
+    }
+    const message = `build worker exited with code ${exitCode} before reporting a result`;
+    this.#logger.error(`[build-batch] generation=${request.generation} ${message}`);
+    return {
+      generation: request.generation,
+      errors: Object.fromEntries(request.needs.map((need) => [need, message])),
+      crashed: true,
+    };
+  }
+}

package/incrementalBuilder/incrementalBuilder.host.test.ts

@@ -10,17 +10,24 @@ afterEach(() => {
   mock.restore();
 });
 
+interface SpawnRecord {
+  proc: { pid: number; send: ReturnType<typeof mock>; kill: ReturnType<typeof mock>; killed: boolean };
+  options: { ipc?: (message: unknown) => void; onExit?: () => void; env?: Record<string, string> };
+}
+
+const mockSpawns = (): SpawnRecord[] => {
+  const spawns: SpawnRecord[] = [];
+  (Bun as unknown as { spawn: typeof Bun.spawn }).spawn = mock((_, options) => {
+    const proc = { pid: 10_000 + spawns.length, send: mock(), kill: mock(), killed: false };
+    spawns.push({ proc, options: options as SpawnRecord["options"] });
+    return proc as never;
+  }) as never;
+  return spawns;
+};
+
 describe("IncrementalBuilderHost", () => {
   test("restarts after a ready builder exits", async () => {
-    const spawns: Array<{
-      proc: { pid: number; send: ReturnType<typeof mock>; kill: ReturnType<typeof mock>; killed: boolean };
-      options: { ipc?: (message: unknown) => void; onExit?: () => void };
-    }> = [];
-    (Bun as unknown as { spawn: typeof Bun.spawn }).spawn = mock((_, options) => {
-      const proc = { pid: 10_000 + spawns.length, send: mock(), kill: mock(), killed: false };
-      spawns.push({ proc, options: options as { ipc?: (message: unknown) => void; onExit?: () => void } });
-      return proc as never;
-    }) as never;
+    const spawns = mockSpawns();
 
     const onReady = mock();
     const onRestartReady = mock();
@@ -48,4 +55,102 @@ describe("IncrementalBuilderHost", () => {
 
     host.stop();
   });
+
+  test("recycles a ready builder gracefully and replaces it immediately", async () => {
+    const spawns = mockSpawns();
+    const onRestartReady = mock();
+    const host = new IncrementalBuilderHost({
+      app: { cwdPath: "/tmp/app" } as never,
+      entry: "/tmp/builder.ts",
+      env: {},
+      onMessage: () => undefined,
+    });
+
+    host.start({ onRestartReady });
+    spawns[0]?.options.ipc?.({ type: "builder-ready" });
+    expect(spawns[0]?.options.env?.AKAN_BUILDER_RECYCLED).toBeUndefined();
+
+    const reason = "rss=1300MiB>=1200MiB after 3 build(s)";
+    expect(host.recycle(reason)).toBe(true);
+    // Graceful: the builder is asked to drain, not killed, so a rebuild in flight still completes.
+    expect(spawns[0]?.proc.send).toHaveBeenCalledWith({ type: "builder-shutdown", reason });
+    expect(spawns[0]?.proc.kill).not.toHaveBeenCalled();
+    expect(host.recycle("second request")).toBe(false);
+
+    // A planned exit skips the crash backoff — the dev server has no file watcher until it is back.
+    spawns[0]?.options.onExit?.();
+    expect(spawns).toHaveLength(2);
+    expect(spawns[1]?.options.env?.AKAN_BUILDER_RECYCLED).toBe("1");
+    spawns[1]?.options.ipc?.({ type: "builder-ready" });
+    expect(onRestartReady).toHaveBeenCalledTimes(1);
+    expect(host.status).toBe("ready");
+
+    // The flag is per-recycle: a later crash restart must not re-announce a boot artifact.
+    spawns[1]?.options.onExit?.();
+    expect(spawns).toHaveLength(2);
+    await wait(1_050);
+    expect(spawns).toHaveLength(3);
+    expect(spawns[2]?.options.env?.AKAN_BUILDER_RECYCLED).toBeUndefined();
+
+    host.stop();
+  });
+
+  test("only recycles a builder that is ready", () => {
+    const spawns = mockSpawns();
+    const host = new IncrementalBuilderHost({
+      app: { cwdPath: "/tmp/app" } as never,
+      entry: "/tmp/builder.ts",
+      env: {},
+      onMessage: () => undefined,
+    });
+
+    host.start();
+    expect(host.recycle("while still booting")).toBe(false);
+    expect(spawns[0]?.proc.send).not.toHaveBeenCalled();
+
+    host.stop();
+    expect(host.recycle("after stop")).toBe(false);
+  });
+});
+
+describe("IncrementalBuilderHost.maxRssBytes", () => {
+  const withEnv = (values: Record<string, string | undefined>, fn: () => void) => {
+    const previous = Object.fromEntries(Object.keys(values).map((key) => [key, process.env[key]]));
+    try {
+      for (const [key, value] of Object.entries(values)) {
+        if (value === undefined) delete process.env[key];
+        else process.env[key] = value;
+      }
+      fn();
+    } finally {
+      for (const [key, value] of Object.entries(previous)) {
+        if (value === undefined) delete process.env[key];
+        else process.env[key] = value;
+      }
+    }
+  };
+
+  test("defaults to a dev ceiling well above a fresh boot", () => {
+    withEnv(
+      { AKAN_BUILDER_MAX_RSS_MB: undefined, AKAN_BUILDER_MAX_RSS: undefined, AKAN_MEMORY_LIMIT: undefined },
+      () => {
+        expect(IncrementalBuilderHost.maxRssBytes()).toBe(1_200 * 1024 * 1024);
+      },
+    );
+  });
+
+  test("honors an explicit override and treats 0 as unbounded", () => {
+    withEnv({ AKAN_BUILDER_MAX_RSS_MB: "700" }, () => {
+      expect(IncrementalBuilderHost.maxRssBytes()).toBe(700 * 1024 * 1024);
+    });
+    withEnv({ AKAN_BUILDER_MAX_RSS_MB: "0" }, () => {
+      expect(IncrementalBuilderHost.maxRssBytes()).toBeNull();
+    });
+  });
+
+  test("takes a share of a declared memory limit, leaving room for the other dev processes", () => {
+    withEnv({ AKAN_BUILDER_MAX_RSS_MB: undefined, AKAN_BUILDER_MAX_RSS: undefined, AKAN_MEMORY_LIMIT: "4gb" }, () => {
+      expect(IncrementalBuilderHost.maxRssBytes()).toBe(Math.floor(4 * 1024 ** 3 * 0.35));
+    });
+  });
 });

package/incrementalBuilder/incrementalBuilder.host.ts

@@ -1,6 +1,7 @@
 import path from "node:path";
 import { Logger } from "akanjs/common";
 import type { BuilderMessage } from "akanjs/server";
+import { MemoryLimit } from "akanjs/server/memoryLimit";
 import type { App } from "../commandDecorators";
 
 const builderMsgTypeSet = new Set<BuilderMessage["type"]>([
@@ -11,6 +12,7 @@ const builderMsgTypeSet = new Set<BuilderMessage["type"]>([
   "css-updated",
   "pages-updated",
   "build-status",
+  "builder-metrics",
 ]);
 interface IncrementalBuilderHostOptions {
   app: App;
@@ -30,6 +32,16 @@ interface IncrementalBuilderStartOptions {
 export class IncrementalBuilderHost {
   static readonly #restartBaseDelayMs = 1_000;
   static readonly #restartMaxDelayMs = 30_000;
+  /**
+   * A builder that has stopped answering has to be replaced anyway; killing it after this long turns
+   * a wedged drain into an ordinary restart instead of leaving the recycle stuck forever.
+   */
+  static readonly #recycleDrainTimeoutMs = 30_000;
+  /**
+   * Dev has no memory limit to derive a fraction from, so this is what bounds the builder there. Well
+   * above a fresh boot (~300-600MB depending on app size) with room for one full rebuild on top.
+   */
+  static readonly #devMaxRssBytes = 1_200 * 1024 * 1024;
   logger = new Logger("IncrementalBuilderHost");
   entry: string;
   env: Record<string, string>;
@@ -40,6 +52,9 @@ export class IncrementalBuilderHost {
   #status: IncrementalBuilderStatus = "stopped";
   #restartAttempts = 0;
   #restartTimer: ReturnType<typeof setTimeout> | null = null;
+  #recycleTimer: ReturnType<typeof setTimeout> | null = null;
+  #recycleRequested: boolean = false;
+  #spawnAfterRecycle: boolean = false;
   #manualStop = false;
   #startOptions: IncrementalBuilderStartOptions = {};
   constructor({ app, entry, env, onMessage }: IncrementalBuilderHostOptions) {
@@ -61,10 +76,14 @@ export class IncrementalBuilderHost {
   #spawn(isRestart: boolean) {
     this.#status = isRestart ? "restarting" : "starting";
     this.ready = false;
+    // A recycled builder rebuilds every artifact, and the running backend still holds the previous
+    // one; the flag is what tells the replacement to re-announce what it booted with.
+    const afterRecycle = this.#spawnAfterRecycle;
+    this.#spawnAfterRecycle = false;
     let proc!: Bun.Subprocess<"ignore", "inherit", "inherit">;
     proc = Bun.spawn(["bun", this.entry], {
       cwd: this.app.cwdPath,
-      env: { ...this.env, AKAN_WATCH: "1" },
+      env: { ...this.env, AKAN_WATCH: "1", ...(afterRecycle ? { AKAN_BUILDER_RECYCLED: "1" } : {}) },
       stdio: ["ignore", "inherit", "inherit"],
       ipc: (msg: BuilderMessage) => {
         if (this.#proc !== proc) return;
@@ -83,6 +102,8 @@ export class IncrementalBuilderHost {
         if (this.#proc !== proc) return;
         this.#proc = null;
         const wasReady = this.ready;
+        const wasRecycle = this.#recycleRequested;
+        this.#clearRecycle();
         this.ready = false;
         if (this.#manualStop || this.#status === "stopped") return;
         if (!wasReady) {
@@ -90,6 +111,14 @@ export class IncrementalBuilderHost {
           this.#startOptions.onExit?.();
           return;
         }
+        // A recycle is a planned exit, so it neither counts as a failed attempt nor waits out the
+        // crash backoff — the dev server is without a watcher until the replacement is up.
+        if (wasRecycle) {
+          this.logger.verbose("builder exited for a recycle; spawning its replacement now");
+          this.#spawnAfterRecycle = true;
+          this.#spawn(true);
+          return;
+        }
         this.#scheduleRestart();
       },
     });
@@ -112,6 +141,47 @@ export class IncrementalBuilderHost {
       this.#spawn(true);
     }, delay);
   }
+  /**
+   * Ask the builder to drain its queues and exit so the OS reclaims the bundler arenas `Bun.build`
+   * never gives back; `onExit` then spawns the replacement. Graceful rather than `kill()` so a rebuild
+   * in flight is never truncated, with a watchdog for a builder that stops answering.
+   */
+  recycle(reason: string): boolean {
+    if (!this.#proc || this.#status !== "ready" || this.#recycleRequested) return false;
+    const proc = this.#proc;
+    if (!this.send({ type: "builder-shutdown", reason })) return false;
+    this.#recycleRequested = true;
+    this.logger.info(`recycling builder pid=${proc.pid} (${reason})`);
+    this.#recycleTimer = setTimeout(() => {
+      this.#recycleTimer = null;
+      if (this.#proc !== proc) return;
+      this.logger.warn(
+        `builder pid=${proc.pid} did not exit within ${IncrementalBuilderHost.#recycleDrainTimeoutMs}ms of the recycle request; killing it`,
+      );
+      proc.kill();
+    }, IncrementalBuilderHost.#recycleDrainTimeoutMs);
+    return true;
+  }
+  #clearRecycle() {
+    this.#recycleRequested = false;
+    if (!this.#recycleTimer) return;
+    clearTimeout(this.#recycleTimer);
+    this.#recycleTimer = null;
+  }
+  /**
+   * RSS at which the builder is recycled: an explicit override, else a share of the container's limit
+   * (the builder is one of several dev processes), else the dev default. Set
+   * `AKAN_BUILDER_MAX_RSS_MB=0` to leave it unbounded.
+   */
+  static maxRssBytes(): number | null {
+    if (process.env.AKAN_BUILDER_MAX_RSS_MB === "0") return null;
+    return MemoryLimit.resolveMaxRssBytes({
+      megabytesEnv: "AKAN_BUILDER_MAX_RSS_MB",
+      bytesEnv: "AKAN_BUILDER_MAX_RSS",
+      limitFraction: 0.35,
+      fallbackBytes: IncrementalBuilderHost.#devMaxRssBytes,
+    });
+  }
   send(message: BuilderMessage): boolean {
     if (!this.#proc || this.#status !== "ready") {
       this.logger.warn(`incrementalBuilderHost is ${this.#status}; cannot send ${message.type}`);
@@ -129,6 +199,7 @@ export class IncrementalBuilderHost {
   }
   stop() {
     this.#manualStop = true;
+    this.#clearRecycle();
     if (this.#restartTimer) {
       clearTimeout(this.#restartTimer);
       this.#restartTimer = null;