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

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,19 +610,47 @@ 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";
 }
@@ -547,12 +664,15 @@ async function initBoss(options) {
   }
   jobLogger.info("Initializing pg-boss...");
   bossConfig = options;
-  bossInstance = new PgBoss({
+  const pgBossOptions = {
     connectionString: options.connectionString,
     schema: options.schema ?? "spfn_queue",
-    maintenanceIntervalSeconds: options.maintenanceIntervalSeconds ?? 120,
-    monitorIntervalSeconds: options.monitorIntervalSeconds
-  });
+    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,
     {},
@@ -1314,6 +1440,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
    */