@forgezero/agent 0.1.22 → 0.1.24

package/dist/lifecycle-helper.js

@@ -0,0 +1,216 @@
+// src/lifecycle-helper.ts
+import { chmodSync, existsSync, readFileSync, unlinkSync } from "node:fs";
+import { connect, createConnection, createServer, isIP } from "node:net";
+var DEFAULT_LIFECYCLE_HELPER_SOCKET = "/run/forgezero-lifecycle/helper.sock";
+var MAX_REQUEST_BYTES = 16 * 1024;
+var REQUEST_TIMEOUT_MS = 5000;
+var ACTION_TIMEOUT_MS = 10 * 60000;
+var unitPattern = /^[A-Za-z0-9_.@-]+\.service$/;
+var privateIp = (value) => {
+  const address = value.replace(/^\[|\]$/g, "").toLowerCase();
+  if (isIP(address) === 4) {
+    const [a, b] = address.split(".").map(Number);
+    return a === 10 || a === 172 && b >= 16 && b <= 31 || a === 192 && b === 168;
+  }
+  if (isIP(address) === 6) {
+    const first = Number.parseInt(address.split(":", 1)[0], 16);
+    return Number.isFinite(first) && (first & 65024) === 64512;
+  }
+  return false;
+};
+function validateLifecycleProfile(profile) {
+  if (!Array.isArray(profile.apiUnits) || profile.apiUnits.length < 1 || profile.apiUnits.some((unit) => !unitPattern.test(unit))) {
+    throw new Error("lifecycle profile needs one or more valid API service units");
+  }
+  if (!unitPattern.test(profile.databaseUnit))
+    throw new Error("lifecycle profile database unit is invalid");
+  const apiUrl = new URL(profile.apiHealthUrl);
+  if (apiUrl.protocol !== "http:" || !["127.0.0.1", "[::1]", "::1", "localhost"].includes(apiUrl.hostname)) {
+    throw new Error("API health URL must be loopback HTTP");
+  }
+  const databaseUrl = new URL(profile.databaseHealthUrl);
+  if (databaseUrl.protocol !== "http:" || !(["127.0.0.1", "[::1]", "::1", "localhost"].includes(databaseUrl.hostname) || privateIp(databaseUrl.hostname))) {
+    throw new Error("database health URL must be loopback or private HTTP");
+  }
+  if (!Array.isArray(profile.databasePorts) || profile.databasePorts.length < 1 || profile.databasePorts.some((port) => !Number.isInteger(port) || port < 1 || port > 65535)) {
+    throw new Error("lifecycle profile database ports are invalid");
+  }
+}
+function loadLifecycleProfile(path) {
+  const profile = JSON.parse(readFileSync(path, "utf8"));
+  validateLifecycleProfile(profile);
+  return profile;
+}
+var spawnLifecycleCommand = async (argv) => {
+  const child = Bun.spawn([...argv], {
+    stdout: "pipe",
+    stderr: "pipe",
+    env: { PATH: "/usr/sbin:/usr/bin:/sbin:/bin" }
+  });
+  let timedOut = false;
+  const timer = setTimeout(() => {
+    timedOut = true;
+    child.kill("SIGTERM");
+  }, ACTION_TIMEOUT_MS);
+  const [stdout, stderr, exitCode] = await Promise.all([
+    new Response(child.stdout).text(),
+    new Response(child.stderr).text(),
+    child.exited
+  ]);
+  clearTimeout(timer);
+  return { exitCode: timedOut ? 124 : exitCode, stdout, stderr };
+};
+var requireSuccess = async (exec, argv, label) => {
+  const result = await exec(argv);
+  if (result.exitCode !== 0)
+    throw new Error(`${label} failed: ${(result.stderr || result.stdout).trim() || `exit ${result.exitCode}`}`);
+  return result.stdout;
+};
+var probeTcp = (host, port, timeoutMs = 5000) => new Promise((resolve, reject) => {
+  const socket = createConnection({ host, port });
+  socket.setTimeout(timeoutMs);
+  socket.once("connect", () => {
+    socket.destroy();
+    resolve();
+  });
+  socket.once("timeout", () => {
+    socket.destroy();
+    reject(new Error(`private peer ${host}:${port} timed out`));
+  });
+  socket.once("error", reject);
+});
+async function executeLifecycleAction(profile, claim, exec = spawnLifecycleCommand, tcpProbe = probeTcp, fetcher = fetch) {
+  validateLifecycleProfile(profile);
+  switch (claim.action) {
+    case "network-ready": {
+      if (!claim.peerPrivateAddresses?.length)
+        throw new Error("network claim has no private peers");
+      if (claim.network === "cloudflare-warp") {
+        const status = await requireSuccess(exec, ["/usr/bin/warp-cli", "--accept-tos", "status"], "WARP status");
+        if (!/\bconnected\b/i.test(status) || /\bdisconnected\b/i.test(status))
+          throw new Error("WARP is not connected");
+      }
+      for (const address of claim.peerPrivateAddresses) {
+        for (const port of profile.databasePorts)
+          await tcpProbe(address, port);
+      }
+      return {
+        targetAgentReady: true,
+        privateNetworkReady: true,
+        ...claim.network === "cloudflare-warp" ? { warpConnected: true } : {}
+      };
+    }
+    case "database-member-ready": {
+      await requireSuccess(exec, ["/usr/bin/systemctl", "is-active", profile.databaseUnit], "database service check");
+      const response = await fetcher(profile.databaseHealthUrl, { signal: AbortSignal.timeout(5000) });
+      if (!response.ok && response.status !== 401)
+        throw new Error(`database health returned HTTP ${response.status}`);
+      return { databaseMemberHealthy: true };
+    }
+    case "api-ready": {
+      const response = await fetcher(profile.apiHealthUrl, { signal: AbortSignal.timeout(5000) });
+      if (!response.ok)
+        throw new Error(`API health returned HTTP ${response.status}`);
+      return { apiHealthy: true };
+    }
+    case "source-drained":
+      await requireSuccess(exec, ["/usr/bin/systemctl", "stop", ...profile.apiUnits], "API drain");
+      return { sourceDrained: true };
+    case "source-stopped":
+      await requireSuccess(exec, ["/usr/bin/systemctl", "stop", ...profile.apiUnits, profile.databaseUnit], "source retirement");
+      return { sourceStopped: true };
+    default:
+      throw new Error("unknown lifecycle action");
+  }
+}
+function startLifecycleHelper(options) {
+  validateLifecycleProfile(options.profile);
+  const socketPath = options.socketPath ?? DEFAULT_LIFECYCLE_HELPER_SOCKET;
+  if (existsSync(socketPath))
+    unlinkSync(socketPath);
+  let tail = Promise.resolve();
+  const server = createServer((socket) => {
+    let buffer = "";
+    socket.setTimeout(REQUEST_TIMEOUT_MS, () => socket.end(`${JSON.stringify({ ok: false, error: { code: "REFUSED", message: "request timed out" } })}
+`));
+    socket.on("data", (chunk) => {
+      buffer += chunk.toString("utf8");
+      if (buffer.length > MAX_REQUEST_BYTES)
+        return void socket.end(`${JSON.stringify({ ok: false, error: { code: "REFUSED", message: "request too large" } })}
+`);
+      const newline = buffer.indexOf(`
+`);
+      if (newline < 0)
+        return;
+      socket.setTimeout(0);
+      const line = buffer.slice(0, newline);
+      buffer = "";
+      const work = async () => {
+        let request;
+        try {
+          request = JSON.parse(line);
+        } catch {
+          return { ok: false, error: { code: "REFUSED", message: "invalid request" } };
+        }
+        if (request?.op !== "apply" || !request.claim)
+          return { ok: false, error: { code: "REFUSED", message: "unknown operation" } };
+        try {
+          return { ok: true, evidence: await executeLifecycleAction(options.profile, request.claim, options.exec, options.tcpProbe, options.fetch) };
+        } catch (cause) {
+          return { ok: false, error: { code: "FAILED", message: cause instanceof Error ? cause.message : "lifecycle action failed" } };
+        }
+      };
+      const response = tail.then(work, work);
+      tail = response;
+      response.then((value) => socket.end(`${JSON.stringify(value)}
+`));
+    });
+    socket.on("error", () => socket.destroy());
+  });
+  server.listen(socketPath, () => chmodSync(socketPath, 432));
+  return {
+    server,
+    async stop() {
+      await new Promise((resolve) => server.close(() => resolve()));
+      await tail;
+    }
+  };
+}
+function requestLifecycleAction(claim, socketPath = DEFAULT_LIFECYCLE_HELPER_SOCKET) {
+  return new Promise((resolve, reject) => {
+    const socket = connect(socketPath, () => socket.write(`${JSON.stringify({ op: "apply", claim })}
+`));
+    socket.setTimeout(ACTION_TIMEOUT_MS + 1e4, () => {
+      socket.destroy();
+      reject(new Error("lifecycle helper response timed out"));
+    });
+    let buffer = "";
+    socket.on("data", (chunk) => {
+      buffer += chunk.toString("utf8");
+      const newline = buffer.indexOf(`
+`);
+      if (newline < 0)
+        return;
+      socket.end();
+      try {
+        const response = JSON.parse(buffer.slice(0, newline));
+        if (response.ok)
+          resolve(response.evidence);
+        else
+          reject(new Error(response.error.message));
+      } catch (cause) {
+        reject(cause);
+      }
+    });
+    socket.on("error", reject);
+  });
+}
+export {
+  validateLifecycleProfile,
+  startLifecycleHelper,
+  spawnLifecycleCommand,
+  requestLifecycleAction,
+  loadLifecycleProfile,
+  executeLifecycleAction,
+  DEFAULT_LIFECYCLE_HELPER_SOCKET
+};