Skip to content
Python
16.4 KB
Raw Blame
import { spawn } from "node:child_process";
import { lstat, readFile, realpath } from "node:fs/promises";
import path from "node:path";

import {
  disableRuntimeService,
  enableRuntimeService,
  installUserService,
  planUserService,
  type RuntimeInstallLayout,
  type RuntimeServicePlan,
  restartUserService,
  runtimeServiceEnabled,
  type ServiceCommandRunner,
  uninstallUserService,
} from "@one-memory/runtime-control";

type ServiceOptions = {
  uid?: number;
  xdgConfigHome?: string;
  /** Injected OS-service command runner. `uninstallUserService` treats any
   * non-zero exit as `runtime_service_command_failed`; callers that already
   * booted the label out (e.g. `memhub stop`) pass a tolerant runner so the
   * plist still gets removed. */
  runCommand?: ServiceCommandRunner;
};

type ManagedSnapshot = {
  kind: "managed";
  plistPath: string;
  content: string;
};

type Registration =
  | { kind: "absent" }
  | ManagedSnapshot
  | { kind: "unmanaged"; plistPath: string | null };

type ServiceFile =
  | { kind: "absent" }
  | { kind: "managed"; content: string }
  | { kind: "unmanaged" };

export type CommandResult = {
  code: number;
  stdout: string;
  stderr: string;
};

export interface ServiceLifecycleDependencies {
  inspectRegistration: (
    plan: RuntimeServicePlan,
    options: ServiceOptions,
  ) => Promise<Registration>;
  inspectServiceFile: (plan: RuntimeServicePlan) => Promise<ServiceFile>;
  install: typeof installUserService;
  restart: typeof restartUserService;
  uninstall: typeof uninstallUserService;
  runCommand: ServiceCommandRunner;
  verifyRegistrationSnapshot: (snapshot: ManagedSnapshot) => Promise<void>;
  /** Whether two absolute paths denote the same file (post-realpath). */
  sameFile: (left: string, right: string) => Promise<boolean>;
  serviceEnabled: (dataDir: string) => Promise<boolean>;
  enableService: (dataDir: string) => Promise<void>;
  disableService: (dataDir: string) => Promise<void>;
}

export type PreparedServiceInstall = {
  layout: RuntimeInstallLayout;
  options: ServiceOptions;
  plan: RuntimeServicePlan;
  mode: "direct" | "bootstrap-existing" | "restart" | "replace";
  previous?: ManagedSnapshot;
  previouslyEnabled: boolean;
  /**
   * Re-bootstrap the previous (possibly older) LaunchAgent when the new one
   * fails to bootstrap. `install` turns this off once the home has been handed
   * to this version's SDK migration: an older Runtime has no migration gate and
   * would serve a home that is not on SDK authority.
   */
  restorePreviousOnFailure?: boolean;
};

const defaultDependencies: ServiceLifecycleDependencies = {
  inspectRegistration: inspectLaunchAgentRegistration,
  inspectServiceFile,
  install: installUserService,
  restart: restartUserService,
  uninstall: uninstallUserService,
  runCommand: runServiceCommand,
  verifyRegistrationSnapshot,
  sameFile: pathsIdentifySameFile,
  serviceEnabled: runtimeServiceEnabled,
  enableService: enableRuntimeService,
  disableService: disableRuntimeService,
};

export async function prepareServiceInstall(
  layout: RuntimeInstallLayout,
  options: ServiceOptions,
  dependencies: ServiceLifecycleDependencies = defaultDependencies,
): Promise<PreparedServiceInstall> {
  const plan = planUserService(layout, options);
  if (plan.status !== "ready" || plan.service_file === null) {
    throw new Error(plan.blocked_reason ?? "runtime_service_plan_blocked");
  }
  const previouslyEnabled = await dependencies.serviceEnabled(layout.dataDir);
  if (layout.platform !== "darwin") {
    return { layout, options, plan, mode: "direct", previouslyEnabled };
  }

  const [registration, target] = await Promise.all([
    dependencies.inspectRegistration(plan, options),
    dependencies.inspectServiceFile(plan),
  ]);
  if (registration.kind === "unmanaged") {
    throw new Error("runtime_service_conflict_unmanaged_label");
  }
  if (target.kind === "unmanaged") {
    throw new Error("runtime_service_conflict_unmanaged_file");
  }
  if (registration.kind === "absent") {
    return {
      layout,
      options,
      plan,
      mode: target.kind === "managed" ? "bootstrap-existing" : "direct",
      previouslyEnabled,
    };
  }
  // launchd reports the plist's realpath, so compare file identity rather than
  // the literal string: the same file can be reached via a different path.
  if (
    await dependencies.sameFile(registration.plistPath, plan.service_file.path)
  ) {
    if (target.kind !== "managed") {
      throw new Error("runtime_service_conflict_unmanaged_file");
    }
    return {
      layout,
      options,
      plan,
      mode: "restart",
      previous: registration,
      previouslyEnabled,
    };
  }
  if (target.kind !== "absent") {
    throw new Error("runtime_service_conflict_unmanaged_file");
  }
  return {
    layout,
    options,
    plan,
    mode: "replace",
    previous: registration,
    previouslyEnabled,
  };
}

export async function applyPreparedServiceInstall(
  prepared: PreparedServiceInstall,
  dependencies: ServiceLifecycleDependencies = defaultDependencies,
): Promise<RuntimeServicePlan> {
  const { layout, options, plan } = prepared;
  try {
    if (prepared.mode === "restart") {
      await dependencies.enableService(layout.dataDir);
      try {
        await verifyPreparedRegistration(prepared, dependencies);
        return await dependencies.restart(layout, options);
      } catch (error) {
        await restoreServiceEnableState(prepared, dependencies).catch(
          () => undefined,
        );
        throw error;
      }
    }
    if (prepared.mode === "bootstrap-existing") {
      await dependencies.enableService(layout.dataDir);
      try {
        for (const command of plan.commands.install) {
          await dependencies.runCommand(command);
        }
      } catch (error) {
        await restoreServiceEnableState(prepared, dependencies).catch(
          () => undefined,
        );
        throw error;
      }
      return plan;
    }
    if (prepared.mode === "direct") {
      return await dependencies.install(layout, options);
    }

    const previous = prepared.previous;
    if (!previous) throw new Error("runtime_service_upgrade_state_invalid");
    await verifyPreparedRegistration(prepared, dependencies);
    const domain = launchdDomain(options.uid);
    let replacementFailure: "upgrade" | "rollback" | "not-restored" | null =
      null;
    const replaceCommand: ServiceCommandRunner = async (command) => {
      if (command[0] !== "launchctl" || command[1] !== "bootstrap") {
        await dependencies.runCommand(command);
        return;
      }
      await dependencies.verifyRegistrationSnapshot(previous);
      await dependencies.runCommand([
        "launchctl",
        "bootout",
        domain,
        previous.plistPath,
      ]);
      try {
        await dependencies.runCommand(command);
      } catch {
        replacementFailure = "upgrade";
        if (prepared.restorePreviousOnFailure === false) {
          replacementFailure = "not-restored";
          throw new Error("runtime_service_replacement_failed");
        }
        try {
          await dependencies.verifyRegistrationSnapshot(previous);
          await dependencies.runCommand([
            "launchctl",
            "bootstrap",
            domain,
            previous.plistPath,
          ]);
        } catch {
          replacementFailure = "rollback";
        }
        throw new Error("runtime_service_managed_upgrade_failed");
      }
    };
    try {
      return await dependencies.install(layout, {
        ...options,
        runCommand: replaceCommand,
      });
    } catch (error) {
      if (replacementFailure === "rollback") {
        throw new Error("runtime_service_managed_upgrade_rollback_failed");
      }
      if (replacementFailure === "upgrade") {
        throw new Error("runtime_service_managed_upgrade_failed");
      }
      if (replacementFailure === "not-restored") {
        throw new Error("runtime_service_replacement_failed");
      }
      throw error;
    }
  } catch (error) {
    if (
      error instanceof Error &&
      error.message === "runtime_install_incomplete"
    ) {
      throw new Error(
        "runtime_install_incomplete: run memhub install --yes first",
      );
    }
    throw error;
  }
}

/** Restore the exact service-registration state observed before install.
 * The callback rolls back Runtime files and ownership while the failed service
 * is stopped; any process relaunched afterward sees the old Runtime and owner. */
export async function rollbackPreparedServiceInstall(
  prepared: PreparedServiceInstall,
  rollbackFilesAndOwner: () => Promise<void>,
  dependencies: ServiceLifecycleDependencies = defaultDependencies,
): Promise<void> {
  const { layout, options, plan } = prepared;
  if (prepared.mode === "direct") {
    await dependencies.uninstall(layout, options);
    await rollbackFilesAndOwner();
    await restoreServiceEnableState(prepared, dependencies);
    return;
  }

  if (prepared.mode === "bootstrap-existing") {
    for (const command of plan.commands.stop) {
      await dependencies.runCommand(command);
    }
    await rollbackFilesAndOwner();
    await restoreServiceEnableState(prepared, dependencies);
    return;
  }

  if (prepared.mode === "restart") {
    await dependencies.uninstall(layout, options);
    await rollbackFilesAndOwner();
    await restoreServiceEnableState(prepared, dependencies);
    await dependencies.install(layout, options);
    return;
  }

  const previous = prepared.previous;
  if (!previous) throw new Error("runtime_service_upgrade_state_invalid");
  await dependencies.verifyRegistrationSnapshot(previous);
  // `replace` published a new plist at this install's target. Remove that
  // declaration completely before restoring the old registration, otherwise
  // the stale target blocks the next install even though launchd is serving
  // the previous plist again.
  await dependencies.uninstall(layout, options);
  await rollbackFilesAndOwner();
  await restoreServiceEnableState(prepared, dependencies);
  await dependencies.runCommand([
    "launchctl",
    "bootstrap",
    launchdDomain(options.uid),
    previous.plistPath,
  ]);
}

async function restoreServiceEnableState(
  prepared: PreparedServiceInstall,
  dependencies: ServiceLifecycleDependencies,
): Promise<void> {
  if (prepared.previouslyEnabled) {
    await dependencies.enableService(prepared.layout.dataDir);
  } else {
    await dependencies.disableService(prepared.layout.dataDir);
  }
}

async function verifyPreparedRegistration(
  prepared: PreparedServiceInstall,
  dependencies: ServiceLifecycleDependencies,
): Promise<void> {
  const previous = prepared.previous;
  if (!previous) throw new Error("runtime_service_upgrade_state_invalid");
  const current = await dependencies.inspectRegistration(
    prepared.plan,
    prepared.options,
  );
  if (
    current.kind !== "managed" ||
    current.plistPath !== previous.plistPath ||
    current.content !== previous.content
  ) {
    throw new Error("runtime_service_registration_changed");
  }
}

export async function uninstallServicePreservingData(
  layout: RuntimeInstallLayout,
  options: ServiceOptions,
  dependencies: ServiceLifecycleDependencies = defaultDependencies,
): Promise<"removed" | "not-installed"> {
  return dependencies.uninstall(layout, options);
}

async function inspectServiceFile(
  plan: RuntimeServicePlan,
): Promise<ServiceFile> {
  if (plan.service_file === null) return { kind: "unmanaged" };
  try {
    const info = await lstat(plan.service_file.path);
    if (
      !info.isFile() ||
      info.isSymbolicLink() ||
      (info.mode & 0o7777) !== 0o600 ||
      (process.getuid && info.uid !== process.getuid())
    ) {
      return { kind: "unmanaged" };
    }
    const content = await readFile(plan.service_file.path, "utf8");
    return content === plan.service_file.content
      ? { kind: "managed", content }
      : { kind: "unmanaged" };
  } catch (error) {
    return (error as NodeJS.ErrnoException).code === "ENOENT"
      ? { kind: "absent" }
      : Promise.reject(error);
  }
}

export async function inspectLaunchAgentRegistration(
  plan: RuntimeServicePlan,
  options: ServiceOptions,
  runCaptured: (
    command: readonly string[],
  ) => Promise<CommandResult> = runServiceCommandCaptured,
): Promise<Registration> {
  if (plan.platform !== "darwin") return { kind: "absent" };
  const domain = launchdDomain(options.uid);
  const result = await runCaptured([
    "launchctl",
    "print",
    `${domain}/${plan.service_id}`,
  ]);
  if (result.code !== 0) {
    if (/could not find service|service not found/i.test(result.stderr)) {
      return { kind: "absent" };
    }
    throw new Error("runtime_service_inspection_failed");
  }
  const plistPath = parseLaunchdPath(result.stdout);
  if (plistPath === null) return { kind: "unmanaged", plistPath: null };
  const plist = await runCaptured([
    "/usr/bin/plutil",
    "-convert",
    "json",
    "-o",
    "-",
    plistPath,
  ]);
  if (plist.code !== 0) return { kind: "unmanaged", plistPath };
  try {
    const document = JSON.parse(plist.stdout) as Record<string, unknown>;
    const args = document.ProgramArguments;
    const environment = document.EnvironmentVariables;
    if (
      document.Label !== plan.service_id ||
      !Array.isArray(args) ||
      args.length !== 3 ||
      typeof args[0] !== "string" ||
      typeof args[1] !== "string" ||
      args[2] !== "serve" ||
      environment === null ||
      typeof environment !== "object" ||
      (environment as Record<string, unknown>).ONE_MEMORY_NODE_COMMAND !==
        args[0] ||
      (environment as Record<string, unknown>).ONE_MEMORY_RUNTIME_ENTRY !==
        args[1]
    ) {
      return { kind: "unmanaged", plistPath };
    }
    const content = await readManagedPlist(plistPath);
    return { kind: "managed", plistPath, content };
  } catch {
    return { kind: "unmanaged", plistPath };
  }
}

async function verifyRegistrationSnapshot(snapshot: ManagedSnapshot) {
  const content = await readManagedPlist(snapshot.plistPath);
  if (content !== snapshot.content) {
    throw new Error("runtime_service_registration_changed");
  }
}

/** Compare two absolute paths as files, resolving symlinks and macOS's
 * `/private` prefix. Falls back to a literal comparison only when neither path
 * can be resolved, so a genuinely different file is never called "same". */
async function pathsIdentifySameFile(
  left: string,
  right: string,
): Promise<boolean> {
  if (left === right) return true;
  const resolved = await Promise.all([
    realpath(left).catch(() => null),
    realpath(right).catch(() => null),
  ]);
  return resolved[0] !== null && resolved[0] === resolved[1];
}

async function readManagedPlist(plistPath: string): Promise<string> {
  if (!path.isAbsolute(plistPath)) {
    throw new Error("runtime_service_registration_unmanaged");
  }
  const info = await lstat(plistPath);
  if (
    !info.isFile() ||
    info.isSymbolicLink() ||
    (info.mode & 0o022) !== 0 ||
    (process.getuid && info.uid !== process.getuid())
  ) {
    throw new Error("runtime_service_registration_unmanaged");
  }
  return readFile(plistPath, "utf8");
}

function parseLaunchdPath(output: string): string | null {
  for (const line of output.split("\n")) {
    const match = /^\s*path\s*=\s*(.+?)\s*$/.exec(line);
    if (match?.[1] && path.isAbsolute(match[1])) return match[1];
  }
  return null;
}

function launchdDomain(uid: number | undefined): string {
  if (!Number.isSafeInteger(uid) || (uid ?? 0) < 1) {
    throw new Error("macos_user_id_required");
  }
  return `gui/${uid}`;
}

async function runServiceCommand(command: readonly string[]): Promise<void> {
  const result = await runServiceCommandCaptured(command);
  if (result.code !== 0) throw new Error("runtime_service_command_failed");
}

async function runServiceCommandCaptured(
  command: readonly string[],
): Promise<CommandResult> {
  const [program, ...args] = command;
  if (!program) throw new Error("runtime_service_command_invalid");
  return new Promise((resolve, reject) => {
    const child = spawn(program, args, {
      shell: false,
      windowsHide: true,
      stdio: ["ignore", "pipe", "pipe"],
    });
    const stdout: Buffer[] = [];
    const stderr: Buffer[] = [];
    child.stdout.on("data", (chunk: Buffer) => stdout.push(chunk));
    child.stderr.on("data", (chunk: Buffer) => stderr.push(chunk));
    child.once("error", () =>
      reject(new Error("runtime_service_command_failed")),
    );
    child.once("exit", (code) =>
      resolve({
        code: code ?? 1,
        stdout: Buffer.concat(stdout).toString("utf8"),
        stderr: Buffer.concat(stderr).toString("utf8"),
      }),
    );
  });
}