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

package/dist/server/index.js

@@ -1,14 +1,17 @@
 import { env } from '@spfn/core/config';
-import { config } from 'dotenv';
-import { existsSync } from 'fs';
+import { existsSync, readFileSync } from 'fs';
 import { resolve, join } from 'path';
+import { parse } from 'dotenv';
+import { logger } from '@spfn/core/logger';
 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 { randomBytes } from 'crypto';
+import { Agent, setGlobalDispatcher } from 'undici';
 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';
@@ -313,24 +316,529 @@ var init_formatters = __esm({
     };
   }
 });
+var envLogger = logger.child("@spfn/core:env-loader");
+function getEnvFiles(nodeEnv, server) {
+  const files = [
+    ".env",
+    `.env.${nodeEnv}`
+  ];
+  if (nodeEnv !== "test") {
+    files.push(".env.local");
+  }
+  files.push(`.env.${nodeEnv}.local`);
+  if (server) {
+    files.push(".env.server");
+    files.push(".env.server.local");
+  }
+  return files;
+}
+function parseEnvFile(filePath) {
+  if (!existsSync(filePath)) {
+    return null;
+  }
+  return parse(readFileSync(filePath, "utf-8"));
+}
+function loadEnv(options = {}) {
+  const {
+    cwd = process.cwd(),
+    nodeEnv = process.env.NODE_ENV || "local",
+    server = true,
+    debug = false,
+    override = false
+  } = options;
+  const envFiles = getEnvFiles(nodeEnv, server);
+  const loadedFiles = [];
+  const existingKeys = new Set(Object.keys(process.env));
+  const merged = {};
+  for (const fileName of envFiles) {
+    const filePath = resolve(cwd, fileName);
+    const parsed = parseEnvFile(filePath);
+    if (parsed === null) {
+      continue;
+    }
+    loadedFiles.push(fileName);
+    Object.assign(merged, parsed);
+  }
+  const loadedKeys = [];
+  for (const [key, value] of Object.entries(merged)) {
+    if (!override && existingKeys.has(key)) {
+      continue;
+    }
+    process.env[key] = value;
+    loadedKeys.push(key);
+  }
+  if (debug && loadedFiles.length > 0) {
+    envLogger.debug(`Loaded env files: ${loadedFiles.join(", ")}`);
+    envLogger.debug(`Loaded ${loadedKeys.length} environment variables`);
+  }
+  return { loadedFiles, loadedKeys };
+}
+
+// src/server/dotenv-loader.ts
+var warned = false;
 function loadEnvFiles() {
-  const cwd = process.cwd();
-  const nodeEnv = process.env.NODE_ENV || "development";
-  const envFiles = [
-    `.env.${nodeEnv}.local`,
-    nodeEnv !== "test" ? ".env.local" : null,
-    `.env.${nodeEnv}`,
-    ".env"
-  ].filter((file) => file !== null);
-  for (const file of envFiles) {
-    const filePath = resolve(cwd, file);
-    if (existsSync(filePath)) {
-      config({ path: filePath });
+  if (!warned) {
+    warned = true;
+    console.warn(
+      '[SPFN] loadEnvFiles() is deprecated. Use loadEnv() from "@spfn/core/env/loader" instead.'
+    );
+  }
+  loadEnv();
+}
+var sseLogger = logger.child("@spfn/core:sse");
+function createSSEHandler(router, config = {}, tokenManager) {
+  const {
+    pingInterval = 3e4,
+    auth: authConfig
+  } = config;
+  return async (c) => {
+    const subject = await authenticateToken(c, tokenManager);
+    if (subject === false) {
+      return c.json({ error: "Missing token parameter" }, 401);
+    }
+    if (subject === null) {
+      return c.json({ error: "Invalid or expired token" }, 401);
+    }
+    if (subject) {
+      c.set("sseSubject", subject);
+    }
+    const requestedEvents = parseRequestedEvents(c);
+    if (!requestedEvents) {
+      return c.json({ error: "Missing events parameter" }, 400);
+    }
+    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);
+    }
+    const allowedEvents = await authorizeEvents(subject, requestedEvents, authConfig);
+    if (allowedEvents === null) {
+      return c.json({ error: "Not authorized for any requested events" }, 403);
+    }
+    sseLogger.debug("SSE connection requested", {
+      events: allowedEvents,
+      subject: subject || void 0,
+      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 allowedEvents) {
+        const eventDef = router.events[eventName];
+        if (!eventDef) {
+          continue;
+        }
+        const unsubscribe = eventDef.subscribe((payload) => {
+          if (subject && authConfig?.filter?.[eventName]) {
+            if (!authConfig.filter[eventName](subject, payload)) {
+              return;
+            }
+          }
+          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: allowedEvents,
+        subscriptionCount: unsubscribes.length
+      });
+      await stream.writeSSE({
+        event: "connected",
+        data: JSON.stringify({
+          subscribedEvents: allowedEvents,
+          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: allowedEvents
+      });
+    }, async (err) => {
+      sseLogger.error("SSE stream error", {
+        error: err.message
+      });
+    });
+  };
+}
+async function authenticateToken(c, tokenManager) {
+  if (!tokenManager) {
+    return void 0;
+  }
+  const token = c.req.query("token");
+  if (!token) {
+    return false;
+  }
+  return await tokenManager.verify(token);
+}
+function parseRequestedEvents(c) {
+  const eventsParam = c.req.query("events");
+  if (!eventsParam) {
+    return null;
+  }
+  return eventsParam.split(",").map((e) => e.trim());
+}
+async function authorizeEvents(subject, requestedEvents, authConfig) {
+  if (!subject || !authConfig?.authorize) {
+    return requestedEvents;
+  }
+  const allowed = await authConfig.authorize(subject, requestedEvents);
+  if (allowed.length === 0) {
+    return null;
+  }
+  return allowed;
+}
+var InMemoryTokenStore = class {
+  tokens = /* @__PURE__ */ new Map();
+  async set(token, data) {
+    this.tokens.set(token, data);
+  }
+  async consume(token) {
+    const data = this.tokens.get(token);
+    if (!data) {
+      return null;
+    }
+    this.tokens.delete(token);
+    return data;
+  }
+  async cleanup() {
+    const now = Date.now();
+    for (const [token, data] of this.tokens) {
+      if (data.expiresAt <= now) {
+        this.tokens.delete(token);
+      }
+    }
+  }
+};
+var CacheTokenStore = class {
+  constructor(cache) {
+    this.cache = cache;
+  }
+  prefix = "sse:token:";
+  async set(token, data) {
+    const ttlSeconds = Math.max(1, Math.ceil((data.expiresAt - Date.now()) / 1e3));
+    await this.cache.set(
+      this.prefix + token,
+      JSON.stringify(data),
+      "EX",
+      ttlSeconds
+    );
+  }
+  async consume(token) {
+    const key = this.prefix + token;
+    let raw = null;
+    if (this.cache.getdel) {
+      raw = await this.cache.getdel(key);
+    } else {
+      raw = await this.cache.get(key);
+      if (raw) {
+        await this.cache.del(key);
+      }
+    }
+    if (!raw) {
+      return null;
+    }
+    return JSON.parse(raw);
+  }
+  async cleanup() {
+  }
+};
+var SSETokenManager = class {
+  store;
+  ttl;
+  cleanupTimer = null;
+  constructor(config) {
+    this.ttl = config?.ttl ?? 3e4;
+    this.store = config?.store ?? new InMemoryTokenStore();
+    const cleanupInterval = config?.cleanupInterval ?? 6e4;
+    this.cleanupTimer = setInterval(() => void this.store.cleanup(), cleanupInterval);
+    this.cleanupTimer.unref();
+  }
+  /**
+   * Issue a new one-time-use token for the given subject
+   */
+  async issue(subject) {
+    const token = randomBytes(32).toString("hex");
+    await this.store.set(token, {
+      token,
+      subject,
+      expiresAt: Date.now() + this.ttl
+    });
+    return token;
+  }
+  /**
+   * Verify and consume a token
+   * @returns subject string if valid, null if invalid/expired/already consumed
+   */
+  async verify(token) {
+    const data = await this.store.consume(token);
+    if (!data || data.expiresAt <= Date.now()) {
+      return null;
+    }
+    return data.subject;
+  }
+  /**
+   * Cleanup timer and resources
+   */
+  destroy() {
+    if (this.cleanupTimer) {
+      clearInterval(this.cleanupTimer);
+      this.cleanupTimer = null;
+    }
+  }
+};
+var serverLogger = logger.child("@spfn/core:server");
+
+// src/server/shutdown-manager.ts
+var DEFAULT_HOOK_TIMEOUT = 1e4;
+var DEFAULT_HOOK_ORDER = 100;
+var DRAIN_POLL_INTERVAL = 500;
+var ShutdownManager = class {
+  state = "running";
+  hooks = [];
+  operations = /* @__PURE__ */ new Map();
+  operationCounter = 0;
+  /**
+   * 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, handler, options) {
+    this.hooks.push({
+      name,
+      handler,
+      timeout: options?.timeout ?? DEFAULT_HOOK_TIMEOUT,
+      order: options?.order ?? DEFAULT_HOOK_ORDER
+    });
+    this.hooks.sort((a, b) => a.order - b.order);
+    serverLogger.debug(`Shutdown hook registered: ${name}`, {
+      order: options?.order ?? DEFAULT_HOOK_ORDER,
+      timeout: `${options?.timeout ?? DEFAULT_HOOK_TIMEOUT}ms`
+    });
+  }
+  /**
+   * 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)
+   * );
+   */
+  async trackOperation(name, operation) {
+    if (this.state !== "running") {
+      throw new Error(`Cannot start operation '${name}': server is shutting down`);
+    }
+    const id = `${name}-${++this.operationCounter}`;
+    this.operations.set(id, {
+      name,
+      startedAt: Date.now()
+    });
+    serverLogger.debug(`Operation tracked: ${id}`, {
+      activeOperations: this.operations.size
+    });
+    try {
+      return await operation;
+    } finally {
+      this.operations.delete(id);
+      serverLogger.debug(`Operation completed: ${id}`, {
+        activeOperations: this.operations.size
+      });
+    }
+  }
+  /**
+   * Whether the server is shutting down
+   *
+   * Use this to reject new work early (e.g., return 503 in route handlers).
+   */
+  isShuttingDown() {
+    return this.state !== "running";
+  }
+  /**
+   * Number of currently active tracked operations
+   */
+  getActiveOperationCount() {
+    return this.operations.size;
+  }
+  /**
+   * 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() {
+    if (this.state !== "running") {
+      return;
+    }
+    this.state = "draining";
+    serverLogger.info("Shutdown manager: state set to draining");
+  }
+  /**
+   * 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)
+   */
+  async execute(drainTimeout) {
+    if (this.state === "closed") {
+      serverLogger.warn("ShutdownManager.execute() called but already closed");
+      return;
+    }
+    this.state = "draining";
+    serverLogger.info("Shutdown manager: draining started", {
+      activeOperations: this.operations.size,
+      registeredHooks: this.hooks.length,
+      drainTimeout: `${drainTimeout}ms`
+    });
+    await this.drain(drainTimeout);
+    await this.executeHooks();
+    this.state = "closed";
+    serverLogger.info("Shutdown manager: all hooks executed");
+  }
+  // ========================================================================
+  // Private
+  // ========================================================================
+  /**
+   * Wait for all tracked operations to complete, up to drainTimeout
+   */
+  async drain(drainTimeout) {
+    if (this.operations.size === 0) {
+      serverLogger.info("Shutdown manager: no active operations, drain skipped");
+      return;
+    }
+    serverLogger.info(`Shutdown manager: waiting for ${this.operations.size} operations to drain...`);
+    const deadline = Date.now() + drainTimeout;
+    while (this.operations.size > 0 && Date.now() < deadline) {
+      const remaining = deadline - Date.now();
+      const ops = Array.from(this.operations.values()).map((op) => ({
+        name: op.name,
+        elapsed: `${Math.round((Date.now() - op.startedAt) / 1e3)}s`
+      }));
+      serverLogger.info("Shutdown manager: drain in progress", {
+        activeOperations: this.operations.size,
+        remainingTimeout: `${Math.round(remaining / 1e3)}s`,
+        operations: ops
+      });
+      await sleep(Math.min(DRAIN_POLL_INTERVAL, remaining));
+    }
+    if (this.operations.size > 0) {
+      const abandoned = Array.from(this.operations.values()).map((op) => op.name);
+      serverLogger.warn("Shutdown manager: drain timeout \u2014 abandoning operations", {
+        abandoned
+      });
+    } else {
+      serverLogger.info("Shutdown manager: all operations drained successfully");
+    }
+  }
+  /**
+   * Execute registered shutdown hooks in order
+   */
+  async executeHooks() {
+    if (this.hooks.length === 0) {
+      return;
+    }
+    serverLogger.info(`Shutdown manager: executing ${this.hooks.length} hooks...`);
+    for (const hook of this.hooks) {
+      serverLogger.debug(`Shutdown hook [${hook.name}] starting (timeout: ${hook.timeout}ms)`);
+      try {
+        await withTimeout(
+          hook.handler(),
+          hook.timeout,
+          `Shutdown hook '${hook.name}' timeout after ${hook.timeout}ms`
+        );
+        serverLogger.info(`Shutdown hook [${hook.name}] completed`);
+      } catch (error) {
+        serverLogger.error(
+          `Shutdown hook [${hook.name}] failed`,
+          error
+        );
+      }
     }
   }
+};
+var instance = null;
+function getShutdownManager() {
+  if (!instance) {
+    instance = new ShutdownManager();
+  }
+  return instance;
+}
+function resetShutdownManager() {
+  instance = null;
+}
+function sleep(ms) {
+  return new Promise((resolve2) => setTimeout(resolve2, ms));
 }
+async function withTimeout(promise, timeout, message) {
+  let timeoutId;
+  return Promise.race([
+    promise.finally(() => {
+      if (timeoutId) clearTimeout(timeoutId);
+    }),
+    new Promise((_, reject) => {
+      timeoutId = setTimeout(() => {
+        reject(new Error(message));
+      }, timeout);
+    })
+  ]);
+}
+
+// src/server/helpers.ts
 function createHealthCheckHandler(detailed) {
   return async (c) => {
+    const shutdownManager = getShutdownManager();
+    if (shutdownManager.isShuttingDown()) {
+      return c.json({
+        status: "shutting_down",
+        timestamp: (/* @__PURE__ */ new Date()).toISOString()
+      }, 503);
+    }
     const response = {
       status: "ok",
       timestamp: (/* @__PURE__ */ new Date()).toISOString()
@@ -387,34 +895,49 @@ function applyServerTimeouts(server, timeouts) {
     server.headersTimeout = timeouts.headers;
   }
 }
-function getTimeoutConfig(config2) {
+function getTimeoutConfig(config) {
+  return {
+    request: config?.request ?? env.SERVER_TIMEOUT,
+    keepAlive: config?.keepAlive ?? env.SERVER_KEEPALIVE_TIMEOUT,
+    headers: config?.headers ?? env.SERVER_HEADERS_TIMEOUT
+  };
+}
+function getShutdownTimeout(config) {
+  return config?.timeout ?? env.SHUTDOWN_TIMEOUT;
+}
+function getFetchTimeoutConfig(config) {
   return {
-    request: config2?.request ?? env.SERVER_TIMEOUT,
-    keepAlive: config2?.keepAlive ?? env.SERVER_KEEPALIVE_TIMEOUT,
-    headers: config2?.headers ?? env.SERVER_HEADERS_TIMEOUT
+    connect: config?.connect ?? env.FETCH_CONNECT_TIMEOUT,
+    headers: config?.headers ?? env.FETCH_HEADERS_TIMEOUT,
+    body: config?.body ?? env.FETCH_BODY_TIMEOUT
   };
 }
-function getShutdownTimeout(config2) {
-  return config2?.timeout ?? env.SHUTDOWN_TIMEOUT;
+function applyGlobalFetchTimeouts(timeouts) {
+  const agent = new Agent({
+    connect: { timeout: timeouts.connect },
+    headersTimeout: timeouts.headers,
+    bodyTimeout: timeouts.body
+  });
+  setGlobalDispatcher(agent);
 }
-function buildMiddlewareOrder(config2) {
+function buildMiddlewareOrder(config) {
   const order = [];
-  const middlewareConfig = config2.middleware ?? {};
+  const middlewareConfig = config.middleware ?? {};
   const enableLogger = middlewareConfig.logger !== false;
   const enableCors = middlewareConfig.cors !== false;
   const enableErrorHandler = middlewareConfig.errorHandler !== false;
   if (enableLogger) order.push("RequestLogger");
   if (enableCors) order.push("CORS");
-  config2.use?.forEach((_, i) => order.push(`Custom[${i}]`));
-  if (config2.beforeRoutes) order.push("beforeRoutes hook");
+  config.use?.forEach((_, i) => order.push(`Custom[${i}]`));
+  if (config.beforeRoutes) order.push("beforeRoutes hook");
   order.push("Routes");
-  if (config2.afterRoutes) order.push("afterRoutes hook");
+  if (config.afterRoutes) order.push("afterRoutes hook");
   if (enableErrorHandler) order.push("ErrorHandler");
   return order;
 }
-function buildStartupConfig(config2, timeouts) {
-  const middlewareConfig = config2.middleware ?? {};
-  const healthCheckConfig = config2.healthCheck ?? {};
+function buildStartupConfig(config, timeouts) {
+  const middlewareConfig = config.middleware ?? {};
+  const healthCheckConfig = config.healthCheck ?? {};
   const healthCheckEnabled = healthCheckConfig.enabled !== false;
   const healthCheckPath = healthCheckConfig.path ?? "/health";
   const healthCheckDetailed = healthCheckConfig.detailed ?? env.NODE_ENV === "development";
@@ -423,7 +946,7 @@ function buildStartupConfig(config2, timeouts) {
       logger: middlewareConfig.logger !== false,
       cors: middlewareConfig.cors !== false,
       errorHandler: middlewareConfig.errorHandler !== false,
-      custom: config2.use?.length ?? 0
+      custom: config.use?.length ?? 0
     },
     healthCheck: healthCheckEnabled ? {
       enabled: true,
@@ -431,8 +954,8 @@ function buildStartupConfig(config2, timeouts) {
       detailed: healthCheckDetailed
     } : { enabled: false },
     hooks: {
-      beforeRoutes: !!config2.beforeRoutes,
-      afterRoutes: !!config2.afterRoutes
+      beforeRoutes: !!config.beforeRoutes,
+      afterRoutes: !!config.afterRoutes
     },
     timeout: {
       request: `${timeouts.request}ms`,
@@ -440,23 +963,22 @@ function buildStartupConfig(config2, timeouts) {
       headers: `${timeouts.headers}ms`
     },
     shutdown: {
-      timeout: `${config2.shutdown?.timeout ?? env.SHUTDOWN_TIMEOUT}ms`
+      timeout: `${config.shutdown?.timeout ?? env.SHUTDOWN_TIMEOUT}ms`
     }
   };
 }
-var serverLogger = logger.child("@spfn/core:server");
 
 // src/server/create-server.ts
-async function createServer(config2) {
+async function createServer(config) {
   const cwd = process.cwd();
   const appPath = join(cwd, "src", "server", "app.ts");
   const appJsPath = join(cwd, "src", "server", "app");
   if (existsSync(appPath) || existsSync(appJsPath)) {
-    return await loadCustomApp(appPath, appJsPath, config2);
+    return await loadCustomApp(appPath, appJsPath, config);
   }
-  return await createAutoConfiguredApp(config2);
+  return await createAutoConfiguredApp(config);
 }
-async function loadCustomApp(appPath, appJsPath, config2) {
+async function loadCustomApp(appPath, appJsPath, config) {
   const actualPath = existsSync(appPath) ? appPath : appJsPath;
   const appModule = await import(actualPath);
   const appFactory = appModule.default;
@@ -464,14 +986,15 @@ async function loadCustomApp(appPath, appJsPath, config2) {
     throw new Error("app.ts must export a default function that returns a Hono app");
   }
   const app = await appFactory();
-  if (config2?.routes) {
-    registerRoutes(app, config2.routes, config2.middlewares);
+  if (config?.routes) {
+    const routes = registerRoutes(app, config.routes, config.middlewares);
+    logRegisteredRoutes(routes, config?.debug ?? false);
   }
   return app;
 }
-async function createAutoConfiguredApp(config2) {
+async function createAutoConfiguredApp(config) {
   const app = new Hono();
-  const middlewareConfig = config2?.middleware ?? {};
+  const middlewareConfig = config?.middleware ?? {};
   const enableLogger = middlewareConfig.logger !== false;
   const enableCors = middlewareConfig.cors !== false;
   const enableErrorHandler = middlewareConfig.errorHandler !== false;
@@ -481,30 +1004,31 @@ async function createAutoConfiguredApp(config2) {
       await next();
     });
   }
-  applyDefaultMiddleware(app, config2, enableLogger, enableCors);
-  if (Array.isArray(config2?.use)) {
-    config2.use.forEach((mw) => app.use("*", mw));
+  applyDefaultMiddleware(app, config, enableLogger, enableCors);
+  if (Array.isArray(config?.use)) {
+    config.use.forEach((mw) => app.use("*", mw));
   }
-  registerHealthCheckEndpoint(app, config2);
-  await executeBeforeRoutesHook(app, config2);
-  await loadAppRoutes(app, config2);
-  await executeAfterRoutesHook(app, config2);
+  registerHealthCheckEndpoint(app, config);
+  await executeBeforeRoutesHook(app, config);
+  await loadAppRoutes(app, config);
+  await registerSSEEndpoint(app, config);
+  await executeAfterRoutesHook(app, config);
   if (enableErrorHandler) {
-    app.onError(ErrorHandler());
+    app.onError(ErrorHandler({ onError: config?.middleware?.onError }));
   }
   return app;
 }
-function applyDefaultMiddleware(app, config2, enableLogger, enableCors) {
+function applyDefaultMiddleware(app, config, enableLogger, enableCors) {
   if (enableLogger) {
     app.use("*", RequestLogger());
   }
   if (enableCors) {
-    const corsOptions = config2?.cors !== false ? config2?.cors : void 0;
+    const corsOptions = config?.cors !== false ? config?.cors : void 0;
     app.use("*", cors(corsOptions));
   }
 }
-function registerHealthCheckEndpoint(app, config2) {
-  const healthCheckConfig = config2?.healthCheck ?? {};
+function registerHealthCheckEndpoint(app, config) {
+  const healthCheckConfig = config?.healthCheck ?? {};
   const healthCheckEnabled = healthCheckConfig.enabled !== false;
   const healthCheckPath = healthCheckConfig.path ?? "/health";
   const healthCheckDetailed = healthCheckConfig.detailed ?? process.env.NODE_ENV === "development";
@@ -513,74 +1037,178 @@ function registerHealthCheckEndpoint(app, config2) {
     serverLogger.debug(`Health check endpoint enabled at ${healthCheckPath}`);
   }
 }
-async function executeBeforeRoutesHook(app, config2) {
-  if (config2?.lifecycle?.beforeRoutes) {
-    await config2.lifecycle.beforeRoutes(app);
+async function executeBeforeRoutesHook(app, config) {
+  if (config?.lifecycle?.beforeRoutes) {
+    await config.lifecycle.beforeRoutes(app);
   }
 }
-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");
-    }
+async function loadAppRoutes(app, config) {
+  const debug = isDebugMode(config);
+  if (config?.routes) {
+    const routes = registerRoutes(app, config.routes, config.middlewares);
+    logRegisteredRoutes(routes, debug);
   } else if (debug) {
     serverLogger.warn("\u26A0\uFE0F  No routes configured. Use defineServerConfig().routes() to register routes.");
   }
 }
-async function executeAfterRoutesHook(app, config2) {
-  if (config2?.lifecycle?.afterRoutes) {
-    await config2.lifecycle.afterRoutes(app);
+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, config) {
+  if (config?.lifecycle?.afterRoutes) {
+    await config.lifecycle.afterRoutes(app);
+  }
+}
+async function registerSSEEndpoint(app, config) {
+  if (!config?.events) {
+    return;
+  }
+  const eventsConfig = config.eventsConfig ?? {};
+  const streamPath = eventsConfig.path ?? "/events/stream";
+  const authConfig = eventsConfig.auth;
+  const debug = isDebugMode(config);
+  let tokenManager;
+  if (authConfig?.enabled) {
+    let store = authConfig.store;
+    if (!store) {
+      try {
+        const { getCache: getCache2 } = await import('@spfn/core/cache');
+        const cache = getCache2();
+        if (cache) {
+          store = new CacheTokenStore(cache);
+          if (debug) {
+            serverLogger.info("SSE token store: cache (Redis/Valkey)");
+          }
+        }
+      } catch {
+      }
+    }
+    tokenManager = new SSETokenManager({
+      ttl: authConfig.tokenTtl,
+      store
+    });
+    const tokenPath = streamPath.replace(/\/[^/]+$/, "/token");
+    const mwHandlers = (config.middlewares ?? []).map((mw) => mw.handler);
+    const getSubject = authConfig.getSubject ?? ((c) => c.get("auth")?.userId ?? null);
+    app.post(tokenPath, ...mwHandlers, async (c) => {
+      const subject = getSubject(c);
+      if (!subject) {
+        return c.json({ error: "Unable to identify subject" }, 401);
+      }
+      const token = await tokenManager.issue(subject);
+      return c.json({ token });
+    });
+    if (debug) {
+      serverLogger.info(`\u2713 SSE token endpoint registered at POST ${tokenPath}`);
+    }
+  }
+  app.get(streamPath, createSSEHandler(config.events, eventsConfig, tokenManager));
+  if (debug) {
+    const eventNames = config.events.eventNames;
+    serverLogger.info(`\u2713 SSE endpoint registered at ${streamPath}`, {
+      events: eventNames,
+      auth: !!authConfig?.enabled
+    });
   }
 }
-function isDebugMode(config2) {
-  return config2?.debug ?? process.env.NODE_ENV === "development";
+function isDebugMode(config) {
+  return config?.debug ?? process.env.NODE_ENV === "development";
 }
 var jobLogger = logger.child("@spfn/core:job");
-var bossInstance = null;
-var bossConfig = null;
+function requiresSSLWithoutVerification(connectionString) {
+  try {
+    const url = new URL(connectionString);
+    const sslmode = url.searchParams.get("sslmode");
+    return sslmode === "require" || sslmode === "prefer";
+  } catch {
+    return false;
+  }
+}
+function stripSslModeFromUrl(connectionString) {
+  const url = new URL(connectionString);
+  url.searchParams.delete("sslmode");
+  return url.toString();
+}
+var BOSS_KEY = Symbol.for("spfn:boss-instance");
+var CONFIG_KEY = Symbol.for("spfn:boss-config");
+var g = globalThis;
+function getBossInstance() {
+  return g[BOSS_KEY] ?? null;
+}
+function setBossInstance(instance2) {
+  g[BOSS_KEY] = instance2;
+}
+function getBossConfig() {
+  return g[CONFIG_KEY] ?? null;
+}
+function setBossConfig(config) {
+  g[CONFIG_KEY] = config;
+}
 async function initBoss(options) {
-  if (bossInstance) {
+  const existing = getBossInstance();
+  if (existing) {
     jobLogger.warn("pg-boss already initialized, returning existing instance");
-    return bossInstance;
+    return existing;
   }
   jobLogger.info("Initializing pg-boss...");
-  bossConfig = options;
-  bossInstance = new PgBoss({
-    connectionString: options.connectionString,
+  setBossConfig(options);
+  const needsSSL = requiresSSLWithoutVerification(options.connectionString);
+  const pgBossOptions = {
+    // pg 드라이버가 URL의 sslmode=require를 verify-full로 해석해서
+    // ssl 옵션을 무시하므로, URL에서 sslmode를 빼고 ssl 객체만 전달
+    connectionString: needsSSL ? stripSslModeFromUrl(options.connectionString) : options.connectionString,
     schema: options.schema ?? "spfn_queue",
-    maintenanceIntervalSeconds: options.maintenanceIntervalSeconds ?? 120,
-    monitorIntervalSeconds: options.monitorIntervalSeconds
-  });
-  bossInstance.on("error", (error) => {
+    maintenanceIntervalSeconds: options.maintenanceIntervalSeconds ?? 120
+  };
+  if (needsSSL) {
+    pgBossOptions.ssl = { rejectUnauthorized: false };
+  }
+  if (options.monitorIntervalSeconds !== void 0 && options.monitorIntervalSeconds >= 1) {
+    pgBossOptions.monitorIntervalSeconds = options.monitorIntervalSeconds;
+  }
+  const boss = new PgBoss(pgBossOptions);
+  boss.on("error", (error) => {
     jobLogger.error("pg-boss error:", error);
   });
-  await bossInstance.start();
+  await boss.start();
+  setBossInstance(boss);
   jobLogger.info("pg-boss started successfully");
-  return bossInstance;
+  return boss;
 }
 function getBoss() {
-  return bossInstance;
+  return getBossInstance();
 }
 async function stopBoss() {
-  if (!bossInstance) {
+  const boss = getBossInstance();
+  if (!boss) {
     return;
   }
   jobLogger.info("Stopping pg-boss...");
   try {
-    await bossInstance.stop({ graceful: true, timeout: 3e4 });
+    await boss.stop({ graceful: true, timeout: 3e4 });
     jobLogger.info("pg-boss stopped gracefully");
   } catch (error) {
     jobLogger.error("Error stopping pg-boss:", error);
     throw error;
   } finally {
-    bossInstance = null;
-    bossConfig = null;
+    setBossInstance(null);
+    setBossConfig(null);
   }
 }
 function shouldClearOnStart() {
-  return bossConfig?.clearOnStart ?? false;
+  return getBossConfig()?.clearOnStart ?? false;
 }
 
 // src/job/job-router.ts
@@ -639,7 +1267,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 +1318,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 +1332,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,
     {},
@@ -762,16 +1396,16 @@ function printBanner(options) {
 }
 
 // src/server/validation.ts
-function validateServerConfig(config2) {
-  if (config2.port !== void 0) {
-    if (!Number.isInteger(config2.port) || config2.port < 0 || config2.port > 65535) {
+function validateServerConfig(config) {
+  if (config.port !== void 0) {
+    if (!Number.isInteger(config.port) || config.port < 0 || config.port > 65535) {
       throw new Error(
-        `Invalid port: ${config2.port}. Port must be an integer between 0 and 65535.`
+        `Invalid port: ${config.port}. Port must be an integer between 0 and 65535.`
       );
     }
   }
-  if (config2.timeout) {
-    const { request, keepAlive, headers } = config2.timeout;
+  if (config.timeout) {
+    const { request, keepAlive, headers } = config.timeout;
     if (request !== void 0 && (request < 0 || !Number.isFinite(request))) {
       throw new Error(`Invalid timeout.request: ${request}. Must be a positive number.`);
     }
@@ -787,16 +1421,16 @@ function validateServerConfig(config2) {
       );
     }
   }
-  if (config2.shutdown?.timeout !== void 0) {
-    const timeout = config2.shutdown.timeout;
+  if (config.shutdown?.timeout !== void 0) {
+    const timeout = config.shutdown.timeout;
     if (timeout < 0 || !Number.isFinite(timeout)) {
       throw new Error(`Invalid shutdown.timeout: ${timeout}. Must be a positive number.`);
     }
   }
-  if (config2.healthCheck?.path) {
-    if (!config2.healthCheck.path.startsWith("/")) {
+  if (config.healthCheck?.path) {
+    if (!config.healthCheck.path.startsWith("/")) {
       throw new Error(
-        `Invalid healthCheck.path: "${config2.healthCheck.path}". Must start with "/".`
+        `Invalid healthCheck.path: "${config.healthCheck.path}". Must start with "/".`
       );
     }
   }
@@ -805,9 +1439,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",
@@ -815,9 +1447,9 @@ var CONFIG_FILE_PATHS = [
   "src/server/server.config.ts"
 ];
 var processHandlersRegistered = false;
-async function startServer(config2) {
-  loadEnvFiles();
-  const finalConfig = await loadAndMergeConfig(config2);
+async function startServer(config) {
+  loadEnv();
+  const finalConfig = await loadAndMergeConfig(config);
   const { host, port, debug } = finalConfig;
   validateServerConfig(finalConfig);
   if (!host || !port) {
@@ -835,6 +1467,8 @@ async function startServer(config2) {
     const server = startHttpServer(app, host, port);
     const timeouts = getTimeoutConfig(finalConfig.timeout);
     applyServerTimeouts(server, timeouts);
+    const fetchTimeouts = getFetchTimeoutConfig(finalConfig.fetchTimeout);
+    applyGlobalFetchTimeouts(fetchTimeouts);
     logServerTimeouts(timeouts);
     printBanner({
       mode: debug ? "Development" : "Production",
@@ -851,11 +1485,6 @@ async function startServer(config2) {
       config: finalConfig,
       close: async () => {
         serverLogger.info("Manual server shutdown requested");
-        if (shutdownState.isShuttingDown) {
-          serverLogger.warn("Shutdown already in progress, ignoring manual close request");
-          return;
-        }
-        shutdownState.isShuttingDown = true;
         await shutdownServer();
       }
     };
@@ -875,7 +1504,7 @@ async function startServer(config2) {
     throw error;
   }
 }
-async function loadAndMergeConfig(config2) {
+async function loadAndMergeConfig(config) {
   const cwd = process.cwd();
   let fileConfig = {};
   let loadedConfigPath = null;
@@ -899,26 +1528,26 @@ async function loadAndMergeConfig(config2) {
   }
   return {
     ...fileConfig,
-    ...config2,
-    port: config2?.port ?? fileConfig?.port ?? env.PORT,
-    host: config2?.host ?? fileConfig?.host ?? env.HOST
+    ...config,
+    port: config?.port ?? fileConfig?.port ?? env.PORT,
+    host: config?.host ?? fileConfig?.host ?? env.HOST
   };
 }
-function getInfrastructureConfig(config2) {
+function getInfrastructureConfig(config) {
   return {
-    database: config2.infrastructure?.database !== false,
-    redis: config2.infrastructure?.redis !== false
+    database: config.infrastructure?.database !== false,
+    redis: config.infrastructure?.redis !== false
   };
 }
-async function initializeInfrastructure(config2) {
-  if (config2.lifecycle?.beforeInfrastructure) {
+async function initializeInfrastructure(config) {
+  if (config.lifecycle?.beforeInfrastructure) {
     serverLogger.debug("Executing beforeInfrastructure hook...");
-    await config2.lifecycle.beforeInfrastructure(config2);
+    await config.lifecycle.beforeInfrastructure(config);
   }
-  const infraConfig = getInfrastructureConfig(config2);
+  const infraConfig = getInfrastructureConfig(config);
   if (infraConfig.database) {
     serverLogger.debug("Initializing database...");
-    await initDatabase(config2.database);
+    await initDatabase(config.database);
   } else {
     serverLogger.debug("Database initialization disabled");
   }
@@ -928,11 +1557,11 @@ async function initializeInfrastructure(config2) {
   } else {
     serverLogger.debug("Redis initialization disabled");
   }
-  if (config2.lifecycle?.afterInfrastructure) {
+  if (config.lifecycle?.afterInfrastructure) {
     serverLogger.debug("Executing afterInfrastructure hook...");
-    await config2.lifecycle.afterInfrastructure();
+    await config.lifecycle.afterInfrastructure();
   }
-  if (config2.jobs) {
+  if (config.jobs) {
     const dbUrl = env.DATABASE_URL;
     if (!dbUrl) {
       throw new Error(
@@ -942,10 +1571,24 @@ async function initializeInfrastructure(config2) {
     serverLogger.debug("Initializing pg-boss...");
     await initBoss({
       connectionString: dbUrl,
-      ...config2.jobsConfig
+      ...config.jobsConfig
     });
     serverLogger.debug("Registering jobs...");
-    await registerJobs(config2.jobs);
+    await registerJobs(config.jobs);
+  }
+  if (config.workflows) {
+    const infraConfig2 = getInfrastructureConfig(config);
+    if (!infraConfig2.database) {
+      throw new Error(
+        "Workflows require database connection. Ensure database is enabled in infrastructure config."
+      );
+    }
+    serverLogger.debug("Initializing workflow engine...");
+    config.workflows._init(
+      getDatabase(),
+      config.workflowsConfig
+    );
+    serverLogger.info("Workflow engine initialized");
   }
 }
 function startHttpServer(app, host, port) {
@@ -956,8 +1599,8 @@ function startHttpServer(app, host, port) {
     hostname: host
   });
 }
-function logMiddlewareOrder(config2) {
-  const middlewareOrder = buildMiddlewareOrder(config2);
+function logMiddlewareOrder(config) {
+  const middlewareOrder = buildMiddlewareOrder(config);
   serverLogger.debug("Middleware execution order", {
     order: middlewareOrder
   });
@@ -969,8 +1612,8 @@ function logServerTimeouts(timeouts) {
     headers: `${timeouts.headers}ms`
   });
 }
-function logServerStarted(debug, host, port, config2, timeouts) {
-  const startupConfig = buildStartupConfig(config2, timeouts);
+function logServerStarted(debug, host, port, config, timeouts) {
+  const startupConfig = buildStartupConfig(config, timeouts);
   serverLogger.info("Server started successfully", {
     mode: debug ? "development" : "production",
     host,
@@ -978,65 +1621,74 @@ function logServerStarted(debug, host, port, config2, timeouts) {
     config: startupConfig
   });
 }
-function createShutdownHandler(server, config2, shutdownState) {
+function createShutdownHandler(server, config, shutdownState) {
   return async () => {
     if (shutdownState.isShuttingDown) {
       serverLogger.debug("Shutdown already in progress for this instance, skipping");
       return;
     }
     shutdownState.isShuttingDown = true;
-    serverLogger.debug("Closing HTTP server...");
-    let timeoutId;
-    await Promise.race([
-      new Promise((resolve2, reject) => {
-        server.close((err) => {
-          if (timeoutId) clearTimeout(timeoutId);
-          if (err) {
-            serverLogger.error("HTTP server close error", err);
-            reject(err);
-          } else {
-            serverLogger.info("HTTP server closed");
-            resolve2();
-          }
-        });
-      }),
-      new Promise((_, reject) => {
-        timeoutId = setTimeout(() => {
-          reject(new Error(`HTTP server close timeout after ${TIMEOUTS.SERVER_CLOSE}ms`));
-        }, TIMEOUTS.SERVER_CLOSE);
-      })
-    ]).catch((error) => {
-      if (timeoutId) clearTimeout(timeoutId);
-      serverLogger.warn("HTTP server close timeout, forcing shutdown", error);
-    });
-    if (config2.jobs) {
-      serverLogger.debug("Stopping pg-boss...");
+    const shutdownTimeout = getShutdownTimeout(config.shutdown);
+    const shutdownManager = getShutdownManager();
+    shutdownManager.beginShutdown();
+    serverLogger.info("Phase 1: Closing HTTP server (stop accepting new connections)...");
+    await closeHttpServer(server);
+    if (config.jobs) {
+      serverLogger.info("Phase 2: Stopping pg-boss...");
       try {
         await stopBoss();
+        serverLogger.info("pg-boss stopped");
       } catch (error) {
         serverLogger.error("pg-boss stop failed", error);
       }
     }
-    if (config2.lifecycle?.beforeShutdown) {
-      serverLogger.debug("Executing beforeShutdown hook...");
+    const drainTimeout = Math.floor(shutdownTimeout * 0.8);
+    serverLogger.info(`Phase 3: Draining tracked operations (timeout: ${drainTimeout}ms)...`);
+    await shutdownManager.execute(drainTimeout);
+    if (config.lifecycle?.beforeShutdown) {
+      serverLogger.info("Phase 4: Executing beforeShutdown lifecycle hook...");
       try {
-        await config2.lifecycle.beforeShutdown();
+        await config.lifecycle.beforeShutdown();
       } catch (error) {
-        serverLogger.error("beforeShutdown hook failed", error);
+        serverLogger.error("beforeShutdown lifecycle hook failed", error);
       }
     }
-    const infraConfig = getInfrastructureConfig(config2);
+    serverLogger.info("Phase 5: Closing infrastructure...");
+    const infraConfig = getInfrastructureConfig(config);
     if (infraConfig.database) {
-      serverLogger.debug("Closing database connections...");
       await closeInfrastructure(closeDatabase, "Database", TIMEOUTS.DATABASE_CLOSE);
     }
     if (infraConfig.redis) {
-      serverLogger.debug("Closing Redis connections...");
       await closeInfrastructure(closeCache, "Redis", TIMEOUTS.REDIS_CLOSE);
     }
     serverLogger.info("Server shutdown completed");
   };
 }
+async function closeHttpServer(server) {
+  let timeoutId;
+  await Promise.race([
+    new Promise((resolve2, reject) => {
+      server.close((err) => {
+        if (timeoutId) clearTimeout(timeoutId);
+        if (err) {
+          serverLogger.error("HTTP server close error", err);
+          reject(err);
+        } else {
+          serverLogger.info("HTTP server closed");
+          resolve2();
+        }
+      });
+    }),
+    new Promise((_, reject) => {
+      timeoutId = setTimeout(() => {
+        reject(new Error(`HTTP server close timeout after ${TIMEOUTS.SERVER_CLOSE}ms`));
+      }, TIMEOUTS.SERVER_CLOSE);
+    })
+  ]).catch((error) => {
+    if (timeoutId) clearTimeout(timeoutId);
+    serverLogger.warn("HTTP server close timeout, forcing shutdown", error);
+  });
+}
 async function closeInfrastructure(closeFn, name, timeout) {
   let timeoutId;
   try {
@@ -1056,14 +1708,14 @@ async function closeInfrastructure(closeFn, name, timeout) {
     serverLogger.error(`${name} close failed or timed out`, error);
   }
 }
-function createGracefulShutdown(shutdownServer, config2, shutdownState) {
+function createGracefulShutdown(shutdownServer, config, shutdownState) {
   return async (signal) => {
     if (shutdownState.isShuttingDown) {
       serverLogger.warn(`${signal} received but shutdown already in progress, ignoring`);
       return;
     }
     serverLogger.info(`${signal} received, starting graceful shutdown...`);
-    const shutdownTimeout = getShutdownTimeout(config2.shutdown);
+    const shutdownTimeout = getShutdownTimeout(config.shutdown);
     let timeoutId;
     try {
       await Promise.race([
@@ -1091,31 +1743,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 +1779,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,20 +1797,21 @@ function registerProcessHandlers(shutdown) {
         promise
       });
     }
-    handleProcessError("UNHANDLED_REJECTION", shutdown);
+    handleProcessError("UNHANDLED_REJECTION");
   });
   serverLogger.debug("Process-level shutdown handlers registered successfully");
 }
-async function cleanupOnFailure(config2) {
+async function cleanupOnFailure(config) {
   try {
     serverLogger.debug("Cleaning up after initialization failure...");
-    const infraConfig = getInfrastructureConfig(config2);
+    const infraConfig = getInfrastructureConfig(config);
     if (infraConfig.database) {
       await closeInfrastructure(closeDatabase, "Database", TIMEOUTS.DATABASE_CLOSE);
     }
     if (infraConfig.redis) {
       await closeInfrastructure(closeCache, "Redis", TIMEOUTS.REDIS_CLOSE);
     }
+    resetShutdownManager();
     serverLogger.debug("Cleanup completed");
   } catch (cleanupError) {
     serverLogger.error("Cleanup failed", cleanupError);
@@ -1307,10 +1937,45 @@ var ServerConfigBuilder = class {
    *   .build();
    * ```
    */
-  jobs(router, config2) {
+  jobs(router, config) {
     this.config.jobs = router;
-    if (config2) {
-      this.config.jobsConfig = config2;
+    if (config) {
+      this.config.jobsConfig = config;
+    }
+    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, config) {
+    this.config.events = router;
+    if (config) {
+      this.config.eventsConfig = config;
     }
     return this;
   }
@@ -1356,6 +2021,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, config) {
+    this.config.workflows = router;
+    if (config) {
+      this.config.workflowsConfig = config;
+    }
+    return this;
+  }
   /**
    * Configure lifecycle hooks
    * Can be called multiple times - hooks will be executed in registration order
@@ -1403,6 +2095,6 @@ function defineServerConfig() {
   return new ServerConfigBuilder();
 }
 
-export { createServer, defineServerConfig, loadEnvFiles, startServer };
+export { createServer, defineServerConfig, getShutdownManager, loadEnv, loadEnvFiles, startServer };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map