@caelo-cms/provisioning 0.10.47 → 0.10.48

package/src/agent/config.ts

@@ -0,0 +1,86 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * The host agent's settings in `.caelo/config.json` (#696 Phase 4c): its
+ * database password and the loopback port Postgres is published on for it.
+ * Generated once and kept, so re-running `agent install`, `up` or `upgrade`
+ * converges onto the same values.
+ */
+
+import { isAgentDbPort } from "../compose.js";
+import { AGENT_DB_ROLE } from "../self-hosted-roles.js";
+import type { AgentDbConnection } from "./queue.js";
+
+/** `config.json` → `agent`. */
+export interface AgentConfig {
+  readonly dbPort: number;
+  readonly dbPassword: string;
+  /**
+   * Set by `agent uninstall`: `init` / `upgrade` then leave the agent off
+   * until `agent install` is run again.
+   */
+  readonly disabled?: boolean;
+}
+
+/** The first port tried for the agent's Postgres; the next free one is taken. */
+export const AGENT_DB_PORT_DEFAULT = 15432;
+const PORT_CANDIDATES = 50;
+
+/** Whether nothing listens on `127.0.0.1:port` (a quick bind test). */
+export function loopbackPortFree(port: number): boolean {
+  try {
+    const server = Bun.listen({
+      hostname: "127.0.0.1",
+      port,
+      socket: { data() {} },
+    });
+    server.stop(true);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * The agent's settings: `existing` unchanged (a running install keeps its
+ * port and password), else a fresh password and the first free port from
+ * {@link AGENT_DB_PORT_DEFAULT} (or `requestedPort`).
+ *
+ * @throws when `requestedPort` is not usable or no candidate port is free
+ */
+export function agentConfigFor(
+  existing: AgentConfig | undefined,
+  opts: {
+    readonly requestedPort?: number;
+    readonly randomSecret: () => string;
+    readonly portFree?: (port: number) => boolean;
+  },
+): AgentConfig {
+  const free = opts.portFree ?? loopbackPortFree;
+  if (existing && (opts.requestedPort === undefined || opts.requestedPort === existing.dbPort)) {
+    const { disabled: _disabled, ...kept } = existing;
+    return kept;
+  }
+  if (opts.requestedPort !== undefined) {
+    if (!isAgentDbPort(opts.requestedPort)) {
+      throw new Error(`--port ${opts.requestedPort} is not a TCP port between 1024 and 65535.`);
+    }
+    if (!free(opts.requestedPort)) {
+      throw new Error(
+        `Port ${opts.requestedPort} on 127.0.0.1 is in use; pick another with --port.`,
+      );
+    }
+    return { dbPort: opts.requestedPort, dbPassword: existing?.dbPassword ?? opts.randomSecret() };
+  }
+  for (let port = AGENT_DB_PORT_DEFAULT; port < AGENT_DB_PORT_DEFAULT + PORT_CANDIDATES; port++) {
+    if (free(port)) return { dbPort: port, dbPassword: opts.randomSecret() };
+  }
+  throw new Error(
+    `No free port on 127.0.0.1 between ${AGENT_DB_PORT_DEFAULT} and ${AGENT_DB_PORT_DEFAULT + PORT_CANDIDATES - 1}; pass --port.`,
+  );
+}
+
+/** The agent's database login. */
+export function agentDbConnection(agent: AgentConfig): AgentDbConnection {
+  return { user: AGENT_DB_ROLE, password: agent.dbPassword, port: agent.dbPort };
+}

package/src/agent/lock-config.test.ts

@@ -0,0 +1,97 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/** The install's upgrade lock (agent/lock.ts) and the agent's settings (agent/config.ts). */
+
+import { afterEach, beforeEach, describe, expect, it } from "bun:test";
+import { existsSync, mkdtempSync, readdirSync, rmSync, utimesSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { AGENT_DB_PORT_DEFAULT, agentConfigFor, agentDbConnection } from "./config.js";
+import { acquireUpgradeLock, upgradeLockPath } from "./lock.js";
+
+describe("acquireUpgradeLock", () => {
+  let dir: string;
+  beforeEach(() => {
+    dir = mkdtempSync(join(tmpdir(), "caelo-lock-"));
+  });
+  afterEach(() => rmSync(dir, { recursive: true, force: true }));
+
+  it("lets one holder in and names it to the next", () => {
+    const release = acquireUpgradeLock(dir, "the update agent", { pid: 101, alive: () => true });
+    expect(() =>
+      acquireUpgradeLock(dir, "`cms-provision upgrade`", { pid: 102, alive: () => true }),
+    ).toThrow(/the update agent is running on this install \(pid 101/);
+    release();
+    release();
+    expect(existsSync(upgradeLockPath(dir))).toBe(false);
+    acquireUpgradeLock(dir, "`cms-provision upgrade`", { pid: 102, alive: () => true })();
+  });
+
+  it("takes over a lock whose process is gone", () => {
+    acquireUpgradeLock(dir, "a crashed agent", { pid: 999_999 });
+    const release = acquireUpgradeLock(dir, "the update agent", {
+      pid: 5,
+      alive: (pid) => pid !== 999_999,
+    });
+    expect(typeof release).toBe("function");
+  });
+
+  it("treats an unreadable lock file as held until it is older than any run", () => {
+    writeFileSync(upgradeLockPath(dir), "{not json");
+    expect(() => acquireUpgradeLock(dir, "the update agent")).toThrow(/unreadable/);
+    const old = new Date(Date.now() - 3 * 60 * 60 * 1000);
+    utimesSync(upgradeLockPath(dir), old, old);
+    expect(() => acquireUpgradeLock(dir, "the update agent")()).not.toThrow();
+  });
+
+  it("leaves no temp files behind", () => {
+    acquireUpgradeLock(dir, "the update agent")();
+    expect(readdirSync(dir)).toEqual([]);
+  });
+});
+
+describe("agentConfigFor", () => {
+  const secret = () => "s".repeat(64);
+
+  it("keeps an existing agent's port and password (and re-enables it)", () => {
+    const existing = { dbPort: 15433, dbPassword: "p", disabled: true };
+    expect(agentConfigFor(existing, { randomSecret: secret, portFree: () => false })).toEqual({
+      dbPort: 15433,
+      dbPassword: "p",
+    });
+  });
+
+  it("takes the first free loopback port from the default", () => {
+    const busy = new Set([AGENT_DB_PORT_DEFAULT, AGENT_DB_PORT_DEFAULT + 1]);
+    expect(
+      agentConfigFor(undefined, { randomSecret: secret, portFree: (p) => !busy.has(p) }),
+    ).toEqual({ dbPort: AGENT_DB_PORT_DEFAULT + 2, dbPassword: secret() });
+  });
+
+  it("checks an explicit port and keeps the password when moving", () => {
+    expect(() =>
+      agentConfigFor(undefined, { requestedPort: 80, randomSecret: secret, portFree: () => true }),
+    ).toThrow(/between 1024 and 65535/);
+    expect(() =>
+      agentConfigFor(undefined, {
+        requestedPort: 20000,
+        randomSecret: secret,
+        portFree: () => false,
+      }),
+    ).toThrow(/in use/);
+    expect(
+      agentConfigFor(
+        { dbPort: 15432, dbPassword: "keep" },
+        { requestedPort: 20000, randomSecret: secret, portFree: () => true },
+      ),
+    ).toEqual({ dbPort: 20000, dbPassword: "keep" });
+  });
+
+  it("logs in as caelo_agent", () => {
+    expect(agentDbConnection({ dbPort: 15432, dbPassword: "pw" })).toEqual({
+      user: "caelo_agent",
+      password: "pw",
+      port: 15432,
+    });
+  });
+});

package/src/agent/lock.ts

@@ -0,0 +1,110 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * One upgrade at a time per self-hosted install (#696 Phase 4c): the host
+ * agent and a hand-run `cms-provision upgrade` both take
+ * `.caelo/upgrade.lock` for the whole run — two concurrent rolls would
+ * overwrite each other's Compose file and restore the wrong one on rollback.
+ *
+ * The file holds the holder's pid; a lock whose process is gone (a crash, a
+ * reboot) is taken over rather than blocking updates forever.
+ *
+ * The record is written to a private temp file first and then hard-linked
+ * into place, so the lock file never exists half-written: a reader that
+ * finds it can always trust its pid. (An unreadable file is only taken over
+ * once it is older than any run could be.)
+ */
+
+import { linkSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+/** `.caelo/upgrade.lock`. */
+export function upgradeLockPath(caeloDir: string): string {
+  return join(caeloDir, "upgrade.lock");
+}
+
+interface LockRecord {
+  readonly pid: number;
+  readonly holder: string;
+  readonly at: string;
+}
+
+/** An unreadable lock file younger than this still counts as held (longer than any run). */
+const UNREADABLE_LOCK_MAX_AGE_MS = 2 * 60 * 60 * 1000;
+
+/** The lock file's modification time (0 when it vanished meanwhile). */
+function lockMtime(path: string): number {
+  try {
+    return statSync(path).mtimeMs;
+  } catch {
+    return 0;
+  }
+}
+
+/** Whether process `pid` exists (signal 0 checks without signalling). */
+function processAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (e) {
+    // EPERM: it exists, it is just someone else's.
+    return (e as NodeJS.ErrnoException).code === "EPERM";
+  }
+}
+
+/**
+ * Take the install's upgrade lock for `holder`.
+ *
+ * @returns the release function (idempotent)
+ * @throws when a live process holds it, naming that holder
+ */
+export function acquireUpgradeLock(
+  caeloDir: string,
+  holder: string,
+  deps: { readonly pid?: number; readonly alive?: (pid: number) => boolean } = {},
+): () => void {
+  const path = upgradeLockPath(caeloDir);
+  const alive = deps.alive ?? processAlive;
+  const record: LockRecord = {
+    pid: deps.pid ?? process.pid,
+    holder,
+    at: new Date().toISOString(),
+  };
+  const temp = `${path}.${record.pid}.${crypto.randomUUID()}`;
+  writeFileSync(temp, JSON.stringify(record), { mode: 0o600, flag: "wx" });
+  try {
+    for (let attempt = 0; attempt < 2; attempt++) {
+      try {
+        // Atomic: fails with EEXIST when someone holds the lock.
+        linkSync(temp, path);
+        let released = false;
+        return () => {
+          if (released) return;
+          released = true;
+          rmSync(path, { force: true });
+        };
+      } catch (e) {
+        if ((e as NodeJS.ErrnoException).code !== "EEXIST") throw e;
+      }
+      let held: Partial<LockRecord> | null = null;
+      try {
+        held = JSON.parse(readFileSync(path, "utf8")) as Partial<LockRecord>;
+      } catch {
+        // Corrupt (never half-written, see above): take it over only when old.
+      }
+      if (held === null) {
+        if (Date.now() - lockMtime(path) < UNREADABLE_LOCK_MAX_AGE_MS) {
+          throw new Error(`another upgrade holds ${path} (its record is unreadable).`);
+        }
+      } else if (typeof held.pid === "number" && alive(held.pid)) {
+        throw new Error(
+          `${held.holder ?? "another upgrade"} is running on this install (pid ${held.pid}, since ${held.at ?? "?"}).`,
+        );
+      }
+      rmSync(path, { force: true });
+    }
+  } finally {
+    rmSync(temp, { force: true });
+  }
+  throw new Error(`could not take ${path}; another process keeps creating it.`);
+}

package/src/agent/queue.test.ts

@@ -0,0 +1,10 @@
+// SPDX-License-Identifier: MPL-2.0
+
+import { describe, expect, it } from "bun:test";
+import { loadAgentQueueOpener } from "./queue.js";
+
+describe("loadAgentQueueOpener", () => {
+  it("finds the agent's database module (the bundle, or the workspace package)", async () => {
+    expect(typeof (await loadAgentQueueOpener())).toBe("function");
+  });
+});

package/src/agent/queue.ts

@@ -0,0 +1,91 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * The self-hosted host agent's database side (#696 Phase 4c): the same
+ * {@link UpdateQueue} the Google Cloud upgrader job drives, plus the
+ * heartbeat the admin reads to decide whether to offer "Install update".
+ *
+ * The queue is implemented in `@caelo-cms/platform-updater` (the job ops,
+ * through the Query API — never raw SQL), which the published CLI cannot
+ * depend on: it is private, and it depends on this package. So the build
+ * bundles its `agent-db` entry into `dist/agent-db.js` (package.json
+ * `build`), and {@link loadAgentQueueOpener} imports that file; a source
+ * checkout imports the workspace package instead.
+ */
+
+import { existsSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import type { UpdateQueue } from "../upgrader-job.js";
+
+/** One check-in of the agent (`platform_update_agent`). */
+export interface AgentHeartbeat {
+  /** The Caelo release of the agent's own code. */
+  readonly agentVersion: string;
+  /** The host it runs on. */
+  readonly host: string;
+  /** Why an install would fail on this host right now; null when none. */
+  readonly problem: string | null;
+}
+
+/** The upgrader's queue plus the agent's heartbeat. */
+export interface AgentQueue extends UpdateQueue {
+  heartbeat(beat: AgentHeartbeat): Promise<void>;
+}
+
+/** Where the agent's database login reaches Postgres (loopback only). */
+export interface AgentDbConnection {
+  readonly user: string;
+  readonly password: string;
+  readonly port: number;
+}
+
+/** An open queue and the pools behind it. */
+export interface OpenedAgentQueue {
+  readonly queue: AgentQueue;
+  close(): Promise<void>;
+}
+
+/** Opens the queue over the agent's login (`@caelo-cms/platform-updater` agent-db). */
+export type OpenAgentQueue = (conn: AgentDbConnection) => Promise<OpenedAgentQueue>;
+
+/**
+ * Where the bundle is, relative to this module: next to the compiled CLI
+ * (`dist/agent/queue.js` → `dist/agent-db.js`), or — when Bun loads the
+ * published package's `src/` through its `bun` export condition — in the
+ * package's `dist/`.
+ */
+const BUNDLED_AGENT_DB = ["../agent-db.js", "../../dist/agent-db.js"] as const;
+
+/**
+ * The workspace package a source checkout loads instead. Held in a variable
+ * so TypeScript does not resolve it: provisioning cannot declare a
+ * dependency on the package that depends on it.
+ */
+const WORKSPACE_AGENT_DB = "@caelo-cms/platform-updater/agent-db";
+
+/**
+ * Load the function that opens the agent's queue: the bundle shipped in the
+ * published package, else (a source checkout) the workspace package.
+ *
+ * @throws when neither is present — a build that skipped the bundle
+ */
+export async function loadAgentQueueOpener(): Promise<OpenAgentQueue> {
+  const bundled = BUNDLED_AGENT_DB.map((rel) => new URL(rel, import.meta.url)).find((url) =>
+    existsSync(fileURLToPath(url)),
+  );
+  const specifier = bundled?.href ?? WORKSPACE_AGENT_DB;
+  let mod: { openAgentQueue?: OpenAgentQueue };
+  try {
+    mod = (await import(specifier)) as { openAgentQueue?: OpenAgentQueue };
+  } catch (e) {
+    throw new Error(
+      `the update agent's database module is missing (${specifier}: ${e instanceof Error ? e.message : String(e)}). This @caelo-cms/provisioning build is incomplete — reinstall it.`,
+    );
+  }
+  if (typeof mod.openAgentQueue !== "function") {
+    throw new Error(
+      `${specifier} does not export openAgentQueue — reinstall @caelo-cms/provisioning.`,
+    );
+  }
+  return mod.openAgentQueue;
+}