create-nexwire 4.0.0

package/hono/src/framework/events/dispatcher.ts

@@ -0,0 +1,49 @@
+import { queueJob } from "@/framework/queue/queue.js";
+import { type BroadcastOptions, broadcast } from "@/framework/realtime/broadcast.js";
+
+type CommandHandler = (payload: any) => Promise<any>;
+
+const commandHandlers = new Map<string, CommandHandler>();
+
+/**
+ * Why: Registers in-memory command handler for synchronous dispatch.
+ * When: Module startup files register command handlers.
+ * Where: Job/command style module code.
+ * How: Stores handler in a process-level map by command name.
+ */
+export function command(name: string, handler: CommandHandler) {
+  commandHandlers.set(name, handler);
+}
+
+/**
+ * Why: Executes command immediately or queues it for async processing.
+ * When: Application logic needs command pattern behavior.
+ * Where: Controllers, jobs, and service layers.
+ * How: Runs local handler unless async requested; otherwise enqueues.
+ */
+export async function dispatchCommand(name: string, payload: any, options: { async?: boolean; queue?: string } = {}) {
+  if (!options.async) {
+    const handler = commandHandlers.get(name);
+    if (handler) return await handler(payload);
+  }
+
+  return await queueJob(name, payload, { queue: options.queue || "default" });
+}
+
+/**
+ * Why: Dispatches domain events with optional queueing and websocket fan-out.
+ * When: Domain actions need side effects or realtime notifications.
+ * Where: Controllers/jobs across modules.
+ * How: Broadcasts via Socket.IO and optionally enqueues job.
+ */
+export async function dispatchEvent(name: string, payload: any, options: { queue?: boolean | string; broadcast?: BroadcastOptions } = {}) {
+  if (options.broadcast) {
+    broadcast(name, payload, options.broadcast);
+  }
+
+  if (options.queue) {
+    return await queueJob(name, payload, {
+      queue: typeof options.queue === "string" ? options.queue : "default"
+    });
+  }
+}

package/hono/src/framework/facade.ts

@@ -0,0 +1,29 @@
+/**
+ * Why: Central public API surface for framework consumers.
+ * When: Modules/middlewares need framework utilities.
+ * Where: App-layer imports should target this file.
+ * How: Re-exports stable, reusable helpers while hiding setup internals.
+ */
+
+export { createRoute, z } from "@hono/zod-openapi";
+export * as lodash from "lodash-es";
+export * as HttpStatusCodes from "stoker/http-status-codes";
+export { jsonContent } from "stoker/openapi/helpers";
+export { cache } from "@/framework/cache/cache.js";
+export { database, db } from "@/framework/database/connection.js";
+export { type PaginatedResult, paginate, paginateModel, paginateQuery, paginateTable } from "@/framework/database/paginate.js";
+export { command, dispatchCommand, dispatchEvent } from "@/framework/events/dispatcher.js";
+export { createRouter, group } from "@/framework/http/router.js";
+export { validate } from "@/framework/http/validation.js";
+export { notify } from "@/framework/notification/index.js";
+export { queue, queueJob, shouldQueue } from "@/framework/queue/queue.js";
+export { broadcast } from "@/framework/realtime/index.js";
+export { defineSchedule } from "@/framework/scheduler/scheduler.js";
+export { session } from "@/framework/session/session.js";
+export { storage } from "@/framework/storage/storage.js";
+export { cookie } from "@/framework/support/cookie.js";
+export { jwt } from "@/framework/support/jwt.js";
+export { logger } from "@/framework/support/logger.js";
+export { mail } from "@/framework/support/mail.js";
+export { password } from "@/framework/support/password.js";
+export { urls } from "@/framework/support/url.js";

package/hono/src/framework/http/app.ts

@@ -0,0 +1,109 @@
+import { createRoute, z } from "@hono/zod-openapi";
+import { appConfig, redisConfig } from "@/config/index.js";
+import { database } from "@/framework/database/connection.js";
+import { corsMiddleware } from "@/framework/http/cors.js";
+import { loggerMiddleware, notFound, onError } from "@/framework/http/logger.js";
+import { getMetrics, incrementRequestCount } from "@/framework/http/metrics.js";
+import { configureOpenApi } from "@/framework/http/openapi.js";
+import { rateLimiterMiddleware } from "@/framework/http/ratelimiter.js";
+import { createRouter } from "@/framework/http/router.js";
+import { securityMiddleware } from "@/framework/http/security.js";
+import { hasUiBuild, storageStaticMiddleware } from "@/framework/http/static.js";
+import { redisClientIfReady } from "@/framework/redis/client.js";
+import { sessionMiddleware } from "@/framework/session/session.js";
+
+/**
+ * Why: Builds the main HTTP app with middleware, health, and error handlers.
+ * When: Kernel creates application server instance.
+ * Where: Framework bootstrap path.
+ * How: Composes router, optional OpenAPI, middleware stack, and fallbacks.
+ */
+export function createHttpApp() {
+  const app = createRouter();
+
+  const healthRoute = createRoute({
+    path: "/health",
+    method: "get",
+    tags: ["System"],
+    responses: {
+      200: {
+        description: "Application health status",
+        content: {
+          "application/json": {
+            schema: z.object({ message: z.string() })
+          }
+        }
+      }
+    }
+  });
+
+  if (appConfig.openApiEnabled) {
+    configureOpenApi(app);
+    app.api(healthRoute, (c: any) => c.json({ message: "Application is healthy" }));
+  }
+
+  app.use("*", sessionMiddleware);
+  app.use("*", corsMiddleware);
+  app.use("*", securityMiddleware);
+  app.use("*", async (_c, next) => {
+    incrementRequestCount();
+    await next();
+  });
+  app.use("*", loggerMiddleware);
+  app.use("*", rateLimiterMiddleware);
+  app.use("/storage/*", storageStaticMiddleware);
+
+  app.get("/ready", (c) => {
+    const checks: Record<string, string> = {};
+    let allOk = true;
+    try {
+      database();
+      checks["database"] = "ok";
+    } catch {
+      checks["database"] = "error";
+      allOk = false;
+    }
+    if (redisConfig.enabled) {
+      if (redisClientIfReady()) {
+        checks["redis"] = "ok";
+      } else {
+        checks["redis"] = "error";
+        allOk = false;
+      }
+    } else {
+      checks["redis"] = "disabled";
+    }
+    const status = allOk ? 200 : 503;
+    return c.json({ status: allOk ? "ready" : "not_ready", checks }, status);
+  });
+
+  app.get("/live", (c) => {
+    return c.json({ status: "alive" });
+  });
+
+  app.get("/metrics", (c) => {
+    const m = getMetrics();
+    const output = [
+      "# HELP http_requests_total Total HTTP requests",
+      "# TYPE http_requests_total counter",
+      `http_requests_total ${m.requestCount}`,
+      "# HELP http_errors_total Total HTTP errors",
+      "# TYPE http_errors_total counter",
+      `http_errors_total ${m.errorCount}`
+    ].join("\n");
+    return c.body(output, 200, { "content-type": "text/plain" });
+  });
+
+  if (!hasUiBuild()) {
+    app.get("/", (c: any) => c.json({ name: appConfig.name, ok: true }));
+  }
+
+  if (!appConfig.openApiEnabled) {
+    app.get("/health", (c: any) => c.json({ message: "Application is healthy" }));
+  }
+
+  app.notFound(notFound);
+  app.onError(onError);
+
+  return app;
+}

package/hono/src/framework/http/cors.ts

@@ -0,0 +1,19 @@
+import { cors } from "hono/cors";
+import { corsConfig } from "@/config/index.js";
+import { parseCsvOrFallback } from "@/framework/support/lifecycle.js";
+
+const corsOrigins = parseCsvOrFallback(corsConfig.origin, []);
+
+/**
+ * Why: Applies credential-aware CORS policy.
+ * When: Global HTTP middleware processing.
+ * Where: App middleware stack.
+ * How: Reflects origin for wildcard mode or validates against allowlist.
+ */
+export const corsMiddleware = cors({
+  origin: (origin) => {
+    if (corsConfig.origin === "*") return origin;
+    return corsOrigins.includes(origin) ? origin : undefined;
+  },
+  credentials: true
+});

package/hono/src/framework/http/logger.ts

@@ -0,0 +1,81 @@
+import type { Context, Next } from "hono";
+import { loggingConfig } from "@/config/index.js";
+import { logger } from "@/framework/support/logger.js";
+
+function ip(c: Context) {
+  return c.req.header("cf-connecting-ip") || c.req.header("x-forwarded-for") || c.req.header("x-real-ip") || null;
+}
+
+function shouldSkipHttpLog(pathname: string) {
+  return pathname.startsWith("/queues");
+}
+
+/**
+ * Why: Logs each HTTP request with latency and request metadata.
+ * When: Applied globally to app routes.
+ * Where: HTTP middleware stack.
+ * How: Captures start time, assigns request id, logs after downstream response.
+ */
+export async function loggerMiddleware(c: Context, next: Next) {
+  const start = Date.now();
+  const requestId = crypto.randomUUID();
+
+  c.set("requestId", requestId);
+  await next();
+
+  if (!loggingConfig.httpRequests || shouldSkipHttpLog(c.req.path)) {
+    return;
+  }
+
+  logger.info("HTTP Request", {
+    requestId,
+    method: c.req.method,
+    path: c.req.path,
+    url: c.req.url,
+    status: c.res.status,
+    duration_ms: Date.now() - start,
+    ip: ip(c),
+    userAgent: c.req.header("user-agent") || null
+  });
+}
+
+/**
+ * Why: Standard 404 handler with structured log context.
+ * When: No route matches request path.
+ * Where: App notFound handler registration.
+ * How: Emits warning log and returns JSON 404 payload.
+ */
+export function notFound(c: Context) {
+  logger.warn("404 Not Found", {
+    requestId: c.get("requestId") || null,
+    method: c.req.method,
+    path: c.req.path,
+    url: c.req.url,
+    ip: ip(c),
+    userAgent: c.req.header("user-agent") || null
+  });
+
+  return c.json({ message: "Not Found" }, 404);
+}
+
+/**
+ * Why: Centralized unhandled error responder and logger.
+ * When: Route/middleware throws uncaught error.
+ * Where: App onError handler registration.
+ * How: Logs stack + request context and returns status/message JSON.
+ */
+export function onError(error: any, c: Context) {
+  logger.error("Unhandled Application Error", {
+    requestId: c.get("requestId") || null,
+    name: error?.name || "Error",
+    message: error?.message,
+    stack: error?.stack,
+    method: c.req.method,
+    path: c.req.path,
+    url: c.req.url,
+    ip: ip(c),
+    userAgent: c.req.header("user-agent") || null
+  });
+
+  return c.json({ message: error?.message || "Internal Server Error" }, error?.status || 500);
+}

package/hono/src/framework/http/metrics.ts

@@ -0,0 +1,22 @@
+let requestCount = 0;
+let errorCount = 0;
+
+export function incrementRequestCount() {
+  requestCount++;
+}
+
+export function incrementErrorCount() {
+  errorCount++;
+}
+
+export function resetMetrics() {
+  requestCount = 0;
+  errorCount = 0;
+}
+
+export function getMetrics() {
+  return {
+    requestCount,
+    errorCount
+  };
+}

package/hono/src/framework/http/openapi.ts

@@ -0,0 +1,42 @@
+import fs from "node:fs";
+import path from "node:path";
+import { Scalar } from "@scalar/hono-api-reference";
+import { openApiConfig } from "@/config/index.js";
+import type { NexwireRouter } from "@/framework/http/router.js";
+
+/**
+ * Why: Registers OpenAPI document and interactive docs UI.
+ * When: OPEN_API is enabled during app boot.
+ * Where: HTTP app setup.
+ * How: Exposes `/doc` spec and `/api-docs` Scalar viewer.
+ */
+export function configureOpenApi(app: NexwireRouter) {
+  app.doc("/doc", {
+    openapi: openApiConfig.version,
+    info: {
+      title: openApiConfig.title,
+      version: openApiConfig.apiVersion,
+      ...(openApiConfig.description ? { description: openApiConfig.description } : {})
+    }
+  });
+
+  if (openApiConfig.scalar.favicon) {
+    app.get("/favicon.ico", (c) => {
+      const faviconPath = path.join(process.cwd(), openApiConfig.scalar.favicon);
+      if (!fs.existsSync(faviconPath)) return c.notFound();
+      return c.body(fs.readFileSync(faviconPath), 200, { "content-type": "image/x-icon" });
+    });
+  }
+
+  app.get(
+    openApiConfig.scalar.docsPath,
+    Scalar({
+      url: openApiConfig.scalar.specUrl,
+      layout: openApiConfig.scalar.layout,
+      theme: openApiConfig.scalar.theme,
+      pageTitle: openApiConfig.scalar.pageTitle,
+      defaultHttpClient: openApiConfig.scalar.defaultHttpClient,
+      defaultOpenAllTags: openApiConfig.scalar.defaultOpenAllTags
+    })
+  );
+}

package/hono/src/framework/http/ratelimiter.ts

@@ -0,0 +1,172 @@
+import type { Context, MiddlewareHandler, Next } from "hono";
+import { MemoryStore, RedisStore, rateLimiter } from "hono-rate-limiter";
+import { rateLimitConfig } from "@/config/index.js";
+import { redisClientIfReady } from "@/framework/redis/client.js";
+
+/**
+ * Why: Protects API from burst abuse and accidental flooding.
+ * When: Applied globally in HTTP middleware chain.
+ * Where: App bootstrap middleware stack.
+ * How: Limits requests per-user (authenticated) or per-session (guest)
+ *      using Redis store when available, falling back to in-memory.
+ *      Sends standard RateLimit-* headers so clients can back off.
+ */
+
+function adaptRedis(raw: any) {
+  return {
+    scriptLoad: (script: string) => raw.script("load", script),
+    evalsha: (sha1: string, keys: string[], args: unknown[]) => raw.evalsha(sha1, keys.length, ...keys, ...args),
+    decr: (key: string) => raw.decr(key),
+    del: (key: string) => raw.del(key)
+  };
+}
+
+const REDIS_RETRY_MS = 30_000;
+
+/**
+ * Why: Uses Redis for distributed rate limiting when available, but never lets
+ *      a Redis outage break requests.
+ * When: The global and login limiters run on every request; Redis can go away
+ *      after the middleware was already built (so the store choice cannot be
+ *      frozen at first request).
+ * Where: src/framework/http/ratelimiter.ts.
+ * How: Backs every call with an always-usable MemoryStore. A RedisStore is
+ *      created lazily (after a ping health check) and used only while it
+ *      responds; any Redis command failure drops the store and starts a
+ *      cooldown, during which traffic is served from memory. After the
+ *      cooldown the store is re-attempted, so a recovered Redis is picked up.
+ */
+function createFailingOverStore() {
+  const memoryStore = new MemoryStore();
+  let redisStore: RedisStore | null = null;
+  let cooldownUntil = 0;
+  let options: any = null;
+
+  function enterCooldown() {
+    redisStore = null;
+    cooldownUntil = Date.now() + REDIS_RETRY_MS;
+  }
+
+  async function redisStoreIfUsable() {
+    if (cooldownUntil > Date.now()) return null;
+
+    if (!redisStore) {
+      const raw = redisClientIfReady();
+      if (!raw) return null;
+
+      try {
+        await raw.ping();
+      } catch {
+        enterCooldown();
+        return null;
+      }
+
+      try {
+        redisStore = new RedisStore({ client: adaptRedis(raw), prefix: rateLimitConfig.keyPrefix });
+        redisStore.init(options);
+      } catch {
+        enterCooldown();
+        return null;
+      }
+    }
+
+    return redisStore;
+  }
+
+  return {
+    init(opts: any) {
+      options = opts;
+      memoryStore.init(opts);
+    },
+
+    async increment(key: string) {
+      const redis = await redisStoreIfUsable();
+      if (redis) {
+        try {
+          return await redis.increment(key);
+        } catch {
+          enterCooldown();
+        }
+      }
+      return memoryStore.increment(key);
+    },
+
+    async decrement(key: string) {
+      const redis = await redisStoreIfUsable();
+      if (redis) {
+        try {
+          await redis.decrement(key);
+          return;
+        } catch {
+          enterCooldown();
+        }
+      }
+      memoryStore.decrement(key);
+    },
+
+    async resetKey(key: string) {
+      const redis = await redisStoreIfUsable();
+      if (redis) {
+        try {
+          await redis.resetKey(key);
+          return;
+        } catch {
+          enterCooldown();
+        }
+      }
+      memoryStore.resetKey(key);
+    },
+
+    async get(key: string) {
+      const redis = await redisStoreIfUsable();
+      if (redis) {
+        try {
+          const info = await redis.get(key);
+          if (info) return info;
+        } catch {
+          enterCooldown();
+        }
+      }
+      return memoryStore.get(key);
+    }
+  };
+}
+
+let middleware: MiddlewareHandler | null = null;
+
+export const rateLimiterMiddleware = async (c: Context, next: Next) => {
+  if (!middleware) {
+    middleware = rateLimiter({
+      windowMs: rateLimitConfig.windowMs,
+      limit: rateLimitConfig.maxRequests,
+      keyGenerator: (c: any) => {
+        const sessionId = c.get("sessionId");
+        if (sessionId) return `session:${sessionId}`;
+        return c.req.header("x-forwarded-for") ?? "unknown";
+      },
+      store: createFailingOverStore(),
+      standardHeaders: "draft-6"
+    });
+  }
+
+  return middleware(c, next);
+};
+
+let loginLimiterMiddleware: MiddlewareHandler | null = null;
+
+export const loginLimiter = async (c: Context, next: Next) => {
+  if (!loginLimiterMiddleware) {
+    loginLimiterMiddleware = rateLimiter({
+      windowMs: rateLimitConfig.windowMs,
+      limit: rateLimitConfig.loginMaxRequests,
+      keyGenerator: (c: any) => {
+        const ip = c.req.header("x-forwarded-for") ?? "unknown";
+        return `login:${ip}`;
+      },
+      store: createFailingOverStore(),
+      standardHeaders: "draft-6"
+    });
+  }
+
+  return loginLimiterMiddleware(c, next);
+};

package/hono/src/framework/http/router.ts

@@ -0,0 +1,76 @@
+import { OpenAPIHono } from "@hono/zod-openapi";
+import { defaultHook } from "stoker/openapi";
+
+export type NexwireRouter = OpenAPIHono & {
+  group: (...middlewares: any[]) => NexwireRouter;
+  api: (route: any, handlerOrMiddlewares: any, handler?: any) => NexwireRouter;
+};
+
+/**
+ * Why: Creates the framework router with OpenAPI + helper methods.
+ * When: Building root app and module route files.
+ * Where: HTTP app bootstrap and route stubs.
+ * How: Wraps OpenAPIHono and adds group/api convenience APIs.
+ */
+export function createRouter(): NexwireRouter {
+  const router = new OpenAPIHono({ strict: false, defaultHook }) as NexwireRouter;
+  const baseOpenapi = router.openapi.bind(router);
+
+  router.group = function (...middlewares) {
+    for (const middleware of middlewares) {
+      this.use("*", middleware);
+    }
+
+    return this;
+  };
+
+  router.api = function (route: any, handlerOrMiddlewares: any, handler?: any) {
+    if (!Array.isArray(handlerOrMiddlewares)) {
+      baseOpenapi(route, handlerOrMiddlewares);
+      return this;
+    }
+
+    const middlewares = handlerOrMiddlewares;
+    const finalHandler = handler;
+
+    if (typeof finalHandler !== "function") {
+      throw new Error("api(route, middlewares, handler) requires a handler function");
+    }
+
+    const wrappedHandler = async (c: any) => {
+      let index = 0;
+
+      const next = async (): Promise<any> => {
+        if (index < middlewares.length) {
+          const middleware = middlewares[index++];
+          let downstream: any;
+          const result = await middleware(c, async () => {
+            downstream = await next();
+            return downstream;
+          });
+
+          return result === undefined ? downstream : result;
+        }
+
+        return await finalHandler(c);
+      };
+
+      return await next();
+    };
+
+    baseOpenapi(route, wrappedHandler);
+    return this;
+  };
+
+  return router;
+}
+
+/**
+ * Why: Shorthand for creating grouped router middleware chain.
+ * When: Route files need shared middleware composition.
+ * Where: Module route declarations.
+ * How: Creates a router instance and applies all provided middlewares.
+ */
+export function group(...middlewares: any[]) {
+  return createRouter().group(...middlewares);
+}

package/hono/src/framework/http/security.ts

@@ -0,0 +1,23 @@
+import type { MiddlewareHandler } from "hono";
+import { securityConfig } from "@/config/index.js";
+
+/**
+ * Why: Sets browser security response headers (CSP, HSTS, X-Frame).
+ * When: Every incoming HTTP request.
+ * Where: App middleware stack, after CORS and session.
+ * How: All headers disabled when securityConfig.enabled is false.
+ *      HSTS only applied when request is HTTPS.
+ */
+export const securityMiddleware: MiddlewareHandler = async (c, next) => {
+  if (securityConfig.enabled) {
+    c.header("Content-Security-Policy", securityConfig.csp);
+    const proto = c.req.header("x-forwarded-proto");
+    if (securityConfig.hsts && proto === "https") {
+      c.header("Strict-Transport-Security", securityConfig.hstsMaxAge);
+    }
+    c.header("X-Frame-Options", securityConfig.xFrame);
+    c.header("X-Content-Type-Options", "nosniff");
+    c.header("Referrer-Policy", "strict-origin-when-cross-origin");
+  }
+  await next();
+};