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

package/dist/server/index.js

@@ -398,11 +398,62 @@ function loadEnvFiles() {
   }
   loadEnv();
 }
+
+// src/event/sse/bounded-writer.ts
+function createBoundedWriter(stream, maxQueue, onClose) {
+  const pending = [];
+  let flushing = false;
+  let closed = false;
+  const flush = async () => {
+    if (flushing || closed) {
+      return;
+    }
+    flushing = true;
+    while (pending.length > 0 && !closed) {
+      const frame = pending.shift();
+      try {
+        await stream.writeSSE(frame);
+      } catch (err) {
+        flushing = false;
+        onClose(err instanceof Error ? err.message : String(err));
+        return;
+      }
+    }
+    flushing = false;
+  };
+  return {
+    enqueue(frame) {
+      if (closed) {
+        return;
+      }
+      pending.push(frame);
+      if (pending.length > maxQueue) {
+        onClose("outbound queue overflow (slow consumer)");
+        return;
+      }
+      void flush();
+    },
+    close() {
+      closed = true;
+      pending.length = 0;
+    },
+    get queued() {
+      return pending.length;
+    }
+  };
+}
+
+// src/event/sse/handler.ts
 var sseLogger = logger.child("@spfn/core:sse");
+var DEFAULT_MAX_QUEUE = 1e3;
 function createSSEHandler(router, config = {}, tokenManager) {
   const {
-    pingInterval = 3e4,
-    auth: authConfig
+    // 10s — keep-alive가 중간 프록시(GCP LB/nginx)의 idle 타임아웃(흔히 ~15-30s)보다 자주 와야
+    // 첫 ping 전 침묵 구간에 연결이 끊기지 않는다. 30s 기본은 idle 타임아웃보다 길어 SSE가
+    // 데이터 없는 동안 끊기던 문제가 있었다.
+    pingInterval = 1e4,
+    auth: authConfig,
+    maxQueue = DEFAULT_MAX_QUEUE
   } = config;
   return async (c) => {
     const subject = await authenticateToken(c, tokenManager);
@@ -443,15 +494,29 @@ function createSSEHandler(router, config = {}, tokenManager) {
       let messageId = 0;
       let connectionDead = false;
       let pingTimer;
-      const cleanup = () => {
+      let writer;
+      const cleanup = (reason) => {
         if (connectionDead) return;
         connectionDead = true;
         clearInterval(pingTimer);
         unsubscribes.forEach((fn) => fn());
+        writer?.close();
         sseLogger.info("SSE dead connection cleaned up", {
-          events: allowedEvents
+          events: allowedEvents,
+          reason
         });
       };
+      writer = createBoundedWriter(stream, maxQueue, (reason) => {
+        sseLogger.warn("SSE connection closed", { events: allowedEvents, reason });
+        cleanup(reason);
+      });
+      writer.enqueue({
+        event: "connected",
+        data: JSON.stringify({
+          subscribedEvents: allowedEvents,
+          timestamp: Date.now()
+        })
+      });
       for (const eventName of allowedEvents) {
         const eventDef = router.events[eventName];
         if (!eventDef) {
@@ -473,17 +538,10 @@ function createSSEHandler(router, config = {}, tokenManager) {
             event: eventName,
             messageId
           });
-          stream.writeSSE({
+          writer.enqueue({
             id: String(messageId),
             event: eventName,
             data: JSON.stringify(message)
-          }).catch((err) => {
-            sseLogger.warn("SSE write failed", {
-              event: eventName,
-              messageId,
-              error: err.message
-            });
-            cleanup();
           });
         });
         unsubscribes.push(unsubscribe);
@@ -492,23 +550,11 @@ function createSSEHandler(router, config = {}, tokenManager) {
         events: allowedEvents,
         subscriptionCount: unsubscribes.length
       });
-      await stream.writeSSE({
-        event: "connected",
-        data: JSON.stringify({
-          subscribedEvents: allowedEvents,
-          timestamp: Date.now()
-        })
-      });
       pingTimer = setInterval(() => {
         if (connectionDead) return;
-        stream.writeSSE({
+        writer.enqueue({
           event: "ping",
           data: JSON.stringify({ timestamp: Date.now() })
-        }).catch((err) => {
-          sseLogger.warn("SSE ping failed", {
-            error: err.message
-          });
-          cleanup();
         });
       }, pingInterval);
       const abortSignal = c.req.raw.signal;
@@ -649,6 +695,263 @@ var SSETokenManager = class {
     }
   }
 };
+var transportLogger = logger.child("@spfn/core:event-transport");
+var DEFAULT_CHANNEL_PREFIX = "spfn:sse:";
+var SUBSCRIBER_QUIT_TIMEOUT_MS = 5e3;
+var PUBLISH_TIMEOUT_MS = 5e3;
+var SUBSCRIBE_TIMEOUT_MS = 5e3;
+var WARN_THROTTLE_MS = 3e4;
+var PUBLISH_BREAKER_COOLDOWN_MS = 1e4;
+function withTimeout(promise, ms, label) {
+  return new Promise((resolve2, reject) => {
+    const timer = setTimeout(() => {
+      reject(new Error(`${label} timed out after ${ms}ms`));
+    }, ms);
+    timer.unref?.();
+    promise.then(
+      (value) => {
+        clearTimeout(timer);
+        resolve2(value);
+      },
+      (err) => {
+        clearTimeout(timer);
+        reject(err);
+      }
+    );
+  });
+}
+var warnThrottle = /* @__PURE__ */ new Map();
+function throttledWarn(key, message, fields) {
+  const now = Date.now();
+  const entry = warnThrottle.get(key);
+  if (entry && now - entry.last < WARN_THROTTLE_MS) {
+    entry.suppressed++;
+    return;
+  }
+  transportLogger.warn(message, entry && entry.suppressed > 0 ? { ...fields, suppressedSinceLast: entry.suppressed } : fields);
+  warnThrottle.set(key, { last: now, suppressed: 0 });
+}
+var STATE_KEY = Symbol.for("@spfn/core:event-transport");
+var state = globalThis[STATE_KEY] ??= {
+  pubSubCache: void 0,
+  subscriber: void 0,
+  channelPrefix: void 0,
+  wired: /* @__PURE__ */ new Map()
+};
+function resolveChannelPrefix(override) {
+  return override ?? process.env.SPFN_SSE_CHANNEL_PREFIX ?? DEFAULT_CHANNEL_PREFIX;
+}
+function createRedisPubSubCache(client, channelPrefix, onSubscriber) {
+  let subscriber;
+  const handlers = /* @__PURE__ */ new Map();
+  let degradedUntil = 0;
+  const ensureSubscriber = () => {
+    if (subscriber) {
+      return subscriber;
+    }
+    subscriber = client.duplicate();
+    onSubscriber?.(subscriber);
+    subscriber.on("message", (channel, raw) => {
+      const handler = handlers.get(channel);
+      if (!handler) {
+        return;
+      }
+      let payload;
+      try {
+        payload = JSON.parse(raw);
+      } catch {
+        transportLogger.warn("Pub/sub message parse failed \u2014 dropped", { channel });
+        return;
+      }
+      void handler(payload);
+    });
+    subscriber.on("error", (err) => {
+      throttledWarn("subscriber-error", "Pub/sub subscriber error", { error: err.message });
+    });
+    return subscriber;
+  };
+  const subscriberHealthy = () => !!subscriber && (subscriber.status === void 0 || subscriber.status === "ready");
+  const deliverLocal = (channel, message) => {
+    const handler = handlers.get(channel);
+    if (handler) {
+      void handler(message);
+    }
+  };
+  return {
+    publish: async (name, message) => {
+      const channel = channelPrefix + name;
+      let serialized;
+      try {
+        serialized = JSON.stringify(message ?? null);
+      } catch (err) {
+        transportLogger.warn("Pub/sub payload serialization failed \u2014 local delivery only", {
+          channel,
+          error: err instanceof Error ? err.message : String(err)
+        });
+        deliverLocal(channel, message ?? null);
+        return;
+      }
+      if (serialized === void 0) {
+        transportLogger.warn("Pub/sub payload not serializable (function/symbol) \u2014 local delivery only", {
+          channel
+        });
+        deliverLocal(channel, message ?? null);
+        return;
+      }
+      const ready = client.status === void 0 || client.status === "ready";
+      const now = Date.now();
+      if (!ready || degradedUntil > 0 && now < degradedUntil) {
+        deliverLocal(channel, JSON.parse(serialized));
+        return;
+      }
+      if (degradedUntil > 0) {
+        degradedUntil = now + PUBLISH_TIMEOUT_MS;
+      }
+      try {
+        await withTimeout(client.publish(channel, serialized), PUBLISH_TIMEOUT_MS, "pub/sub publish");
+        degradedUntil = 0;
+        if (!subscriberHealthy()) {
+          throttledWarn("subscriber-down", "Subscriber connection down \u2014 same-pod local fallback", {
+            channel
+          });
+          deliverLocal(channel, JSON.parse(serialized));
+        }
+      } catch (err) {
+        degradedUntil = Date.now() + PUBLISH_BREAKER_COOLDOWN_MS;
+        throttledWarn("publish-failed", "Pub/sub publish failed \u2014 local delivery only", {
+          channel,
+          error: err instanceof Error ? err.message : String(err)
+        });
+        deliverLocal(channel, JSON.parse(serialized));
+      }
+    },
+    subscribe: async (name, handler) => {
+      const channel = channelPrefix + name;
+      const sub = ensureSubscriber();
+      try {
+        await withTimeout(sub.subscribe(channel), SUBSCRIBE_TIMEOUT_MS, "pub/sub subscribe");
+      } catch (err) {
+        if (handlers.size === 0 && subscriber === sub) {
+          subscriber = void 0;
+          void sub.quit?.().catch(() => void 0);
+        }
+        throw err;
+      }
+      handlers.set(channel, handler);
+    }
+  };
+}
+async function wireEventRouterCache(router, options = {}) {
+  if (options.multiInstance === false) {
+    const events2 = router.events;
+    const stillRedis = Object.keys(events2).filter((k) => state.wired.has(events2[k].name)).length;
+    if (stillRedis > 0) {
+      transportLogger.warn("multiInstance:false has no effect on events already wired to redis by another router", {
+        redisWired: stillRedis
+      });
+    } else {
+      transportLogger.info("Event transport: in-process (multiInstance disabled)");
+    }
+    return "in-process";
+  }
+  const pubSubCache = await resolvePubSubCache(options.channelPrefix);
+  if (!pubSubCache) {
+    transportLogger.info("Event transport: in-process (no cache configured)");
+    return "in-process";
+  }
+  const events = router.events;
+  let wired = 0;
+  let degraded = 0;
+  let alreadyWired = 0;
+  for (const key of Object.keys(events)) {
+    const event = events[key];
+    if (state.wired.has(event.name)) {
+      alreadyWired++;
+      continue;
+    }
+    try {
+      await event.useCache(pubSubCache);
+      state.wired.set(event.name, event);
+      wired++;
+    } catch (err) {
+      degraded++;
+      transportLogger.warn("Event cache wiring failed \u2014 staying in-process for this event", {
+        event: event.name,
+        error: err instanceof Error ? err.message : String(err)
+      });
+    }
+  }
+  if (wired + alreadyWired === 0) {
+    transportLogger.warn("Event transport: redis configured but no event wired \u2014 running in-process", {
+      total: Object.keys(events).length,
+      degraded
+    });
+    return "in-process";
+  }
+  transportLogger.info("Event transport: redis (cross-pod fan-out)", {
+    total: Object.keys(events).length,
+    wired,
+    degraded,
+    alreadyWired
+  });
+  return "redis";
+}
+async function resolvePubSubCache(channelPrefix) {
+  const resolvedPrefix = resolveChannelPrefix(channelPrefix);
+  if (state.pubSubCache) {
+    if (state.channelPrefix !== resolvedPrefix) {
+      transportLogger.warn("Conflicting channelPrefix ignored \u2014 the transport prefix is process-global (first wiring wins).", {
+        active: state.channelPrefix,
+        ignored: resolvedPrefix
+      });
+    }
+    return state.pubSubCache;
+  }
+  let client;
+  try {
+    const { getCache: getCache2 } = await import('@spfn/core/cache');
+    client = getCache2();
+  } catch {
+    return void 0;
+  }
+  if (!client) {
+    return void 0;
+  }
+  if (!channelPrefix && !process.env.SPFN_SSE_CHANNEL_PREFIX) {
+    transportLogger.warn(
+      "Event fan-out is on the default channel prefix (spfn:sse:). Apps sharing one Redis must set channelPrefix or SPFN_SSE_CHANNEL_PREFIX to avoid cross-app leakage."
+    );
+  }
+  state.channelPrefix = resolvedPrefix;
+  state.pubSubCache = createRedisPubSubCache(
+    client,
+    resolvedPrefix,
+    (connection) => {
+      state.subscriber = connection;
+    }
+  );
+  return state.pubSubCache;
+}
+async function closeEventTransport() {
+  const subscriber = state.subscriber;
+  for (const event of state.wired.values()) {
+    event._resetCache?.();
+  }
+  state.subscriber = void 0;
+  state.pubSubCache = void 0;
+  state.channelPrefix = void 0;
+  state.wired.clear();
+  if (!subscriber?.quit) {
+    return;
+  }
+  await Promise.race([
+    subscriber.quit().catch(() => void 0),
+    new Promise((resolve2) => {
+      const timer = setTimeout(resolve2, SUBSCRIBER_QUIT_TIMEOUT_MS);
+      timer.unref?.();
+    })
+  ]);
+}
 var serverLogger = logger.child("@spfn/core:server");
 
 // src/server/shutdown-manager.ts
@@ -822,7 +1125,7 @@ var ShutdownManager = class {
     for (const hook of this.hooks) {
       serverLogger.debug(`Shutdown hook [${hook.name}] starting (timeout: ${hook.timeout}ms)`);
       try {
-        await withTimeout(
+        await withTimeout2(
           hook.handler(),
           hook.timeout,
           `Shutdown hook '${hook.name}' timeout after ${hook.timeout}ms`
@@ -850,7 +1153,7 @@ function resetShutdownManager() {
 function sleep(ms) {
   return new Promise((resolve2) => setTimeout(resolve2, ms));
 }
-async function withTimeout(promise, timeout, message) {
+async function withTimeout2(promise, timeout, message) {
   let timeoutId;
   return Promise.race([
     promise.finally(() => {
@@ -1040,6 +1343,7 @@ async function createAutoConfiguredApp(config) {
     });
   }
   applyDefaultMiddleware(app, config, enableLogger, enableCors);
+  await applyProxyGuard(app, config);
   if (Array.isArray(config?.use)) {
     config.use.forEach((mw) => app.use("*", mw));
   }
@@ -1062,6 +1366,48 @@ function applyDefaultMiddleware(app, config, enableLogger, enableCors) {
     app.use("*", cors(corsOptions));
   }
 }
+async function applyProxyGuard(app, config) {
+  const proxyGuardConfig = config?.proxyGuard;
+  const mode = proxyGuardConfig?.mode ?? "off";
+  if (mode === "off") {
+    return;
+  }
+  const { createProxyGuard, createCacheNonceStore } = await import('@spfn/core/middleware');
+  let nonceStore;
+  if (proxyGuardConfig?.nonce) {
+    try {
+      const { getCache: getCache2 } = await import('@spfn/core/cache');
+      const cache = getCache2();
+      if (cache) {
+        nonceStore = createCacheNonceStore(cache);
+        serverLogger.info("Proxy-guard nonce replay rejection: cache (Redis/Valkey)");
+      } else {
+        serverLogger.warn("Proxy-guard nonce enabled but no cache available \u2014 using timestamp window only");
+      }
+    } catch {
+      serverLogger.warn("Proxy-guard nonce enabled but cache module unavailable \u2014 using timestamp window only");
+    }
+  }
+  const autoSkip = [config?.healthCheck?.path ?? "/health"];
+  if (config?.events) {
+    autoSkip.push(config.eventsConfig?.path ?? "/events/stream");
+  }
+  if (config?.websockets) {
+    autoSkip.push(config.websocketsConfig?.path ?? "/ws");
+  }
+  const skipPaths = [...proxyGuardConfig?.skipPaths ?? [], ...autoSkip];
+  app.use("*", createProxyGuard({
+    mode,
+    secret: proxyGuardConfig?.secret,
+    previousSecrets: proxyGuardConfig?.previousSecrets,
+    windowMs: proxyGuardConfig?.windowMs,
+    allowedOrigins: proxyGuardConfig?.allowedOrigins,
+    maxBodyBytes: proxyGuardConfig?.maxBodyBytes,
+    nonceStore,
+    skipPaths
+  }));
+  serverLogger.info(`\u2713 Proxy-guard enabled (mode: ${mode})`);
+}
 function registerHealthCheckEndpoint(app, config) {
   const healthCheckConfig = config?.healthCheck ?? {};
   const healthCheckEnabled = healthCheckConfig.enabled !== false;
@@ -1150,12 +1496,17 @@ async function registerSSEEndpoint(app, config) {
       serverLogger.info(`\u2713 SSE token endpoint registered at POST ${tokenPath}`);
     }
   }
+  const transport = await wireEventRouterCache(config.events, {
+    multiInstance: eventsConfig.multiInstance,
+    channelPrefix: eventsConfig.channelPrefix
+  });
   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
+      auth: !!authConfig?.enabled,
+      transport
     });
   }
 }
@@ -1890,6 +2241,10 @@ async function initializeWebSocket(server, app, config) {
     });
     if (debug) serverLogger.info(`\u2713 WS token endpoint registered at POST ${tokenPath}`);
   }
+  await wireEventRouterCache(wsRouter, {
+    multiInstance: wsConfig.multiInstance,
+    channelPrefix: wsConfig.channelPrefix
+  });
   return await attachWSHandler(server, wsRouter, wsConfig, tokenManager);
 }
 function logMiddlewareOrder(config) {
@@ -1961,6 +2316,7 @@ function createShutdownHandler(server, config, shutdownState, wsCleanup) {
       await closeInfrastructure(closeDatabase, "Database", TIMEOUTS.DATABASE_CLOSE);
     }
     if (infraConfig.redis) {
+      await closeEventTransport();
       await closeInfrastructure(closeCache, "Redis", TIMEOUTS.REDIS_CLOSE);
     }
     serverLogger.info("Server shutdown completed");
@@ -2111,6 +2467,7 @@ async function cleanupOnFailure(config) {
       await closeInfrastructure(closeDatabase, "Database", TIMEOUTS.DATABASE_CLOSE);
     }
     if (infraConfig.redis) {
+      await closeEventTransport();
       await closeInfrastructure(closeCache, "Redis", TIMEOUTS.REDIS_CLOSE);
     }
     resetShutdownManager();
@@ -2179,6 +2536,13 @@ var ServerConfigBuilder = class {
     this.config.middlewares = middlewares;
     return this;
   }
+  /**
+   * Configure proxy-guard (verify trusted-proxy signature + origin → clientType)
+   */
+  proxyGuard(proxyGuard) {
+    this.config.proxyGuard = proxyGuard;
+    return this;
+  }
   /**
    * Register define-route based router
    *