Skip to content
Python
6.1 KB
Raw Blame
/** `memhub backup restore`: drive Core's managed restore from a stopped Runtime.
 *
 * Contract: docs/contracts/c0-ui-and-restore-contract.md (C0, H25) and Core
 * commit `a8ade00`. Restore replaces the business database, so Core refuses it
 * from a Runtime-owning process (`backup_restore_runtime_running`). The CLI
 * therefore starts a *non-owning* maintenance Core (`one-memory serve
 * --maintenance`) against the same data dir, calls
 * `POST /api/v1/backup/restore`, and then tears that process down. Core keeps
 * the safety envelope (managed `backups/` source, protective copy, atomic
 * replace, stable failure codes); the CLI only adds preview + explicit confirm.
 */

export interface RestoreResult {
  state: "restored";
  restoredBytes: number;
  previousBackupPath: string;
  sourceSchemaVersion: number;
}

export type RestoreOutcome =
  | { state: "restored" }
  | { state: "rejected"; code: string };

const CONTRACT_CODES = new Set([
  "backup_restore_runtime_running",
  "backup_restore_source_outside_home",
  "backup_restore_source_invalid",
  "backup_restore_source_too_new",
  "backup_restore_protective_backup_failed",
  "backup_restore_replace_failed",
]);

/** Validate the HTTP result. Anything malformed returns null so the caller
 * reports a failure rather than a false "restored". */
export function normalizeRestoreResult(value: unknown): RestoreResult | null {
  if (value === null || typeof value !== "object" || Array.isArray(value)) {
    return null;
  }
  const record = value as Record<string, unknown>;
  if (record.state !== "restored") return null;
  if (
    typeof record.restored_bytes !== "number" ||
    !Number.isInteger(record.restored_bytes) ||
    record.restored_bytes < 0
  ) {
    return null;
  }
  if (
    typeof record.previous_backup_path !== "string" ||
    record.previous_backup_path === ""
  ) {
    return null;
  }
  if (
    typeof record.source_schema_version !== "number" ||
    !Number.isInteger(record.source_schema_version) ||
    record.source_schema_version < 0
  ) {
    return null;
  }
  return {
    state: "restored",
    restoredBytes: record.restored_bytes,
    previousBackupPath: record.previous_backup_path,
    sourceSchemaVersion: record.source_schema_version,
  };
}

/** Map a Core detail code to the CLI vocabulary. Unknown codes stay visible as
 * a generic failure, never as success. */
export function restoreFailure(code: string): { code: string } {
  return { code: CONTRACT_CODES.has(code) ? code : "backup_restore_failed" };
}

export function restoreExitCode(outcome: RestoreOutcome): number {
  return outcome.state === "restored" ? 0 : 1;
}

export function restoreIsDestructive(): true {
  return true;
}

/** The loopback call itself, factored out so it can be exercised against a
 * real socket in tests. */
export async function callRestore(
  options: {
    host: string;
    port: number;
    apiToken: string;
  },
  source: string,
  request: typeof defaultPost = defaultPost,
): Promise<
  | { state: "restored"; result: RestoreResult }
  | { state: "rejected"; code: string }
> {
  const response = await request(
    `http://${options.host}:${options.port}/api/v1/backup/restore`,
    { source },
    {
      Authorization: `Bearer ${options.apiToken}`,
    },
  );
  if (response.status === 200) {
    const result = normalizeRestoreResult(response.data);
    return result === null
      ? { state: "rejected", code: "backup_restore_failed" }
      : { state: "restored", result };
  }
  if (response.status === 409) {
    // Runtime still owns the data dir. Distinguish it from transport errors.
    return { state: "rejected", code: "backup_restore_runtime_running" };
  }
  if (response.status === 404) {
    // Core predates the endpoint.
    return { state: "rejected", code: "backup_restore_contract_unavailable" };
  }
  const detail = (response.data as { detail?: unknown } | null)?.detail;
  if (typeof detail === "string") {
    return { state: "rejected", ...restoreFailure(detail) };
  }
  return { state: "rejected", code: "backup_restore_failed" };
}

type Post = (
  url: string,
  body: unknown,
  headers: Record<string, string>,
) => Promise<{ status: number; data: unknown }>;

type Get = (
  url: string,
  headers: Record<string, string>,
) => Promise<{ status: number; data: unknown }>;

/** Verify that the process answering on the maintenance port is the Core
 * instance this CLI just launched. The health call carries no Authorization;
 * the bearer is only sent after the exact instance id matches. */
export async function verifyMaintenanceCoreIdentity(
  options: { host: string; port: number; instanceId: string },
  request: Get = defaultGet,
): Promise<boolean> {
  let response: { status: number; data: unknown };
  try {
    response = await request(
      `http://${options.host}:${options.port}/api/v1/health`,
      {},
    );
  } catch {
    return false;
  }
  if (response.status !== 200) return false;
  if (
    response.data === null ||
    typeof response.data !== "object" ||
    Array.isArray(response.data)
  ) {
    return false;
  }
  const body = response.data as Record<string, unknown>;
  return (
    body.status === "ok" &&
    body.service === "one-memory-core" &&
    body.instance_id === options.instanceId
  );
}

async function defaultGet(
  url: string,
  headers: Record<string, string>,
): Promise<{ status: number; data: unknown }> {
  const { default: axios } = await import("axios");
  const response = await axios.get(url, {
    headers,
    timeout: 2_000,
    proxy: false,
    maxRedirects: 0,
    maxContentLength: 4 * 1024 * 1024,
    validateStatus: () => true,
  });
  return { status: response.status, data: response.data };
}

async function defaultPost(
  url: string,
  body: unknown,
  headers: Record<string, string>,
): Promise<{ status: number; data: unknown }> {
  const { default: axios } = await import("axios");
  const response = await axios.post(url, body, {
    headers,
    timeout: 120_000,
    proxy: false,
    maxRedirects: 0,
    maxContentLength: 4 * 1024 * 1024,
    maxBodyLength: 64 * 1024,
    validateStatus: () => true,
  });
  return { status: response.status, data: response.data };
}