azurajs 3.0.1 → 3.0.2

package/src/types/plugins/plugin.type.ts

@@ -0,0 +1,170 @@
+import type {
+  AzuraRequest,
+  AzuraResponse,
+  NextFunction,
+} from "../common.type.js";
+
+export interface PluginContext {
+  req: AzuraRequest;
+  res: AzuraResponse;
+}
+
+export type PluginHandler = (
+  ctx: PluginContext,
+  next: NextFunction,
+) => void | Promise<void>;
+
+export type PluginFactory<T = any> = (options?: T) => PluginHandler;
+
+export interface PluginDefinition<T = any> {
+  name: string;
+  version?: string;
+  factory: PluginFactory<T>;
+  defaultOptions?: T;
+}
+
+export interface CORSOptions {
+  origins?: string | string[] | ((origin: string) => boolean);
+  methods?: string[];
+  allowedHeaders?: string[];
+  exposedHeaders?: string[];
+  credentials?: boolean;
+  maxAge?: number;
+  preflightContinue?: boolean;
+}
+
+export interface RateLimitOptions {
+  windowMs?: number;
+  max?: number;
+  message?: string | object;
+  statusCode?: number;
+  keyGenerator?: (req: AzuraRequest) => string;
+  skipSuccessfulRequests?: boolean;
+  skipFailedRequests?: boolean;
+  store?: RateLimitStore;
+}
+
+export interface RateLimitStore {
+  increment(key: string): Promise<{ totalHits: number; resetTime: Date }>;
+  decrement(key: string): Promise<void>;
+  resetKey(key: string): Promise<void>;
+}
+
+export interface HelmetOptions {
+  contentSecurityPolicy?: false | Record<string, string[]>;
+  crossOriginEmbedderPolicy?: boolean;
+  crossOriginOpenerPolicy?: boolean | { policy: string };
+  crossOriginResourcePolicy?: boolean | { policy: string };
+  dnsPrefetchControl?: boolean | { allow: boolean };
+  frameguard?: boolean | { action: "deny" | "sameorigin" };
+  hsts?: boolean | { maxAge: number; includeSubDomains?: boolean; preload?: boolean };
+  ieNoOpen?: boolean;
+  noSniff?: boolean;
+  referrerPolicy?: boolean | { policy: string | string[] };
+  xssFilter?: boolean;
+  permissionsPolicy?: Record<string, string[]>;
+}
+
+export interface JWTOptions {
+  secret: string;
+  algorithm?: "HS256" | "HS384" | "HS512";
+  expiresIn?: string | number;
+  issuer?: string;
+  audience?: string;
+  paths?: string[];
+  exclude?: string[];
+  getToken?: (req: AzuraRequest) => string | null;
+}
+
+export interface SessionOptions {
+  secret: string;
+  name?: string;
+  maxAge?: number;
+  secure?: boolean;
+  httpOnly?: boolean;
+  sameSite?: "Strict" | "Lax" | "None";
+  store?: SessionStore;
+}
+
+export interface SessionStore {
+  get(id: string): Promise<Record<string, any> | null>;
+  set(id: string, data: Record<string, any>, maxAge: number): Promise<void>;
+  destroy(id: string): Promise<void>;
+  touch?(id: string, maxAge: number): Promise<void>;
+}
+
+export interface CompressionOptions {
+  threshold?: number;
+  level?: number;
+  algorithms?: ("gzip" | "deflate" | "br")[];
+  filter?: (req: AzuraRequest, res: AzuraResponse) => boolean;
+}
+
+export interface StaticOptions {
+  root: string;
+  prefix?: string;
+  index?: string | string[];
+  dotfiles?: "allow" | "deny" | "ignore";
+  maxAge?: number;
+  etag?: boolean;
+  lastModified?: boolean;
+  fallthrough?: boolean;
+  immutable?: boolean;
+}
+
+export interface ETagOptions {
+  weak?: boolean;
+}
+
+export interface RequestIdOptions {
+  header?: string;
+  generator?: () => string;
+}
+
+export interface TimeoutOptions {
+  timeout: number;
+  message?: string | object;
+  statusCode?: number;
+}
+
+export interface HealthCheckOptions {
+  path?: string;
+  checks?: Record<string, () => Promise<boolean> | boolean>;
+  timeout?: number;
+}
+
+export interface CircuitBreakerOptions {
+  threshold?: number;
+  timeout?: number;
+  resetTimeout?: number;
+  halfOpenRequests?: number;
+  monitor?: (state: CircuitBreakerState) => void;
+}
+
+export type CircuitBreakerState = "CLOSED" | "OPEN" | "HALF_OPEN";
+
+export interface ProxyOptions {
+  target: string;
+  pathRewrite?: Record<string, string>;
+  changeOrigin?: boolean;
+  timeout?: number;
+  headers?: Record<string, string>;
+  onProxyReq?: (proxyReq: any, req: AzuraRequest) => void;
+  onProxyRes?: (proxyRes: any, res: AzuraResponse) => void;
+}
+
+export interface SSEOptions {
+  path: string;
+  heartbeatInterval?: number;
+  retry?: number;
+  maxClients?: number;
+}
+
+export interface MultipartOptions {
+  maxFileSize?: number;
+  maxFiles?: number;
+  maxFieldSize?: number;
+  maxFields?: number;
+  allowedMimeTypes?: string[];
+  uploadDir?: string;
+}

package/src/types/reflect.d.ts

@@ -0,0 +1,14 @@
+declare namespace Reflect {
+  function defineMetadata(
+    metadataKey: string,
+    metadataValue: any,
+    target: any,
+    propertyKey?: string,
+  ): void;
+
+  function getMetadata(
+    metadataKey: string,
+    target: any,
+    propertyKey?: string,
+  ): any;
+}

package/src/types/routes.type.ts

@@ -0,0 +1,70 @@
+import type { HttpMethod, MiddlewareHandler, RouteHandler } from "./common.type.js";
+
+export interface RouteDefinition {
+  method: HttpMethod;
+  path: string;
+  handler: RouteHandler;
+  middlewares?: MiddlewareHandler[];
+  meta?: RouteMeta;
+}
+
+export interface RouteMeta {
+  summary?: string;
+  description?: string;
+  tags?: string[];
+  deprecated?: boolean;
+  produces?: string[];
+  consumes?: string[];
+  parameters?: ParameterMeta[];
+  responses?: Record<number, ResponseMeta>;
+  security?: Record<string, string[]>[];
+}
+
+export interface ParameterMeta {
+  name: string;
+  in: "path" | "query" | "header" | "body";
+  required?: boolean;
+  type?: string;
+  description?: string;
+  schema?: any;
+}
+
+export interface ResponseMeta {
+  description: string;
+  schema?: any;
+  headers?: Record<string, { type: string; description: string }>;
+}
+
+export type ParamType =
+  | "body"
+  | "query"
+  | "param"
+  | "header"
+  | "cookie"
+  | "req"
+  | "res"
+  | "next"
+  | "ip"
+  | "session";
+
+export interface ParamMetadata {
+  index: number;
+  type: ParamType;
+  name?: string;
+  pipes?: ((value: any) => any)[];
+}
+
+export interface ControllerMetadata {
+  prefix: string;
+  middlewares: MiddlewareHandler[];
+  routes: Map<string, RouteMetadata>;
+}
+
+export interface RouteMetadata {
+  method: HttpMethod;
+  path: string;
+  propertyKey: string;
+  middlewares: MiddlewareHandler[];
+  params: ParamMetadata[];
+  meta?: RouteMeta;
+}

package/src/utils/HttpError.ts

@@ -0,0 +1,62 @@
+import { HttpStatusText } from "../types/http/status.js";
+
+export class HttpError extends Error {
+  public readonly statusCode: number;
+  public readonly details?: any;
+  public readonly isOperational: boolean;
+
+  constructor(statusCode: number, message?: string, details?: any) {
+    super(message ?? HttpStatusText[statusCode] ?? "Unknown Error");
+    this.statusCode = statusCode;
+    this.details = details;
+    this.isOperational = true;
+    Object.setPrototypeOf(this, HttpError.prototype);
+  }
+
+  toJSON(): Record<string, any> {
+    const obj: Record<string, any> = {
+      error: {
+        statusCode: this.statusCode,
+        message: this.message,
+      },
+    };
+    if (this.details) obj.error.details = this.details;
+    return obj;
+  }
+
+  static badRequest(message?: string, details?: any): HttpError {
+    return new HttpError(400, message ?? "Bad Request", details);
+  }
+
+  static unauthorized(message?: string): HttpError {
+    return new HttpError(401, message ?? "Unauthorized");
+  }
+
+  static forbidden(message?: string): HttpError {
+    return new HttpError(403, message ?? "Forbidden");
+  }
+
+  static notFound(message?: string): HttpError {
+    return new HttpError(404, message ?? "Not Found");
+  }
+
+  static methodNotAllowed(message?: string): HttpError {
+    return new HttpError(405, message ?? "Method Not Allowed");
+  }
+
+  static conflict(message?: string, details?: any): HttpError {
+    return new HttpError(409, message ?? "Conflict", details);
+  }
+
+  static unprocessableEntity(message?: string, details?: any): HttpError {
+    return new HttpError(422, message ?? "Unprocessable Entity", details);
+  }
+
+  static tooManyRequests(message?: string): HttpError {
+    return new HttpError(429, message ?? "Too Many Requests");
+  }
+
+  static internal(message?: string): HttpError {
+    return new HttpError(500, message ?? "Internal Server Error");
+  }
+}

package/src/utils/IpResolver.ts

@@ -0,0 +1,30 @@
+import type { IncomingMessage } from "node:http";
+
+const PROXY_HEADERS = [
+  "x-forwarded-for",
+  "x-real-ip",
+  "cf-connecting-ip",
+  "x-client-ip",
+  "x-cluster-client-ip",
+  "fastly-client-ip",
+  "true-client-ip",
+] as const;
+
+export function resolveIp(req: IncomingMessage): string {
+  for (const header of PROXY_HEADERS) {
+    const val = req.headers[header];
+    if (val) {
+      const ip = typeof val === "string" ? val.split(",")[0].trim() : val[0];
+      if (ip && ip.length > 0) return normalizeIp(ip);
+    }
+  }
+
+  const remoteAddr = req.socket?.remoteAddress ?? "127.0.0.1";
+  return normalizeIp(remoteAddr);
+}
+
+function normalizeIp(ip: string): string {
+  if (ip === "::1" || ip === "::ffff:127.0.0.1") return "127.0.0.1";
+  if (ip.startsWith("::ffff:")) return ip.slice(7);
+  return ip;
+}

package/src/utils/Logger.ts

@@ -0,0 +1,144 @@
+type LogLevel = "debug" | "info" | "warn" | "error" | "silent";
+
+const LEVEL_PRIORITY: Record<LogLevel, number> = {
+  debug: 0,
+  info: 1,
+  warn: 2,
+  error: 3,
+  silent: 4,
+};
+
+const COLORS = {
+  reset: "\x1b[0m",
+  bold: "\x1b[1m",
+  dim: "\x1b[2m",
+  red: "\x1b[31m",
+  green: "\x1b[32m",
+  yellow: "\x1b[33m",
+  blue: "\x1b[34m",
+  magenta: "\x1b[35m",
+  cyan: "\x1b[36m",
+  white: "\x1b[37m",
+  gray: "\x1b[90m",
+  bgRed: "\x1b[41m",
+  bgGreen: "\x1b[42m",
+  bgYellow: "\x1b[43m",
+  bgBlue: "\x1b[44m",
+} as const;
+
+const METHOD_COLORS: Record<string, string> = {
+  GET: COLORS.green,
+  POST: COLORS.blue,
+  PUT: COLORS.yellow,
+  DELETE: COLORS.red,
+  PATCH: COLORS.magenta,
+  HEAD: COLORS.cyan,
+  OPTIONS: COLORS.gray,
+};
+
+function statusColor(code: number): string {
+  if (code < 200) return COLORS.gray;
+  if (code < 300) return COLORS.green;
+  if (code < 400) return COLORS.cyan;
+  if (code < 500) return COLORS.yellow;
+  return COLORS.red;
+}
+
+function formatDuration(ns: bigint): string {
+  const us = Number(ns) / 1_000;
+  if (us < 1_000) return `${us.toFixed(0)}µs`;
+  const ms = us / 1_000;
+  if (ms < 1_000) return `${ms.toFixed(1)}ms`;
+  return `${(ms / 1_000).toFixed(2)}s`;
+}
+
+export class Logger {
+  private level: LogLevel;
+  private useColors: boolean;
+  private showTimestamp: boolean;
+  private prefix: string;
+
+  constructor(options: {
+    level?: LogLevel;
+    colors?: boolean;
+    timestamp?: boolean;
+    prefix?: string;
+  } = {}) {
+    this.level = options.level ?? "info";
+    this.useColors = options.colors ?? process.stdout.isTTY !== false;
+    this.showTimestamp = options.timestamp ?? true;
+    this.prefix = options.prefix ?? "azura";
+  }
+
+  private shouldLog(level: LogLevel): boolean {
+    return LEVEL_PRIORITY[level] >= LEVEL_PRIORITY[this.level];
+  }
+
+  private timestamp(): string {
+    if (!this.showTimestamp) return "";
+    const now = new Date();
+    return `${COLORS.gray}${now.toISOString().slice(11, 23)}${COLORS.reset} `;
+  }
+
+  private tag(level: LogLevel): string {
+    if (!this.useColors) return `[${level.toUpperCase()}]`;
+    const colorMap: Record<string, string> = {
+      debug: COLORS.gray,
+      info: COLORS.blue,
+      warn: COLORS.yellow,
+      error: COLORS.red,
+    };
+    return `${colorMap[level] ?? ""}[${level.toUpperCase()}]${COLORS.reset}`;
+  }
+
+  debug(message: string, ...args: any[]): void {
+    if (!this.shouldLog("debug")) return;
+    console.debug(`${this.timestamp()}${this.tag("debug")} ${message}`, ...args);
+  }
+
+  info(message: string, ...args: any[]): void {
+    if (!this.shouldLog("info")) return;
+    console.info(`${this.timestamp()}${this.tag("info")} ${message}`, ...args);
+  }
+
+  warn(message: string, ...args: any[]): void {
+    if (!this.shouldLog("warn")) return;
+    console.warn(`${this.timestamp()}${this.tag("warn")} ${message}`, ...args);
+  }
+
+  error(message: string, ...args: any[]): void {
+    if (!this.shouldLog("error")) return;
+    console.error(`${this.timestamp()}${this.tag("error")} ${message}`, ...args);
+  }
+
+  request(method: string, path: string, statusCode: number, duration: bigint): void {
+    if (!this.shouldLog("info")) return;
+    const mc = this.useColors ? METHOD_COLORS[method] ?? COLORS.white : "";
+    const sc = this.useColors ? statusColor(statusCode) : "";
+    const r = this.useColors ? COLORS.reset : "";
+    const dur = formatDuration(duration);
+    console.info(
+      `${this.timestamp()}${mc}${method.padEnd(7)}${r} ${path} ${sc}${statusCode}${r} ${COLORS.dim}${dur}${r}`,
+    );
+  }
+
+  banner(port: number, host: string): void {
+    if (!this.shouldLog("info")) return;
+    const c = this.useColors;
+    const lines = [
+      "",
+      `${c ? COLORS.bold + COLORS.cyan : ""}  ⚡ AzuraJS v3.0.0${c ? COLORS.reset : ""}`,
+      "",
+      `${c ? COLORS.green : ""}  ➜ Local:   ${c ? COLORS.bold : ""}http://${host}:${port}/${c ? COLORS.reset : ""}`,
+      `${c ? COLORS.dim : ""}  ➜ Press Ctrl+C to stop${c ? COLORS.reset : ""}`,
+      "",
+    ];
+    console.info(lines.join("\n"));
+  }
+
+  setLevel(level: LogLevel): void {
+    this.level = level;
+  }
+}
+
+export const logger = new Logger();

package/src/utils/Parser.ts

@@ -0,0 +1,182 @@
+import type { IncomingMessage } from "node:http";
+
+export function parseQueryString(qs: string): Record<string, string | string[]> {
+  const result: Record<string, string | string[]> = Object.create(null);
+  if (!qs || qs.length === 0) return result;
+
+  let key = "";
+  let value = "";
+  let startingKey = true;
+  let i = qs.charCodeAt(0) === 63 ? 1 : 0; // skip leading ?
+
+  for (; i < qs.length; i++) {
+    const ch = qs.charCodeAt(i);
+
+    if (ch === 61 /* = */ && startingKey) {
+      startingKey = false;
+      continue;
+    }
+
+    if (ch === 38 /* & */) {
+      if (key.length > 0) {
+        const decodedKey = fastDecode(key);
+        const decodedVal = fastDecode(value);
+        const existing = result[decodedKey];
+        if (existing === undefined) {
+          result[decodedKey] = decodedVal;
+        } else if (typeof existing === "string") {
+          result[decodedKey] = [existing, decodedVal];
+        } else {
+          existing.push(decodedVal);
+        }
+      }
+      key = "";
+      value = "";
+      startingKey = true;
+      continue;
+    }
+
+    if (startingKey) {
+      key += qs[i];
+    } else {
+      value += qs[i];
+    }
+  }
+
+  if (key.length > 0) {
+    const decodedKey = fastDecode(key);
+    const decodedVal = fastDecode(value);
+    const existing = result[decodedKey];
+    if (existing === undefined) {
+      result[decodedKey] = decodedVal;
+    } else if (typeof existing === "string") {
+      result[decodedKey] = [existing, decodedVal];
+    } else {
+      existing.push(decodedVal);
+    }
+  }
+
+  return result;
+}
+
+function fastDecode(str: string): string {
+  if (str.indexOf("%") === -1 && str.indexOf("+") === -1) return str;
+  try {
+    return decodeURIComponent(str.replace(/\+/g, " "));
+  } catch {
+    return str;
+  }
+}
+
+export function parseCookies(header: string | undefined): Record<string, string> {
+  const cookies: Record<string, string> = Object.create(null);
+  if (!header) return cookies;
+
+  let i = 0;
+  const len = header.length;
+
+  while (i < len) {
+    while (i < len && header.charCodeAt(i) === 32) i++; // skip spaces
+
+    let eqIdx = -1;
+    let semiIdx = -1;
+    for (let j = i; j < len; j++) {
+      const ch = header.charCodeAt(j);
+      if (ch === 61 && eqIdx === -1) eqIdx = j;
+      if (ch === 59) { semiIdx = j; break; }
+    }
+
+    if (eqIdx === -1) {
+      i = semiIdx === -1 ? len : semiIdx + 1;
+      continue;
+    }
+
+    const end = semiIdx === -1 ? len : semiIdx;
+    const name = header.slice(i, eqIdx).trim();
+    let val = header.slice(eqIdx + 1, end).trim();
+
+    if (val.charCodeAt(0) === 34 && val.charCodeAt(val.length - 1) === 34) {
+      val = val.slice(1, -1);
+    }
+
+    if (cookies[name] === undefined) {
+      cookies[name] = fastDecode(val);
+    }
+
+    i = end + 1;
+  }
+
+  return cookies;
+}
+
+const CONTENT_TYPE_JSON = "application/json";
+const CONTENT_TYPE_FORM = "application/x-www-form-urlencoded";
+
+export async function parseBody(req: IncomingMessage): Promise<any> {
+  const contentType = req.headers["content-type"] ?? "";
+  const contentLength = req.headers["content-length"];
+
+  if (
+    req.method === "GET" ||
+    req.method === "HEAD" ||
+    req.method === "OPTIONS" ||
+    (contentLength !== undefined && contentLength === "0")
+  ) {
+    return undefined;
+  }
+
+  const chunks: Buffer[] = [];
+  let totalSize = 0;
+  const maxSize = 10 * 1024 * 1024; // 10MB default
+
+  return new Promise((resolve, reject) => {
+    req.on("data", (chunk: Buffer) => {
+      totalSize += chunk.length;
+      if (totalSize > maxSize) {
+        req.destroy();
+        reject(new Error("Request body too large"));
+        return;
+      }
+      chunks.push(chunk);
+    });
+
+    req.on("end", () => {
+      if (chunks.length === 0) {
+        resolve(undefined);
+        return;
+      }
+
+      const raw = Buffer.concat(chunks).toString("utf-8");
+
+      if (contentType.startsWith(CONTENT_TYPE_JSON)) {
+        try {
+          resolve(JSON.parse(raw));
+        } catch {
+          resolve(raw);
+        }
+      } else if (contentType.startsWith(CONTENT_TYPE_FORM)) {
+        resolve(parseQueryString(raw));
+      } else {
+        resolve(raw);
+      }
+    });
+
+    req.on("error", reject);
+  });
+}
+
+export function parseUrl(url: string): { pathname: string; search: string } {
+  let pathname = "";
+  let search = "";
+  let i = 0;
+
+  for (; i < url.length; i++) {
+    if (url.charCodeAt(i) === 63) { // ?
+      pathname = url.slice(0, i);
+      search = url.slice(i);
+      return { pathname, search };
+    }
+  }
+
+  return { pathname: url, search: "" };
+}