@fluojs/throttler 1.0.1 → 1.0.3

package/README.ko.md

@@ -125,7 +125,7 @@ ThrottlerModule.forRoot({
 - `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를 조정할 수 있습니다. 모듈 옵션은 guard가 연결될 때 검증되고 값으로 캡처되므로, 호출자가 나중에 options 객체를 변경해도 실행 중인 throttling 정책은 바뀌지 않습니다. `store` 옵션을 제공하지 않으면 각 `ThrottlerGuard` 인스턴스가 자체 in-memory store를 소유합니다. 저장소를 공유하거나 외부에서 관리해야 한다면 `RedisThrottlerStore` 같은 `ThrottlerStore` 구현을 전달하세요.
 
 ### 데코레이터
 - `@Throttle({ ttl, limit })`: 클래스나 메서드에 특정 속도 제한을 설정합니다.
@@ -144,6 +144,11 @@ ThrottlerModule.forRoot({
 ### status와 diagnostics
 - `createThrottlerPlatformStatusSnapshot(...)`: 플랫폼 status snapshot을 생성합니다.
 - `createThrottlerPlatformDiagnosticIssues(...)`: 잘못된 throttler 상태에 대한 diagnostic issue를 생성합니다.
+- `ThrottlerStatusAdapterInput`: status 및 diagnostic helper의 공개 입력 shape입니다. 부트스트랩 중 수집한 store kind, ownership mode, operation mode, backing-store readiness, dependency linkage, readiness criticality 힌트를 전달합니다.
+- `ThrottlerPlatformStatusSnapshot`: `createThrottlerPlatformStatusSnapshot(...)`이 반환하는 공개 출력 shape입니다. 런타임 platform snapshot과 호환되는 readiness, health, ownership, details 섹션을 포함합니다.
+- `ThrottlerStoreKind`: status adapter가 인식하는 store category입니다: `memory`, `redis`, `custom`.
+- `ThrottlerStoreOwnershipMode`: status snapshot에 보고되는 ownership mode입니다: guard가 소유한 리소스는 `framework`, 외부에서 관리되는 store는 `external`입니다.
+- `ThrottlerOperationMode`: status details에 보고되는 operation mode입니다: `local-only`, `distributed`, `local-fallback`, `custom`.
 
 메서드 수준 `@Throttle(...)`은 클래스 수준 설정보다 우선하고, 클래스 수준 설정은 모듈 기본값보다 우선합니다. `@SkipThrottle()`은 클래스나 메서드 수준 모두에서 throttling을 우회합니다.
 

package/README.md

@@ -125,7 +125,7 @@ ThrottlerModule.forRoot({
 - `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. 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.
@@ -144,6 +144,11 @@ ThrottlerModule.forRoot({
 ### Status and diagnostics
 - `createThrottlerPlatformStatusSnapshot(...)`: Creates a platform status snapshot.
 - `createThrottlerPlatformDiagnosticIssues(...)`: Creates diagnostic issues for invalid throttler state.
+- `ThrottlerStatusAdapterInput`: Public input shape for status and diagnostic helpers. It carries store kind, ownership mode, operation mode, backing-store readiness, dependency linkage, and readiness criticality hints collected during bootstrap.
+- `ThrottlerPlatformStatusSnapshot`: Public output shape returned by `createThrottlerPlatformStatusSnapshot(...)`, containing readiness, health, ownership, and details sections compatible with runtime platform snapshots.
+- `ThrottlerStoreKind`: Store categories recognized by the status adapter: `memory`, `redis`, or `custom`.
+- `ThrottlerStoreOwnershipMode`: Ownership modes reported in status snapshots: `framework` for guard-owned resources or `external` for externally managed stores.
+- `ThrottlerOperationMode`: Operation modes reported in status details: `local-only`, `distributed`, `local-fallback`, or `custom`.
 
 Method-level `@Throttle(...)` overrides class-level settings, class-level settings override module defaults, and `@SkipThrottle()` bypasses throttling at either class or method level.
 

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;AA6D9F;;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}`;
 }
@@ -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,36 +104,24 @@ 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) {
+    if (entry.count > policy.limit) {
       const retryAfter = resolveRetryAfterSeconds(rawEntry, now);
       requestContext.response.setHeader('Retry-After', String(retryAfter));
       throw new TooManyRequestsException('Too Many Requests', {

package/package.json

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