Skip to content
Python
4.3 KB
Raw Blame
import { verifyBackgroundArtifact } from "./background-artifact.js";
import type { BackgroundOperationAdapter } from "./background-controller.js";
import {
  type BackgroundHealth,
  inspectBackgroundHealth,
} from "./background-health.js";
import type { BackgroundIntent } from "./background-operation.js";
import type {
  BackgroundPlanRegistry,
  TrustedBackgroundPlan,
} from "./background-plan.js";
import type { BackgroundRegistrationStatus } from "./background-status.js";
import { installUserService, uninstallUserService } from "./service-install.js";
import type {
  RuntimeInstallLayout,
  RuntimeServicePlan,
} from "./service-plan.js";

interface Options {
  registration(
    plan: TrustedBackgroundPlan,
  ): Promise<BackgroundRegistrationStatus>;
  verifyArtifact?: (
    layout: RuntimeInstallLayout,
  ) => Promise<{ digest: string; root: string; version: string }>;
  health?: (options: { dataDir: string }) => Promise<BackgroundHealth>;
  install?: (
    layout: RuntimeInstallLayout,
    options: { uid: number },
  ) => Promise<RuntimeServicePlan>;
  uninstall?: (
    layout: RuntimeInstallLayout,
    options: { uid: number },
  ) => Promise<"removed" | "not-installed">;
}

/** Internal guarded wiring to the existing installer, not a public mutation API.
 * Requires trusted OS observation; unknown is never treated as absent. Full
 * loaded-job provenance is not yet available, so inspect never attests applied.
 * Do not expose this adapter as enabled UI until that remaining gate is resolved.
 */
export class BackgroundServiceAdapter implements BackgroundOperationAdapter {
  constructor(
    private readonly plans: BackgroundPlanRegistry,
    private readonly options: Options,
  ) {}
  async check(intent: Readonly<BackgroundIntent>): Promise<boolean> {
    try {
      const plan = this.plans.resolve(intent);
      const artifact = await (
        this.options.verifyArtifact ?? verifyBackgroundArtifact
      )(plan.layout);
      if (
        artifact.digest !== intent.artifactDigest ||
        artifact.root !== plan.artifact.root ||
        artifact.version !== plan.artifact.version
      )
        return false;
      const status = await this.options.registration(plan);
      if (
        status.serviceId !== plan.service.service_id ||
        status.reason !== null
      )
        return false;
      if (intent.action === "disable")
        return (
          status.file === "managed" && status.registration === "registered"
        );
      if (status.file !== "absent" || status.registration !== "absent")
        return false;
      const health = await (this.options.health ?? inspectBackgroundHealth)({
        dataDir: plan.layout.dataDir,
      });
      return health.state === "stopped" && health.core === "stopped";
    } catch {
      return false;
    }
  }
  async apply(intent: Readonly<BackgroundIntent>): Promise<void> {
    // Resolve first preserves consumed/expired diagnostics instead of reducing
    // an attempted repeat to a misleading change of plan.
    const plan = this.plans.resolve(intent);
    if (!(await this.check(intent))) throw Error("background_plan_changed");
    this.plans.markApplying(intent);
    if (intent.action === "enable") {
      await (this.options.install ?? installUserService)(plan.layout, {
        uid: plan.uid,
      });
    } else {
      await (this.options.uninstall ?? uninstallUserService)(plan.layout, {
        uid: plan.uid,
      });
    }
  }
  async inspect(
    intent: Readonly<BackgroundIntent>,
  ): Promise<"unknown" | "conflict"> {
    const plan = this.plans.inspect(intent);
    if (!plan) return "unknown";
    try {
      const artifact = await (
        this.options.verifyArtifact ?? verifyBackgroundArtifact
      )(plan.layout);
      if (
        artifact.digest !== intent.artifactDigest ||
        artifact.root !== plan.artifact.root ||
        artifact.version !== plan.artifact.version
      )
        return "conflict";
      const registration = await this.options.registration(plan);
      if (
        registration.file === "conflict" ||
        registration.registration === "conflict"
      )
        return "conflict";
      // SM eligibility + healthy detached Runtime is not evidence that launchd
      // loaded this exact operation. Absence cannot prove no earlier effect.
      return "unknown";
    } catch {
      return "unknown";
    }
  }
}