@spfn/core 0.2.0-beta.1 → 0.2.0-beta.11

package/dist/server/index.d.ts

@@ -2,12 +2,42 @@ 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 { 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 '@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
+ */
 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
  */
@@ -117,7 +147,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')
      */
@@ -293,6 +355,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
@@ -545,7 +640,38 @@ 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(router: EventRouterDef<any>, config?: SSEHandlerConfig & {
+        path?: string;
+    }): this;
     /**
      * Enable/disable debug mode
      */
@@ -570,6 +696,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 +739,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' };
  *     }),
  * });
  *

package/dist/server/index.js

@@ -6,9 +6,10 @@ import { Hono } from 'hono';
 import { cors } from 'hono/cors';
 import { registerRoutes } from '@spfn/core/route';
 import { ErrorHandler, RequestLogger } from '@spfn/core/middleware';
+import { streamSSE } from 'hono/streaming';
+import { logger } from '@spfn/core/logger';
 import { initDatabase, getDatabase, closeDatabase } from '@spfn/core/db';
 import { initCache, getCache, closeCache } from '@spfn/core/cache';
-import { logger } from '@spfn/core/logger';
 import { serve } from '@hono/node-server';
 import PgBoss from 'pg-boss';
 import { networkInterfaces } from 'os';
@@ -317,6 +318,8 @@ function loadEnvFiles() {
   const cwd = process.cwd();
   const nodeEnv = process.env.NODE_ENV || "development";
   const envFiles = [
+    ".env.server.local",
+    ".env.server",
     `.env.${nodeEnv}.local`,
     nodeEnv !== "test" ? ".env.local" : null,
     `.env.${nodeEnv}`,
@@ -329,6 +332,90 @@ function loadEnvFiles() {
     }
   }
 }
+var sseLogger = logger.child("@spfn/core:sse");
+function createSSEHandler(router, config2 = {}) {
+  const {
+    pingInterval = 3e4
+    // headers: customHeaders = {},  // Reserved for future use
+  } = config2;
+  return async (c) => {
+    const eventsParam = c.req.query("events");
+    if (!eventsParam) {
+      return c.json({ error: "Missing events parameter" }, 400);
+    }
+    const requestedEvents = eventsParam.split(",").map((e) => e.trim());
+    const validEventNames = router.eventNames;
+    const invalidEvents = requestedEvents.filter((e) => !validEventNames.includes(e));
+    if (invalidEvents.length > 0) {
+      return c.json({
+        error: "Invalid event names",
+        invalidEvents,
+        validEvents: validEventNames
+      }, 400);
+    }
+    sseLogger.debug("SSE connection requested", {
+      events: requestedEvents,
+      clientIp: c.req.header("x-forwarded-for") || c.req.header("x-real-ip")
+    });
+    return streamSSE(c, async (stream) => {
+      const unsubscribes = [];
+      let messageId = 0;
+      for (const eventName of requestedEvents) {
+        const eventDef = router.events[eventName];
+        if (!eventDef) {
+          continue;
+        }
+        const unsubscribe = eventDef.subscribe((payload) => {
+          messageId++;
+          const message = {
+            event: eventName,
+            data: payload
+          };
+          sseLogger.debug("SSE sending event", {
+            event: eventName,
+            messageId
+          });
+          void stream.writeSSE({
+            id: String(messageId),
+            event: eventName,
+            data: JSON.stringify(message)
+          });
+        });
+        unsubscribes.push(unsubscribe);
+      }
+      sseLogger.info("SSE connection established", {
+        events: requestedEvents,
+        subscriptionCount: unsubscribes.length
+      });
+      await stream.writeSSE({
+        event: "connected",
+        data: JSON.stringify({
+          subscribedEvents: requestedEvents,
+          timestamp: Date.now()
+        })
+      });
+      const pingTimer = setInterval(() => {
+        void stream.writeSSE({
+          event: "ping",
+          data: JSON.stringify({ timestamp: Date.now() })
+        });
+      }, pingInterval);
+      const abortSignal = c.req.raw.signal;
+      while (!abortSignal.aborted) {
+        await stream.sleep(pingInterval);
+      }
+      clearInterval(pingTimer);
+      unsubscribes.forEach((fn) => fn());
+      sseLogger.info("SSE connection closed", {
+        events: requestedEvents
+      });
+    }, async (err) => {
+      sseLogger.error("SSE stream error", {
+        error: err.message
+      });
+    });
+  };
+}
 function createHealthCheckHandler(detailed) {
   return async (c) => {
     const response = {
@@ -465,7 +552,8 @@ async function loadCustomApp(appPath, appJsPath, config2) {
   }
   const app = await appFactory();
   if (config2?.routes) {
-    registerRoutes(app, config2.routes, config2.middlewares);
+    const routes = registerRoutes(app, config2.routes, config2.middlewares);
+    logRegisteredRoutes(routes, config2?.debug ?? false);
   }
   return app;
 }
@@ -488,6 +576,7 @@ async function createAutoConfiguredApp(config2) {
   registerHealthCheckEndpoint(app, config2);
   await executeBeforeRoutesHook(app, config2);
   await loadAppRoutes(app, config2);
+  registerSSEEndpoint(app, config2);
   await executeAfterRoutesHook(app, config2);
   if (enableErrorHandler) {
     app.onError(ErrorHandler());
@@ -521,38 +610,69 @@ async function executeBeforeRoutesHook(app, config2) {
 async function loadAppRoutes(app, config2) {
   const debug = isDebugMode(config2);
   if (config2?.routes) {
-    registerRoutes(app, config2.routes, config2.middlewares);
-    if (debug) {
-      serverLogger.info("\u2713 Routes registered");
-    }
+    const routes = registerRoutes(app, config2.routes, config2.middlewares);
+    logRegisteredRoutes(routes, debug);
   } else if (debug) {
     serverLogger.warn("\u26A0\uFE0F  No routes configured. Use defineServerConfig().routes() to register routes.");
   }
 }
+function logRegisteredRoutes(routes, debug) {
+  if (routes.length === 0) {
+    if (debug) {
+      serverLogger.warn("\u26A0\uFE0F  No routes registered");
+    }
+    return;
+  }
+  const sortedRoutes = [...routes].sort((a, b) => a.path.localeCompare(b.path));
+  const maxMethodLen = Math.max(...sortedRoutes.map((r) => r.method.length));
+  const routeLines = sortedRoutes.map(
+    (r) => `  ${r.method.padEnd(maxMethodLen)}  ${r.path}`
+  ).join("\n");
+  serverLogger.info(`\u2713 Routes registered (${routes.length}):
+${routeLines}`);
+}
 async function executeAfterRoutesHook(app, config2) {
   if (config2?.lifecycle?.afterRoutes) {
     await config2.lifecycle.afterRoutes(app);
   }
 }
+function registerSSEEndpoint(app, config2) {
+  if (!config2?.events) {
+    return;
+  }
+  const eventsConfig = config2.eventsConfig ?? {};
+  const path = eventsConfig.path ?? "/events/stream";
+  const debug = isDebugMode(config2);
+  app.get(path, createSSEHandler(config2.events, eventsConfig));
+  if (debug) {
+    const eventNames = config2.events.eventNames;
+    serverLogger.info(`\u2713 SSE endpoint registered at ${path}`, {
+      events: eventNames
+    });
+  }
+}
 function isDebugMode(config2) {
   return config2?.debug ?? process.env.NODE_ENV === "development";
 }
 var jobLogger = logger.child("@spfn/core:job");
 var bossInstance = null;
 var bossConfig = null;
-async function initBoss(config2) {
+async function initBoss(options) {
   if (bossInstance) {
     jobLogger.warn("pg-boss already initialized, returning existing instance");
     return bossInstance;
   }
   jobLogger.info("Initializing pg-boss...");
-  bossConfig = config2;
-  bossInstance = new PgBoss({
-    connectionString: config2.connectionString,
-    schema: config2.schema ?? "spfn_queue",
-    maintenanceIntervalSeconds: config2.maintenanceIntervalSeconds ?? 120,
-    monitorIntervalSeconds: config2.monitorIntervalSeconds
-  });
+  bossConfig = options;
+  const pgBossOptions = {
+    connectionString: options.connectionString,
+    schema: options.schema ?? "spfn_queue",
+    maintenanceIntervalSeconds: options.maintenanceIntervalSeconds ?? 120
+  };
+  if (options.monitorIntervalSeconds !== void 0 && options.monitorIntervalSeconds >= 1) {
+    pgBossOptions.monitorIntervalSeconds = options.monitorIntervalSeconds;
+  }
+  bossInstance = new PgBoss(pgBossOptions);
   bossInstance.on("error", (error) => {
     jobLogger.error("pg-boss error:", error);
   });
@@ -639,7 +759,11 @@ async function registerJobs(router) {
   }
   jobLogger2.info("All jobs registered successfully");
 }
+async function ensureQueue(boss, queueName) {
+  await boss.createQueue(queueName);
+}
 async function registerWorker(boss, job2, queueName) {
+  await ensureQueue(boss, queueName);
   await boss.work(
     queueName,
     { batchSize: 1 },
@@ -686,6 +810,7 @@ async function registerCronSchedule(boss, job2) {
     return;
   }
   jobLogger2.debug(`[Job:${job2.name}] Scheduling cron: ${job2.cronExpression}`);
+  await ensureQueue(boss, job2.name);
   await boss.schedule(
     job2.name,
     job2.cronExpression,
@@ -699,6 +824,7 @@ async function queueRunOnceJob(boss, job2) {
     return;
   }
   jobLogger2.debug(`[Job:${job2.name}] Queuing runOnce job`);
+  await ensureQueue(boss, job2.name);
   await boss.send(
     job2.name,
     {},
@@ -805,9 +931,7 @@ var DEFAULT_MAX_LISTENERS = 15;
 var TIMEOUTS = {
   SERVER_CLOSE: 5e3,
   DATABASE_CLOSE: 5e3,
-  REDIS_CLOSE: 5e3,
-  PRODUCTION_ERROR_SHUTDOWN: 1e4
-};
+  REDIS_CLOSE: 5e3};
 var CONFIG_FILE_PATHS = [
   ".spfn/server/server.config.mjs",
   ".spfn/server/server.config",
@@ -947,6 +1071,20 @@ async function initializeInfrastructure(config2) {
     serverLogger.debug("Registering jobs...");
     await registerJobs(config2.jobs);
   }
+  if (config2.workflows) {
+    const infraConfig2 = getInfrastructureConfig(config2);
+    if (!infraConfig2.database) {
+      throw new Error(
+        "Workflows require database connection. Ensure database is enabled in infrastructure config."
+      );
+    }
+    serverLogger.debug("Initializing workflow engine...");
+    config2.workflows._init(
+      getDatabase(),
+      config2.workflowsConfig
+    );
+    serverLogger.info("Workflow engine initialized");
+  }
 }
 function startHttpServer(app, host, port) {
   serverLogger.debug(`Starting server on ${host}:${port}...`);
@@ -1091,31 +1229,8 @@ function createGracefulShutdown(shutdownServer, config2, shutdownState) {
     }
   };
 }
-function handleProcessError(errorType, shutdown) {
-  const isProduction = env.NODE_ENV === "production";
-  const isDevelopment = env.NODE_ENV === "development";
-  if (isDevelopment || process.env.WATCH_MODE === "true") {
-    serverLogger.info("Exiting immediately for clean restart");
-    process.exit(1);
-  } else if (isProduction) {
-    serverLogger.info(`Attempting graceful shutdown after ${errorType}`);
-    const forceExitTimer = setTimeout(() => {
-      serverLogger.error(`Forced exit after ${TIMEOUTS.PRODUCTION_ERROR_SHUTDOWN}ms - graceful shutdown did not complete`);
-      process.exit(1);
-    }, TIMEOUTS.PRODUCTION_ERROR_SHUTDOWN);
-    shutdown(errorType).then(() => {
-      clearTimeout(forceExitTimer);
-      serverLogger.info("Graceful shutdown completed, exiting");
-      process.exit(0);
-    }).catch((shutdownError) => {
-      clearTimeout(forceExitTimer);
-      serverLogger.error("Graceful shutdown failed", shutdownError);
-      process.exit(1);
-    });
-  } else {
-    serverLogger.info("Exiting immediately");
-    process.exit(1);
-  }
+function handleProcessError(errorType) {
+  serverLogger.warn(`${errorType} occurred - server continues running. Check logs above for details.`);
 }
 function registerProcessHandlers(shutdown) {
   if (processHandlersRegistered) {
@@ -1150,7 +1265,7 @@ function registerProcessHandlers(shutdown) {
     } else {
       serverLogger.error("Uncaught exception", error);
     }
-    handleProcessError("UNCAUGHT_EXCEPTION", shutdown);
+    handleProcessError("UNCAUGHT_EXCEPTION");
   });
   process.on("unhandledRejection", (reason, promise) => {
     if (reason instanceof Error) {
@@ -1168,7 +1283,7 @@ function registerProcessHandlers(shutdown) {
         promise
       });
     }
-    handleProcessError("UNHANDLED_REJECTION", shutdown);
+    handleProcessError("UNHANDLED_REJECTION");
   });
   serverLogger.debug("Process-level shutdown handlers registered successfully");
 }
@@ -1314,6 +1429,41 @@ var ServerConfigBuilder = class {
     }
     return 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(router, config2) {
+    this.config.events = router;
+    if (config2) {
+      this.config.eventsConfig = config2;
+    }
+    return this;
+  }
   /**
    * Enable/disable debug mode
    */
@@ -1356,6 +1506,33 @@ var ServerConfigBuilder = class {
     this.config.infrastructure = infrastructure;
     return 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, config2) {
+    this.config.workflows = router;
+    if (config2) {
+      this.config.workflowsConfig = config2;
+    }
+    return this;
+  }
   /**
    * Configure lifecycle hooks
    * Can be called multiple times - hooks will be executed in registration order