create-nexwire 4.0.0

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

@@ -0,0 +1,68 @@
+import type { Socket } from "socket.io";
+import { cookieConfig } from "@/config/index.js";
+import type { RealtimeAuthContext } from "@/framework/realtime/types.js";
+import { jwt } from "@/framework/support/jwt.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 rawToken = cookies[`${cookieConfig.name}_access`];
+
+  if (!rawToken) {
+    return unauthenticatedRealtimeAuth();
+  }
+
+  // Strip Hono's signed-cookie HMAC signature (last .<base64> part appended by setSignedCookie)
+  const token = rawToken.lastIndexOf(".") > 0 ? rawToken.substring(0, rawToken.lastIndexOf(".")) : rawToken;
+
+  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/hono/src/framework/realtime/socket.ts

@@ -0,0 +1,196 @@
+import { createAdapter } from "@socket.io/redis-adapter";
+import { Server as SocketIOServer } from "socket.io";
+import { appConfig, realtimeConfig, redisConfig } from "@/config/index.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";
+import { isBun } from "@/framework/runtime/runtime.js";
+import { logger } from "@/framework/support/logger.js";
+
+export const WS_PATH = "/socket.io";
+
+/**
+ * Why: Describes runtime-specific WebSocket wiring for the HTTP server adapter.
+ * When: startHttpServer needs Bun websocket handlers from the bun engine.
+ * Where: Cross-runtime server bootstrap.
+ * How: `bun` carries the bun-engine handler's websocket options; `node` attaches
+ *      Socket.IO directly to the http server so no node field is needed.
+ */
+export type RealtimeServeWebSocket = {
+  node?: any;
+  bun?: {
+    websocket: any;
+    idleTimeout?: number;
+    maxRequestBodySize?: number;
+  };
+};
+
+export type RealtimeInit = {
+  io: SocketIOServer;
+  websocketServe: RealtimeServeWebSocket;
+};
+
+let io: SocketIOServer | null = null;
+let adapterSubClient: ReturnType<typeof redisClientIfReady> | null = null;
+let serveWebSocket: RealtimeServeWebSocket = {};
+
+function socketAllowedOrigins() {
+  const origins = [appConfig.url, appConfig.frontendUrl].filter(Boolean) as string[];
+  if (realtimeConfig.enabled) origins.push("https://admin.socket.io");
+  return [...new Set(origins)];
+}
+
+function socketCors() {
+  return { origin: socketAllowedOrigins(), credentials: true };
+}
+
+/**
+ * Why: Attaches the Redis pub/sub adapter so broadcasts span processes.
+ * When: Redis is available at realtime boot.
+ * Where: Realtime bootstrap.
+ * How: Duplicates the shared client for the adapter's subscription leg.
+ */
+async function attachRedisAdapter() {
+  if (!redisConfig.enabled) return;
+
+  const pubClient = redisClientIfReady();
+  if (!pubClient) return;
+
+  adapterSubClient = pubClient.duplicate();
+  await adapterSubClient.connect();
+  io?.adapter(createAdapter(pubClient, adapterSubClient));
+}
+
+/**
+ * Why: Registers auth middleware and connection handling for the singleton.
+ * When: Realtime server is created.
+ * Where: Realtime bootstrap.
+ * How: Resolves auth from handshake cookies and joins user/role/auth rooms.
+ */
+function registerAuthAndRooms() {
+  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
+      });
+    });
+  });
+}
+
+/**
+ * Why: Boots the singleton Socket.IO server with auth-aware room assignment.
+ * When: HTTP server starts and realtime is enabled.
+ * Where: Framework server lifecycle.
+ * How: On node attaches to the created http server; on bun binds the bun-engine
+ *      and registers its `/socket.io` route on the Hono app, returning the
+ *      websocket options the Bun server needs.
+ */
+export async function initRealtime(target: { app?: any; httpServer?: any }): Promise<RealtimeInit | null> {
+  if (!realtimeConfig.enabled) {
+    logger.info("Socket.IO disabled (disabled in config)");
+    return null;
+  }
+
+  if (io) return { io, websocketServe: serveWebSocket };
+
+  if (isBun()) {
+    const { Server: Engine } = await import("@socket.io/bun-engine");
+    const engine = new Engine({ path: WS_PATH, cors: socketCors() });
+    io = new SocketIOServer();
+    io.bind(engine);
+
+    const handler = engine.handler();
+
+    serveWebSocket.bun = {
+      websocket: handler.websocket,
+      idleTimeout: handler.idleTimeout || 120,
+      maxRequestBodySize: handler.maxRequestBodySize || 1024 * 1024
+    };
+
+    // Store engine in app for later use
+    if (target.app) {
+      (target.app as any)._engine = engine;
+    }
+  } else {
+    io = new SocketIOServer(target.httpServer, { cors: socketCors() });
+  }
+
+  await attachRedisAdapter();
+  registerAuthAndRooms();
+
+  logger.info(`Socket.IO enabled at ${WS_PATH}`);
+  return { io, websocketServe: serveWebSocket };
+}
+
+/**
+ * Why: Returns the 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 the Socket.IO server gracefully on shutdown.
+ * When: Server stop hooks.
+ * Where: Framework runtime teardown.
+ * How: Awaits close callback and clears the 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;
+  serveWebSocket = {};
+}

package/hono/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/hono/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 { appConfig, realtimeConfig } from "@/config/index.js";
+
+export function setupSocketAdminUI(io: SocketIOServer | null) {
+  if (!io || !realtimeConfig.enabled || appConfig.environment === "production") {
+    return { enabled: false };
+  }
+
+  instrument(io, {
+    auth: false,
+    mode: "development"
+  });
+
+  return { enabled: true };
+}

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

@@ -0,0 +1,151 @@
+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;
+  }
+}

package/hono/src/framework/runtime/runtime.ts

@@ -0,0 +1,23 @@
+export type Runtime = "node" | "bun" | "unknown";
+
+const runtimeGlobals = globalThis as Record<string, unknown>;
+
+/**
+ * Why: Select the correct driver/flavor when a runtime has specialized packages.
+ * When: Loading DB clients, web servers, and queues that vary per runtime.
+ * Where: Framework bootstrap and driver resolution layers.
+ * How: Inspects global runtime markers (Bun) and falls back to Node/unknown.
+ */
+export function runtime(): Runtime {
+  if (runtimeGlobals.Bun !== undefined) return "bun";
+  if (typeof process !== "undefined" && process.versions?.node) return "node";
+  return "unknown";
+}
+
+export function isBun(): boolean {
+  return runtime() === "bun";
+}
+
+export function isNode(): boolean {
+  return runtime() === "node";
+}

package/hono/src/framework/runtime/server-adapter.ts

@@ -0,0 +1,94 @@
+import type { AddressInfo } from "node:net";
+import type { RealtimeServeWebSocket } from "@/framework/realtime/socket.js";
+import { WS_PATH } from "@/framework/realtime/socket.js";
+import { runtime } from "@/framework/runtime/runtime.js";
+
+export type HttpServerHandle = {
+  address(): string | AddressInfo | null;
+  close(): Promise<void>;
+  native: unknown;
+};
+
+/**
+ * Why: Starts the Hono app on the active runtime's native HTTP server.
+ * When: Server bootstrap after the kernel is created.
+ * Where: Framework server entrypoint.
+ * How: Picks the runtime-appropriate serve (node-server/Bun.serve),
+ *      wires runtime-specific WebSocket primitives when provided, and wraps
+ *      the server in a uniform handle for address/close access.
+ */
+async function startNode(
+  app: { fetch: (request: Request) => Response | Promise<Response> },
+  port: number,
+  websocket?: RealtimeServeWebSocket
+): Promise<HttpServerHandle> {
+  const [{ serve }, { createServer }] = await Promise.all([import("@hono/node-server"), import("node:http")]);
+
+  const server = websocket?.node
+    ? serve({ fetch: app.fetch, port, createServer, websocket: { server: websocket.node } })
+    : serve({ fetch: app.fetch, port, createServer });
+  return {
+    native: server,
+    address: () => server.address(),
+    close: () => new Promise<void>((resolve) => server.close(() => resolve()))
+  };
+}
+
+async function startBun(
+  app: { fetch: (request: Request) => Response | Promise<Response> },
+  port: number,
+  websocket?: RealtimeServeWebSocket
+): Promise<HttpServerHandle> {
+  const globals = globalThis as Record<string, any>;
+
+  let serverInstance: any;
+
+  const serverConfig: any = {
+    fetch: async (req: Request) => {
+      // Check if this is a socket.io request
+      const url = new URL(req.url);
+      if (url.pathname === WS_PATH || url.pathname.startsWith(`${WS_PATH}/`)) {
+        const engine = (app as any)._engine;
+        if (engine) {
+          // Pass the Bun server instance
+          return engine.handleRequest(req, serverInstance);
+        }
+      }
+      return app.fetch(req);
+    },
+    port
+  };
+
+  if (websocket?.bun) {
+    serverConfig.websocket = websocket.bun.websocket;
+    if (websocket.bun.idleTimeout) {
+      serverConfig.idleTimeout = websocket.bun.idleTimeout;
+    }
+    if (websocket.bun.maxRequestBodySize) {
+      serverConfig.maxRequestBodySize = websocket.bun.maxRequestBodySize;
+    }
+  }
+
+  serverInstance = globals.Bun.serve(serverConfig);
+
+  return {
+    native: serverInstance,
+    address: () =>
+      ({
+        address: serverInstance.hostname || "localhost",
+        family: "IPv4",
+        port: serverInstance.port
+      }) as AddressInfo,
+    close: () => Promise.resolve(serverInstance.stop())
+  };
+}
+
+export async function startHttpServer(
+  app: { fetch: (request: Request) => Response | Promise<Response> },
+  port: number,
+  websocket?: RealtimeServeWebSocket
+): Promise<HttpServerHandle> {
+  const activeRuntime = runtime();
+  if (activeRuntime === "bun") return startBun(app, port, websocket);
+  return startNode(app, port, websocket);
+}

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

@@ -0,0 +1,116 @@
+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);
+  }
+}