@spfn/core 0.2.0-beta.6 → 0.2.0-beta.64

package/dist/event/sse/index.js

@@ -1,19 +1,97 @@
 import { streamSSE } from 'hono/streaming';
 import { logger } from '@spfn/core/logger';
+import { randomBytes, createHash } from 'crypto';
+
+// src/event/sse/handler.ts
+
+// 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");
-function createSSEHandler(router, config = {}) {
+var frameCache = /* @__PURE__ */ new WeakMap();
+function serializeFrame(eventName, payload) {
+  if (payload === null || typeof payload !== "object") {
+    return JSON.stringify({ event: eventName, data: payload });
+  }
+  let byEvent = frameCache.get(payload);
+  if (!byEvent) {
+    byEvent = /* @__PURE__ */ new Map();
+    frameCache.set(payload, byEvent);
+  }
+  let serialized = byEvent.get(eventName);
+  if (serialized === void 0) {
+    serialized = JSON.stringify({ event: eventName, data: payload });
+    byEvent.set(eventName, serialized);
+  }
+  return serialized;
+}
+var DEFAULT_MAX_QUEUE = 1e3;
+function createSSEHandler(router, config = {}, tokenManager) {
   const {
-    pingInterval = 3e4
-    // headers: customHeaders = {},  // Reserved for future use
+    // 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 eventsParam = c.req.query("events");
-    if (!eventsParam) {
+    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 requestedEvents = eventsParam.split(",").map((e) => e.trim());
     const validEventNames = router.eventNames;
     const invalidEvents = requestedEvents.filter((e) => !validEventNames.includes(e));
     if (invalidEvents.length > 0) {
@@ -23,62 +101,94 @@ function createSSEHandler(router, config = {}) {
         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: requestedEvents,
+      events: allowedEvents,
+      subject: subject || void 0,
       clientIp: c.req.header("x-forwarded-for") || c.req.header("x-real-ip")
     });
+    c.header("X-Accel-Buffering", "no");
     return streamSSE(c, async (stream) => {
       const unsubscribes = [];
       let messageId = 0;
-      for (const eventName of requestedEvents) {
+      let connectionDead = false;
+      let pingTimer;
+      let writer;
+      let onClosed;
+      const cleanup = (reason) => {
+        if (connectionDead) return;
+        connectionDead = true;
+        clearInterval(pingTimer);
+        unsubscribes.forEach((fn) => fn());
+        writer?.close();
+        onClosed?.();
+        sseLogger.info("SSE dead connection cleaned up", {
+          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) {
           continue;
         }
         const unsubscribe = eventDef.subscribe((payload) => {
+          if (connectionDead) return;
+          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({
+          writer.enqueue({
             id: String(messageId),
             event: eventName,
-            data: JSON.stringify(message)
+            data: serializeFrame(eventName, payload)
           });
         });
         unsubscribes.push(unsubscribe);
       }
       sseLogger.info("SSE connection established", {
-        events: requestedEvents,
+        events: allowedEvents,
         subscriptionCount: unsubscribes.length
       });
-      await stream.writeSSE({
-        event: "connected",
-        data: JSON.stringify({
-          subscribedEvents: requestedEvents,
-          timestamp: Date.now()
-        })
-      });
-      const pingTimer = setInterval(() => {
-        void stream.writeSSE({
+      pingTimer = setInterval(() => {
+        if (connectionDead) return;
+        writer.enqueue({
           event: "ping",
           data: JSON.stringify({ timestamp: Date.now() })
         });
       }, pingInterval);
       const abortSignal = c.req.raw.signal;
-      while (!abortSignal.aborted) {
-        await stream.sleep(pingInterval);
+      if (!abortSignal.aborted && !connectionDead) {
+        await new Promise((resolve) => {
+          const onAbort = () => resolve();
+          abortSignal.addEventListener("abort", onAbort, { once: true });
+          onClosed = () => {
+            abortSignal.removeEventListener("abort", onAbort);
+            resolve();
+          };
+        });
       }
-      clearInterval(pingTimer);
-      unsubscribes.forEach((fn) => fn());
-      sseLogger.info("SSE connection closed", {
-        events: requestedEvents
-      });
+      cleanup();
     }, async (err) => {
       sseLogger.error("SSE stream error", {
         error: err.message
@@ -86,7 +196,136 @@ function createSSEHandler(router, config = {}) {
     });
   };
 }
+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;
+}
+function hashToken(token) {
+  return createHash("sha256").update(token).digest("hex");
+}
+var InMemoryTokenStore = class {
+  tokens = /* @__PURE__ */ new Map();
+  async set(token, data) {
+    this.tokens.set(hashToken(token), data);
+  }
+  async consume(token) {
+    const key = hashToken(token);
+    const data = this.tokens.get(key);
+    if (!data) {
+      return null;
+    }
+    this.tokens.delete(key);
+    return data;
+  }
+  async cleanup() {
+    const now = Date.now();
+    for (const [key, data] of this.tokens) {
+      if (data.expiresAt <= now) {
+        this.tokens.delete(key);
+      }
+    }
+  }
+};
+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 + hashToken(token),
+      JSON.stringify(data),
+      "EX",
+      ttlSeconds
+    );
+  }
+  async consume(token) {
+    const key = this.prefix + hashToken(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, {
+      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;
+    }
+  }
+};
 
-export { createSSEHandler };
+export { CacheTokenStore, SSETokenManager, createSSEHandler };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/event/sse/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../src/event/sse/handler.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["/**\n * SSE Handler for Hono\n *\n * Creates SSE stream endpoint for event subscription\n *\n * @example\n * ```typescript\n * import { Hono } from 'hono';\n * import { createSSEHandler } from '@spfn/core/event/sse';\n * import { eventRouter } from './events';\n *\n * const app = new Hono();\n *\n * // GET /events/stream?events=userCreated,orderPlaced\n * app.get('/events/stream', createSSEHandler(eventRouter));\n * ```\n */\n\nimport type { Context } from 'hono';\nimport { streamSSE } from 'hono/streaming';\nimport { logger } from '@spfn/core/logger';\nimport type { EventRouterDef, InferEventNames } from '../router';\nimport type { SSEHandlerConfig } from './types';\n\nconst sseLogger = logger.child('@spfn/core:sse');\n\n/**\n * Create SSE handler for Hono\n *\n * Query parameters:\n * - events: Comma-separated list of event names to subscribe\n *\n * @example\n * ```typescript\n * app.get('/events/stream', createSSEHandler(eventRouter, {\n *     pingInterval: 30000,\n * }));\n * ```\n */\nexport function createSSEHandler<TRouter extends EventRouterDef<any>>(\n    router: TRouter,\n    config: SSEHandlerConfig = {}\n)\n{\n    const {\n        pingInterval = 30000,\n        // headers: customHeaders = {},  // Reserved for future use\n    } = config;\n\n    return async (c: Context) =>\n    {\n        // Parse events from query parameter\n        const eventsParam = c.req.query('events');\n\n        if (!eventsParam)\n        {\n            return c.json({ error: 'Missing events parameter' }, 400);\n        }\n\n        const requestedEvents = eventsParam.split(',').map(e => e.trim());\n\n        // Validate event names\n        const validEventNames = router.eventNames as string[];\n        const invalidEvents = requestedEvents.filter(e => !validEventNames.includes(e));\n\n        if (invalidEvents.length > 0)\n        {\n            return c.json({\n                error: 'Invalid event names',\n                invalidEvents,\n                validEvents: validEventNames,\n            }, 400);\n        }\n\n        sseLogger.debug('SSE connection requested', {\n            events: requestedEvents,\n            clientIp: c.req.header('x-forwarded-for') || c.req.header('x-real-ip'),\n        });\n\n        // Start SSE stream\n        return streamSSE(c, async (stream) =>\n        {\n            const unsubscribes: (() => void)[] = [];\n            let messageId = 0;\n\n            // Subscribe to each requested event\n            for (const eventName of requestedEvents as InferEventNames<TRouter>[])\n            {\n                const eventDef = router.events[eventName];\n\n                if (!eventDef)\n                {\n                    continue;\n                }\n\n                const unsubscribe = eventDef.subscribe((payload: unknown) =>\n                {\n                    messageId++;\n\n                    const message = {\n                        event: eventName,\n                        data: payload,\n                    };\n\n                    sseLogger.debug('SSE sending event', {\n                        event: eventName,\n                        messageId,\n                    });\n\n                    // Fire-and-forget in sync callback\n                    void stream.writeSSE({\n                        id: String(messageId),\n                        event: eventName as string,\n                        data: JSON.stringify(message),\n                    });\n                });\n\n                unsubscribes.push(unsubscribe);\n            }\n\n            sseLogger.info('SSE connection established', {\n                events: requestedEvents,\n                subscriptionCount: unsubscribes.length,\n            });\n\n            // Send initial connection message\n            await stream.writeSSE({\n                event: 'connected',\n                data: JSON.stringify({\n                    subscribedEvents: requestedEvents,\n                    timestamp: Date.now(),\n                }),\n            });\n\n            // Keep-alive ping\n            const pingTimer = setInterval(() =>\n            {\n                // Fire-and-forget in sync callback\n                void stream.writeSSE({\n                    event: 'ping',\n                    data: JSON.stringify({ timestamp: Date.now() }),\n                });\n            }, pingInterval);\n\n            // Wait for client disconnect using abort signal\n            const abortSignal = c.req.raw.signal;\n\n            while (!abortSignal.aborted)\n            {\n                await stream.sleep(pingInterval);\n            }\n\n            // Cleanup\n            clearInterval(pingTimer);\n            unsubscribes.forEach(fn => fn());\n\n            sseLogger.info('SSE connection closed', {\n                events: requestedEvents,\n            });\n        }, async (err: Error) =>\n        {\n            sseLogger.error('SSE stream error', {\n                error: err.message,\n            });\n        });\n    };\n}\n\n"]}
+{"version":3,"sources":["../../../src/event/sse/bounded-writer.ts","../../../src/event/sse/handler.ts","../../../src/event/sse/token-manager.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["/**\n * Bounded SSE outbound writer\n *\n * Serializes writes to one SSE stream through a single drain loop that `await`s\n * each `writeSSE` — so a slow client applies real backpressure instead of letting\n * frames pile up unbounded in memory (OOM under a fast producer + slow consumer).\n *\n * The queue is per-connection, so a slow stream never blocks other connections.\n * When the queue exceeds `maxQueue`, the connection is closed (via `onClose`)\n * rather than silently dropping frames — dropping a chunk would corrupt an\n * ordered token/chat stream; the client reconnects and re-fetches instead.\n */\n\n/** A frame to write to the SSE stream (subset of Hono's SSEMessage). */\nexport interface SSEFrame\n{\n    data: string;\n    event?: string;\n    id?: string;\n}\n\n/** Minimal stream surface this writer needs (Hono's SSEStreamingApi satisfies it). */\nexport interface SSEWritable\n{\n    writeSSE(message: SSEFrame): Promise<void>;\n}\n\nexport interface BoundedWriter\n{\n    /** Queue a frame for delivery; closes the connection if the queue overflows. */\n    enqueue(frame: SSEFrame): void;\n\n    /** Stop draining and drop any queued frames (called on connection cleanup). */\n    close(): void;\n\n    /** Current queue depth (for tests/diagnostics). */\n    readonly queued: number;\n}\n\n/**\n * Create a bounded, backpressure-aware writer for one SSE stream.\n *\n * @param stream   the SSE stream (`writeSSE` returns a promise that resolves when\n *                 the socket has drained — that is what gives us backpressure)\n * @param maxQueue max frames buffered before the connection is closed\n * @param onClose  called once when the writer closes the connection (overflow or\n *                 a write error); the caller cleans up and logs\n */\nexport function createBoundedWriter(\n    stream: SSEWritable,\n    maxQueue: number,\n    onClose: (reason: string) => void,\n): BoundedWriter\n{\n    const pending: SSEFrame[] = [];\n    let flushing = false;\n    let closed = false;\n\n    const flush = async (): Promise<void> =>\n    {\n        if (flushing || closed)\n        {\n            return;\n        }\n\n        flushing = true;\n\n        while (pending.length > 0 && !closed)\n        {\n            const frame = pending.shift() as SSEFrame;\n            try\n            {\n                await stream.writeSSE(frame);\n            }\n            catch (err)\n            {\n                flushing = false;\n                onClose(err instanceof Error ? err.message : String(err));\n\n                return;\n            }\n        }\n\n        flushing = false;\n    };\n\n    return {\n        enqueue(frame: SSEFrame): void\n        {\n            if (closed)\n            {\n                return;\n            }\n\n            pending.push(frame);\n\n            // Slow consumer: the drain loop can't keep up, so the queue grew past\n            // the bound. Close rather than buffer unboundedly or drop silently.\n            if (pending.length > maxQueue)\n            {\n                onClose('outbound queue overflow (slow consumer)');\n\n                return;\n            }\n\n            void flush();\n        },\n\n        close(): void\n        {\n            closed = true;\n            pending.length = 0;\n        },\n\n        get queued(): number\n        {\n            return pending.length;\n        },\n    };\n}\n","/**\n * SSE Handler for Hono\n *\n * Creates SSE stream endpoint for event subscription\n *\n * @example\n * ```typescript\n * import { Hono } from 'hono';\n * import { createSSEHandler } from '@spfn/core/event/sse';\n * import { eventRouter } from './events';\n *\n * const app = new Hono();\n *\n * // GET /events/stream?events=userCreated,orderPlaced\n * app.get('/events/stream', createSSEHandler(eventRouter));\n * ```\n */\n\nimport type { Context } from 'hono';\nimport { streamSSE } from 'hono/streaming';\nimport { logger } from '@spfn/core/logger';\nimport type { EventRouterDef, InferEventNames } from '../router';\nimport type { SSEHandlerConfig, SSEHandlerAuthConfig } from './types';\nimport type { SSETokenManager } from './token-manager';\nimport { createBoundedWriter } from './bounded-writer';\n\nconst sseLogger = logger.child('@spfn/core:sse');\n\n/**\n * Serialize a fan-out frame once per (event, payload).\n *\n * One `emit` delivers the same payload object to every subscribed connection, so\n * without memoization each connection re-`JSON.stringify`s the identical payload\n * — O(N) for N subscribers on a hot broadcast. Keyed by the payload object\n * (WeakMap → auto-GC after the emit); primitives are cheap to stringify directly.\n */\nconst frameCache = new WeakMap<object, Map<string, string>>();\n\nexport function serializeFrame(eventName: string, payload: unknown): string\n{\n    if (payload === null || typeof payload !== 'object')\n    {\n        return JSON.stringify({ event: eventName, data: payload });\n    }\n\n    let byEvent = frameCache.get(payload);\n    if (!byEvent)\n    {\n        byEvent = new Map<string, string>();\n        frameCache.set(payload, byEvent);\n    }\n\n    let serialized = byEvent.get(eventName);\n    if (serialized === undefined)\n    {\n        serialized = JSON.stringify({ event: eventName, data: payload });\n        byEvent.set(eventName, serialized);\n    }\n\n    return serialized;\n}\n\n/** Default outbound queue cap per connection before a slow consumer is dropped. */\nconst DEFAULT_MAX_QUEUE = 1000;\n\n// Extend Hono context with SSE subject\ndeclare module 'hono'\n{\n    interface ContextVariableMap\n    {\n        sseSubject?: string;\n    }\n}\n\n/**\n * Create SSE handler for Hono\n *\n * Query parameters:\n * - events: Comma-separated list of event names to subscribe\n * - token: One-time auth token (when auth is enabled)\n *\n * @example\n * ```typescript\n * app.get('/events/stream', createSSEHandler(eventRouter, {\n *     pingInterval: 30000,\n * }));\n * ```\n */\nexport function createSSEHandler<TRouter extends EventRouterDef<any>>(\n    router: TRouter,\n    config: SSEHandlerConfig = {},\n    tokenManager?: SSETokenManager,\n)\n{\n    const {\n        // 10s — keep-alive가 중간 프록시(GCP LB/nginx)의 idle 타임아웃(흔히 ~15-30s)보다 자주 와야\n        // 첫 ping 전 침묵 구간에 연결이 끊기지 않는다. 30s 기본은 idle 타임아웃보다 길어 SSE가\n        // 데이터 없는 동안 끊기던 문제가 있었다.\n        pingInterval = 10000,\n        auth: authConfig,\n        maxQueue = DEFAULT_MAX_QUEUE,\n    } = config;\n\n    return async (c: Context) =>\n    {\n        // ── 1. Token Authentication ──\n        const subject = await authenticateToken(c, tokenManager);\n        if (subject === false)\n        {\n            return c.json({ error: 'Missing token parameter' }, 401);\n        }\n        if (subject === null)\n        {\n            return c.json({ error: 'Invalid or expired token' }, 401);\n        }\n        if (subject)\n        {\n            c.set('sseSubject', subject);\n        }\n\n        // ── 2. Parse events from query parameter ──\n        const requestedEvents = parseRequestedEvents(c);\n        if (!requestedEvents)\n        {\n            return c.json({ error: 'Missing events parameter' }, 400);\n        }\n\n        // ── 3. Validate event names ──\n        const validEventNames = router.eventNames as string[];\n        const invalidEvents = requestedEvents.filter(e => !validEventNames.includes(e));\n\n        if (invalidEvents.length > 0)\n        {\n            return c.json({\n                error: 'Invalid event names',\n                invalidEvents,\n                validEvents: validEventNames,\n            }, 400);\n        }\n\n        // ── 4. Subscription Authorization ──\n        const allowedEvents = await authorizeEvents(subject, requestedEvents, authConfig);\n        if (allowedEvents === null)\n        {\n            return c.json({ error: 'Not authorized for any requested events' }, 403);\n        }\n\n        sseLogger.debug('SSE connection requested', {\n            events: allowedEvents,\n            subject: subject || undefined,\n            clientIp: c.req.header('x-forwarded-for') || c.req.header('x-real-ip'),\n        });\n\n        // ── 5. SSE Stream ──\n        c.header('X-Accel-Buffering', 'no');\n\n        return streamSSE(c, async (stream) =>\n        {\n            const unsubscribes: (() => void)[] = [];\n            let messageId = 0;\n            let connectionDead = false;\n            let pingTimer: ReturnType<typeof setInterval>;\n            let writer: ReturnType<typeof createBoundedWriter>;\n            // Resolves the disconnect wait below when the connection is closed\n            // server-side (overflow/error), so teardown doesn't wait for the loop.\n            let onClosed: (() => void) | undefined;\n\n            const cleanup = (reason?: string) =>\n            {\n                if (connectionDead) return;\n                connectionDead = true;\n                clearInterval(pingTimer);\n                unsubscribes.forEach(fn => fn());\n                writer?.close();\n                onClosed?.();\n                sseLogger.info('SSE dead connection cleaned up', {\n                    events: allowedEvents,\n                    reason,\n                });\n            };\n\n            // All writes go through one bounded, backpressure-aware drain loop so a\n            // slow client can't pile frames up in memory (it's closed on overflow).\n            writer = createBoundedWriter(stream, maxQueue, (reason) =>\n            {\n                sseLogger.warn('SSE connection closed', { events: allowedEvents, reason });\n                cleanup(reason);\n            });\n\n            // Send initial connection message (first frame in the queue).\n            writer.enqueue({\n                event: 'connected',\n                data: JSON.stringify({\n                    subscribedEvents: allowedEvents,\n                    timestamp: Date.now(),\n                }),\n            });\n\n            for (const eventName of allowedEvents as InferEventNames<TRouter>[])\n            {\n                const eventDef = router.events[eventName];\n\n                if (!eventDef)\n                {\n                    continue;\n                }\n\n                const unsubscribe = eventDef.subscribe((payload: unknown) =>\n                {\n                    if (connectionDead) return;\n\n                    // ── Payload Filtering ──\n                    if (subject && authConfig?.filter?.[eventName as string])\n                    {\n                        if (!authConfig.filter[eventName as string](subject, payload))\n                        {\n                            return;\n                        }\n                    }\n\n                    messageId++;\n\n                    sseLogger.debug('SSE sending event', {\n                        event: eventName,\n                        messageId,\n                    });\n\n                    writer.enqueue({\n                        id: String(messageId),\n                        event: eventName as string,\n                        data: serializeFrame(eventName as string, payload),\n                    });\n                });\n\n                unsubscribes.push(unsubscribe);\n            }\n\n            sseLogger.info('SSE connection established', {\n                events: allowedEvents,\n                subscriptionCount: unsubscribes.length,\n            });\n\n            // Keep-alive ping\n            pingTimer = setInterval(() =>\n            {\n                if (connectionDead) return;\n\n                writer.enqueue({\n                    event: 'ping',\n                    data: JSON.stringify({ timestamp: Date.now() }),\n                });\n            }, pingInterval);\n\n            // Wait for client disconnect (abort) or a server-side close. Waiting on\n            // the abort event instead of polling sleep(pingInterval) means a dropped\n            // client is torn down immediately, not up to one ping interval later.\n            const abortSignal = c.req.raw.signal;\n\n            if (!abortSignal.aborted && !connectionDead)\n            {\n                await new Promise<void>((resolve) =>\n                {\n                    const onAbort = () => resolve();\n                    abortSignal.addEventListener('abort', onAbort, { once: true });\n                    // Server-side close (cleanup) resolves the wait and drops the listener.\n                    onClosed = () =>\n                    {\n                        abortSignal.removeEventListener('abort', onAbort);\n                        resolve();\n                    };\n                });\n            }\n\n            // Cleanup (normal disconnect path; idempotent if already closed)\n            cleanup();\n        }, async (err: Error) =>\n        {\n            sseLogger.error('SSE stream error', {\n                error: err.message,\n            });\n        });\n    };\n}\n\n// ============================================================================\n// Helper Functions\n// ============================================================================\n\n/**\n * Authenticate via one-time token\n * @returns subject string if authenticated, undefined if no auth required,\n *          false if token missing, null if token invalid/expired\n */\nasync function authenticateToken(\n    c: Context,\n    tokenManager?: SSETokenManager,\n): Promise<string | undefined | false | null>\n{\n    if (!tokenManager)\n    {\n        return undefined;\n    }\n\n    const token = c.req.query('token');\n    if (!token)\n    {\n        return false;\n    }\n\n    return await tokenManager.verify(token);\n}\n\n/**\n * Parse requested events from query parameter\n */\nfunction parseRequestedEvents(c: Context): string[] | null\n{\n    const eventsParam = c.req.query('events');\n    if (!eventsParam)\n    {\n        return null;\n    }\n\n    return eventsParam.split(',').map(e => e.trim());\n}\n\n/**\n * Authorize event subscription via auth hook\n * @returns allowed events array, or null if rejected\n */\nasync function authorizeEvents(\n    subject: string | undefined,\n    requestedEvents: string[],\n    authConfig?: SSEHandlerAuthConfig,\n): Promise<string[] | null>\n{\n    if (!subject || !authConfig?.authorize)\n    {\n        return requestedEvents;\n    }\n\n    const allowed = await authConfig.authorize(subject, requestedEvents);\n\n    if (allowed.length === 0)\n    {\n        return null;\n    }\n\n    return allowed;\n}\n","/**\n * SSE Token Manager\n *\n * Auth-agnostic token issuance and verification for SSE connections.\n * Issues one-time-use tokens with TTL for Token Exchange pattern.\n *\n * @example\n * ```typescript\n * const manager = new SSETokenManager({ ttl: 30000 });\n *\n * // Issue token for authenticated user\n * const token = await manager.issue('user-123');\n *\n * // Verify and consume token (one-time use)\n * const subject = await manager.verify(token); // 'user-123'\n * const again = await manager.verify(token);   // null (already consumed)\n *\n * // Cleanup on shutdown\n * manager.destroy();\n * ```\n */\n\nimport { randomBytes, createHash } from 'crypto';\n\n/**\n * Hash a token for storage. The raw token is a bearer secret — storing it at rest\n * (e.g. as a Redis key/value) means a store dump hands out live tokens. We persist\n * only sha256(token) and look up by the same hash; the raw token exists only in\n * transit and in the issue() return value.\n */\nfunction hashToken(token: string): string\n{\n    return createHash('sha256').update(token).digest('hex');\n}\n\n/**\n * Minimal cache client interface (compatible with ioredis Redis | Cluster)\n */\ntype CacheClient = {\n    set(key: string, value: string, ...args: any[]): Promise<any>;\n    getdel?(key: string): Promise<string | null>;\n    get(key: string): Promise<string | null>;\n    del(...keys: string[]): Promise<number>;\n};\n\n// ============================================================================\n// Types\n// ============================================================================\n\n/**\n * Stored SSE token data\n */\nexport interface SSEToken\n{\n    subject: string;\n    expiresAt: number;\n}\n\n/**\n * Token storage interface\n *\n * Implement this for custom storage backends (e.g., Redis for multi-instance).\n */\nexport interface SSETokenStore\n{\n    /** Store a token */\n    set(token: string, data: SSEToken): Promise<void>;\n\n    /** Get and delete a token (one-time use) */\n    consume(token: string): Promise<SSEToken | null>;\n\n    /** Remove expired tokens */\n    cleanup(): Promise<void>;\n}\n\n/**\n * SSETokenManager configuration\n */\nexport interface SSETokenManagerConfig\n{\n    /**\n     * Token time-to-live in milliseconds\n     * @default 30000\n     */\n    ttl?: number;\n\n    /**\n     * Custom token store (default: in-memory Map)\n     */\n    store?: SSETokenStore;\n\n    /**\n     * Cleanup interval in milliseconds\n     * @default 60000\n     */\n    cleanupInterval?: number;\n}\n\n// ============================================================================\n// InMemoryTokenStore\n// ============================================================================\n\nclass InMemoryTokenStore implements SSETokenStore\n{\n    private tokens = new Map<string, SSEToken>();\n\n    async set(token: string, data: SSEToken): Promise<void>\n    {\n        this.tokens.set(hashToken(token), data);\n    }\n\n    async consume(token: string): Promise<SSEToken | null>\n    {\n        const key = hashToken(token);\n        const data = this.tokens.get(key);\n        if (!data)\n        {\n            return null;\n        }\n\n        this.tokens.delete(key);\n\n        return data;\n    }\n\n    async cleanup(): Promise<void>\n    {\n        const now = Date.now();\n\n        for (const [key, data] of this.tokens)\n        {\n            if (data.expiresAt <= now)\n            {\n                this.tokens.delete(key);\n            }\n        }\n    }\n}\n\n// ============================================================================\n// CacheTokenStore (Redis/Valkey)\n// ============================================================================\n\n/**\n * Redis/Valkey-backed token store for multi-instance deployments.\n *\n * Uses SET EX for automatic TTL expiry and GETDEL for atomic one-time consumption.\n * No cleanup needed — Redis handles expiration automatically.\n *\n * @example\n * ```typescript\n * import { getCache } from '@spfn/core/cache';\n *\n * const cache = getCache();\n * if (cache) {\n *     const store = new CacheTokenStore(cache);\n *     const manager = new SSETokenManager({ store });\n * }\n * ```\n */\nexport class CacheTokenStore implements SSETokenStore\n{\n    private prefix = 'sse:token:';\n\n    constructor(private cache: CacheClient) \n    {}\n\n    async set(token: string, data: SSEToken): Promise<void>\n    {\n        const ttlSeconds = Math.max(1, Math.ceil((data.expiresAt - Date.now()) / 1000));\n        await this.cache.set(\n            this.prefix + hashToken(token),\n            JSON.stringify(data),\n            'EX',\n            ttlSeconds,\n        );\n    }\n\n    async consume(token: string): Promise<SSEToken | null>\n    {\n        const key = this.prefix + hashToken(token);\n\n        // GETDEL (Redis 6.2+) for atomic consume, fallback to GET+DEL\n        let raw: string | null = null;\n\n        if (this.cache.getdel)\n        {\n            raw = await this.cache.getdel(key);\n        }\n        else\n        {\n            raw = await this.cache.get(key);\n            if (raw)\n            {\n                await this.cache.del(key);\n            }\n        }\n\n        if (!raw)\n        {\n            return null;\n        }\n\n        return JSON.parse(raw) as SSEToken;\n    }\n\n    async cleanup(): Promise<void>\n    {\n        // No-op: Redis TTL handles expiration automatically\n    }\n}\n\n// ============================================================================\n// SSETokenManager\n// ============================================================================\n\nexport class SSETokenManager\n{\n    private store: SSETokenStore;\n    private ttl: number;\n    private cleanupTimer: ReturnType<typeof setInterval> | null = null;\n\n    constructor(config?: SSETokenManagerConfig)\n    {\n        this.ttl = config?.ttl ?? 30000;\n        this.store = config?.store ?? new InMemoryTokenStore();\n\n        const cleanupInterval = config?.cleanupInterval ?? 60000;\n        this.cleanupTimer = setInterval(() => void this.store.cleanup(), cleanupInterval);\n        this.cleanupTimer.unref();\n    }\n\n    /**\n     * Issue a new one-time-use token for the given subject\n     */\n    async issue(subject: string): Promise<string>\n    {\n        const token = randomBytes(32).toString('hex');\n\n        // The store keys by sha256(token); the raw token is never persisted.\n        await this.store.set(token, {\n            subject,\n            expiresAt: Date.now() + this.ttl,\n        });\n\n        return token;\n    }\n\n    /**\n     * Verify and consume a token\n     * @returns subject string if valid, null if invalid/expired/already consumed\n     */\n    async verify(token: string): Promise<string | null>\n    {\n        const data = await this.store.consume(token);\n\n        if (!data || data.expiresAt <= Date.now())\n        {\n            return null;\n        }\n\n        return data.subject;\n    }\n\n    /**\n     * Cleanup timer and resources\n     */\n    destroy(): void\n    {\n        if (this.cleanupTimer)\n        {\n            clearInterval(this.cleanupTimer);\n            this.cleanupTimer = null;\n        }\n    }\n}\n"]}

package/dist/event/ws/client.d.ts

@@ -0,0 +1,59 @@
+import { W as WSRouterDef, k as WSSubscribeOptions, l as WSUnsubscribe, i as WSConnectionState, h as WSClientConfig } from '../../types-DVjf37yO.js';
+import 'hono';
+import '../../token-manager-jKD_EsSE.js';
+import '@sinclair/typebox';
+
+/**
+ * WebSocket Client
+ *
+ * Type-safe browser WebSocket wrapper for event subscription and bidirectional messaging.
+ *
+ * @example
+ * ```typescript
+ * import { createWSClient } from '@spfn/core/event/ws/client';
+ * import type { WSRouter } from '@/server/ws';
+ *
+ * const client = createWSClient<WSRouter>();
+ *
+ * const unsubscribe = client.subscribe({
+ *     events: ['userUpdated', 'notification'],
+ *     handlers: {
+ *         userUpdated: ({ userId }) => console.log(userId),
+ *         notification: ({ message }) => console.log(message),
+ *     },
+ *     onOpen: () => console.log('connected'),
+ * });
+ *
+ * // Send message to server
+ * client.send('ping', {});
+ *
+ * // Cleanup
+ * unsubscribe();
+ * ```
+ */
+
+interface WSClient<TRouter extends WSRouterDef<any, any>> {
+    /**
+     * Subscribe to server-push events
+     * Returns an unsubscribe function
+     */
+    subscribe(options: WSSubscribeOptions<TRouter>): WSUnsubscribe;
+    /**
+     * Send a message to the server
+     */
+    send<TType extends string>(type: TType, payload: unknown): void;
+    /**
+     * Get current connection state
+     */
+    getState(): WSConnectionState;
+    /**
+     * Close the connection permanently
+     */
+    close(): void;
+}
+/**
+ * Create a type-safe WebSocket client
+ */
+declare function createWSClient<TRouter extends WSRouterDef<any, any>>(config?: WSClientConfig): WSClient<TRouter>;
+
+export { type WSClient, createWSClient };