mm_quota 0.0.0-stage → 1.0.0

package/README.md

@@ -1,3 +1,31 @@
-# Temporary Holding Version
+# mm_quota 配额模块
 
-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、应用 id 等）统计窗口内用量，超出 `limit` 拒绝，窗口结束后自动重置。适用于 API 调用次数、存储容量等配额场景。
+
+## 快速开始
+
+```javascript
+const { quotaAdmin } = require('mm_quota');
+
+const quota = quotaAdmin('web', { limit: 1000, window: 3600000 }); // 每小时 1000 次
+
+const q = quota.consume(ctx.user_id);
+if (!q.allowed) {
+  ctx.status = 429;
+  ctx.retry_after = q.reset_at - Date.now(); // 窗口重置时间
+  return;
+}
+```
+
+## API
+
+| 方法 | 说明 |
+| --- | --- |
+| `consume(key, cost?)` | 消费配额，返回 `{ allowed, used, limit, remaining, reset_at }` |
+| `status(key)` | 查询配额状态（不消费） |
+| `reset(key)` | 重置某个 key 的配额 |
+| `clear()` | 清空全部记录 |
+
+默认配置：`limit: 1000`、`window: 3600000`（1 小时）、`max_keys: 10000`（超限淘汰最久未用的记录）。
+
+`quotaAdmin(scope, config)` 按作用域缓存实例，相同 `scope` 返回同一实例。

package/index.js

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

package/lib/quota.js

@@ -0,0 +1,124 @@
+'use strict';
+
+const { Base } = require('mm_mod');
+
+/**
+ * 配额管理类
+ *
+ * 固定时间窗口配额：按 key 统计窗口内的用量，超出 limit 拒绝，
+ * 窗口结束后自动重置。适用于 API 调用次数、存储容量等配额场景。
+ */
+class Quota extends Base {
+  /**
+   * 模块默认配置
+   */
+  static config = {
+    name: 'quota',
+    title: '配额管理模块',
+    description: '固定时间窗口配额：按 key 统计用量，超限拒绝，窗口自动重置',
+    // 窗口内允许的总用量
+    limit: 1000,
+    // 窗口时长（毫秒）
+    window: 3600000,
+    // 最大跟踪 key 数，超出后淘汰最久未使用的记录
+    max_keys: 10000
+  };
+
+  /**
+   * 配额记录：key -> { used, window_start }
+   * @type {Map<string, Object>}
+   */
+  #records = new Map();
+
+  /**
+   * 消费配额
+   * @param {string} key 配额维度（用户 id、应用 id 等）
+   * @param {number} [cost] 本次消耗量，默认 1
+   * @returns {Object} 结果 { allowed, used, limit, remaining, reset_at }
+   */
+  consume(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 now = Date.now();
+    let record = this.#records.get(key);
+    if (!record) {
+      if (this.#records.size >= this.config.max_keys) {
+        let oldest_key = null;
+        let oldest = Infinity;
+        for (const [k, r] of this.#records) {
+          if (r.window_start < oldest) {
+            oldest = r.window_start;
+            oldest_key = k;
+          }
+        }
+        if (oldest_key !== null) {
+          this.#records.delete(oldest_key);
+        }
+      }
+      record = { used: 0, window_start: now };
+      this.#records.set(key, record);
+    }
+
+    // 窗口已过，自动重置
+    if (now - record.window_start >= this.config.window) {
+      record.used = 0;
+      record.window_start = now;
+    }
+
+    const allowed = record.used + want <= this.config.limit;
+    if (allowed) {
+      record.used += want;
+    }
+    return {
+      allowed,
+      used: record.used,
+      limit: this.config.limit,
+      remaining: Math.max(0, this.config.limit - record.used),
+      reset_at: record.window_start + this.config.window
+    };
+  }
+
+  /**
+   * 查询配额状态（不消费）
+   * @param {string} key 配额维度
+   * @returns {Object} 状态 { used, limit, remaining, reset_at }；未使用过时 used 为 0
+   */
+  status(key) {
+    const record = this.#records.get(key);
+    const now = Date.now();
+    if (!record || now - record.window_start >= this.config.window) {
+      return { used: 0, limit: this.config.limit, remaining: this.config.limit, reset_at: null };
+    }
+    return {
+      used: record.used,
+      limit: this.config.limit,
+      remaining: Math.max(0, this.config.limit - record.used),
+      reset_at: record.window_start + this.config.window
+    };
+  }
+
+  /**
+   * 重置某个 key 的配额
+   * @param {string} key 配额维度
+   * @returns {boolean} 是否删除成功
+   */
+  reset(key) {
+    return this.#records.delete(key);
+  }
+
+  /**
+   * 清空全部配额记录
+   * @returns {Quota} 当前实例
+   */
+  clear() {
+    this.#records.clear();
+    return this;
+  }
+}
+
+module.exports = { Quota };

package/package.json

@@ -1,6 +1,27 @@
 {
   "name": "mm_quota",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "超级美眉配额模块：固定时间窗口配额，按 key 统计用量，超限拒绝，窗口自动重置",
+  "main": "index.js",
+  "scripts": {
+    "test": "node test.js && node --test tests/quota.test.js"
+  },
+  "keywords": [
+    "mm_mod",
+    "mm_middleware",
+    "quota",
+    "limit",
+    "window"
+  ],
+  "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.Quota, 'function', '应导出 Quota 类');
+assert.strictEqual(typeof mod.quotaAdmin, 'function', '应导出 quotaAdmin 函数');
+
+const q = mod.quotaAdmin('smoke', { limit: 2, window: 60000 });
+assert.ok(q instanceof mod.Quota);
+assert.strictEqual(q.consume('k').allowed, true);
+assert.strictEqual(q.consume('k').allowed, true);
+assert.strictEqual(q.consume('k').allowed, false, '超出配额后应拒绝');
+
+console.log('mm_quota 模块测试通过');

package/tests/quota.test.js

@@ -0,0 +1,83 @@
+'use strict';
+/**
+ * mm_quota 单元测试
+ */
+const test = require('node:test');
+const assert = require('assert');
+
+const { Quota, quotaAdmin } = require('../index.js');
+
+test('基本配额：窗口内累计，超限拒绝', () => {
+  const q = new Quota({ limit: 5, window: 60000 });
+  assert.strictEqual(q.consume('u1').allowed, true);
+  assert.strictEqual(q.consume('u1', 3).allowed, true);
+  const denied = q.consume('u1', 2); // 已用 4，再要 2 超限
+  assert.strictEqual(denied.allowed, false);
+  assert.strictEqual(denied.used, 4);
+  assert.strictEqual(denied.remaining, 1);
+  assert.strictEqual(q.consume('u1').allowed, true); // 剩余 1 可用
+  assert.strictEqual(q.consume('u1').allowed, false); // 已满
+  assert.strictEqual(denied.limit, 5);
+  assert.ok(denied.reset_at > Date.now(), 'reset_at 应指向窗口结束时间');
+});
+
+test('不同 key 相互隔离', () => {
+  const q = new Quota({ limit: 1, window: 60000 });
+  assert.strictEqual(q.consume('a').allowed, true);
+  assert.strictEqual(q.consume('a').allowed, false);
+  assert.strictEqual(q.consume('b').allowed, true);
+});
+
+test('cost 参数校验', () => {
+  const q = new Quota({ limit: 10, window: 60000 });
+  assert.throws(() => q.consume('k', 0), TypeError);
+  assert.throws(() => q.consume('k', -5), TypeError);
+  assert.throws(() => q.consume('k', NaN), TypeError);
+  assert.throws(() => q.consume(''), TypeError);
+});
+
+test('status 查询不消费', () => {
+  const q = new Quota({ limit: 10, window: 60000 });
+  assert.strictEqual(q.status('fresh').used, 0);
+  q.consume('fresh', 4);
+  const s = q.status('fresh');
+  assert.strictEqual(s.used, 4);
+  assert.strictEqual(s.remaining, 6);
+  assert.strictEqual(q.status('fresh').used, 4, 'status 不应改变用量');
+  q.consume('fresh', 1);
+  assert.strictEqual(q.status('fresh').used, 5);
+});
+
+test('窗口过期自动重置', async () => {
+  const q = new Quota({ limit: 1, window: 50 });
+  assert.strictEqual(q.consume('w').allowed, true);
+  assert.strictEqual(q.consume('w').allowed, false);
+  await new Promise((r) => setTimeout(r, 70));
+  assert.strictEqual(q.consume('w').allowed, true, '窗口过期后应重置');
+});
+
+test('reset / clear 与 max_keys 淘汰', async () => {
+  const tick = () => new Promise((r) => setTimeout(r, 3));
+  // max_keys 淘汰：按 window_start 淘汰最早创建的记录
+  const q = new Quota({ limit: 1, window: 60000, max_keys: 2 });
+  q.consume('a');
+  await tick();
+  q.consume('b');
+  await tick();
+  q.consume('c'); // 淘汰 a
+  assert.strictEqual(q.status('a').used, 0, 'a 被淘汰');
+  assert.strictEqual(q.status('b').used, 1, 'b 保留');
+  // reset / clear
+  assert.strictEqual(q.reset('b'), true);
+  assert.strictEqual(q.reset('nope'), false);
+  assert.strictEqual(q.status('b').used, 0);
+  q.clear();
+  assert.strictEqual(q.status('c').used, 0);
+});
+
+test('工厂函数按作用域共享实例', () => {
+  const a = quotaAdmin('ut-quota', {});
+  const b = quotaAdmin('ut-quota');
+  assert.strictEqual(a, b);
+  assert.notStrictEqual(quotaAdmin('ut-quota-2'), a);
+});