@secondlayer/shared 7.9.0 → 7.11.0

package/dist/src/runtime/index.js

@@ -0,0 +1,694 @@
+import { createRequire } from "node:module";
+var __defProp = Object.defineProperty;
+var __returnValue = (v) => v;
+function __exportSetter(name, newValue) {
+  this[name] = __returnValue.bind(null, newValue);
+}
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, {
+      get: all[name],
+      enumerable: true,
+      configurable: true,
+      set: __exportSetter.bind(all, name)
+    });
+};
+
+// src/runtime/modules.ts
+var MODULE_IDS = [
+  "api",
+  "ingest",
+  "decoder",
+  "subgraph",
+  "notification",
+  "verification",
+  "publisher"
+];
+var MODULE_STATES = [
+  "stopped",
+  "starting",
+  "running",
+  "degraded",
+  "failed"
+];
+var DEFAULT_PROFILE = [
+  "api",
+  "ingest",
+  "decoder",
+  "subgraph",
+  "notification",
+  "verification"
+];
+var PUBLISHER_PROFILE = ["publisher"];
+function isModuleId(value) {
+  return MODULE_IDS.includes(value);
+}
+function emptyHealth(id) {
+  return { id, state: "stopped", detail: null, restarts: 0 };
+}
+function createMemoryModule(id, opts) {
+  let health = emptyHealth(id);
+  return {
+    id,
+    setState(state, detail) {
+      health = { ...health, state, detail: detail ?? health.detail };
+    },
+    async start() {
+      if (opts?.failStart) {
+        health = {
+          ...health,
+          state: "failed",
+          detail: "start failed"
+        };
+        throw new Error(`${id} start failed`);
+      }
+      opts?.onStart?.();
+      health = {
+        ...health,
+        state: opts?.loop ? "failed" : "running",
+        detail: opts?.loop ? "loop contained" : null,
+        restarts: health.restarts
+      };
+      if (opts?.loop)
+        throw new Error(`${id} loop`);
+    },
+    async stop() {
+      opts?.onStop?.();
+      health = { ...health, state: "stopped" };
+    },
+    health: () => health
+  };
+}
+// src/runtime/supervisor.ts
+function createSupervisor(modules) {
+  const byId = new Map(modules.map((m) => [m.id, m]));
+  const selected = new Set;
+  const restarts = new Map;
+  function snapshot() {
+    return [...byId.values()].map((mod) => {
+      const health = selected.has(mod.id) ? mod.health() : emptyHealth(mod.id);
+      return { ...health, restarts: restarts.get(mod.id) ?? health.restarts };
+    });
+  }
+  function aggregate(list) {
+    const live = list.filter((m) => selected.has(m.id));
+    if (live.length === 0)
+      return "failed";
+    if (live.every((m) => m.state === "failed" || m.state === "stopped")) {
+      return "failed";
+    }
+    if (live.some((m) => m.state === "failed" || m.state === "degraded")) {
+      return "degraded";
+    }
+    if (live.every((m) => m.state === "running"))
+      return "healthy";
+    return "degraded";
+  }
+  return {
+    async start(ids) {
+      const targets = ids ?? [...byId.keys()];
+      for (const id of targets) {
+        const mod = byId.get(id);
+        if (!mod)
+          continue;
+        selected.add(id);
+        try {
+          await mod.start();
+        } catch {}
+      }
+    },
+    async stop(id) {
+      if (id) {
+        const mod = byId.get(id);
+        if (mod && selected.has(id))
+          await mod.stop();
+        selected.delete(id);
+        return;
+      }
+      for (const mid of [...selected]) {
+        const mod = byId.get(mid);
+        if (mod)
+          await mod.stop();
+        selected.delete(mid);
+      }
+    },
+    async restart(id) {
+      const mod = byId.get(id);
+      if (!mod)
+        throw new Error(`unknown module ${id}`);
+      if (selected.has(id))
+        await mod.stop();
+      selected.add(id);
+      restarts.set(id, (restarts.get(id) ?? 0) + 1);
+      try {
+        await mod.start();
+      } catch {}
+    },
+    health() {
+      const modules2 = snapshot();
+      return { status: aggregate(modules2), modules: modules2 };
+    }
+  };
+}
+// src/runtime/isolate.ts
+var ISOLATION_FAULTS = [
+  "timeout",
+  "throw",
+  "oom",
+  "kill",
+  "network"
+];
+
+class IsolationNetworkError extends Error {
+  name = "IsolationNetworkError";
+}
+
+class IsolationKillError extends Error {
+  name = "IsolationKillError";
+}
+
+class IsolationOomError extends Error {
+  name = "IsolationOomError";
+}
+async function isolateHandler(run, limits) {
+  const controller = new AbortController;
+  const timer = setTimeout(() => controller.abort(), limits.timeoutMs);
+  const blockedFetch = async (_url) => {
+    throw new IsolationNetworkError("network is disabled in this handler");
+  };
+  try {
+    await run({
+      signal: controller.signal,
+      fetch: limits.allowNetwork ? (url) => fetch(url) : blockedFetch
+    });
+    if (controller.signal.aborted) {
+      return {
+        ok: false,
+        fault: "timeout",
+        hostAlive: true,
+        detail: `exceeded ${limits.timeoutMs}ms`
+      };
+    }
+    return { ok: true, hostAlive: true };
+  } catch (error) {
+    if (controller.signal.aborted || isAbort(error)) {
+      return {
+        ok: false,
+        fault: "timeout",
+        hostAlive: true,
+        detail: `exceeded ${limits.timeoutMs}ms`
+      };
+    }
+    if (error instanceof IsolationNetworkError) {
+      return {
+        ok: false,
+        fault: "network",
+        hostAlive: true,
+        detail: error.message
+      };
+    }
+    if (error instanceof IsolationKillError) {
+      return {
+        ok: false,
+        fault: "kill",
+        hostAlive: true,
+        detail: error.message
+      };
+    }
+    if (error instanceof IsolationOomError) {
+      return {
+        ok: false,
+        fault: "oom",
+        hostAlive: true,
+        detail: error.message
+      };
+    }
+    return {
+      ok: false,
+      fault: "throw",
+      hostAlive: true,
+      detail: error instanceof Error ? error.message : String(error)
+    };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+function isAbort(error) {
+  return error instanceof Error && error.name === "AbortError";
+}
+// src/runtime/migrate-embed.ts
+var MIGRATION_LOCK_KEY = 1397509447;
+async function migrateEmbedded(runner) {
+  const got = await runner.acquire(MIGRATION_LOCK_KEY);
+  if (!got) {
+    return {
+      applied: [],
+      ok: false,
+      error: "migration lock held by another process"
+    };
+  }
+  try {
+    const applied = await runner.apply();
+    return { applied, ok: true, error: null };
+  } catch (error) {
+    return {
+      applied: [],
+      ok: false,
+      error: error instanceof Error ? error.message : String(error)
+    };
+  } finally {
+    await runner.release(MIGRATION_LOCK_KEY);
+  }
+}
+function createMemoryMigrationRunner(opts) {
+  let held = false;
+  const state = { holders: 0, appliedCount: 0 };
+  return {
+    get holders() {
+      return state.holders;
+    },
+    get appliedCount() {
+      return state.appliedCount;
+    },
+    async acquire() {
+      if (held)
+        return false;
+      held = true;
+      state.holders += 1;
+      return true;
+    },
+    async release() {
+      held = false;
+      state.holders = Math.max(0, state.holders - 1);
+    },
+    async apply() {
+      if (opts?.delayMs)
+        await (opts.sleep ?? delay)(opts.delayMs);
+      if (opts?.fail)
+        throw new Error("migration failed");
+      state.appliedCount += 1;
+      return ["0116_coverage_schema"];
+    }
+  };
+}
+function delay(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+// src/runtime/config.ts
+var NODE_MODES = ["external", "stacks", "full"];
+var NETWORKS = ["mainnet", "testnet", "devnet"];
+var REQUIRED_KEYS = [
+  "NETWORK",
+  "DATABASE_URL",
+  "NODE_MODE",
+  "DATA_DIR",
+  "API_PORT",
+  "INDEXER_PORT"
+];
+var OPTIONAL_KEYS = [
+  "STACKS_NODE_RPC_URL",
+  "LISTEN_HOST",
+  "LOG_LEVEL",
+  "INSTANCE_MODE"
+];
+var SECRET_KEYS = [
+  "INSTANCE_TOKEN",
+  "API_KEY",
+  "SECONDLAYER_SECRETS_KEY",
+  "STREAMS_SIGNING_PRIVATE_KEY",
+  "SECONDLAYER_WEBHOOK_SIGNING_PRIVATE_KEY",
+  "POSTGRES_PASSWORD",
+  "BITCOIN_RPC_PASSWORD"
+];
+var KNOWN = new Set([
+  ...REQUIRED_KEYS,
+  ...OPTIONAL_KEYS,
+  ...SECRET_KEYS,
+  "SOURCE_DATABASE_URL",
+  "TARGET_DATABASE_URL",
+  "INSTANCE_MODE",
+  "NODE_ENV",
+  "ALLOW_UNSIGNED_WEBHOOKS",
+  "OBSERVER_JOURNAL_ENABLED",
+  "STACKS_NETWORK"
+]);
+function parseRuntimeConfig(env) {
+  const errors = [];
+  for (const key of Object.keys(env)) {
+    if (env[key] === undefined)
+      continue;
+    if (key.startsWith("SL_") || key.startsWith("POSTGRES_"))
+      continue;
+    if (!KNOWN.has(key) && isRuntimeish(key)) {
+      errors.push(`unknown config ${key}`);
+    }
+  }
+  const network = (env.NETWORK ?? env.STACKS_NETWORK ?? "").trim();
+  if (!isNetwork(network)) {
+    errors.push("NETWORK must be mainnet | testnet | devnet");
+  }
+  const database = (env.DATABASE_URL ?? "").trim();
+  if (!database)
+    errors.push("DATABASE_URL is required");
+  const mode = (env.NODE_MODE ?? "").trim();
+  if (!isNodeMode(mode)) {
+    errors.push("NODE_MODE must be external | stacks | full");
+  }
+  const dataDir = (env.DATA_DIR ?? "/data").trim();
+  const apiPort = parsePort(env.API_PORT ?? "3800", "API_PORT", errors);
+  const indexerPort = parsePort(env.INDEXER_PORT ?? "3700", "INDEXER_PORT", errors);
+  if (mode === "external" && env.BITCOIN_RPC_PASSWORD) {
+    errors.push("NODE_MODE=external contradicts BITCOIN_RPC_PASSWORD");
+  }
+  if (mode === "full" && !env.BITCOIN_RPC_PASSWORD) {
+    errors.push("NODE_MODE=full requires BITCOIN_RPC_PASSWORD");
+  }
+  if (mode === "stacks" && env.BITCOIN_RPC_PASSWORD) {
+    errors.push("NODE_MODE=stacks uses public Bitcoin; drop BITCOIN_RPC_PASSWORD");
+  }
+  if (errors.length > 0)
+    return { ok: false, errors };
+  return {
+    ok: true,
+    config: {
+      NETWORK: network,
+      DATABASE_URL: database,
+      NODE_MODE: mode,
+      DATA_DIR: dataDir,
+      API_PORT: apiPort,
+      INDEXER_PORT: indexerPort,
+      STACKS_NODE_RPC_URL: env.STACKS_NODE_RPC_URL?.trim() || null,
+      LISTEN_HOST: env.LISTEN_HOST?.trim() || "0.0.0.0",
+      LOG_LEVEL: env.LOG_LEVEL?.trim() || "info"
+    }
+  };
+}
+function isNetwork(value) {
+  return NETWORKS.includes(value);
+}
+function isNodeMode(value) {
+  return NODE_MODES.includes(value);
+}
+function isRuntimeish(key) {
+  return /^[A-Z][A-Z0-9_]+$/.test(key);
+}
+function parsePort(raw, name, errors) {
+  const n = Number(raw);
+  if (!Number.isInteger(n) || n < 1 || n > 65535) {
+    errors.push(`${name} must be a TCP port`);
+    return 0;
+  }
+  return n;
+}
+// src/runtime/status.ts
+var STATUS_PLANES = [
+  "node",
+  "raw",
+  "decoder",
+  "subgraph",
+  "queue",
+  "archive",
+  "disk",
+  "coverage"
+];
+var MODULE_TO_PLANE = {
+  ingest: "raw",
+  decoder: "decoder",
+  subgraph: "subgraph",
+  notification: "queue",
+  verification: "coverage"
+};
+function reportRuntimeStatus(input) {
+  const planes = [];
+  planes.push({
+    plane: "node",
+    state: input.node ?? "unknown",
+    action: actionFor("node", input.node ?? "unknown")
+  });
+  for (const mod of input.supervisor.modules) {
+    const plane = MODULE_TO_PLANE[mod.id];
+    if (!plane)
+      continue;
+    planes.push({
+      plane,
+      state: mod.state,
+      action: actionFor(plane, mod.state)
+    });
+  }
+  planes.push({
+    plane: "archive",
+    state: input.archive ?? "idle",
+    action: actionFor("archive", input.archive ?? "idle")
+  });
+  planes.push({
+    plane: "disk",
+    state: input.disk ?? "ok",
+    action: actionFor("disk", input.disk ?? "ok")
+  });
+  planes.push({
+    plane: "coverage",
+    state: input.coverage ?? "unknown",
+    action: actionFor("coverage", String(input.coverage ?? "unknown"))
+  });
+  return {
+    status: input.supervisor.status,
+    modules: input.supervisor.modules,
+    planes
+  };
+}
+function actionFor(plane, state) {
+  if (state === "running" || state === "ok" || state === "complete") {
+    return "none";
+  }
+  if (state === "failed" || state === "gap") {
+    return plane === "raw" || plane === "coverage" ? "sl verify all --against <manifest>" : `restart ${plane}`;
+  }
+  if (state === "lagging" || state === "syncing")
+    return "wait for catch-up";
+  if (state === "stale")
+    return "refresh source tip";
+  if (plane === "archive" && state === "idle")
+    return "sl bootstrap --against <manifest>";
+  if (plane === "disk" && state !== "ok")
+    return "free disk and retry";
+  if (plane === "node" && state === "unknown")
+    return "sl observer";
+  return "inspect logs";
+}
+// src/runtime/backup.ts
+var BACKUP_PARTS = [
+  "db",
+  "config",
+  "keys",
+  "handlers",
+  "scope"
+];
+function planBackup(input) {
+  if (!input.encryptedKeys) {
+    return {
+      ok: false,
+      manifest: emptyManifest(input),
+      reason: "keys must be encrypted"
+    };
+  }
+  if (input.fromHeight < 0) {
+    return {
+      ok: false,
+      manifest: emptyManifest(input),
+      reason: "scope from_height must be >= 0"
+    };
+  }
+  return {
+    ok: true,
+    manifest: {
+      created_at: input.now ?? "1970-01-01T00:00:00.000Z",
+      network: input.network,
+      parts: [...BACKUP_PARTS],
+      encrypted: true,
+      scope: {
+        from_height: input.fromHeight,
+        to_height: input.toHeight ?? null
+      }
+    },
+    reason: "dry-run backup bundle"
+  };
+}
+function restoreBackup(plan, opts) {
+  if (!plan.ok)
+    return { ok: false, reason: plan.reason };
+  if (!opts?.apply)
+    return { ok: true, applied: false, deep_green: false };
+  return {
+    ok: true,
+    applied: true,
+    deep_green: opts.deepVerify !== false
+  };
+}
+function emptyManifest(input) {
+  return {
+    created_at: input.now ?? "1970-01-01T00:00:00.000Z",
+    network: input.network,
+    parts: [],
+    encrypted: false,
+    scope: { from_height: input.fromHeight, to_height: input.toHeight ?? null }
+  };
+}
+// src/runtime/upgrade.ts
+var UPGRADE_STEPS = [
+  "pin",
+  "preflight",
+  "backup",
+  "migrate",
+  "health",
+  "verify"
+];
+function planUpgrade(input) {
+  const rollback = "roll back to the pinned previous image; schema migrations are forward-only";
+  if (input.from === input.to) {
+    return {
+      from: input.from,
+      to: input.to,
+      steps: [],
+      ok: false,
+      reason: "from and to are the same image",
+      rollback
+    };
+  }
+  if (input.supported && !input.supported.includes(input.to)) {
+    return {
+      from: input.from,
+      to: input.to,
+      steps: [],
+      ok: false,
+      reason: `image ${input.to} is not in the supported matrix`,
+      rollback
+    };
+  }
+  if (!input.diskOk) {
+    return {
+      from: input.from,
+      to: input.to,
+      steps: ["pin", "preflight"],
+      ok: false,
+      reason: "disk preflight failed",
+      rollback
+    };
+  }
+  if (!input.schemaOk) {
+    return {
+      from: input.from,
+      to: input.to,
+      steps: ["pin", "preflight"],
+      ok: false,
+      reason: "schema preflight failed",
+      rollback
+    };
+  }
+  if (!input.backupDone) {
+    return {
+      from: input.from,
+      to: input.to,
+      steps: ["pin", "preflight", "backup"],
+      ok: false,
+      reason: "backup required before migrate",
+      rollback
+    };
+  }
+  return {
+    from: input.from,
+    to: input.to,
+    steps: [...UPGRADE_STEPS],
+    ok: true,
+    reason: "dry-run upgrade",
+    rollback
+  };
+}
+function applyUpgrade(plan, opts) {
+  if (!plan.ok)
+    return { ok: false, applied: false, reason: plan.reason };
+  if (!opts?.apply)
+    return { ok: true, applied: false, reason: plan.reason };
+  return { ok: true, applied: true, reason: "upgrade applied" };
+}
+// src/runtime/guardrails.ts
+var FLOORS = {
+  appRamMb: 4096,
+  fullRamMb: 98304,
+  appDiskGb: 80,
+  fullDiskGb: 1500,
+  postgresMaxConnections: 50
+};
+function preflightResources(snap, mode) {
+  const errors = [];
+  const ramFloor = mode === "full" ? FLOORS.fullRamMb : FLOORS.appRamMb;
+  const diskFloor = mode === "full" ? FLOORS.fullDiskGb : FLOORS.appDiskGb;
+  if (snap.ramMb < ramFloor) {
+    errors.push(`RAM ${snap.ramMb}MB below ${ramFloor}MB for NODE_MODE=${mode}`);
+  }
+  if (snap.diskGb < diskFloor) {
+    errors.push(`disk ${snap.diskGb}GB below ${diskFloor}GB for NODE_MODE=${mode}`);
+  }
+  if (snap.postgresMaxConnections < FLOORS.postgresMaxConnections) {
+    errors.push(`Postgres max_connections ${snap.postgresMaxConnections} below ${FLOORS.postgresMaxConnections}`);
+  }
+  if (errors.length > 0)
+    return { ok: false, errors };
+  return { ok: true, estimates: { diskGbPer100kBlocks: 1 } };
+}
+// src/runtime/commands.ts
+var MODULE_COMMANDS = {
+  api: ["bun", "run", "packages/api/src/index.ts"],
+  ingest: ["bun", "run", "packages/indexer/src/index.ts"],
+  decoder: ["bun", "run", "packages/indexer/src/decode/service.ts"],
+  subgraph: ["bun", "run", "packages/subgraphs/src/service.ts"],
+  notification: [
+    "bun",
+    "run",
+    "packages/subgraphs/src/subscription-service.ts"
+  ],
+  verification: ["bun", "run", "packages/shared/src/runtime/verify-loop.ts"],
+  publisher: ["bun", "run", "packages/indexer/src/streams-bulk/scheduler.ts"]
+};
+function commandFor(id) {
+  return MODULE_COMMANDS[id];
+}
+export {
+  restoreBackup,
+  reportRuntimeStatus,
+  preflightResources,
+  planUpgrade,
+  planBackup,
+  parseRuntimeConfig,
+  migrateEmbedded,
+  isolateHandler,
+  isModuleId,
+  emptyHealth,
+  createSupervisor,
+  createMemoryModule,
+  createMemoryMigrationRunner,
+  commandFor,
+  applyUpgrade,
+  actionFor,
+  UPGRADE_STEPS,
+  STATUS_PLANES,
+  SECRET_KEYS,
+  REQUIRED_KEYS,
+  PUBLISHER_PROFILE,
+  OPTIONAL_KEYS,
+  NODE_MODES,
+  NETWORKS,
+  MODULE_STATES,
+  MODULE_IDS,
+  MODULE_COMMANDS,
+  MIGRATION_LOCK_KEY,
+  IsolationOomError,
+  IsolationNetworkError,
+  IsolationKillError,
+  ISOLATION_FAULTS,
+  FLOORS,
+  DEFAULT_PROFILE,
+  BACKUP_PARTS
+};
+
+//# debugId=7A7ED27F7FDF478264756E2164756E21
+//# sourceMappingURL=index.js.map