create-nexwire 4.2.5 → 4.3.0

package/express/src/framework/server.ts

@@ -5,7 +5,7 @@ import { appConfig, mailConfig, realtimeConfig, redisConfig } from "@/config/ind
 import { createKernel } from "@/framework/kernel.js";
 import { stopQueueRuntime } from "@/framework/queue/queue.js";
 import { stopQueueDashboard } from "@/framework/queue/ui.js";
-import { broadcast, closeRealtime, initRealtime, WS_PATH } from "@/framework/realtime/index.js";
+import { broadcast, closeRealtime, socketServer, WS_PATH } from "@/framework/realtime/index.js";
 import { setupSocketAdminUI } from "@/framework/realtime/ui.js";
 import { closeRedis, redisClientIfReady, redisError, redisReady } from "@/framework/redis/client.js";
 import { type HttpServerHandle, startHttpServer } from "@/framework/runtime/server-adapter.js";
@@ -14,23 +14,15 @@ import { logger } from "@/framework/support/logger.js";
 
 const redisBackedServices = "cache, session, queue, events, Queue Dashboard";
 
-/**
- * Why: Builds reliable local URL string for runtime service output.
- * When: Printing API/docs/Queue Dashboard endpoints at startup.
- * Where: Server runtime logging.
- * How: Derives bound port from server address and normalizes hostname.
- */
 function serverUrl(server: HttpServerHandle, pathname = "") {
   const address = server.address();
   const port = typeof address === "object" && address ? address.port : appConfig.port;
-
   try {
     const currentUrl = new URL(appConfig.url);
     currentUrl.port = String(port);
     if (currentUrl.hostname === "0.0.0.0" || currentUrl.hostname === "::") {
       currentUrl.hostname = "localhost";
     }
-
     return `${currentUrl.toString().replace(/\/$/, "")}${pathname}`;
   } catch {
     return `http://localhost:${port}${pathname}`;
@@ -41,27 +33,22 @@ export interface ServerHandle {
   app: Awaited<ReturnType<typeof createKernel>>["app"];
   bullBoard: Awaited<ReturnType<typeof createKernel>>["bullBoard"];
   server: HttpServerHandle;
-  realtime: Awaited<ReturnType<typeof initRealtime>>;
+  realtime: any; // Type for Express is simpler
   broadcastSubClient: ReturnType<typeof redisClientIfReady> | null;
   shutdown: (signal: ShutdownSignal) => Promise<void>;
   closeHttpServer: () => Promise<void>;
 }
 
-/**
- * Why: Starts the HTTP server and wires realtime/queue/redis shutdown.
- * When: CLI `serve` command or E2E test bootstrap.
- * Where: Server entrypoint.
- * How: Creates kernel, starts HTTP, registers signal handlers, returns handle.
- *      When called as the main module, also prints startup banners.
- */
 export async function startServer(): Promise<ServerHandle> {
   const { app, bullBoard } = await createKernel();
 
-  let realtime = null as Awaited<ReturnType<typeof initRealtime>>;
+  // 1. Start the server (this internally attaches Socket.IO for Express)
   const server = await startHttpServer(app, appConfig.port);
-  realtime = await initRealtime({ httpServer: server.native });
 
-  const socketAdmin = setupSocketAdminUI(realtime?.io ?? null);
+  // 2. Grab the existing Socket.IO instance
+  const io = socketServer();
+  const realtime = io ? { io } : null;
+  const socketAdmin = setupSocketAdminUI(io);
 
   let shuttingDown = false;
   let broadcastSubClient: ReturnType<typeof redisClientIfReady> | null = null;
@@ -83,7 +70,9 @@ export async function startServer(): Promise<ServerHandle> {
       }
       broadcastSubClient = null;
     }
-    await Promise.allSettled([closeRealtime(), stopQueueRuntime(), closeHttpServer()]);
+
+    // closeRealtime is handled by server.close() adapter
+    await Promise.allSettled([stopQueueRuntime(), closeHttpServer()]);
     stopQueueDashboard();
     await closeRedis();
 
@@ -111,57 +100,52 @@ export async function startServer(): Promise<ServerHandle> {
   }
 
   const views = new Set(parseCsvOrFallback(process.env.NEXWIRE_DEV_VIEWS, []).map((view) => view.toLowerCase()));
-  let redisWarnColor: ((text: string) => string) | null = null;
+
   if (appConfig.openApiEnabled) {
     console.log(`API Docs: ${serverUrl(server, "/api-docs")}`);
   }
 
   if (appConfig.uiEnabled) {
-    if (process.env.NEXWIRE_FRONTEND_URL) {
-      console.log(`UI: ${process.env.NEXWIRE_FRONTEND_URL}`);
-    } else {
-      console.log("UI enabled");
-    }
+    console.log(`UI: ${process.env.NEXWIRE_FRONTEND_URL}`);
   } else {
-    console.log(chalk.gray("UI disabled (disabled in src/config/app.ts)"));
+    console.log(chalk.gray("UI: .env -> UI=false (API-only mode)"));
   }
 
-  const bullboardLine = `${bullBoard.enabled ? "Queue Dashboard enabled" : "Queue Dashboard unavailable"}: ${serverUrl(server, bullBoard.basePath)}`;
-  console.log(redisWarnColor ? redisWarnColor(bullboardLine) : bullboardLine);
+  if (redisConfig.enabled && bullBoard.enabled) {
+    console.log(`Queue: ${serverUrl(server, bullBoard.basePath)}`);
+  }
 
   if (views.has("maildev")) {
-    const maildevLine = `MailDev: http://localhost:${mailConfig.maildev.webPort} (SMTP ${mailConfig.maildev.smtpPort})`;
-    const line = `${maildevLine} (requested; see dev process status)`;
-    console.log(redisWarnColor ? redisWarnColor(line) : line);
+    console.log(`MailDev: http://localhost:${mailConfig.maildev.webPort} (SMTP ${mailConfig.maildev.smtpPort})`);
   }
 
   if (views.has("studio")) {
-    console.log("Drizzle Studio requested: https://local.drizzle.studio (see dev process status)");
+    console.log("Drizzle: https://local.drizzle.studio");
   }
 
   const wsUrl = serverUrl(server, WS_PATH).replace(/^http/, "ws");
-  const socketLine = !realtimeConfig.enabled
-    ? "Realtime (Socket.IO) disabled"
-    : realtime
-      ? `Realtime (Socket.IO) enabled: ${socketAdmin.enabled ? `Admin UI: https://admin.socket.io | ${wsUrl}` : `| ${wsUrl}`}`
-      : "Realtime (Socket.IO) unavailable";
-  console.log(!realtimeConfig.enabled ? chalk.gray(socketLine) : realtime ? chalk.green(socketLine) : chalk.yellow(socketLine));
-
-  if (views.has("redis")) {
-    const redisUiLine = `Redis UI: http://localhost:${redisConfig.commanderPort}`;
-    const line = `${redisUiLine} (requested; see dev process status)`;
-    console.log(redisWarnColor ? redisWarnColor(line) : line);
+  if (!realtimeConfig.enabled) {
+    console.log(chalk.gray("Realtime (Socket.IO) disabled"));
+  } else if (realtime) {
+    if (socketAdmin.enabled) {
+      console.log(`Realtime: https://admin.socket.io | ${wsUrl}`);
+    } else {
+      console.log(`Realtime: ${wsUrl}`);
+    }
+  } else {
+    console.log(chalk.yellow("Realtime (Socket.IO) unavailable"));
+  }
+
+  if (redisConfig.enabled && views.has("redis")) {
+    console.log(`Redis UI: http://localhost:${redisConfig.commanderPort}`);
   }
 
   if (!redisConfig.enabled) {
-    redisWarnColor = chalk.cyan;
-    console.log(chalk.cyan("Redis disabled (configured in src/config/redis.ts)"));
-    console.log(chalk.cyan(`Redis-backed services disabled: ${redisBackedServices}`));
+    console.log(chalk.cyan(`Redis: .env -> REDIS=false (disabled ${redisBackedServices})`));
   } else if (redisReady()) {
     console.log(chalk.green(`Redis connected: ${redisConfig.url}`));
     console.log(chalk.green(`Redis-backed services enabled: ${redisBackedServices}`));
   } else {
-    redisWarnColor = chalk.yellow;
     console.log(chalk.yellow(`Redis unavailable: ${redisError() || "not connected"}`));
     console.log(chalk.yellow(`Redis-backed services unavailable: ${redisBackedServices}`));
   }

package/express/src/framework/session/session.ts

@@ -1,8 +1,16 @@
 import { randomUUID } from "node:crypto";
 import type { NextFunction, Request, Response } from "express";
 import { appConfig, redisConfig, sessionConfig } from "@/config/index.js";
+import { createCircuitBreaker, isCircuitBreakerError } from "@/framework/circuit-breaker/cb.js";
 import { redisClientIfReady } from "@/framework/redis/client.js";
 
+// Initialize the breaker for Session operations
+const sessionBreaker = createCircuitBreaker({
+  name: "Redis Session",
+  failureThreshold: 3,
+  resetTimeout: 30000
+});
+
 function originOf(url?: string) {
   if (!url) return "";
   try {
@@ -22,6 +30,9 @@ function sessionKey(id: string) {
   return `${sessionConfig.keyPrefix}:${id}`;
 }
 
+/**
+ * Global middleware that ensures every request has a session cookie.
+ */
 export async function sessionMiddleware(req: Request, res: Response, next: NextFunction) {
   let sessionId = req.cookies?.[sessionConfig.cookieName];
 
@@ -38,26 +49,44 @@ export async function sessionMiddleware(req: Request, res: Response, next: NextF
   }
 
   res.locals.sessionId = sessionId;
+
+  // Refresh is safely wrapped in the breaker internally
   await session.refresh(sessionId);
+
   next();
 }
 
+/** Redis-backed server-side session store. */
 export const session = {
   async start(data: Record<string, unknown> = {}) {
     const client = redisClientIfReady();
     if (!client) return "";
 
-    const id = randomUUID();
-    await client.set(sessionKey(id), JSON.stringify(data), "EX", sessionConfig.ttlSeconds);
-    return id;
+    try {
+      return await sessionBreaker.exec(async () => {
+        const id = randomUUID();
+        await client.set(sessionKey(id), JSON.stringify(data), "EX", sessionConfig.ttlSeconds);
+        return id;
+      });
+    } catch (error) {
+      if (isCircuitBreakerError(error)) return "";
+      return "";
+    }
   },
 
   async all<T = Record<string, unknown>>(id: string): Promise<T | null> {
     const client = redisClientIfReady();
     if (!client) return null;
 
-    const data = await client.get(sessionKey(id));
-    return data ? JSON.parse(data) : null;
+    try {
+      return await sessionBreaker.exec(async () => {
+        const data = await client.get(sessionKey(id));
+        return data ? (JSON.parse(data) as T) : null;
+      });
+    } catch (error) {
+      if (isCircuitBreakerError(error)) return null;
+      return null;
+    }
   },
 
   async get<T>(id: string, key: string): Promise<T | null> {
@@ -69,10 +98,22 @@ export const session = {
     const client = redisClientIfReady();
     if (!client) return false;
 
-    const data = (await session.all<Record<string, unknown>>(id)) || {};
-    data[key] = value;
-    await client.set(sessionKey(id), JSON.stringify(data), "EX", sessionConfig.ttlSeconds);
-    return true;
+    try {
+      return await sessionBreaker.exec(async () => {
+        // Read through the client directly rather than `session.all()`. Calling
+        // another breaker-wrapped method from inside `exec` deadlocks the
+        // half-open probe: the inner call sees the outer probe in flight and
+        // rejects, so a `set` could never be the call that closes the breaker.
+        const raw = await client.get(sessionKey(id));
+        const data = raw ? (JSON.parse(raw) as Record<string, unknown>) : {};
+        data[key] = value;
+        await client.set(sessionKey(id), JSON.stringify(data), "EX", sessionConfig.ttlSeconds);
+        return true;
+      });
+    } catch (error) {
+      if (isCircuitBreakerError(error)) return false;
+      return false;
+    }
   },
 
   /** @deprecated Use set() instead. */
@@ -84,19 +125,33 @@ export const session = {
     const client = redisClientIfReady();
     if (!client) return false;
 
-    await client.expire(sessionKey(id), sessionConfig.ttlSeconds);
-    return true;
+    try {
+      return await sessionBreaker.exec(async () => {
+        await client.expire(sessionKey(id), sessionConfig.ttlSeconds);
+        return true;
+      });
+    } catch (error) {
+      if (isCircuitBreakerError(error)) return false;
+      return false;
+    }
   },
 
   async destroy(id: string) {
     const client = redisClientIfReady();
     if (!client) return false;
 
-    await client.del(sessionKey(id));
-    return true;
+    try {
+      return await sessionBreaker.exec(async () => {
+        await client.del(sessionKey(id));
+        return true;
+      });
+    } catch (error) {
+      if (isCircuitBreakerError(error)) return false;
+      return false;
+    }
   },
 
   isAvailable() {
-    return redisConfig.enabled && redisClientIfReady() !== null;
+    return redisConfig.enabled && redisClientIfReady() !== null && sessionBreaker.getState() !== "open";
   }
 };