@forgezero/agent 0.1.41 → 0.1.43

package/dist/recovery-host.d.ts

@@ -0,0 +1,7 @@
+export interface RecoveryHostResult {
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+}
+export type RecoveryHostExec = (argv: readonly string[]) => Promise<RecoveryHostResult>;
+export declare function runRecoveryHost(args: readonly string[], run?: RecoveryHostExec): Promise<void>;

package/dist/recovery-host.js

@@ -0,0 +1,124 @@
+// src/recovery-host.ts
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { hostname } from "node:os";
+import { join } from "node:path";
+var execute = async (argv) => {
+  const child = Bun.spawn([...argv], { stdout: "pipe", stderr: "pipe", env: { PATH: "/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin" } });
+  const [stdout, stderr, exitCode] = await Promise.all([new Response(child.stdout).text(), new Response(child.stderr).text(), child.exited]);
+  return { stdout, stderr, exitCode };
+};
+var checked = async (run, argv, expected = 0) => {
+  const result = await run(argv);
+  if (result.exitCode !== expected)
+    throw new Error(`${argv[0]} failed (${result.exitCode})`);
+  return result;
+};
+var activeSlot = () => {
+  const slot = readFileSync("/opt/forgezero/.forge-slot", "utf8").trim();
+  if (slot !== "blue" && slot !== "green")
+    throw new Error("invalid active slot");
+  return slot;
+};
+var exactState = (path, expected) => {
+  if (!readFileSync(path, "utf8").split(`
+`).includes(expected))
+    throw new Error(`state mismatch: ${expected}`);
+};
+var nonEmpty = (path) => {
+  if (!existsSync(path) || !statSync(path).isFile() || statSync(path).size < 1)
+    throw new Error(`required file missing: ${path}`);
+};
+var option = (args, name) => {
+  const value = args.find((arg) => arg.startsWith(`--${name}=`))?.slice(name.length + 3);
+  if (!value || /[\0\r\n]/.test(value))
+    throw new Error(`missing or invalid --${name}`);
+  return value;
+};
+var unit = (value) => {
+  if (!/^forgezero-dr-[a-z0-9-]{1,64}$/.test(value))
+    throw new Error("invalid recovery unit");
+  return value;
+};
+async function runRecoveryHost(args, run = execute) {
+  const action = args[0];
+  if (action === "preflight") {
+    const identity = option(args, "identity");
+    if (hostname().split(".")[0] !== identity)
+      throw new Error("recovery host identity mismatch");
+    const profile = option(args, "profile");
+    const role = option(args, "db-role");
+    const software = option(args, "software-profile");
+    const apiOrigin = option(args, "api-origin");
+    const edgeHostname = option(args, "edge-hostname");
+    const databaseAddress = args.find((arg) => arg.startsWith("--db-address="))?.slice(13);
+    exactState("/opt/forgezero/.forge-state", `profile=${profile}`);
+    exactState("/opt/forgezero/.forge-state", `db_role=${role}`);
+    exactState("/opt/forgezero/.forge-state", `software_profile=${software}`);
+    if (databaseAddress)
+      exactState("/opt/forgezero/.forge-state", `db_address=${databaseAddress}`);
+    exactState("/opt/forgezero/shared/.env", "ARANGO_DB=fz");
+    exactState("/opt/forgezero/shared/.env", "FZ_DATABASE_MODE=platform");
+    exactState("/opt/forgezero/shared/.env", `API_ORIGIN=${apiOrigin}`);
+    exactState("/opt/forgezero/shared/.env", `FZ_NODE_HOSTNAME=${edgeHostname}`);
+    nonEmpty("/etc/forgezero/creds/arangodb-jwt.cred");
+    const hasDatabase = role !== "none";
+    if (hasDatabase) {
+      nonEmpty("/etc/forgezero/creds/backup-s3-secret.cred");
+      nonEmpty("/etc/forgezero/creds/backup-recovery-root.cred");
+    }
+    const slot = activeSlot();
+    nonEmpty(join("/opt/forgezero/slots", slot, "src/server/maintenance/restore-backup.ts"));
+    nonEmpty(join("/opt/forgezero/slots", slot, "src/server/maintenance/verify-recovery-cluster.ts"));
+    await checked(run, ["/usr/bin/test", "-x", "/usr/local/bin/fz"]);
+    await checked(run, ["/usr/bin/systemctl", "is-active", "--quiet", "forgezero-db.service"], hasDatabase ? 0 : 3);
+    if (args.includes("--require-stopped")) {
+      await checked(run, ["/usr/bin/systemctl", "is-active", "--quiet", "forgezero@blue.service"], 3);
+      await checked(run, ["/usr/bin/systemctl", "is-active", "--quiet", "forgezero@green.service"], 3);
+    }
+    return;
+  }
+  if (action === "fence") {
+    await checked(run, ["/usr/bin/systemctl", "stop", "forgezero@blue.service", "forgezero@green.service"]);
+    await checked(run, ["/usr/bin/systemctl", "is-active", "--quiet", "forgezero@blue.service"], 3);
+    await checked(run, ["/usr/bin/systemctl", "is-active", "--quiet", "forgezero@green.service"], 3);
+    const role = option(args, "db-role");
+    await checked(run, ["/usr/bin/systemctl", "is-active", "--quiet", "forgezero-db.service"], role === "none" ? 3 : 0);
+    return;
+  }
+  if (action === "start-active") {
+    const slot = activeSlot();
+    const inactive = slot === "blue" ? "green" : "blue";
+    await checked(run, ["/usr/bin/systemctl", "stop", `forgezero@${inactive}.service`]);
+    await checked(run, ["/usr/bin/systemctl", "start", `forgezero@${slot}.service`]);
+    await checked(run, ["/usr/bin/systemctl", "is-active", "--quiet", `forgezero@${slot}.service`]);
+    await checked(run, ["/usr/bin/systemctl", "is-active", "--quiet", `forgezero@${inactive}.service`], 3);
+    return;
+  }
+  if (action === "maintenance") {
+    const separator = args.indexOf("--");
+    if (separator < 0 || separator === args.length - 1)
+      throw new Error("maintenance requires fixed fz argv after --");
+    const fzArgs = args.slice(separator + 1);
+    if (fzArgs[0] !== "db" || fzArgs.some((arg) => /[\0\r\n]/.test(arg)))
+      throw new Error("maintenance accepts only fz db argv");
+    const slot = activeSlot();
+    const properties = [
+      "--property=User=forgezero",
+      `--property=WorkingDirectory=/opt/forgezero/slots/${slot}`,
+      "--property=Environment=NODE_ENV=production",
+      "--property=EnvironmentFile=/opt/forgezero/shared/.env",
+      "--property=LoadCredentialEncrypted=arangodb-jwt:/etc/forgezero/creds/arangodb-jwt.cred",
+      ...args.includes("--fleet-fenced") ? ["--property=Environment=FZ_RECOVERY_FLEET_FENCED=all-api-and-scheduler-replicas-are-stopped"] : [],
+      ...args.includes("--backup-credentials") ? [
+        "--property=LoadCredentialEncrypted=backup-s3-secret:/etc/forgezero/creds/backup-s3-secret.cred",
+        "--property=LoadCredentialEncrypted=backup-recovery-root:/etc/forgezero/creds/backup-recovery-root.cred"
+      ] : []
+    ];
+    await checked(run, ["/usr/bin/systemd-run", "--quiet", "--wait", "--pipe", "--collect", `--unit=${unit(option(args, "unit"))}`, ...properties, "/usr/local/bin/fz", ...fzArgs]);
+    return;
+  }
+  throw new Error("unknown recovery-host action");
+}
+export {
+  runRecoveryHost
+};

package/dist/service-supervisor.d.ts

@@ -0,0 +1,42 @@
+import { type DeploymentService } from './definition';
+export declare const SERVICE_STATE_DIRECTORY = "/var/lib/forgezero/services";
+export declare const SERVICE_CONFIG_DIRECTORY = "/etc/forgezero/services";
+export declare const SERVICE_UNIT_DIRECTORY = "/etc/systemd/system";
+export declare const SERVICE_NGINX_DIRECTORY = "/etc/nginx/conf.d";
+export interface ServiceActivationRequest {
+    key: string;
+    revision: string;
+    release: string;
+    root: string;
+    service: DeploymentService;
+}
+export interface ServiceActivationState {
+    format: 1;
+    id: string;
+    key: string;
+    revision: string;
+    strategy: DeploymentService['strategy'];
+    publicPort: number;
+    applicationPorts: number[];
+    activeSlot: 0 | 1;
+    healthPath: string;
+    updatedAtTs: number;
+}
+export interface ServiceSupervisorHost {
+    write(path: string, content: string, mode: number): void;
+    read(path: string): string;
+    exists(path: string): boolean;
+    list(path: string): string[];
+    realpath(path: string): string;
+    mkdir(path: string, mode: number): void;
+    remove(path: string): void;
+    exec(argv: readonly string[]): Promise<{
+        exitCode: number;
+        output: string;
+    }>;
+    health(port: number, path: string): Promise<boolean>;
+    sleep(ms: number): Promise<void>;
+    now(): number;
+}
+/** Serialized by the root helper. Starts the new slot, proves health, switches nginx, then drains old. */
+export declare function activateSupervisedService(request: ServiceActivationRequest, host?: ServiceSupervisorHost): Promise<ServiceActivationState>;

package/dist/software-helper.d.ts

@@ -1,12 +1,16 @@
 import { type Server } from 'node:net';
 import { ensureSoftwareRequirements, type SoftwareRequirement } from './software';
+import { activateSupervisedService, type ServiceActivationRequest, type ServiceActivationState } from './service-supervisor';
 export declare const DEFAULT_SOFTWARE_HELPER_SOCKET = "/run/forgezero-software/helper.sock";
 export declare const SOFTWARE_HELPER_GROUP = "forgezero-software";
 export declare const SOFTWARE_HELPER_UNIT_PATH = "/etc/systemd/system/forgezero-software-helper.service";
 export declare function startSoftwareHelper(options?: {
     socketPath?: string;
     ensure?: typeof ensureSoftwareRequirements;
+    activate?: typeof activateSupervisedService;
+    allowedRoot?: string;
 }): Server;
+export declare function requestServiceActivation(request: ServiceActivationRequest, socketPath?: string, timeoutMs?: number): Promise<ServiceActivationState>;
 export declare function requestSoftware(requirements: readonly SoftwareRequirement[], socketPath?: string, timeoutMs?: number): Promise<Array<{
     id: string;
     version: string;