Skip to content
Python
6.8 KB
Raw Blame
import type { HealthResponse } from "@one-memory/contracts";
import { type DiagnosticSink, diagnosticError } from "./diagnostic-log.js";

export interface RuntimeCore {
  readonly instanceId: string;
  readonly apiToken: string;
  readonly port: number;
  start(): Promise<HealthResponse>;
  stop(): Promise<void>;
}

export interface RuntimeSidecar {
  start(): Promise<unknown>;
  stop(): Promise<void>;
}

/** A sidecar fault observed AFTER a successful start.
 *
 * The Broker runs inside the Runtime process, so a JS-level fault there
 * (an unhandled rejection from a request handler, an `error` event on the
 * server) would otherwise take the whole daemon down. The documented contract
 * is the opposite: the outer Runtime stays alive and the state degrades. This
 * record is what the supervisor exposes so `background-health` can report
 * `broker=unhealthy` + overall `degraded` instead of `stopped`. */
export interface RuntimeSidecarFault {
  code: string;
  at: number;
}

export interface RuntimeConnection {
  coreBaseUrl: string;
  coreApiToken: string;
  instanceId: string;
}

export interface RuntimeSupervisorOptions {
  core: RuntimeCore;
  createSidecar(
    connection: RuntimeConnection,
    reportFault: (code: string) => void,
  ): RuntimeSidecar;
  diagnostics?: DiagnosticSink;
  /** Notified exactly once, on the first post-start sidecar fault. Used by the
   * outer service to publish a durable `degraded` status without polling. */
  onSidecarFault?: (fault: RuntimeSidecarFault) => void;
}

/** Owns one complete local Runtime lifecycle without depending on Electron. */
export class RuntimeSupervisor {
  private readonly core: RuntimeCore;
  private readonly createSidecar: RuntimeSupervisorOptions["createSidecar"];
  private readonly diagnostics?: DiagnosticSink;
  private readonly onSidecarFault?: RuntimeSupervisorOptions["onSidecarFault"];
  private sidecar: RuntimeSidecar | null = null;
  private sidecarFault: RuntimeSidecarFault | null = null;
  private started = false;
  private stopping: Promise<void> | null = null;

  constructor(options: RuntimeSupervisorOptions) {
    this.core = options.core;
    this.createSidecar = options.createSidecar;
    this.diagnostics = options.diagnostics;
    this.onSidecarFault = options.onSidecarFault;
  }

  get connection(): RuntimeConnection {
    if (!this.started) throw new Error("MemHub Runtime is not running");
    return this.currentConnection();
  }

  /** The first post-start sidecar fault, if any. Never clears on its own: a
   * fault must not be masked by a later healthy read. A successful restart of
   * the sidecar (elsewhere) is the only thing that would clear it, and this
   * build deliberately does not restart a failed sidecar. */
  get sidecarFaultState(): RuntimeSidecarFault | null {
    return this.sidecarFault;
  }

  /** Sidecar health as the supervisor last observed it. `failed` is a captured
   * post-start fault; `stopped` is a clean drain; `running` is the normal case.
   * Read by the outer Runtime when publishing its own status receipt. */
  get sidecarState(): "running" | "failed" | "stopped" {
    if (this.sidecarFault !== null) return "failed";
    if (this.sidecar !== null) return "running";
    return "stopped";
  }

  async start(): Promise<HealthResponse> {
    if (this.started || this.sidecar || this.stopping) {
      throw new Error("MemHub Runtime supervisor already started");
    }
    const started = Date.now();
    await this.diagnostics?.log({
      level: "info",
      component: "runtime.supervisor",
      event: "runtime.starting",
      outcome: "started",
    });
    let coreStarted = false;
    let phase: "core" | "sidecar" = "core";
    try {
      const health = await this.core.start();
      coreStarted = true;
      phase = "sidecar";
      const sidecar = this.createSidecar(this.currentConnection(), (code) =>
        this.recordSidecarFault(code),
      );
      this.sidecar = sidecar;
      await sidecar.start();
      this.started = true;
      await this.diagnostics?.log({
        level: "info",
        component: "runtime.supervisor",
        event: "runtime.ready",
        outcome: "succeeded",
        instance_id: this.core.instanceId,
        duration_ms: Date.now() - started,
      });
      return health;
    } catch (error) {
      await this.diagnostics?.log({
        level: "error",
        component: "runtime.supervisor",
        event: "runtime.start_failed",
        outcome: "failed",
        instance_id: this.core.instanceId,
        duration_ms: Date.now() - started,
        error_code: "runtime_start_failed",
        details: { phase },
        ...diagnosticError(error),
      });
      await this.sidecar?.stop();
      if (coreStarted) await this.core.stop();
      this.sidecar = null;
      throw error;
    }
  }

  async stop(): Promise<void> {
    if (this.stopping) return this.stopping;
    const sidecar = this.sidecar;
    this.started = false;
    this.stopping = (async () => {
      const started = Date.now();
      await this.diagnostics?.log({
        level: "info",
        component: "runtime.supervisor",
        event: "runtime.stopping",
        outcome: "started",
        instance_id: this.core.instanceId,
      });
      await sidecar?.stop();
      await this.core.stop();
      this.sidecar = null;
      await this.diagnostics?.log({
        level: "info",
        component: "runtime.supervisor",
        event: "runtime.stopped",
        outcome: "succeeded",
        duration_ms: Date.now() - started,
      });
    })();
    try {
      await this.stopping;
    } finally {
      this.stopping = null;
    }
  }

  async restart(): Promise<HealthResponse> {
    await this.stop();
    return this.start();
  }

  private currentConnection(): RuntimeConnection {
    return Object.freeze({
      coreBaseUrl: `http://127.0.0.1:${this.core.port}`,
      coreApiToken: this.core.apiToken,
      instanceId: this.core.instanceId,
    });
  }

  /** Capture a sidecar fault without letting it escape.
   *
   * This is the fault-isolation boundary: a Broker fault must degrade the
   * Runtime, never terminate it. The first fault is retained, later ones are
   * ignored so a fault loop cannot grow unbounded state, and nothing here
   * throws into the caller (which is often an event handler). */
  private recordSidecarFault(code: string): void {
    if (this.sidecarFault !== null) return;
    this.sidecarFault = Object.freeze({
      code: code || "runtime_sidecar_failed",
      at: Date.now(),
    });
    void this.diagnostics?.log({
      level: "error",
      component: "runtime.supervisor",
      event: "runtime.sidecar_failed",
      outcome: "failed",
      instance_id: this.core.instanceId,
      error_code: this.sidecarFault.code,
    });
    try {
      this.onSidecarFault?.(this.sidecarFault);
    } catch {
      // A fault observer must never turn one failure into a fatal one.
    }
  }
}