create-nexwire 4.2.4 → 4.3.0

package/express/src/framework/realtime/socket.ts

@@ -1,119 +1,149 @@
-import { createAdapter } from "@socket.io/redis-adapter";
-import { Server as SocketIOServer } from "socket.io";
-import { appConfig, realtimeConfig, redisConfig } from "@/config/index.js";
-import { authFromSocketHandshake, unauthenticatedRealtimeAuth } from "@/framework/realtime/socket-cookie.js";
-import type { RealtimeAuthContext } from "@/framework/realtime/types.js";
-import { redisClientIfReady } from "@/framework/redis/client.js";
-import { logger } from "@/framework/support/logger.js";
-
-export type RealtimeServeWebSocket = Record<string, never>;
-
-export type RealtimeInit = {
-  io: SocketIOServer;
-  websocketServe: RealtimeServeWebSocket;
-};
-
-export const WS_PATH = "/socket.io";
-
-let io: SocketIOServer | null = null;
-let adapterSubClient: ReturnType<typeof redisClientIfReady> | null = null;
-
-function socketAllowedOrigins() {
-  const origins = [appConfig.url, appConfig.frontendUrl].filter(Boolean) as string[];
-  if (realtimeConfig.enabled) origins.push("https://admin.socket.io");
-  return [...new Set(origins)];
-}
-
-async function attachRedisAdapter() {
-  if (!redisConfig.enabled) return;
-
-  const pubClient = redisClientIfReady();
-  if (!pubClient) return;
-
-  adapterSubClient = pubClient.duplicate();
-  await adapterSubClient.connect();
-  io?.adapter(createAdapter(pubClient, adapterSubClient));
-}
-
-function registerAuthAndRooms() {
-  io?.use(async (socket, next) => {
-    const auth = await authFromSocketHandshake(socket);
-    socket.data.auth = auth as RealtimeAuthContext;
-
-    if (auth.isAuthenticated) {
-      socket.join("auth");
-      if (auth.userId) socket.join(`user:${auth.userId}`);
-      for (const role of auth.roles) socket.join(`role:${role}`);
-    } else {
-      socket.join("guest");
-    }
-
-    next();
-  });
-
-  io?.on("connection", (socket) => {
-    const auth = (socket.data.auth || unauthenticatedRealtimeAuth()) as RealtimeAuthContext;
-
-    logger.debug("Socket connected", {
-      socketId: socket.id,
-      authenticated: auth.isAuthenticated,
-      userId: auth.userId
-    });
-
-    socket.on("join", (room) => socket.join(String(room)));
-    socket.on("disconnect", (reason) => {
-      logger.info("Socket disconnected", {
-        socketId: socket.id,
-        reason,
-        authenticated: auth.isAuthenticated,
-        userId: auth.userId
-      });
-    });
-  });
-}
-
-export async function initRealtime(target: { httpServer: any }): Promise<RealtimeInit | null> {
-  if (!realtimeConfig.enabled) {
-    logger.info("Socket.IO disabled (disabled in config)");
-    return null;
-  }
-
-  if (io) return { io, websocketServe: {} };
-
-  io = new SocketIOServer(target.httpServer, {
-    cors: { origin: socketAllowedOrigins(), credentials: true }
-  });
-
-  await attachRedisAdapter();
-  registerAuthAndRooms();
-
-  logger.info(`Socket.IO enabled at ${WS_PATH}`);
-  return { io, websocketServe: {} };
-}
-
-export function socketServer() {
-  return io;
-}
-
-export function ioServer() {
-  return io;
-}
-
-export async function closeRealtime() {
-  if (!io) return;
-
-  await new Promise<void>((resolve) => {
-    io?.close(() => resolve());
-  });
-
-  if (adapterSubClient) {
-    try {
-      await adapterSubClient.quit();
-    } catch {
-      adapterSubClient.disconnect();
-    }
-    adapterSubClient = null;
-  }
-
-  io = null;
-}
+import { createAdapter } from "@socket.io/redis-adapter";
+import { Server as SocketIOServer } from "socket.io";
+import { appConfig, realtimeConfig, redisConfig } from "@/config/index.js";
+import { createCircuitBreaker, isCircuitBreakerError } from "@/framework/circuit-breaker/cb.js";
+import { authFromSocketHandshake, unauthenticatedRealtimeAuth } from "@/framework/realtime/socket-cookie.js";
+import type { RealtimeAuthContext } from "@/framework/realtime/types.js";
+import { redisClientIfReady } from "@/framework/redis/client.js";
+import { logger } from "@/framework/support/logger.js";
+
+export const WS_PATH = "/socket.io";
+
+// Create a breaker for the Socket.IO Redis adapter
+const socketAdapterBreaker = createCircuitBreaker({
+  name: "Socket.IO Redis Adapter",
+  failureThreshold: 3,
+  resetTimeout: 30000
+});
+
+export type RealtimeServeWebSocket = Record<string, never>;
+
+export type RealtimeInit = {
+  io: SocketIOServer;
+  websocketServe: RealtimeServeWebSocket;
+};
+
+let io: SocketIOServer | null = null;
+let adapterSubClient: ReturnType<typeof redisClientIfReady> | null = null;
+
+function socketAllowedOrigins() {
+  const origins = [appConfig.url, appConfig.frontendUrl].filter(Boolean) as string[];
+  if (realtimeConfig.enabled) origins.push("https://admin.socket.io");
+  return [...new Set(origins)];
+}
+
+async function attachRedisAdapter() {
+  if (!redisConfig.enabled) return;
+
+  try {
+    await socketAdapterBreaker.exec(async () => {
+      const pubClient = redisClientIfReady();
+      if (!pubClient) throw new Error("Redis client not ready");
+
+      // Socket.IO requires a duplicate connection for subscriptions
+      adapterSubClient = pubClient.duplicate();
+      await adapterSubClient.connect();
+
+      io?.adapter(createAdapter(pubClient, adapterSubClient));
+      logger.debug("Socket.IO Redis adapter attached successfully");
+    });
+  } catch (error) {
+    if (isCircuitBreakerError(error)) {
+      logger.warn("Socket.IO Redis adapter skipped due to circuit breaker");
+    } else {
+      logger.error("Failed to attach Socket.IO Redis adapter", { error });
+    }
+    // Fallback: Socket.IO will automatically use its default in-memory adapter.
+  }
+}
+
+function registerAuthAndRooms() {
+  io?.use(async (socket, next) => {
+    const auth = await authFromSocketHandshake(socket);
+    socket.data.auth = auth as RealtimeAuthContext;
+
+    if (auth.isAuthenticated) {
+      socket.join("auth");
+      if (auth.userId) socket.join(`user:${auth.userId}`);
+      for (const role of auth.roles) socket.join(`role:${role}`);
+    } else {
+      socket.join("guest");
+    }
+
+    next();
+  });
+
+  io?.on("connection", (socket) => {
+    const auth = (socket.data.auth || unauthenticatedRealtimeAuth()) as RealtimeAuthContext;
+
+    logger.debug("Socket connected", {
+      socketId: socket.id,
+      authenticated: auth.isAuthenticated,
+      userId: auth.userId
+    });
+
+    socket.on("join", (room) => socket.join(String(room)));
+    socket.on("disconnect", (reason) => {
+      logger.info("Socket disconnected", {
+        socketId: socket.id,
+        reason,
+        authenticated: auth.isAuthenticated,
+        userId: auth.userId
+      });
+    });
+  });
+}
+
+/**
+ * Why: Boots the singleton Socket.IO server for Express.
+ * When: Express HTTP server starts and realtime is enabled.
+ * Where: Framework server lifecycle.
+ * How: Attaches Socket.IO directly to the Express/Node httpServer.
+ */
+export async function initRealtime(target: { httpServer: any }): Promise<RealtimeInit | null> {
+  if (!realtimeConfig.enabled) {
+    logger.debug("Socket.IO disabled (disabled in config)");
+    return null;
+  }
+
+  if (io) return { io, websocketServe: {} };
+
+  // Express uses the native Node.js httpServer
+  io = new SocketIOServer(target.httpServer, {
+    path: WS_PATH, // Explicitly set the path to match Hono
+    cors: { origin: socketAllowedOrigins(), credentials: true }
+  });
+
+  await attachRedisAdapter();
+  registerAuthAndRooms();
+
+  logger.debug(`Socket.IO enabled at ${WS_PATH}`);
+  return { io, websocketServe: {} };
+}
+
+export function socketServer() {
+  return io;
+}
+
+export function ioServer() {
+  return io;
+}
+
+export async function closeRealtime() {
+  if (!io) return;
+
+  await new Promise<void>((resolve) => {
+    io?.close(() => resolve());
+  });
+
+  if (adapterSubClient) {
+    try {
+      await adapterSubClient.quit();
+    } catch {
+      adapterSubClient.disconnect();
+    }
+    adapterSubClient = null;
+  }
+
+  io = null;
+}

package/express/src/framework/redis/client.ts

@@ -1,151 +1,148 @@
-import { Redis } from "ioredis";
-import { redisConfig } from "@/config/index.js";
-import { CircuitBreaker } from "@/framework/circuit-breaker/cb.js";
-import { logger } from "@/framework/support/logger.js";
-
-export type redis = Redis;
-
-let client: redis | null = null;
-let ready = false;
-let lastError: string | null = null;
-let redisBreaker: CircuitBreaker | null = null;
-
-if (redisConfig.enabled) {
-  redisBreaker = new CircuitBreaker();
-}
-
-function safeRedisUrl() {
-  try {
-    const url = new URL(redisConfig.url);
-    if (url.password) url.password = "***";
-    return url.toString();
-  } catch {
-    return redisConfig.url;
-  }
-}
-
-/**
- * Why: Initializes shared Redis connection for cache/queue/events/session.
- * When: Runtime bootstrap before Redis-backed features are used.
- * Where: Server, worker, scheduler startup paths.
- * How: Connects once, tracks readiness, and degrades gracefully if unavailable.
- */
-export async function initRedis() {
-  if (client) return client;
-
-  if (!redisConfig.enabled) {
-    ready = false;
-    lastError = "redis disabled in config";
-    logger.info("Redis disabled; cache, session storage, queue, events, and cockpit unavailable");
-    return null;
-  }
-
-  if (redisBreaker?.getState() === "open") {
-    lastError = "redis circuit breaker is open";
-    logger.warn("Redis circuit breaker is open; skipping connection");
-    return null;
-  }
-
-  try {
-    client = new Redis(redisConfig.url, {
-      lazyConnect: true,
-      enableReadyCheck: true,
-      maxRetriesPerRequest: 0,
-      retryStrategy: () => null
-    });
-
-    client.on("error", (error) => {
-      lastError = error.message;
-      if (ready) {
-        logger.warn("Redis connection error", {
-          redisUrl: safeRedisUrl(),
-          error: error.message
-        });
-      }
-    });
-
-    await client.connect();
-    await client.ping();
-    ready = true;
-    redisBreaker?.onSuccess();
-    return client;
-  } catch (error) {
-    lastError ||= error instanceof Error ? error.message : String(error);
-    client?.disconnect();
-    client = null;
-    ready = false;
-    redisBreaker?.onFailure();
-    logger.warn(`Redis unavailable; continuing without Redis features (${lastError})`);
-    return null;
-  }
-}
-
-/**
- * Why: Returns the current Redis client instance.
- * When: Internal helpers need direct Redis operations.
- * Where: Cache/session/queue/events modules.
- * How: Returns nullable singleton without creating a new connection.
- */
-export function redis() {
-  return client;
-}
-
-/**
- * Why: Indicates whether Redis is connected and usable.
- * When: Features need to branch on Redis availability.
- * Where: Cache/session/queue/event internals.
- * How: Combines readiness flag with client presence.
- */
-export function redisReady() {
-  return ready && client !== null;
-}
-
-/**
- * Why: Provides a single ready-checked Redis client accessor.
- * When: Redis-backed modules need quick availability guard.
- * Where: Cache/session/queue/events/BullBoard internals.
- * How: Returns connected client or null when Redis is unavailable.
- */
-export function redisClientIfReady() {
-  if (redisBreaker?.getState() === "open") return null;
-  return redisReady() ? client : null;
-}
-
-/**
- * Why: Exposes last Redis error for diagnostics.
- * When: Startup or health logs need failure detail.
- * Where: Runtime status output.
- * How: Returns cached error message string.
- */
-export function redisError() {
-  return lastError;
-}
-
-/**
- * Why: Returns the Redis circuit breaker instance or null when disabled.
- * When: Health checks and diagnostics need breaker state.
- * Where: Runtime status and monitoring paths.
- * How: Returns the breaker if Redis is enabled, null otherwise.
- */
-export function getRedisBreaker() {
-  return redisBreaker;
-}
-
-/**
- * Why: Closes Redis connection during graceful shutdown.
- * When: Process stop hooks for server/worker/scheduler.
- * Where: Runtime lifecycle files.
- * How: Attempts quit, falls back to disconnect, then resets state.
- */
-export async function closeRedis() {
-  if (!client) return;
-
-  try {
-    await client.quit();
-  } catch {
-    client.disconnect();
-  } finally {
-    client = null;
-    ready = false;
-  }
-}
+import { Redis } from "ioredis";
+import { redisConfig } from "@/config/index.js";
+import { createCircuitBreaker, isCircuitBreakerError } from "@/framework/circuit-breaker/cb.js";
+import { logger } from "@/framework/support/logger.js";
+
+export type redis = Redis;
+
+let client: redis | null = null;
+let ready = false;
+let lastError: string | null = null;
+let redisBreaker: any | null = null;
+
+if (redisConfig.enabled) {
+  redisBreaker = createCircuitBreaker({ name: "Redis", failureThreshold: 3, resetTimeout: 30000 });
+}
+
+function safeRedisUrl() {
+  try {
+    const url = new URL(redisConfig.url);
+    if (url.password) url.password = "***";
+    return url.toString();
+  } catch {
+    return redisConfig.url;
+  }
+}
+
+/**
+ * Why: Initializes shared Redis connection for cache/queue/events/session.
+ * When: Runtime bootstrap before Redis-backed features are used.
+ * Where: Server, worker, scheduler startup paths.
+ * How: Connects once, tracks readiness, and degrades gracefully if unavailable.
+ */
+export async function initRedis() {
+  if (client) return client;
+
+  if (!redisConfig.enabled) {
+    ready = false;
+    lastError = "redis disabled in config";
+    logger.debug("Redis disabled; cache, session storage, queue, events, and cockpit unavailable");
+    return null;
+  }
+
+  try {
+    return await redisBreaker.exec(async () => {
+      client = new Redis(redisConfig.url, {
+        lazyConnect: true,
+        enableReadyCheck: true,
+        maxRetriesPerRequest: 0,
+        retryStrategy: () => null
+      });
+
+      client.on("error", (error) => {
+        lastError = error.message;
+        if (ready) logger.warn("Redis connection error", { redisUrl: safeRedisUrl(), error: error.message });
+      });
+
+      await client.connect();
+      await client.ping();
+
+      ready = true;
+      logger.debug("Redis connected successfully");
+      return client;
+    });
+  } catch (error) {
+    // Use the functional guard
+    if (isCircuitBreakerError(error)) {
+      lastError = error.message;
+      logger.warn("Redis initialization blocked by circuit breaker");
+    } else {
+      lastError = error instanceof Error ? error.message : String(error);
+      logger.warn(`Redis unavailable; continuing without Redis features (${lastError})`);
+    }
+
+    client?.disconnect();
+    client = null;
+    ready = false;
+    return null;
+  }
+}
+
+/**
+ * Why: Returns the current Redis client instance.
+ * When: Internal helpers need direct Redis operations.
+ * Where: Cache/session/queue/events modules.
+ * How: Returns nullable singleton without creating a new connection.
+ */
+export function redis() {
+  return client;
+}
+
+/**
+ * Why: Indicates whether Redis is connected and usable.
+ * When: Features need to branch on Redis availability.
+ * Where: Cache/session/queue/event internals.
+ * How: Combines readiness flag with client presence.
+ */
+export function redisReady() {
+  return ready && client !== null;
+}
+
+/**
+ * Why: Provides a single ready-checked Redis client accessor.
+ * When: Redis-backed modules need quick availability guard.
+ * Where: Cache/session/queue/events/BullBoard internals.
+ * How: Returns connected client or null when Redis is unavailable.
+ */
+export function redisClientIfReady() {
+  return redisReady() ? client : null;
+}
+
+/**
+ * Why: Exposes last Redis error for diagnostics.
+ * When: Startup or health logs need failure detail.
+ * Where: Runtime status output.
+ * How: Returns cached error message string.
+ */
+export function redisError() {
+  return lastError;
+}
+
+/**
+ * Why: Returns the Redis circuit breaker instance or null when disabled.
+ * When: Health checks and diagnostics need breaker state.
+ * Where: Runtime status and monitoring paths.
+ * How: Returns the breaker if Redis is enabled, null otherwise.
+ */
+export function getRedisBreaker() {
+  return redisBreaker;
+}
+
+/**
+ * Why: Closes Redis connection during graceful shutdown.
+ * When: Process stop hooks for server/worker/scheduler.
+ * Where: Runtime lifecycle files.
+ * How: Attempts quit, falls back to disconnect, then resets state.
+ */
+export async function closeRedis() {
+  if (!client) return;
+
+  try {
+    await client.quit();
+  } catch {
+    client.disconnect();
+  } finally {
+    client = null;
+    ready = false;
+  }
+}

package/express/src/framework/runtime/server-adapter.ts

@@ -1,34 +1,39 @@
-import type { AddressInfo } from "node:net";
-import type { Express } from "express";
-import type { RealtimeServeWebSocket } from "@/framework/realtime/socket.js";
-import { runtime } from "@/framework/runtime/runtime.js";
-
-export type HttpServerHandle = {
-  address(): string | AddressInfo | null;
-  close(): Promise<void>;
-  native: unknown;
-};
-
-async function startNode(app: Express, port: number, _websocket?: RealtimeServeWebSocket): Promise<HttpServerHandle> {
-  const { createServer } = await import("node:http");
-
-  const server = createServer(app);
-  await new Promise<void>((resolve) => server.listen(port, resolve));
-
-  return {
-    native: server,
-    address: () => server.address(),
-    close: () => new Promise<void>((resolve) => server.close(() => resolve()))
-  };
-}
-
-async function startBun(app: Express, port: number, _websocket?: RealtimeServeWebSocket): Promise<HttpServerHandle> {
-  const server = await startNode(app, port);
-  return server;
-}
-
-export async function startHttpServer(app: Express, port: number, websocket?: RealtimeServeWebSocket): Promise<HttpServerHandle> {
-  const activeRuntime = runtime();
-  if (activeRuntime === "bun") return startBun(app, port, websocket);
-  return startNode(app, port, websocket);
-}
+import { createServer, type Server } from "node:http";
+import type { AddressInfo } from "node:net";
+import type { Express } from "express";
+import { closeRealtime, initRealtime } from "@/framework/realtime/socket.js";
+
+export type HttpServerHandle = {
+  address(): string | AddressInfo | null;
+  close(): Promise<void>;
+  native: unknown;
+};
+
+async function startNode(app: Express, port: number): Promise<HttpServerHandle> {
+  const server = createServer(app);
+
+  // 1. Attach Socket.IO BEFORE starting the server
+  await initRealtime({ httpServer: server });
+
+  // 2. Start listening
+  await new Promise<void>((resolve, reject) => {
+    server.listen(port, () => resolve());
+    server.on("error", (err) => reject(err));
+  });
+
+  return {
+    native: server,
+    address: () => server.address(),
+    close: async () => {
+      // 3. Close Socket.IO safely, then the HTTP server
+      await closeRealtime();
+      await new Promise<void>((resolve) => server.close(() => resolve()));
+    }
+  };
+}
+
+export async function startHttpServer(app: Express, port: number): Promise<HttpServerHandle> {
+  // Express runs natively on Node.js.
+  // Even if you run Express on Bun, Bun's Node compatibility layer handles http.createServer.
+  return startNode(app, port);
+}