miravo 0.6.0 → 0.6.2

package/src/lib/daemon-registry.ts

@@ -1,343 +0,0 @@
-/**
- * Daemon registry — tracks background simulation processes.
- *
- * Each background simulation gets a JSON entry at `~/.miravo/daemon/<name>.json`.
- * Management commands (ps, stop, logs, rm) use this registry to discover and
- * interact with running simulations via their admin HTTP server.
- */
-
-import { mkdir, open, readdir, rename, unlink } from "node:fs/promises";
-import { resolveMiravoHome } from "@miravo/core";
-import { MiravoError, SimulationNameSchema } from "@miravo/shared";
-import { z } from "zod";
-
-// ---------------------------------------------------------------------------
-// Schema (CLI-only — not in packages/shared/)
-// ---------------------------------------------------------------------------
-
-const DaemonAdapterEntrySchema = z.object({
-  port: z.number().int().positive(),
-  host: z.string().min(1),
-});
-
-const DaemonRegistryEntrySchema = z.object({
-  name: z.string().min(1),
-  pid: z.number().int().positive(),
-  adminPort: z.number().int().positive(),
-  adminHost: z.string().min(1),
-  adapters: z.record(z.string(), DaemonAdapterEntrySchema),
-  templatePath: z.string().min(1),
-  startedAt: z.string().min(1),
-  seed: z.number().finite(),
-  runId: z.string().min(1),
-});
-
-type DaemonAdapterEntry = z.infer<typeof DaemonAdapterEntrySchema>;
-export type DaemonRegistryEntry = z.infer<typeof DaemonRegistryEntrySchema>;
-
-interface EntryIdentityResult {
-  readonly status: "dead" | "verified" | "mismatch" | "unreachable";
-  readonly ready: boolean;
-}
-
-// ---------------------------------------------------------------------------
-// Directory resolution
-// ---------------------------------------------------------------------------
-
-/** Returns the path to the daemon registry directory (`~/.miravo/daemon/`). */
-function daemonDir(): string {
-  return `${resolveMiravoHome()}/daemon`;
-}
-
-/**
- * Validate a simulation name to prevent path traversal.
- * Reuses the shared SimulationNameSchema (lowercase alphanumeric + hyphens).
- */
-function validateName(name: string): void {
-  const result = SimulationNameSchema.safeParse(name);
-  if (!result.success) {
-    throw new MiravoError(
-      `Invalid simulation name: "${name}".`,
-      "Use lowercase letters, numbers, and hyphens only (e.g., my-sim-1).",
-    );
-  }
-}
-
-function entryPath(name: string): string {
-  validateName(name);
-  return `${daemonDir()}/${name}.json`;
-}
-
-// ---------------------------------------------------------------------------
-// CRUD operations
-// ---------------------------------------------------------------------------
-
-/** Write a registry entry atomically (temp file + rename). */
-export async function writeEntry(entry: DaemonRegistryEntry): Promise<void> {
-  const dir = daemonDir();
-  await mkdir(dir, { recursive: true });
-  const filePath = entryPath(entry.name);
-  const tmpPath = `${filePath}.${process.pid}.tmp`;
-  await Bun.write(tmpPath, JSON.stringify(entry, null, 2));
-  await rename(tmpPath, filePath);
-}
-
-/**
- * Acquire an exclusive lock for a simulation name.
- * Prevents concurrent `start -d` from spawning duplicate daemons.
- * Returns a release function; call it when done (even on error).
- *
- * Stale locks from crashed processes are detected via PID liveness and
- * cleaned up automatically before retrying.
- *
- * @throws MiravoError if the name is already locked by a live process.
- */
-export async function acquireNameLock(name: string): Promise<() => Promise<void>> {
-  validateName(name);
-  const dir = daemonDir();
-  await mkdir(dir, { recursive: true });
-  const lockPath = `${dir}/${name}.lock`;
-
-  const tryAcquire = async (): Promise<void> => {
-    try {
-      // O_CREAT | O_EXCL — fails if file already exists
-      const handle = await open(lockPath, "wx");
-      await handle.writeFile(String(process.pid));
-      await handle.close();
-    } catch (error) {
-      if ((error as NodeJS.ErrnoException).code === "EEXIST") {
-        // Check if the lock belongs to a live process or is stale (crashed).
-        try {
-          const content = await Bun.file(lockPath).text();
-          const pid = parseInt(content.trim(), 10);
-          if (!Number.isNaN(pid) && !isPidAlive(pid)) {
-            // Stale lock from a crashed process — remove and retry.
-            await unlink(lockPath);
-            return tryAcquire();
-          }
-        } catch {
-          // Lock file disappeared between EEXIST and reading — retry.
-          return tryAcquire();
-        }
-        throw new MiravoError(
-          `Another 'miravo start -d' is already starting simulation "${name}".`,
-          "Wait for the other start to complete, or remove the lock with 'miravo rm'.",
-        );
-      }
-      throw error;
-    }
-  };
-
-  await tryAcquire();
-
-  return async () => {
-    try {
-      await unlink(lockPath);
-    } catch {
-      // Ignore — lock may have been cleaned up already
-    }
-  };
-}
-
-/** Read and validate a registry entry. Returns null if missing or invalid. */
-export async function readEntry(name: string): Promise<DaemonRegistryEntry | null> {
-  const filePath = entryPath(name);
-  const file = Bun.file(filePath);
-  if (!(await file.exists())) return null;
-  try {
-    const content = await file.text();
-    const parsed: unknown = JSON.parse(content);
-    const result = DaemonRegistryEntrySchema.safeParse(parsed);
-    return result.success ? result.data : null;
-  } catch {
-    return null;
-  }
-}
-
-/** Remove a registry entry. Safe if file does not exist. */
-export async function removeEntry(name: string): Promise<void> {
-  try {
-    await unlink(entryPath(name));
-  } catch (error) {
-    if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
-  }
-}
-
-/** List all valid registry entries. Invalid files are silently skipped. */
-export async function listEntries(): Promise<readonly DaemonRegistryEntry[]> {
-  const dir = daemonDir();
-  let files: string[];
-  try {
-    files = await readdir(dir);
-  } catch (error) {
-    if ((error as NodeJS.ErrnoException).code === "ENOENT") return [];
-    throw error;
-  }
-
-  const entries: DaemonRegistryEntry[] = [];
-  for (const file of files) {
-    if (!file.endsWith(".json") || file.endsWith(".tmp")) continue;
-    const name = file.slice(0, -5); // strip .json
-    const entry = await readEntry(name);
-    if (entry) entries.push(entry);
-  }
-  return entries;
-}
-
-// ---------------------------------------------------------------------------
-// Liveness checks
-// ---------------------------------------------------------------------------
-
-/** Check if a PID is alive using signal 0. */
-export function isPidAlive(pid: number): boolean {
-  try {
-    process.kill(pid, 0);
-    return true;
-  } catch (err) {
-    if (
-      err &&
-      typeof err === "object" &&
-      "code" in err &&
-      (err.code === "EPERM" || err.code === "EACCES")
-    ) {
-      return true; // process exists but we can't signal it
-    }
-    return false;
-  }
-}
-
-/**
- * Verify that a registry entry corresponds to a live Miravo simulation.
- *
- * Two-step check:
- * 1. PID alive (fast, avoids network I/O for dead processes)
- * 2. RunId matches via GET /readyz (guards against PID reuse after reboot)
- */
-export async function probeEntryIdentity(entry: DaemonRegistryEntry): Promise<EntryIdentityResult> {
-  if (!isPidAlive(entry.pid)) {
-    return { status: "dead", ready: false };
-  }
-
-  try {
-    const url = `http://${entry.adminHost}:${entry.adminPort}/readyz`;
-    const response = await fetch(url, { signal: AbortSignal.timeout(2_000) });
-    const bodyText = await response.text();
-    let body: unknown;
-    try {
-      body = JSON.parse(bodyText) as unknown;
-    } catch {
-      return { status: "mismatch", ready: false };
-    }
-    if (
-      typeof body !== "object" ||
-      body === null ||
-      !("runId" in body) ||
-      typeof body["runId"] !== "string"
-    ) {
-      return { status: "mismatch", ready: false };
-    }
-    if (body["runId"] !== entry.runId) {
-      return { status: "mismatch", ready: false };
-    }
-    return { status: "verified", ready: response.ok };
-  } catch {
-    // Keep the registry entry when the admin server is temporarily unreachable,
-    // but do not treat the identity as safe for raw signal delivery.
-    return { status: "unreachable", ready: false };
-  }
-}
-
-/**
- * Remove all registry entries whose processes are no longer alive.
- * Uses full identity verification (PID + runId) to handle PID reuse.
- */
-export async function sweepStaleEntries(): Promise<void> {
-  const entries = await listEntries();
-  for (const entry of entries) {
-    const identity = await probeEntryIdentity(entry);
-    if (identity.status === "dead" || identity.status === "mismatch") {
-      await removeEntry(entry.name);
-    }
-  }
-}
-
-// ---------------------------------------------------------------------------
-// Conflict detection
-// ---------------------------------------------------------------------------
-
-/**
- * Check for port conflicts against live registry entries.
- *
- * @param ports - Map of label → port to check (e.g., "admin" → 8080, "mqtt" → 1883)
- * @param excludeName - Optional entry name to exclude (for re-checking own entry)
- * @returns Array of human-readable conflict messages (empty = no conflicts)
- */
-export async function checkPortConflicts(
-  ports: ReadonlyMap<string, number>,
-  excludeName?: string,
-): Promise<readonly string[]> {
-  const entries = await listEntries();
-  const conflicts: string[] = [];
-
-  for (const entry of entries) {
-    if (entry.name === excludeName) continue;
-    // Use PID check only (not full identity verification) for performance —
-    // port conflicts are about actual port usage, not Miravo identity.
-    if (!isPidAlive(entry.pid)) continue;
-
-    // Check admin port
-    for (const [label, port] of ports) {
-      if (port === entry.adminPort) {
-        conflicts.push(
-          `Port ${port} (${label}) is already in use by simulation "${entry.name}". Stop it first: miravo stop ${entry.name}`,
-        );
-      }
-      // Check adapter ports
-      for (const [adapterName, adapter] of Object.entries(entry.adapters) as [
-        string,
-        DaemonAdapterEntry,
-      ][]) {
-        if (port === adapter.port) {
-          conflicts.push(
-            `Port ${port} (${label}) conflicts with ${adapterName} port of simulation "${entry.name}". Stop it first: miravo stop ${entry.name}`,
-          );
-        }
-      }
-    }
-  }
-
-  return conflicts;
-}
-
-/**
- * Check if a simulation name is already in use by a live entry.
- * Removes stale entries as a side effect.
- *
- * @returns The alive entry if the name is taken, null otherwise.
- */
-export async function checkNameConflict(name: string): Promise<DaemonRegistryEntry | null> {
-  const entry = await readEntry(name);
-  if (!entry) return null;
-
-  const identity = await probeEntryIdentity(entry);
-  if (identity.status === "verified" || identity.status === "unreachable") return entry;
-
-  if (identity.status === "dead" || identity.status === "mismatch") {
-    // Stale entry — clean it up
-    await removeEntry(name);
-  }
-  return null;
-}
-
-// ---------------------------------------------------------------------------
-// Display helpers
-// ---------------------------------------------------------------------------
-
-/**
- * Map bind addresses to connectable addresses for display.
- * `0.0.0.0` and `::` are replaced with `127.0.0.1`.
- */
-export function displayHost(host: string): string {
-  if (host === "0.0.0.0" || host === "::") return "127.0.0.1";
-  return host;
-}