@spfn/core 0.2.0-beta.71 → 0.2.0-beta.72

package/dist/server/index.d.ts

@@ -9,7 +9,7 @@ import { c as JobRouter, e as BossOptions } from '../boss-D16fO2oG.js';
 import { b as EventRouterDef, E as EventDef } from '../token-manager-BT5EnUAR.js';
 import { d as SSEHandlerConfig, e as SSEAuthConfig } from '../types-ZQODsBft.js';
 import { W as WSRouterDef, f as WSHandlerConfig, e as WSMessageHandlers, g as WSAuthConfig } from '../types-2AbaW4Ie.js';
-import { DatabaseProvider } from '@spfn/core/db';
+import { DatabaseProvider, MigrationStatus, MigrationStatusDb } from '@spfn/core/db';
 import '@sinclair/typebox';
 import 'pg-boss';
 
@@ -477,6 +477,27 @@ interface ServerConfig {
          */
         detailed?: boolean;
     };
+    /**
+     * Migration boot gate
+     *
+     * Before serving, the server compares the migrations shipped by installed
+     * function packages (and by `src/server/drizzle`) against what the database
+     * records as applied, and refuses to start when any are still pending —
+     * otherwise the mismatch surfaces only at request time, as an opaque 500.
+     *
+     * Skipped when the app initializes no database or ships no migrations.
+     */
+    migrations?: {
+        /**
+         * Start anyway when migrations are pending, logging a warning that lists
+         * them. The environment equivalent is `SPFN_ALLOW_PENDING_MIGRATIONS=true`;
+         * this field wins over it.
+         *
+         * @default false
+         * @env SPFN_ALLOW_PENDING_MIGRATIONS
+         */
+        allowPending?: boolean;
+    };
     /**
      * Infrastructure initialization control
      * Controls automatic initialization of database and Redis
@@ -877,6 +898,65 @@ declare function resetServerlessApp(): void;
  */
 declare function provisionInfrastructure(config?: ServerConfig): Promise<void>;
 
+/**
+ * Migration Boot Gate
+ *
+ * A server that boots with pending migrations passes its health check and then
+ * fails every request that touches a missing column, as an opaque 500. The gate
+ * moves that failure to boot, where it is one line to read and one command to
+ * fix.
+ *
+ * The check runs on the database the server already connected to. When no
+ * database was initialized — an app that uses none — there is nothing to check
+ * and boot proceeds. When the database is configured but unreachable,
+ * `initDatabase()` has already failed before the gate runs, so the gate never
+ * turns a database outage into a migration message.
+ */
+
+type MigrationSnapshot = 
+/** Checked successfully — `status` carries per-target applied/pending counts. */
+{
+    state: 'ok';
+    checkedAt: string;
+    status: MigrationStatus;
+    pending: number;
+}
+/** Nothing to check: no database in use, or no migrations shipped. */
+ | {
+    state: 'skipped';
+    checkedAt: string;
+    reason: string;
+}
+/** Could not check — distinct from "checked and pending". */
+ | {
+    state: 'unavailable';
+    checkedAt: string;
+    reason: string;
+};
+/**
+ * Thrown when the gate refuses a boot. Not an HTTP error — it never reaches a
+ * request.
+ */
+declare class PendingMigrationsError extends Error {
+    readonly targets: string[];
+    constructor(message: string, targets: string[]);
+}
+/**
+ * Forget the cached snapshot — used by tests and after a manual migration run.
+ */
+declare function resetMigrationSnapshot(): void;
+/**
+ * Current migration snapshot, recomputed at most once per TTL.
+ *
+ * The boot gate seeds it, so the first health probe after startup costs nothing.
+ */
+declare function getMigrationSnapshot(options?: {
+    cwd?: string;
+    db?: MigrationStatusDb;
+    force?: boolean;
+    ttlMs?: number;
+}): Promise<MigrationSnapshot>;
+
 /**
  * Server Config Builder
  *
@@ -1073,6 +1153,18 @@ declare class ServerConfigBuilder {
      * Configure infrastructure initialization
      */
     infrastructure(infrastructure: ServerConfig['infrastructure']): this;
+    /**
+     * Configure the migration boot gate
+     *
+     * @example
+     * ```typescript
+     * // A harness that applies migrations itself, after the server is up
+     * export default defineServerConfig()
+     *     .migrations({ allowPending: true })
+     *     .build();
+     * ```
+     */
+    migrations(migrations: ServerConfig['migrations']): this;
     /**
      * Register workflow router for workflow orchestration
      *
@@ -1133,4 +1225,4 @@ declare class ServerConfigBuilder {
  */
 declare function defineServerConfig(): ServerConfigBuilder;
 
-export { type AppFactory, type ServerConfig, type ServerInstance, type ShutdownHookOptions, createServer, createServerlessApp, defineServerConfig, getShutdownManager, loadEnvFiles, provisionInfrastructure, resetServerlessApp, startServer };
+export { type AppFactory, type MigrationSnapshot, PendingMigrationsError, type ServerConfig, type ServerInstance, type ShutdownHookOptions, createServer, createServerlessApp, defineServerConfig, getMigrationSnapshot, getShutdownManager, loadEnvFiles, provisionInfrastructure, resetMigrationSnapshot, resetServerlessApp, startServer };

package/dist/server/index.js

@@ -11,7 +11,7 @@ import { setDefaultSafeFetchPolicy } from '@spfn/core/security';
 import { streamSSE } from 'hono/streaming';
 import { randomBytes, createHash } from 'crypto';
 import { Agent, setGlobalDispatcher } from 'undici';
-import { initDatabase, getDatabase, closeDatabase } from '@spfn/core/db';
+import { initDatabase, getDatabase, hasMigrationTargets, collectMigrationStatus, countPendingMigrations, pendingMigrationTargets, formatPendingMigrations, pendingMigrationsSummary, RUN_MIGRATIONS_HINT, migrationTargets, closeDatabase } from '@spfn/core/db';
 import { initCache, getCache, closeCache } from '@spfn/core/cache';
 import { serve } from '@hono/node-server';
 import PgBoss from 'pg-boss';
@@ -646,8 +646,8 @@ var InMemoryTokenStore = class {
   }
 };
 var CacheTokenStore = class {
-  constructor(cache) {
-    this.cache = cache;
+  constructor(cache2) {
+    this.cache = cache2;
   }
   prefix = "sse:token:";
   async set(token, data) {
@@ -989,6 +989,93 @@ async function closeEventTransport() {
 }
 var serverLogger = logger.child("@spfn/core:server");
 
+// src/server/migration-gate.ts
+var SNAPSHOT_TTL_MS = 3e4;
+var cache = null;
+var PendingMigrationsError = class extends Error {
+  targets;
+  constructor(message, targets) {
+    super(message);
+    this.name = "PendingMigrationsError";
+    this.targets = targets;
+  }
+};
+function resetMigrationSnapshot() {
+  cache = null;
+}
+async function inspect(cwd, db) {
+  const checkedAt = (/* @__PURE__ */ new Date()).toISOString();
+  if (!hasMigrationTargets(cwd)) {
+    return { state: "skipped", checkedAt, reason: "no function package or project migrations found" };
+  }
+  let database = db;
+  if (!database) {
+    try {
+      database = getDatabase();
+    } catch {
+      return { state: "skipped", checkedAt, reason: "no database initialized" };
+    }
+  }
+  try {
+    const status = await collectMigrationStatus(database, cwd);
+    return { state: "ok", checkedAt, status, pending: countPendingMigrations(status) };
+  } catch (error) {
+    return {
+      state: "unavailable",
+      checkedAt,
+      reason: error instanceof Error ? error.message : String(error)
+    };
+  }
+}
+async function getMigrationSnapshot(options = {}) {
+  const cwd = options.cwd ?? process.cwd();
+  const ttl = options.ttlMs ?? SNAPSHOT_TTL_MS;
+  const now = Date.now();
+  if (!options.force && cache && cache.cwd === cwd && now - cache.at < ttl) {
+    return cache.value;
+  }
+  const value = await inspect(cwd, options.db);
+  cache = { at: now, cwd, value };
+  return value;
+}
+function pendingIsAllowed(config) {
+  return config?.migrations?.allowPending ?? env.SPFN_ALLOW_PENDING_MIGRATIONS === true;
+}
+async function runMigrationBootGate(config, cwd = process.cwd()) {
+  const snapshot = await getMigrationSnapshot({ cwd, force: true });
+  if (snapshot.state === "skipped") {
+    serverLogger.debug(`Migration gate skipped: ${snapshot.reason}`);
+    return snapshot;
+  }
+  if (snapshot.state === "unavailable") {
+    serverLogger.warn(
+      `Could not verify migration status: ${snapshot.reason}. Starting anyway \u2014 run \`pnpm spfn db status\` to check.`
+    );
+    return snapshot;
+  }
+  const targets = pendingMigrationTargets(snapshot.status);
+  if (targets.length === 0) {
+    serverLogger.debug("Migration gate passed: database is up to date");
+    return snapshot;
+  }
+  const lines = formatPendingMigrations(targets);
+  const summary = pendingMigrationsSummary(targets);
+  if (pendingIsAllowed(config)) {
+    serverLogger.warn(`Starting with pending migrations \u2014 ${summary}`);
+    lines.forEach((line) => serverLogger.warn(`  ${line}`));
+    serverLogger.warn(`  Requests hitting the missing columns will fail. ${RUN_MIGRATIONS_HINT}`);
+    return snapshot;
+  }
+  serverLogger.error(`Refusing to start: ${summary}`);
+  lines.forEach((line) => serverLogger.error(`  ${line}`));
+  serverLogger.error(`  ${RUN_MIGRATIONS_HINT}`);
+  serverLogger.error("  To start anyway: SPFN_ALLOW_PENDING_MIGRATIONS=true (or `spfn dev --allow-pending-migrations`)");
+  throw new PendingMigrationsError(
+    `${summary}. ${RUN_MIGRATIONS_HINT}, or set SPFN_ALLOW_PENDING_MIGRATIONS=true to start anyway.`,
+    targets.map((target) => target.name)
+  );
+}
+
 // src/server/shutdown-manager.ts
 var DEFAULT_HOOK_TIMEOUT = 1e4;
 var DEFAULT_HOOK_ORDER = 100;
@@ -1203,6 +1290,24 @@ async function withTimeout2(promise, timeout, message) {
 }
 
 // src/server/helpers.ts
+async function readMigrationHealth() {
+  const snapshot = await getMigrationSnapshot();
+  if (snapshot.state !== "ok") {
+    return {
+      status: "unknown",
+      pending: 0,
+      checkedAt: snapshot.checkedAt,
+      targets: [],
+      reason: snapshot.reason
+    };
+  }
+  return {
+    status: snapshot.pending > 0 ? "pending" : "up_to_date",
+    pending: snapshot.pending,
+    checkedAt: snapshot.checkedAt,
+    targets: migrationTargets(snapshot.status)
+  };
+}
 function createHealthCheckHandler(detailed) {
   return async (c) => {
     const shutdownManager = getShutdownManager();
@@ -1256,6 +1361,7 @@ function createHealthCheckHandler(detailed) {
       };
       const hasErrors = dbStatus === "error" || dbStatus === "not_initialized" || redisStatus === "error";
       response.status = hasErrors ? "degraded" : "ok";
+      response.migrations = await readMigrationHealth();
     }
     const statusCode = response.status === "ok" ? 200 : 503;
     return c.json(response, statusCode);
@@ -1436,9 +1542,9 @@ async function applyProxyGuard(app, config) {
   if (proxyGuardConfig?.nonce) {
     try {
       const { getCache: getCache2 } = await import('@spfn/core/cache');
-      const cache = getCache2();
-      if (cache) {
-        nonceStore = createCacheNonceStore(cache);
+      const cache2 = getCache2();
+      if (cache2) {
+        nonceStore = createCacheNonceStore(cache2);
         serverLogger.info("Proxy-guard nonce replay rejection: cache (Redis/Valkey)");
       } else {
         nonceStore = createInMemoryNonceStore();
@@ -1550,9 +1656,9 @@ async function registerSSEEndpoint(app, config) {
     if (!store) {
       try {
         const { getCache: getCache2 } = await import('@spfn/core/cache');
-        const cache = getCache2();
-        if (cache) {
-          store = new CacheTokenStore(cache);
+        const cache2 = getCache2();
+        if (cache2) {
+          store = new CacheTokenStore(cache2);
           if (debug) {
             serverLogger.info("SSE token store: cache (Redis/Valkey)");
           }
@@ -2248,6 +2354,7 @@ async function startServer(config) {
   };
   try {
     await initializeInfrastructure(finalConfig);
+    await runMigrationBootGate(finalConfig);
     const app = await createServer(finalConfig);
     const server = startHttpServer(app, host, port);
     let wsCleanup;
@@ -2400,9 +2507,9 @@ async function initializeWebSocket(server, app, config) {
     if (!store) {
       try {
         const { getCache: getCache2 } = await import('@spfn/core/cache');
-        const cache = getCache2();
-        if (cache) {
-          store = new CacheTokenStore(cache);
+        const cache2 = getCache2();
+        if (cache2) {
+          store = new CacheTokenStore(cache2);
           if (debug) serverLogger.info("WS token store: cache (Redis/Valkey)");
         }
       } catch {
@@ -2988,6 +3095,21 @@ var ServerConfigBuilder = class {
     this.config.infrastructure = infrastructure;
     return this;
   }
+  /**
+   * Configure the migration boot gate
+   *
+   * @example
+   * ```typescript
+   * // A harness that applies migrations itself, after the server is up
+   * export default defineServerConfig()
+   *     .migrations({ allowPending: true })
+   *     .build();
+   * ```
+   */
+  migrations(migrations) {
+    this.config.migrations = migrations;
+    return this;
+  }
   /**
    * Register workflow router for workflow orchestration
    *
@@ -3062,6 +3184,6 @@ function defineServerConfig() {
   return new ServerConfigBuilder();
 }
 
-export { createServer, createServerlessApp, defineServerConfig, getShutdownManager, loadEnv, loadEnvFiles, provisionInfrastructure, resetServerlessApp, startServer };
+export { PendingMigrationsError, createServer, createServerlessApp, defineServerConfig, getMigrationSnapshot, getShutdownManager, loadEnv, loadEnvFiles, provisionInfrastructure, resetMigrationSnapshot, resetServerlessApp, startServer };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map