create-nexgen 1.0.4

package/template/src/framework/redis/client.ts

@@ -0,0 +1,126 @@
+import { Redis } from "ioredis";
+import { env } from "@/env.js";
+import { logger } from "@/framework/support/logger.js";
+
+export type redis = Redis;
+
+let client: redis | null = null;
+let ready = false;
+let lastError: string | null = null;
+
+function safeRedisUrl() {
+  try {
+    const url = new URL(env.REDIS_URL);
+    if (url.password) url.password = "***";
+    return url.toString();
+  } catch {
+    return env.REDIS_URL;
+  }
+}
+
+/**
+ * Why: Initializes shared Redis connection for cache/queue/events/session.
+ * When: Runtime bootstrap before Redis-backed features are used.
+ * Where: Server, worker, scheduler startup paths.
+ * How: Connects once, tracks readiness, and degrades gracefully if unavailable.
+ */
+export async function initRedis() {
+  if (client) return client;
+
+  if (!env.REDIS) {
+    ready = false;
+    lastError = "REDIS=false";
+    logger.info("Redis disabled; cache, session storage, queue, events, and BullBoard unavailable");
+    return null;
+  }
+
+  try {
+    client = new Redis(env.REDIS_URL, {
+      lazyConnect: true,
+      enableReadyCheck: true,
+      maxRetriesPerRequest: 0,
+      retryStrategy: () => null
+    });
+
+    client.on("error", (error) => {
+      lastError = error.message;
+      if (ready) {
+        logger.warn("Redis connection error", {
+          redisUrl: safeRedisUrl(),
+          error: error.message
+        });
+      }
+    });
+
+    await client.connect();
+    await client.ping();
+    ready = true;
+    return client;
+  } catch (error) {
+    lastError ||= error instanceof Error ? error.message : String(error);
+    client?.disconnect();
+    client = null;
+    ready = false;
+    logger.warn(`Redis unavailable; continuing without Redis features (${lastError})`);
+    return null;
+  }
+}
+
+/**
+ * Why: Returns the current Redis client instance.
+ * When: Internal helpers need direct Redis operations.
+ * Where: Cache/session/queue/events modules.
+ * How: Returns nullable singleton without creating a new connection.
+ */
+export function redis() {
+  return client;
+}
+
+/**
+ * Why: Indicates whether Redis is connected and usable.
+ * When: Features need to branch on Redis availability.
+ * Where: Cache/session/queue/event internals.
+ * How: Combines readiness flag with client presence.
+ */
+export function redisReady() {
+  return ready && client !== null;
+}
+
+/**
+ * Why: Provides a single ready-checked Redis client accessor.
+ * When: Redis-backed modules need quick availability guard.
+ * Where: Cache/session/queue/events/BullBoard internals.
+ * How: Returns connected client or null when Redis is unavailable.
+ */
+export function redisClientIfReady() {
+  return redisReady() ? client : null;
+}
+
+/**
+ * Why: Exposes last Redis error for diagnostics.
+ * When: Startup or health logs need failure detail.
+ * Where: Runtime status output.
+ * How: Returns cached error message string.
+ */
+export function redisError() {
+  return lastError;
+}
+
+/**
+ * Why: Closes Redis connection during graceful shutdown.
+ * When: Process stop hooks for server/worker/scheduler.
+ * Where: Runtime lifecycle files.
+ * How: Attempts quit, falls back to disconnect, then resets state.
+ */
+export async function closeRedis() {
+  if (!client) return;
+
+  try {
+    await client.quit();
+  } catch {
+    client.disconnect();
+  } finally {
+    client = null;
+    ready = false;
+  }
+}

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

@@ -0,0 +1,124 @@
+import { randomUUID } from "node:crypto";
+import { env } from "@/env.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.query(
+      `CREATE TABLE IF NOT EXISTS "${lockTable}" (name VARCHAR(191) PRIMARY KEY, owner VARCHAR(191) NOT NULL, expires_at BIGINT NOT NULL)`
+    );
+    return;
+  }
+
+  pool.exec(
+    `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 result = await pool.query(
+      `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 result.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;
+  }
+
+  pool
+    .prepare(
+      `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 < ?`
+    )
+    .run(name, owner, expiresAt, now);
+  return pool.prepare(`SELECT owner FROM "${lockTable}" WHERE name = ?`).get(name)?.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.query(`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
+    ]);
+  return pool.prepare(`DELETE FROM "${lockTable}" WHERE name = ? AND owner = ?`).run(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 = `${env.REDIS_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);
+  }
+}

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

@@ -0,0 +1,26 @@
+import { initDatabase } from "@/framework/database/connection.js";
+import { stopQueueRuntime, bootQueueJobs } 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";
+
+await initDatabase();
+await initRedis();
+await bootQueueJobs();
+await startScheduler();
+console.log("Scheduler started");
+
+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(), closeRedis()]);
+
+  process.exit(0);
+}
+
+registerShutdownSignals(shutdown);

package/template/src/framework/scheduler/scheduler.ts

@@ -0,0 +1,82 @@
+import cron from "node-cron";
+import { discoverModuleFiles, importFile } from "@/framework/modules/discover.js";
+import { runWithLock } from "@/framework/scheduler/lock.js";
+
+type Schedule = {
+  name: string;
+  expression: string;
+  handler: () => void | Promise<void>;
+  timezone?: string;
+  runOnInit?: boolean;
+  enabled?: boolean;
+  ttlMs?: number;
+};
+
+const schedules: Schedule[] = [];
+const tasks: Array<{ stop: () => void; destroy?: () => void }> = [];
+
+/**
+ * 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.
+ */
+export function defineSchedule(schedule: Schedule) {
+  schedules.push({ enabled: true, runOnInit: false, ttlMs: 120_000, ...schedule });
+}
+
+/**
+ * Why: Loads module schedule files so jobs 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;
+}
+
+/**
+ * Why: Starts cron tasks for all enabled schedules.
+ * When: Scheduler worker process boots.
+ * Where: `schedule:work` runtime.
+ * How: Wraps each handler with distributed lock and schedules via node-cron.
+ */
+export async function startScheduler() {
+  await bootSchedules();
+
+  for (const schedule of schedules) {
+    if (!schedule.enabled) continue;
+
+    const run = () =>
+      runWithLock(
+        schedule.name,
+        async () => {
+          await schedule.handler();
+        },
+        { ttlMs: schedule.ttlMs }
+      );
+
+    const task = cron.schedule(schedule.expression, run, { timezone: schedule.timezone });
+    tasks.push(task);
+    if (schedule.runOnInit) await run();
+  }
+
+  return schedules.length;
+}
+
+/**
+ * Why: Stops and destroys active cron tasks.
+ * When: Scheduler shutdown.
+ * Where: Process lifecycle handlers.
+ * How: Iterates task registry and invokes stop/destroy.
+ */
+export function stopScheduler() {
+  for (const task of tasks) {
+    task.stop();
+    task.destroy?.();
+  }
+
+  tasks.length = 0;
+}

package/template/src/framework/server.ts

@@ -0,0 +1,147 @@
+import { serve } from "@hono/node-server";
+import type { AddressInfo } from "node:net";
+import { createServer } from "node:http";
+import chalk from "chalk";
+import { env } from "@/env.js";
+import { createKernel } from "@/framework/kernel.js";
+import { stopQueueRuntime } from "@/framework/queue/queue.js";
+import { closeRealtime, initRealtime } from "@/framework/realtime/index.js";
+import { setupSocketAdminUI } from "@/framework/realtime/ui.js";
+import { closeRedis, redisError, redisReady } from "@/framework/redis/client.js";
+import { parseCsvOrFallback, registerShutdownSignals, type ShutdownSignal } from "@/framework/support/lifecycle.js";
+import { logger } from "@/framework/support/logger.js";
+
+const redisBackedServices = "cache, session, queue, events, BullBoard";
+
+/**
+ * Why: Builds reliable local URL string for runtime service output.
+ * When: Printing API/docs/BullBoard endpoints at startup.
+ * Where: Server runtime logging.
+ * How: Derives bound port from server address and normalizes hostname.
+ */
+function serverUrl(server: { address(): string | AddressInfo | null; }, pathname = "") {
+  const address = server.address();
+  const port = typeof address === "object" && address ? address.port : env.APP_PORT;
+
+  try {
+    const currentUrl = new URL(env.APP_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}`;
+  }
+}
+
+const { app, bullBoard } = await createKernel();
+
+/**
+ * Why: Parses optional dev sidecar views requested by dev command.
+ * When: Server starts and prints local tooling URLs.
+ * Where: Runtime startup output logic.
+ * How: Reads `NEXGEN_DEV_VIEWS` comma-separated env and returns a set.
+ */
+function devViews() {
+  return new Set(parseCsvOrFallback(process.env.NEXGEN_DEV_VIEWS, []).map((view) => view.toLowerCase()));
+}
+
+const server = serve({
+  fetch: app.fetch,
+  port: env.APP_PORT,
+  createServer
+});
+
+let shuttingDown = false;
+
+/**
+ * Why: Gracefully closes HTTP server listener.
+ * When: Shutdown signal handling.
+ * Where: Server runtime teardown.
+ * How: Wraps callback-based close in a promise.
+ */
+async function closeHttpServer() {
+  await new Promise<void>((resolve) => {
+    server.close(() => resolve());
+  });
+}
+
+/**
+ * Why: Coordinates full process shutdown for API runtime.
+ * When: SIGINT/SIGTERM received.
+ * Where: Server entrypoint lifecycle.
+ * How: Stops realtime/events/queue/redis/http resources then exits.
+ */
+async function shutdown(signal: ShutdownSignal) {
+  if (shuttingDown) return;
+  shuttingDown = true;
+
+  logger.info("Shutdown signal received", { signal });
+  await Promise.allSettled([
+    closeRealtime(),
+    stopQueueRuntime(),
+    closeRedis(),
+    closeHttpServer()
+  ]);
+
+  process.exit(0);
+}
+
+registerShutdownSignals(shutdown);
+
+const io = await initRealtime(server);
+const socketAdmin = setupSocketAdminUI(io);
+const views = devViews();
+let redisWarnColor: ((text: string) => string) | null = null;
+console.log(`API Docs: ${serverUrl(server, "/api-docs")}`);
+
+if (views.has("studio")) {
+  console.log("Drizzle Studio requested: https://local.drizzle.studio (see dev process status)");
+}
+
+if (!env.REDIS) {
+  redisWarnColor = chalk.cyan;
+  console.log(chalk.cyan("Redis disabled (REDIS=false)"));
+  console.log(chalk.cyan(`Redis-backed services disabled: ${redisBackedServices}`));
+} else if (redisReady()) {
+  console.log(chalk.green(`Redis connected: ${env.REDIS_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}`));
+}
+
+const bullboardLine = `${bullBoard.enabled ? "BullBoard UI enabled" : "BullBoard UI unavailable"}: ${serverUrl(server, bullBoard.basePath)}`;
+console.log(redisWarnColor ? redisWarnColor(bullboardLine) : bullboardLine);
+
+const socketLine = env.SOCKET
+  ? `Socket.IO enabled: ${env.APP_URL}${socketAdmin.enabled ? " | Admin UI: https://admin.socket.io" : ""}`
+  : "Socket.IO disabled";
+console.log(socketLine);
+
+if (views.has("maildev")) {
+  const maildevLine = `MailDev: http://localhost:${env.MAILDEV_WEB_PORT} (SMTP ${env.MAIL_PORT})`;
+  const line = `${maildevLine} (requested; see dev process status)`;
+  console.log(redisWarnColor ? redisWarnColor(line) : line);
+}
+
+if (views.has("redis")) {
+  const redisUiLine = `Redis UI: http://localhost:${env.REDIS_COMMANDER_PORT}`;
+  const line = `${redisUiLine} (requested; see dev process status)`;
+  console.log(redisWarnColor ? redisWarnColor(line) : line);
+}
+
+if (env.FRONTEND) {
+  if (process.env.NEXGEN_FRONTEND_URL) {
+    console.log("Frontend UI: " + process.env.NEXGEN_FRONTEND_URL);
+  } else {
+    console.log("Frontend enabled");
+  }
+} else {
+  console.log("Frontend disabled (FRONTEND=false)");
+}
+
+console.log(`${env.APP_NAME} API running on ${serverUrl(server)}`);

package/template/src/framework/session/session.ts

@@ -0,0 +1,116 @@
+import type { Context, Next } from "hono";
+import { getCookie, setCookie } from "hono/cookie";
+import { randomUUID } from "node:crypto";
+import { env } from "@/env.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(env.APP_URL);
+  const frontendOrigin = originOf(env.FRONTEND_URL);
+  return Boolean(appOrigin && frontendOrigin && appOrigin !== frontendOrigin);
+}
+
+/** Builds the Redis key for a session id using the configured prefix. */
+function sessionKey(id: string) {
+  return `${env.REDIS_PREFIX}:session:${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, env.SESSION_COOKIE);
+
+  if (!sessionId) {
+    sessionId = randomUUID();
+    const crossSiteCookie = needsCrossSiteCookie();
+    setCookie(c, env.SESSION_COOKIE, sessionId, {
+      httpOnly: true,
+      sameSite: crossSiteCookie ? "None" : "Lax",
+      secure: crossSiteCookie,
+      path: "/",
+      maxAge: env.SESSION_TTL_SECONDS
+    });
+  }
+
+  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", env.SESSION_TTL_SECONDS);
+    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", env.SESSION_TTL_SECONDS);
+    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), env.SESSION_TTL_SECONDS);
+    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 env.REDIS && redisClientIfReady() !== null;
+  }
+};