xytara 3.1.16 → 3.2.0

package/lib/runtime_state_store.js

@@ -1,495 +0,0 @@
-"use strict";
-
-const crypto = require("crypto");
-const fs = require("fs");
-const path = require("path");
-
-function normalizeFilePath(filePath) {
-  const raw = typeof filePath === "string" ? filePath.trim() : "";
-  return raw ? path.resolve(raw) : "";
-}
-
-function normalizeUrl(url) {
-  const raw = typeof url === "string" ? url.trim() : "";
-  return raw ? raw.replace(/\/+$/, "") : "";
-}
-
-function normalizeString(value, fallback = "") {
-  const raw = typeof value === "string" ? value.trim() : "";
-  return raw || fallback;
-}
-
-// Top-level state keys that are PROCESS-LOCAL transient scratch, not durable facts, and
-// must never be snapshotted: persisting them risks restoring a stale entry that briefly
-// misbehaves after a restart. Kept out of the snapshot entirely (no write, no restore).
-const TRANSIENT_STATE_KEYS = new Set(["inFlightPaymentAuthorizations"]);
-
-function stateForSnapshot(state) {
-  if (!state || typeof state !== "object" || Array.isArray(state)) return state;
-  const snapshotSource = {};
-  for (const [key, value] of Object.entries(state)) {
-    if (TRANSIENT_STATE_KEYS.has(key)) continue;
-    snapshotSource[key] = value;
-  }
-  return snapshotSource;
-}
-
-function serializeValue(value) {
-  if (value instanceof Map) {
-    return {
-      __runtime_state_kind: "Map",
-      value: Array.from(value.entries()).map(([key, entry]) => [key, serializeValue(entry)])
-    };
-  }
-  if (value instanceof Set) {
-    return {
-      __runtime_state_kind: "Set",
-      value: Array.from(value.values()).map((entry) => serializeValue(entry))
-    };
-  }
-  if (Array.isArray(value)) {
-    return value.map((entry) => serializeValue(entry));
-  }
-  if (value && typeof value === "object") {
-    return Object.fromEntries(
-      Object.entries(value).map(([key, entry]) => [key, serializeValue(entry)])
-    );
-  }
-  return value;
-}
-
-function deserializeValue(value) {
-  if (Array.isArray(value)) {
-    return value.map((entry) => deserializeValue(entry));
-  }
-  if (!value || typeof value !== "object") {
-    return value;
-  }
-  if (value.__runtime_state_kind === "Map" && Array.isArray(value.value)) {
-    return new Map(value.value.map((entry) => [entry[0], deserializeValue(entry[1])]));
-  }
-  if (value.__runtime_state_kind === "Set" && Array.isArray(value.value)) {
-    return new Set(value.value.map((entry) => deserializeValue(entry)));
-  }
-  return Object.fromEntries(
-    Object.entries(value).map(([key, entry]) => [key, deserializeValue(entry)])
-  );
-}
-
-function createRuntimeStateStore(config = {}) {
-  const filePath = normalizeFilePath(config.filePath);
-  const directoryPath = filePath ? path.dirname(filePath) : "";
-  const intervalMs = Math.max(1000, Number.parseInt(String(config.intervalMs || 15000), 10) || 15000);
-  // Rolling history (Supabase mode): every historyIntervalMs, the snapshot is ALSO written to one of
-  // historySlots rotating rows (`<stateKey>::history::<n>`) in the same table, so a bad write or a
-  // logical clobber of the main row can be rolled back. 0 disables. Off-site copies are separate
-  // (see scripts/state_backup_offsite.js).
-  const historyIntervalMs = config.historyIntervalMs === undefined || config.historyIntervalMs === null || config.historyIntervalMs === ""
-    ? 3600000
-    : Math.max(0, Number(config.historyIntervalMs) || 0);
-  const historySlots = Math.max(1, Math.min(168, Number.parseInt(String(config.historySlots || 24), 10) || 24));
-  const supabaseUrl = normalizeUrl(config.supabaseUrl);
-  const supabaseServiceRoleKey = normalizeString(config.supabaseServiceRoleKey);
-  const supabaseTable = normalizeString(config.supabaseTable, "xytara_runtime_state");
-  const stateKey = normalizeString(config.stateKey, "default");
-  const supabaseTimeoutMs = Math.max(1000, Number.parseInt(String(config.supabaseTimeoutMs || process.env.XYTARA_SUPABASE_TIMEOUT_MS || 10000), 10) || 10000);
-  const storageMode = supabaseUrl && supabaseServiceRoleKey ? "supabase" : filePath ? "file" : "memory";
-  let dirty = false;
-  let timer = null;
-  let lastPersistedAtIso = null;
-  let lastFlushSucceeded = false;
-  let lastError = null;
-  let snapshotExists = false;
-  let snapshotUpdatedAtIso = null;
-  let snapshotSizeBytes = 0;
-  let remoteConfigured = storageMode === "supabase";
-  let remoteReachable = storageMode !== "supabase";
-  let remoteTableReady = storageMode !== "supabase";
-  // WRITE GUARD: nothing is written until the durable snapshot has been read successfully (a
-  // restore, or a confirmed "no snapshot yet"). If the boot-time load fails (e.g. the backend
-  // times out), the process runs on empty state — and writing that would OVERWRITE the good
-  // snapshot. Instead flushes are refused and the load is retried; on success the snapshot is
-  // merged under whatever happened since boot, and only then do writes resume.
-  // Content digest of the last snapshot actually persisted: an unchanged snapshot is never rewritten.
-  let lastPersistedDigest = null;
-  let skippedUnchangedWrites = 0;
-  let lastHistoryAtMs = 0;
-  let lastHistorySlot = null;
-  let lastHistoryError = null;
-  let restoreConfirmed = false;
-  let restoreAttempts = 0;
-  let lastRestoreAttemptAtIso = null;
-  let restoreMergedAfterBoot = false;
-
-  function enabled() {
-    return storageMode !== "memory";
-  }
-
-  // Merge a restored snapshot UNDER the live in-memory state (used only when a restore succeeds
-  // after the process already started on empty state): collections are unioned with live entries
-  // winning; scalars/objects take the restored (durable) value.
-  function mergeRestoredState(state, restored) {
-    if (!restored || typeof restored !== "object" || !state) return false;
-    for (const key of Object.keys(state)) {
-      if (!Object.prototype.hasOwnProperty.call(restored, key)) continue;
-      const live = state[key];
-      const durable = restored[key];
-      if (live instanceof Map && durable instanceof Map) {
-        state[key] = new Map([...durable, ...live]);
-      } else if (live instanceof Set && durable instanceof Set) {
-        state[key] = new Set([...durable, ...live]);
-      } else if (Array.isArray(live) && Array.isArray(durable)) {
-        const seen = new Set(durable.map((entry) => JSON.stringify(entry)));
-        state[key] = durable.concat(live.filter((entry) => !seen.has(JSON.stringify(entry))));
-      } else {
-        state[key] = durable;
-      }
-    }
-    return true;
-  }
-
-  function markDirty() {
-    if (!enabled()) return;
-    dirty = true;
-  }
-
-  function applyRestoredState(state, restored) {
-    if (!restored || typeof restored !== "object" || !state) return false;
-    for (const key of Object.keys(state)) {
-      if (Object.prototype.hasOwnProperty.call(restored, key)) {
-        state[key] = restored[key];
-      }
-    }
-    return true;
-  }
-
-  function inspectFileDirectory() {
-    let exists = false;
-    let writable = false;
-    let error = null;
-    if (storageMode !== "file") {
-      return {
-        exists: false,
-        writable: false,
-        error: null
-      };
-    }
-    try {
-      exists = fs.existsSync(directoryPath);
-      if (exists) {
-        fs.accessSync(directoryPath, fs.constants.W_OK);
-        writable = true;
-      }
-    } catch (issue) {
-      writable = false;
-      error = issue;
-    }
-    return {
-      exists,
-      writable,
-      error
-    };
-  }
-
-  async function fetchSupabase(pathname, options = {}) {
-    // Bounded: a hung Supabase must never stall boot (the server waits for the restore before it
-    // listens) or a flush. A timeout is just a failed attempt; the write guard handles the rest.
-    const response = await fetch(`${supabaseUrl}${pathname}`, {
-      signal: options.signal || AbortSignal.timeout(supabaseTimeoutMs),
-      ...options,
-      headers: {
-        apikey: supabaseServiceRoleKey,
-        authorization: `Bearer ${supabaseServiceRoleKey}`,
-        ...(options.headers || {})
-      }
-    });
-    remoteReachable = true;
-    if (!response.ok) {
-      const text = await response.text();
-      const error = new Error(`supabase_runtime_state_${response.status}: ${text || response.statusText}`);
-      error.status = response.status;
-      throw error;
-    }
-    return response;
-  }
-
-  function updateSuccessSnapshotMetadata(persistedAtIso, snapshotJson) {
-    lastPersistedAtIso = persistedAtIso;
-    lastFlushSucceeded = true;
-    lastError = null;
-    snapshotExists = true;
-    snapshotUpdatedAtIso = persistedAtIso;
-    snapshotSizeBytes = Buffer.byteLength(snapshotJson, "utf8");
-  }
-
-  function digestOf(json) {
-    return crypto.createHash("sha256").update(json, "utf8").digest("hex");
-  }
-
-  function upsertRowBody(key, snapshotJson, persistedAtIso) {
-    return `[{"state_key":${JSON.stringify(key)},"snapshot":${snapshotJson},"persisted_at_iso":${JSON.stringify(persistedAtIso)}}]`;
-  }
-
-  async function upsertSupabaseRow(key, snapshotJson, persistedAtIso) {
-    await fetchSupabase(`/rest/v1/${encodeURIComponent(supabaseTable)}?on_conflict=state_key`, {
-      method: "POST",
-      headers: {
-        "content-type": "application/json",
-        prefer: "resolution=merge-duplicates,return=minimal"
-      },
-      body: upsertRowBody(key, snapshotJson, persistedAtIso)
-    });
-  }
-
-  // Best-effort rolling history copy; never fails the main flush.
-  async function maybeWriteHistory(snapshotJson, persistedAtIso) {
-    if (historyIntervalMs <= 0) return;
-    const nowMs = Date.parse(persistedAtIso);
-    if (lastHistoryAtMs && nowMs - lastHistoryAtMs < historyIntervalMs) return;
-    const slot = Math.floor(nowMs / historyIntervalMs) % historySlots;
-    try {
-      await upsertSupabaseRow(`${stateKey}::history::${slot}`, snapshotJson, persistedAtIso);
-      lastHistoryAtMs = nowMs;
-      lastHistorySlot = slot;
-      lastHistoryError = null;
-    } catch (error) {
-      lastHistoryError = error;
-    }
-  }
-
-  async function flushSupabase(state) {
-    if (!dirty || !state) return false;
-    const persistedAtIso = new Date().toISOString();
-    const snapshotJson = JSON.stringify(serializeValue(stateForSnapshot(state)));
-    const digest = digestOf(snapshotJson);
-    if (digest === lastPersistedDigest) {
-      // Nothing changed since the last successful write (e.g. a read-only POST): skip the rewrite.
-      dirty = false;
-      skippedUnchangedWrites += 1;
-      return false;
-    }
-    try {
-      await upsertSupabaseRow(stateKey, snapshotJson, persistedAtIso);
-      remoteTableReady = true;
-      dirty = false;
-      lastPersistedDigest = digest;
-      updateSuccessSnapshotMetadata(persistedAtIso, snapshotJson);
-      await maybeWriteHistory(snapshotJson, persistedAtIso);
-      return true;
-    } catch (error) {
-      lastFlushSucceeded = false;
-      lastError = error;
-      remoteReachable = false;
-      remoteTableReady = false;
-      throw error;
-    }
-  }
-
-  function flushFile(state) {
-    if (!dirty || !state) return false;
-    try {
-      fs.mkdirSync(path.dirname(filePath), { recursive: true });
-      const tempPath = `${filePath}.tmp`;
-      const persistedAtIso = new Date().toISOString();
-      const serializedSnapshot = serializeValue(stateForSnapshot(state));
-      const snapshotJson = JSON.stringify(serializedSnapshot);
-      const digest = digestOf(snapshotJson);
-      if (digest === lastPersistedDigest) {
-        dirty = false;
-        skippedUnchangedWrites += 1;
-        return false;
-      }
-      const snapshot = {
-        persisted_at_iso: persistedAtIso,
-        state: serializedSnapshot
-      };
-      fs.writeFileSync(tempPath, JSON.stringify(snapshot, null, 2), "utf8");
-      fs.renameSync(tempPath, filePath);
-      dirty = false;
-      lastPersistedDigest = digest;
-      updateSuccessSnapshotMetadata(persistedAtIso, snapshotJson);
-      return true;
-    } catch (error) {
-      lastFlushSucceeded = false;
-      lastError = error;
-      throw error;
-    }
-  }
-
-  async function flush(state) {
-    if (!enabled() || !dirty || !state) return false;
-    if (!restoreConfirmed) return false; // never overwrite a snapshot we have not read yet
-    if (storageMode === "supabase") {
-      return flushSupabase(state);
-    }
-    if (storageMode === "file") {
-      return flushFile(state);
-    }
-    return false;
-  }
-
-  async function loadSupabase(state, options = {}) {
-    try {
-      const response = await fetchSupabase(
-        `/rest/v1/${encodeURIComponent(supabaseTable)}?state_key=eq.${encodeURIComponent(stateKey)}&select=snapshot,persisted_at_iso&limit=1`
-      );
-      const rows = await response.json();
-      const row = Array.isArray(rows) && rows[0] ? rows[0] : null;
-      remoteTableReady = true;
-      if (!row || !row.snapshot) {
-        dirty = Boolean(options.merge && dirty);
-        lastFlushSucceeded = true;
-        lastError = null;
-        snapshotExists = false;
-        return false;
-      }
-      const restored = deserializeValue(row.snapshot);
-      const applied = options.merge ? mergeRestoredState(state, restored) : applyRestoredState(state, restored);
-      // After a late merge the live state now holds snapshot + post-boot changes: persist it.
-      dirty = Boolean(options.merge);
-      lastPersistedAtIso = row.persisted_at_iso ? String(row.persisted_at_iso) : null;
-      lastFlushSucceeded = true;
-      lastError = null;
-      snapshotExists = applied;
-      snapshotUpdatedAtIso = lastPersistedAtIso;
-      snapshotSizeBytes = Buffer.byteLength(JSON.stringify(row.snapshot), "utf8");
-      return applied;
-    } catch (error) {
-      lastFlushSucceeded = false;
-      lastError = error;
-      remoteReachable = false;
-      remoteTableReady = false;
-      throw error;
-    }
-  }
-
-  async function loadFile(state, options = {}) {
-    if (!state || !fs.existsSync(filePath)) return false;
-    const raw = fs.readFileSync(filePath, "utf8");
-    const parsed = JSON.parse(raw);
-    const restored = deserializeValue(parsed && parsed.state ? parsed.state : parsed);
-    const applied = options.merge ? mergeRestoredState(state, restored) : applyRestoredState(state, restored);
-    dirty = Boolean(options.merge);
-    lastPersistedAtIso = parsed && parsed.persisted_at_iso ? String(parsed.persisted_at_iso) : null;
-    lastFlushSucceeded = true;
-    lastError = null;
-    snapshotExists = applied;
-    snapshotUpdatedAtIso = parsed && parsed.persisted_at_iso ? String(parsed.persisted_at_iso) : null;
-    snapshotSizeBytes = Buffer.byteLength(raw, "utf8");
-    return applied;
-  }
-
-  // options.merge: the process already ran on empty state, so merge the snapshot under the live
-  // state instead of replacing it. Any successful read (restore OR confirmed-empty) unlocks writes;
-  // a failed read leaves writes locked and the error propagates to the caller.
-  async function load(state, options = {}) {
-    if (!enabled() || !state) return false;
-    restoreAttempts += 1;
-    lastRestoreAttemptAtIso = new Date().toISOString();
-    let result = false;
-    if (storageMode === "supabase") {
-      result = await loadSupabase(state, options);
-    } else if (storageMode === "file") {
-      result = await loadFile(state, options);
-    }
-    restoreConfirmed = true;
-    if (options.merge) restoreMergedAfterBoot = true;
-    return result;
-  }
-
-  function restoreConfirmedState() {
-    return restoreConfirmed;
-  }
-
-  function inspect() {
-    const fileDirectory = inspectFileDirectory();
-    const fileStats = storageMode === "file" && snapshotExists && fs.existsSync(filePath)
-      ? fs.statSync(filePath)
-      : null;
-    return {
-      enabled: enabled(),
-      storage_mode: storageMode,
-      file_path: filePath || null,
-      directory_path: directoryPath || null,
-      interval_ms: intervalMs,
-      dirty,
-      timer_active: Boolean(timer),
-      directory_exists: storageMode === "file" ? fileDirectory.exists : false,
-      directory_writable: storageMode === "file" ? fileDirectory.writable : false,
-      directory_error: storageMode === "file" && fileDirectory.error ? fileDirectory.error.message : null,
-      snapshot_exists: snapshotExists,
-      snapshot_size_bytes: fileStats ? fileStats.size : snapshotSizeBytes,
-      snapshot_updated_at_iso: fileStats ? fileStats.mtime.toISOString() : snapshotUpdatedAtIso,
-      last_persisted_at_iso: lastPersistedAtIso,
-      last_flush_succeeded: lastFlushSucceeded,
-      last_error: lastError ? lastError.message : null,
-      supabase_url: supabaseUrl || null,
-      supabase_table: storageMode === "supabase" ? supabaseTable : null,
-      supabase_state_key: storageMode === "supabase" ? stateKey : null,
-      remote_configured: remoteConfigured,
-      remote_reachable: remoteReachable,
-      remote_table_ready: remoteTableReady,
-      skipped_unchanged_writes: skippedUnchangedWrites,
-      history_interval_ms: storageMode === "supabase" ? historyIntervalMs : null,
-      history_slots: storageMode === "supabase" ? historySlots : null,
-      last_history_at_iso: lastHistoryAtMs ? new Date(lastHistoryAtMs).toISOString() : null,
-      last_history_slot: lastHistorySlot,
-      last_history_error: lastHistoryError ? lastHistoryError.message : null,
-      restore_confirmed: restoreConfirmed,
-      writes_locked_until_restore: enabled() && !restoreConfirmed,
-      restore_attempts: restoreAttempts,
-      last_restore_attempt_at_iso: lastRestoreAttemptAtIso,
-      restore_merged_after_boot: restoreMergedAfterBoot
-    };
-  }
-
-  // onRestored(restored): optional callback when a deferred restore finally succeeds.
-  function start(state, onRestored) {
-    if (!enabled() || timer) return;
-    let busy = false;
-    timer = setInterval(() => {
-      if (busy) return;
-      busy = true;
-      const step = restoreConfirmed
-        ? Promise.resolve(flush(state))
-        : Promise.resolve(load(state, { merge: true })).then((restored) => {
-            console.log("xytara runtime state restore succeeded after boot; writes unlocked");
-            if (typeof onRestored === "function") onRestored(restored);
-          });
-      step.catch((error) => {
-        console.error(restoreConfirmed ? "runtime state snapshot flush failed" : "runtime state restore retry failed (writes stay locked)", error && error.message ? error.message : error);
-      }).finally(() => { busy = false; });
-    }, intervalMs);
-    if (typeof timer.unref === "function") timer.unref();
-  }
-
-  async function stop(state) {
-    if (timer) {
-      clearInterval(timer);
-      timer = null;
-    }
-    try {
-      await flush(state);
-    } catch (error) {
-      console.error("runtime state snapshot final flush failed", error);
-    }
-  }
-
-  return {
-    enabled,
-    storageMode,
-    filePath,
-    intervalMs,
-    inspect,
-    load,
-    restoreConfirmed: restoreConfirmedState,
-    markDirty,
-    flush,
-    start,
-    stop
-  };
-}
-
-module.exports = {
-  createRuntimeStateStore
-};