create-nexwire 4.2.5 → 4.3.0

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

@@ -1,151 +1,148 @@
-import { Redis } from "ioredis";
-import { redisConfig } from "@/config/index.js";
-import { CircuitBreaker } from "@/framework/circuit-breaker/cb.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;
-let redisBreaker: CircuitBreaker | null = null;
-
-if (redisConfig.enabled) {
-  redisBreaker = new CircuitBreaker();
-}
-
-function safeRedisUrl() {
-  try {
-    const url = new URL(redisConfig.url);
-    if (url.password) url.password = "***";
-    return url.toString();
-  } catch {
-    return redisConfig.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 (!redisConfig.enabled) {
-    ready = false;
-    lastError = "redis disabled in config";
-    logger.info("Redis disabled; cache, session storage, queue, events, and cockpit unavailable");
-    return null;
-  }
-
-  if (redisBreaker?.getState() === "open") {
-    lastError = "redis circuit breaker is open";
-    logger.warn("Redis circuit breaker is open; skipping connection");
-    return null;
-  }
-
-  try {
-    client = new Redis(redisConfig.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;
-    redisBreaker?.onSuccess();
-    return client;
-  } catch (error) {
-    lastError ||= error instanceof Error ? error.message : String(error);
-    client?.disconnect();
-    client = null;
-    ready = false;
-    redisBreaker?.onFailure();
-    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() {
-  if (redisBreaker?.getState() === "open") return null;
-  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: Returns the Redis circuit breaker instance or null when disabled.
- * When: Health checks and diagnostics need breaker state.
- * Where: Runtime status and monitoring paths.
- * How: Returns the breaker if Redis is enabled, null otherwise.
- */
-export function getRedisBreaker() {
-  return redisBreaker;
-}
-
-/**
- * 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;
-  }
-}
+import { Redis } from "ioredis";
+import { redisConfig } from "@/config/index.js";
+import { createCircuitBreaker, isCircuitBreakerError } from "@/framework/circuit-breaker/cb.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;
+let redisBreaker: any | null = null;
+
+if (redisConfig.enabled) {
+  redisBreaker = createCircuitBreaker({ name: "Redis", failureThreshold: 3, resetTimeout: 30000 });
+}
+
+function safeRedisUrl() {
+  try {
+    const url = new URL(redisConfig.url);
+    if (url.password) url.password = "***";
+    return url.toString();
+  } catch {
+    return redisConfig.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 (!redisConfig.enabled) {
+    ready = false;
+    lastError = "redis disabled in config";
+    logger.debug("Redis disabled; cache, session storage, queue, events, and cockpit unavailable");
+    return null;
+  }
+
+  try {
+    return await redisBreaker.exec(async () => {
+      client = new Redis(redisConfig.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;
+      logger.debug("Redis connected successfully");
+      return client;
+    });
+  } catch (error) {
+    // Use the functional guard
+    if (isCircuitBreakerError(error)) {
+      lastError = error.message;
+      logger.warn("Redis initialization blocked by circuit breaker");
+    } else {
+      lastError = error instanceof Error ? error.message : String(error);
+      logger.warn(`Redis unavailable; continuing without Redis features (${lastError})`);
+    }
+
+    client?.disconnect();
+    client = null;
+    ready = false;
+    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: Returns the Redis circuit breaker instance or null when disabled.
+ * When: Health checks and diagnostics need breaker state.
+ * Where: Runtime status and monitoring paths.
+ * How: Returns the breaker if Redis is enabled, null otherwise.
+ */
+export function getRedisBreaker() {
+  return redisBreaker;
+}
+
+/**
+ * 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/hono/src/framework/scheduler/lock.ts

@@ -1,116 +1,128 @@
-import { randomUUID } from "node:crypto";
-import { redisConfig } from "@/config/index.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.unsafe(
-      `CREATE TABLE IF NOT EXISTS "${lockTable}" (name VARCHAR(191) PRIMARY KEY, owner VARCHAR(191) NOT NULL, expires_at BIGINT NOT NULL)`
-    );
-    return;
-  }
-
-  await pool.execute(`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 rows = await pool.unsafe(
-      `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 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;
-  }
-
-  await pool.execute({
-    sql: `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 < ?`,
-    args: [name, owner, expiresAt, now]
-  });
-  const result = await pool.execute({
-    sql: `SELECT owner FROM "${lockTable}" WHERE name = ?`,
-    args: [name]
-  });
-  return result.rows?.[0]?.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.unsafe(`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]);
-  await pool.execute({
-    sql: `DELETE FROM "${lockTable}" WHERE name = ? AND owner = ?`,
-    args: [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 = `${redisConfig.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);
-  }
-}
+import { randomUUID } from "node:crypto";
+import { redisConfig } from "@/config/index.js";
+import { createCircuitBreaker, isCircuitBreakerError } from "@/framework/circuit-breaker/cb.js";
+import { databaseDialect, databasePool } from "@/framework/database/connection.js";
+import { redis, redisReady } from "@/framework/redis/client.js";
+import { logger } from "@/framework/support/logger.js";
+
+type LockOptions = { ttlMs?: number; tableName?: string };
+
+// Circuit breaker for the Redis Lock
+const lockBreaker = createCircuitBreaker({ name: "Redis Lock", failureThreshold: 3, resetTimeout: 30000 });
+
+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.unsafe(
+      `CREATE TABLE IF NOT EXISTS "${lockTable}" (name VARCHAR(191) PRIMARY KEY, owner VARCHAR(191) NOT NULL, expires_at BIGINT NOT NULL)`
+    );
+    return;
+  }
+
+  await pool.execute(`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 rows = await pool.unsafe(
+      `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 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;
+  }
+
+  await pool.execute({
+    sql: `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 < ?`,
+    args: [name, owner, expiresAt, now]
+  });
+  const result = await pool.execute({
+    sql: `SELECT owner FROM "${lockTable}" WHERE name = ?`,
+    args: [name]
+  });
+  return result.rows?.[0]?.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.unsafe(`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]);
+  await pool.execute({
+    sql: `DELETE FROM "${lockTable}" WHERE name = ? AND owner = ?`,
+    args: [name, owner]
+  });
+}
+
+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) {
+    try {
+      return await lockBreaker.exec(async () => {
+        const key = `${redisConfig.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);
+        }
+      });
+    } catch (error) {
+      // If the circuit breaker is open, we log it and fall back to DB lock
+      if (isCircuitBreakerError(error)) {
+        logger.warn(`Redis lock skipped due to circuit breaker for ${name}; falling back to DB`);
+      } else {
+        logger.error(`Redis lock error for ${name}; falling back to DB`, { error });
+      }
+      // Fall through to DB lock
+    }
+  }
+
+  // DB Lock Fallback
+  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/hono/src/framework/server.ts

@@ -119,54 +119,52 @@ export async function startServer(): Promise<ServerHandle> {
   }
 
   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.openApiEnabled) {
+    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");
-    }
+    console.log(`UI: ${process.env.NEXWIRE_FRONTEND_URL}`);
   } else {
-    console.log(chalk.gray("UI disabled (disabled in src/config/app.ts)"));
+    console.log(chalk.gray("UI: .env -> UI=false (API-only mode)"));
   }
 
-  const bullboardLine = `${bullBoard.enabled ? "Queue Dashboard enabled" : "Queue Dashboard unavailable"}: ${serverUrl(server, bullBoard.basePath)}`;
-  console.log(redisWarnColor ? redisWarnColor(bullboardLine) : bullboardLine);
+  if (redisConfig.enabled && bullBoard.enabled) {
+    console.log(`Queue: ${serverUrl(server, bullBoard.basePath)}`);
+  }
 
   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);
+    console.log(`MailDev: http://localhost:${mailConfig.maildev.webPort} (SMTP ${mailConfig.maildev.smtpPort})`);
   }
 
   if (views.has("studio")) {
-    console.log("Drizzle Studio requested: https://local.drizzle.studio (see dev process status)");
+    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"));
   }
 
-  const socketLine = !realtimeConfig.enabled
-    ? "Realtime (Socket.IO) disabled"
-    : realtime
-      ? `Realtime (Socket.IO) enabled: ${socketAdmin.enabled ? "Admin UI: https://admin.socket.io" : ""}${socketAdmin.enabled ? " | " : " "}${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 && views.has("redis")) {
+    console.log(`Redis UI: http://localhost:${redisConfig.commanderPort}`);
   }
 
   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}`));
+    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 {
-    redisWarnColor = chalk.yellow;
     console.log(chalk.yellow(`Redis unavailable: ${redisError() || "not connected"}`));
     console.log(chalk.yellow(`Redis-backed services unavailable: ${redisBackedServices}`));
   }