create-nexwire 4.2.4 → 4.3.0

package/express/src/framework/scheduler/lock.ts

@@ -1,116 +1,128 @@
-import { randomUUID } from "node:crypto";
-import { redisConfig } from "@/config/index.js";
-import { databaseDialect, databasePool } from "@/framework/database/connection.js";
-import { redis, redisReady } from "@/framework/redis/client.js";
-
-type LockOptions = { ttlMs?: number; tableName?: string };
-
-function table(name?: string) {
-  return name || "scheduler_locks";
-}
-
-async function ensureTable(tableName?: string) {
-  const pool = databasePool();
-  const dialect = databaseDialect();
-  const lockTable = table(tableName);
-
-  if (dialect === "mysql") {
-    await pool.query(
-      `CREATE TABLE IF NOT EXISTS \`${lockTable}\` (name VARCHAR(191) PRIMARY KEY, owner VARCHAR(191) NOT NULL, expires_at BIGINT NOT NULL)`
-    );
-    return;
-  }
-
-  if (dialect === "postgresql") {
-    await pool.unsafe(
-      `CREATE TABLE IF NOT EXISTS "${lockTable}" (name VARCHAR(191) PRIMARY KEY, owner VARCHAR(191) NOT NULL, expires_at BIGINT NOT NULL)`
-    );
-    return;
-  }
-
-  await pool.execute(`CREATE TABLE IF NOT EXISTS "${lockTable}" (name TEXT PRIMARY KEY, owner TEXT NOT NULL, expires_at INTEGER NOT NULL)`);
-}
-
-async function acquireDbLock(name: string, owner: string, ttlMs: number, tableName?: string) {
-  await ensureTable(tableName);
-  const pool = databasePool();
-  const dialect = databaseDialect();
-  const lockTable = table(tableName);
-  const now = Date.now();
-  const expiresAt = now + ttlMs;
-
-  if (dialect === "postgresql") {
-    const rows = await pool.unsafe(
-      `INSERT INTO "${lockTable}" (name, owner, expires_at) VALUES ($1, $2, $3) ON CONFLICT (name) DO UPDATE SET owner = EXCLUDED.owner, expires_at = EXCLUDED.expires_at WHERE "${lockTable}".expires_at < $4 RETURNING owner`,
-      [name, owner, expiresAt, now]
-    );
-    return rows?.[0]?.owner === owner;
-  }
-
-  if (dialect === "mysql") {
-    await pool.query(
-      `INSERT INTO \`${lockTable}\` (name, owner, expires_at) VALUES (?, ?, ?) ON DUPLICATE KEY UPDATE owner = IF(expires_at < ?, VALUES(owner), owner), expires_at = IF(expires_at < ?, VALUES(expires_at), expires_at)`,
-      [name, owner, expiresAt, now, now]
-    );
-    const [rows] = await pool.query(`SELECT owner FROM \`${lockTable}\` WHERE name = ?`, [name]);
-    return rows?.[0]?.owner === owner;
-  }
-
-  await pool.execute({
-    sql: `INSERT INTO "${lockTable}" (name, owner, expires_at) VALUES (?, ?, ?) ON CONFLICT(name) DO UPDATE SET owner = excluded.owner, expires_at = excluded.expires_at WHERE "${lockTable}".expires_at < ?`,
-    args: [name, owner, expiresAt, now]
-  });
-  const result = await pool.execute({
-    sql: `SELECT owner FROM "${lockTable}" WHERE name = ?`,
-    args: [name]
-  });
-  return result.rows?.[0]?.owner === owner;
-}
-
-async function releaseDbLock(name: string, owner: string, tableName?: string) {
-  const pool = databasePool();
-  const dialect = databaseDialect();
-  const lockTable = table(tableName);
-
-  if (dialect === "postgresql") return await pool.unsafe(`DELETE FROM "${lockTable}" WHERE name = $1 AND owner = $2`, [name, owner]);
-  if (dialect === "mysql") return await pool.query(`DELETE FROM \`${lockTable}\` WHERE name = ? AND owner = ?`, [name, owner]);
-  await pool.execute({
-    sql: `DELETE FROM "${lockTable}" WHERE name = ? AND owner = ?`,
-    args: [name, owner]
-  });
-}
-
-/**
- * Why: Runs a handler with distributed lock to prevent duplicate execution.
- * When: Scheduled tasks may run across multiple processes/instances.
- * Where: Scheduler runtime around each cron job.
- * How: Uses Redis NX lock when available, otherwise falls back to DB lock table.
- */
-export async function runWithLock<T>(name: string, handler: () => Promise<T>, options: LockOptions = {}) {
-  const owner = randomUUID();
-  const ttlMs = options.ttlMs || 60_000;
-  const client = redis();
-
-  if (redisReady() && client) {
-    const key = `${redisConfig.prefix}:lock:${name}`;
-    const ok = await client.set(key, owner, "PX", ttlMs, "NX");
-    if (!ok) return { ran: false, backend: "redis" as const };
-
-    try {
-      const result = await handler();
-      return { ran: true, backend: "redis" as const, result };
-    } finally {
-      await client.del(key);
-    }
-  }
-
-  const ok = await acquireDbLock(name, owner, ttlMs, options.tableName);
-  if (!ok) return { ran: false, backend: "db" as const };
-
-  try {
-    const result = await handler();
-    return { ran: true, backend: "db" as const, result };
-  } finally {
-    await releaseDbLock(name, owner, options.tableName);
-  }
-}
+import { randomUUID } from "node:crypto";
+import { redisConfig } from "@/config/index.js";
+import { createCircuitBreaker, isCircuitBreakerError } from "@/framework/circuit-breaker/cb.js";
+import { databaseDialect, databasePool } from "@/framework/database/connection.js";
+import { redis, redisReady } from "@/framework/redis/client.js";
+import { logger } from "@/framework/support/logger.js";
+
+type LockOptions = { ttlMs?: number; tableName?: string };
+
+// Circuit breaker for the Redis Lock
+const lockBreaker = createCircuitBreaker({ name: "Redis Lock", failureThreshold: 3, resetTimeout: 30000 });
+
+function table(name?: string) {
+  return name || "scheduler_locks";
+}
+
+async function ensureTable(tableName?: string) {
+  const pool = databasePool();
+  const dialect = databaseDialect();
+  const lockTable = table(tableName);
+
+  if (dialect === "mysql") {
+    await pool.query(
+      `CREATE TABLE IF NOT EXISTS \`${lockTable}\` (name VARCHAR(191) PRIMARY KEY, owner VARCHAR(191) NOT NULL, expires_at BIGINT NOT NULL)`
+    );
+    return;
+  }
+
+  if (dialect === "postgresql") {
+    await pool.unsafe(
+      `CREATE TABLE IF NOT EXISTS "${lockTable}" (name VARCHAR(191) PRIMARY KEY, owner VARCHAR(191) NOT NULL, expires_at BIGINT NOT NULL)`
+    );
+    return;
+  }
+
+  await pool.execute(`CREATE TABLE IF NOT EXISTS "${lockTable}" (name TEXT PRIMARY KEY, owner TEXT NOT NULL, expires_at INTEGER NOT NULL)`);
+}
+
+async function acquireDbLock(name: string, owner: string, ttlMs: number, tableName?: string) {
+  await ensureTable(tableName);
+  const pool = databasePool();
+  const dialect = databaseDialect();
+  const lockTable = table(tableName);
+  const now = Date.now();
+  const expiresAt = now + ttlMs;
+
+  if (dialect === "postgresql") {
+    const rows = await pool.unsafe(
+      `INSERT INTO "${lockTable}" (name, owner, expires_at) VALUES ($1, $2, $3) ON CONFLICT (name) DO UPDATE SET owner = EXCLUDED.owner, expires_at = EXCLUDED.expires_at WHERE "${lockTable}".expires_at < $4 RETURNING owner`,
+      [name, owner, expiresAt, now]
+    );
+    return rows?.[0]?.owner === owner;
+  }
+
+  if (dialect === "mysql") {
+    await pool.query(
+      `INSERT INTO \`${lockTable}\` (name, owner, expires_at) VALUES (?, ?, ?) ON DUPLICATE KEY UPDATE owner = IF(expires_at < ?, VALUES(owner), owner), expires_at = IF(expires_at < ?, VALUES(expires_at), expires_at)`,
+      [name, owner, expiresAt, now, now]
+    );
+    const [rows] = await pool.query(`SELECT owner FROM \`${lockTable}\` WHERE name = ?`, [name]);
+    return rows?.[0]?.owner === owner;
+  }
+
+  await pool.execute({
+    sql: `INSERT INTO "${lockTable}" (name, owner, expires_at) VALUES (?, ?, ?) ON CONFLICT(name) DO UPDATE SET owner = excluded.owner, expires_at = excluded.expires_at WHERE "${lockTable}".expires_at < ?`,
+    args: [name, owner, expiresAt, now]
+  });
+  const result = await pool.execute({
+    sql: `SELECT owner FROM "${lockTable}" WHERE name = ?`,
+    args: [name]
+  });
+  return result.rows?.[0]?.owner === owner;
+}
+
+async function releaseDbLock(name: string, owner: string, tableName?: string) {
+  const pool = databasePool();
+  const dialect = databaseDialect();
+  const lockTable = table(tableName);
+
+  if (dialect === "postgresql") return await pool.unsafe(`DELETE FROM "${lockTable}" WHERE name = $1 AND owner = $2`, [name, owner]);
+  if (dialect === "mysql") return await pool.query(`DELETE FROM \`${lockTable}\` WHERE name = ? AND owner = ?`, [name, owner]);
+  await pool.execute({
+    sql: `DELETE FROM "${lockTable}" WHERE name = ? AND owner = ?`,
+    args: [name, owner]
+  });
+}
+
+export async function runWithLock<T>(name: string, handler: () => Promise<T>, options: LockOptions = {}) {
+  const owner = randomUUID();
+  const ttlMs = options.ttlMs || 60_000;
+  const client = redis();
+
+  if (redisReady() && client) {
+    try {
+      return await lockBreaker.exec(async () => {
+        const key = `${redisConfig.prefix}:lock:${name}`;
+        const ok = await client.set(key, owner, "PX", ttlMs, "NX");
+        if (!ok) return { ran: false, backend: "redis" as const };
+
+        try {
+          const result = await handler();
+          return { ran: true, backend: "redis" as const, result };
+        } finally {
+          await client.del(key);
+        }
+      });
+    } catch (error) {
+      // If the circuit breaker is open, we log it and fall back to DB lock
+      if (isCircuitBreakerError(error)) {
+        logger.warn(`Redis lock skipped due to circuit breaker for ${name}; falling back to DB`);
+      } else {
+        logger.error(`Redis lock error for ${name}; falling back to DB`, { error });
+      }
+      // Fall through to DB lock
+    }
+  }
+
+  // DB Lock Fallback
+  const ok = await acquireDbLock(name, owner, ttlMs, options.tableName);
+  if (!ok) return { ran: false, backend: "db" as const };
+
+  try {
+    const result = await handler();
+    return { ran: true, backend: "db" as const, result };
+  } finally {
+    await releaseDbLock(name, owner, options.tableName);
+  }
+}

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";
   }
 };