@zucker-framework/rate-limiter 1.0.0

package/dist/index.js

@@ -0,0 +1,574 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  DynamicLimiterManager: () => DynamicLimiterManager,
+  RATE_LIMIT_KEY: () => RATE_LIMIT_KEY,
+  RateLimit: () => RateLimit,
+  RateLimitGuard: () => RateLimitGuard,
+  RateLimiterService: () => RateLimiterService,
+  TooManyRequestsException: () => TooManyRequestsException,
+  ZuckerRateLimiterModule: () => ZuckerRateLimiterModule,
+  deriveRateLimitKey: () => deriveRateLimitKey
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/rate-limiter.service.ts
+var import_common = require("@nestjs/common");
+var import_rate_limiter_flexible = require("rate-limiter-flexible");
+var import_core = require("@zucker-framework/core");
+var import_node_crypto = require("crypto");
+function _ts_decorate(decorators, target, key, desc) {
+  var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+  if (typeof Reflect === "object" && typeof Reflect.decorate === "function") {
+    r = Reflect.decorate(decorators, target, key, desc);
+  } else {
+    for (var i = decorators.length - 1; i >= 0; i--) {
+      if (d = decorators[i]) {
+        r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+      }
+    }
+  }
+  return c > 3 && r && Object.defineProperty(target, key, r), r;
+}
+__name(_ts_decorate, "_ts_decorate");
+function _ts_metadata(metadataKey, metadataValue) {
+  if (typeof Reflect === "object" && typeof Reflect.metadata === "function") {
+    return Reflect.metadata(metadataKey, metadataValue);
+  }
+}
+__name(_ts_metadata, "_ts_metadata");
+function deriveRateLimitKey(key, secret) {
+  if (!secret) return key;
+  return `v1:${(0, import_node_crypto.createHmac)("sha256", secret).update(key).digest("hex")}`;
+}
+__name(deriveRateLimitKey, "deriveRateLimitKey");
+var TooManyRequestsException = class extends import_common.HttpException {
+  static {
+    __name(this, "TooManyRequestsException");
+  }
+  retryAfter;
+  constructor(message, retryAfter) {
+    super({
+      statusCode: import_common.HttpStatus.TOO_MANY_REQUESTS,
+      message,
+      retryAfter
+    }, import_common.HttpStatus.TOO_MANY_REQUESTS);
+    this.retryAfter = retryAfter;
+  }
+};
+var RateLimiterService = class _RateLimiterService {
+  static {
+    __name(this, "RateLimiterService");
+  }
+  options;
+  logger = new import_common.Logger(_RateLimiterService.name);
+  limiters = /* @__PURE__ */ new Map();
+  useRedis = false;
+  constructor(options) {
+    this.options = options;
+  }
+  async onModuleInit() {
+    if (this.options.redisClient) {
+      this.useRedis = true;
+      this.logger.log("RateLimiterService \u4F7F\u7528 Redis \u5206\u5E03\u5F0F\u9650\u6D41");
+    }
+    for (const [name, config] of Object.entries(this.options.limiters)) {
+      if (config.points <= 0 || config.duration <= 0) {
+        this.logger.warn(`\u9650\u6D41\u5668 '${name}' \u914D\u7F6E\u65E0\u6548 (points=${config.points}, duration=${config.duration})\uFF0C\u5DF2\u8DF3\u8FC7`);
+        continue;
+      }
+      const opts = {
+        points: config.points,
+        duration: config.duration,
+        blockDuration: config.blockDuration ?? config.duration
+      };
+      if (this.useRedis) {
+        this.limiters.set(name, new import_rate_limiter_flexible.RateLimiterRedis({
+          ...opts,
+          storeClient: this.options.redisClient,
+          keyPrefix: config.keyPrefix ?? `rl:${name}:`
+        }));
+      } else {
+        this.limiters.set(name, new import_rate_limiter_flexible.RateLimiterMemory(opts));
+      }
+    }
+    this.logger.log(`RateLimiterService \u521D\u59CB\u5316\u5B8C\u6210 (${this.useRedis ? "Redis" : "Memory"}), ${this.limiters.size} \u4E2A\u9650\u6D41\u5668`);
+  }
+  onModuleDestroy() {
+    this.limiters.clear();
+    this.logger.log("RateLimiterService \u5DF2\u6E05\u7406");
+  }
+  /**
+  * Consume points from a rate limiter.
+  * Throws TooManyRequestsException (429) when limit is exceeded.
+  */
+  async consume(limiterName, key, pointsToConsume = 1, errorMessage = "\u8BF7\u6C42\u8FC7\u4E8E\u9891\u7E41\uFF0C\u8BF7\u7A0D\u540E\u518D\u8BD5") {
+    const limiter = this.getLimiter(limiterName);
+    const storageKey = this.toStorageKey(key);
+    if (pointsToConsume <= 0 || !Number.isFinite(pointsToConsume)) {
+      throw new import_core.BusinessException(`\u6D88\u8D39\u70B9\u6570\u65E0\u6548: ${pointsToConsume}`, "INVALID_POINTS", 400);
+    }
+    try {
+      const res = await limiter.consume(storageKey, pointsToConsume);
+      return {
+        remaining: res.remainingPoints,
+        msBeforeNext: res.msBeforeNext,
+        consumedPoints: res.consumedPoints
+      };
+    } catch (error) {
+      if (error && typeof error === "object" && "msBeforeNext" in error) {
+        const res = error;
+        const retryAfter = Math.ceil(res.msBeforeNext / 1e3);
+        this.logger.warn(`\u9650\u6D41\u89E6\u53D1: limiter=${limiterName}, retryAfter=${retryAfter}s`);
+        throw new TooManyRequestsException(errorMessage, retryAfter);
+      }
+      throw error;
+    }
+  }
+  /**
+  * Apply a penalty by consuming extra points, extending the block time.
+  * Useful for failed login attempts, abuse detection, etc.
+  */
+  async penalty(limiterName, key, points = 1) {
+    const limiter = this.getLimiter(limiterName);
+    await limiter.penalty(this.toStorageKey(key), points);
+    this.logger.log(`\u9650\u6D41\u60E9\u7F5A: limiter=${limiterName}, points=${points}`);
+  }
+  /**
+  * Reward by reducing consumed points (opposite of penalty).
+  */
+  async reward(limiterName, key, points = 1) {
+    const limiter = this.getLimiter(limiterName);
+    await limiter.reward(this.toStorageKey(key), points);
+  }
+  async getRemaining(limiterName, key) {
+    const limiter = this.getLimiter(limiterName);
+    const res = await limiter.get(this.toStorageKey(key));
+    if (!res) {
+      const config = this.options.limiters[limiterName];
+      return {
+        remaining: config.points,
+        resetAt: new Date(Date.now() + config.duration * 1e3)
+      };
+    }
+    return {
+      remaining: res.remainingPoints,
+      resetAt: new Date(Date.now() + res.msBeforeNext)
+    };
+  }
+  async reset(limiterName, key) {
+    const limiter = this.getLimiter(limiterName);
+    await limiter.delete(this.toStorageKey(key));
+  }
+  /**
+  * Convenience method for public API rate limiting.
+  * Consumes 1 point from the named limiter using the given key.
+  * Throws TooManyRequestsException (429) when limit is exceeded.
+  *
+  * @param key - Unique identifier for the consumer (e.g., IP address)
+  * @param limiterName - Name of the registered rate limiter
+  */
+  async checkPublicApiLimit(key, limiterName) {
+    await this.consume(limiterName, key, 1, "\u8BF7\u6C42\u8FC7\u4E8E\u9891\u7E41\uFF0C\u8BF7\u7A0D\u540E\u518D\u8BD5");
+  }
+  /**
+  * Check AI operation rate limit for a user.
+  * Falls back gracefully if the limiter doesn't exist (AI ops are best-effort limited).
+  *
+  * @param userId - User identifier
+  * @param operation - Human-readable description of the AI operation
+  * @param points - Points to consume (default: 1)
+  */
+  async checkAILimit(userId, operation, points = 1) {
+    const limiterName = "ai-default";
+    if (!this.has(limiterName)) return;
+    await this.consume(limiterName, userId, points, `AI \u64CD\u4F5C"${operation}"\u8BF7\u6C42\u8FC7\u4E8E\u9891\u7E41\uFF0C\u8BF7\u7A0D\u540E\u518D\u8BD5`);
+  }
+  /** Check if a limiter exists by name */
+  has(limiterName) {
+    return this.limiters.has(limiterName);
+  }
+  /** Get all registered limiter names */
+  getLimiterNames() {
+    return [
+      ...this.limiters.keys()
+    ];
+  }
+  isDistributed() {
+    return this.useRedis;
+  }
+  /** Get a limiter by name, throwing if not found */
+  getLimiter(limiterName) {
+    const limiter = this.limiters.get(limiterName);
+    if (!limiter) {
+      throw new import_core.NotFoundException(`\u9650\u6D41\u5668 '${limiterName}' \u4E0D\u5B58\u5728 (\u53EF\u7528: ${this.getLimiterNames().join(", ")})`);
+    }
+    return limiter;
+  }
+  toStorageKey(key) {
+    return deriveRateLimitKey(key, this.options.keyHashSecret);
+  }
+};
+RateLimiterService = _ts_decorate([
+  (0, import_common.Injectable)(),
+  _ts_metadata("design:type", Function),
+  _ts_metadata("design:paramtypes", [
+    typeof RateLimiterModuleOptions === "undefined" ? Object : RateLimiterModuleOptions
+  ])
+], RateLimiterService);
+
+// src/rate-limiter.module.ts
+var import_common4 = require("@nestjs/common");
+var import_core3 = require("@nestjs/core");
+
+// src/guards/rate-limit.guard.ts
+var import_common3 = require("@nestjs/common");
+var import_core2 = require("@nestjs/core");
+
+// src/decorators/rate-limit.decorator.ts
+var import_common2 = require("@nestjs/common");
+var RATE_LIMIT_KEY = "ZUCKER_RATE_LIMIT";
+function RateLimit(options) {
+  const opts = typeof options === "string" ? {
+    limiter: options
+  } : options;
+  return (0, import_common2.SetMetadata)(RATE_LIMIT_KEY, opts);
+}
+__name(RateLimit, "RateLimit");
+
+// src/guards/rate-limit.guard.ts
+function _ts_decorate2(decorators, target, key, desc) {
+  var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+  if (typeof Reflect === "object" && typeof Reflect.decorate === "function") {
+    r = Reflect.decorate(decorators, target, key, desc);
+  } else {
+    for (var i = decorators.length - 1; i >= 0; i--) {
+      if (d = decorators[i]) {
+        r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+      }
+    }
+  }
+  return c > 3 && r && Object.defineProperty(target, key, r), r;
+}
+__name(_ts_decorate2, "_ts_decorate");
+function _ts_metadata2(metadataKey, metadataValue) {
+  if (typeof Reflect === "object" && typeof Reflect.metadata === "function") {
+    return Reflect.metadata(metadataKey, metadataValue);
+  }
+}
+__name(_ts_metadata2, "_ts_metadata");
+function _ts_param(paramIndex, decorator) {
+  return function(target, key) {
+    decorator(target, key, paramIndex);
+  };
+}
+__name(_ts_param, "_ts_param");
+var RateLimitGuard = class {
+  static {
+    __name(this, "RateLimitGuard");
+  }
+  reflector;
+  rateLimiterService;
+  constructor(reflector, rateLimiterService) {
+    this.reflector = reflector;
+    this.rateLimiterService = rateLimiterService;
+  }
+  async canActivate(context) {
+    const options = this.reflector.getAllAndOverride(RATE_LIMIT_KEY, [
+      context.getHandler(),
+      context.getClass()
+    ]);
+    if (!options || !this.rateLimiterService) return true;
+    const request = context.switchToHttp().getRequest();
+    const key = this.extractKey(request, options);
+    try {
+      await this.rateLimiterService.consume(options.limiter, key);
+      return true;
+    } catch (err) {
+      if (err instanceof TooManyRequestsException) {
+        throw new TooManyRequestsException(options.message ?? "Too many requests", err.retryAfter);
+      }
+      throw err;
+    }
+  }
+  extractKey(request, options) {
+    const networkKey = request.ip ?? request.socket?.remoteAddress ?? "unknown-client";
+    switch (options.keyExtractor) {
+      case "#userId":
+        return request.user?.id ?? networkKey;
+      case "#username":
+        return request.user?.username ?? networkKey;
+      default:
+        return networkKey;
+    }
+  }
+};
+RateLimitGuard = _ts_decorate2([
+  (0, import_common3.Injectable)(),
+  _ts_param(1, (0, import_common3.Inject)("RATE_LIMITER_SERVICE")),
+  _ts_param(1, (0, import_common3.Optional)()),
+  _ts_metadata2("design:type", Function),
+  _ts_metadata2("design:paramtypes", [
+    typeof import_core2.Reflector === "undefined" ? Object : import_core2.Reflector,
+    Object
+  ])
+], RateLimitGuard);
+
+// src/rate-limiter.module.ts
+function _ts_decorate3(decorators, target, key, desc) {
+  var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+  if (typeof Reflect === "object" && typeof Reflect.decorate === "function") {
+    r = Reflect.decorate(decorators, target, key, desc);
+  } else {
+    for (var i = decorators.length - 1; i >= 0; i--) {
+      if (d = decorators[i]) {
+        r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+      }
+    }
+  }
+  return c > 3 && r && Object.defineProperty(target, key, r), r;
+}
+__name(_ts_decorate3, "_ts_decorate");
+var RATE_LIMITER_MODULE_OPTIONS = /* @__PURE__ */ Symbol("RATE_LIMITER_MODULE_OPTIONS");
+var ZuckerRateLimiterModule = class _ZuckerRateLimiterModule {
+  static {
+    __name(this, "ZuckerRateLimiterModule");
+  }
+  static forRoot(options) {
+    const providers = [
+      {
+        provide: RateLimiterService,
+        useFactory: /* @__PURE__ */ __name(() => new RateLimiterService(options), "useFactory")
+      },
+      {
+        provide: "RATE_LIMITER_SERVICE",
+        useExisting: RateLimiterService
+      },
+      RateLimitGuard
+    ];
+    if (options.globalGuard !== false) {
+      providers.push({
+        provide: import_core3.APP_GUARD,
+        useExisting: RateLimitGuard
+      });
+    }
+    return {
+      module: _ZuckerRateLimiterModule,
+      global: true,
+      providers,
+      exports: [
+        RateLimiterService,
+        RateLimitGuard,
+        "RATE_LIMITER_SERVICE"
+      ]
+    };
+  }
+  static forRootAsync(options) {
+    const asyncProviders = this.createAsyncProviders(options);
+    const providers = [
+      ...asyncProviders,
+      {
+        provide: RateLimiterService,
+        useFactory: /* @__PURE__ */ __name((opts) => new RateLimiterService(opts), "useFactory"),
+        inject: [
+          RATE_LIMITER_MODULE_OPTIONS
+        ]
+      },
+      {
+        provide: "RATE_LIMITER_SERVICE",
+        useExisting: RateLimiterService
+      },
+      RateLimitGuard
+    ];
+    if (options.globalGuard !== false) {
+      providers.push({
+        provide: import_core3.APP_GUARD,
+        useExisting: RateLimitGuard
+      });
+    }
+    return {
+      module: _ZuckerRateLimiterModule,
+      global: true,
+      imports: options.imports ?? [],
+      providers,
+      exports: [
+        RateLimiterService,
+        RateLimitGuard,
+        "RATE_LIMITER_SERVICE"
+      ]
+    };
+  }
+  static createAsyncProviders(options) {
+    if (options.useFactory) {
+      return [
+        {
+          provide: RATE_LIMITER_MODULE_OPTIONS,
+          useFactory: options.useFactory,
+          inject: options.inject ?? []
+        }
+      ];
+    }
+    const optionsProvider = {
+      provide: RATE_LIMITER_MODULE_OPTIONS,
+      useFactory: /* @__PURE__ */ __name(async (factory) => factory.createRateLimiterOptions(), "useFactory"),
+      inject: [
+        options.useClass ?? options.useExisting
+      ]
+    };
+    if (options.useClass) {
+      return [
+        {
+          provide: options.useClass,
+          useClass: options.useClass
+        },
+        optionsProvider
+      ];
+    }
+    return [
+      optionsProvider
+    ];
+  }
+};
+ZuckerRateLimiterModule = _ts_decorate3([
+  (0, import_common4.Global)(),
+  (0, import_common4.Module)({})
+], ZuckerRateLimiterModule);
+
+// src/dynamic-limiter.ts
+var import_common5 = require("@nestjs/common");
+function _ts_decorate4(decorators, target, key, desc) {
+  var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+  if (typeof Reflect === "object" && typeof Reflect.decorate === "function") {
+    r = Reflect.decorate(decorators, target, key, desc);
+  } else {
+    for (var i = decorators.length - 1; i >= 0; i--) {
+      if (d = decorators[i]) {
+        r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+      }
+    }
+  }
+  return c > 3 && r && Object.defineProperty(target, key, r), r;
+}
+__name(_ts_decorate4, "_ts_decorate");
+var DynamicLimiterManager = class _DynamicLimiterManager {
+  static {
+    __name(this, "DynamicLimiterManager");
+  }
+  logger = new import_common5.Logger(_DynamicLimiterManager.name);
+  rules = /* @__PURE__ */ new Map();
+  listeners = [];
+  /** 添加或更新限流规则 */
+  setRule(rule) {
+    rule.createdAt = rule.createdAt ?? Date.now();
+    this.rules.set(rule.id, rule);
+    this.notifyListeners();
+    this.logger.log(`Dynamic limiter rule set: ${rule.id} (${rule.points}/${rule.duration}s)`);
+  }
+  /** 删除限流规则 */
+  removeRule(id) {
+    const removed = this.rules.delete(id);
+    if (removed) {
+      this.notifyListeners();
+      this.logger.log(`Dynamic limiter rule removed: ${id}`);
+    }
+    return removed;
+  }
+  /** 获取所有规则（按优先级排序） */
+  getRules() {
+    return Array.from(this.rules.values()).filter((r) => r.enabled).sort((a, b) => (b.priority ?? 0) - (a.priority ?? 0));
+  }
+  /** 根据路径和角色匹配限流规则 */
+  matchRule(path, roles) {
+    for (const rule of this.getRules()) {
+      if (rule.pathPattern) {
+        const regex = this.globToRegex(rule.pathPattern);
+        if (!regex.test(path)) continue;
+      }
+      if (rule.roles?.length) {
+        if (!roles?.some((r) => rule.roles.includes(r))) continue;
+      }
+      return rule;
+    }
+    return void 0;
+  }
+  /** 批量导入规则 */
+  importRules(rules) {
+    for (const rule of rules) {
+      this.rules.set(rule.id, {
+        ...rule,
+        createdAt: rule.createdAt ?? Date.now()
+      });
+    }
+    this.notifyListeners();
+    this.logger.log(`Imported ${rules.length} dynamic limiter rules`);
+  }
+  /** 导出所有规则 */
+  exportRules() {
+    return Array.from(this.rules.values());
+  }
+  /** 监听规则变更 */
+  onRulesChanged(listener) {
+    this.listeners.push(listener);
+    return {
+      unsubscribe: /* @__PURE__ */ __name(() => {
+        const idx = this.listeners.indexOf(listener);
+        if (idx >= 0) this.listeners.splice(idx, 1);
+      }, "unsubscribe")
+    };
+  }
+  /** 启用/禁用规则 */
+  toggleRule(id, enabled) {
+    const rule = this.rules.get(id);
+    if (!rule) return false;
+    rule.enabled = enabled;
+    this.notifyListeners();
+    return true;
+  }
+  notifyListeners() {
+    const rules = this.getRules();
+    for (const listener of this.listeners) {
+      try {
+        listener(rules);
+      } catch {
+      }
+    }
+  }
+  globToRegex(glob) {
+    const escaped = glob.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*").replace(/\?/g, ".");
+    return new RegExp(`^${escaped}$`);
+  }
+};
+DynamicLimiterManager = _ts_decorate4([
+  (0, import_common5.Injectable)()
+], DynamicLimiterManager);
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  DynamicLimiterManager,
+  RATE_LIMIT_KEY,
+  RateLimit,
+  RateLimitGuard,
+  RateLimiterService,
+  TooManyRequestsException,
+  ZuckerRateLimiterModule,
+  deriveRateLimitKey
+});