Skip to content
Python
13.0 KB
Raw Blame
/** Service-aware start/stop/status for the launchd-managed Runtime.
 *
 * `start`/`stop`/`status` used to be purely receipt-based: they looked at
 * `runtime.json`/`runtime-service.json`. When the Runtime is managed by the
 * launchd KeepAlive service, those receipts can disappear while the daemon is
 * still alive, so `stop` reported "stopped" (exit 0) with the daemon running,
 * and `start` then failed with "exited before ready" because the service was
 * already holding the data directory. This module makes the three commands
 * consult the real launchd state and act on it:
 *   - `stop` boots the service out (真正停用) and verifies it is gone;
 *   - `start` kickstarts an already-registered service instead of spawning a
 *     competing process;
 *   - `status` can report the service as running even without a receipt.
 *
 * All launchctl interaction goes through an injectable runner so the logic is
 * testable without touching the host's launchd.
 */

import { spawn } from "node:child_process";
import { access } from "node:fs/promises";
import path from "node:path";

export interface CommandResult {
  code: number;
  stdout: string;
  stderr: string;
}

export type ServiceCommandRunner = (
  command: readonly string[],
) => Promise<CommandResult>;

export type LaunchdServiceState =
  | { state: "running"; pid: number; plistPath: string | null }
  /** Loaded by launchd but with no live pid right now (e.g. throttled, or
   * between KeepAlive restarts). Still a registered service. */
  | { state: "loaded"; plistPath: string | null }
  /** A `com.tencent.onememory.runtime` label is running, but its plist binds a
   * different data dir. The label is global per user, so a second install must
   * not be mistaken for this one. */
  | { state: "foreign"; plistPath: string | null }
  | { state: "absent" }
  | { state: "unknown"; code: string };

function launchdDomain(uid: number): string {
  return `gui/${uid}`;
}

/** Deterministic location of the managed LaunchAgent plist. Needed because
 * after `bootout` launchd no longer reports a path, yet `start` must be able to
 * bootstrap the very same service back. */
export function defaultLaunchAgentPath(
  home: string,
  serviceId: string,
): string {
  return path.posix.join(home, "Library", "LaunchAgents", `${serviceId}.plist`);
}

async function fileExists(target: string): Promise<boolean> {
  return access(target).then(
    () => true,
    () => false,
  );
}

/** Inspect the launchd label for this product. `launchctl print` succeeds with
 * `state = running` / `pid = N` while loaded; a non-zero exit that mentions the
 * service is missing means absent; anything else is unknown (fail-closed). */
export async function inspectLaunchdService(options: {
  serviceId: string;
  uid: number;
  runCaptured: ServiceCommandRunner;
  /** When given, a running/loaded label is only claimed for this data dir:
   * the plist's `ONE_MEMORY_DATA_DIR` must match it. The label name alone is
   * not identity — it is global per user, so a second install would otherwise
   * be reported as this one. Omit only where the caller already knows it owns
   * the label (e.g. bootstrapping the exact plist it just wrote). */
  dataDir?: string;
}): Promise<LaunchdServiceState> {
  const result = await options.runCaptured([
    "launchctl",
    "print",
    `${launchdDomain(options.uid)}/${options.serviceId}`,
  ]);
  if (result.code !== 0) {
    if (/could not find service|service not found/i.test(result.stderr)) {
      return { state: "absent" };
    }
    return { state: "unknown", code: "launchd_inspection_failed" };
  }
  const pid = /^\s*pid\s*=\s*(\d+)\s*$/m.exec(result.stdout);
  const plist = /^\s*path\s*=\s*(.+?)\s*$/m.exec(result.stdout);
  const plistPath = plist?.[1] ?? null;
  if (options.dataDir !== undefined && plistPath !== null) {
    const bound = await readPlistDataDir(plistPath, options.runCaptured).catch(
      () => undefined,
    );
    // Fail closed: an unreadable plist or a missing/mismatched data dir is not
    // proof that this label belongs to us.
    if (bound !== options.dataDir) return { state: "foreign", plistPath };
  }
  if (!pid || Number(pid[1]) < 1) return { state: "loaded", plistPath };
  return {
    state: "running",
    pid: Number(pid[1]),
    plistPath,
  };
}

/** The `ONE_MEMORY_DATA_DIR` a managed plist was written with, or undefined if
 * it cannot be read. Used only to attribute a global launchd label to a data
 * dir; never to trust the label name on its own. */
async function readPlistDataDir(
  plistPath: string,
  runCaptured: ServiceCommandRunner,
): Promise<string | undefined> {
  const result = await runCaptured([
    "/usr/bin/plutil",
    "-convert",
    "json",
    "-o",
    "-",
    plistPath,
  ]);
  if (result.code !== 0) return undefined;
  try {
    const document = JSON.parse(result.stdout) as {
      EnvironmentVariables?: Record<string, unknown>;
    };
    const value = document.EnvironmentVariables?.ONE_MEMORY_DATA_DIR;
    return typeof value === "string" ? value : undefined;
  } catch {
    return undefined;
  }
}

async function delay(milliseconds: number): Promise<void> {
  await new Promise((resolve) => setTimeout(resolve, milliseconds));
}

/** Stop the managed service for real. Returns "stopped" only after the label is
 * verifiably gone; returning early would reproduce the exact false success this
 * module exists to prevent. */
export async function stopManagedService(options: {
  serviceId: string;
  uid: number;
  runCaptured: ServiceCommandRunner;
  /** Attribution: only a label bound to this data dir may be stopped. */
  dataDir?: string;
  timeoutMs?: number;
  /** Consecutive absent samples required before "stopped" is returned. */
  sustainedAbsentSamples?: number;
  /** Delay between absence samples. */
  pollMs?: number;
}): Promise<"stopped" | "not-running" | "still-running"> {
  const before = await inspectLaunchdService(options);
  // `foreign`: another install's daemon holds this (global) label. Not ours to
  // stop or report on — let the caller fall through to its own receipt path.
  if (before.state === "absent" || before.state === "foreign")
    return "not-running";
  if (before.state === "unknown") throw new Error(before.code);
  const domain = launchdDomain(options.uid);
  // Prefer the plist path launchd itself reports; fall back to the label.
  const target = before.plistPath
    ? (["launchctl", "bootout", domain, before.plistPath] as const)
    : (["launchctl", "bootout", `${domain}/${options.serviceId}`] as const);
  const result = await options.runCaptured([...target]);
  if (
    result.code !== 0 &&
    !/could not find service|service not found/i.test(result.stderr)
  ) {
    throw new Error("launchd_bootout_failed");
  }
  // "Stopped" must mean the label stays gone, not that we saw it gone once.
  // macOS launchd re-loads plists from ~/Library/LaunchAgents, so a single
  // absent sample right after bootout can be followed by the service coming
  // back with a new pid. Require N consecutive absent samples spaced out, and
  // treat any reappearance as "still-running" so the caller reports non-zero
  // instead of the false success A8 exists to prevent.
  // ~5s of consecutive absence (20 × 250ms). A 1.5s window was observed to be
  // too short: a crash-looping service (`state = spawn scheduled`) came back
  // with a new pid a few seconds after bootout, and the CLI had already
  // reported success. 5s matches the acceptance criterion the verifier used
  // ("label 连续 5s 计数 0").
  const requiredAbsentSamples = options.sustainedAbsentSamples ?? 20;
  const pollMs = options.pollMs ?? 250;
  const deadline = Date.now() + (options.timeoutMs ?? 10_000);
  let consecutiveAbsent = 0;
  while (Date.now() < deadline) {
    const now = await inspectLaunchdService(options);
    if (now.state === "absent") {
      consecutiveAbsent += 1;
      if (consecutiveAbsent >= requiredAbsentSamples) return "stopped";
    } else {
      consecutiveAbsent = 0;
    }
    await delay(pollMs);
  }
  return "still-running";
}

/** Start (or restart) the managed service if it is registered; report whether a
 * kickstart was used so the caller can avoid spawning a second process. */
export async function startManagedService(options: {
  serviceId: string;
  uid: number;
  /** Home whose LaunchAgents dir holds the managed plist; required to
   * bootstrap a service that was previously booted out. */
  home?: string;
  runCaptured: ServiceCommandRunner;
  /** Attribution: a label bound to another data dir must not be kickstarted. */
  dataDir?: string;
  timeoutMs?: number;
}): Promise<"started" | "absent" | "not-ready"> {
  const before = await inspectLaunchdService(options);
  if (before.state === "unknown") throw new Error(before.code);
  // A stranger's daemon owns this label; do not kickstart or claim it.
  if (before.state === "foreign") return "absent";
  if (before.state === "running") return "started";
  const domain = launchdDomain(options.uid);
  if (before.state === "absent") {
    // Not loaded: bootstrap the managed plist if it exists; otherwise there is
    // nothing service-backed to start and the caller spawns instead.
    const plist = options.home
      ? defaultLaunchAgentPath(options.home, options.serviceId)
      : null;
    if (plist === null || !(await fileExists(plist))) return "absent";
    const boot = await options.runCaptured([
      "launchctl",
      "bootstrap",
      domain,
      plist,
    ]);
    if (boot.code !== 0) throw new Error("launchd_bootstrap_failed");
  } else {
    const result = await options.runCaptured([
      "launchctl",
      "kickstart",
      "-k",
      `${domain}/${options.serviceId}`,
    ]);
    if (result.code !== 0) throw new Error("launchd_kickstart_failed");
  }
  const deadline = Date.now() + (options.timeoutMs ?? 15_000);
  while (Date.now() < deadline) {
    const now = await inspectLaunchdService(options);
    if (now.state === "running") return "started";
    await delay(150);
  }
  return "not-ready";
}

/** Restart a registered service in place with `kickstart -k`, which keeps the
 * launchd registration. `absent` means the caller should fall back to the
 * receipt/spawn path. */
export async function restartManagedService(options: {
  serviceId: string;
  uid: number;
  runCaptured: ServiceCommandRunner;
  /** Attribution: never kickstart a label bound to another data dir. */
  dataDir?: string;
  timeoutMs?: number;
}): Promise<"restarted" | "absent" | "not-ready"> {
  const before = await inspectLaunchdService(options);
  if (before.state === "absent" || before.state === "foreign") return "absent";
  if (before.state === "unknown") throw new Error(before.code);
  const domain = launchdDomain(options.uid);
  const result = await options.runCaptured([
    "launchctl",
    "kickstart",
    "-k",
    `${domain}/${options.serviceId}`,
  ]);
  if (result.code !== 0) throw new Error("launchd_kickstart_failed");
  const deadline = Date.now() + (options.timeoutMs ?? 15_000);
  while (Date.now() < deadline) {
    const now = await inspectLaunchdService(options);
    if (now.state === "running") return "restarted";
    await delay(150);
  }
  return "not-ready";
}

export async function runLaunchctlCaptured(
  command: readonly string[],
): Promise<CommandResult> {
  const [program, ...args] = command;
  if (!program) throw new Error("launchd_command_invalid");
  return new Promise((resolve, reject) => {
    const child = spawn(program, args, {
      shell: false,
      windowsHide: true,
      stdio: ["ignore", "pipe", "pipe"],
    });
    let stdout = "";
    let stderr = "";
    child.stdout?.on("data", (chunk) => {
      stdout += String(chunk);
    });
    child.stderr?.on("data", (chunk) => {
      stderr += String(chunk);
    });
    child.once("error", () => reject(new Error("launchd_command_failed")));
    child.once("close", (code) => resolve({ code: code ?? 1, stdout, stderr }));
  });
}

/** Run launchctl for a teardown step and tolerate an already-gone target.
 *
 * `launchctl bootout` exits non-zero ("Boot-out failed: 3: No such process")
 * when the label is not loaded. That is the desired end state, not a failure.
 * The managed-service uninstaller otherwise aborts before unlinking the plist,
 * leaving a stale file that makes every later `install --yes` refuse with
 * `runtime_service_file_exists`. This is exactly the sequence `memhub stop`
 * (bootout) followed by `memhub uninstall --yes` produces. */
export function createTolerantLaunchctlRunner(
  runCaptured: ServiceCommandRunner,
): (command: readonly string[]) => Promise<void> {
  return async (command) => {
    const result = await runCaptured(command);
    if (result.code === 0) return;
    // Only launchctl gets this leniency; a non-launchctl teardown failure is a
    // real failure. Keeping it scoped also keeps Linux `systemctl` behaviour
    // exactly as the shared package defines it.
    if (command[0] === "launchctl" && isAlreadyGone(result.stderr)) return;
    throw new Error("runtime_service_command_failed");
  };
}

function isAlreadyGone(stderr: string): boolean {
  return /could not find service|service not found|no such process|boot-out failed|not loaded/i.test(
    stderr,
  );
}