Skip to content

armgit / ruflo

Public Imported from GitHub
0

🌊 The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated

10.3 KB
Raw Blame
/**
 * meta-proxy process lifecycle (ADR-307) β€” start/stop/status/logs.
 *
 * Adapts daemon.ts's proven pattern (PID file, O_EXCL lockfile for atomic
 * check-then-start, signal-0 liveness, SIGTERM->1000ms->SIGKILL) to a
 * native binary instead of a forked Node process. `spawn()` here passes zero
 * arguments, always β€” starting the server is the argument-free behavior and
 * the only one this module wants.
 *
 * That is now a choice rather than a constraint. The 2026-07-16 note here
 * ("the binary takes no CLI flags β€” no `--version`/`--help`, any invocation
 * just starts the server") was true of the release pinned at the time, and
 * stopped being true: meta-proxy v0.7.2 handles `--help` before binding, and
 * v0.7.3 makes `--help`/`--version` win from any argv position. Do not read
 * the old note as "the binary cannot be asked what it is" β€” it can. The
 * installed version is still read from the install manifest rather than by
 * executing the binary, because a filesystem read cannot start a listener
 * and an exec of an old build can (a `--version` probe against 0.4.0 leaves
 * a daemon bound to 127.0.0.1:11435).
 *
 * Foreground `start` (the ADR-307 default) uses `stdio: 'inherit'` and
 * blocks directly β€” simplest and safest, no log-file redirection needed.
 * `start --service` needs REAL file-descriptor redirection
 * (`stdio: ['ignore', fd, fd]`) + `detached: true` + `unref()` via
 * `child_process.spawn()` directly β€” `SafeExecutor.executeStreaming()`
 * buffers output in-process, which is wrong for a process meant to outlive
 * the `ruflo` invocation that started it.
 *
 * @module proxy/lifecycle
 */

import { spawn } from 'node:child_process';
import * as fs from 'node:fs';
import {
  proxyBinaryPath,
  proxyPidFilePath,
  proxyLockFilePath,
  proxyLogFilePath,
  proxyInstallManifestPath,
  type InstallManifest,
} from './paths.js';

export class ProxyNotInstalledError extends Error {
  constructor() {
    super('meta-proxy is not installed. Run: ruflo proxy install');
    this.name = 'ProxyNotInstalledError';
  }
}

export class ProxyAlreadyRunningError extends Error {
  constructor(public readonly pid: number) {
    super(`meta-proxy is already running (pid ${pid}). Stop it first with: ruflo proxy stop`);
    this.name = 'ProxyAlreadyRunningError';
  }
}

function requireBinary(): string {
  const bin = proxyBinaryPath();
  if (!fs.existsSync(bin)) throw new ProxyNotInstalledError();
  return bin;
}

/** Signal-0 liveness probe β€” cross-platform in Node, throws if the process is dead. */
function isProcessRunning(pid: number): boolean {
  try {
    process.kill(pid, 0);
    return true;
  } catch {
    return false;
  }
}

export interface ProxyStatus {
  installed: boolean;
  running: boolean;
  pid: number | null;
  stalePidFile: boolean;
  /**
   * The release recorded by the install that produced the binary on disk, or
   * null when unknown β€” either nothing is installed, or the binary predates
   * the manifest / the manifest was hand-removed. Callers must treat null as
   * "cannot tell", never as "up to date".
   */
  version: string | null;
}

/**
 * The installed release, from `install.ts`'s manifest. Deliberately a
 * filesystem read and not `meta-proxy --version`: exec'ing the binary to ask
 * its version is exactly the probe that starts a listener on the older
 * builds this is most needed to detect.
 *
 * Never throws β€” a missing, unreadable, or malformed manifest is a normal
 * "unknown", not a reason to fail `proxy status`.
 */
function readInstalledVersion(): string | null {
  try {
    const raw = fs.readFileSync(proxyInstallManifestPath(), 'utf-8');
    const manifest = JSON.parse(raw) as Partial<InstallManifest>;
    return typeof manifest.version === 'string' && manifest.version ? manifest.version : null;
  } catch {
    return null;
  }
}

export function getProxyStatus(): ProxyStatus {
  const installed = fs.existsSync(proxyBinaryPath());
  const version = installed ? readInstalledVersion() : null;
  const pidPath = proxyPidFilePath();
  if (!fs.existsSync(pidPath)) {
    return { installed, running: false, pid: null, stalePidFile: false, version };
  }
  const raw = fs.readFileSync(pidPath, 'utf-8').trim();
  const pid = parseInt(raw, 10);
  if (!Number.isFinite(pid)) {
    return { installed, running: false, pid: null, stalePidFile: true, version };
  }
  const running = isProcessRunning(pid);
  return { installed, running, pid: running ? pid : null, stalePidFile: !running, version };
}

function writePidFile(pid: number): void {
  fs.writeFileSync(proxyPidFilePath(), String(pid), 'utf-8');
}

function clearStalePidFile(): void {
  try {
    fs.unlinkSync(proxyPidFilePath());
  } catch {
    // already absent
  }
}

/**
 * Atomic check-then-start via an O_EXCL lockfile β€” the same fix daemon.ts
 * applies for the identical race (#2407/#2484: without this, N concurrent
 * `start` calls all see "not running" and all spawn their own process).
 * Returns the lock fd to release once the PID file has been written (or on
 * any early-return/throw), never before.
 */
function acquireStartLock(): number | null {
  const lockFile = proxyLockFilePath();
  try {
    return fs.openSync(lockFile, fs.constants.O_CREAT | fs.constants.O_EXCL | fs.constants.O_WRONLY);
  } catch (e) {
    if ((e as NodeJS.ErrnoException).code === 'EEXIST') return null; // another start is mid-spawn
    throw e;
  }
}

function releaseStartLock(fd: number | null): void {
  if (fd === null) return;
  try {
    fs.closeSync(fd);
  } catch {
    /* ignore */
  }
  try {
    fs.unlinkSync(proxyLockFilePath());
  } catch {
    /* ignore */
  }
}

/**
 * Foreground start (ADR-307 default) β€” blocks the caller until the process
 * exits or is interrupted. `stdio: 'inherit'` passes the proxy's own output
 * straight through to the terminal; signals (Ctrl+C) propagate naturally to
 * the child, no manual forwarding needed.
 */
export async function startForeground(supervised = false): Promise<never> {
  const bin = requireBinary();
  const status = getProxyStatus();
  // In service mode startBackground has already written this supervisor's
  // PID. Treating it as a competing proxy makes the supervisor immediately
  // exit before it can spawn meta-proxy.
  if (!supervised && status.running && status.pid) throw new ProxyAlreadyRunningError(status.pid);
  if (status.stalePidFile) clearStalePidFile();

  const child = spawn(bin, [], { stdio: 'inherit', windowsHide: false });
  if (!supervised && child.pid) writePidFile(child.pid);

  const cleanup = () => clearStalePidFile();
  process.on('exit', cleanup);
  if (supervised) {
    const forwardSignal = (signal: NodeJS.Signals) => {
      if (!child.killed) child.kill(signal);
    };
    process.once('SIGTERM', () => forwardSignal('SIGTERM'));
    process.once('SIGINT', () => forwardSignal('SIGINT'));
  }

  await new Promise<void>((resolve) => {
    child.on('exit', () => {
      cleanup();
      resolve();
    });
  });
  process.exit(0);
}

/**
 * Background/`--service` start β€” detaches so the process outlives this
 * `ruflo` invocation, redirecting stdout/stderr to a real log file (not
 * buffered in-process). Returns once the child's PID is confirmed written,
 * without waiting for the process to exit.
 */
export async function startBackground(): Promise<{ pid: number }> {
  requireBinary();
  const status = getProxyStatus();
  if (status.running && status.pid) throw new ProxyAlreadyRunningError(status.pid);

  const lockFd = acquireStartLock();
  try {
    // Re-check under the lock β€” the dedup above raced a concurrent starter.
    const rechecked = getProxyStatus();
    if (rechecked.running && rechecked.pid) throw new ProxyAlreadyRunningError(rechecked.pid);
    if (rechecked.stalePidFile) clearStalePidFile();

    const logFd = fs.openSync(proxyLogFilePath(), 'a');
    const cliEntry = process.argv[1];
    if (!cliEntry) throw new Error('cannot locate the ruflo CLI entrypoint for supervised service mode');
    const child = spawn(process.execPath, [cliEntry, 'proxy', 'supervise'], {
      stdio: ['ignore', logFd, logFd],
      detached: true,
      windowsHide: true,
    });
    fs.closeSync(logFd); // the child holds its own duplicated fd; safe to close ours

    if (!child.pid) throw new Error('ruflo proxy supervisor failed to spawn β€” no PID returned');
    writePidFile(child.pid);
    child.unref();
    return { pid: child.pid };
  } finally {
    releaseStartLock(lockFd);
  }
}

export interface StopResult {
  wasRunning: boolean;
  pid: number | null;
}

/** SIGTERM -> 1000ms -> SIGKILL if still alive, mirroring daemon.ts's killBackgroundDaemon. */
export async function stopProxy(): Promise<StopResult> {
  const status = getProxyStatus();
  if (!status.running || !status.pid) {
    if (status.stalePidFile) clearStalePidFile();
    return { wasRunning: false, pid: null };
  }

  const pid = status.pid;
  process.kill(pid, 'SIGTERM');
  await new Promise((r) => setTimeout(r, 1000));
  if (isProcessRunning(pid)) {
    process.kill(pid, 'SIGKILL');
  }
  clearStalePidFile();
  return { wasRunning: true, pid };
}

const TAIL_BYTES = 64 * 1024; // bounded read β€” a long-running proxy's log grows over weeks

export function readProxyLogTail(maxBytes: number = TAIL_BYTES): string {
  const logPath = proxyLogFilePath();
  if (!fs.existsSync(logPath)) return '';
  const { size } = fs.statSync(logPath);
  const start = Math.max(0, size - maxBytes);
  const fd = fs.openSync(logPath, 'r');
  try {
    const buf = Buffer.alloc(size - start);
    fs.readSync(fd, buf, 0, buf.length, start);
    return buf.toString('utf-8');
  } finally {
    fs.closeSync(fd);
  }
}

/** Streams new log lines as they're appended, starting from the current end of file. */
export function watchProxyLog(onLine: (line: string) => void): fs.FSWatcher {
  const logPath = proxyLogFilePath();
  if (!fs.existsSync(logPath)) {
    throw new Error('no log file yet β€” meta-proxy has never been started in --service mode');
  }
  let offset = fs.statSync(logPath).size;
  return fs.watch(logPath, () => {
    const { size } = fs.statSync(logPath);
    if (size <= offset) return;
    const fd = fs.openSync(logPath, 'r');
    try {
      const buf = Buffer.alloc(size - offset);
      fs.readSync(fd, buf, 0, buf.length, offset);
      offset = size;
      for (const line of buf.toString('utf-8').split('\n')) {
        if (line.length > 0) onLine(line);
      }
    } finally {
      fs.closeSync(fd);
    }
  });
}