@spfn/core 0.2.0-beta.2 → 0.2.0-beta.21

package/dist/server/index.d.ts

@@ -1,13 +1,41 @@
+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 BossConfig } from '../boss-D-fGtVgM.js';
+import { OnErrorContext } from '@spfn/core/middleware';
+import { J as JobRouter, B as BossOptions } from '../boss-DI1r4kTS.js';
+import { E as EventRouterDef } from '../router-Di7ENoah.js';
+import { S as SSEHandlerConfig, a as SSEAuthConfig } from '../types-DHQMQlcb.js';
 import '@sinclair/typebox';
 import 'pg-boss';
 
+/**
+ * @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
  */
@@ -47,6 +75,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
@@ -117,7 +160,39 @@ interface ServerConfig {
      * pg-boss configuration options
      * Only used if jobs router is provided
      */
-    jobsConfig?: Omit<BossConfig, 'connectionString'>;
+    jobsConfig?: Omit<BossOptions, 'connectionString'>;
+    /**
+     * Event router for SSE (Server-Sent Events) subscription
+     * Enables real-time event streaming to frontend clients
+     *
+     * @example
+     * ```typescript
+     * import { defineEvent, defineEventRouter } from '@spfn/core/event';
+     *
+     * const userCreated = defineEvent('user.created', Type.Object({
+     *   userId: Type.String(),
+     * }));
+     *
+     * const eventRouter = defineEventRouter({ userCreated });
+     *
+     * export default defineServerConfig()
+     *   .routes(appRouter)
+     *   .events(eventRouter)  // → GET /events/stream
+     *   .build();
+     * ```
+     */
+    events?: EventRouterDef<any>;
+    /**
+     * SSE configuration options
+     * Only used if events router is provided
+     */
+    eventsConfig?: SSEHandlerConfig & {
+        /**
+         * SSE endpoint path
+         * @default '/events/stream'
+         */
+        path?: string;
+    };
     /**
      * Enable debug mode (default: NODE_ENV === 'development')
      */
@@ -237,6 +312,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
@@ -244,9 +347,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;
@@ -293,6 +400,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
@@ -472,6 +612,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
  *
@@ -545,7 +803,39 @@ declare class ServerConfigBuilder {
      *   .build();
      * ```
      */
-    jobs(router: JobRouter<any>, config?: Omit<BossConfig, 'connectionString'>): this;
+    jobs(router: JobRouter<any>, config?: Omit<BossOptions, 'connectionString'>): this;
+    /**
+     * Register event router for SSE (Server-Sent Events)
+     *
+     * Enables real-time event streaming to frontend clients.
+     * Events defined with defineEvent() can be subscribed by:
+     * - Backend: .subscribe() for internal handlers
+     * - Jobs: .on(event) for background processing
+     * - Frontend: SSE stream for real-time updates
+     *
+     * @example
+     * ```typescript
+     * import { defineEvent, defineEventRouter } from '@spfn/core/event';
+     *
+     * const userCreated = defineEvent('user.created', Type.Object({
+     *   userId: Type.String(),
+     * }));
+     *
+     * const eventRouter = defineEventRouter({ userCreated });
+     *
+     * export default defineServerConfig()
+     *   .routes(appRouter)
+     *   .events(eventRouter)  // → GET /events/stream
+     *   .build();
+     *
+     * // Custom path
+     * .events(eventRouter, { path: '/sse' })
+     * ```
+     */
+    events<TRouter extends EventRouterDef<any>>(router: TRouter, config?: Omit<SSEHandlerConfig, 'auth'> & {
+        path?: string;
+        auth?: SSEAuthConfig<TRouter>;
+    }): this;
     /**
      * Enable/disable debug mode
      */
@@ -570,6 +860,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
@@ -592,10 +903,10 @@ declare class ServerConfigBuilder {
  *
  * const appRouter = defineRouter({
  *   getUser: route.get('/users/:id')
- *     .input(Type.Object({ id: Type.String() }))
+ *     .input({ params: Type.Object({ id: Type.String() }) })
  *     .handler(async (c) => {
- *       const { id } = await c.data();
- *       return c.success({ id, name: 'John' });
+ *       const { params } = await c.data();
+ *       return { id: params.id, name: 'John' };
  *     }),
  * });
  *
@@ -609,4 +920,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 };