@fluojs/throttler 1.0.2 → 1.0.4

package/README.ko.md

@@ -12,12 +12,15 @@
 - [공통 패턴](#공통-패턴)
   - [Redis 저장소 사용](#redis-저장소-사용)
   - [커스텀 키 생성](#커스텀-키-생성)
+- [NestJS 마이그레이션 경계](#nestjs-마이그레이션-경계)
 - [공개 API 개요](#공개-api-개요)
 - [관련 패키지](#관련-패키지)
 - [예제 소스](#예제-소스)
 
 ## 설치
 
+`@fluojs/throttler`는 배포 package manifest에서 `engines.node >=20.0.0`을 선언합니다.
+
 ```bash
 npm install @fluojs/throttler
 ```
@@ -71,6 +74,8 @@ class AuthController {
 
 다중 인스턴스 배포 환경에서는 `RedisThrottlerStore`를 사용하여 모든 인스턴스 간에 속도 제한 상태를 공유하세요. Redis 기반 윈도우는 Redis 서버 시간을 기준으로 고정되므로, 애플리케이션 노드 간 시계 오차가 있어도 하나의 공통 reset 경계를 강제합니다.
 
+`RedisThrottlerStore`는 패키지 로컬 구조적 `RedisThrottlerClient` 계약을 받습니다. 이 계약은 `eval(script, numberOfKeys, ...args)` 메서드를 제공하는 Redis command client를 의미합니다. `@fluojs/redis`, `ioredis`, 호환 custom client를 전달할 수 있으며, root `@fluojs/throttler` import가 concrete `ioredis` constructor type에 의존하지 않습니다.
+
 ```typescript
 import { ThrottlerModule, RedisThrottlerStore } from '@fluojs/throttler';
 import { REDIS_CLIENT } from '@fluojs/redis';
@@ -86,7 +91,7 @@ ThrottlerModule.forRoot({
 });
 ```
 
-`ThrottlerStore` 계약을 구현한 객체도 `store` 옵션으로 직접 전달할 수 있습니다.
+`ThrottlerStore` 계약을 구현한 객체도 `store` 옵션으로 직접 전달할 수 있습니다. `ThrottlerModule.forRoot(...)`는 요청 처리 전에 custom store가 `consume(...)` 함수를 노출하는지 검증합니다.
 
 ### 커스텀 키 생성
 
@@ -119,17 +124,27 @@ ThrottlerModule.forRoot({
 });
 ```
 
+## NestJS 마이그레이션 경계
+
+`@nestjs/throttler`에서 마이그레이션할 때 `@fluojs/throttler`는 drop-in 전역 limiter가 아니라 명시적인 guard-stage 패키지로 다뤄야 합니다:
+
+- `ThrottlerModule.forRoot(...)`는 검증된 옵션과 provider를 등록하지만, 모든 route에 throttling을 자동으로 강제하지 않습니다. 보호가 필요한 곳마다 `@UseGuards(ThrottlerGuard)` 같은 Fluo guard metadata로 `ThrottlerGuard`를 활성화하세요.
+- 공개 정책 shape는 하나의 module default와 class 또는 method 수준 `@Throttle({ ttl, limit })` override입니다. burst와 sustained limit을 함께 두는 named multi-window definition은 HTTP middleware, custom `ThrottlerStore`, 또는 애플리케이션이 소유한 guard wrapper로 명시적으로 조합해야 합니다.
+- Forwarded client IP header는 기본적으로 무시됩니다. `Forwarded`, `X-Forwarded-For`, `X-Real-IP`를 신뢰 가능한 proxy가 덮어쓰는 배포에서만 `trustProxyHeaders: true`를 활성화하세요.
+- 제한 초과 시 보장되는 응답 계약은 HTTP `429`와 `Retry-After`입니다. 추가 rate-limit header나 response body는 exception filter 같은 애플리케이션 경계에서 더하세요.
+
 ## 공개 API 개요
 
 ### 모듈
 - `ThrottlerModule.forRoot(options)`: 검증된 throttler 옵션과 `ThrottlerGuard`를 모듈 그래프에 제공합니다.
 - 패키지 수준 등록은 `ThrottlerModule.forRoot(options)`를 통해 지원합니다. 내부 프로바이더 조합 헬퍼와 DI 토큰은 공개 계약에 포함되지 않습니다.
 
-`ttl`과 `limit`은 양의 finite integer여야 합니다. `trustProxyHeaders`와 `keyGenerator`로 client identity를 조정할 수 있습니다. 모듈 옵션은 guard가 연결될 때 검증되고 값으로 캡처되므로, 호출자가 나중에 options 객체를 변경해도 실행 중인 throttling 정책은 바뀌지 않습니다. `store` 옵션을 제공하지 않으면 각 `ThrottlerGuard` 인스턴스가 자체 in-memory store를 소유합니다. 저장소를 공유하거나 외부에서 관리해야 한다면 `RedisThrottlerStore` 같은 `ThrottlerStore` 구현을 전달하세요.
+`ttl`과 `limit`은 양의 finite integer여야 합니다. `global`은 기본값이 `true`입니다. throttler provider를 가져온 모듈 범위에만 유지하려면 `global: false`를 설정하세요. `trustProxyHeaders`와 `keyGenerator`로 client identity를 조정할 수 있으며, `keyGenerator`를 제공할 때는 함수여야 합니다. 모듈 옵션은 guard가 연결될 때 검증되고 값으로 캡처되므로, 호출자가 나중에 options 객체를 변경해도 실행 중인 throttling 정책은 바뀌지 않습니다. `store` 옵션을 제공하지 않으면 각 `ThrottlerGuard` 인스턴스가 자체 in-memory store를 소유합니다. 저장소를 공유하거나 외부에서 관리해야 한다면 `RedisThrottlerStore` 같은 `ThrottlerStore` 구현을 전달하세요.
 
 ### 데코레이터
 - `@Throttle({ ttl, limit })`: 클래스나 메서드에 특정 속도 제한을 설정합니다.
 - `@SkipThrottle()`: 클래스나 메서드에 대해 속도 제한을 비활성화합니다.
+- `ThrottlerHandlerOptions`: `@Throttle(...)`이 받는 공개 `{ ttl, limit }` 정책 shape입니다. 두 값은 모두 양의 finite integer여야 하며, 메서드 수준 정책은 클래스 수준 정책보다 우선하고 클래스 수준 정책은 모듈 기본값보다 우선합니다.
 - 기존 root-barrel metadata helper(`throttleRouteMetadataKey`, `getThrottleMetadata`, `getSkipThrottleMetadata`, `getClassThrottleMetadata`, `getClassSkipThrottleMetadata`)는 decorator metadata를 직접 검사하던 advanced integration과의 호환성을 위해 계속 export됩니다.
 
 ### 가드
@@ -138,8 +153,10 @@ ThrottlerModule.forRoot({
 ### 저장소(Store)
 - `createMemoryThrottlerStore()`: 간단한 메모리 내 저장소를 생성합니다 (기본값).
 - `RedisThrottlerStore`: Redis용 저장소 어댑터입니다.
+- `RedisThrottlerClient`: `RedisThrottlerStore`가 받는 구조적 Redis command client 계약입니다.
 - `ThrottlerStore`: custom store를 위한 공개 계약입니다.
 - `ThrottlerConsumeInput`: custom store가 guard의 현재 시간과 TTL window를 공유할 수 있도록 `ThrottlerStore.consume(key, input)`에 전달되는 공개 입력 shape입니다.
+- `ThrottlerStoreEntry`: `ThrottlerStore.consume(...)`이 반환하는 공개 결과 shape입니다. `count`는 현재 consume 이후 활성 window의 요청 수이고, `resetAt`은 `Retry-After` 계산에 사용하는 epoch millisecond reset 경계입니다. Custom store는 backing store clock이 애플리케이션 프로세스보다 더 authoritative할 때 선택적 `retryAfterMs`를 반환할 수 있으며, guard는 limit 초과 시 이를 `Retry-After` 계산에 사용합니다.
 
 ### status와 diagnostics
 - `createThrottlerPlatformStatusSnapshot(...)`: 플랫폼 status snapshot을 생성합니다.
@@ -155,7 +172,7 @@ ThrottlerModule.forRoot({
 ## 관련 패키지
 
 - `@fluojs/http`: HTTP 컨텍스트 및 예외 처리를 위해 필요합니다.
-- `@fluojs/redis`: `RedisThrottlerStore` 사용 시 필요합니다.
+- `@fluojs/redis`: `RedisThrottlerStore`를 위한 공식 Redis client 통합입니다. `ioredis`와 호환되는 구조적 client도 지원합니다.
 
 ## 예제 소스
 

package/README.md

@@ -12,12 +12,15 @@ Decorator-based rate limiting for fluo applications with in-memory and Redis sto
 - [Common Patterns](#common-patterns)
   - [Redis Storage](#redis-storage)
   - [Custom Key Generation](#custom-key-generation)
+- [NestJS Migration Boundaries](#nestjs-migration-boundaries)
 - [Public API Overview](#public-api-overview)
 - [Related Packages](#related-packages)
 - [Example Sources](#example-sources)
 
 ## Installation
 
+`@fluojs/throttler` declares `engines.node >=20.0.0` in its published package manifest.
+
 ```bash
 npm install @fluojs/throttler
 ```
@@ -71,6 +74,8 @@ class AuthController {
 
 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.
 
+`RedisThrottlerStore` accepts the package-local structural `RedisThrottlerClient` contract: a Redis command client with an `eval(script, numberOfKeys, ...args)` method. `@fluojs/redis`, `ioredis`, and compatible custom clients can be passed without making the root `@fluojs/throttler` import depend on a concrete `ioredis` constructor type.
+
 ```typescript
 import { ThrottlerModule, RedisThrottlerStore } from '@fluojs/throttler';
 import { REDIS_CLIENT } from '@fluojs/redis';
@@ -86,7 +91,7 @@ ThrottlerModule.forRoot({
 });
 ```
 
-You can also pass any object that implements the `ThrottlerStore` contract through the `store` option.
+You can also pass any object that implements the `ThrottlerStore` contract through the `store` option. `ThrottlerModule.forRoot(...)` validates that a custom store exposes a `consume(...)` function before request handling starts.
 
 ### Custom Key Generation
 
@@ -119,17 +124,27 @@ ThrottlerModule.forRoot({
 });
 ```
 
+## NestJS Migration Boundaries
+
+When migrating from `@nestjs/throttler`, treat `@fluojs/throttler` as an explicit guard-stage package rather than a drop-in global limiter:
+
+- `ThrottlerModule.forRoot(...)` registers validated options and providers, but it does not automatically enforce throttling on every route. Activate `ThrottlerGuard` with Fluo guard metadata such as `@UseGuards(ThrottlerGuard)` wherever enforcement is required.
+- The public policy shape is one module default plus class- or method-level `@Throttle({ ttl, limit })` overrides. Named multi-window definitions such as burst plus sustained limits require explicit composition through HTTP middleware, a custom `ThrottlerStore`, or an application-owned guard wrapper.
+- Forwarded client IP headers are ignored by default. Enable `trustProxyHeaders: true` only behind a trusted proxy that overwrites `Forwarded`, `X-Forwarded-For`, or `X-Real-IP`.
+- The guaranteed limit-exceeded response contract is HTTP `429` with `Retry-After`. Additional rate-limit headers or response bodies should be added at the application boundary, for example with an exception filter.
+
 ## Public API Overview
 
 ### Modules
 - `ThrottlerModule.forRoot(options)`: Provides validated throttler options and `ThrottlerGuard` to the module graph.
 - Package-level registration is supported through `ThrottlerModule.forRoot(options)`. Internal provider-composition helpers and DI tokens are not part of the public contract.
 
-`ttl` and `limit` must be positive finite integers. `trustProxyHeaders` and `keyGenerator` customize client identity. Module options are validated and captured by value when the guard is wired so later mutation of the caller's options object does not change live throttling policy. If no `store` option is supplied, each `ThrottlerGuard` instance owns its own in-memory store; pass a `ThrottlerStore` implementation such as `RedisThrottlerStore` when storage must be shared or externally managed.
+`ttl` and `limit` must be positive finite integers. `global` defaults to `true`; set `global: false` when the throttler providers should stay scoped to the importing module. `trustProxyHeaders` and `keyGenerator` customize client identity; `keyGenerator`, when provided, must be a function. Module options are validated and captured by value when the guard is wired so later mutation of the caller's options object does not change live throttling policy. If no `store` option is supplied, each `ThrottlerGuard` instance owns its own in-memory store; pass a `ThrottlerStore` implementation such as `RedisThrottlerStore` when storage must be shared or externally managed.
 
 ### Decorators
 - `@Throttle({ ttl, limit })`: Sets a specific rate limit for a class or method.
 - `@SkipThrottle()`: Disables throttling for a class or method.
+- `ThrottlerHandlerOptions`: Public `{ ttl, limit }` policy shape accepted by `@Throttle(...)`. Both values must be positive finite integers; method-level policies override class-level policies, which override module defaults.
 - Existing root-barrel metadata helpers (`throttleRouteMetadataKey`, `getThrottleMetadata`, `getSkipThrottleMetadata`, `getClassThrottleMetadata`, and `getClassSkipThrottleMetadata`) remain exported for compatibility with advanced integrations that already inspect decorator metadata directly.
 
 ### Guards
@@ -138,8 +153,10 @@ ThrottlerModule.forRoot({
 ### Stores
 - `createMemoryThrottlerStore()`: Creates a simple in-memory store (default).
 - `RedisThrottlerStore`: Store adapter for Redis.
+- `RedisThrottlerClient`: Structural Redis command client contract accepted by `RedisThrottlerStore`.
 - `ThrottlerStore`: Public contract for custom stores.
 - `ThrottlerConsumeInput`: Public input shape passed to `ThrottlerStore.consume(key, input)` so custom stores can share the guard's current time and TTL window.
+- `ThrottlerStoreEntry`: Public result shape returned by `ThrottlerStore.consume(...)`; `count` is the post-consume request count for the active window and `resetAt` is the epoch-millisecond reset boundary used for `Retry-After` calculation. Custom stores may return optional `retryAfterMs` when a backing store has a more authoritative clock than the application process; the guard uses it for `Retry-After` when the limit is exceeded.
 
 ### Status and diagnostics
 - `createThrottlerPlatformStatusSnapshot(...)`: Creates a platform status snapshot.
@@ -155,7 +172,7 @@ Method-level `@Throttle(...)` overrides class-level settings, class-level settin
 ## Related Packages
 
 - `@fluojs/http`: Required for HTTP context and Exception handling.
-- `@fluojs/redis`: Required when using `RedisThrottlerStore`.
+- `@fluojs/redis`: Official Redis client integration for `RedisThrottlerStore`; `ioredis` and compatible structural clients are also supported.
 
 ## Example Sources
 

package/dist/guard.d.ts

@@ -5,8 +5,10 @@ import type { ThrottlerModuleOptions } from './types.js';
  */
 export declare class ThrottlerGuard implements Guard {
     private readonly options;
+    private readonly resolvedPolicies;
     private readonly store;
     constructor(options: ThrottlerModuleOptions);
+    private getResolvedPolicy;
     /**
      * Evaluate whether the current request is still within its allowed rate-limit window.
      *

package/dist/guard.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"guard.d.ts","sourceRoot":"","sources":["../src/guard.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,KAAK,KAAK,EAAE,KAAK,YAAY,EAAoD,MAAM,cAAc,CAAC;AAa/G,OAAO,KAAK,EAAE,sBAAsB,EAAuC,MAAM,YAAY,CAAC;AAuD9F;;GAEG;AACH,qBACa,cAAe,YAAW,KAAK;IAC1C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAyB;IAEjD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAiB;gBAE3B,OAAO,EAAE,sBAAsB;IAO3C;;;;;;OAMG;IACG,WAAW,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,OAAO,CAAC;CAkD3D"}
+{"version":3,"file":"guard.d.ts","sourceRoot":"","sources":["../src/guard.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,KAAK,KAAK,EAAE,KAAK,YAAY,EAAoD,MAAM,cAAc,CAAC;AAa/G,OAAO,KAAK,EAAE,sBAAsB,EAAuC,MAAM,YAAY,CAAC;AA4D9F;;GAEG;AACH,qBACa,cAAe,YAAW,KAAK;IAC1C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAyB;IAEjD,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAA+D;IAEhG,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAiB;gBAE3B,OAAO,EAAE,sBAAsB;IAO3C,OAAO,CAAC,iBAAiB;IAuCzB;;;;;;OAMG;IACG,WAAW,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,OAAO,CAAC;CAkC3D"}

package/dist/guard.js

@@ -29,8 +29,7 @@ function defaultKeyGenerator(ctx, trustProxyHeaders) {
     trustProxyHeaders
   });
 }
-function buildStoreKey(handlerKey, clientKey) {
-  const encodedHandlerKey = encodeURIComponent(handlerKey);
+function buildStoreKey(encodedHandlerKey, clientKey) {
   const encodedClientKey = encodeURIComponent(clientKey);
   return `throttler:${encodedHandlerKey}:${encodedClientKey}`;
 }
@@ -39,7 +38,7 @@ function buildHandlerKey(handler) {
   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];
+  const retryAfterMs = entry.retryAfterMs ?? entry[throttlerRetryAfterMsSymbol];
   if (typeof retryAfterMs === 'number' && Number.isFinite(retryAfterMs)) {
     return Math.max(1, Math.ceil(retryAfterMs / 1000));
   }
@@ -55,12 +54,43 @@ class ThrottlerGuard {
     [_ThrottlerGuard, _initClass] = _applyDecs(this, [Inject(THROTTLER_OPTIONS)], []).c;
   }
   options;
+  resolvedPolicies = new WeakMap();
   store;
   constructor(options) {
     const validatedOptions = validateThrottlerModuleOptions(options);
     this.options = validatedOptions;
     this.store = validatedOptions.store ?? createMemoryThrottlerStore();
   }
+  getResolvedPolicy(handler) {
+    let controllerPolicies = this.resolvedPolicies.get(handler.controllerToken);
+    if (!controllerPolicies) {
+      controllerPolicies = new Map();
+      this.resolvedPolicies.set(handler.controllerToken, controllerPolicies);
+    }
+    const version = handler.route.version ?? handler.metadata.effectiveVersion ?? 'unversioned';
+    const cacheKey = [handler.methodName, handler.route.method, handler.route.path, version].join('\u0000');
+    const cachedPolicy = controllerPolicies.get(cacheKey);
+    if (cachedPolicy) {
+      return cachedPolicy;
+    }
+    const classBag = getClassMetadataBag(handler.controllerToken);
+    const methodBag = getMethodMetadataBag(handler.controllerToken, handler.methodName);
+    const skip = (classBag ? getClassSkipThrottleMetadata(classBag) : false) || (methodBag ? getSkipThrottleMetadata(methodBag) : false);
+    const methodThrottle = methodBag ? getThrottleMetadata(methodBag) : undefined;
+    const classThrottle = classBag ? getClassThrottleMetadata(classBag) : undefined;
+    const resolvedThrottle = validateThrottleOptions({
+      limit: methodThrottle?.limit ?? classThrottle?.limit ?? this.options.limit,
+      ttl: methodThrottle?.ttl ?? classThrottle?.ttl ?? this.options.ttl
+    });
+    const policy = {
+      encodedHandlerKey: encodeURIComponent(buildHandlerKey(handler)),
+      limit: resolvedThrottle.limit,
+      skip,
+      ttlSeconds: resolvedThrottle.ttl
+    };
+    controllerPolicies.set(cacheKey, policy);
+    return policy;
+  }
 
   /**
    * Evaluate whether the current request is still within its allowed rate-limit window.
@@ -74,37 +104,25 @@ class ThrottlerGuard {
       handler,
       requestContext
     } = context;
-    const classBag = getClassMetadataBag(handler.controllerToken);
-    const methodBag = getMethodMetadataBag(handler.controllerToken, handler.methodName);
-    const classSkip = classBag ? getClassSkipThrottleMetadata(classBag) : false;
-    const methodSkip = methodBag ? getSkipThrottleMetadata(methodBag) : false;
-    if (classSkip || methodSkip) {
+    const policy = this.getResolvedPolicy(handler);
+    if (policy.skip) {
       return true;
     }
-    const methodThrottle = methodBag ? getThrottleMetadata(methodBag) : undefined;
-    const classThrottle = classBag ? getClassThrottleMetadata(classBag) : undefined;
-    const resolvedThrottle = validateThrottleOptions({
-      limit: methodThrottle?.limit ?? classThrottle?.limit ?? this.options.limit,
-      ttl: methodThrottle?.ttl ?? classThrottle?.ttl ?? this.options.ttl
-    });
-    const ttlSeconds = resolvedThrottle.ttl;
-    const limit = resolvedThrottle.limit;
     const middlewareCtx = {
       request: requestContext.request,
       requestContext,
       response: requestContext.response
     };
     const clientKey = this.options.keyGenerator ? this.options.keyGenerator(middlewareCtx) : defaultKeyGenerator(middlewareCtx, this.options.trustProxyHeaders ?? false);
-    const handlerKey = buildHandlerKey(handler);
-    const storeKey = buildStoreKey(handlerKey, clientKey);
+    const storeKey = buildStoreKey(policy.encodedHandlerKey, clientKey);
     const now = Date.now();
     const rawEntry = await this.store.consume(storeKey, {
       now,
-      ttlSeconds
+      ttlSeconds: policy.ttlSeconds
     });
     const entry = validateThrottlerStoreEntry(rawEntry);
-    if (entry.count > limit) {
-      const retryAfter = resolveRetryAfterSeconds(rawEntry, now);
+    if (entry.count > policy.limit) {
+      const retryAfter = resolveRetryAfterSeconds(entry, now);
       requestContext.response.setHeader('Retry-After', String(retryAfter));
       throw new TooManyRequestsException('Too Many Requests', {
         meta: {

package/dist/index.d.ts

@@ -2,6 +2,7 @@ export { getClassSkipThrottleMetadata, getClassThrottleMetadata, getSkipThrottle
 export { ThrottlerGuard } from './guard.js';
 export * from './module.js';
 export { RedisThrottlerStore } from './redis-store.js';
+export type { RedisThrottlerClient } from './redis-store.js';
 export * from './status.js';
 export { createMemoryThrottlerStore } from './store.js';
 export type { ThrottlerConsumeInput, ThrottlerHandlerOptions, ThrottlerModuleOptions, ThrottlerStore, ThrottlerStoreEntry, } from './types.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,4BAA4B,EAC5B,wBAAwB,EACxB,uBAAuB,EACvB,mBAAmB,EACnB,YAAY,EACZ,QAAQ,EACR,wBAAwB,GACzB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAC5C,cAAc,aAAa,CAAC;AAC5B,OAAO,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AACvD,cAAc,aAAa,CAAC;AAC5B,OAAO,EAAE,0BAA0B,EAAE,MAAM,YAAY,CAAC;AACxD,YAAY,EACV,qBAAqB,EACrB,uBAAuB,EACvB,sBAAsB,EACtB,cAAc,EACd,mBAAmB,GACpB,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,4BAA4B,EAC5B,wBAAwB,EACxB,uBAAuB,EACvB,mBAAmB,EACnB,YAAY,EACZ,QAAQ,EACR,wBAAwB,GACzB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAC5C,cAAc,aAAa,CAAC;AAC5B,OAAO,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AACvD,YAAY,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AAC7D,cAAc,aAAa,CAAC;AAC5B,OAAO,EAAE,0BAA0B,EAAE,MAAM,YAAY,CAAC;AACxD,YAAY,EACV,qBAAqB,EACrB,uBAAuB,EACvB,sBAAsB,EACtB,cAAc,EACd,mBAAmB,GACpB,MAAM,YAAY,CAAC"}

package/dist/module.d.ts

@@ -1,18 +1,19 @@
 import { type ModuleType } from '@fluojs/runtime';
 import type { ThrottlerModuleOptions } from './types.js';
 /**
- * Runtime module entrypoint for global throttling.
+ * Runtime module entrypoint for throttler policy and guard provider registration.
  *
  * @remarks
- * The module wires one global `ThrottlerGuard`; route-level overrides still come
- * from `@Throttle(...)` and `@SkipThrottle()` metadata.
+ * The module registers validated throttler options and makes `ThrottlerGuard`
+ * injectable. Routes still opt in to enforcement explicitly with guard metadata
+ * such as `@UseGuards(ThrottlerGuard)`.
  */
 export declare class ThrottlerModule {
     /**
-     * Register the global throttling guard with validated module options.
+     * Register throttler providers with validated module options.
      *
      * @param options Module-wide throttling policy.
-     * @returns A runtime module exporting `ThrottlerGuard`.
+     * @returns A runtime module exporting `ThrottlerGuard` for explicit route activation.
      *
      * @example
      * ```ts

package/dist/module.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"module.d.ts","sourceRoot":"","sources":["../src/module.ts"],"names":[],"mappings":"AACA,OAAO,EAAgB,KAAK,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAIhE,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AAkBzD;;;;;;GAMG;AACH,qBAAa,eAAe;IAC1B;;;;;;;;;;;;;OAaG;IACH,MAAM,CAAC,OAAO,CAAC,OAAO,EAAE,sBAAsB,GAAG,UAAU;CAS5D"}
+{"version":3,"file":"module.d.ts","sourceRoot":"","sources":["../src/module.ts"],"names":[],"mappings":"AACA,OAAO,EAAgB,KAAK,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAIhE,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AAkBzD;;;;;;;GAOG;AACH,qBAAa,eAAe;IAC1B;;;;;;;;;;;;;OAaG;IACH,MAAM,CAAC,OAAO,CAAC,OAAO,EAAE,sBAAsB,GAAG,UAAU;CAS5D"}

package/dist/module.js

@@ -14,18 +14,19 @@ function createThrottlerProviders(options) {
 }
 
 /**
- * Runtime module entrypoint for global throttling.
+ * Runtime module entrypoint for throttler policy and guard provider registration.
  *
  * @remarks
- * The module wires one global `ThrottlerGuard`; route-level overrides still come
- * from `@Throttle(...)` and `@SkipThrottle()` metadata.
+ * The module registers validated throttler options and makes `ThrottlerGuard`
+ * injectable. Routes still opt in to enforcement explicitly with guard metadata
+ * such as `@UseGuards(ThrottlerGuard)`.
  */
 export class ThrottlerModule {
   /**
-   * Register the global throttling guard with validated module options.
+   * Register throttler providers with validated module options.
    *
    * @param options Module-wide throttling policy.
-   * @returns A runtime module exporting `ThrottlerGuard`.
+   * @returns A runtime module exporting `ThrottlerGuard` for explicit route activation.
    *
    * @example
    * ```ts

package/dist/redis-store.d.ts

@@ -1,5 +1,23 @@
-import type Redis from 'ioredis';
 import type { ThrottlerConsumeInput, ThrottlerStore, ThrottlerStoreEntry } from './types.js';
+/**
+ * Structural Redis command client accepted by `RedisThrottlerStore`.
+ *
+ * @remarks
+ * This package-local contract keeps the throttler root API independent of
+ * concrete Redis client packages while remaining compatible with `ioredis`,
+ * `@fluojs/redis`, and custom clients that expose Redis `EVAL`.
+ */
+export interface RedisThrottlerClient {
+    /**
+     * Evaluate a Redis Lua script.
+     *
+     * @param script Lua script to evaluate.
+     * @param numberOfKeys Number of key arguments Redis should treat as `KEYS`.
+     * @param args Key and argument values passed to Redis `EVAL`.
+     * @returns The raw Redis response for the script.
+     */
+    eval(script: string, numberOfKeys: number, ...args: string[]): unknown | Promise<unknown>;
+}
 /**
  * Redis-backed throttler store for distributed rate limits.
  *
@@ -9,7 +27,12 @@ import type { ThrottlerConsumeInput, ThrottlerStore, ThrottlerStoreEntry } from
  */
 export declare class RedisThrottlerStore implements ThrottlerStore {
     private readonly client;
-    constructor(client: Redis);
+    /**
+     * Create a Redis-backed throttler store.
+     *
+     * @param client Redis command client that supports `EVAL`.
+     */
+    constructor(client: RedisThrottlerClient);
     /**
      * Consume one throttle slot for the provided key.
      *

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;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"}
+{"version":3,"file":"redis-store.d.ts","sourceRoot":"","sources":["../src/redis-store.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,qBAAqB,EAAE,cAAc,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAG7F;;;;;;;GAOG;AACH,MAAM,WAAW,oBAAoB;IACnC;;;;;;;OAOG;IACH,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAC3F;AAmED;;;;;;GAMG;AACH,qBAAa,mBAAoB,YAAW,cAAc;IAM5C,OAAO,CAAC,QAAQ,CAAC,MAAM;IALnC;;;;OAIG;gBAC0B,MAAM,EAAE,oBAAoB;IAEzD;;;;;;OAMG;IACG,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,qBAAqB,GAAG,OAAO,CAAC,mBAAmB,CAAC;CAUvF"}

package/dist/redis-store.js

@@ -1,5 +1,15 @@
 import { throttlerRetryAfterMsSymbol } from './store-internals.js';
 import { validateThrottlerStoreEntry } from './validation.js';
+
+/**
+ * Structural Redis command client accepted by `RedisThrottlerStore`.
+ *
+ * @remarks
+ * This package-local contract keeps the throttler root API independent of
+ * concrete Redis client packages while remaining compatible with `ioredis`,
+ * `@fluojs/redis`, and custom clients that expose Redis `EVAL`.
+ */
+
 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) {
@@ -11,7 +21,11 @@ function parseConsumeResult(result) {
   if (!Number.isFinite(count) || !Number.isFinite(resetAt)) {
     throw new Error('Redis throttler consume script returned non-numeric counters.');
   }
-  const entry = validateThrottlerStoreEntry({
+  const entry = Number.isFinite(retryAfterMs) ? validateThrottlerStoreEntry({
+    count,
+    resetAt,
+    retryAfterMs
+  }) : validateThrottlerStoreEntry({
     count,
     resetAt
   });
@@ -34,6 +48,11 @@ function parseConsumeResult(result) {
  * requests across instances observe the same counter and reset window.
  */
 export class RedisThrottlerStore {
+  /**
+   * Create a Redis-backed throttler store.
+   *
+   * @param client Redis command client that supports `EVAL`.
+   */
   constructor(client) {
     this.client = client;
   }

package/dist/types.d.ts

@@ -1,10 +1,21 @@
 import type { MiddlewareContext } from '@fluojs/http';
 /**
- * Snapshot of a client's current rate-limit window state.
+ * Snapshot of a client's current rate-limit window state returned by a throttler store.
+ *
+ * @remarks
+ * Stores return this value after a `consume(...)` operation. `ThrottlerGuard`
+ * compares `count` with the resolved request limit and uses `resetAt` to compute
+ * the `Retry-After` value when the limit is exceeded. Custom stores that have
+ * a more authoritative server-side clock may return `retryAfterMs` to override
+ * that calculation without relying on a private package symbol.
  */
 export interface ThrottlerStoreEntry {
+    /** Number of requests recorded in the active window after the current consume operation. */
     count: number;
+    /** Epoch time in milliseconds when the active rate-limit window resets. */
     resetAt: number;
+    /** Optional authoritative milliseconds until retry, usually from a backing store server clock. */
+    retryAfterMs?: number;
 }
 /**
  * Public input passed to a `ThrottlerStore` when consuming a request slot.
@@ -26,7 +37,11 @@ export interface ThrottlerStore {
     consume(key: string, input: ThrottlerConsumeInput): ThrottlerStoreEntry | Promise<ThrottlerStoreEntry>;
 }
 /**
- * Per-handler or per-controller throttle override.
+ * Per-handler or per-controller throttle policy accepted by `@Throttle(...)`.
+ *
+ * @remarks
+ * Method-level policies override class-level policies, and class-level policies
+ * override module defaults. Both values must be positive finite integers.
  */
 export interface ThrottlerHandlerOptions {
     /** Seconds in the rate-limit window. */

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAEtD;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,qBAAqB;IACpC,oEAAoE;IACpE,GAAG,EAAE,MAAM,CAAC;IACZ,2CAA2C;IAC3C,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,qBAAqB,GAAG,mBAAmB,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAAC;CACxG;AAED;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC,wCAAwC;IACxC,GAAG,EAAE,MAAM,CAAC;IACZ,4DAA4D;IAC5D,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,kFAAkF;IAClF,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,8DAA8D;IAC9D,GAAG,EAAE,MAAM,CAAC;IACZ,kFAAkF;IAClF,KAAK,EAAE,MAAM,CAAC;IACd;;;OAGG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B;;;OAGG;IACH,YAAY,CAAC,EAAE,CAAC,GAAG,EAAE,iBAAiB,KAAK,MAAM,CAAC;IAClD,+DAA+D;IAC/D,KAAK,CAAC,EAAE,cAAc,CAAC;CACxB"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAEtD;;;;;;;;;GASG;AACH,MAAM,WAAW,mBAAmB;IAClC,4FAA4F;IAC5F,KAAK,EAAE,MAAM,CAAC;IACd,2EAA2E;IAC3E,OAAO,EAAE,MAAM,CAAC;IAChB,kGAAkG;IAClG,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,qBAAqB;IACpC,oEAAoE;IACpE,GAAG,EAAE,MAAM,CAAC;IACZ,2CAA2C;IAC3C,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,qBAAqB,GAAG,mBAAmB,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAAC;CACxG;AAED;;;;;;GAMG;AACH,MAAM,WAAW,uBAAuB;IACtC,wCAAwC;IACxC,GAAG,EAAE,MAAM,CAAC;IACZ,4DAA4D;IAC5D,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,kFAAkF;IAClF,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,8DAA8D;IAC9D,GAAG,EAAE,MAAM,CAAC;IACZ,kFAAkF;IAClF,KAAK,EAAE,MAAM,CAAC;IACd;;;OAGG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B;;;OAGG;IACH,YAAY,CAAC,EAAE,CAAC,GAAG,EAAE,iBAAiB,KAAK,MAAM,CAAC;IAClD,+DAA+D;IAC/D,KAAK,CAAC,EAAE,cAAc,CAAC;CACxB"}

package/dist/validation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../src/validation.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,uBAAuB,EAAE,sBAAsB,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAoBvG;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,uBAAuB,GAAG,uBAAuB,CAOjG;AAED;;;;;GAKG;AACH,wBAAgB,8BAA8B,CAAC,OAAO,EAAE,sBAAsB,GAAG,sBAAsB,CAatG;AAED;;;;;GAKG;AACH,wBAAgB,2BAA2B,CAAC,KAAK,EAAE,mBAAmB,GAAG,mBAAmB,CAQ3F"}
+{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../src/validation.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,uBAAuB,EAAE,sBAAsB,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AA0BvG;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,uBAAuB,GAAG,uBAAuB,CAOjG;AAED;;;;;GAKG;AACH,wBAAgB,8BAA8B,CAAC,OAAO,EAAE,sBAAsB,GAAG,sBAAsB,CAqBtG;AAED;;;;;GAKG;AACH,wBAAgB,2BAA2B,CAAC,KAAK,EAAE,mBAAmB,GAAG,mBAAmB,CAkB3F"}

package/dist/validation.js

@@ -8,6 +8,11 @@ function assertFiniteInteger(value, field) {
     throw new Error(`Invalid throttler ${field}: expected a finite integer.`);
   }
 }
+function assertNonNegativeFiniteInteger(value, field) {
+  if (!Number.isFinite(value) || !Number.isInteger(value) || value < 0) {
+    throw new Error(`Invalid throttler ${field}: expected a non-negative finite integer.`);
+  }
+}
 function assertOptionalBoolean(value, field) {
   if (value !== undefined && typeof value !== 'boolean') {
     throw new Error(`Invalid throttler ${field}: expected a boolean when provided.`);
@@ -39,6 +44,12 @@ export function validateThrottlerModuleOptions(options) {
   validateThrottleOptions(options);
   assertOptionalBoolean(options.global, 'global');
   assertOptionalBoolean(options.trustProxyHeaders, 'trustProxyHeaders');
+  if (options.keyGenerator !== undefined && typeof options.keyGenerator !== 'function') {
+    throw new Error('Invalid throttler keyGenerator: expected a function when provided.');
+  }
+  if (options.store !== undefined && (options.store === null || typeof options.store.consume !== 'function')) {
+    throw new Error('Invalid throttler store.consume: expected a function when store is provided.');
+  }
   return {
     global: options.global,
     keyGenerator: options.keyGenerator,
@@ -58,8 +69,15 @@ export function validateThrottlerModuleOptions(options) {
 export function validateThrottlerStoreEntry(entry) {
   assertPositiveFiniteInteger(entry.count, 'store count');
   assertFiniteInteger(entry.resetAt, 'store resetAt');
-  return {
+  if (entry.retryAfterMs !== undefined) {
+    assertNonNegativeFiniteInteger(entry.retryAfterMs, 'store retryAfterMs');
+  }
+  const validatedEntry = {
     count: entry.count,
     resetAt: entry.resetAt
   };
+  if (entry.retryAfterMs !== undefined) {
+    validatedEntry.retryAfterMs = entry.retryAfterMs;
+  }
+  return validatedEntry;
 }

package/package.json

@@ -9,7 +9,7 @@
     "redis",
     "decorator"
   ],
-  "version": "1.0.2",
+  "version": "1.0.4",
   "private": false,
   "license": "MIT",
   "repository": {
@@ -36,14 +36,14 @@
     "dist"
   ],
   "dependencies": {
-    "@fluojs/core": "^1.0.2",
-    "@fluojs/di": "^1.0.2",
-    "@fluojs/http": "^1.0.0",
-    "@fluojs/runtime": "^1.1.0"
+    "@fluojs/core": "^1.0.3",
+    "@fluojs/di": "^1.1.0",
+    "@fluojs/http": "^1.1.2",
+    "@fluojs/runtime": "^1.1.8"
   },
   "peerDependencies": {
     "ioredis": "^5.0.0",
-    "@fluojs/redis": "^1.0.0"
+    "@fluojs/redis": "^1.0.2"
   },
   "peerDependenciesMeta": {
     "@fluojs/redis": {
@@ -56,7 +56,7 @@
   "devDependencies": {
     "ioredis": "^5.10.0",
     "vitest": "^3.2.4",
-    "@fluojs/testing": "^1.0.2"
+    "@fluojs/testing": "^1.0.6"
   },
   "scripts": {
     "prebuild": "node ../../tooling/scripts/clean-dist.mjs",