create-nexwire 4.2.5 → 4.4.0

package/fastify/src/framework/scheduler/run.ts

@@ -0,0 +1,48 @@
+import { initDatabase } from "@/framework/database/connection.js";
+import { bootQueueJobs, stopQueueRuntime } from "@/framework/queue/queue.js";
+import { closeRedis, initRedis } from "@/framework/redis/client.js";
+import { startScheduler, stopScheduler } from "@/framework/scheduler/scheduler.js";
+import { registerShutdownSignals, type ShutdownSignal } from "@/framework/support/lifecycle.js";
+import { logger } from "@/framework/support/logger.js";
+
+export interface SchedulerHandle {
+  count: number;
+  shutdown: (signal: ShutdownSignal) => Promise<void>;
+}
+
+/**
+ * Why: Starts the scheduler and wires DB/Redis/queue shutdown.
+ * When: CLI `schedule:work` command or E2E test bootstrap.
+ * Where: Scheduler entrypoint.
+ * How: Inits DB/Redis, boots queue jobs, starts scheduler, registers signals.
+ *      When called as the main module, also prints the startup banner.
+ */
+export async function startSchedulerRuntime(): Promise<SchedulerHandle> {
+  await initDatabase();
+  await initRedis();
+  await bootQueueJobs();
+  const count = await startScheduler();
+  console.log(`Scheduler started [${count} schedule(s)]`);
+
+  let shuttingDown = false;
+
+  async function shutdown(signal: ShutdownSignal) {
+    if (shuttingDown) return;
+    shuttingDown = true;
+
+    logger.info("Scheduler shutdown signal received", { signal });
+    await Promise.allSettled([Promise.resolve(stopScheduler()), stopQueueRuntime()]);
+    await closeRedis();
+
+    process.exit(0);
+  }
+
+  registerShutdownSignals(shutdown);
+
+  return { count, shutdown };
+}
+
+const isMain = process.argv[1]?.endsWith("run.ts") || process.argv[1]?.endsWith("run.js");
+if (isMain) {
+  await startSchedulerRuntime();
+}

package/fastify/src/framework/scheduler/scheduler.ts

@@ -0,0 +1,155 @@
+import { Cron } from "croner";
+import { discoverModuleFiles, importFile } from "@/framework/modules/discover.js";
+import { getQueue } from "@/framework/queue/queue.js";
+import { runWithLock } from "@/framework/scheduler/lock.js";
+
+type Schedule = {
+  name: string;
+  expression: string;
+  handler?: () => void | Promise<void>;
+  /** Queue mode: on each tick dispatches `job` to the given queue for its worker to process. */
+  queue?: string;
+  /** Queue mode: job name enqueued on each tick (defaults to `name`). */
+  job?: string;
+  /** Queue mode: static data passed to every enqueued job. */
+  data?: any;
+  timezone?: string;
+  /** Queue mode: also dispatch one job immediately at scheduler boot. */
+  immediately?: boolean;
+  runOnInit?: boolean;
+  enabled?: boolean;
+  ttlMs?: number;
+};
+
+const schedules: Schedule[] = [];
+const tasks: Cron[] = [];
+
+const PAD = 60;
+
+function pad(str: string, len: number, char = " ") {
+  return str.length >= len ? str : str + char.repeat(len - str.length);
+}
+
+function printHeader() {
+  console.log("");
+  console.log("Running Scheduled Commands");
+  console.log(`${"=".repeat(PAD)}`);
+}
+
+function printScheduleResult(name: string, startMs: number, success: boolean, _message?: string) {
+  const elapsed = ((Date.now() - startMs) / 1000).toFixed(2);
+  const now = new Date().toLocaleString("en-GB", { hour12: true });
+  const dots = ".".repeat(Math.max(1, PAD - name.length - 8));
+  const status = success ? `${elapsed}s` : `FAIL`;
+  console.log(` ${name} ${dots} ${status}`);
+}
+
+/**
+ * Why: Registers a cron schedule definition at runtime.
+ * When: Module console/schedule files are imported.
+ * Where: Scheduler-related module files.
+ * How: Pushes normalized schedule config into in-memory registry. Handler
+ *      schedules run an in-process callback on each tick; queue-mode schedules
+ *      dispatch a job to their queue on each tick. `schedule:work` is the sole
+ *      trigger — queue workers never fire schedules on their own.
+ */
+export function defineSchedule(schedule: Schedule) {
+  const normalized = { enabled: true, runOnInit: false, ttlMs: 120_000, ...schedule };
+  schedules.push(normalized);
+
+  if (normalized.queue) {
+    // nothing to pre-register: schedule:work dispatches on each tick
+  } else if (!normalized.handler) {
+    console.warn(`Schedule "${normalized.name}" has no handler and no queue; nothing will run`);
+  }
+}
+
+/**
+ * Why: Loads module schedule files so schedules are registered.
+ * When: Scheduler boot process starts.
+ * Where: Scheduler worker startup.
+ * How: Discovers schedules/console files and imports them.
+ */
+export async function bootSchedules() {
+  const files = await discoverModuleFiles("**/{schedules,console}/*.{ts,js}");
+  for (const file of files) await importFile(file);
+  return files.length;
+}
+
+function handlerRun(schedule: Schedule) {
+  return async () => {
+    await runWithLock(
+      schedule.name,
+      async () => {
+        const startMs = Date.now();
+        try {
+          await schedule.handler!();
+          printScheduleResult(schedule.name, startMs, true);
+        } catch (err: any) {
+          printScheduleResult(schedule.name, startMs, false, err?.message || String(err));
+        }
+      },
+      { ttlMs: schedule.ttlMs }
+    );
+  };
+}
+
+function queueDispatchRun(schedule: Schedule) {
+  return async () => {
+    await runWithLock(
+      schedule.name,
+      async () => {
+        const startMs = Date.now();
+        try {
+          const queue = getQueue(schedule.queue);
+          if (!queue) throw new Error(`Queue "${schedule.queue}" is unavailable`);
+          await queue.add(schedule.job ?? schedule.name, schedule.data ?? {});
+          printScheduleResult(schedule.name, startMs, true);
+        } catch (err: any) {
+          printScheduleResult(schedule.name, startMs, false, err?.message || String(err));
+        }
+      },
+      { ttlMs: schedule.ttlMs }
+    );
+  };
+}
+
+/**
+ * Why: Starts cron tasks for all enabled schedules.
+ * When: Scheduler worker process boots.
+ * Where: `schedule:work` runtime.
+ * How: Creates a croner task per enabled schedule — handler schedules run the
+ *      callback in-process, queue-mode schedules dispatch a job to their queue
+ *      on each tick (the target worker processes it). Boots once for
+ *      `runOnInit` handlers and `immediately` queue schedules.
+ */
+export async function startScheduler() {
+  await bootSchedules();
+
+  for (const schedule of schedules) {
+    if (!schedule.enabled) continue;
+    const run = schedule.handler ? handlerRun(schedule) : queueDispatchRun(schedule);
+    tasks.push(new Cron(schedule.expression, { timezone: schedule.timezone, name: schedule.name }, run));
+  }
+
+  printHeader();
+
+  for (const schedule of schedules) {
+    if (!schedule.enabled) continue;
+    if (schedule.handler && schedule.runOnInit) await handlerRun(schedule)();
+    if (schedule.queue && schedule.immediately) await queueDispatchRun(schedule)();
+  }
+
+  return schedules.length;
+}
+
+/**
+ * Why: Stops and destroys active cron tasks.
+ * When: Scheduler shutdown.
+ * Where: Process lifecycle handlers.
+ * How: Iterates task registry and invokes stop on each croner job.
+ */
+export async function stopScheduler() {
+  await Promise.all(tasks.map((task) => task.stop()));
+  tasks.length = 0;
+}

package/fastify/src/framework/server.ts

@@ -0,0 +1,162 @@
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import chalk from "chalk";
+import { appConfig, mailConfig, realtimeConfig, redisConfig } from "@/config/index.js";
+import { createKernel } from "@/framework/kernel.js";
+import { stopQueueRuntime } from "@/framework/queue/queue.js";
+import { stopQueueDashboard } from "@/framework/queue/ui.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";
+import { parseCsvOrFallback, registerShutdownSignals, type ShutdownSignal } from "@/framework/support/lifecycle.js";
+import { logger } from "@/framework/support/logger.js";
+
+const redisBackedServices = "cache, session, queue, events, Queue Dashboard";
+
+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}`;
+  }
+}
+
+export interface ServerHandle {
+  app: Awaited<ReturnType<typeof createKernel>>["app"];
+  bullBoard: Awaited<ReturnType<typeof createKernel>>["bullBoard"];
+  server: HttpServerHandle;
+  realtime: any; // Type for Fastify is simpler
+  broadcastSubClient: ReturnType<typeof redisClientIfReady> | null;
+  shutdown: (signal: ShutdownSignal) => Promise<void>;
+  closeHttpServer: () => Promise<void>;
+}
+
+export async function startServer(): Promise<ServerHandle> {
+  const { app, bullBoard } = await createKernel();
+
+  // 1. Start the server (this internally attaches Socket.IO for Fastify)
+  const server = await startHttpServer(app, appConfig.port);
+
+  // 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;
+
+  async function closeHttpServer() {
+    await server.close();
+  }
+
+  async function shutdown(signal: ShutdownSignal) {
+    if (shuttingDown) return;
+    shuttingDown = true;
+
+    logger.info("Shutdown signal received", { signal });
+    if (broadcastSubClient) {
+      try {
+        await broadcastSubClient.quit();
+      } catch {
+        broadcastSubClient.disconnect();
+      }
+      broadcastSubClient = null;
+    }
+
+    // closeRealtime is handled by server.close() adapter
+    await Promise.allSettled([stopQueueRuntime(), closeHttpServer()]);
+    stopQueueDashboard();
+    await closeRedis();
+
+    process.exit(0);
+  }
+
+  registerShutdownSignals(shutdown);
+
+  if (redisConfig.enabled && realtime) {
+    const redis = redisClientIfReady();
+    if (redis) {
+      broadcastSubClient = redis.duplicate();
+      await broadcastSubClient.connect();
+      const channel = `${redisConfig.prefix}:broadcast`;
+      await broadcastSubClient.subscribe(channel);
+      broadcastSubClient.on("message", (_channel: string, message: string) => {
+        try {
+          const { event, payload, options } = JSON.parse(message);
+          if (event) broadcast(event, payload, options);
+        } catch (error) {
+          logger.error("Broadcast relay error", { error });
+        }
+      });
+    }
+  }
+
+  const views = new Set(parseCsvOrFallback(process.env.NEXWIRE_DEV_VIEWS, []).map((view) => view.toLowerCase()));
+
+  if (appConfig.openApiEnabled) {
+    console.log(`API Docs: ${serverUrl(server, "/api-docs")}`);
+  }
+
+  if (appConfig.uiEnabled) {
+    console.log(`UI: ${process.env.NEXWIRE_FRONTEND_URL}`);
+  } else {
+    console.log(chalk.gray("UI: .env -> UI=false (API-only mode)"));
+  }
+
+  if (redisConfig.enabled && bullBoard.enabled) {
+    console.log(`Queue: ${serverUrl(server, bullBoard.basePath)}`);
+  }
+
+  if (views.has("maildev")) {
+    console.log(`MailDev: http://localhost:${mailConfig.maildev.webPort} (SMTP ${mailConfig.maildev.smtpPort})`);
+  }
+
+  if (views.has("studio")) {
+    console.log("Drizzle: https://local.drizzle.studio");
+  }
+
+  const wsUrl = serverUrl(server, WS_PATH).replace(/^http/, "ws");
+  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) {
+    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 {
+    console.log(chalk.yellow(`Redis unavailable: ${redisError() || "not connected"}`));
+    console.log(chalk.yellow(`Redis-backed services unavailable: ${redisBackedServices}`));
+  }
+
+  console.log(`${appConfig.name} API running on ${serverUrl(server)}`);
+
+  return { app, bullBoard, server, realtime, broadcastSubClient, shutdown, closeHttpServer };
+}
+
+const currentFile = fileURLToPath(import.meta.url);
+const isMain = process.argv[1] && path.resolve(process.argv[1]) === path.resolve(currentFile);
+if (isMain) {
+  await startServer();
+}

package/fastify/src/framework/session/session.ts

@@ -0,0 +1,160 @@
+import { randomUUID } from "node:crypto";
+import type { FastifyReply, FastifyRequest } from "fastify";
+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 {
+    return new URL(url).origin;
+  } catch {
+    return "";
+  }
+}
+
+function needsCrossSiteCookie() {
+  const appOrigin = originOf(appConfig.url);
+  const frontendOrigin = originOf(appConfig.frontendUrl);
+  return Boolean(appOrigin && frontendOrigin && appOrigin !== frontendOrigin);
+}
+
+function sessionKey(id: string) {
+  return `${sessionConfig.keyPrefix}:${id}`;
+}
+
+/**
+ * Global hook that ensures every request has a session cookie.
+ *
+ * Runs in an onRequest hook, after `@fastify/cookie` has parsed the header, so
+ * `request.cookies` is available. The session id is exposed on the request for
+ * downstream handlers, mirroring Express's `res.locals.sessionId`.
+ */
+export async function sessionMiddleware(request: FastifyRequest, reply: FastifyReply) {
+  let sessionId = request.cookies?.[sessionConfig.cookieName];
+
+  if (!sessionId) {
+    sessionId = randomUUID();
+    const crossSiteCookie = needsCrossSiteCookie();
+    reply.setCookie(sessionConfig.cookieName, sessionId, {
+      httpOnly: true,
+      sameSite: crossSiteCookie ? "none" : "lax",
+      secure: crossSiteCookie,
+      path: "/",
+      // @fastify/cookie expects maxAge in seconds.
+      maxAge: sessionConfig.ttlSeconds
+    });
+  }
+
+  request.sessionId = sessionId;
+
+  // Refresh is safely wrapped in the breaker internally
+  await session.refresh(sessionId);
+}
+
+/** Redis-backed server-side session store. */
+export const session = {
+  async start(data: Record<string, unknown> = {}) {
+    const client = redisClientIfReady();
+    if (!client) return "";
+
+    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;
+
+    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> {
+    const data = await session.all<Record<string, T>>(id);
+    return data?.[key] ?? null;
+  },
+
+  async set(id: string, key: string, value: unknown) {
+    const client = redisClientIfReady();
+    if (!client) return false;
+
+    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. */
+  async put(id: string, key: string, value: unknown) {
+    return this.set(id, key, value);
+  },
+
+  async refresh(id: string) {
+    const client = redisClientIfReady();
+    if (!client) return false;
+
+    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;
+
+    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 && sessionBreaker.getState() !== "open";
+  }
+};