aetherframework-middleware 1.0.0

package/src/middleware/json.js

@@ -0,0 +1,207 @@
+// json.js - JSON parsing middleware for AetherJS
+// High-performance JSON parsing with size limits and error handling
+
+/**
+ * Create JSON parsing middleware for AetherJS
+ * @param {Object} options - JSON parser configuration
+ * @returns {Function} - JSON parser middleware function
+ */
+function createJsonMiddleware(options = {}) {
+  // Load configuration from environment variables
+  const envConfig = {
+    limit: process.env.BODY_LIMIT_JSON,
+    strict: process.env.JSON_STRICT,
+    reviver: process.env.JSON_REVIVER,
+    enable: process.env.JSON_ENABLE,
+  };
+
+  // Default configuration
+  const defaults = {
+    enabled: envConfig.enable !== "false",
+    limit: parseSize(envConfig.limit || "1mb"),
+    strict: envConfig.strict !== "false",
+    reviver: envConfig.reviver ? eval(`(${envConfig.reviver})`) : null,
+
+    // Error handling
+    onError: (context, error) => {
+      context.setStatus(400).json({
+        error: "Bad Request",
+        message: "Invalid JSON format",
+        details: error.message,
+      });
+    },
+
+    // Size limit exceeded handler
+    onLimitExceeded: (context, limit) => {
+      context.setStatus(413).json({
+        error: "Payload Too Large",
+        message: `JSON payload exceeds ${limit} bytes limit`,
+      });
+    },
+  };
+
+  // Parse size string to bytes
+  function parseSize(size) {
+    const units = {
+      b: 1,
+      kb: 1024,
+      mb: 1024 * 1024,
+      gb: 1024 * 1024 * 1024,
+    };
+
+    // 1. 确保 size 是字符串，并转换为小写以便匹配
+    const lowerSize = String(size).toLowerCase();
+
+    // 2. 执行正则匹配
+    const match = lowerSize.match(/^(\d+(?:\.\d+)?)\s*(b|kb|mb|gb)$/);
+
+    if (!match) {
+      throw new Error(`Invalid size format: ${size}`);
+    }
+
+    // 3. 从匹配数组中提取数值部分 (index 1) 和单位部分 (index 2)
+    const value = parseFloat(match[1]); // 提取第一个捕获组（数字）
+    const unit = match[2]; // 提取第二个捕获组（单位）
+
+    // 4. 计算并返回字节数
+    return value * (units[unit] || 1);
+  }
+
+  // Merge with provided options
+  const config = { ...defaults, ...options };
+
+  /**
+   * Parse JSON from request body
+   * @param {Object} request - HTTP request object
+   * @returns {Promise<Object>} - Parsed JSON object
+   */
+  async function parseJson(request) {
+    return new Promise((resolve, reject) => {
+      const chunks = [];
+      let totalLength = 0;
+
+      request.on("data", (chunk) => {
+        totalLength += chunk.length;
+
+        if (totalLength > config.limit) {
+          request.destroy();
+          reject(new Error(`JSON payload exceeds ${config.limit} bytes limit`));
+          return;
+        }
+
+        chunks.push(chunk);
+      });
+
+      request.on("end", () => {
+        try {
+          const buffer = Buffer.concat(chunks);
+          const text = buffer.toString("utf8");
+
+          if (config.strict && text.trim() === "") {
+            reject(new Error("Empty JSON payload"));
+            return;
+          }
+
+          const parsed = config.reviver
+            ? JSON.parse(text, config.reviver)
+            : JSON.parse(text);
+
+          resolve(parsed);
+        } catch (error) {
+          reject(error);
+        }
+      });
+
+      request.on("error", (error) => {
+        reject(error);
+      });
+    });
+  }
+
+  /**
+   * JSON middleware function
+   * @param {AetherContext} context - AetherJS execution context
+   * @param {Object} signal - Signal object for flow control
+   */
+  return async function jsonMiddleware(context, signal) {
+    if (!config.enabled) {
+      return signal.next();
+    }
+
+    // Skip if not JSON content type
+    const contentType = context.getHeader("content-type") || "";
+    if (!contentType.includes("application/json")) {
+      return signal.next();
+    }
+
+    // Skip if no body is expected
+    if (context.method === "GET" || context.method === "HEAD") {
+      return signal.next();
+    }
+
+    const contentLength = parseInt(context.getHeader("content-length")) || 0;
+
+    // Skip if no content
+    if (contentLength === 0) {
+      return signal.next();
+    }
+
+    // Check size limit
+    if (contentLength > config.limit) {
+      return config.onLimitExceeded(context, config.limit);
+    }
+
+    try {
+      // Parse JSON body
+      const json = await parseJson(context._request);
+
+      // Store parsed JSON in context
+      context.setState("json", json);
+      context.setState("body", json);
+
+      // Add JSON methods to context
+      context.jsonBody = json;
+      context.getJson = () => json;
+
+      await signal.next();
+    } catch (error) {
+      if (error.message.includes("exceeds")) {
+        return config.onLimitExceeded(context, config.limit);
+      } else {
+        return config.onError(context, error);
+      }
+    }
+  };
+}
+
+// Add utility functions to the middleware
+createJsonMiddleware.parse = function (text, reviver) {
+  try {
+    return reviver ? JSON.parse(text, reviver) : JSON.parse(text);
+  } catch (error) {
+    throw new Error(`JSON parse error: ${error.message}`);
+  }
+};
+
+createJsonMiddleware.stringify = function (value, replacer, space) {
+  try {
+    return JSON.stringify(value, replacer, space);
+  } catch (error) {
+    throw new Error(`JSON stringify error: ${error.message}`);
+  }
+};
+
+createJsonMiddleware.isValid = function (text) {
+  try {
+    JSON.parse(text);
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+createJsonMiddleware.format = function (json, space = 2) {
+  return JSON.stringify(json, null, space);
+};
+
+export default createJsonMiddleware;

package/src/middleware/jwt.js

@@ -0,0 +1,222 @@
+import jwt from "jsonwebtoken";
+
+/**
+ * 辅助函数：解析算法配置
+ */
+function parseAlgorithms(algorithmsString) {
+  if (!algorithmsString) return ["HS256"];
+  return algorithmsString.split(",").map((alg) => alg.trim());
+}
+
+/**
+ * Create JWT middleware for AetherJS
+ * @param {Object} options - JWT configuration options
+ * @returns {Function} - JWT middleware function
+ */
+function createJwtMiddleware(options = {}) {
+  // Load configuration from environment variables
+  const envConfig = {
+    enabled: process.env.JWT_ENABLED,
+    secret: process.env.JWT_SECRET,
+    algorithms: process.env.JWT_ALGORITHMS,
+    audience: process.env.JWT_AUDIENCE,
+    issuer: process.env.JWT_ISSUER,
+    expiresIn: process.env.JWT_EXPIRES_IN,
+    ignoreExpiration: process.env.JWT_IGNORE_EXPIRATION,
+    credentialsRequired: process.env.JWT_CREDENTIALS_REQUIRED,
+    tokenHeader: process.env.JWT_TOKEN_HEADER,
+    tokenQuery: process.env.JWT_TOKEN_QUERY,
+    tokenCookie: process.env.JWT_TOKEN_COOKIE,
+  };
+
+  // Default configuration
+  const defaults = {
+    enabled: envConfig.enabled !== "false",
+    secret:
+      envConfig.secret || "your-super-secret-jwt-key-change-in-production",
+    algorithms: parseAlgorithms(envConfig.algorithms),
+    algorithm: envConfig.algorithms
+      ? parseAlgorithms(envConfig.algorithms)[0]
+      : "HS256",
+    audience: envConfig.audience,
+    issuer: envConfig.issuer,
+    expiresIn: envConfig.expiresIn || "7d",
+    ignoreExpiration: envConfig.ignoreExpiration === "true",
+    credentialsRequired: envConfig.credentialsRequired !== "false",
+    tokenHeader: envConfig.tokenHeader || "authorization",
+    tokenQuery: envConfig.tokenQuery || "token",
+    tokenCookie: envConfig.tokenCookie || "token",
+
+    // Token extraction methods
+    extractors: [
+      (context) => {
+        const header = context.getHeader(defaults.tokenHeader);
+        if (header && header.startsWith("Bearer ")) {
+          return header.substring(7);
+        }
+        return null;
+      },
+      (context) => {
+        return context.query[defaults.tokenQuery] || null;
+      },
+      (context) => {
+        const cookies = parseCookies(context.getHeader("cookie") || "");
+        return cookies[defaults.tokenCookie] || null;
+      },
+    ],
+
+    validationOptions: {
+      algorithms: parseAlgorithms(envConfig.algorithms),
+      audience: envConfig.audience,
+      issuer: envConfig.issuer,
+      ignoreExpiration: envConfig.ignoreExpiration === "true",
+    },
+
+    onError: (context, error) => {
+      context.setStatus(401).json({
+        error: "Unauthorized",
+        message: error.message,
+      });
+    },
+
+    onMissing: (context) => {
+      context.setStatus(401).json({
+        error: "Unauthorized",
+        message: "No token provided",
+      });
+    },
+  };
+
+  const config = { ...defaults, ...options };
+
+  function parseCookies(cookieHeader) {
+    const cookies = {};
+    if (!cookieHeader) return cookies;
+
+    const pairs = cookieHeader.split(";");
+    for (let i = 0; i < pairs.length; i++) {
+      const eqIdx = pairs[i].indexOf("=");
+      if (eqIdx === -1) continue;
+      const key = pairs[i].substring(0, eqIdx).trim();
+      const value = pairs[i].substring(eqIdx + 1).trim();
+      // 只保留第一次见到的 Cookie，防止同名覆盖攻击/隐患
+      if (!cookies[key]) {
+        cookies[key] = value;
+      }
+    }
+    return cookies;
+  }
+
+  function extractToken(context) {
+    for (let i = 0; i < config.extractors.length; i++) {
+      const token = config.extractors[i](context);
+      if (token) return token;
+    }
+    return null;
+  }
+
+  /**
+   * 💡 极致优化：去掉异步 Promise，改为同步校验，杜绝线程池排队阻塞
+   */
+  function verifyTokenSync(token) {
+    return jwt.verify(token, config.secret, config.validationOptions);
+  }
+
+  /**
+   * 签发通常不属于超高频热点，可保留异步或同步。这里维持原异步以保障向下兼容性。
+   */
+  async function signToken(payload, signOptions = {}) {
+    return new Promise((resolve, reject) => {
+      const algorithm = signOptions.algorithm || config.algorithm || "HS256";
+      const options = {
+        algorithm: algorithm,
+        expiresIn: config.expiresIn,
+        audience: config.audience,
+        issuer: config.issuer,
+        ...signOptions,
+      };
+
+      jwt.sign(payload, config.secret, options, (error, token) => {
+        if (error) reject(error);
+        else resolve(token);
+      });
+    });
+  }
+
+  return async function jwtMiddleware(context, next) {
+    if (!config.enabled) {
+      return typeof next === "function" ? next() : null;
+    }
+
+    const token = extractToken(context);
+
+    if (!token) {
+      if (config.credentialsRequired) {
+        return config.onMissing(context);
+      }
+      return typeof next === "function" ? next() : null;
+    }
+
+    try {
+      // 💡 同步执行，无等待延迟
+      const decoded = verifyTokenSync(token);
+
+      context.setState("jwt", decoded);
+      context.setState("user", decoded);
+      context.setState("token", token);
+
+      context.jwt = {
+        payload: decoded,
+        token: token,
+        refresh: async (newPayload = {}) => {
+          const payload = { ...decoded, ...newPayload };
+          const newToken = await signToken(payload);
+          context.setState("jwt", payload);
+          context.setState("token", newToken);
+          return newToken;
+        },
+        verify: async () => {
+          return verifyTokenSync(token);
+        },
+        expiresAt: () => (decoded.exp ? new Date(decoded.exp * 1000) : null),
+        isExpired: () =>
+          decoded.exp ? Date.now() >= decoded.exp * 1000 : false,
+        issuedAt: () => (decoded.iat ? new Date(decoded.iat * 1000) : null),
+      };
+
+      if (typeof next === "function") {
+        await next();
+      }
+    } catch (error) {
+      return config.onError(context, error);
+    }
+  };
+}
+
+// 静态方法修正：与运行时实例解耦，统一走静态安全配置
+createJwtMiddleware.sign = async function (payload, options = {}) {
+  const secret =
+    process.env.JWT_SECRET || "your-super-secret-jwt-key-change-in-production";
+  const algorithm = options.algorithm || "HS256";
+
+  return new Promise((resolve, reject) => {
+    jwt.sign(payload, secret, { algorithm, ...options }, (error, token) => {
+      if (error) reject(error);
+      else resolve(token);
+    });
+  });
+};
+
+createJwtMiddleware.verify = function (token, options = {}) {
+  const secret =
+    process.env.JWT_SECRET || "your-super-secret-jwt-key-change-in-production";
+  const algorithms = options.algorithms || ["HS256"];
+  // 静态暴露同样支持同步直出
+  return jwt.verify(token, secret, { algorithms, ...options });
+};
+
+createJwtMiddleware.decode = function (token, options = {}) {
+  return jwt.decode(token, options);
+};
+
+export default createJwtMiddleware;

package/src/middleware/rate-limit.js

@@ -0,0 +1,232 @@
+/**
+ * 高性能内存存储 - 基于惰性双重校验与微任务抽样清理
+ * O(1) 复杂度，彻底消灭定时器引发的 Long Task 阻塞
+ */
+class MemoryStore {
+  constructor(windowMs) {
+    this.windowMs = windowMs;
+    this.hits = new Map();
+    this.keysIterator = null; // 用于增量迭代清理
+  }
+
+  async increment(key) {
+    const now = Date.now();
+    let record = this.hits.get(key);
+
+    if (!record) {
+      this.hits.set(key, {
+        count: 1,
+        resetTime: now + this.windowMs,
+      });
+
+      // 💡 核心优化：万分之一的概率触发“增量、分批”微清理，不阻塞主线程
+      if (Math.random() < 0.0001) {
+        this._incrementalCleanup(now, 50); // 每次最多只检查 50 个 Key
+      }
+      return 1;
+    }
+
+    // 💡 核心优化：惰性过期检查。如果当前 Key 已经过了生命周期，直接就地重置
+    if (now > record.resetTime) {
+      record.count = 1;
+      record.resetTime = now + this.windowMs;
+      return 1;
+    }
+
+    record.count++;
+    return record.count;
+  }
+
+  async decrement(key) {
+    const record = this.hits.get(key);
+    if (record) {
+      record.count = Math.max(0, record.count - 1);
+    }
+  }
+
+  async resetKey(key) {
+    this.hits.delete(key);
+  }
+
+  async resetAll() {
+    this.hits.clear();
+    this.keysIterator = null;
+  }
+
+  async getRemaining(key, max) {
+    const record = this.hits.get(key);
+    if (!record || Date.now() > record.resetTime) return max;
+    return Math.max(0, max - record.count);
+  }
+
+  async getResetTime(key) {
+    const record = this.hits.get(key);
+    const now = Date.now();
+    if (!record || now > record.resetTime) return now + this.windowMs;
+    return record.resetTime;
+  }
+
+  /**
+   * 💡 分批、渐进式迭代清理，避免单次循环过大
+   */
+  _incrementalCleanup(now, limit) {
+    if (!this.keysIterator) {
+      this.keysIterator = this.hits.keys();
+    }
+
+    let count = 0;
+    while (count < limit) {
+      const next = this.keysIterator.next();
+      if (next.done) {
+        this.keysIterator = null; // 遍历完了，清空以便下次重新开始
+        break;
+      }
+
+      const key = next.value;
+      const record = this.hits.get(key);
+      if (record && now > record.resetTime) {
+        this.hits.delete(key);
+      }
+      count++;
+    }
+  }
+}
+
+/**
+ * Create rate limiting middleware for AetherJS
+ * @param {Object} options - Rate limiting configuration
+ * @returns {Function} - Rate limiting middleware function
+ */
+function createRateLimitMiddleware(options = {}) {
+  const envConfig = {
+    enabled: process.env.RATE_LIMIT_ENABLED,
+    windowMs: process.env.RATE_LIMIT_WINDOW_MS,
+    max: process.env.RATE_LIMIT_MAX_REQUESTS,
+    message: process.env.RATE_LIMIT_MESSAGE,
+    statusCode: process.env.RATE_LIMIT_STATUS_CODE,
+    skipSuccessfulRequests: process.env.RATE_LIMIT_SKIP_SUCCESSFUL,
+    skipFailedRequests: process.env.RATE_LIMIT_SKIP_FAILED,
+  };
+
+  const defaults = {
+    enabled: envConfig.enabled !== "false",
+    windowMs: envConfig.windowMs
+      ? parseInt(envConfig.windowMs)
+      : 15 * 60 * 1000,
+    max: envConfig.max ? parseInt(envConfig.max) : 100,
+    message: envConfig.message || "Too many requests, please try again later.",
+    statusCode: envConfig.statusCode ? parseInt(envConfig.statusCode) : 429,
+    skipSuccessfulRequests: envConfig.skipSuccessfulRequests === "true",
+    skipFailedRequests: envConfig.skipFailedRequests === "true",
+    store: new MemoryStore(
+      envConfig.windowMs ? parseInt(envConfig.windowMs) : 15 * 60 * 1000,
+    ),
+
+    keyGenerator: (context) => {
+      // 兼容 AetherContext 的标准方法与原生底层属性访问
+      const getHeader =
+        typeof context.getHeader === "function"
+          ? context.getHeader.bind(context)
+          : (k) => context.headers?.[k] || context.res?.getHeader?.(k);
+
+      return (
+        context.ip ||
+        getHeader("x-forwarded-for") ||
+        (context._request &&
+          context._request.socket &&
+          context._request.socket.remoteAddress) ||
+        (context.req &&
+          context.req.socket &&
+          context.req.socket.remoteAddress) ||
+        "unknown"
+      );
+    },
+
+    skip: (context) => {
+      const skipPaths = ["/health", "/metrics", "/favicon.ico"];
+      return skipPaths.includes(context.path || context.url);
+    },
+
+    handler: (context, options) => {
+      context.setStatus(options.statusCode);
+      context.setHeader(
+        "Retry-After",
+        Math.ceil(options.windowMs / 1000).toString(),
+      );
+      context.json({
+        error: options.message,
+        retryAfter: Math.ceil(options.windowMs / 1000),
+      });
+    },
+  };
+
+  const opts = { ...defaults, ...options };
+
+  return async function rateLimitMiddleware(context, next) {
+    if (!opts.enabled) {
+      return typeof next === "function" ? next() : null;
+    }
+
+    if (opts.skip && opts.skip(context)) {
+      return typeof next === "function" ? next() : null;
+    }
+
+    const key = opts.keyGenerator(context);
+    const current = await opts.store.increment(key);
+
+    const remaining = Math.max(0, opts.max - current);
+    const resetTime = await opts.store.getResetTime(key);
+
+    // 🛡️ 核心修复 1：安全的武器级 Header 写入。支持全小写规范，避免多方扫描时发生二义性冲突
+    const getHeader =
+      typeof context.getHeader === "function"
+        ? context.getHeader.bind(context)
+        : () => null;
+
+    if (!getHeader("x-ratelimit-limit") && !getHeader("X-RateLimit-Limit")) {
+      context.setHeader("X-RateLimit-Limit", opts.max.toString());
+    }
+    if (
+      !getHeader("x-ratelimit-remaining") &&
+      !getHeader("X-RateLimit-Remaining")
+    ) {
+      context.setHeader("X-RateLimit-Remaining", remaining.toString());
+    }
+    if (!getHeader("x-ratelimit-reset") && !getHeader("X-RateLimit-Reset")) {
+      context.setHeader(
+        "X-RateLimit-Reset",
+        Math.ceil(resetTime / 1000).toString(),
+      );
+    }
+
+    // 🛡️ 核心修复 2：前置触发熔断，直接阻断，不再向下游和回溯传递
+    if (current > opts.max) {
+      opts.handler(context, opts);
+      if (typeof context.terminate === "function") context.terminate();
+      return;
+    }
+
+    // 执行下游中间件
+    if (typeof next === "function") {
+      await next();
+    }
+
+    // 🛡️ 核心修复 3：回溯精准补偿。为了不破坏外层缓存提炼，业务流回溯完毕后必须立刻 return 干净
+    const statusCode =
+      context.statusCode ||
+      (context._response && context._response.statusCode) ||
+      (context.res && context.res.statusCode);
+
+    if (opts.skipSuccessfulRequests && statusCode >= 200 && statusCode < 300) {
+      await opts.store.decrement(key);
+    }
+
+    if (opts.skipFailedRequests && statusCode >= 400) {
+      await opts.store.decrement(key);
+    }
+
+    return; // 💥 强力斩断任何微任务隐式溢出，保证 V8 垃圾回收的高效性
+  };
+}
+
+export default createRateLimitMiddleware;