@fluojs/throttler 1.0.0-beta.2 → 1.0.0-beta.4

package/README.ko.md

@@ -69,7 +69,7 @@ class AuthController {
 
 ### Redis 저장소 사용
 
-다중 인스턴스 배포 환경에서는 `RedisThrottlerStore`를 사용하여 모든 인스턴스 간에 속도 제한 상태를 공유하세요.
+다중 인스턴스 배포 환경에서는 `RedisThrottlerStore`를 사용하여 모든 인스턴스 간에 속도 제한 상태를 공유하세요. Redis 기반 윈도우는 Redis 서버 시간을 기준으로 고정되므로, 애플리케이션 노드 간 시계 오차가 있어도 하나의 공통 reset 경계를 강제합니다.
 
 ```typescript
 import { ThrottlerModule, RedisThrottlerStore } from '@fluojs/throttler';

package/README.md

@@ -69,7 +69,7 @@ class AuthController {
 
 ### Redis Storage
 
-For multi-instance deployments, use `RedisThrottlerStore` to share the rate limit state across all instances.
+For multi-instance deployments, use `RedisThrottlerStore` to share the rate limit state across all instances. Redis-backed windows are anchored to Redis server time, so distributed app nodes with clock skew still enforce one shared reset boundary.
 
 ```typescript
 import { ThrottlerModule, RedisThrottlerStore } from '@fluojs/throttler';

package/dist/guard.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"guard.d.ts","sourceRoot":"","sources":["../src/guard.ts"],"names":[],"mappings":"AAEA,OAAO,EAA4B,KAAK,KAAK,EAAE,KAAK,YAAY,EAA0B,MAAM,cAAc,CAAC;AAY/G,OAAO,KAAK,EAAE,sBAAsB,EAAkB,MAAM,YAAY,CAAC;AA2CzE;;GAEG;AACH,qBACa,cAAe,YAAW,KAAK;IAG9B,OAAO,CAAC,QAAQ,CAAC,OAAO;IAFpC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAiB;gBAEV,OAAO,EAAE,sBAAsB;IAK5D;;;;;;OAMG;IACG,WAAW,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,OAAO,CAAC;CAiD3D"}
+{"version":3,"file":"guard.d.ts","sourceRoot":"","sources":["../src/guard.ts"],"names":[],"mappings":"AAEA,OAAO,EAA4B,KAAK,KAAK,EAAE,KAAK,YAAY,EAA0B,MAAM,cAAc,CAAC;AAa/G,OAAO,KAAK,EAAE,sBAAsB,EAAuC,MAAM,YAAY,CAAC;AAuD9F;;GAEG;AACH,qBACa,cAAe,YAAW,KAAK;IAG9B,OAAO,CAAC,QAAQ,CAAC,OAAO;IAFpC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAiB;gBAEV,OAAO,EAAE,sBAAsB;IAK5D;;;;;;OAMG;IACG,WAAW,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,OAAO,CAAC;CAkD3D"}

package/dist/guard.js

@@ -5,15 +5,16 @@ function _toPrimitive(t, r) { if ("object" != typeof t || !t) return t; var e =
 function _setFunctionName(e, t, n) { "symbol" == typeof t && (t = (t = t.description) ? "[" + t + "]" : ""); try { Object.defineProperty(e, "name", { configurable: !0, value: n ? n + " " + t : t }); } catch (e) {} return e; }
 function _checkInRHS(e) { if (Object(e) !== e) throw TypeError("right-hand side of 'in' should be an object, got " + (null !== e ? typeof e : "null")); return e; }
 import { Inject } from '@fluojs/core';
-import { metadataSymbol } from '@fluojs/core/internal';
+import { getStandardMetadataBag } from '@fluojs/core/internal';
 import { TooManyRequestsException } from '@fluojs/http';
 import { resolveClientIdentity } from '@fluojs/http/internal';
 import { getClassSkipThrottleMetadata, getClassThrottleMetadata, getSkipThrottleMetadata, getThrottleMetadata, throttleRouteMetadataKey } from './decorators.js';
+import { throttlerRetryAfterMsSymbol } from './store-internals.js';
 import { createMemoryThrottlerStore } from './store.js';
 import { THROTTLER_OPTIONS } from './tokens.js';
 import { validateThrottleOptions, validateThrottlerModuleOptions, validateThrottlerStoreEntry } from './validation.js';
 function getClassMetadataBag(target) {
-  return target[metadataSymbol];
+  return getStandardMetadataBag(target);
 }
 function getMethodMetadataBag(controllerToken, methodName) {
   const classBag = getClassMetadataBag(controllerToken);
@@ -37,6 +38,13 @@ function buildHandlerKey(handler) {
   const version = handler.route.version ?? handler.metadata.effectiveVersion ?? 'unversioned';
   return [`method:${handler.route.method}`, `path:${encodeURIComponent(handler.route.path)}`, `version:${encodeURIComponent(version)}`, `handler:${encodeURIComponent(handler.methodName)}`].join('|');
 }
+function resolveRetryAfterSeconds(entry, now) {
+  const retryAfterMs = entry[throttlerRetryAfterMsSymbol];
+  if (typeof retryAfterMs === 'number' && Number.isFinite(retryAfterMs)) {
+    return Math.max(1, Math.ceil(retryAfterMs / 1000));
+  }
+  return Math.max(1, Math.ceil((entry.resetAt - now) / 1000));
+}
 
 /**
  * Guard that enforces module-, class-, and method-level throttling policies.
@@ -89,12 +97,13 @@ class ThrottlerGuard {
     const handlerKey = buildHandlerKey(handler);
     const storeKey = buildStoreKey(handlerKey, clientKey);
     const now = Date.now();
-    const entry = validateThrottlerStoreEntry(await this.store.consume(storeKey, {
+    const rawEntry = await this.store.consume(storeKey, {
       now,
       ttlSeconds
-    }));
+    });
+    const entry = validateThrottlerStoreEntry(rawEntry);
     if (entry.count > limit) {
-      const retryAfter = Math.ceil((entry.resetAt - now) / 1000);
+      const retryAfter = resolveRetryAfterSeconds(rawEntry, now);
       requestContext.response.setHeader('Retry-After', String(retryAfter));
       throw new TooManyRequestsException('Too Many Requests', {
         meta: {

package/dist/redis-store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"redis-store.d.ts","sourceRoot":"","sources":["../src/redis-store.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,SAAS,CAAC;AAEjC,OAAO,KAAK,EAAE,qBAAqB,EAAE,cAAc,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AA4C7F;;;;;;GAMG;AACH,qBAAa,mBAAoB,YAAW,cAAc;IAC5C,OAAO,CAAC,QAAQ,CAAC,MAAM;gBAAN,MAAM,EAAE,KAAK;IAE1C;;;;;;OAMG;IACG,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,qBAAqB,GAAG,OAAO,CAAC,mBAAmB,CAAC;CAWvF"}
+{"version":3,"file":"redis-store.d.ts","sourceRoot":"","sources":["../src/redis-store.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,SAAS,CAAC;AAGjC,OAAO,KAAK,EAAE,qBAAqB,EAAE,cAAc,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AA8D7F;;;;;;GAMG;AACH,qBAAa,mBAAoB,YAAW,cAAc;IAC5C,OAAO,CAAC,QAAQ,CAAC,MAAM;gBAAN,MAAM,EAAE,KAAK;IAE1C;;;;;;OAMG;IACG,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,qBAAqB,GAAG,OAAO,CAAC,mBAAmB,CAAC;CAUvF"}

package/dist/redis-store.js

@@ -1,18 +1,29 @@
+import { throttlerRetryAfterMsSymbol } from './store-internals.js';
 import { validateThrottlerStoreEntry } from './validation.js';
-const CONSUME_LUA = ["local key = KEYS[1]", "local now = tonumber(ARGV[1])", "local ttlMs = tonumber(ARGV[2])", "local raw = redis.call('GET', key)", "local count", "local resetAt", 'if not raw then', '  count = 1', '  resetAt = now + ttlMs', 'else', '  local decoded = cjson.decode(raw)', "  count = tonumber(decoded['count']) or 0", "  resetAt = tonumber(decoded['resetAt']) or (now + ttlMs)", '  if now >= resetAt then', '    count = 1', '    resetAt = now + ttlMs', '  else', '    count = count + 1', '  end', 'end', 'local ttlMsLeft = math.max(resetAt - now, 1)', "redis.call('SET', key, cjson.encode({ count = count, resetAt = resetAt }), 'PX', ttlMsLeft)", 'return {count, resetAt}'].join('\n');
+const CONSUME_LUA = ["local key = KEYS[1]", "local ttlMs = tonumber(ARGV[1])", "local time = redis.call('TIME')", "local nowSeconds = tonumber(time[1])", "local nowMicros = tonumber(time[2])", 'local now = math.floor((nowSeconds * 1000) + (nowMicros / 1000))', "local raw = redis.call('GET', key)", "local count", "local resetAt", 'if not raw then', '  count = 1', '  resetAt = now + ttlMs', 'else', '  local decoded = cjson.decode(raw)', "  count = tonumber(decoded['count']) or 0", "  resetAt = tonumber(decoded['resetAt']) or (now + ttlMs)", '  if now >= resetAt then', '    count = 1', '    resetAt = now + ttlMs', '  else', '    count = count + 1', '  end', 'end', 'local ttlMsLeft = math.max(resetAt - now, 1)', "redis.call('SET', key, cjson.encode({ count = count, resetAt = resetAt }), 'PX', ttlMsLeft)", 'return {count, resetAt, ttlMsLeft}'].join('\n');
 function parseConsumeResult(result) {
   if (!Array.isArray(result) || result.length < 2) {
     throw new Error('Redis throttler consume script returned an invalid response.');
   }
   const count = Number(result[0]);
   const resetAt = Number(result[1]);
+  const retryAfterMs = result.length >= 3 ? Number(result[2]) : Number.NaN;
   if (!Number.isFinite(count) || !Number.isFinite(resetAt)) {
     throw new Error('Redis throttler consume script returned non-numeric counters.');
   }
-  return validateThrottlerStoreEntry({
+  const entry = validateThrottlerStoreEntry({
     count,
     resetAt
   });
+  if (Number.isFinite(retryAfterMs)) {
+    Object.defineProperty(entry, throttlerRetryAfterMsSymbol, {
+      configurable: false,
+      enumerable: false,
+      value: retryAfterMs,
+      writable: false
+    });
+  }
+  return entry;
 }
 
 /**
@@ -35,7 +46,7 @@ export class RedisThrottlerStore {
    * @returns The updated counter value and reset timestamp for the current window.
    */
   async consume(key, input) {
-    const result = await this.client.eval(CONSUME_LUA, 1, key, String(input.now), String(input.ttlSeconds * 1000));
+    const result = await this.client.eval(CONSUME_LUA, 1, key, String(input.ttlSeconds * 1000));
     return parseConsumeResult(result);
   }
 }

package/dist/store-internals.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Internal store-entry symbol used to carry Redis-derived retry-after milliseconds.
+ */
+export declare const throttlerRetryAfterMsSymbol: unique symbol;
+//# sourceMappingURL=store-internals.d.ts.map

package/dist/store-internals.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store-internals.d.ts","sourceRoot":"","sources":["../src/store-internals.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,eAAO,MAAM,2BAA2B,eAAmC,CAAC"}

package/dist/store-internals.js

@@ -0,0 +1,4 @@
+/**
+ * Internal store-entry symbol used to carry Redis-derived retry-after milliseconds.
+ */
+export const throttlerRetryAfterMsSymbol = Symbol('throttler.retryAfterMs');

package/package.json

@@ -9,7 +9,7 @@
     "redis",
     "decorator"
   ],
-  "version": "1.0.0-beta.2",
+  "version": "1.0.0-beta.4",
   "private": false,
   "license": "MIT",
   "repository": {
@@ -36,10 +36,10 @@
     "dist"
   ],
   "dependencies": {
-    "@fluojs/core": "^1.0.0-beta.1",
-    "@fluojs/di": "^1.0.0-beta.2",
-    "@fluojs/http": "^1.0.0-beta.1",
-    "@fluojs/runtime": "^1.0.0-beta.2"
+    "@fluojs/core": "^1.0.0-beta.2",
+    "@fluojs/di": "^1.0.0-beta.4",
+    "@fluojs/runtime": "^1.0.0-beta.4",
+    "@fluojs/http": "^1.0.0-beta.3"
   },
   "peerDependencies": {
     "ioredis": "^5.0.0",