@secondlayer/shared 7.9.0 → 7.11.0

package/dist/src/runtime/index.d.ts

@@ -0,0 +1,256 @@
+/**
+* Lifecycle modules — each runtime plane exposes start/stop/health so a
+* supervisor can restart one without taking the others down.
+*/
+declare const MODULE_IDS: readonly ["api", "ingest", "decoder", "subgraph", "notification", "verification", "publisher"];
+type ModuleId = (typeof MODULE_IDS)[number];
+declare const MODULE_STATES: readonly ["stopped", "starting", "running", "degraded", "failed"];
+type ModuleState = (typeof MODULE_STATES)[number];
+type ModuleHealth = {
+	id: ModuleId
+	state: ModuleState
+	detail: string | null
+	restarts: number
+};
+type RuntimeModule = {
+	id: ModuleId
+	start: () => Promise<void>
+	stop: () => Promise<void>
+	health: () => ModuleHealth
+};
+declare const DEFAULT_PROFILE: readonly ModuleId[];
+declare const PUBLISHER_PROFILE: readonly ModuleId[];
+declare function isModuleId(value: string): value is ModuleId;
+declare function emptyHealth(id: ModuleId): ModuleHealth;
+/** In-memory module used by restart/fault tests. */
+declare function createMemoryModule(id: ModuleId, opts?: {
+	failStart?: boolean
+	loop?: boolean
+	onStart?: () => void
+	onStop?: () => void
+}): RuntimeModule & {
+	setState: (state: ModuleState, detail?: string) => void
+};
+type SupervisorHealth = {
+	status: "healthy" | "degraded" | "failed"
+	modules: ModuleHealth[]
+};
+type Supervisor = {
+	start: (ids?: readonly ModuleId[]) => Promise<void>
+	stop: (id?: ModuleId) => Promise<void>
+	restart: (id: ModuleId) => Promise<void>
+	health: () => SupervisorHealth
+};
+declare function createSupervisor(modules: readonly RuntimeModule[]): Supervisor;
+/**
+* Handler isolation — untrusted subgraph handlers run behind a timeout,
+* optional network deny, and cannot take down the host process.
+*/
+declare const ISOLATION_FAULTS: readonly ["timeout", "throw", "oom", "kill", "network"];
+type IsolationFault = (typeof ISOLATION_FAULTS)[number];
+type IsolationLimits = {
+	timeoutMs: number
+	memoryMb?: number
+	allowNetwork?: boolean
+};
+type IsolationResult = {
+	ok: true
+	hostAlive: true
+} | {
+	ok: false
+	fault: IsolationFault
+	hostAlive: true
+	detail: string
+};
+declare class IsolationNetworkError extends Error {
+	readonly name = "IsolationNetworkError";
+}
+declare class IsolationKillError extends Error {
+	readonly name = "IsolationKillError";
+}
+declare class IsolationOomError extends Error {
+	readonly name = "IsolationOomError";
+}
+declare function isolateHandler(run: (ctx: {
+	signal: AbortSignal
+	fetch: (url: string) => Promise<unknown>
+}) => Promise<void>, limits: IsolationLimits): Promise<IsolationResult>;
+/**
+* Embedded migration — advisory-locked before listeners/workers start.
+* Concurrent boots serialize. A failed pass releases the lock and refuses
+* to start the rest of the runtime.
+*/
+declare const MIGRATION_LOCK_KEY = 1397509447;
+type EmbeddedMigration = {
+	applied: string[]
+	ok: boolean
+	error: string | null
+};
+type MigrationRunner = {
+	acquire: (key: number) => Promise<boolean>
+	release: (key: number) => Promise<void>
+	apply: () => Promise<string[]>
+};
+declare function migrateEmbedded(runner: MigrationRunner): Promise<EmbeddedMigration>;
+/** In-memory lock used by concurrent-startup tests. */
+declare function createMemoryMigrationRunner(opts?: {
+	fail?: boolean
+	delayMs?: number
+	sleep?: (ms: number) => Promise<void>
+}): MigrationRunner & {
+	holders: number
+	appliedCount: number
+};
+/**
+* Minimal runtime config — six or fewer required non-secret values.
+* Unknown or contradictory values fail before ingest starts.
+*/
+declare const NODE_MODES: readonly ["external", "stacks", "full"];
+type NodeMode = (typeof NODE_MODES)[number];
+declare const NETWORKS: readonly ["mainnet", "testnet", "devnet"];
+type RuntimeNetwork = (typeof NETWORKS)[number];
+/** Required non-secret keys. Secrets (tokens, signing keys) come from `sl init`. */
+declare const REQUIRED_KEYS: readonly ["NETWORK", "DATABASE_URL", "NODE_MODE", "DATA_DIR", "API_PORT", "INDEXER_PORT"];
+type RequiredConfigKey = (typeof REQUIRED_KEYS)[number];
+declare const OPTIONAL_KEYS: readonly ["STACKS_NODE_RPC_URL", "LISTEN_HOST", "LOG_LEVEL", "INSTANCE_MODE"];
+declare const SECRET_KEYS: readonly ["INSTANCE_TOKEN", "API_KEY", "SECONDLAYER_SECRETS_KEY", "STREAMS_SIGNING_PRIVATE_KEY", "SECONDLAYER_WEBHOOK_SIGNING_PRIVATE_KEY", "POSTGRES_PASSWORD", "BITCOIN_RPC_PASSWORD"];
+type RuntimeConfig = {
+	NETWORK: RuntimeNetwork
+	DATABASE_URL: string
+	NODE_MODE: NodeMode
+	DATA_DIR: string
+	API_PORT: number
+	INDEXER_PORT: number
+	STACKS_NODE_RPC_URL: string | null
+	LISTEN_HOST: string
+	LOG_LEVEL: string
+};
+type ConfigResult = {
+	ok: true
+	config: RuntimeConfig
+} | {
+	ok: false
+	errors: string[]
+};
+declare function parseRuntimeConfig(env: Record<string, string | undefined>): ConfigResult;
+declare const COVERAGE_STATES: readonly ["complete", "syncing", "lagging", "gap", "stale", "failed", "unverified_import", "unanchored", "source_unavailable", "out_of_scope", "disabled"];
+type CoverageState = (typeof COVERAGE_STATES)[number];
+declare const STATUS_PLANES: readonly ["node", "raw", "decoder", "subgraph", "queue", "archive", "disk", "coverage"];
+type StatusPlane = (typeof STATUS_PLANES)[number];
+type PlaneStatus = {
+	plane: StatusPlane
+	state: string
+	action: string
+};
+type RuntimeStatusReport = {
+	status: SupervisorHealth["status"]
+	modules: ModuleHealth[]
+	planes: PlaneStatus[]
+};
+declare function reportRuntimeStatus(input: {
+	supervisor: SupervisorHealth
+	node?: string
+	archive?: string
+	disk?: string
+	coverage?: CoverageState | string
+}): RuntimeStatusReport;
+declare function actionFor(plane: StatusPlane, state: string): string;
+/**
+* Backup bundle — consistent DB, pinned config, encrypted keys, handler
+* manifests, and scope. Restore onto a wiped host must deep-verify green.
+*/
+declare const BACKUP_PARTS: readonly ["db", "config", "keys", "handlers", "scope"];
+type BackupPart = (typeof BACKUP_PARTS)[number];
+type BackupManifest = {
+	created_at: string
+	network: string
+	parts: BackupPart[]
+	encrypted: boolean
+	scope: {
+		from_height: number
+		to_height: number | null
+	}
+};
+type BackupPlan = {
+	ok: boolean
+	manifest: BackupManifest
+	reason: string
+};
+declare function planBackup(input: {
+	network: string
+	encryptedKeys: boolean
+	fromHeight: number
+	toHeight?: number | null
+	now?: string
+}): BackupPlan;
+type RestoreResult = {
+	ok: true
+	applied: boolean
+	deep_green: boolean
+} | {
+	ok: false
+	reason: string
+};
+declare function restoreBackup(plan: BackupPlan, opts?: {
+	apply?: boolean
+	deepVerify?: boolean
+}): RestoreResult;
+/**
+* Upgrade contract — pin image, preflight schema/disk, backup first,
+* migrate, health/verify, document rollback limits.
+*/
+declare const UPGRADE_STEPS: readonly ["pin", "preflight", "backup", "migrate", "health", "verify"];
+type UpgradeStep = (typeof UPGRADE_STEPS)[number];
+type UpgradePlan = {
+	from: string
+	to: string
+	steps: UpgradeStep[]
+	ok: boolean
+	reason: string
+	rollback: string
+};
+declare function planUpgrade(input: {
+	from: string
+	to: string
+	diskOk: boolean
+	schemaOk: boolean
+	backupDone: boolean
+	supported?: readonly string[]
+}): UpgradePlan;
+declare function applyUpgrade(plan: UpgradePlan, opts?: {
+	apply?: boolean
+}): {
+	ok: boolean
+	applied: boolean
+	reason: string
+};
+/**
+* Resource guardrails — preflight RAM/disk/Postgres and estimate growth.
+* Constrained fixtures fail early.
+*/
+type ResourceSnapshot = {
+	ramMb: number
+	diskGb: number
+	postgresMaxConnections: number
+	postgresSharedBuffersMb?: number
+};
+type GuardrailResult = {
+	ok: true
+	estimates: {
+		diskGbPer100kBlocks: number
+	}
+} | {
+	ok: false
+	errors: string[]
+};
+declare const FLOORS: {
+	readonly appRamMb: 4096
+	readonly fullRamMb: 98304
+	readonly appDiskGb: 80
+	readonly fullDiskGb: 1500
+	readonly postgresMaxConnections: 50
+};
+declare function preflightResources(snap: ResourceSnapshot, mode: "external" | "stacks" | "full"): GuardrailResult;
+declare const MODULE_COMMANDS: Record<ModuleId, readonly string[]>;
+declare function commandFor(id: ModuleId): readonly string[];
+export { restoreBackup, reportRuntimeStatus, preflightResources, planUpgrade, planBackup, parseRuntimeConfig, migrateEmbedded, isolateHandler, isModuleId, emptyHealth, createSupervisor, createMemoryModule, createMemoryMigrationRunner, commandFor, applyUpgrade, actionFor, UpgradeStep, UpgradePlan, UPGRADE_STEPS, SupervisorHealth, Supervisor, StatusPlane, STATUS_PLANES, SECRET_KEYS, RuntimeStatusReport, RuntimeNetwork, RuntimeModule, RuntimeConfig, RestoreResult, ResourceSnapshot, RequiredConfigKey, REQUIRED_KEYS, PlaneStatus, PUBLISHER_PROFILE, OPTIONAL_KEYS, NodeMode, NODE_MODES, NETWORKS, ModuleState, ModuleId, ModuleHealth, MigrationRunner, MODULE_STATES, MODULE_IDS, MODULE_COMMANDS, MIGRATION_LOCK_KEY, IsolationResult, IsolationOomError, IsolationNetworkError, IsolationLimits, IsolationKillError, IsolationFault, ISOLATION_FAULTS, GuardrailResult, FLOORS, EmbeddedMigration, DEFAULT_PROFILE, ConfigResult, BackupPlan, BackupPart, BackupManifest, BACKUP_PARTS };