mm_rate_limit 0.0.0-stage → 1.0.1

package/README.md

@@ -1,3 +1,31 @@
-# Temporary Holding Version
+# mm_rate_limit 限流模块
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+按 key 维度（用户 id、IP、路由等）的令牌桶限流：桶容量 `capacity`，按 `interval` 毫秒匀速补充，支持突发流量与速率控制。
+
+## 快速开始
+
+```javascript
+const { rateLimitAdmin } = require('mm_rate_limit');
+
+const limiter = rateLimitAdmin('web', { capacity: 60, interval: 60000 }); // 每分钟 60 次
+
+// 事件 before 阶段或中间件中检查
+const rl = limiter.check(ctx.ip);
+if (!rl.allowed) {
+  ctx.status = 429;
+  ctx.retry_after = rl.retry_after; // 建议等待毫秒数
+  return;
+}
+```
+
+## API
+
+| 方法 | 说明 |
+| --- | --- |
+| `check(key, cost?)` | 消费令牌，返回 `{ allowed, remaining, retry_after, limit }` |
+| `reset(key)` | 删除某个 key 的桶（重置） |
+| `clear()` | 清空全部桶 |
+
+默认配置：`capacity: 60`、`interval: 60000`（每分钟 60 次）、`max_keys: 10000`（超限淘汰最久未用的桶）。
+
+`rateLimitAdmin(scope, config)` 按作用域缓存实例，相同 `scope` 返回同一实例。

package/index.js

@@ -0,0 +1,25 @@
+const { RateLimit } = require('./lib/rate_limit.js');
+const Admin = require('mm_corejs').Admin;
+
+/**
+ * 限流管理 Admin 工厂
+ * 支持 os.js 调用：require('mm_rate_limit').admin.setServer(os) -> admin.get(scope, config)
+ */
+let admin = new Admin();
+admin.setClass(RateLimit);
+
+/**
+ * 获取（或创建）指定作用域的限流实例
+ * @param {string} [scope] 作用域，缺省 'web'
+ * @param {Object} [config] 配置参数
+ * @returns {RateLimit} 限流实例
+ */
+function rateLimitAdmin(scope, config) {
+  return admin.get(scope || 'web', config);
+}
+
+module.exports = {
+  RateLimit,
+  admin,
+  rateLimitAdmin
+};

package/lib/rate_limit.js

@@ -0,0 +1,116 @@
+'use strict';
+
+const { Base } = require('mm_mod');
+
+/**
+ * 令牌桶限流类
+ *
+ * 以 key（如用户 id、IP、路由）为维度的令牌桶限流：
+ * 桶容量 capacity，按 interval 毫秒匀速补充 capacity 个令牌（速率 = capacity/interval）。
+ * 突发流量可一次性消费桶内存量令牌，长期速率不超过补充速率。
+ */
+class RateLimit extends Base {
+  /**
+   * 模块默认配置
+   */
+  static config = {
+    name: 'rate_limit',
+    title: '令牌桶限流模块',
+    description: '按 key 维度的令牌桶限流，支持突发与匀速补充',
+    // 桶容量（突发上限）
+    capacity: 60,
+    // 补充周期（毫秒），每周期补充 capacity 个令牌
+    interval: 60000,
+    // 最大跟踪 key 数，超出后淘汰最久未使用的桶
+    max_keys: 10000
+  };
+
+  /**
+   * 桶表：key -> { tokens, updated_at }
+   * @type {Map<string, Object>}
+   */
+  #buckets = new Map();
+
+  /**
+   * 计算当前可用令牌并消费
+   * @param {string} key 限流维度（用户 id、IP、路由等）
+   * @param {number} [cost] 本次消耗令牌数，默认 1
+   * @returns {Object} 结果 { allowed, remaining, retry_after, limit }
+   */
+  check(key, cost) {
+    if (!key || typeof key !== 'string') {
+      throw new TypeError(`${this._label()} key must be a non-empty string`);
+    }
+    const want = cost === undefined ? 1 : cost;
+    if (typeof want !== 'number' || !Number.isFinite(want) || want <= 0) {
+      throw new TypeError(`${this._label()} cost must be a positive finite number`);
+    }
+    const capacity = this.config.capacity;
+    const interval = this.config.interval;
+    const now = Date.now();
+
+    let bucket = this.#buckets.get(key);
+    if (!bucket) {
+      // 淘汰最久未用的桶，防止内存膨胀
+      if (this.#buckets.size >= this.config.max_keys) {
+        let oldest_key = null;
+        let oldest = Infinity;
+        for (const [k, b] of this.#buckets) {
+          if (b.updated_at < oldest) {
+            oldest = b.updated_at;
+            oldest_key = k;
+          }
+        }
+        if (oldest_key !== null) {
+          this.#buckets.delete(oldest_key);
+        }
+      }
+      bucket = { tokens: capacity, updated_at: now };
+      this.#buckets.set(key, bucket);
+    }
+
+    // 按时间流逝补充令牌（不足一个周期按比例补充）
+    const elapsed = Math.max(0, now - bucket.updated_at);
+    if (elapsed > 0 && bucket.tokens < capacity) {
+      const refill = (elapsed / interval) * capacity;
+      bucket.tokens = Math.min(capacity, bucket.tokens + refill);
+    }
+    bucket.updated_at = now;
+
+    const allowed = bucket.tokens >= want;
+    const result = {
+      allowed,
+      remaining: Math.floor(Math.max(0, bucket.tokens - (allowed ? want : 0))),
+      retry_after: 0,
+      limit: capacity
+    };
+    if (allowed) {
+      bucket.tokens -= want;
+    } else {
+      // 计算补足所需令牌的等待毫秒数（向上取整到秒）
+      const need = want - bucket.tokens;
+      result.retry_after = Math.ceil((need / capacity) * interval / 1000) * 1000;
+    }
+    return result;
+  }
+
+  /**
+   * 删除某个 key 的桶（如用户登出时重置）
+   * @param {string} key 限流维度
+   * @returns {boolean} 是否删除成功
+   */
+  reset(key) {
+    return this.#buckets.delete(key);
+  }
+
+  /**
+   * 清空全部桶
+   * @returns {RateLimit} 当前实例
+   */
+  clear() {
+    this.#buckets.clear();
+    return this;
+  }
+}
+
+module.exports = { RateLimit };

package/package.json

@@ -1,6 +1,27 @@
 {
-  "name": "mm_rate_limit",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+    "name": "mm_rate_limit",
+    "version": "1.0.1",
+    "description": "超级美眉限流模块：按 key 维度的令牌桶限流，支持突发与匀速补充",
+    "main": "index.js",
+    "scripts": {
+        "test": "node test.js && node --test tests/rate_limit.test.js"
+    },
+    "keywords": [
+        "mm_mod",
+        "mm_middleware",
+        "rate_limit",
+        "token_bucket",
+        "throttle"
+    ],
+    "layer": "middleware",
+    "group": "web",
+    "author": "邱文武",
+    "license": "MIT",
+    "dependencies": {
+        "mm_corejs": "^1.1.4",
+        "mm_mod": "^1.0.1"
+    },
+    "engines": {
+        "node": ">=18.0.0"
+    }
+}

package/test.js

@@ -0,0 +1,14 @@
+'use strict';
+const assert = require('assert');
+const mod = require('./index.js');
+
+assert.strictEqual(typeof mod.RateLimit, 'function', '应导出 RateLimit 类');
+assert.strictEqual(typeof mod.rateLimitAdmin, 'function', '应导出 rateLimitAdmin 函数');
+
+const rl = mod.rateLimitAdmin('smoke', { capacity: 2, interval: 60000 });
+assert.ok(rl instanceof mod.RateLimit);
+assert.strictEqual(rl.check('k').allowed, true);
+assert.strictEqual(rl.check('k').allowed, true);
+assert.strictEqual(rl.check('k').allowed, false, '容量耗尽后应拒绝');
+
+console.log('mm_rate_limit 模块测试通过');

package/tests/rate_limit.test.js

@@ -0,0 +1,79 @@
+'use strict';
+/**
+ * mm_rate_limit 单元测试
+ */
+const test = require('node:test');
+const assert = require('assert');
+
+const { RateLimit, rateLimitAdmin } = require('../index.js');
+
+test('基本限流：容量内放行，耗尽拒绝', () => {
+  const rl = new RateLimit({ capacity: 3, interval: 60000 });
+  assert.strictEqual(rl.check('u1').allowed, true);
+  assert.strictEqual(rl.check('u1').allowed, true);
+  assert.strictEqual(rl.check('u1').allowed, true);
+  const denied = rl.check('u1');
+  assert.strictEqual(denied.allowed, false);
+  assert.ok(denied.retry_after > 0, '拒绝时应给出重试等待毫秒');
+  assert.strictEqual(rl.check('u1', 1).remaining, 0, 'remaining 不为负');
+  assert.strictEqual(denied.limit, 3);
+});
+
+test('不同 key 相互隔离', () => {
+  const rl = new RateLimit({ capacity: 1, interval: 60000 });
+  assert.strictEqual(rl.check('a').allowed, true);
+  assert.strictEqual(rl.check('a').allowed, false);
+  assert.strictEqual(rl.check('b').allowed, true, '不同 key 独立计数');
+});
+
+test('cost 批量消费', () => {
+  const rl = new RateLimit({ capacity: 10, interval: 60000 });
+  assert.strictEqual(rl.check('bulk', 4).allowed, true);
+  assert.strictEqual(rl.check('bulk', 4).allowed, true);
+  assert.strictEqual(rl.check('bulk', 4).allowed, false, '余量不足时应拒绝');
+  assert.throws(() => rl.check('bulk', 0), TypeError);
+  assert.throws(() => rl.check('bulk', -1), TypeError);
+  assert.throws(() => rl.check(''), TypeError);
+});
+
+test('时间流逝自动补充令牌（按比例）', async () => {
+  const rl = new RateLimit({ capacity: 10, interval: 100 });
+  for (let i = 0; i < 10; i++) {
+    rl.check('t'); // 耗尽桶
+  }
+  assert.strictEqual(rl.check('t').allowed, false);
+  await new Promise((resolve) => setTimeout(resolve, 150)); // 流逝 150ms，应补充 15 个（截断为满桶 10）
+  assert.strictEqual(rl.check('t').allowed, true, '时间流逝后应补充令牌');
+});
+
+test('reset / clear', () => {
+  const rl = new RateLimit({ capacity: 1, interval: 60000 });
+  rl.check('x');
+  assert.strictEqual(rl.reset('x'), true);
+  assert.strictEqual(rl.reset('x'), false);
+  assert.strictEqual(rl.check('x').allowed, true, 'reset 后重新放行');
+  rl.check('y');
+  rl.clear();
+  assert.strictEqual(rl.check('y').allowed, true, 'clear 后重新放行');
+});
+
+test('max_keys 淘汰最久未用的桶', async () => {
+  const rl = new RateLimit({ capacity: 1, interval: 60000, max_keys: 2 });
+  const tick = () => new Promise((r) => setTimeout(r, 3));
+  rl.check('k1');
+  await tick();
+  rl.check('k2');
+  await tick();
+  rl.check('k1'); // k1 变为最近使用
+  await tick();
+  rl.check('k3'); // 超出 max_keys，应淘汰 k2
+  assert.strictEqual(rl.check('k1').allowed, false, 'k1 已消费，应拒绝');
+  assert.strictEqual(rl.check('k2').allowed, true, 'k2 桶被淘汰后重新满桶');
+});
+
+test('工厂函数按作用域共享实例', () => {
+  const a = rateLimitAdmin('ut-rl', {});
+  const b = rateLimitAdmin('ut-rl');
+  assert.strictEqual(a, b);
+  assert.notStrictEqual(rateLimitAdmin('ut-rl-2'), a);
+});