@spfn/core 0.2.0-beta.45 → 0.2.0-beta.47

package/dist/event/ws/index.js

@@ -0,0 +1,213 @@
+import { logger } from '@spfn/core/logger';
+
+// src/event/ws/handler.ts
+var wsLogger = logger.child("@spfn/core:ws");
+async function attachWSHandler(server, router, config = {}, tokenManager) {
+  const WebSocketServer = await loadWSServer();
+  const {
+    pingInterval = 3e4,
+    path = "/ws",
+    auth: authConfig
+  } = config;
+  if (authConfig?.enabled && !tokenManager) {
+    throw new Error(
+      "WebSocket auth.enabled=true requires a tokenManager. Pass tokenManager or use .websockets(router, { auth: { enabled: true } }) via startServer."
+    );
+  }
+  const wss = new WebSocketServer({ server, path });
+  const clients = /* @__PURE__ */ new Set();
+  wss.on("connection", (ws, req) => {
+    clients.add(ws);
+    ws.on("close", () => clients.delete(ws));
+    handleConnection(ws, req, router, authConfig, tokenManager, pingInterval).catch((err) => {
+      wsLogger.error("WebSocket connection handler error", err);
+      if (ws.readyState === 1) ws.close(1011, "Internal server error");
+    });
+  });
+  wss.on("error", (err) => {
+    wsLogger.error("WebSocket server error", err);
+  });
+  wsLogger.info(`\u2713 WebSocket endpoint registered at ${path}`, {
+    events: router.eventNames,
+    auth: !!authConfig?.enabled
+  });
+  return () => new Promise((resolve, reject) => {
+    for (const client of clients) {
+      client.close(1001, "Server shutting down");
+    }
+    clients.clear();
+    wss.close((err) => {
+      if (err) reject(err);
+      else resolve();
+    });
+  });
+}
+async function handleConnection(ws, req, router, authConfig, tokenManager, pingInterval) {
+  let pingTimer;
+  let connectionUnsubscribes = [];
+  let subscribedEvents = [];
+  ws.on("close", () => {
+    clearInterval(pingTimer);
+    connectionUnsubscribes.forEach((fn) => fn());
+    if (subscribedEvents.length > 0)
+      wsLogger.info("WebSocket connection closed", { events: subscribedEvents });
+  });
+  const url = parseURL(req);
+  if (!url) {
+    ws.close(1002, "Invalid request URL");
+    return;
+  }
+  const subject = await resolveSubject(url, authConfig?.enabled ? tokenManager : void 0);
+  if (subject === false) {
+    ws.close(4001, "Missing token");
+    return;
+  }
+  if (subject === null) {
+    ws.close(4001, "Invalid or expired token");
+    return;
+  }
+  const requestedEvents = parseRequestedEvents(url, router.eventNames);
+  if (requestedEvents.length === 0) {
+    ws.close(4e3, "No valid event names specified");
+    return;
+  }
+  const allowedEvents = await resolveAllowedEvents(subject, requestedEvents, authConfig);
+  if (allowedEvents === null) {
+    ws.close(4003, "Not authorized for any requested events");
+    return;
+  }
+  subscribedEvents = allowedEvents;
+  wsLogger.info("WebSocket connection established", {
+    events: allowedEvents,
+    subject: subject ?? void 0
+  });
+  const connection = createConnection(ws);
+  connectionUnsubscribes = subscribeEvents(ws, router, allowedEvents, subject, authConfig);
+  if (ws.readyState !== 1) {
+    connectionUnsubscribes.forEach((fn) => fn());
+    connectionUnsubscribes = [];
+    return;
+  }
+  ws.on("message", (data) => {
+    onClientMessage(data, router, connection, subject).catch((err) => wsLogger.error("Unhandled message error", err));
+  });
+  if (pingInterval > 0) {
+    pingTimer = setInterval(() => {
+      if (ws.readyState === 1) ws.ping();
+    }, pingInterval);
+  }
+  connection.send("__connected", {
+    subscribedEvents: allowedEvents,
+    timestamp: Date.now()
+  });
+}
+function parseURL(req) {
+  try {
+    return new URL(req.url ?? "/", "ws://localhost");
+  } catch {
+    return null;
+  }
+}
+async function resolveSubject(url, tokenManager) {
+  if (!tokenManager) {
+    return void 0;
+  }
+  const token = url.searchParams.get("token");
+  if (!token) {
+    return false;
+  }
+  return await tokenManager.verify(token);
+}
+function parseRequestedEvents(url, validEventNames) {
+  const eventsParam = url.searchParams.get("events");
+  if (!eventsParam) {
+    return [];
+  }
+  return eventsParam.split(",").map((e) => e.trim()).filter((e) => validEventNames.includes(e));
+}
+async function resolveAllowedEvents(subject, requestedEvents, authConfig) {
+  if (!subject || !authConfig?.authorize) {
+    return requestedEvents;
+  }
+  const allowed = await authConfig.authorize(subject, requestedEvents);
+  return allowed.length === 0 ? null : allowed;
+}
+function createConnection(ws) {
+  return {
+    send: (type, payload) => {
+      if (ws.readyState !== 1) return;
+      ws.send(JSON.stringify({ type, data: payload }));
+    },
+    close: (code, reason) => ws.close(code, reason)
+  };
+}
+function subscribeEvents(ws, router, allowedEvents, subject, authConfig) {
+  const unsubscribes = [];
+  for (const eventName of allowedEvents) {
+    const eventDef = router.events[eventName];
+    if (!eventDef) continue;
+    const unsubscribe = eventDef.subscribe((payload) => {
+      if (ws.readyState !== 1) return;
+      if (subject && authConfig?.filter?.[eventName]) {
+        if (!authConfig.filter[eventName](subject, payload)) return;
+      }
+      try {
+        ws.send(JSON.stringify({ type: eventName, data: payload }));
+      } catch {
+      }
+    });
+    unsubscribes.push(unsubscribe);
+  }
+  return unsubscribes;
+}
+async function onClientMessage(data, router, connection, subject) {
+  let message;
+  try {
+    message = JSON.parse(data.toString());
+  } catch {
+    return;
+  }
+  const { type, data: payload } = message;
+  if (!type) return;
+  const handler = router.messages[type];
+  if (!handler) return;
+  try {
+    await handler({ payload, subject, ws: connection });
+  } catch (err) {
+    wsLogger.error(`WebSocket message handler error: ${type}`, err);
+  }
+}
+async function loadWSServer() {
+  try {
+    const mod = await import('ws');
+    const WS = mod.default ?? mod;
+    const WSS = WS.WebSocketServer ?? WS.Server;
+    if (typeof WSS !== "function") {
+      throw new Error(
+        "WebSocketServer not found in ws module. Ensure ws@^8 is installed: pnpm add ws"
+      );
+    }
+    return WSS;
+  } catch (err) {
+    if (err instanceof Error && err.message.includes("WebSocketServer not found")) {
+      throw err;
+    }
+    throw new Error(
+      '@spfn/core WebSocket support requires the "ws" package.\nInstall it with: pnpm add ws'
+    );
+  }
+}
+
+// src/event/ws/index.ts
+function defineWSRouter(def) {
+  return {
+    events: def.events,
+    eventNames: Object.keys(def.events),
+    messages: def.messages ?? {},
+    _types: {}
+  };
+}
+
+export { attachWSHandler, defineWSRouter };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/event/ws/handler.ts","../../../src/event/ws/index.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["/**\n * WebSocket Handler\n *\n * Attaches a WebSocket server to an existing Node.js http.Server.\n * Handles authentication, event subscription, and client message routing.\n */\n\nimport type { Server } from 'node:http';\nimport type { EventDef } from '../types';\nimport type {\n    WSRouterDef,\n    WSHandlerConfig,\n    WSHandlerAuthConfig,\n    WSMessageHandlers,\n    WSRawConnection,\n} from './types';\nimport type { SSETokenManager } from '../sse/token-manager';\nimport { logger } from '@spfn/core/logger';\n\nconst wsLogger = logger.child('@spfn/core:ws');\n\n// ============================================================================\n// Public API\n// ============================================================================\n\n/**\n * Attach a WebSocket server to a Node.js http.Server\n *\n * @returns cleanup function that closes the WebSocket server\n */\nexport async function attachWSHandler<\n    TEvents extends Record<string, EventDef<any>>,\n    TMessages extends WSMessageHandlers\n>(\n    server: Server,\n    router: WSRouterDef<TEvents, TMessages>,\n    config: WSHandlerConfig & { path?: string } = {},\n    tokenManager?: SSETokenManager\n): Promise<() => Promise<void>>\n{\n    const WebSocketServer = await loadWSServer();\n\n    const {\n        pingInterval = 30000,\n        path = '/ws',\n        auth: authConfig,\n    } = config;\n\n    if (authConfig?.enabled && !tokenManager)\n    {\n        throw new Error(\n            'WebSocket auth.enabled=true requires a tokenManager. ' +\n            'Pass tokenManager or use .websockets(router, { auth: { enabled: true } }) via startServer.'\n        );\n    }\n\n    const wss = new WebSocketServer({ server, path });\n\n    // Track live connections for graceful shutdown\n    const clients = new Set<any>();\n\n    wss.on('connection', (ws: any, req: any) =>\n    {\n        clients.add(ws);\n        ws.on('close', () => clients.delete(ws));\n        handleConnection(ws, req, router, authConfig, tokenManager, pingInterval)\n            .catch((err: Error) =>\n            {\n                wsLogger.error('WebSocket connection handler error', err);\n                if (ws.readyState === 1) ws.close(1011, 'Internal server error');\n            });\n    });\n\n    wss.on('error', (err: Error) =>\n    {\n        wsLogger.error('WebSocket server error', err);\n    });\n\n    wsLogger.info(`✓ WebSocket endpoint registered at ${path}`, {\n        events: router.eventNames,\n        auth: !!authConfig?.enabled,\n    });\n\n    return () => new Promise<void>((resolve, reject) =>\n    {\n        // Close all existing connections with 1001 Going Away\n        for (const client of clients)\n        {\n            client.close(1001, 'Server shutting down');\n        }\n        clients.clear();\n\n        wss.close((err?: Error) =>\n        {\n            if (err) reject(err);\n            else resolve();\n        });\n    });\n}\n\n// ============================================================================\n// Connection Handler\n// ============================================================================\n\nasync function handleConnection(\n    ws: any,\n    req: any,\n    router: WSRouterDef<any, any>,\n    authConfig: WSHandlerAuthConfig | undefined,\n    tokenManager: SSETokenManager | undefined,\n    pingInterval: number\n): Promise<void>\n{\n    // Register close handler before any await — ensures we never miss the event even during auth\n    let pingTimer: ReturnType<typeof setInterval> | undefined;\n    let connectionUnsubscribes: (() => void)[] = [];\n    let subscribedEvents: string[] = [];\n    ws.on('close', () =>\n    {\n        clearInterval(pingTimer);\n        connectionUnsubscribes.forEach(fn => fn());\n        if (subscribedEvents.length > 0)\n            wsLogger.info('WebSocket connection closed', { events: subscribedEvents });\n    });\n\n    const url = parseURL(req);\n    if (!url)\n    {\n        ws.close(1002, 'Invalid request URL');\n        return;\n    }\n\n    // ── 1. Authenticate ──\n    const subject = await resolveSubject(url, authConfig?.enabled ? tokenManager : undefined);\n    if (subject === false)\n    {\n        ws.close(4001, 'Missing token');\n        return;\n    }\n    if (subject === null)\n    {\n        ws.close(4001, 'Invalid or expired token');\n        return;\n    }\n\n    // ── 2. Resolve subscribed events ──\n    const requestedEvents = parseRequestedEvents(url, router.eventNames as string[]);\n    if (requestedEvents.length === 0)\n    {\n        ws.close(4000, 'No valid event names specified');\n        return;\n    }\n\n    // ── 3. Authorize ──\n    const allowedEvents = await resolveAllowedEvents(subject, requestedEvents, authConfig);\n    if (allowedEvents === null)\n    {\n        ws.close(4003, 'Not authorized for any requested events');\n        return;\n    }\n\n    subscribedEvents = allowedEvents;\n    wsLogger.info('WebSocket connection established', {\n        events: allowedEvents,\n        subject: subject ?? undefined,\n    });\n\n    // ── 4. Build connection wrapper ──\n    const connection = createConnection(ws);\n\n    // ── 5. Subscribe to server-push events ──\n    connectionUnsubscribes = subscribeEvents(ws, router, allowedEvents, subject, authConfig);\n\n    // If socket closed during auth awaits, clean up and bail\n    if (ws.readyState !== 1)\n    {\n        connectionUnsubscribes.forEach(fn => fn());\n        connectionUnsubscribes = [];\n        return;\n    }\n\n    // ── 6. Handle incoming messages ──\n    ws.on('message', (data: Buffer | string) =>\n    {\n        onClientMessage(data, router, connection, subject)\n            .catch((err: Error) => wsLogger.error('Unhandled message error', err));\n    });\n\n    // ── 7. Keep-alive ping ──\n    if (pingInterval > 0)\n    {\n        pingTimer = setInterval(() =>\n        {\n            if (ws.readyState === 1) ws.ping();\n        }, pingInterval);\n    }\n\n    // ── 9. Send connected ack ──\n    connection.send('__connected', {\n        subscribedEvents: allowedEvents,\n        timestamp: Date.now(),\n    });\n}\n\n// ============================================================================\n// Helpers\n// ============================================================================\n\nfunction parseURL(req: any): URL | null\n{\n    try\n    {\n        return new URL(req.url ?? '/', 'ws://localhost');\n    }\n    catch\n    {\n        return null;\n    }\n}\n\n/**\n * Resolve subject from token\n * - undefined: no auth required\n * - false: token param missing (when required)\n * - null: token invalid/expired\n * - string: authenticated subject\n */\nasync function resolveSubject(\n    url: URL,\n    tokenManager?: SSETokenManager\n): Promise<string | undefined | false | null>\n{\n    if (!tokenManager)\n    {\n        return undefined;\n    }\n\n    const token = url.searchParams.get('token');\n    if (!token)\n    {\n        return false;\n    }\n\n    return await tokenManager.verify(token);\n}\n\nfunction parseRequestedEvents(url: URL, validEventNames: string[]): string[]\n{\n    const eventsParam = url.searchParams.get('events');\n    if (!eventsParam)\n    {\n        return [];\n    }\n\n    return eventsParam\n        .split(',')\n        .map(e => e.trim())\n        .filter(e => validEventNames.includes(e));\n}\n\nasync function resolveAllowedEvents(\n    subject: string | undefined,\n    requestedEvents: string[],\n    authConfig?: WSHandlerAuthConfig\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    return allowed.length === 0 ? null : allowed;\n}\n\nfunction createConnection(ws: any): WSRawConnection\n{\n    return {\n        send: (type, payload) =>\n        {\n            if (ws.readyState !== 1) return;\n            ws.send(JSON.stringify({ type, data: payload }));\n        },\n        close: (code, reason) => ws.close(code, reason),\n    };\n}\n\nfunction subscribeEvents(\n    ws: any,\n    router: WSRouterDef<any, any>,\n    allowedEvents: string[],\n    subject: string | undefined,\n    authConfig?: WSHandlerAuthConfig\n): (() => void)[]\n{\n    const unsubscribes: (() => void)[] = [];\n\n    for (const eventName of allowedEvents)\n    {\n        const eventDef = router.events[eventName];\n        if (!eventDef) continue;\n\n        const unsubscribe = eventDef.subscribe((payload: unknown) =>\n        {\n            if (ws.readyState !== 1) return;\n\n            if (subject && authConfig?.filter?.[eventName])\n            {\n                if (!authConfig.filter[eventName](subject, payload)) return;\n            }\n\n            try\n            {\n                ws.send(JSON.stringify({ type: eventName, data: payload }));\n            }\n            catch\n            {\n                // Socket closed between readyState check and send — ignore\n            }\n        });\n\n        unsubscribes.push(unsubscribe);\n    }\n\n    return unsubscribes;\n}\n\nasync function onClientMessage(\n    data: Buffer | string,\n    router: WSRouterDef<any, any>,\n    connection: WSRawConnection,\n    subject: string | undefined\n): Promise<void>\n{\n    let message: { type?: string; data?: unknown };\n\n    try\n    {\n        message = JSON.parse(data.toString());\n    }\n    catch\n    {\n        return;\n    }\n\n    const { type, data: payload } = message;\n    if (!type) return;\n\n    const handler = router.messages[type];\n    if (!handler) return;\n\n    try\n    {\n        await handler({ payload, subject, ws: connection });\n    }\n    catch (err)\n    {\n        wsLogger.error(`WebSocket message handler error: ${type}`, err as Error);\n    }\n}\n\n// ============================================================================\n// Dynamic import for optional 'ws' dependency\n// ============================================================================\n\nasync function loadWSServer(): Promise<any>\n{\n    try\n    {\n        // ws is a CJS package: module.exports = WebSocket, WebSocket.WebSocketServer is set on it.\n        // ESM dynamic import wraps CJS default export under .default\n        // eslint-disable-next-line @typescript-eslint/no-explicit-any\n        const mod = await import('ws') as any;\n        const WS = mod.default ?? mod;\n        const WSS = WS.WebSocketServer ?? WS.Server;\n\n        if (typeof WSS !== 'function')\n        {\n            throw new Error(\n                'WebSocketServer not found in ws module. ' +\n                'Ensure ws@^8 is installed: pnpm add ws'\n            );\n        }\n\n        return WSS;\n    }\n    catch (err)\n    {\n        if (err instanceof Error && err.message.includes('WebSocketServer not found'))\n        {\n            throw err;\n        }\n        throw new Error(\n            '@spfn/core WebSocket support requires the \"ws\" package.\\n' +\n            'Install it with: pnpm add ws'\n        );\n    }\n}\n","/**\n * WebSocket Module\n *\n * Type-safe WebSocket server with event-based pub/sub and bidirectional messaging.\n *\n * @example Server setup\n * ```typescript\n * // src/server/ws.ts\n * import { defineWSRouter } from '@spfn/core/event/ws';\n * import { defineEvent } from '@spfn/core/event';\n * import { Type } from '@sinclair/typebox';\n *\n * const userUpdated = defineEvent('user.updated', Type.Object({ userId: Type.String() }));\n * const notification = defineEvent('notification', Type.Object({ message: Type.String() }));\n *\n * export const wsRouter = defineWSRouter({\n *     events: { userUpdated, notification },\n *     messages: {\n *         ping: ({ ws }) => ws.send('pong', {}),\n *     },\n * });\n *\n * export type WSRouter = typeof wsRouter;\n *\n * // server.config.ts\n * defineServerConfig()\n *     .websockets(wsRouter)\n *     .build();\n * ```\n *\n * @example Client usage\n * ```typescript\n * import { createWSClient } from '@spfn/core/event/ws/client';\n * import type { WSRouter } from '@/server/ws';\n *\n * const client = createWSClient<WSRouter>();\n *\n * client.subscribe({\n *     events: ['userUpdated', 'notification'],\n *     handlers: {\n *         userUpdated: ({ userId }) => console.log(userId),\n *         notification: ({ message }) => console.log(message),\n *     },\n * });\n *\n * client.send('ping', {});\n * ```\n */\n\nimport type { EventDef } from '../types';\nimport type { WSRouterDef, WSMessageHandlers } from './types';\n\nexport { attachWSHandler } from './handler';\nexport type {\n    WSRouterDef,\n    WSHandlerConfig,\n    WSAuthConfig,\n    WSHandlerAuthConfig,\n    WSMessageContext,\n    WSMessageHandlerFn,\n    WSMessageHandlers,\n    WSRawConnection,\n    WSClientConfig,\n    WSConnectionState,\n    WSEventHandlers,\n    WSSubscribeOptions,\n    WSUnsubscribe,\n} from './types';\n\n/**\n * Define a WebSocket router\n *\n * Combines server→client event push with client→server message handlers.\n *\n * @example\n * ```typescript\n * export const wsRouter = defineWSRouter({\n *     events: { userUpdated, notification },\n *     messages: {\n *         ping: ({ ws }) => ws.send('pong', {}),\n *         'chat.send': ({ payload, subject }) => handleChat(payload, subject),\n *     },\n * });\n * ```\n */\nexport function defineWSRouter<\n    TEvents extends Record<string, EventDef<any>>,\n    TMessages extends WSMessageHandlers = WSMessageHandlers\n>(def: {\n    events: TEvents;\n    messages?: TMessages;\n}): WSRouterDef<TEvents, TMessages>\n{\n    return {\n        events: def.events,\n        eventNames: Object.keys(def.events) as (keyof TEvents)[],\n        messages: (def.messages ?? {}) as TMessages,\n        _types: {} as WSRouterDef<TEvents, TMessages>['_types'],\n    };\n}\n"]}

package/dist/server/index.d.ts

@@ -5,8 +5,9 @@ import { serve } from '@hono/node-server';
 import { NamedMiddleware, Router } from '@spfn/core/route';
 import { OnErrorContext } from '@spfn/core/middleware';
 import { J as JobRouter, B as BossOptions } from '../boss-Cxqc-Oiw.js';
-import { E as EventRouterDef } from '../router-Di7ENoah.js';
-import { S as SSEHandlerConfig, a as SSEAuthConfig } from '../types-DKQ90YL7.js';
+import { E as EventRouterDef } from '../token-manager-DSwIDD-_.js';
+import { S as SSEHandlerConfig, a as SSEAuthConfig } from '../types-BOOUBu9l.js';
+import { W as WSRouterDef, a as WSHandlerConfig, b as WSMessageHandlers, c as WSAuthConfig } from '../types-FuJb3yrP.js';
 import '@sinclair/typebox';
 import 'pg-boss';
 
@@ -193,6 +194,30 @@ interface ServerConfig {
          */
         path?: string;
     };
+    /**
+     * WebSocket router for bidirectional real-time communication
+     *
+     * @example
+     * ```typescript
+     * import { defineWSRouter } from '@spfn/core/event/ws';
+     *
+     * export default defineServerConfig()
+     *   .websockets(wsRouter)       // → WS /ws
+     *   .build();
+     * ```
+     */
+    websockets?: WSRouterDef<any, any>;
+    /**
+     * WebSocket configuration options
+     * Only used if websockets router is provided
+     */
+    websocketsConfig?: WSHandlerConfig & {
+        /**
+         * WebSocket endpoint path
+         * @default '/ws'
+         */
+        path?: string;
+    };
     /**
      * Enable debug mode (default: NODE_ENV === 'development')
      */
@@ -836,6 +861,37 @@ declare class ServerConfigBuilder {
         path?: string;
         auth?: SSEAuthConfig<TRouter>;
     }): this;
+    /**
+     * Register WebSocket router for bidirectional real-time communication
+     *
+     * Enables type-safe WebSocket connections with:
+     * - Server→client event push (via defineEvent + emit)
+     * - Client→server message handling (via messages in defineWSRouter)
+     *
+     * @example
+     * ```typescript
+     * // src/server/ws.ts
+     * export const wsRouter = defineWSRouter({
+     *     events: { userUpdated, notification },
+     *     messages: {
+     *         ping: ({ ws }) => ws.send('pong', {}),
+     *     },
+     * });
+     *
+     * // server.config.ts
+     * export default defineServerConfig()
+     *     .websockets(wsRouter)              // → WS /ws
+     *     .websockets(wsRouter, {
+     *         path: '/realtime',             // custom path
+     *         auth: { enabled: true },       // token authentication
+     *     })
+     *     .build();
+     * ```
+     */
+    websockets<TEvents extends Record<string, any>, TMessages extends WSMessageHandlers, TRouter extends WSRouterDef<TEvents, TMessages>>(router: TRouter, config?: Omit<WSHandlerConfig, 'auth'> & {
+        path?: string;
+        auth?: WSAuthConfig<TRouter>;
+    }): this;
     /**
      * Enable/disable debug mode
      */

package/dist/server/index.js

@@ -1413,6 +1413,202 @@ async function registerJob(job2) {
   await queueRunOnceJob(boss, job2);
   jobLogger2.debug(`Job registered: ${job2.name}`);
 }
+var wsLogger = logger.child("@spfn/core:ws");
+async function attachWSHandler(server, router, config = {}, tokenManager) {
+  const WebSocketServer = await loadWSServer();
+  const {
+    pingInterval = 3e4,
+    path = "/ws",
+    auth: authConfig
+  } = config;
+  if (authConfig?.enabled && !tokenManager) {
+    throw new Error(
+      "WebSocket auth.enabled=true requires a tokenManager. Pass tokenManager or use .websockets(router, { auth: { enabled: true } }) via startServer."
+    );
+  }
+  const wss = new WebSocketServer({ server, path });
+  const clients = /* @__PURE__ */ new Set();
+  wss.on("connection", (ws, req) => {
+    clients.add(ws);
+    ws.on("close", () => clients.delete(ws));
+    handleConnection(ws, req, router, authConfig, tokenManager, pingInterval).catch((err) => {
+      wsLogger.error("WebSocket connection handler error", err);
+      if (ws.readyState === 1) ws.close(1011, "Internal server error");
+    });
+  });
+  wss.on("error", (err) => {
+    wsLogger.error("WebSocket server error", err);
+  });
+  wsLogger.info(`\u2713 WebSocket endpoint registered at ${path}`, {
+    events: router.eventNames,
+    auth: !!authConfig?.enabled
+  });
+  return () => new Promise((resolve2, reject) => {
+    for (const client of clients) {
+      client.close(1001, "Server shutting down");
+    }
+    clients.clear();
+    wss.close((err) => {
+      if (err) reject(err);
+      else resolve2();
+    });
+  });
+}
+async function handleConnection(ws, req, router, authConfig, tokenManager, pingInterval) {
+  let pingTimer;
+  let connectionUnsubscribes = [];
+  let subscribedEvents = [];
+  ws.on("close", () => {
+    clearInterval(pingTimer);
+    connectionUnsubscribes.forEach((fn) => fn());
+    if (subscribedEvents.length > 0)
+      wsLogger.info("WebSocket connection closed", { events: subscribedEvents });
+  });
+  const url = parseURL(req);
+  if (!url) {
+    ws.close(1002, "Invalid request URL");
+    return;
+  }
+  const subject = await resolveSubject(url, authConfig?.enabled ? tokenManager : void 0);
+  if (subject === false) {
+    ws.close(4001, "Missing token");
+    return;
+  }
+  if (subject === null) {
+    ws.close(4001, "Invalid or expired token");
+    return;
+  }
+  const requestedEvents = parseRequestedEvents2(url, router.eventNames);
+  if (requestedEvents.length === 0) {
+    ws.close(4e3, "No valid event names specified");
+    return;
+  }
+  const allowedEvents = await resolveAllowedEvents(subject, requestedEvents, authConfig);
+  if (allowedEvents === null) {
+    ws.close(4003, "Not authorized for any requested events");
+    return;
+  }
+  subscribedEvents = allowedEvents;
+  wsLogger.info("WebSocket connection established", {
+    events: allowedEvents,
+    subject: subject ?? void 0
+  });
+  const connection = createConnection(ws);
+  connectionUnsubscribes = subscribeEvents(ws, router, allowedEvents, subject, authConfig);
+  if (ws.readyState !== 1) {
+    connectionUnsubscribes.forEach((fn) => fn());
+    connectionUnsubscribes = [];
+    return;
+  }
+  ws.on("message", (data) => {
+    onClientMessage(data, router, connection, subject).catch((err) => wsLogger.error("Unhandled message error", err));
+  });
+  if (pingInterval > 0) {
+    pingTimer = setInterval(() => {
+      if (ws.readyState === 1) ws.ping();
+    }, pingInterval);
+  }
+  connection.send("__connected", {
+    subscribedEvents: allowedEvents,
+    timestamp: Date.now()
+  });
+}
+function parseURL(req) {
+  try {
+    return new URL(req.url ?? "/", "ws://localhost");
+  } catch {
+    return null;
+  }
+}
+async function resolveSubject(url, tokenManager) {
+  if (!tokenManager) {
+    return void 0;
+  }
+  const token = url.searchParams.get("token");
+  if (!token) {
+    return false;
+  }
+  return await tokenManager.verify(token);
+}
+function parseRequestedEvents2(url, validEventNames) {
+  const eventsParam = url.searchParams.get("events");
+  if (!eventsParam) {
+    return [];
+  }
+  return eventsParam.split(",").map((e) => e.trim()).filter((e) => validEventNames.includes(e));
+}
+async function resolveAllowedEvents(subject, requestedEvents, authConfig) {
+  if (!subject || !authConfig?.authorize) {
+    return requestedEvents;
+  }
+  const allowed = await authConfig.authorize(subject, requestedEvents);
+  return allowed.length === 0 ? null : allowed;
+}
+function createConnection(ws) {
+  return {
+    send: (type, payload) => {
+      if (ws.readyState !== 1) return;
+      ws.send(JSON.stringify({ type, data: payload }));
+    },
+    close: (code, reason) => ws.close(code, reason)
+  };
+}
+function subscribeEvents(ws, router, allowedEvents, subject, authConfig) {
+  const unsubscribes = [];
+  for (const eventName of allowedEvents) {
+    const eventDef = router.events[eventName];
+    if (!eventDef) continue;
+    const unsubscribe = eventDef.subscribe((payload) => {
+      if (ws.readyState !== 1) return;
+      if (subject && authConfig?.filter?.[eventName]) {
+        if (!authConfig.filter[eventName](subject, payload)) return;
+      }
+      try {
+        ws.send(JSON.stringify({ type: eventName, data: payload }));
+      } catch {
+      }
+    });
+    unsubscribes.push(unsubscribe);
+  }
+  return unsubscribes;
+}
+async function onClientMessage(data, router, connection, subject) {
+  let message;
+  try {
+    message = JSON.parse(data.toString());
+  } catch {
+    return;
+  }
+  const { type, data: payload } = message;
+  if (!type) return;
+  const handler = router.messages[type];
+  if (!handler) return;
+  try {
+    await handler({ payload, subject, ws: connection });
+  } catch (err) {
+    wsLogger.error(`WebSocket message handler error: ${type}`, err);
+  }
+}
+async function loadWSServer() {
+  try {
+    const mod = await import('ws');
+    const WS = mod.default ?? mod;
+    const WSS = WS.WebSocketServer ?? WS.Server;
+    if (typeof WSS !== "function") {
+      throw new Error(
+        "WebSocketServer not found in ws module. Ensure ws@^8 is installed: pnpm add ws"
+      );
+    }
+    return WSS;
+  } catch (err) {
+    if (err instanceof Error && err.message.includes("WebSocketServer not found")) {
+      throw err;
+    }
+    throw new Error(
+      '@spfn/core WebSocket support requires the "ws" package.\nInstall it with: pnpm add ws'
+    );
+  }
+}
 function getNetworkAddress() {
   const nets = networkInterfaces();
   for (const name of Object.keys(nets)) {
@@ -1519,6 +1715,10 @@ async function startServer(config) {
     await initializeInfrastructure(finalConfig);
     const app = await createServer(finalConfig);
     const server = startHttpServer(app, host, port);
+    let wsCleanup;
+    if (finalConfig.websockets) {
+      wsCleanup = await initializeWebSocket(server, app, finalConfig);
+    }
     const timeouts = getTimeoutConfig(finalConfig.timeout);
     applyServerTimeouts(server, timeouts);
     const fetchTimeouts = getFetchTimeoutConfig(finalConfig.fetchTimeout);
@@ -1530,7 +1730,7 @@ async function startServer(config) {
       port
     });
     logServerStarted(debug, host, port, finalConfig, timeouts);
-    const shutdownServer = createShutdownHandler(server, finalConfig, shutdownState);
+    const shutdownServer = createShutdownHandler(server, finalConfig, shutdownState, wsCleanup);
     const shutdown = createGracefulShutdown(shutdownServer, finalConfig, shutdownState);
     registerProcessHandlers(shutdown);
     const serverInstance = {
@@ -1653,6 +1853,46 @@ function startHttpServer(app, host, port) {
     hostname: host
   });
 }
+async function initializeWebSocket(server, app, config) {
+  const wsRouter = config.websockets;
+  const wsConfig = config.websocketsConfig ?? {};
+  const authConfig = wsConfig.auth;
+  const wsPath = wsConfig.path ?? "/ws";
+  const debug = config.debug ?? process.env.NODE_ENV === "development";
+  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("WS token store: cache (Redis/Valkey)");
+        }
+      } catch {
+      }
+    }
+    const externalManager = typeof authConfig.tokenManager === "function" ? authConfig.tokenManager() : authConfig.tokenManager;
+    tokenManager = externalManager ?? new SSETokenManager({
+      ttl: authConfig.tokenTtl,
+      store
+    });
+    const tokenPath = wsPath.replace(/\/[^/]+$/, "/token");
+    const mwHandlers = (config.middlewares ?? []).map((mw) => mw.handler);
+    const getSubject = authConfig.getSubject ?? ((c) => c.get("auth")?.userId ?? null);
+    app.on(["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 WS token endpoint registered at POST ${tokenPath}`);
+  }
+  return await attachWSHandler(server, wsRouter, wsConfig, tokenManager);
+}
 function logMiddlewareOrder(config) {
   const middlewareOrder = buildMiddlewareOrder(config);
   serverLogger.debug("Middleware execution order", {
@@ -1675,7 +1915,7 @@ function logServerStarted(debug, host, port, config, timeouts) {
     config: startupConfig
   });
 }
-function createShutdownHandler(server, config, shutdownState) {
+function createShutdownHandler(server, config, shutdownState, wsCleanup) {
   return async () => {
     if (shutdownState.isShuttingDown) {
       serverLogger.debug("Shutdown already in progress for this instance, skipping");
@@ -1687,6 +1927,15 @@ function createShutdownHandler(server, config, shutdownState) {
     shutdownManager.beginShutdown();
     serverLogger.info("Phase 1: Closing HTTP server (stop accepting new connections)...");
     await closeHttpServer(server);
+    if (wsCleanup) {
+      serverLogger.info("Phase 1.5: Closing WebSocket server...");
+      try {
+        await wsCleanup();
+        serverLogger.info("WebSocket server closed");
+      } catch (error) {
+        serverLogger.error("WebSocket server close failed", error);
+      }
+    }
     if (config.jobs) {
       serverLogger.info("Phase 2: Stopping pg-boss...");
       try {
@@ -2033,6 +2282,40 @@ var ServerConfigBuilder = class {
     }
     return this;
   }
+  /**
+   * Register WebSocket router for bidirectional real-time communication
+   *
+   * Enables type-safe WebSocket connections with:
+   * - Server→client event push (via defineEvent + emit)
+   * - Client→server message handling (via messages in defineWSRouter)
+   *
+   * @example
+   * ```typescript
+   * // src/server/ws.ts
+   * export const wsRouter = defineWSRouter({
+   *     events: { userUpdated, notification },
+   *     messages: {
+   *         ping: ({ ws }) => ws.send('pong', {}),
+   *     },
+   * });
+   *
+   * // server.config.ts
+   * export default defineServerConfig()
+   *     .websockets(wsRouter)              // → WS /ws
+   *     .websockets(wsRouter, {
+   *         path: '/realtime',             // custom path
+   *         auth: { enabled: true },       // token authentication
+   *     })
+   *     .build();
+   * ```
+   */
+  websockets(router, config) {
+    this.config.websockets = router;
+    if (config) {
+      this.config.websocketsConfig = config;
+    }
+    return this;
+  }
   /**
    * Enable/disable debug mode
    */