create-nexwire 4.0.0

package/hono/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/hono/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/hono/src/framework/server.ts

@@ -0,0 +1,183 @@
+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, initRealtime, 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 { isBun } from "@/framework/runtime/runtime.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";
+
+/**
+ * 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}`;
+  }
+}
+
+export interface ServerHandle {
+  app: Awaited<ReturnType<typeof createKernel>>["app"];
+  bullBoard: Awaited<ReturnType<typeof createKernel>>["bullBoard"];
+  server: HttpServerHandle;
+  realtime: Awaited<ReturnType<typeof initRealtime>>;
+  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>>;
+  let server: HttpServerHandle;
+
+  if (isBun()) {
+    realtime = await initRealtime({ app });
+    server = await startHttpServer(app, appConfig.port, realtime?.websocketServe);
+  } else {
+    server = await startHttpServer(app, appConfig.port);
+    realtime = await initRealtime({ httpServer: server.native });
+  }
+
+  const socketAdmin = setupSocketAdminUI(realtime?.io ?? null);
+
+  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;
+    }
+    await Promise.allSettled([closeRealtime(), 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()));
+  let redisWarnColor: ((text: string) => string) | null = null;
+  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");
+    }
+  } else {
+    console.log(chalk.gray("UI disabled (disabled in src/config/app.ts)"));
+  }
+
+  const bullboardLine = `${bullBoard.enabled ? "Queue Dashboard enabled" : "Queue Dashboard unavailable"}: ${serverUrl(server, bullBoard.basePath)}`;
+  console.log(redisWarnColor ? redisWarnColor(bullboardLine) : bullboardLine);
+
+  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);
+  }
+
+  if (views.has("studio")) {
+    console.log("Drizzle Studio requested: https://local.drizzle.studio (see dev process status)");
+  }
+
+  const socketLine = !realtimeConfig.enabled
+    ? "Realtime (Socket.IO) disabled"
+    : realtime
+      ? `Realtime (Socket.IO) enabled: ${socketAdmin.enabled ? "Admin UI: https://admin.socket.io" : ""} ${"| " + serverUrl(server, WS_PATH).replace(/^http/, "ws")}`
+      : "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 (!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}`));
+  } 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}`));
+  }
+
+  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/hono/src/framework/session/session.ts

@@ -0,0 +1,116 @@
+import { randomUUID } from "node:crypto";
+import type { Context, Next } from "hono";
+import { getCookie, setCookie } from "hono/cookie";
+import { appConfig, redisConfig, sessionConfig } from "@/config/index.js";
+import { redisClientIfReady } from "@/framework/redis/client.js";
+
+/** Extract origin from a URL string. Returns empty string on invalid/missing input. */
+function originOf(url?: string) {
+  if (!url) return "";
+  try {
+    return new URL(url).origin;
+  } catch {
+    return "";
+  }
+}
+
+/** Returns true when FRONTEND_URL and APP_URL point to different origins — requires SameSite=None; Secure for session cookies. */
+function needsCrossSiteCookie() {
+  const appOrigin = originOf(appConfig.url);
+  const frontendOrigin = originOf(appConfig.frontendUrl);
+  return Boolean(appOrigin && frontendOrigin && appOrigin !== frontendOrigin);
+}
+
+/** Builds the Redis key for a session id using the configured prefix. */
+function sessionKey(id: string) {
+  return `${sessionConfig.keyPrefix}:${id}`;
+}
+
+/**
+ * Global middleware that ensures every request has a session cookie.
+ * - Reads existing session cookie from request.
+ * - If missing: generates a UUID, sets a new cookie (SameSite=None; Secure if cross-origin, else Lax).
+ * - Stores sessionId in Hono context (`c.get("sessionId")`).
+ * - Refreshes the Redis session TTL on every request.
+ */
+export async function sessionMiddleware(c: Context, next: Next) {
+  let sessionId = getCookie(c, sessionConfig.cookieName);
+
+  if (!sessionId) {
+    sessionId = randomUUID();
+    const crossSiteCookie = needsCrossSiteCookie();
+    setCookie(c, sessionConfig.cookieName, sessionId, {
+      httpOnly: true,
+      sameSite: crossSiteCookie ? "None" : "Lax",
+      secure: crossSiteCookie,
+      path: "/",
+      maxAge: sessionConfig.ttlSeconds
+    });
+  }
+
+  c.set("sessionId", sessionId);
+  await session.refresh(sessionId);
+  await next();
+}
+
+/** Redis-backed server-side session store. Each session is a namespaced JSON document with configurable TTL. */
+export const session = {
+  /** Create a new session document in Redis. Returns the generated session id, or empty string when Redis is unavailable. */
+  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;
+  },
+
+  /** Get the full session payload for a given id. Returns null when session doesn't exist or Redis is unavailable. */
+  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;
+  },
+
+  /** Read a single key from the session payload. Returns null if the key or session doesn't exist. */
+  async get<T>(id: string, key: string): Promise<T | null> {
+    const data = await session.all<Record<string, T>>(id);
+    return data?.[key] ?? null;
+  },
+
+  /** Write or update a single key in the session payload. Rewrites the entire document with a fresh TTL. Returns false when Redis is unavailable. */
+  async put(id: string, key: string, value: unknown) {
+    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;
+  },
+
+  /** Extend the TTL of an existing session. Called automatically by sessionMiddleware. Returns false when Redis is unavailable. */
+  async refresh(id: string) {
+    const client = redisClientIfReady();
+    if (!client) return false;
+
+    await client.expire(sessionKey(id), sessionConfig.ttlSeconds);
+    return true;
+  },
+
+  /** Delete a session document from Redis. Use on logout or session expiry. Returns false when Redis is unavailable. */
+  async destroy(id: string) {
+    const client = redisClientIfReady();
+    if (!client) return false;
+
+    await client.del(sessionKey(id));
+    return true;
+  },
+
+  /** Returns true when Redis is enabled and the Redis client is ready — guards against using session store without Redis. */
+  isAvailable() {
+    return redisConfig.enabled && redisClientIfReady() !== null;
+  }
+};