@spfn/core 0.2.0-beta.9 → 0.3.0-beta.2

package/dist/server/index.d.ts

@@ -1,23 +1,24 @@
-import { MiddlewareHandler, Hono } from 'hono';
+export { loadEnv } from '../env/loader.js';
+import { Hono, MiddlewareHandler } from 'hono';
 import { cors } from 'hono/cors';
 import { serve } from '@hono/node-server';
 import { NamedMiddleware, Router } from '@spfn/core/route';
-import { J as JobRouter, B as BossOptions } from '../boss-DI1r4kTS.js';
-import { E as EventRouterDef } from '../router-Di7ENoah.js';
-import { S as SSEHandlerConfig } from '../types-B-e_f2dQ.js';
+import { OnErrorContext, ProxyGuardConfig, RateLimitOptions } from '@spfn/core/middleware';
+import { SafeFetchPolicy } from '@spfn/core/security';
+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, MigrationStatus, MigrationStatusDb } from '@spfn/core/db';
 import '@sinclair/typebox';
 import 'pg-boss';
 
 /**
- * Load environment files for SPFN server
- *
- * Priority (high → low, later files don't override):
- * 1. .env.server.local  - Server-only secrets (gitignored)
- * 2. .env.server        - Server-only defaults
- * 3. .env.{NODE_ENV}.local
- * 4. .env.local         - Local overrides (gitignored)
- * 5. .env.{NODE_ENV}
- * 6. .env               - Defaults
+ * @deprecated Use `loadEnv` from '@spfn/core/env/loader' instead.
+ * This module will be removed in the next major version.
+ */
+/**
+ * @deprecated Use `loadEnv()` from '@spfn/core/env/loader' instead.
  */
 declare function loadEnvFiles(): void;
 
@@ -77,11 +78,86 @@ interface ServerConfig {
          * Error handler (default: true)
          */
         errorHandler?: boolean;
+        /**
+         * Callback invoked when an error occurs (passed to ErrorHandler)
+         *
+         * Called asynchronously without blocking the response.
+         *
+         * @example
+         * ```typescript
+         * import { createErrorSlackNotifier } from '@spfn/notification/server';
+         *
+         * middleware: {
+         *     onError: createErrorSlackNotifier({ minStatusCode: 500 }),
+         * }
+         * ```
+         */
+        onError?: (err: Error, context: OnErrorContext) => Promise<void> | void;
     };
     /**
      * Additional custom middleware
      */
     use?: MiddlewareHandler[];
+    /**
+     * Proxy-guard: verify requests came through the trusted Next.js RPC proxy
+     * (HMAC signature) and/or an allowed browser origin, then tag `clientType`.
+     * Lets the backend reject direct-to-backend calls that bypass the proxy.
+     *
+     * Disabled by default (`mode: 'off'`). Requires the same `SPFN_PROXY_SECRET`
+     * on the proxy and the backend. See PROXY-BACKEND-AUTH-SPEC.md.
+     *
+     * @example
+     * ```typescript
+     * .proxyGuard({ mode: 'strict', allowedOrigins: ['https://app.example.com'] })
+     * ```
+     */
+    proxyGuard?: Omit<ProxyGuardConfig, 'nonceStore'> & {
+        /**
+         * Enable hard replay rejection via a Redis nonce store. Evaluated in BOTH modes
+         * (tag observes replays, strict rejects). Requires a cache (CACHE_URL); without
+         * one, falls back to the timestamp window. Degrades to the window if the store
+         * is briefly unavailable. @default false
+         */
+        nonce?: boolean;
+    };
+    /**
+     * Rate limiting: an optional global default limiter plus named policies.
+     *
+     * `mode: 'on'` applies `default` to every named-middleware route (opt out
+     * with `.skip(['rateLimit'])`); `policies` lets packages tag sensitive routes
+     * via `rateLimitPolicy(name, fallback)` while this app tunes the numbers in
+     * one place. Backed by the shared cache (CACHE_URL); without a cache it fails
+     * open unless `default.failClosed` is set. Disabled by default (`mode: 'off'`).
+     *
+     * @example
+     * ```typescript
+     * .rateLimit({
+     *     mode: 'on',
+     *     default: { limit: 100, windowMs: 60_000 },
+     *     policies: { 'auth-login': { limit: 5, windowMs: 60_000 } },
+     * })
+     * ```
+     */
+    rateLimit?: {
+        /** 'on' applies the default limiter to every route. @default 'off' */
+        mode?: 'off' | 'on';
+        /** Default policy applied to all routes when `mode` is 'on'. */
+        default?: RateLimitOptions;
+        /** Named policies referenced by `rateLimitPolicy(name, fallback)` tags. */
+        policies?: Record<string, RateLimitOptions>;
+    };
+    /**
+     * SSRF policy for outbound requests made via `safeFetch` (`@spfn/core/security`).
+     * Sets the process-wide default used by webhook/callback senders. Private and
+     * reserved IPs are blocked by default; set `allowHosts` to restrict to a known
+     * set of upstreams, or `blockPrivateIps: false` for trusted internal calls.
+     *
+     * @example
+     * ```typescript
+     * .outboundFetch({ allowHosts: ['hooks.slack.com'] })
+     * ```
+     */
+    outboundFetch?: SafeFetchPolicy;
     /**
      * Global middlewares with names for route-level skip control
      * Use defineMiddleware() for type-safe middleware definitions
@@ -180,6 +256,30 @@ interface ServerConfig {
          */
         path?: string;
     };
+    /**
+     * WebSocket router for bidirectional real-time communication
+     *
+     * @example
+     * ```typescript
+     * import { defineWSRouter } from '@spfn/core/event/ws';
+     *
+     * export default defineServerConfig()
+     *   .websockets(wsRouter)       // → WS /ws
+     *   .build();
+     * ```
+     */
+    websockets?: WSRouterDef<any, any>;
+    /**
+     * WebSocket configuration options
+     * Only used if websockets router is provided
+     */
+    websocketsConfig?: WSHandlerConfig & {
+        /**
+         * WebSocket endpoint path
+         * @default '/ws'
+         */
+        path?: string;
+    };
     /**
      * Enable debug mode (default: NODE_ENV === 'development')
      */
@@ -188,6 +288,13 @@ interface ServerConfig {
      * Database configuration
      */
     database?: {
+        /**
+         * Externally owned PostgreSQL Drizzle provider.
+         *
+         * When supplied, SPFN skips DATABASE_URL/postgres.js initialization
+         * and closes the provider during graceful shutdown.
+         */
+        provider?: DatabaseProvider;
         /**
          * Connection pool configuration
          * Overrides environment variables and defaults
@@ -299,6 +406,34 @@ interface ServerConfig {
          */
         headers?: number;
     };
+    /**
+     * Fetch (outbound HTTP) timeout configuration
+     * Controls Node.js undici global dispatcher timeouts for fetch() calls
+     * Applies to all outbound HTTP requests made via fetch() in this process
+     */
+    fetchTimeout?: {
+        /**
+         * TCP connection timeout in milliseconds
+         * Time to establish socket connection to upstream server
+         * @default 10000 (10 seconds)
+         * @env FETCH_CONNECT_TIMEOUT
+         */
+        connect?: number;
+        /**
+         * Response headers timeout in milliseconds
+         * Time to receive complete response headers after request sent
+         * @default 300000 (5 minutes)
+         * @env FETCH_HEADERS_TIMEOUT
+         */
+        headers?: number;
+        /**
+         * Body data timeout in milliseconds
+         * Maximum time between body data chunks from upstream server
+         * @default 300000 (5 minutes)
+         * @env FETCH_BODY_TIMEOUT
+         */
+        body?: number;
+    };
     /**
      * Graceful shutdown configuration
      * Controls server shutdown behavior during SIGTERM/SIGINT signals
@@ -306,9 +441,13 @@ interface ServerConfig {
     shutdown?: {
         /**
          * Graceful shutdown timeout in milliseconds
-         * Maximum time to wait for ongoing requests and resource cleanup
-         * After timeout, forces process termination
-         * @default 30000 (30 seconds)
+         * Maximum time to wait for in-flight operations to drain and resource cleanup
+         * After timeout, forces process.exit() before k8s SIGKILL
+         *
+         * Formula: terminationGracePeriodSeconds - preStopSleep - safetyMargin
+         * Default: 300s - 5s - 15s = 280s
+         *
+         * @default 280000 (280 seconds)
          * @env SHUTDOWN_TIMEOUT
          */
         timeout?: number;
@@ -338,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
@@ -567,6 +727,236 @@ declare function createServer(config?: ServerConfig): Promise<Hono>;
  */
 declare function startServer(config?: ServerConfig): Promise<ServerInstance>;
 
+/**
+ * Shutdown Manager
+ *
+ * Manages graceful shutdown with drain behavior.
+ * All tracked operations must complete before shutdown proceeds.
+ *
+ * Features:
+ * - Hook registry: Multiple modules can register independent cleanup handlers
+ * - Operation tracking: Long-running tasks are awaited during shutdown (drain)
+ * - State management: isShuttingDown() for rejecting new work
+ */
+interface ShutdownHookOptions {
+    /**
+     * Timeout for this hook in milliseconds
+     * If the hook exceeds this time, it is skipped and the next hook runs
+     * @default 10000 (10s)
+     */
+    timeout?: number;
+    /**
+     * Execution order (lower runs first)
+     * @default 100
+     */
+    order?: number;
+}
+declare class ShutdownManager {
+    private state;
+    private hooks;
+    private operations;
+    private operationCounter;
+    /**
+     * Register a shutdown hook
+     *
+     * Hooks run in order during shutdown, after all tracked operations drain.
+     * Each hook has its own timeout — failure does not block subsequent hooks.
+     *
+     * @example
+     * shutdown.onShutdown('ai-service', async () => {
+     *     await aiService.cancelPending();
+     * }, { timeout: 30000, order: 10 });
+     */
+    onShutdown(name: string, handler: () => Promise<void>, options?: ShutdownHookOptions): void;
+    /**
+     * Track a long-running operation
+     *
+     * During shutdown (drain phase), the process waits for ALL tracked
+     * operations to complete before proceeding with cleanup.
+     *
+     * If shutdown has already started, the operation is rejected immediately.
+     *
+     * @returns The operation result (pass-through)
+     *
+     * @example
+     * const result = await shutdown.trackOperation(
+     *     'ai-generate',
+     *     aiService.generate(prompt)
+     * );
+     */
+    trackOperation<T>(name: string, operation: Promise<T>): Promise<T>;
+    /**
+     * Whether the server is shutting down
+     *
+     * Use this to reject new work early (e.g., return 503 in route handlers).
+     */
+    isShuttingDown(): boolean;
+    /**
+     * Number of currently active tracked operations
+     */
+    getActiveOperationCount(): number;
+    /**
+     * Mark shutdown as started immediately
+     *
+     * Call this at the very beginning of the shutdown sequence so that:
+     * - Health check returns 503 right away
+     * - trackOperation() rejects new work
+     * - isShuttingDown() returns true
+     */
+    beginShutdown(): void;
+    /**
+     * Execute the full shutdown sequence
+     *
+     * 1. State → draining (reject new operations)
+     * 2. Wait for all tracked operations to complete (drain)
+     * 3. Run shutdown hooks in order
+     * 4. State → closed
+     *
+     * @param drainTimeout - Max time to wait for operations to drain (ms)
+     */
+    execute(drainTimeout: number): Promise<void>;
+    /**
+     * Wait for all tracked operations to complete, up to drainTimeout
+     */
+    private drain;
+    /**
+     * Execute registered shutdown hooks in order
+     */
+    private executeHooks;
+}
+/**
+ * Get the global ShutdownManager instance
+ *
+ * Available after server starts. Use this to register shutdown hooks
+ * or track long-running operations.
+ *
+ * @example
+ * import { getShutdownManager } from '@spfn/core/server';
+ *
+ * const shutdown = getShutdownManager();
+ *
+ * // Register cleanup
+ * shutdown.onShutdown('my-service', async () => {
+ *     await myService.close();
+ * });
+ *
+ * // Track long operation
+ * await shutdown.trackOperation('ai-task', longRunningPromise);
+ */
+declare function getShutdownManager(): ShutdownManager;
+
+/**
+ * Serverless target for SPFN.
+ *
+ * Produces a listen-free, initialized Hono app for serverless platforms (Vercel,
+ * AWS Lambda, Cloudflare) — wrap the result with a hono platform adapter, e.g.
+ * `handle(app)` from `hono/vercel`.
+ *
+ * Unlike {@link startServer} (which serve()s a long-lived process and is the
+ * always-on / container path), this:
+ *   - initializes the database in-handler (startServer welds DB init to serve()),
+ *   - runs at most once per warm container (memoized),
+ *   - disables the periodic DB health-check (pointless — and a timer leak — on
+ *     frozen invocations),
+ *   - does NOT start the in-process pg-boss worker (it cannot run on a serverless
+ *     platform); enqueue still works, but nothing drains the queue here,
+ *   - does NOT run seed/RBAC provisioning per cold start — that moves to a
+ *     deploy-time step, see {@link provisionInfrastructure}.
+ *
+ * `startServer()` / `spfn start` (the always-on path) is unchanged by this module.
+ */
+
+/**
+ * Build — once per warm container — the initialized, listen-free Hono app for a
+ * serverless platform. Wrap the result with the platform adapter:
+ *
+ * ```ts
+ * import { handle } from 'hono/vercel';
+ * import { createServerlessApp } from '@spfn/core/server';
+ * import serverConfig from '@/server/server.config';
+ *
+ * const handler = async (req: Request) => handle(await createServerlessApp(serverConfig))(req);
+ * export const GET = handler;
+ * export const POST = handler;
+ * ```
+ */
+declare function createServerlessApp(config?: ServerConfig): Promise<Hono>;
+/**
+ * Reset the memoized serverless app. Tests only.
+ */
+declare function resetServerlessApp(): void;
+/**
+ * Deploy-time provisioning — run ONCE per deploy, not per request.
+ *
+ * Initializes the database and runs the config's provisioning lifecycle hooks
+ * (`beforeInfrastructure` / `afterInfrastructure`, e.g. admin seeding + RBAC init).
+ * Intended for a build/deploy step (`spfn provision`), keeping per-cold-start work
+ * out of the serverless handler. On always-on targets this is equally useful: it
+ * avoids re-seeding on every pod restart / replica.
+ *
+ * Does NOT start the HTTP server, jobs worker, or health-check.
+ */
+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
  *
@@ -600,12 +990,47 @@ declare class ServerConfigBuilder {
      * Add named middlewares for route-level skip control
      */
     middlewares(middlewares: ServerConfig['middlewares']): this;
+    /**
+     * Configure proxy-guard (verify trusted-proxy signature + origin → clientType)
+     */
+    proxyGuard(proxyGuard: ServerConfig['proxyGuard']): this;
+    /**
+     * Configure rate limiting: an optional global default limiter plus the named
+     * policies that `rateLimitPolicy(name, fallback)` tags resolve against.
+     *
+     * @example
+     * ```typescript
+     * .rateLimit({
+     *     mode: 'on',
+     *     default: { limit: 100, windowMs: 60_000 },
+     *     policies: { 'auth-login': { limit: 5, windowMs: 60_000 } },
+     * })
+     * ```
+     */
+    rateLimit(rateLimit: ServerConfig['rateLimit']): this;
+    /**
+     * Configure the SSRF policy for outbound `safeFetch` calls (webhooks,
+     * callbacks). Private/reserved IPs are blocked by default.
+     *
+     * @example
+     * ```typescript
+     * .outboundFetch({ allowHosts: ['hooks.slack.com'] })
+     * ```
+     */
+    outboundFetch(outboundFetch: ServerConfig['outboundFetch']): this;
     /**
      * Register define-route based router
      *
-     * Automatically applies:
-     * - Global middlewares from router._globalMiddlewares (via .use())
-     * - Package routers from router._packageRouters (via .packages())
+     * Router-level middleware (`.use()`) and package routers (`.packages()`) travel
+     * with the router itself and are applied by `registerRoutes` when the routes are
+     * mounted — this method only records which router to mount.
+     *
+     * It deliberately does **not** copy `router._globalMiddlewares` into
+     * `config.middlewares`: that copy used to make `registerRoutes` see the same
+     * middleware twice (once from the config list, once from the router it was
+     * handed) and attach both to every route. Middleware that verifies a JWT survives
+     * running twice; middleware that consumes one-shot state — a nonce replay ledger —
+     * rejects its own request the second time round.
      *
      * @example
      * ```typescript
@@ -616,7 +1041,7 @@ declare class ServerConfigBuilder {
      * .use([authMiddleware]);
      *
      * export default defineServerConfig()
-     *   .routes(appRouter)  // middlewares auto-applied
+     *   .routes(appRouter)  // .use() middleware applied once, at registration
      *   .build();
      * ```
      */
@@ -669,8 +1094,40 @@ declare class ServerConfigBuilder {
      * .events(eventRouter, { path: '/sse' })
      * ```
      */
-    events(router: EventRouterDef<any>, config?: SSEHandlerConfig & {
+    events<TRouter extends EventRouterDef<any>>(router: TRouter, config?: Omit<SSEHandlerConfig, 'auth'> & {
+        path?: string;
+        auth?: SSEAuthConfig<TRouter>;
+    }): this;
+    /**
+     * Register WebSocket router for bidirectional real-time communication
+     *
+     * Enables type-safe WebSocket connections with:
+     * - Server→client event push (via defineEvent + emit)
+     * - Client→server message handling (via messages in defineWSRouter)
+     *
+     * @example
+     * ```typescript
+     * // src/server/ws.ts
+     * export const wsRouter = defineWSRouter({
+     *     events: { userUpdated, notification },
+     *     messages: {
+     *         ping: ({ ws }) => ws.send('pong', {}),
+     *     },
+     * });
+     *
+     * // server.config.ts
+     * export default defineServerConfig()
+     *     .websockets(wsRouter)              // → WS /ws
+     *     .websockets(wsRouter, {
+     *         path: '/realtime',             // custom path
+     *         auth: { enabled: true },       // token authentication
+     *     })
+     *     .build();
+     * ```
+     */
+    websockets<TEvents extends Record<string, EventDef<any>>, TMessages extends WSMessageHandlers>(router: WSRouterDef<TEvents, TMessages>, config?: Omit<WSHandlerConfig, 'auth'> & {
         path?: string;
+        auth?: WSAuthConfig<WSRouterDef<TEvents, TMessages>>;
     }): this;
     /**
      * Enable/disable debug mode
@@ -696,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
      *
@@ -756,4 +1225,4 @@ declare class ServerConfigBuilder {
  */
 declare function defineServerConfig(): ServerConfigBuilder;
 
-export { type AppFactory, type ServerConfig, type ServerInstance, createServer, defineServerConfig, loadEnvFiles, startServer };
+export { type AppFactory, type MigrationSnapshot, PendingMigrationsError, type ServerConfig, type ServerInstance, type ShutdownHookOptions, createServer, createServerlessApp, defineServerConfig, getMigrationSnapshot, getShutdownManager, loadEnvFiles, provisionInfrastructure, resetMigrationSnapshot, resetServerlessApp, startServer };