@forgezero/agent 0.1.2 → 0.1.10

package/dist/compute.js

@@ -0,0 +1,150 @@
+// src/compute.ts
+class ComputeError extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+    this.name = "ComputeError";
+  }
+}
+var NAME = /^[a-z][a-z0-9-]{1,30}[a-z0-9]$/;
+var unitName = (name) => {
+  if (!NAME.test(name)) {
+    throw new ComputeError("BAD_NAME", `"${name}" is not a usable guest name — lower case, digits and hyphens, 3-32 characters.`);
+  }
+  return `forgezero-guest@${name}.service`;
+};
+function qemuArgv(spec) {
+  if (spec.vcpu < 1 || spec.memoryGib < 1) {
+    throw new ComputeError("BAD_SPEC", "a guest needs at least 1 vCPU and 1 GiB");
+  }
+  const argv = [
+    "/usr/bin/qemu-system-x86_64",
+    "-name",
+    spec.name,
+    "-accel",
+    "kvm",
+    "-cpu",
+    "host",
+    "-m",
+    `${spec.memoryGib}G`,
+    "-smp",
+    String(spec.vcpu)
+  ];
+  if (spec.confidential) {
+    const { cbitpos, reducedPhysBits, policy } = spec.confidential;
+    argv.push("-machine", `q35,confidential-guest-support=snp,memory-backend=ram`, "-object", `memory-backend-memfd,id=ram,size=${spec.memoryGib}G,share=true`, "-object", `sev-snp-guest,id=snp,cbitpos=${cbitpos},reduced-phys-bits=${reducedPhysBits},policy=${policy}`, "-bios", "/usr/share/ovmf/OVMF.fd");
+  } else {
+    argv.push("-machine", "q35");
+  }
+  argv.push("-drive", `file=${spec.disk},format=raw,if=none,id=disk0,cache=none,aio=native`, "-device", "virtio-blk-pci,drive=disk0,iommu_platform=on", "-drive", `file=${spec.seed},format=raw,if=none,id=seed0,readonly=on`, "-device", "virtio-blk-pci,drive=seed0,iommu_platform=on", "-netdev", spec.tap ? `tap,id=net0,ifname=${spec.tap},script=no,downscript=no` : `bridge,id=net0,br=${spec.bridge}`, "-device", `virtio-net-pci,netdev=net0,mac=${spec.mac},iommu_platform=on`, "-display", "none");
+  if (spec.consoleLog)
+    argv.push("-serial", `file:${spec.consoleLog}`);
+  return argv;
+}
+function guestUnit(spec) {
+  const argv = qemuArgv(spec).map((part) => /[\s"']/.test(part) ? JSON.stringify(part) : part).join(" ");
+  if (spec.egress && !spec.tap) {
+    throw new ComputeError("BAD_SPEC", "shaped egress needs a stable tap device");
+  }
+  const tapSetup = spec.tap ? [
+    `ExecStartPre=-/usr/sbin/ip link del ${spec.tap}`,
+    `ExecStartPre=/usr/sbin/ip tuntap add dev ${spec.tap} mode tap`,
+    `ExecStartPre=/usr/sbin/ip link set ${spec.tap} master ${spec.bridge}`,
+    `ExecStartPre=/usr/sbin/ip link set ${spec.tap} up`,
+    ...spec.egress ? shapeEgressUnitDirectives(spec.tap, spec.egress.guaranteedMbps, spec.egress.burstMbps) : [],
+    `ExecStopPost=-/usr/sbin/ip link del ${spec.tap}`
+  ].join(`
+`) : "";
+  return `[Unit]
+Description=ForgeZero guest ${spec.name}
+Documentation=https://www.forgezero.net
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+Slice=forgezero-guests.slice
+${tapSetup}
+ExecStart=${argv}
+Restart=always
+RestartSec=5
+${spec.allowedCpus ? `AllowedCPUs=${spec.allowedCpus}
+` : ""}${spec.allowedMemoryNodes ? `AllowedMemoryNodes=${spec.allowedMemoryNodes}
+` : ""}# The affinity belongs to the unit rather than only QEMU's vCPU threads. Its
+# emulator and IO threads can otherwise run on a different tenant's cores.
+# The agent is NOT the parent. Restarting or upgrading fz-agent must never stop
+# a tenant's compute, which is the whole reason this is a unit rather than a
+# child process.
+KillMode=mixed
+TimeoutStopSec=120
+
+[Install]
+WantedBy=multi-user.target
+`;
+}
+function parseCensus(psOutput) {
+  const guests = [];
+  for (const line of psOutput.split(`
+`)) {
+    const trimmed = line.trim();
+    if (!trimmed || !trimmed.includes("qemu-system"))
+      continue;
+    const pid = Number(trimmed.split(/\s+/)[0]);
+    const name = /-name\s+([^\s]+)/.exec(trimmed)?.[1];
+    if (!Number.isFinite(pid) || !name)
+      continue;
+    const disks = [...trimmed.matchAll(/file=([^,\s]+)/g)].map((match) => match[1]);
+    guests.push({ name, pid, disks });
+  }
+  return guests;
+}
+var deviceInUse = (census, device) => census.some((guest) => guest.disks.includes(device));
+function shapeEgressCommands(tap, mbps, burstMbps = mbps * 2) {
+  if (!/^[a-z][a-z0-9]{0,14}$/.test(tap)) {
+    throw new ComputeError("BAD_SPEC", `"${tap}" is not a device name`);
+  }
+  if (mbps <= 0)
+    return [
+      `tc qdisc del dev ${tap} root 2>/dev/null || true`,
+      `tc qdisc del dev ${tap} ingress 2>/dev/null || true`
+    ];
+  const ceiling = `${Math.floor(Math.max(burstMbps, mbps))}mbit`;
+  return [
+    `tc qdisc del dev ${tap} root 2>/dev/null || true`,
+    `tc qdisc del dev ${tap} ingress 2>/dev/null || true`,
+    `tc qdisc add dev ${tap} handle ffff: ingress`,
+    `tc filter add dev ${tap} parent ffff: protocol all u32 match u32 0 0 action police rate ${ceiling} burst 16mb conform-exceed drop`
+  ];
+}
+function shapeEgressUnitDirectives(tap, guaranteedMbps, burstMbps) {
+  if (!/^[a-z][a-z0-9]{0,14}$/.test(tap)) {
+    throw new ComputeError("BAD_SPEC", `"${tap}" is not a device name`);
+  }
+  if (!Number.isInteger(guaranteedMbps) || guaranteedMbps < 0 || !Number.isInteger(burstMbps) || burstMbps < guaranteedMbps) {
+    throw new ComputeError("BAD_SPEC", "egress rates must be whole numbers and burst must cover the guarantee");
+  }
+  const clear = [
+    `ExecStartPre=-/usr/sbin/tc qdisc del dev ${tap} root`,
+    `ExecStartPre=-/usr/sbin/tc qdisc del dev ${tap} ingress`
+  ];
+  if (guaranteedMbps === 0)
+    return clear;
+  return [
+    ...clear,
+    `ExecStartPre=/usr/sbin/tc qdisc add dev ${tap} handle ffff: ingress`,
+    `ExecStartPre=/usr/sbin/tc filter add dev ${tap} parent ffff: protocol all u32 match u32 0 0 action police rate ${burstMbps}mbit burst 16mb conform-exceed drop`
+  ];
+}
+var tapFor = (guestIndex) => `tap${guestIndex}`;
+export {
+  unitName,
+  tapFor,
+  shapeEgressUnitDirectives,
+  shapeEgressCommands,
+  qemuArgv,
+  parseCensus,
+  guestUnit,
+  deviceInUse,
+  ComputeError
+};

package/dist/compute.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/control.d.ts

@@ -0,0 +1,57 @@
+import { type Server } from 'node:net';
+import type { DeploymentManager, DeploymentRequest, DeploymentResult } from './deployment';
+export declare const DEFAULT_CONTROL_SOCKET = "/run/forgezero/control.sock";
+export type ControlRequest = {
+    op: 'deploy';
+    request?: DeploymentRequest;
+} | {
+    op: 'status';
+} | {
+    op: 'pause';
+} | {
+    op: 'resume';
+} | {
+    op: 'pause-key';
+    key: string;
+} | {
+    op: 'resume-key';
+    key: string;
+} | {
+    op: 'stop-key';
+    key: string;
+} | {
+    op: 'start-key';
+    key: string;
+} | {
+    op: 'cancel';
+    id: string;
+};
+export type ControlResponse = {
+    ok: true;
+    op: 'deploy';
+    taskId: string;
+    result: DeploymentResult;
+} | {
+    ok: true;
+    op: 'status';
+    queue: ReturnType<DeploymentManager['snapshot']>;
+} | {
+    ok: true;
+    op: Exclude<ControlRequest['op'], 'deploy' | 'status' | 'stop-key'>;
+    changed: boolean;
+} | {
+    ok: true;
+    op: 'stop-key';
+    changed: boolean;
+    removed: number;
+} | {
+    ok: false;
+    error: {
+        code: string;
+        message: string;
+    };
+};
+export declare function handleControl(manager: DeploymentManager, request: ControlRequest): Promise<ControlResponse>;
+/** Root/operator control is deliberately separate from the tenant vault socket. */
+export declare function startControlServer(manager: DeploymentManager, socketPath?: string): Server;
+export declare function requestControl(request: ControlRequest, socketPath?: string): Promise<ControlResponse>;

package/dist/control.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/definition.d.ts

@@ -0,0 +1,34 @@
+import type { Pipeline, PipelineStep } from './pipeline';
+export declare const PIPELINE_VERSION: 1;
+export interface SoftwareRequirement {
+    name: string;
+    check: string;
+    install: string;
+}
+export interface PipelineRole {
+    name: string;
+    count: number;
+    software: readonly SoftwareRequirement[];
+}
+export interface DeployStep extends PipelineStep {
+    phase: 'build' | 'release' | 'migrate' | 'health';
+    /** The coordinator runs this on one selected node, never on every replica. */
+    once?: boolean;
+    /** Run only when every named non-secret deployment coordinate has this value. */
+    when?: Readonly<Record<string, string>>;
+}
+export interface DeployDefinition {
+    version: typeof PIPELINE_VERSION;
+    name: string;
+    requireAttestation?: boolean;
+    roles: readonly PipelineRole[];
+    steps: readonly DeployStep[];
+}
+export declare class DefinitionError extends Error {
+    constructor(message: string);
+}
+/** Validate parsed YAML before any command from it is allowed to run. */
+export declare function parseDeployDefinition(value: unknown): DeployDefinition;
+export declare function phasePipeline(definition: DeployDefinition, phase: DeployStep['phase']): Pipeline;
+/** Turn one role's declared software checks into the same executable pipeline shape. */
+export declare function prerequisitePipeline(definition: DeployDefinition, roleName: string): Pipeline;

package/dist/definition.js

@@ -0,0 +1,159 @@
+// src/definition.ts
+var PIPELINE_VERSION = 1;
+
+class DefinitionError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "DefinitionError";
+  }
+}
+var record = (value, where) => {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new DefinitionError(`${where} must be an object.`);
+  }
+  return value;
+};
+var text = (value, where) => {
+  if (typeof value !== "string" || value.trim() === "") {
+    throw new DefinitionError(`${where} must be a non-empty string.`);
+  }
+  return value;
+};
+var exactKeys = (value, allowed, where) => {
+  const unknown = Object.keys(value).filter((key) => !allowed.includes(key));
+  if (unknown.length > 0)
+    throw new DefinitionError(`${where} contains unknown field(s): ${unknown.join(", ")}.`);
+};
+var RESERVED_STEP_ENV = new Set([
+  "PATH",
+  "HOME",
+  "SHELL",
+  "PWD",
+  "BUN_INSTALL",
+  "NODE_OPTIONS",
+  "LD_PRELOAD",
+  "LD_LIBRARY_PATH",
+  "GIT_SSH",
+  "GIT_SSH_COMMAND"
+]);
+function parseDeployDefinition(value) {
+  const root = record(value, "pipeline");
+  exactKeys(root, ["version", "name", "requireAttestation", "roles", "steps"], "pipeline");
+  if (root.version !== PIPELINE_VERSION) {
+    throw new DefinitionError(`pipeline.version must be ${PIPELINE_VERSION}.`);
+  }
+  if (!Array.isArray(root.roles) || root.roles.length === 0) {
+    throw new DefinitionError("pipeline.roles must contain at least one role.");
+  }
+  if (!Array.isArray(root.steps) || root.steps.length === 0) {
+    throw new DefinitionError("pipeline.steps must contain at least one step.");
+  }
+  const roles = root.roles.map((raw, index) => {
+    const role = record(raw, `roles[${index}]`);
+    exactKeys(role, ["name", "count", "software"], `roles[${index}]`);
+    const count = Number(role.count);
+    if (!Number.isSafeInteger(count) || count < 1) {
+      throw new DefinitionError(`roles[${index}].count must be a positive integer.`);
+    }
+    if (!Array.isArray(role.software)) {
+      throw new DefinitionError(`roles[${index}].software must be an array.`);
+    }
+    return {
+      name: text(role.name, `roles[${index}].name`),
+      count,
+      software: role.software.map((rawSoftware, softwareIndex) => {
+        const software = record(rawSoftware, `roles[${index}].software[${softwareIndex}]`);
+        exactKeys(software, ["name", "check", "install"], `roles[${index}].software[${softwareIndex}]`);
+        return {
+          name: text(software.name, `roles[${index}].software[${softwareIndex}].name`),
+          check: text(software.check, `roles[${index}].software[${softwareIndex}].check`),
+          install: text(software.install, `roles[${index}].software[${softwareIndex}].install`)
+        };
+      })
+    };
+  });
+  if (new Set(roles.map((role) => role.name)).size !== roles.length) {
+    throw new DefinitionError("pipeline.roles must have unique names.");
+  }
+  const phases = new Set(["build", "release", "migrate", "health"]);
+  const steps = root.steps.map((raw, index) => {
+    const step = record(raw, `steps[${index}]`);
+    exactKeys(step, ["name", "run", "phase", "secrets", "once", "always", "timeoutMs", "when"], `steps[${index}]`);
+    const phase = text(step.phase, `steps[${index}].phase`);
+    if (!phases.has(phase))
+      throw new DefinitionError(`steps[${index}].phase is not supported.`);
+    if (step.secrets !== undefined && (!Array.isArray(step.secrets) || step.secrets.some((name) => typeof name !== "string" || !/^[A-Z_][A-Z0-9_]*$/.test(name)))) {
+      throw new DefinitionError(`steps[${index}].secrets must contain names only.`);
+    }
+    if (Array.isArray(step.secrets) && new Set(step.secrets).size !== step.secrets.length) {
+      throw new DefinitionError(`steps[${index}].secrets must not contain duplicates.`);
+    }
+    if (Array.isArray(step.secrets) && step.secrets.some((name) => RESERVED_STEP_ENV.has(String(name)))) {
+      throw new DefinitionError(`steps[${index}].secrets may not replace process-control environment variables.`);
+    }
+    const timeoutMs = step.timeoutMs === undefined ? undefined : Number(step.timeoutMs);
+    if (timeoutMs !== undefined && (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 86400000)) {
+      throw new DefinitionError(`steps[${index}].timeoutMs must be an integer from 1 to 86400000.`);
+    }
+    let when;
+    if (step.when !== undefined) {
+      const conditions = record(step.when, `steps[${index}].when`);
+      when = {};
+      for (const [name, expected] of Object.entries(conditions)) {
+        if (!/^[A-Z_][A-Z0-9_]*$/.test(name) || typeof expected !== "string" || expected.length === 0) {
+          throw new DefinitionError(`steps[${index}].when must map environment names to non-empty strings.`);
+        }
+        when[name] = expected;
+      }
+      if (Object.keys(when).length === 0)
+        throw new DefinitionError(`steps[${index}].when must not be empty.`);
+    }
+    return {
+      name: text(step.name, `steps[${index}].name`),
+      run: text(step.run, `steps[${index}].run`),
+      phase,
+      secrets: step.secrets,
+      once: step.once === true,
+      always: step.always === true,
+      timeoutMs,
+      when
+    };
+  });
+  if (new Set(steps.map((step) => step.name)).size !== steps.length) {
+    throw new DefinitionError("pipeline.steps must have unique names.");
+  }
+  return {
+    version: PIPELINE_VERSION,
+    name: text(root.name, "pipeline.name"),
+    requireAttestation: root.requireAttestation === true,
+    roles,
+    steps
+  };
+}
+function phasePipeline(definition, phase) {
+  return {
+    name: `${definition.name}:${phase}`,
+    requireAttestation: definition.requireAttestation,
+    steps: definition.steps.filter((step) => step.phase === phase)
+  };
+}
+function prerequisitePipeline(definition, roleName) {
+  const role = definition.roles.find((candidate) => candidate.name === roleName);
+  if (!role)
+    throw new DefinitionError(`pipeline role does not exist: ${roleName}.`);
+  return {
+    name: `${definition.name}:prerequisites:${role.name}`,
+    requireAttestation: definition.requireAttestation,
+    steps: role.software.map((software) => ({
+      name: `prepare ${software.name}`,
+      run: `${software.check} >/dev/null 2>&1 || { ${software.install}; ${software.check}; }`
+    }))
+  };
+}
+export {
+  prerequisitePipeline,
+  phasePipeline,
+  parseDeployDefinition,
+  PIPELINE_VERSION,
+  DefinitionError
+};

package/dist/definition.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/deployment-pull.d.ts

@@ -0,0 +1,61 @@
+import type { NodeKeyPair } from '@forgezero/runtime/identity';
+import type { DeploymentManager, DeploymentResult, GitSourceAuth } from './deployment';
+export interface RemoteDeploymentClaim {
+    runKey: string;
+    pipelineKey: string;
+    revision: string;
+    claimToken: string;
+    claimExpiresAtTs: number;
+    attempt: number;
+    source: {
+        repository: string;
+        branch: string;
+        role: string;
+        knownHosts?: string;
+        auth?: GitSourceAuth;
+    };
+}
+export interface DeploymentPullOptions {
+    apiUrl: string;
+    nodeKey: string;
+    keys: NodeKeyPair;
+    manager?: DeploymentManager;
+    /** Automatic computes construct one manager from the server-owned source coordinates. */
+    managerFor?: (claim: RemoteDeploymentClaim) => DeploymentManager;
+    fetch?: (input: URL, init: RequestInit) => Promise<Response>;
+    intervalMs?: number;
+    /** Concurrent claim workers. Same-key execution still serializes in the manager queue. */
+    parallelism?: number;
+    requestTimeoutMs?: number;
+    completionAttempts?: number;
+    sleep?: (ms: number) => Promise<void>;
+    now?: () => number;
+    renewRetryMs?: number;
+    setTimer?: (callback: () => void, ms: number) => unknown;
+    clearTimer?: (handle: unknown) => void;
+    onEvent?: (event: string, detail?: unknown) => void;
+}
+export type PullResult = {
+    status: 'idle';
+} | {
+    status: 'deployed';
+    claim: RemoteDeploymentClaim;
+    result: DeploymentResult;
+} | {
+    status: 'failed';
+    claim: RemoteDeploymentClaim;
+    reason: string;
+};
+/** Claim at most one job and await its exact deployment result before reporting. */
+export declare function pullDeploymentOnce(options: DeploymentPullOptions): Promise<PullResult>;
+/**
+ * Bounded outbound intake for the deployment manager.
+ *
+ * Claim workers may receive different pipeline keys concurrently. Managers
+ * still own execution ordering: a single pipeline key is serial even when two
+ * of its claims were fetched by different workers.
+ */
+export declare function startDeploymentPull(options: DeploymentPullOptions): {
+    stop(): Promise<void>;
+    readonly active: boolean;
+};

package/dist/deployment-pull.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/deployment-runner.d.ts

@@ -0,0 +1,23 @@
+import { type Server } from 'node:net';
+import type { CommandInput, CommandResult } from './deployment';
+export declare const DEFAULT_DEPLOYMENT_RUNNER_SOCKET = "/run/forgezero-deploy/runner.sock";
+/**
+ * Execute tenant-controlled project commands under a separate Unix identity.
+ *
+ * This daemon has no LoadCredential directive and cannot open the owner-only
+ * agent socket. The credential-bearing agent may submit an exact command and
+ * only the secrets named for that step; the subprocess can steal those values,
+ * because it is the intended consumer, but cannot steal the node or Git key.
+ */
+export declare function startDeploymentRunner(options: {
+    root: string;
+    home: string;
+    socketPath?: string;
+    /** systemd socket activation passes the agent-owned listener as fd 3. */
+    listenFd?: number;
+    exec?: (input: CommandInput, home: string) => Promise<CommandResult>;
+}): {
+    server: Server;
+    stop(): Promise<void>;
+};
+export declare function requestDeploymentCommand(input: CommandInput, socketPath?: string): Promise<CommandResult>;