@spfn/core 0.2.0-beta.5 → 0.2.0-beta.51

package/dist/server/index.d.ts

@@ -1,26 +1,42 @@
+export { loadEnv } from '../env/loader.js';
 import { MiddlewareHandler, Hono } 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-BO8ty33K.js';
-import { E as EventRouterDef } from '../router-Di7ENoah.js';
-import { S as SSEHandlerConfig } from '../types-B-e_f2dQ.js';
+import { OnErrorContext } from '@spfn/core/middleware';
+import { J as JobRouter, B as BossOptions } from '../boss-Cxqc-Oiw.js';
+import { E as EventRouterDef } from '../token-manager-CyG7la3p.js';
+import { S as SSEHandlerConfig, a as SSEAuthConfig } from '../types-C1jMLGwK.js';
+import { W as WSRouterDef, a as WSHandlerConfig, b as WSMessageHandlers, c as WSAuthConfig } from '../types-Cfj--lfr.js';
 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;
 
+/**
+ * Workflow router interface for @spfn/core integration
+ *
+ * This is a minimal interface that avoids circular dependency with @spfn/workflow.
+ * The actual WorkflowRouter from @spfn/workflow implements this interface.
+ */
+interface WorkflowRouterLike {
+    /**
+     * Initialize the workflow engine
+     * Called by server during infrastructure initialization
+     *
+     * @internal
+     */
+    _init: (db: any, options?: {
+        largeOutputThreshold?: number;
+    }) => void;
+}
 /**
  * CORS configuration options - inferred from hono/cors
  */
@@ -60,6 +76,21 @@ 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
@@ -163,6 +194,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')
      */
@@ -282,6 +337,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
@@ -289,9 +372,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 +425,39 @@ interface ServerConfig {
          */
         redis?: boolean;
     };
+    /**
+     * Workflow router for workflow orchestration
+     *
+     * Automatically initializes the workflow engine after database is ready.
+     * Workflows are defined using @spfn/workflow package.
+     *
+     * @example
+     * ```typescript
+     * import { defineWorkflowRouter } from '@spfn/workflow';
+     *
+     * const workflowRouter = defineWorkflowRouter([
+     *     provisionTenant,
+     *     deprovisionTenant,
+     * ]);
+     *
+     * export default defineServerConfig()
+     *     .workflows(workflowRouter)
+     *     .build();
+     * ```
+     */
+    workflows?: WorkflowRouterLike;
+    /**
+     * Workflow engine configuration
+     * Only used if workflows router is provided
+     */
+    workflowsConfig?: {
+        /**
+         * Large output threshold in bytes
+         * Outputs larger than this will be stored in external storage
+         * @default 1024 * 1024 (1MB)
+         */
+        largeOutputThreshold?: number;
+    };
     /**
      * Server lifecycle hooks for custom infrastructure setup and management
      * Allows initialization of custom services and resources at different stages
@@ -517,6 +637,124 @@ 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;
+
 /**
  * Server Config Builder
  *
@@ -619,8 +857,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, any>, TMessages extends WSMessageHandlers, TRouter extends WSRouterDef<TEvents, TMessages>>(router: TRouter, config?: Omit<WSHandlerConfig, 'auth'> & {
         path?: string;
+        auth?: WSAuthConfig<TRouter>;
     }): this;
     /**
      * Enable/disable debug mode
@@ -646,6 +916,27 @@ declare class ServerConfigBuilder {
      * Configure infrastructure initialization
      */
     infrastructure(infrastructure: ServerConfig['infrastructure']): this;
+    /**
+     * Register workflow router for workflow orchestration
+     *
+     * Automatically initializes the workflow engine after database is ready.
+     *
+     * @example
+     * ```typescript
+     * import { defineWorkflowRouter } from '@spfn/workflow';
+     *
+     * const workflowRouter = defineWorkflowRouter([
+     *     provisionTenant,
+     *     deprovisionTenant,
+     * ]);
+     *
+     * export default defineServerConfig()
+     *     .routes(appRouter)
+     *     .workflows(workflowRouter)
+     *     .build();
+     * ```
+     */
+    workflows(router: ServerConfig['workflows'], config?: ServerConfig['workflowsConfig']): this;
     /**
      * Configure lifecycle hooks
      * Can be called multiple times - hooks will be executed in registration order
@@ -685,4 +976,4 @@ declare class ServerConfigBuilder {
  */
 declare function defineServerConfig(): ServerConfigBuilder;
 
-export { type AppFactory, type ServerConfig, type ServerInstance, createServer, defineServerConfig, loadEnvFiles, startServer };
+export { type AppFactory, type ServerConfig, type ServerInstance, type ShutdownHookOptions, createServer, defineServerConfig, getShutdownManager, loadEnvFiles, startServer };