azurajs 3.0.1 → 3.0.2

package/src/decorators/Route.ts

@@ -0,0 +1,110 @@
+import type { HttpMethod, MiddlewareHandler } from "../types/common.type.js";
+import type { ParamMetadata, RouteMeta } from "../types/routes.type.js";
+
+const CONTROLLER_META_KEY = "azura:controller";
+const ROUTES_META_KEY = "azura:routes";
+const PARAMS_META_KEY = "azura:params";
+const MIDDLEWARES_META_KEY = "azura:middlewares";
+
+function ensureReflect(): void {
+  if (typeof Reflect === "undefined" || !Reflect.getMetadata) {
+    const store = new Map<string, Map<any, any>>();
+    (Reflect as any).defineMetadata = (key: string, value: any, target: any, prop?: string) => {
+      const k = prop ? `${key}::${prop}` : key;
+      if (!store.has(k)) store.set(k, new Map());
+      store.get(k)!.set(target, value);
+    };
+    (Reflect as any).getMetadata = (key: string, target: any, prop?: string) => {
+      const k = prop ? `${key}::${prop}` : key;
+      return store.get(k)?.get(target);
+    };
+  }
+}
+
+ensureReflect();
+
+export function Controller(prefix: string = ""): ClassDecorator {
+  return (target) => {
+    Reflect.defineMetadata(CONTROLLER_META_KEY, prefix, target);
+  };
+}
+
+function createMethodDecorator(method: HttpMethod) {
+  return (path: string = ""): MethodDecorator => {
+    return (target, propertyKey, _descriptor) => {
+      Reflect.defineMetadata(
+        ROUTES_META_KEY,
+        { method, path, propertyKey: String(propertyKey), middlewares: [], params: [], meta: undefined },
+        target,
+        String(propertyKey),
+      );
+    };
+  };
+}
+
+export const Get = createMethodDecorator("GET");
+export const Post = createMethodDecorator("POST");
+export const Put = createMethodDecorator("PUT");
+export const Delete = createMethodDecorator("DELETE");
+export const Patch = createMethodDecorator("PATCH");
+export const Head = createMethodDecorator("HEAD");
+export const Options = createMethodDecorator("OPTIONS");
+
+function createParamDecorator(type: ParamMetadata["type"]) {
+  return (name?: string): ParameterDecorator => {
+    return (target, propertyKey, parameterIndex) => {
+      const key = String(propertyKey);
+      const existing: ParamMetadata[] = Reflect.getMetadata(PARAMS_META_KEY, target, key) ?? [];
+      existing.push({ index: parameterIndex, type, name });
+      Reflect.defineMetadata(PARAMS_META_KEY, existing, target, key);
+    };
+  };
+}
+
+export const Body = createParamDecorator("body");
+export const Query = createParamDecorator("query");
+export const Param = createParamDecorator("param");
+export const Headers = createParamDecorator("header");
+export const Cookies = createParamDecorator("cookie");
+export const Req = createParamDecorator("req");
+export const Res = createParamDecorator("res");
+export const NextFunc = createParamDecorator("next");
+export const Ip = createParamDecorator("ip");
+export const Session = createParamDecorator("session");
+
+export function UseMiddleware(...middlewares: MiddlewareHandler[]): MethodDecorator & ClassDecorator {
+  return (target: any, propertyKey?: string | symbol, _descriptor?: PropertyDescriptor) => {
+    if (propertyKey) {
+      const existing: MiddlewareHandler[] =
+        Reflect.getMetadata(MIDDLEWARES_META_KEY, target, String(propertyKey)) ?? [];
+      Reflect.defineMetadata(MIDDLEWARES_META_KEY, [...existing, ...middlewares], target, String(propertyKey));
+    } else {
+      const existing: MiddlewareHandler[] =
+        Reflect.getMetadata(MIDDLEWARES_META_KEY, target) ?? [];
+      Reflect.defineMetadata(MIDDLEWARES_META_KEY, [...existing, ...middlewares], target);
+    }
+  };
+}
+
+export function applyDecorators(...decorators: (MethodDecorator | ClassDecorator)[]): MethodDecorator & ClassDecorator {
+  return (target: any, propertyKey?: string | symbol, descriptor?: PropertyDescriptor) => {
+    for (const decorator of decorators) {
+      if (propertyKey !== undefined) {
+        (decorator as MethodDecorator)(target, propertyKey, descriptor!);
+      } else {
+        (decorator as ClassDecorator)(target);
+      }
+    }
+  };
+}
+
+export function Meta(key: string, value: any): MethodDecorator {
+  return (target, propertyKey, _descriptor) => {
+    const routeMeta = Reflect.getMetadata(ROUTES_META_KEY, target, String(propertyKey));
+    if (routeMeta) {
+      if (!routeMeta.meta) routeMeta.meta = {};
+      routeMeta.meta[key] = value;
+      Reflect.defineMetadata(ROUTES_META_KEY, routeMeta, target, String(propertyKey));
+    }
+  };
+}

package/src/decorators/index.ts

@@ -0,0 +1,23 @@
+export {
+  Controller,
+  Get,
+  Post,
+  Put,
+  Delete,
+  Patch,
+  Head,
+  Options,
+  Body,
+  Query,
+  Param,
+  Headers,
+  Cookies,
+  Req,
+  Res,
+  NextFunc,
+  Ip,
+  Session,
+  UseMiddleware,
+  applyDecorators,
+  Meta,
+} from "./Route.js";

package/src/index.ts

@@ -0,0 +1,12 @@
+// Core — always available from root
+export { AzuraServer } from "./core/server.js";
+export { Router } from "./core/router.js";
+
+// Sub-module re-exports for convenience
+// Users can also import directly: "azurats/plugins", "azurats/decorators", etc.
+export * from "./decorators/index.js";
+export * from "./plugins/index.js";
+export * from "./utils/index.js";
+export * from "./config/index.js";
+export * from "./middleware/index.js";
+export * from "./types/index.js";

package/src/middleware/LoggingMiddleware.ts

@@ -0,0 +1,20 @@
+import type { PluginHandler } from "../types/plugins/plugin.type.js";
+
+export function LoggingMiddleware(): PluginHandler {
+  return (ctx, next) => {
+    const { req, res } = ctx;
+    const start = process.hrtime.bigint();
+
+    const originalEnd = res.end;
+    (res as any).end = function (...args: any[]) {
+      const duration = process.hrtime.bigint() - start;
+      const ms = Number(duration) / 1_000_000;
+
+      res.setHeader("X-Response-Time", `${ms.toFixed(2)}ms`);
+
+      return (originalEnd as any).apply(this, args);
+    };
+
+    next();
+  };
+}

package/src/middleware/index.ts

@@ -0,0 +1 @@
+export { LoggingMiddleware } from "./LoggingMiddleware.js";

package/src/plugins/CORSPlugin.ts

@@ -0,0 +1,56 @@
+import type { CORSOptions, PluginHandler } from "../types/plugins/plugin.type.js";
+
+const DEFAULT_METHODS = ["GET", "POST", "PUT", "DELETE", "PATCH", "HEAD", "OPTIONS"];
+const DEFAULT_HEADERS = ["Content-Type", "Authorization", "Accept", "X-Requested-With"];
+
+export function CORSPlugin(options: CORSOptions = {}): PluginHandler {
+  const {
+    origins = "*",
+    methods = DEFAULT_METHODS,
+    allowedHeaders = DEFAULT_HEADERS,
+    exposedHeaders = [],
+    credentials = false,
+    maxAge = 86400,
+    preflightContinue = false,
+  } = options;
+
+  const methodsStr = methods.join(", ");
+  const headersStr = allowedHeaders.join(", ");
+  const exposedStr = exposedHeaders.length > 0 ? exposedHeaders.join(", ") : "";
+
+  const isAllowedOrigin = (origin: string): string | false => {
+    if (origins === "*") return credentials ? origin : "*";
+    if (typeof origins === "function") return origins(origin) ? origin : false;
+    if (typeof origins === "string") return origin === origins ? origin : false;
+    if (Array.isArray(origins)) return origins.includes(origin) ? origin : false;
+    return false;
+  };
+
+  return (ctx, next) => {
+    const { req, res } = ctx;
+    const origin = req.headers.origin ?? "";
+
+    const allowedOrigin = isAllowedOrigin(origin);
+
+    if (allowedOrigin) {
+      res.setHeader("Access-Control-Allow-Origin", allowedOrigin);
+      if (credentials) res.setHeader("Access-Control-Allow-Credentials", "true");
+      if (exposedStr) res.setHeader("Access-Control-Expose-Headers", exposedStr);
+      if (allowedOrigin !== "*") res.setHeader("Vary", "Origin");
+    }
+
+    if (req.method === "OPTIONS") {
+      res.setHeader("Access-Control-Allow-Methods", methodsStr);
+      res.setHeader("Access-Control-Allow-Headers", headersStr);
+      res.setHeader("Access-Control-Max-Age", String(maxAge));
+
+      if (!preflightContinue) {
+        res.statusCode = 204;
+        res.end();
+        return;
+      }
+    }
+
+    next();
+  };
+}

package/src/plugins/CircuitBreakerPlugin.ts

@@ -0,0 +1,84 @@
+import type { CircuitBreakerOptions, CircuitBreakerState, PluginHandler } from "../types/plugins/plugin.type.js";
+
+export function CircuitBreakerPlugin(options: CircuitBreakerOptions = {}): PluginHandler {
+  const {
+    threshold = 5,
+    timeout: breakerTimeout = 30_000,
+    resetTimeout = 60_000,
+    halfOpenRequests = 1,
+    monitor,
+  } = options;
+
+  let state: CircuitBreakerState = "CLOSED";
+  let failures = 0;
+  let successes = 0;
+  let lastFailureTime = 0;
+  let halfOpenCount = 0;
+
+  const transition = (newState: CircuitBreakerState) => {
+    if (state !== newState) {
+      state = newState;
+      monitor?.(state);
+    }
+  };
+
+  return (ctx, next) => {
+    const { res } = ctx;
+
+    if (state === "OPEN") {
+      if (Date.now() - lastFailureTime >= resetTimeout) {
+        transition("HALF_OPEN");
+        halfOpenCount = 0;
+      } else {
+        res.statusCode = 503;
+        res.setHeader("Content-Type", "application/json");
+        res.setHeader("Retry-After", String(Math.ceil(resetTimeout / 1000)));
+        res.end(
+          JSON.stringify({
+            error: { statusCode: 503, message: "Service temporarily unavailable (circuit open)" },
+          }),
+        );
+        return;
+      }
+    }
+
+    if (state === "HALF_OPEN" && halfOpenCount >= halfOpenRequests) {
+      res.statusCode = 503;
+      res.setHeader("Content-Type", "application/json");
+      res.end(
+        JSON.stringify({
+          error: { statusCode: 503, message: "Service temporarily unavailable (circuit half-open)" },
+        }),
+      );
+      return;
+    }
+
+    if (state === "HALF_OPEN") halfOpenCount++;
+
+    const originalEnd = res.end;
+    (res as any).end = function (...args: any[]) {
+      if (res.statusCode >= 500) {
+        failures++;
+        lastFailureTime = Date.now();
+        if (state === "HALF_OPEN" || failures >= threshold) {
+          transition("OPEN");
+        }
+      } else {
+        if (state === "HALF_OPEN") {
+          successes++;
+          if (successes >= halfOpenRequests) {
+            failures = 0;
+            successes = 0;
+            transition("CLOSED");
+          }
+        } else {
+          failures = Math.max(0, failures - 1);
+        }
+      }
+
+      return (originalEnd as any).apply(this, args);
+    };
+
+    next();
+  };
+}

package/src/plugins/CompressionPlugin.ts

@@ -0,0 +1,80 @@
+import { createGzip, createDeflate, type Gzip, type Deflate } from "node:zlib";
+import type { CompressionOptions, PluginHandler } from "../types/plugins/plugin.type.js";
+
+const COMPRESSIBLE_TYPES = /^text\/|application\/json|application\/javascript|application\/xml|image\/svg\+xml/;
+
+export function CompressionPlugin(options: CompressionOptions = {}): PluginHandler {
+  const {
+    threshold = 1024,
+    level = 6,
+    algorithms = ["gzip", "deflate"],
+    filter,
+  } = options;
+
+  return (ctx, next) => {
+    const { req, res } = ctx;
+
+    if (filter && !filter(req as any, res as any)) {
+      next();
+      return;
+    }
+
+    const acceptEncoding = req.headers["accept-encoding"] ?? "";
+    let encoding: string | null = null;
+
+    for (const algo of algorithms) {
+      if (typeof acceptEncoding === "string" && acceptEncoding.includes(algo)) {
+        encoding = algo;
+        break;
+      }
+    }
+
+    if (!encoding) {
+      next();
+      return;
+    }
+
+    const originalEnd = res.end;
+    const originalWrite = res.write;
+
+    (res as any).end = function (chunk?: any, encodingArg?: any, callback?: any) {
+      if (!chunk || (typeof chunk !== "string" && !Buffer.isBuffer(chunk))) {
+        return (originalEnd as any).call(this, chunk, encodingArg, callback);
+      }
+
+      const buf = typeof chunk === "string" ? Buffer.from(chunk) : chunk;
+
+      if (buf.length < threshold) {
+        return (originalEnd as any).call(this, chunk, encodingArg, callback);
+      }
+
+      const contentType = String(res.getHeader("Content-Type") ?? "");
+      if (!COMPRESSIBLE_TYPES.test(contentType)) {
+        return (originalEnd as any).call(this, chunk, encodingArg, callback);
+      }
+
+      res.removeHeader("Content-Length");
+      res.setHeader("Content-Encoding", encoding!);
+      res.setHeader("Vary", "Accept-Encoding");
+
+      let stream: Gzip | Deflate;
+      if (encoding === "gzip") {
+        stream = createGzip({ level });
+      } else {
+        stream = createDeflate({ level });
+      }
+
+      const chunks: Buffer[] = [];
+      stream.on("data", (c: Buffer) => chunks.push(c));
+      stream.on("end", () => {
+        const compressed = Buffer.concat(chunks);
+        res.setHeader("Content-Length", compressed.length);
+        (originalEnd as any).call(res, compressed);
+      });
+
+      stream.end(buf);
+    };
+
+    next();
+  };
+}

package/src/plugins/ETagPlugin.ts

@@ -0,0 +1,31 @@
+import { createHash } from "node:crypto";
+import type { ETagOptions, PluginHandler } from "../types/plugins/plugin.type.js";
+
+export function ETagPlugin(options: ETagOptions = {}): PluginHandler {
+  const { weak = true } = options;
+
+  return (ctx, next) => {
+    const { req, res } = ctx;
+
+    const originalEnd = res.end;
+    (res as any).end = function (chunk?: any, encoding?: any, callback?: any) {
+      if (chunk && (typeof chunk === "string" || Buffer.isBuffer(chunk)) && res.statusCode === 200) {
+        const buf = typeof chunk === "string" ? Buffer.from(chunk) : chunk;
+        const hash = createHash("md5").update(buf).digest("hex").slice(0, 16);
+        const etag = weak ? `W/"${hash}"` : `"${hash}"`;
+
+        res.setHeader("ETag", etag);
+
+        const ifNoneMatch = req.headers["if-none-match"];
+        if (ifNoneMatch === etag) {
+          res.statusCode = 304;
+          return (originalEnd as any).call(this);
+        }
+      }
+
+      return (originalEnd as any).call(this, chunk, encoding, callback);
+    };
+
+    next();
+  };
+}

package/src/plugins/HealthCheckPlugin.ts

@@ -0,0 +1,57 @@
+import type { HealthCheckOptions, PluginHandler } from "../types/plugins/plugin.type.js";
+
+export function HealthCheckPlugin(options: HealthCheckOptions = {}): PluginHandler {
+  const {
+    path = "/health",
+    checks = {},
+    timeout: checkTimeout = 5000,
+  } = options;
+
+  return async (ctx, next) => {
+    const { req, res } = ctx;
+
+    if (req.pathname !== path) {
+      next();
+      return;
+    }
+
+    const results: Record<string, { status: string; duration: number }> = {};
+    let allHealthy = true;
+
+    for (const [name, check] of Object.entries(checks)) {
+      const start = Date.now();
+      try {
+        const result = await Promise.race([
+          Promise.resolve(check()),
+          new Promise<boolean>((_, reject) =>
+            setTimeout(() => reject(new Error("timeout")), checkTimeout),
+          ),
+        ]);
+        results[name] = {
+          status: result ? "healthy" : "unhealthy",
+          duration: Date.now() - start,
+        };
+        if (!result) allHealthy = false;
+      } catch {
+        results[name] = {
+          status: "unhealthy",
+          duration: Date.now() - start,
+        };
+        allHealthy = false;
+      }
+    }
+
+    const body = JSON.stringify({
+      status: allHealthy ? "healthy" : "unhealthy",
+      timestamp: new Date().toISOString(),
+      uptime: process.uptime(),
+      memory: process.memoryUsage(),
+      checks: results,
+    });
+
+    res.statusCode = allHealthy ? 200 : 503;
+    res.setHeader("Content-Type", "application/json");
+    res.setHeader("Cache-Control", "no-cache, no-store");
+    res.end(body);
+  };
+}

package/src/plugins/HelmetPlugin.ts

@@ -0,0 +1,89 @@
+import type { HelmetOptions, PluginHandler } from "../types/plugins/plugin.type.js";
+
+export function HelmetPlugin(options: HelmetOptions = {}): PluginHandler {
+  const headers: [string, string][] = [];
+
+  if (options.noSniff !== false) {
+    headers.push(["X-Content-Type-Options", "nosniff"]);
+  }
+
+  if (options.xssFilter !== false) {
+    headers.push(["X-XSS-Protection", "0"]);
+  }
+
+  if (options.ieNoOpen !== false) {
+    headers.push(["X-Download-Options", "noopen"]);
+  }
+
+  const frameguard = options.frameguard ?? true;
+  if (frameguard !== false) {
+    const action = typeof frameguard === "object" ? frameguard.action : "sameorigin";
+    headers.push(["X-Frame-Options", action.toUpperCase()]);
+  }
+
+  if (options.dnsPrefetchControl !== false) {
+    const allow = typeof options.dnsPrefetchControl === "object"
+      ? options.dnsPrefetchControl.allow
+      : false;
+    headers.push(["X-DNS-Prefetch-Control", allow ? "on" : "off"]);
+  }
+
+  const hsts = options.hsts ?? true;
+  if (hsts !== false) {
+    const maxAge = typeof hsts === "object" ? hsts.maxAge : 15552000;
+    const includeSubDomains = typeof hsts === "object" ? hsts.includeSubDomains !== false : true;
+    const preload = typeof hsts === "object" ? hsts.preload : false;
+    let value = `max-age=${maxAge}`;
+    if (includeSubDomains) value += "; includeSubDomains";
+    if (preload) value += "; preload";
+    headers.push(["Strict-Transport-Security", value]);
+  }
+
+  if (options.crossOriginEmbedderPolicy !== false) {
+    headers.push(["Cross-Origin-Embedder-Policy", "require-corp"]);
+  }
+
+  if (options.crossOriginOpenerPolicy !== false) {
+    const policy = typeof options.crossOriginOpenerPolicy === "object"
+      ? options.crossOriginOpenerPolicy.policy
+      : "same-origin";
+    headers.push(["Cross-Origin-Opener-Policy", policy]);
+  }
+
+  if (options.crossOriginResourcePolicy !== false) {
+    const policy = typeof options.crossOriginResourcePolicy === "object"
+      ? options.crossOriginResourcePolicy.policy
+      : "same-origin";
+    headers.push(["Cross-Origin-Resource-Policy", policy]);
+  }
+
+  const referrer = options.referrerPolicy ?? true;
+  if (referrer !== false) {
+    const policy = typeof referrer === "object"
+      ? (Array.isArray(referrer.policy) ? referrer.policy.join(", ") : referrer.policy)
+      : "no-referrer";
+    headers.push(["Referrer-Policy", policy]);
+  }
+
+  if (options.contentSecurityPolicy !== false && options.contentSecurityPolicy) {
+    const csp = options.contentSecurityPolicy;
+    const directives = Object.entries(csp)
+      .map(([key, values]) => `${key} ${values.join(" ")}`)
+      .join("; ");
+    headers.push(["Content-Security-Policy", directives]);
+  }
+
+  if (options.permissionsPolicy) {
+    const pp = Object.entries(options.permissionsPolicy)
+      .map(([key, values]) => `${key}=(${values.join(" ")})`)
+      .join(", ");
+    headers.push(["Permissions-Policy", pp]);
+  }
+
+  return (ctx, next) => {
+    for (const [name, value] of headers) {
+      ctx.res.setHeader(name, value);
+    }
+    next();
+  };
+}