create-nexwire 4.2.5 → 4.4.0

package/express/src/framework/queue/queue.ts

@@ -1,8 +1,9 @@
 import { type Job, type JobsOptions, Queue, QueueEvents, Worker } from "bullmq";
 import { type DurableContext, type DurableJob, DurableWorker, RedisStateStore } from "bullmq-durable";
-import { queueConfig } from "@/config/index.js";
+import { queueConfig, redisConfig } from "@/config/index.js";
 import { discoverModuleFiles, importFile } from "@/framework/modules/discover.js";
 import { redisClientIfReady } from "@/framework/redis/client.js";
+import { logger } from "@/framework/support/logger.js";
 
 export type QueueJob = {
   name: string;
@@ -10,9 +11,7 @@ export type QueueJob = {
 };
 
 export type QueueHandler = (job: Job) => Promise<any>;
-
 export type DurableQueueHandler = (job: DurableJob, ctx: DurableContext) => Promise<any>;
-
 export type AnyQueueHandler = QueueHandler | DurableQueueHandler;
 
 const queues = new Map<string, Queue>();
@@ -48,6 +47,14 @@ function key(queue: string, job: string) {
   return `${queue}:${job}`;
 }
 
+/**
+ * Why: BullMQ manages its own connections. We pass the URL string,
+ * not the shared client, so BullMQ doesn't crash if the shared client dies.
+ */
+function connectionOptions() {
+  return { url: redisConfig.url };
+}
+
 /**
  * Why: Registers a job handler for a queue + job name.
  * When: Module job files are loaded during boot.
@@ -73,14 +80,14 @@ export function shouldQueue(job: string, queue: string, handler: AnyQueueHandler
  * How: Reuses shared Redis connection and memoized queue map.
  */
 export function getQueue(queue = "default") {
-  const client = redisClientIfReady();
-  if (!client) return null;
+  // Check if Redis is supposed to be enabled
+  if (!redisConfig.enabled) return null;
 
   if (!queues.has(queue)) {
     queues.set(
       queue,
       new Queue(queue, {
-        connection: client as any,
+        connection: connectionOptions(), // Let BullMQ handle its own connection
         prefix: queuePrefix(),
         defaultJobOptions: {
           attempts: 3,
@@ -197,15 +204,20 @@ export async function queueJob(
     return null;
   }
 
-  return await queue.add(job, data, {
-    delay: options.delay ? options.delay * 1000 : 0,
-    attempts: options.attempts ?? 3,
-    jobId: options.jobId,
-    priority: options.priority,
-    removeOnComplete: options.removeOnComplete ?? 1000,
-    removeOnFail: options.removeOnFail ?? 5000,
-    backoff: options.backoff ?? { type: "exponential", delay: 3000 }
-  });
+  try {
+    return await queue.add(job, data, {
+      delay: options.delay ? options.delay * 1000 : 0,
+      attempts: options.attempts ?? 3,
+      jobId: options.jobId,
+      priority: options.priority,
+      removeOnComplete: options.removeOnComplete ?? 1000,
+      removeOnFail: options.removeOnFail ?? 5000,
+      backoff: options.backoff ?? { type: "exponential", delay: 3000 }
+    });
+  } catch (error) {
+    logger.error(`Failed to queue job ${job}`, { error });
+    return null;
+  }
 }
 
 /**
@@ -234,7 +246,7 @@ export async function bootQueueJobs() {
  *      queue's keys on demand if any code path still dispatches to it.
  */
 export async function pruneStaleQueues(protectedQueues: string[] = []) {
-  if (!queueConfig.autoPruneQueues) return;
+  if (!queueConfig.autoPruneQueues || !redisConfig.enabled) return;
 
   const client = redisClientIfReady();
   if (!client) return;
@@ -264,13 +276,13 @@ export async function pruneStaleQueues(protectedQueues: string[] = []) {
         if (live !== 0) continue;
 
         await queue.obliterate({ force: true });
-        console.log(`Pruned stale queue "${name}"`);
+        logger.info(`Pruned stale queue "${name}"`);
       } catch (error: any) {
-        console.warn(`Could not prune stale queue "${name}": ${error?.message || error}`);
+        logger.warn(`Could not prune stale queue "${name}": ${error?.message || error}`);
       }
     }
   } catch (error: any) {
-    console.warn(`Could not scan queues for stale cleanup: ${error?.message || error}`);
+    logger.warn(`Could not scan queues for stale cleanup: ${error?.message || error}`);
   }
 }
 
@@ -282,23 +294,21 @@ export async function pruneStaleQueues(protectedQueues: string[] = []) {
  */
 export async function startQueueWorker(queueNames = ["default"]) {
   await bootQueueJobs();
-  const client = redisClientIfReady();
-  if (!client) throw new Error("Redis is required for queue workers");
+  if (!redisConfig.enabled) throw new Error("Redis is required for queue workers");
 
   for (const queueName of queueNames) {
-    // Already working this queue in this process: a second worker would add a
-    // second blocking connection and a second copy of every log line, and would
-    // never process a job the first one was not already getting.
     if (workedQueues.has(queueName)) continue;
     workedQueues.add(queueName);
 
     if (!events.has(queueName)) {
-      events.set(queueName, new QueueEvents(queueName, { connection: client as any, prefix: queuePrefix() }));
+      // Let BullMQ manage its own connection for events
+      events.set(queueName, new QueueEvents(queueName, { connection: connectionOptions(), prefix: queuePrefix() }));
     }
 
     const durable = [...durableHandlers.keys()].some((k) => k.startsWith(`${queueName}:`));
 
     if (durable) {
+      // Durable worker still needs a shared client for its state store in this specific lib
       const store = durableStateStoreIfReady();
       if (!store) throw new Error("Redis is required for durable queue workers");
 
@@ -311,20 +321,14 @@ export async function startQueueWorker(queueNames = ["default"]) {
       }
 
       const worker = new DurableWorker(queueName, map as never, {
-        connection: client as any,
+        connection: connectionOptions(),
         prefix: queuePrefix(),
         stateStore: store,
         concurrency: 10
       });
 
-      worker.on("completed", (job) => {
-        console.log(`[${new Date().toLocaleTimeString()}] Processed:  ${job.name} (${queueName})`);
-      });
-
-      worker.on("failed", (job, error) => {
-        const jobName = job?.name ?? "unknown";
-        console.log(`[${new Date().toLocaleTimeString()}] Failed:     ${jobName} (${queueName}) - ${error.message}`);
-      });
+      worker.on("completed", (job) => logger.info(`Processed: ${job.name} (${queueName})`));
+      worker.on("failed", (job, error) => logger.warn(`Failed: ${job?.name ?? "unknown"} (${queueName}) - ${error.message}`));
 
       workers.push(worker as unknown as Worker);
       continue;
@@ -333,22 +337,16 @@ export async function startQueueWorker(queueNames = ["default"]) {
     const worker = new Worker(
       queueName,
       async (job) => {
-        console.log(`[${new Date().toLocaleTimeString()}] Processing: ${job.name} (${queueName})`);
+        logger.info(`Processing: ${job.name} (${queueName})`);
         const handler = handlers.get(key(queueName, job.name));
         if (!handler) throw new Error(`No handler registered for ${queueName}:${job.name}`);
         return await handler(job);
       },
-      { connection: client as any, prefix: queuePrefix(), concurrency: 10 }
+      { connection: connectionOptions(), prefix: queuePrefix(), concurrency: 10 }
     );
 
-    worker.on("completed", (job) => {
-      console.log(`[${new Date().toLocaleTimeString()}] Processed:  ${job.name} (${queueName})`);
-    });
-
-    worker.on("failed", (job, error) => {
-      const jobName = job?.name ?? "unknown";
-      console.log(`[${new Date().toLocaleTimeString()}] Failed:     ${jobName} (${queueName}) - ${error.message}`);
-    });
+    worker.on("completed", (job) => logger.info(`Processed: ${job.name} (${queueName})`));
+    worker.on("failed", (job, error) => logger.warn(`Failed: ${job?.name ?? "unknown"} (${queueName}) - ${error.message}`));
 
     workers.push(worker);
   }
@@ -364,6 +362,7 @@ export async function startQueueWorker(queueNames = ["default"]) {
  *      Cache/session/rate-limit keys are intentionally left alone.
  */
 export async function clearQueue() {
+  if (!redisConfig.enabled) return;
   const client = redisClientIfReady();
   if (!client) return;
 

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

@@ -1,6 +1,8 @@
 import { env } from "@/env.js";
+import { createCircuitBreaker, isCircuitBreakerError } from "@/framework/circuit-breaker/cb.js";
 import { socketServer } from "@/framework/realtime/socket.js";
 import { redisClientIfReady } from "@/framework/redis/client.js";
+import { logger } from "@/framework/support/logger.js";
 
 export type BroadcastOptions = {
   users?: Array<string | number>;
@@ -10,6 +12,13 @@ export type BroadcastOptions = {
   all?: boolean;
 };
 
+// Circuit breaker for the pub/sub relay (used by workers that don't have Socket.IO)
+const broadcastBreaker = createCircuitBreaker({
+  name: "Realtime Broadcast Relay",
+  failureThreshold: 3,
+  resetTimeout: 30000
+});
+
 /**
  * Why: Emits realtime events to targeted audiences.
  * When: Domain events need websocket fan-out.
@@ -29,18 +38,33 @@ function emitViaIo(event: string, payload: any, options: BroadcastOptions) {
   for (const room of options.rooms || []) io.to(room).emit(event, payload);
 }
 
-export function broadcast(event: string, payload: any, options: BroadcastOptions = {}) {
+export async function broadcast(event: string, payload: any, options: BroadcastOptions = {}) {
   const io = socketServer();
 
+  // If this process has Socket.IO (the main API server), emit directly
   if (io) {
-    emitViaIo(event, payload, options);
+    try {
+      emitViaIo(event, payload, options);
+    } catch (error) {
+      logger.error("Failed to broadcast event via Socket.IO", { error, event });
+    }
     return;
   }
 
-  // No Socket.IO in this process — relay through Redis so the main process can broadcast
+  // If this is a background worker, relay through Redis
   const redis = redisClientIfReady();
   if (!redis) return;
 
-  const channel = `${env.REDIS_PREFIX}:broadcast`;
-  redis.publish(channel, JSON.stringify({ event, payload, options }));
+  try {
+    await broadcastBreaker.exec(async () => {
+      const channel = `${env.REDIS_PREFIX}:broadcast`;
+      await redis.publish(channel, JSON.stringify({ event, payload, options }));
+    });
+  } catch (error) {
+    if (isCircuitBreakerError(error)) {
+      logger.warn("Broadcast relay skipped: Circuit breaker is open");
+    } else {
+      logger.error("Failed to relay broadcast via Redis", { error, event });
+    }
+  }
 }

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