create-nexgen 1.0.4

package/template/src/framework/queue/queue.ts

@@ -0,0 +1,213 @@
+import { Job, Queue, QueueEvents, Worker, type JobsOptions } from "bullmq";
+import { env } from "@/env.js";
+import { discoverModuleFiles, importFile } from "@/framework/modules/discover.js";
+import { redisClientIfReady } from "@/framework/redis/client.js";
+
+export type QueueHandler = (job: Job) => Promise<any>;
+
+const queues = new Map<string, Queue>();
+const events = new Map<string, QueueEvents>();
+const handlers = new Map<string, QueueHandler>();
+const workers: Worker[] = [];
+
+function queuePrefix() {
+  return `${env.REDIS_PREFIX}:queue`;
+}
+
+function key(queue: string, job: string) {
+  return `${queue}:${job}`;
+}
+
+/**
+ * Why: Registers a job handler for a queue + job name.
+ * When: Module job files are loaded during boot.
+ * Where: Module job definition files under `src/modules/<module>/jobs`.
+ * How: Stores handler in an in-memory lookup key.
+ */
+export function shouldQueue(job: string, queue: string, handler: QueueHandler) {
+  handlers.set(key(queue || "default", job), handler);
+}
+
+/**
+ * Why: Gets or lazily creates a BullMQ queue instance.
+ * When: Enqueueing jobs or ensuring queue resources.
+ * Where: Queue facade and dispatcher.
+ * How: Reuses shared Redis connection and memoized queue map.
+ */
+export function getQueue(queue = "default") {
+  const client = redisClientIfReady();
+  if (!client) return null;
+
+  if (!queues.has(queue)) {
+    queues.set(
+      queue,
+      new Queue(queue, {
+        connection: client,
+        prefix: queuePrefix(),
+        defaultJobOptions: {
+          attempts: 3,
+          backoff: { type: "exponential", delay: 3000 },
+          removeOnComplete: 1000,
+          removeOnFail: 5000
+        }
+      })
+    );
+  }
+
+  return queues.get(queue)!;
+}
+
+/**
+ * Why: Facade-friendly alias for getQueue.
+ * When: Consumers want fluent queue access.
+ * Where: Framework facade/API usage.
+ * How: Delegates directly to getQueue.
+ */
+export function queue(queueName = "default") {
+  return getQueue(queueName);
+}
+
+/**
+ * Why: Ensures configured queues exist before UI/runtime usage.
+ * When: BullBoard setup or startup warmup.
+ * Where: Queue UI/bootstrap code.
+ * How: Iterates names and resolves queue instances.
+ */
+export function ensureQueues(queueNames: string[]) {
+  for (const queueName of queueNames) {
+    getQueue(queueName);
+  }
+}
+
+/**
+ * Why: Returns all created queue instances.
+ * When: Queue introspection and dashboard binding.
+ * Where: BullBoard setup code.
+ * How: Converts internal queue map to array.
+ */
+export function getAllQueues() {
+  return Array.from(queues.values());
+}
+
+/**
+ * Why: Adds a job to BullMQ with project defaults.
+ * When: Commands/events need background execution.
+ * Where: Dispatcher and feature modules.
+ * How: Resolves queue then calls add with retry/backoff options.
+ */
+export async function queueJob(
+  job: string,
+  data: any,
+  options: {
+    queue?: string;
+    delay?: number;
+    attempts?: number;
+    jobId?: string;
+    priority?: number;
+    removeOnComplete?: JobsOptions["removeOnComplete"];
+    removeOnFail?: JobsOptions["removeOnFail"];
+    backoff?: JobsOptions["backoff"];
+  } = {}
+) {
+  const queueName = options.queue || "default";
+  const queue = getQueue(queueName);
+  if (!queue) 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 }
+  });
+}
+
+/**
+ * Why: Loads module job files so handlers are registered.
+ * When: Worker start and explicit queue boot flows.
+ * Where: Worker/runtime bootstrap.
+ * How: Discovers jobs glob and imports each file.
+ */
+export async function bootQueueJobs() {
+  const files = await discoverModuleFiles("**/jobs/*.{ts,js}");
+  for (const file of files) await importFile(file);
+  return files.length;
+}
+
+/**
+ * Why: Starts BullMQ workers for selected queues.
+ * When: Queue worker process boots.
+ * Where: Worker runtime entrypoint.
+ * How: Boots handlers, creates QueueEvents, and creates workers.
+ */
+export async function startQueueWorker(queueNames = ["default"]) {
+  await bootQueueJobs();
+  const client = redisClientIfReady();
+  if (!client) throw new Error("Redis is required for queue workers");
+
+  for (const queueName of queueNames) {
+    if (!events.has(queueName)) {
+      events.set(
+        queueName,
+        new QueueEvents(queueName, { connection: client, prefix: queuePrefix() })
+      );
+    }
+
+    const worker = new Worker(
+      queueName,
+      async (job) => {
+        console.log(`[${new Date().toLocaleTimeString()}] 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, 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}`);
+    });
+
+    workers.push(worker);
+  }
+}
+
+/**
+ * Why: Clears queue-related Redis keys for reset workflows.
+ * When: Local cleanup and maintenance commands.
+ * Where: `queue:clear` command.
+ * How: Scans prefixed keys and deletes in batches.
+ */
+export async function clearQueue() {
+  const client = redisClientIfReady();
+  if (!client) return;
+
+  const stream = client.scanStream({ match: `${queuePrefix()}*`, count: 100 });
+  for await (const keys of stream) {
+    if (keys.length) await client.del(keys);
+  }
+}
+
+/**
+ * Why: Gracefully stops all workers/events/queues.
+ * When: Process shutdown.
+ * Where: Server/worker lifecycle hooks.
+ * How: Closes resources with Promise.allSettled and clears registries.
+ */
+export async function stopQueueRuntime() {
+  await Promise.allSettled(workers.map((worker) => worker.close()));
+  workers.length = 0;
+
+  await Promise.allSettled(Array.from(events.values()).map((queueEvents) => queueEvents.close()));
+  events.clear();
+
+  await Promise.allSettled(Array.from(queues.values()).map((queue) => queue.close()));
+  queues.clear();
+}

package/template/src/framework/queue/ui.ts

@@ -0,0 +1,104 @@
+import { createBullBoard } from "@bull-board/api";
+import { BullMQAdapter } from "@bull-board/api/bullMQAdapter";
+import { HonoAdapter } from "@bull-board/hono";
+import { serveStatic } from "@hono/node-server/serve-static";
+import { env } from "@/env.js";
+import { redisClientIfReady } from "@/framework/redis/client.js";
+import { ensureQueues, getAllQueues } from "@/framework/queue/queue.js";
+import { parseCsvOrFallback } from "@/framework/support/lifecycle.js";
+import { authMiddleware } from "@/middlewares/auth-middleware.js";
+
+function redisAvailable() {
+  return redisClientIfReady() !== null;
+}
+
+function allowedBullmqEmails() {
+  const emails = parseCsvOrFallback(env.BULLMQ_UI_ALLOWED_EMAILS, []);
+  return new Set(emails.map((email) => email.toLowerCase()));
+}
+
+/**
+ * Why: Initializes BullBoard dashboard with auth protection.
+ * When: HTTP kernel boots queue UI integration.
+ * Where: Kernel startup and `/bullmq` route mounting.
+ * How: Builds protected route; returns unavailable page when Redis is down.
+ */
+export function setupBullBoard() {
+  const basePath = "/bullmq";
+  const allowedEmails = allowedBullmqEmails();
+
+  const protectRoute = (app: any) => {
+    const guard = async (c: any, next: any) => {
+      const response = await authMiddleware(c, async () => {
+        const auth = c.get("auth");
+        const email = String(auth?.email || "")
+          .trim()
+          .toLowerCase();
+
+        if (allowedEmails.size > 0 && !allowedEmails.has(email)) {
+          return c.json({ message: "Forbidden" }, 403);
+        }
+
+        await next();
+      });
+
+      return response;
+    };
+
+    app.use(basePath, guard);
+    app.use(`${basePath}/*`, guard);
+  };
+
+  if (!redisAvailable()) {
+    const route = (app: any) => {
+      protectRoute(app);
+      app.get(basePath, (c: any) =>
+        c.html(`
+        <!doctype html>
+        <html>
+          <head>
+            <title>Queue Dashboard Unavailable</title>
+            <style>
+              body { font-family: system-ui, sans-serif; padding: 48px; text-align: center; }
+              h1 { color: #dc2626; }
+            </style>
+          </head>
+          <body>
+            <h1>Queue Dashboard Unavailable</h1>
+            <p>Redis is not connected. Check REDIS_URL and make sure Redis is running.</p>
+            <p>Redis URL: ${env.REDIS_URL}</p>
+          </body>
+        </html>
+      `)
+      );
+
+      app.get(`${basePath}/*`, (c: any) => c.redirect(basePath));
+    };
+
+    return { basePath, enabled: false, route };
+  }
+
+  ensureQueues(["default", "mail"]);
+
+  const serverAdapter = new HonoAdapter(serveStatic);
+  serverAdapter.setBasePath(basePath);
+
+  createBullBoard({
+    queues: getAllQueues().map((queue) => new BullMQAdapter(queue)),
+    serverAdapter,
+    options: {
+      uiConfig: {
+        boardTitle: "Queue Dashboard",
+        hideRedisDetails: true
+      }
+    }
+  });
+
+  const pluginRoute = serverAdapter.registerPlugin();
+  const route = (app: any) => {
+    protectRoute(app);
+    app.route(basePath, pluginRoute);
+  };
+
+  return { basePath, enabled: true, route };
+}

package/template/src/framework/queue/worker.ts

@@ -0,0 +1,33 @@
+import { closeRedis, initRedis, redisError, redisReady } from "@/framework/redis/client.js";
+import { startQueueWorker, stopQueueRuntime } from "@/framework/queue/queue.js";
+import { parseCsvOrFallback, registerShutdownSignals, type ShutdownSignal } from "@/framework/support/lifecycle.js";
+import { logger } from "@/framework/support/logger.js";
+
+const queuesArg = process.argv.find((arg) => arg.startsWith("--queue="));
+const queueNames = queuesArg?.split("=")[1];
+const queues = parseCsvOrFallback(queueNames, ["default"]);
+
+await initRedis();
+if (!redisReady()) {
+  logger.error("Queue worker cannot start because Redis is unavailable", {
+    error: redisError()
+  });
+  process.exit(1);
+}
+
+await startQueueWorker(queues);
+console.log(`Queue worker started: ${queues.join(", ")}`);
+
+let shuttingDown = false;
+
+async function shutdown(signal: ShutdownSignal) {
+  if (shuttingDown) return;
+  shuttingDown = true;
+
+  logger.info("Queue worker shutdown signal received", { signal });
+  await Promise.allSettled([stopQueueRuntime(), closeRedis()]);
+
+  process.exit(0);
+}
+
+registerShutdownSignals(shutdown);

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

@@ -0,0 +1,27 @@
+import { socketServer } from "@/framework/realtime/index.js";
+
+export type BroadcastOptions = {
+  users?: Array<string | number>;
+  roles?: string[];
+  rooms?: string[];
+  auth?: boolean;
+  all?: boolean;
+};
+
+/**
+ * Why: Emits realtime events to targeted audiences.
+ * When: Domain events need websocket fan-out.
+ * Where: Event dispatcher and module jobs.
+ * How: Emits to all/auth/users/roles/custom rooms using Socket.IO rooms.
+ */
+export function broadcast(event: string, payload: any, options: BroadcastOptions = {}) {
+  const io = socketServer();
+  if (!io) return;
+
+  if (options.all) io.emit(event, payload);
+  if (options.auth) io.to("auth").emit(event, payload);
+
+  for (const user of options.users || []) io.to(`user:${user}`).emit(event, payload);
+  for (const role of options.roles || []) io.to(`role:${role}`).emit(event, payload);
+  for (const room of options.rooms || []) io.to(room).emit(event, payload);
+}

package/template/src/framework/realtime/index.ts

@@ -0,0 +1 @@
+export { initRealtime, socketServer, closeRealtime } from "@/framework/realtime/socket.js";

package/template/src/framework/realtime/socket-cookie.ts

@@ -0,0 +1,65 @@
+import type { Socket } from "socket.io";
+import { env } from "@/env.js";
+import { jwt } from "@/framework/support/jwt.js";
+import type { RealtimeAuthContext } from "@/framework/realtime/types.js";
+
+export function unauthenticatedRealtimeAuth(): RealtimeAuthContext {
+  return { isAuthenticated: false, userId: null, roles: [], payload: null };
+}
+
+function parseCookieHeader(header: string | undefined) {
+  if (!header) return {} as Record<string, string>;
+
+  const cookies: Record<string, string> = {};
+  for (const part of header.split(";")) {
+    const [rawName, ...rawValue] = part.trim().split("=");
+    if (!rawName || rawValue.length === 0) continue;
+    cookies[rawName] = decodeURIComponent(rawValue.join("="));
+  }
+
+  return cookies;
+}
+
+function userIdFromPayload(payload: Record<string, unknown>) {
+  const candidate = payload.userId ?? payload.id ?? payload.sub;
+  if (candidate === null || candidate === undefined) return null;
+  return String(candidate);
+}
+
+function rolesFromPayload(payload: Record<string, unknown>) {
+  const direct = payload.roles;
+  if (Array.isArray(direct)) return direct.map((role) => String(role));
+
+  const single = payload.role;
+  if (single === null || single === undefined) return [];
+  return [String(single)];
+}
+
+/**
+ * Why: Resolves auth context for websocket connections from cookies.
+ * When: Socket.IO handshake middleware executes.
+ * Where: Realtime server auth pipeline.
+ * How: Parses access cookie, verifies JWT, then normalizes user/role claims.
+ */
+export async function authFromSocketHandshake(socket: Socket): Promise<RealtimeAuthContext> {
+  const cookies = parseCookieHeader(socket.handshake.headers.cookie);
+  const token = cookies[`${env.COOKIE_NAME}_access`];
+
+  if (!token) {
+    return unauthenticatedRealtimeAuth();
+  }
+
+  const payload = await jwt.verifyToken(token, "access");
+  if (!payload) {
+    return unauthenticatedRealtimeAuth();
+  }
+
+  const normalizedPayload = payload as Record<string, unknown>;
+
+  return {
+    isAuthenticated: true,
+    userId: userIdFromPayload(normalizedPayload),
+    roles: rolesFromPayload(normalizedPayload),
+    payload: normalizedPayload
+  };
+}

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

@@ -0,0 +1,132 @@
+import { Server } from "socket.io";
+import { createAdapter } from "@socket.io/redis-adapter";
+import { env } from "@/env.js";
+import { logger } from "@/framework/support/logger.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";
+
+let io: Server | null = null;
+let adapterSubClient: ReturnType<typeof redisClientIfReady> | null = null;
+
+function socketAllowedOrigins() {
+  const origins = [env.APP_URL, env.FRONTEND_URL].filter(Boolean) as string[];
+  if (env.SOCKET) origins.push("https://admin.socket.io");
+  return [...new Set(origins)];
+}
+
+/**
+ * Why: Boots singleton Socket.IO server with auth-aware room assignment.
+ * When: HTTP server starts and realtime is enabled.
+ * Where: Framework server lifecycle.
+ * How: Configures CORS, resolves auth from cookies, and joins role/user rooms.
+ */
+export async function initRealtime(server: any) {
+  if (!env.SOCKET) {
+    logger.info("Socket.IO disabled (SOCKET=false)");
+    return null;
+  }
+
+  if (io) return io;
+
+  io = new Server(server, {
+    cors: {
+      origin: socketAllowedOrigins(),
+      credentials: true
+    }
+  });
+
+  if (env.REDIS) {
+    const pubClient = redisClientIfReady();
+    if (pubClient) {
+      adapterSubClient = pubClient.duplicate();
+      await adapterSubClient.connect();
+      io.adapter(createAdapter(pubClient, adapterSubClient));
+    }
+  }
+
+  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
+      });
+    });
+  });
+
+  return io;
+}
+
+/**
+ * Why: Returns active Socket.IO server instance.
+ * When: Broadcast helpers need emitter access.
+ * Where: Realtime broadcast/event internals.
+ * How: Returns nullable singleton created by initRealtime.
+ */
+export function socketServer() {
+  return io;
+}
+
+/**
+ * Why: Alias for socketServer for facade ergonomics.
+ * When: Existing consumers use `io` naming.
+ * Where: Framework facade export compatibility.
+ * How: Returns same singleton Socket.IO instance.
+ */
+export function ioServer() {
+  return io;
+}
+
+/**
+ * Why: Closes Socket.IO server gracefully on shutdown.
+ * When: Server stop hooks.
+ * Where: Framework runtime teardown.
+ * How: Awaits close callback and clears singleton reference.
+ */
+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/template/src/framework/realtime/types.ts

@@ -0,0 +1,6 @@
+export type RealtimeAuthContext = {
+  isAuthenticated: boolean;
+  userId: string | null;
+  roles: string[];
+  payload: Record<string, unknown> | null;
+};

package/template/src/framework/realtime/ui.ts

@@ -0,0 +1,16 @@
+import { instrument } from "@socket.io/admin-ui";
+import type { Server as SocketIOServer } from "socket.io";
+import { env } from "@/env.js";
+
+export function setupSocketAdminUI(io: SocketIOServer | null) {
+  if (!io || !env.SOCKET || env.APP_ENV === "production") {
+    return { enabled: false };
+  }
+
+  instrument(io, {
+    auth: false,
+    mode: "development"
+  });
+
+  return { enabled: true };
+}