cnc_wams/wasm-port/runtime/opfs/snapshot-store.js

import { loadTextFile, saveTextFile } from "./file-service.js";
import {
  gcodeProgramPath,
  machineIniPath,
  normalizeOpfsPath,
  parameterFilePath,
  sessionSnapshotPath,
  toolTablePath,
} from "./path-model.js";
import {
  VIRTUAL_HAL_SIM_CONFIG_MACRO_LOAD_FIXTURES,
  VIRTUAL_HAL_SIM_CONFIG_PROMOTION_CANDIDATES,
  VIRTUAL_HAL_SIM_CONFIG_SOURCE_TARGETS,
  cloneVirtualHalState,
  createVirtualHalCommandScriptFixtureReport,
  createVirtualHalMotionControllerMatrixReport,
  createVirtualHalSimConfigMacroLoadFixtureReport,
  createVirtualHalSimConfigPromotionCandidateReport,
  createVirtualHalSimConfigSourceCoverageReport,
  createVirtualHalSimulationReplacementReport,
  createVirtualHalSourceComplianceReport,
  createVirtualHalState,
} from "../sdk/src/linuxcnc-hal.js";

export const SESSION_SNAPSHOT_FORMAT = "linuxcnc-wasm-session-snapshot";
export const SESSION_SNAPSHOT_VERSION = 1;

function assertPlainObject(value, label) {
  if (value === null || typeof value !== "object" || Array.isArray(value)) {
    throw new Error(`${label} must be a plain object.`);
  }
}

function optionalOpfsPath(value, label) {
  if (value === undefined) {
    return undefined;
  }
  if (typeof value !== "string") {
    throw new Error(`${label} must be a string.`);
  }
  return normalizeOpfsPath(value);
}

function requiredSnapshotFilePath(files, key, label) {
  const value = files[key];
  if (typeof value !== "string") {
    throw new Error(`${label} must be a string.`);
  }
  return normalizeOpfsPath(value);
}

function validateMachineSessionSnapshotPayload(payload, machineId) {
  assertPlainObject(payload, "machine session snapshot payload");
  if (payload.machineId !== machineId) {
    throw new Error(`Machine session snapshot id mismatch: ${payload.machineId}`);
  }
  assertPlainObject(payload.files, "machine session snapshot files");
  requiredSnapshotFilePath(payload.files, "ini", "machine session INI OPFS path");
  requiredSnapshotFilePath(payload.files, "parameters", "machine session parameter OPFS path");
  requiredSnapshotFilePath(payload.files, "toolTable", "machine session tool table OPFS path");
  optionalOpfsPath(payload.files.gcode, "machine session G-code OPFS path");
  if (payload.virtualHal !== undefined) {
    validateVirtualHalSessionPayload(payload.virtualHal);
  }
  return payload;
}

function validateVirtualHalSessionPayload(virtualHal) {
  assertPlainObject(virtualHal, "virtual HAL session payload");
  assertPlainObject(virtualHal.state, "virtual HAL session state");
  assertPlainObject(virtualHal.diagnostics, "virtual HAL session diagnostics");
  assertPlainObject(virtualHal.sourceCompliance, "virtual HAL session source compliance");
  assertPlainObject(virtualHal.simConfigSourceCoverage, "virtual HAL session sim-config source coverage");
  assertPlainObject(virtualHal.simConfigPromotionCandidates, "virtual HAL session sim-config promotion candidates");
  assertPlainObject(virtualHal.simConfigMacroLoadFixtures, "virtual HAL session sim-config macro/load fixtures");
  assertPlainObject(virtualHal.commandScriptFixtures, "virtual HAL session command script fixtures");
  assertPlainObject(virtualHal.motionControllerMatrix, "virtual HAL session motion controller matrix");
  if (virtualHal.state.source !== "browser-virtual-hal") {
    throw new Error(`Unsupported virtual HAL state source: ${virtualHal.state.source}`);
  }
  if (virtualHal.sourceCompliance.complete !== true) {
    throw new Error("virtual HAL source compliance is incomplete.");
  }
  if (virtualHal.simConfigSourceCoverage.complete !== true) {
    throw new Error("virtual HAL sim-config source coverage is incomplete.");
  }
  if (virtualHal.simConfigPromotionCandidates.complete !== true) {
    throw new Error("virtual HAL sim-config promotion candidates are incomplete.");
  }
  if (virtualHal.simConfigMacroLoadFixtures.complete !== true) {
    throw new Error("virtual HAL sim-config macro/load fixtures are incomplete.");
  }
  if (virtualHal.commandScriptFixtures.complete !== true) {
    throw new Error("virtual HAL command script fixtures are incomplete.");
  }
  if (virtualHal.motionControllerMatrix.complete !== true) {
    throw new Error("virtual HAL motion controller matrix is incomplete.");
  }
  return virtualHal;
}

export function createVirtualHalSessionPayload(halState = createVirtualHalState(), options = {}) {
  const state = cloneVirtualHalState(halState);
  const reportOptions = {
    ...options,
    ...(
      options.manifestText === undefined && options.manifestEntries === undefined
        ? {
            manifestEntries: [
              ...VIRTUAL_HAL_SIM_CONFIG_SOURCE_TARGETS.flatMap((target) => target.sourceFiles ?? []),
              ...VIRTUAL_HAL_SIM_CONFIG_PROMOTION_CANDIDATES.flatMap((candidate) => candidate.sourceFiles ?? []),
              ...VIRTUAL_HAL_SIM_CONFIG_MACRO_LOAD_FIXTURES.flatMap((fixture) => fixture.sourceFiles ?? []),
            ],
          }
        : {}
    ),
  };
  const simConfigSourceCoverage = options.simConfigSourceCoverage ?? createVirtualHalSimConfigSourceCoverageReport(reportOptions);
  const simConfigMacroLoadFixtures = options.simConfigMacroLoadFixtures ?? createVirtualHalSimConfigMacroLoadFixtureReport(reportOptions);
  const commandScriptFixtures = options.commandScriptFixtures ?? createVirtualHalCommandScriptFixtureReport({ ...reportOptions, halState: state });
  const motionControllerMatrix = options.motionControllerMatrix ?? createVirtualHalMotionControllerMatrixReport(reportOptions);
  const simConfigPromotionCandidates = options.simConfigPromotionCandidates ?? createVirtualHalSimConfigPromotionCandidateReport({
    ...reportOptions,
    simConfigSourceCoverage,
    commandScriptFixtures,
    motionControllerMatrix,
  });
  const sourceCompliance = options.sourceCompliance ?? createVirtualHalSourceComplianceReport({
    ...reportOptions,
    halState: state,
    simConfigSourceCoverage,
    commandScriptFixtures,
    motionControllerMatrix,
  });
  const diagnostics = options.diagnostics ?? createVirtualHalSimulationReplacementReport(state, {
    ...reportOptions,
    sourceCompliance,
    simConfigSourceCoverage,
    commandScriptFixtures,
    motionControllerMatrix,
  });
  return validateVirtualHalSessionPayload({
    apiName: "linuxcnc-wasm-virtual-hal-session-payload",
    payloadVersion: 1,
    source: "browser-virtual-hal",
    state,
    diagnostics,
    sourceCompliance,
    simConfigSourceCoverage,
    simConfigPromotionCandidates,
    simConfigMacroLoadFixtures,
    commandScriptFixtures,
    motionControllerMatrix,
  });
}

export function restoreVirtualHalStateFromSessionSnapshot(snapshot) {
  assertPlainObject(snapshot, "session snapshot");
  const virtualHal = validateVirtualHalSessionPayload(snapshot.payload?.virtualHal);
  return cloneVirtualHalState(virtualHal.state);
}

export function createMachineSessionSnapshotPayload(machineId, options = {}) {
  assertPlainObject(options, "machine session snapshot options");
  const ini = optionalOpfsPath(options.iniOpfsPath, "INI OPFS path") ??
    machineIniPath(machineId, options.iniFilename);
  const parameters = optionalOpfsPath(options.parameterOpfsPath, "parameter OPFS path") ??
    parameterFilePath(machineId, options.parameterFilename);
  const toolTable = optionalOpfsPath(options.toolTableOpfsPath, "tool table OPFS path") ??
    toolTablePath(machineId, options.toolTableFilename);
  const gcode = optionalOpfsPath(options.gcodeOpfsPath, "G-code OPFS path") ??
    (options.gcodeFilename === undefined ? undefined : gcodeProgramPath(options.gcodeFilename));
  const virtualHal = options.virtualHalState === undefined && options.virtualHal === undefined
    ? undefined
    : (options.virtualHal ?? createVirtualHalSessionPayload(options.virtualHalState, options.virtualHalOptions ?? {}));

  return {
    machineId,
    files: {
      ini,
      parameters,
      toolTable,
      ...(gcode === undefined ? {} : { gcode }),
    },
    ...(virtualHal === undefined ? {} : { virtualHal }),
  };
}

export function createSessionSnapshot(sessionId, payload, options = {}) {
  sessionSnapshotPath(sessionId, options.filename);
  assertPlainObject(payload, "snapshot payload");
  if (options.metadata !== undefined) {
    assertPlainObject(options.metadata, "snapshot metadata");
  }

  return {
    format: SESSION_SNAPSHOT_FORMAT,
    version: SESSION_SNAPSHOT_VERSION,
    sessionId,
    createdAt: options.createdAt ?? new Date().toISOString(),
    metadata: options.metadata ?? {},
    payload,
  };
}

export function validateSessionSnapshot(snapshot, sessionId) {
  assertPlainObject(snapshot, "session snapshot");
  if (snapshot.format !== SESSION_SNAPSHOT_FORMAT) {
    throw new Error(`Unsupported session snapshot format: ${snapshot.format}`);
  }
  if (snapshot.version !== SESSION_SNAPSHOT_VERSION) {
    throw new Error(`Unsupported session snapshot version: ${snapshot.version}`);
  }
  if (snapshot.sessionId !== sessionId) {
    throw new Error(`Session snapshot id mismatch: ${snapshot.sessionId}`);
  }
  assertPlainObject(snapshot.metadata, "snapshot metadata");
  assertPlainObject(snapshot.payload, "snapshot payload");
  return snapshot;
}

export async function saveSessionSnapshot(sessionId, payload, options = {}) {
  const snapshot = createSessionSnapshot(sessionId, payload, options);
  const path = sessionSnapshotPath(sessionId, options.filename);
  await saveTextFile(path, `${JSON.stringify(snapshot, null, 2)}\n`, options.storage);
  return snapshot;
}

export async function saveMachineSessionSnapshot(sessionId, machineId, options = {}) {
  assertPlainObject(options, "machine session snapshot save options");
  const payload = createMachineSessionSnapshotPayload(machineId, options);
  return saveSessionSnapshot(sessionId, payload, options);
}

export async function loadMachineSessionSnapshot(sessionId, machineId, options = {}) {
  const snapshot = await loadSessionSnapshot(sessionId, options);
  validateMachineSessionSnapshotPayload(snapshot.payload, machineId);
  return snapshot;
}

export async function loadSessionSnapshot(sessionId, options = {}) {
  const path = sessionSnapshotPath(sessionId, options.filename);
  const text = await loadTextFile(path, options.storage);
  let snapshot;
  try {
    snapshot = JSON.parse(text);
  } catch (error) {
    throw new Error(`Invalid session snapshot JSON: ${error.message}`);
  }
  return validateSessionSnapshot(snapshot, sessionId);
}