@futdevpro/nts-dynamo 1.15.145 → 1.15.151

package/src/_modules/rate-limit/rate-limit.middleware.ts

@@ -2,342 +2,503 @@ import { Request, Response } from 'express';
 
 import { DyFM_Error } from '@futdevpro/fsm-dynamo';
 
-import { DyNTS_SingletonServiceBase } from '../../_services/base/singleton.service-base';
 import { DyNTS_global_settings } from '../../_collections/global-settings.const';
-
+import { DyNTS_SingletonServiceBase } from '../../_services/base/singleton.service-base';
+import { DyNTS_RateLimitStoreKind_Type } from './_enums/rate-limit-store-kind.type-enum';
 import { DyNTS_RateLimit_Config } from './_models/rate-limit-config.interface';
+import { DyNTS_RateLimit_ConsumeResult_Interface } from './_models/rate-limit-consume-result.interface';
 import { DyNTS_RateLimit_Policy } from './_models/rate-limit-policy.interface';
+import { DyNTS_RateLimit_Store_Interface } from './_models/rate-limit-store.interface';
+import { DyNTS_RateLimit_InMemoryStore } from './rate-limit-in-memory.store';
 
-
-/** Default request-limit per default-window. */
 const DEFAULT_LIMIT: number = 100;
-
-/** Default sliding-window hossza ms-ben (1 perc). */
-const DEFAULT_WINDOW_MS: number = 60000;
-
-/** Default response-header allitas. */
+const DEFAULT_WINDOW_MS: number = 60_000;
 const DEFAULT_RESPONSE_HEADERS: boolean = true;
-
-/** Periodikus garbage-collection intervallum ms-ben (5 perc).
- * A request-log-bol takaritja a regen inaktiv kulcsokat (memory-leak prevention).
- */
-const GC_INTERVAL_MS: number = 5 * 60 * 1000;
-
-/** Service-nev az error-okhoz. */
+const MAX_LIMIT: number = 1_000_000;
+const MAX_WINDOW_MS: number = 7 * 24 * 60 * 60 * 1_000;
+const MAX_BUCKET_PART_LENGTH: number = 240;
 const SERVICE_NAME: string = 'DyNTS_RateLimit_Middleware';
 
-/** ErrorCode-builder — system shortcode + sajat kod. */
-const buildErrorCode = (subcode: string): string => {
-  const sys: string = DyNTS_global_settings.systemShortCodeName ?? 'DyNTS';
-  return `${sys}|DyNTS-RL-${subcode}`;
-};
-
-
-/**
- * Sliding-window HTTP rate-limit middleware — opt-in service-szel, a meglevo
- * `DyNTS_Endpoint_Params.preProcesses` mechanizmus mellol mukodik.
- *
- * **Hasznalat (host app):**
- * ```ts
- * const rateLimit = DyNTS_RateLimit_Middleware.getInstance();
- * rateLimit.configure({
- *   defaultLimit: 100,            // 100 req/perc default
- *   defaultWindowMs: 60_000,
- *   keyExtractor: (req) => req.headers['x-api-key'] as string || req.ip,
- * });
- *
- * new DyNTS_Endpoint_Params({
- *   ...,
- *   preProcesses: [rateLimit.check, ...other],
- * });
- *
- * // subscription-tier-up: per-kulcs egyedi limit
- * rateLimit.setPolicyForKey('subscriber-tier-key-123', {
- *   limit: 1000,
- *   windowMs: 60_000,
- * });
- * ```
- *
- * **Viselkedes:**
- * - Sliding-window algoritmus: minden request egy timestamp; a window-on
- *   kivuli timestamp-ek nem szamolnak. Tobb pontos mint a fix-bucket
- *   (boundary-burst nincs).
- * - In-memory storage — single-instance MVP-nek megfelelo. Multi-instance
- *   prod-hoz Redis-backed extension kell (lasd a kozelebb dokumentumaltot).
- * - Limit lepes: 429 DyFM_Error + `X-RateLimit-*` + `Retry-After` header-ek.
- *
- * **Storage:** `Map<storageKey, timestamps[]>` ahol storageKey = `${subject}|${endpoint}`.
- * Periodikus GC takaritja a inaktiv kulcsokat.
- *
- * **Singleton:** `getInstance()`-szel hivd. A `.check` mezo binding-elve van
- * `this`-re, igy direkt atadhato `preProcesses`-be ujracsomagolas nelkul.
- */
-export class DyNTS_RateLimit_Middleware extends DyNTS_SingletonServiceBase {
+interface DyNTS_RateLimit_ErrorContext_Interface {
+  status: number;
+  subcode: string;
+  message: string;
+  userMessage: string;
+}
 
-  static getInstance(): DyNTS_RateLimit_Middleware {
-    return DyNTS_RateLimit_Middleware.getSingletonInstance() as DyNTS_RateLimit_Middleware;
-  }
+interface DyNTS_RateLimit_HeaderContext_Interface {
+  policy: DyNTS_RateLimit_Policy;
+  result: DyNTS_RateLimit_ConsumeResult_Interface;
+  now: number;
+}
 
+interface DyNTS_RateLimit_ConfigSnapshot_Interface {
+  defaultLimit: number;
+  defaultWindowMs: number;
+  isResponseHeadersEnabled: boolean;
+  isSharedStoreRequired: boolean;
+  keyExtractor: (req: Request) => string;
+  endpointGrouper: (req: Request) => string;
+  costExtractor: (req: Request) => number;
+  clock: () => number;
+  store: DyNTS_RateLimit_Store_Interface;
+  isKeyExtractorExplicit: boolean;
+  isEndpointGrouperExplicit: boolean;
+  keyPolicies: Map<string, DyNTS_RateLimit_Policy>;
+  endpointPolicies: Map<string, DyNTS_RateLimit_Policy>;
+}
+
+/** Atomic HTTP rate-limit boundary with an explicit shared-store production gate. */
+export class DyNTS_RateLimit_Middleware extends DyNTS_SingletonServiceBase {
   private defaultLimit: number = DEFAULT_LIMIT;
   private defaultWindowMs: number = DEFAULT_WINDOW_MS;
-  private responseHeaders: boolean = DEFAULT_RESPONSE_HEADERS;
-
-  private keyExtractor: (req: Request) => string =
-    (req: Request): string => this.defaultKeyExtractor(req);
-  private endpointGrouper: (req: Request) => string =
-    (req: Request): string => req.path;
-
-  /** request-log: storageKey → timestamp-tomb (Date.now() ms). */
-  private requestLog: Map<string, number[]> = new Map();
-
-  /** Per-kulcs egyedi policy-k. */
+  private isResponseHeadersEnabled: boolean = DEFAULT_RESPONSE_HEADERS;
+  private isSharedStoreRequired: boolean = false;
+  private isKeyExtractorExplicit: boolean = false;
+  private isEndpointGrouperExplicit: boolean = false;
+  private keyExtractor: (req: Request) => string = (req: Request): string => req.ip ?? 'unknown';
+  private endpointGrouper: (req: Request) => string = (req: Request): string => req.path;
+  private costExtractor: (req: Request) => number = (req: Request): number => {
+    void req;
+
+    return 1;
+  };
+  private clock: () => number = (): number => Date.now();
+  private store: DyNTS_RateLimit_Store_Interface = new DyNTS_RateLimit_InMemoryStore();
   private keyPolicies: Map<string, DyNTS_RateLimit_Policy> = new Map();
-
-  /** Per-endpoint(-csoport) egyedi policy-k (a `endpointGrouper` outputjara kulcsolva). */
   private endpointPolicies: Map<string, DyNTS_RateLimit_Policy> = new Map();
 
-  /** GC timer handle. */
-  private gcTimer: NodeJS.Timeout | null = null;
-
+  /** Returns the process-wide rate-limit middleware. */
+  public static getInstance(): DyNTS_RateLimit_Middleware {
+    return DyNTS_RateLimit_Middleware.getSingletonInstance();
+  }
 
-  /**
-   * Konfig override. Hianyzo mezok a default-okat orzik. Hivhato barmikor —
-   * a `check()` a friss config-ot olvassa.
-   */
-  configure(config: DyNTS_RateLimit_Config): void {
-    if (config.defaultLimit !== undefined) {
-      this.defaultLimit = config.defaultLimit;
-    }
-    if (config.defaultWindowMs !== undefined) {
-      this.defaultWindowMs = config.defaultWindowMs;
-    }
-    if (config.keyExtractor !== undefined) {
-      this.keyExtractor = config.keyExtractor;
-    }
-    if (config.endpointGrouper !== undefined) {
-      this.endpointGrouper = config.endpointGrouper;
-    }
-    if (config.responseHeaders !== undefined) {
-      this.responseHeaders = config.responseHeaders;
-    }
-    if (config.initialKeyPolicies !== undefined) {
-      for (const [ key, policy ] of Object.entries(config.initialKeyPolicies)) {
-        this.keyPolicies.set(key, policy);
-      }
-    }
-    if (config.initialEndpointPolicies !== undefined) {
-      for (const [ endpoint, policy ] of Object.entries(config.initialEndpointPolicies)) {
-        this.endpointPolicies.set(endpoint, policy);
-      }
-    }
-    this.startGcTimer();
+  /** Applies a validated configuration atomically; invalid settings do not partially mutate the service. */
+  public configure(config: DyNTS_RateLimit_Config): void {
+    const snapshot: DyNTS_RateLimit_ConfigSnapshot_Interface = this.buildConfigSnapshot(config);
+
+    this.defaultLimit = snapshot.defaultLimit;
+    this.defaultWindowMs = snapshot.defaultWindowMs;
+    this.isResponseHeadersEnabled = snapshot.isResponseHeadersEnabled;
+    this.isSharedStoreRequired = snapshot.isSharedStoreRequired;
+    this.keyExtractor = snapshot.keyExtractor;
+    this.endpointGrouper = snapshot.endpointGrouper;
+    this.costExtractor = snapshot.costExtractor;
+    this.clock = snapshot.clock;
+    this.store = snapshot.store;
+    this.isKeyExtractorExplicit = snapshot.isKeyExtractorExplicit;
+    this.isEndpointGrouperExplicit = snapshot.isEndpointGrouperExplicit;
+    this.keyPolicies = snapshot.keyPolicies;
+    this.endpointPolicies = snapshot.endpointPolicies;
   }
 
-  /**
-   * Aktualis konfig olvasasa (diagnosztika celokra).
-   */
-  getConfig(): {
+  /** Returns content-free configuration diagnostics. */
+  public getConfig(): {
     defaultLimit: number;
     defaultWindowMs: number;
     responseHeaders: boolean;
     activeKeyPolicies: number;
     activeEndpointPolicies: number;
     trackedStorageKeys: number;
-  } {
+    storeKind: DyNTS_RateLimitStoreKind_Type;
+    requireSharedStore: boolean;
+    } {
     return {
-      defaultLimit:            this.defaultLimit,
-      defaultWindowMs:         this.defaultWindowMs,
-      responseHeaders:         this.responseHeaders,
-      activeKeyPolicies:       this.keyPolicies.size,
-      activeEndpointPolicies:  this.endpointPolicies.size,
-      trackedStorageKeys:      this.requestLog.size,
+      defaultLimit: this.defaultLimit,
+      defaultWindowMs: this.defaultWindowMs,
+      responseHeaders: this.isResponseHeadersEnabled,
+      activeKeyPolicies: this.keyPolicies.size,
+      activeEndpointPolicies: this.endpointPolicies.size,
+      trackedStorageKeys: this.store instanceof DyNTS_RateLimit_InMemoryStore
+        ? this.store.getTrackedBucketCount()
+        : 0,
+      storeKind: this.store.storeKind,
+      requireSharedStore: this.isSharedStoreRequired,
     };
   }
 
-  /**
-   * Per-kulcs egyedi policy beallitas (pl. subscription-tier alapjan).
-   * A `key`-nek pontosan azzal a stringgel kell egyeznie, amit a `keyExtractor`
-   * visszaad.
-   */
-  setPolicyForKey(key: string, policy: DyNTS_RateLimit_Policy): void {
-    this.keyPolicies.set(key, policy);
+  /** Sets one validated subject policy. */
+  public setPolicyForKey(key: string, policy: DyNTS_RateLimit_Policy): void {
+    this.assertBucketPart(key);
+    this.assertPolicy(policy);
+    this.keyPolicies.set(key, { ...policy });
   }
 
-  /**
-   * Per-kulcs policy torlese (visszaall a default-ra).
-   */
-  clearPolicyForKey(key: string): void {
+  /** Removes one subject policy. */
+  public clearPolicyForKey(key: string): void {
     this.keyPolicies.delete(key);
   }
 
-  /**
-   * Per-endpoint(-csoport) egyedi policy beallitas. Az `endpoint`-nek pontosan
-   * azzal a stringgel kell egyeznie, amit az `endpointGrouper` visszaad (default: `req.path`).
-   * Akkor hasznos, ha egy endpointnak a globalis default-tol eltero limit kell — pl. egy
-   * webhook nagy burst-toleranciat igenyel (a legit, distributed forgalom ne bukjon), mig
-   * egy admin-endpoint szuk limitet. Precedencia: per-kulcs policy > per-endpoint policy > default.
-   */
-  setPolicyForEndpoint(endpoint: string, policy: DyNTS_RateLimit_Policy): void {
-    this.endpointPolicies.set(endpoint, policy);
+  /** Sets one validated endpoint-group policy. */
+  public setPolicyForEndpoint(endpoint: string, policy: DyNTS_RateLimit_Policy): void {
+    this.assertBucketPart(endpoint);
+    this.assertPolicy(policy);
+    this.endpointPolicies.set(endpoint, { ...policy });
   }
 
-  /**
-   * Per-endpoint policy torlese (visszaall a default-ra).
-   */
-  clearPolicyForEndpoint(endpoint: string): void {
+  /** Removes one endpoint-group policy. */
+  public clearPolicyForEndpoint(endpoint: string): void {
     this.endpointPolicies.delete(endpoint);
   }
 
+  /** Atomically consumes one request permit or raises a stable content-free error. */
+  public readonly check = async (req: Request, res: Response): Promise<void> => {
+    const subject: string = this.extractBucketPart(this.keyExtractor, req);
+    const endpoint: string = this.extractBucketPart(this.endpointGrouper, req);
+    const cost: number = this.extractCost(req);
+
+    const policy: DyNTS_RateLimit_Policy = this.keyPolicies.get(subject)
+      ?? this.endpointPolicies.get(endpoint)
+      ?? { limit: this.defaultLimit, windowMs: this.defaultWindowMs };
+
+    this.assertPolicy(policy);
+    this.assertCost(cost, policy);
+
+    const now: number = this.getNow();
+    let result: unknown;
 
-  /**
-   * Pre-process function — atadhato `DyNTS_Endpoint_Params.preProcesses`-be.
-   *
-   * Throws:
-   *   - 429 ha az aktualis request meghaladna a limit-et a sliding window-on
-   *
-   * Side-effect: ha `responseHeaders === true`, beallitja az `X-RateLimit-Limit`,
-   * `X-RateLimit-Remaining`, `X-RateLimit-Reset` header-eket; 429 eseten
-   * a `Retry-After` header-t is.
-   */
-  readonly check = async (req: Request, res: Response): Promise<void> => {
-    const subject: string = this.keyExtractor(req);
-    const endpoint: string = this.endpointGrouper(req);
-    const storageKey: string = `${subject}|${endpoint}`;
-
-    // precedencia: per-kulcs policy (legspecifikusabb, pl. subscriber-tier) > per-endpoint policy > default
-    const policy: DyNTS_RateLimit_Policy =
-      this.keyPolicies.get(subject) ??
-      this.endpointPolicies.get(endpoint) ??
-      {
-        limit:    this.defaultLimit,
-        windowMs: this.defaultWindowMs,
-      };
-
-    const now: number = Date.now();
-    const windowStart: number = now - policy.windowMs;
-
-    // sliding-window: tartomanyon kivuli timestamp-eket eldobjuk
-    const existing: number[] = this.requestLog.get(storageKey) ?? [];
-    const recent: number[] = existing.filter((t: number): boolean => t > windowStart);
-
-    if (recent.length >= policy.limit) {
-      const oldest: number = recent[0];
-      const resetAt: number = oldest + policy.windowMs;
-      const retryAfterSec: number = Math.max(1, Math.ceil((resetAt - now) / 1000));
-
-      if (this.responseHeaders) {
-        res.setHeader('X-RateLimit-Limit', policy.limit.toString());
-        res.setHeader('X-RateLimit-Remaining', '0');
-        res.setHeader('X-RateLimit-Reset', Math.ceil(resetAt / 1000).toString());
-        res.setHeader('Retry-After', retryAfterSec.toString());
-      }
-
-      // Frissitjuk a log-ot a kiszurt verzioval (felesleges regi timestamp-eket eldobtuk)
-      this.requestLog.set(storageKey, recent);
-
-      throw new DyFM_Error({
-        status:    429,
-        errorCode: buildErrorCode('LIMIT'),
-        addECToUserMsg: true,
-        message:   `Rate limit exceeded: ${policy.limit} req per ${policy.windowMs}ms for ${storageKey}`,
-        userMessage: `Too many requests, retry after ${retryAfterSec}s`,
-        issuerService: SERVICE_NAME,
+    try {
+      result = await this.store.consume({
+        bucketKey: this.buildBucketKey(subject, endpoint),
+        policy: policy,
+        cost: cost,
+        now: now,
+      });
+    } catch {
+      this.throwRateLimitError({
+        status: 503,
+        subcode: 'STORE_UNAVAILABLE',
+        message: 'The configured rate-limit store could not commit a permit decision.',
+        userMessage: 'Request protection is temporarily unavailable. Please try again later.',
       });
     }
 
-    // alatta vagyunk a limit-nek: append the current request
-    recent.push(now);
-    this.requestLog.set(storageKey, recent);
-
-    if (this.responseHeaders) {
-      res.setHeader('X-RateLimit-Limit', policy.limit.toString());
-      res.setHeader('X-RateLimit-Remaining', Math.max(0, policy.limit - recent.length).toString());
-      res.setHeader('X-RateLimit-Reset', Math.ceil((now + policy.windowMs) / 1000).toString());
+    this.assertStoreResult(result, policy, now);
+    this.setResponseHeaders(res, {
+      policy: policy,
+      result: result,
+      now: now,
+    });
+
+    if (!result.allowed) {
+      const retryAfterSeconds: number = this.getRetryAfterSeconds(result.resetAt, now);
+
+      this.throwRateLimitError({
+        status: 429,
+        subcode: 'LIMIT',
+        message: 'The rate-limit policy rejected a request.',
+        userMessage: `Too many requests. Retry after ${retryAfterSeconds} seconds.`,
+      });
     }
   };
 
+  /** Performs explicit opportunistic cleanup only for the local test/development store. */
+  public runGc(): void {
+    if (this.store instanceof DyNTS_RateLimit_InMemoryStore) {
+      this.store.cleanup(this.clock());
+    }
+  }
+
+  /** Backward-compatible no-op: this implementation never starts a timer. */
+  public stopGcTimer(): void {}
+
+  /** Resets all state to deterministic local defaults for tests. */
+  public _resetForTesting(): void {
+    this.defaultLimit = DEFAULT_LIMIT;
+    this.defaultWindowMs = DEFAULT_WINDOW_MS;
+    this.isResponseHeadersEnabled = DEFAULT_RESPONSE_HEADERS;
+    this.isSharedStoreRequired = false;
+    this.isKeyExtractorExplicit = false;
+    this.isEndpointGrouperExplicit = false;
+    this.keyExtractor = (req: Request): string => req.ip ?? 'unknown';
+    this.endpointGrouper = (req: Request): string => req.path;
+    this.costExtractor = (req: Request): number => {
+      void req;
+
+      return 1;
+    };
+    this.clock = (): number => Date.now();
+    this.store = new DyNTS_RateLimit_InMemoryStore();
+    this.keyPolicies.clear();
+    this.endpointPolicies.clear();
+  }
+
+  private buildConfigSnapshot(config: DyNTS_RateLimit_Config): DyNTS_RateLimit_ConfigSnapshot_Interface {
+    const defaultLimit: number = config.defaultLimit ?? this.defaultLimit;
+    const defaultWindowMs: number = config.defaultWindowMs ?? this.defaultWindowMs;
+    const store: DyNTS_RateLimit_Store_Interface = config.store ?? this.store;
+    const isSharedStoreRequired: boolean = config.requireSharedStore ?? this.isSharedStoreRequired;
+    const isKeyExtractorExplicit: boolean = config.keyExtractor !== undefined || this.isKeyExtractorExplicit;
+    const isEndpointGrouperExplicit: boolean = config.endpointGrouper !== undefined
+      || this.isEndpointGrouperExplicit;
+    const keyPolicies: Map<string, DyNTS_RateLimit_Policy> = new Map(this.keyPolicies);
+    const endpointPolicies: Map<string, DyNTS_RateLimit_Policy> = new Map(this.endpointPolicies);
+
+    this.assertPolicy({ limit: defaultLimit, windowMs: defaultWindowMs });
+    this.assertConfigurationFunctions(config);
+    this.assertStore(store);
+    this.addInitialPolicies(keyPolicies, config.initialKeyPolicies);
+    this.addInitialPolicies(endpointPolicies, config.initialEndpointPolicies);
+
+    if (
+      isSharedStoreRequired
+      && (
+        store.storeKind !== DyNTS_RateLimitStoreKind_Type.shared
+        || !isKeyExtractorExplicit
+        || !isEndpointGrouperExplicit
+      )
+    ) {
+      this.throwRateLimitError({
+        status: 500,
+        subcode: 'SHARED_STORE_REQUIRED',
+        message: 'Production rate limiting requires a shared store and explicit opaque bucket extractors.',
+        userMessage: 'Request protection is not configured.',
+      });
+    }
+
+    return {
+      defaultLimit: defaultLimit,
+      defaultWindowMs: defaultWindowMs,
+      isResponseHeadersEnabled: config.responseHeaders ?? this.isResponseHeadersEnabled,
+      isSharedStoreRequired: isSharedStoreRequired,
+      keyExtractor: config.keyExtractor ?? this.keyExtractor,
+      endpointGrouper: config.endpointGrouper ?? this.endpointGrouper,
+      costExtractor: config.costExtractor ?? this.costExtractor,
+      clock: config.clock ?? this.clock,
+      store: store,
+      isKeyExtractorExplicit: isKeyExtractorExplicit,
+      isEndpointGrouperExplicit: isEndpointGrouperExplicit,
+      keyPolicies: keyPolicies,
+      endpointPolicies: endpointPolicies,
+    };
+  }
+
+  private addInitialPolicies(
+    target: Map<string, DyNTS_RateLimit_Policy>,
+    policies?: Record<string, DyNTS_RateLimit_Policy>
+  ): void {
+    if (!policies) {
+      return;
+    }
 
-  /**
-   * Default key-extractor: x-forwarded-for vagy req.ip vagy 'unknown'.
-   * Csak akkor hasznalt, ha a host nem allit be sajat extractort a configure-ben.
-   */
-  private defaultKeyExtractor(req: Request): string {
-    const xff: unknown = req.headers['x-forwarded-for'];
-    if (typeof xff === 'string' && xff.length > 0) {
-      const first: string = xff.split(',')[0]?.trim() ?? '';
-      if (first.length > 0) {
-        return first;
-      }
+    for (const entry of Object.entries(policies)) {
+      const key: string = entry[0];
+      const policy: DyNTS_RateLimit_Policy = entry[1];
+
+      this.assertBucketPart(key);
+      this.assertPolicy(policy);
+      target.set(key, { ...policy });
     }
-    if (Array.isArray(xff) && xff.length > 0) {
-      const first: string = xff[0]?.split(',')[0]?.trim() ?? '';
-      if (first.length > 0) {
-        return first;
-      }
+  }
+
+  private assertPolicy(policy: DyNTS_RateLimit_Policy): void {
+    if (
+      !Number.isSafeInteger(policy.limit)
+      || policy.limit <= 0
+      || policy.limit > MAX_LIMIT
+      || !Number.isSafeInteger(policy.windowMs)
+      || policy.windowMs <= 0
+      || policy.windowMs > MAX_WINDOW_MS
+    ) {
+      this.throwRateLimitError({
+        status: 500,
+        subcode: 'POLICY_INVALID',
+        message: 'A rate-limit policy is outside the supported safety bounds.',
+        userMessage: 'Request protection is not configured.',
+      });
     }
-    return req.ip ?? 'unknown';
   }
 
+  private assertCost(cost: number, policy: DyNTS_RateLimit_Policy): void {
+    if (!Number.isSafeInteger(cost) || cost <= 0 || cost > policy.limit) {
+      this.throwRateLimitError({
+        status: 500,
+        subcode: 'COST_INVALID',
+        message: 'A rate-limit request cost is outside the active policy.',
+        userMessage: 'Request protection is not configured.',
+      });
+    }
+  }
 
-  /**
-   * GC timer inditasa (idempotent). Periodikusan eltavolitja az inaktiv
-   * storage-key-eket a request-log-bol — memory-leak prevention.
-   */
-  private startGcTimer(): void {
-    if (this.gcTimer !== null) {
-      return;
+  private assertConfigurationFunctions(config: DyNTS_RateLimit_Config): void {
+    const hasInvalidFunction: boolean = (
+      config.keyExtractor !== undefined && typeof config.keyExtractor !== 'function'
+    ) || (
+      config.endpointGrouper !== undefined && typeof config.endpointGrouper !== 'function'
+    ) || (
+      config.costExtractor !== undefined && typeof config.costExtractor !== 'function'
+    ) || (
+      config.clock !== undefined && typeof config.clock !== 'function'
+    );
+
+    if (hasInvalidFunction) {
+      this.throwRateLimitError({
+        status: 500,
+        subcode: 'CONFIG_INVALID',
+        message: 'A rate-limit configuration callback is invalid.',
+        userMessage: 'Request protection is not configured.',
+      });
     }
-    this.gcTimer = setInterval((): void => {
-      this.runGc();
-    }, GC_INTERVAL_MS);
-    // unref hogy a process ne maradjon eletben a timer miatt
-    if (typeof this.gcTimer.unref === 'function') {
-      this.gcTimer.unref();
+  }
+
+  private assertStore(store: DyNTS_RateLimit_Store_Interface): void {
+    const hasKnownKind: boolean = store?.storeKind === DyNTS_RateLimitStoreKind_Type.inMemory
+      || store?.storeKind === DyNTS_RateLimitStoreKind_Type.shared;
+
+    if (!hasKnownKind || typeof store.consume !== 'function') {
+      this.throwRateLimitError({
+        status: 500,
+        subcode: 'STORE_INVALID',
+        message: 'The configured rate-limit store does not satisfy the Bedrock contract.',
+        userMessage: 'Request protection is not configured.',
+      });
     }
   }
 
-  /**
-   * GC sweep — minden storage-key-rol levagja a regi timestamp-eket, es
-   * eltavolitja az ureseket. Hivhato kulonosen test-bol.
-   */
-  runGc(): void {
-    const now: number = Date.now();
-    const horizon: number = now - this.defaultWindowMs;
-
-    for (const [ key, timestamps ] of this.requestLog) {
-      const recent: number[] = timestamps.filter((t: number): boolean => t > horizon);
-      if (recent.length === 0) {
-        this.requestLog.delete(key);
-      } else {
-        this.requestLog.set(key, recent);
-      }
+  private extractBucketPart(extractor: (req: Request) => string, req: Request): string {
+    let value: unknown;
+
+    try {
+      value = extractor(req);
+    } catch {
+      value = undefined;
     }
+
+    if (typeof value !== 'string') {
+      this.throwBucketKeyInvalid();
+    }
+
+    const normalized: string = value.trim();
+
+    this.assertBucketPart(normalized);
+
+    return normalized;
   }
 
-  /**
-   * GC timer leallitasa (graceful shutdown vagy test-cleanup).
-   */
-  stopGcTimer(): void {
-    if (this.gcTimer !== null) {
-      clearInterval(this.gcTimer);
-      this.gcTimer = null;
+  private extractCost(req: Request): number {
+    try {
+      return this.costExtractor(req);
+    } catch {
+      this.throwRateLimitError({
+        status: 500,
+        subcode: 'COST_INVALID',
+        message: 'The rate-limit request cost could not be derived.',
+        userMessage: 'Request protection is not configured.',
+      });
     }
   }
 
+  private buildBucketKey(subject: string, endpoint: string): string {
+    return `${subject.length}:${subject}${endpoint.length}:${endpoint}`;
+  }
 
-  /**
-   * Test-only: visszaallitja a default config-ot + uriti a state-et, hogy a
-   * specfajlok ne szivarogjak at egymas state-jet. Production code NE hivja.
-   */
-  _resetForTesting(): void {
-    this.defaultLimit     = DEFAULT_LIMIT;
-    this.defaultWindowMs  = DEFAULT_WINDOW_MS;
-    this.responseHeaders  = DEFAULT_RESPONSE_HEADERS;
-    this.keyExtractor     = (req: Request): string => this.defaultKeyExtractor(req);
-    this.endpointGrouper  = (req: Request): string => req.path;
-    this.requestLog.clear();
-    this.keyPolicies.clear();
-    this.endpointPolicies.clear();
-    this.stopGcTimer();
+  private getNow(): number {
+    let now: unknown;
+
+    try {
+      now = this.clock();
+    } catch {
+      now = undefined;
+    }
+
+    if (!Number.isSafeInteger(now) || typeof now !== 'number' || now < 0) {
+      this.throwRateLimitError({
+        status: 503,
+        subcode: 'CLOCK_INVALID',
+        message: 'The rate-limit clock returned an invalid timestamp.',
+        userMessage: 'Request protection is temporarily unavailable. Please try again later.',
+      });
+    }
+
+    return now;
+  }
+
+  private assertBucketPart(value: string): void {
+    if (!value || value.length > MAX_BUCKET_PART_LENGTH) {
+      this.throwBucketKeyInvalid();
+    }
+  }
+
+  private throwBucketKeyInvalid(): never {
+    this.throwRateLimitError({
+      status: 500,
+      subcode: 'BUCKET_KEY_INVALID',
+      message: 'A rate-limit bucket component is missing, invalid or too large.',
+      userMessage: 'Request protection is not configured.',
+    });
+  }
+
+  private assertStoreResult(
+    result: unknown,
+    policy: DyNTS_RateLimit_Policy,
+    now: number
+  ): asserts result is DyNTS_RateLimit_ConsumeResult_Interface {
+    const isValid: boolean = typeof result === 'object'
+      && result !== null
+      && 'allowed' in result
+      && 'remaining' in result
+      && 'resetAt' in result
+      && typeof result.allowed === 'boolean'
+      && typeof result.remaining === 'number'
+      && Number.isSafeInteger(result.remaining)
+      && result.remaining >= 0
+      && result.remaining <= policy.limit
+      && typeof result.resetAt === 'number'
+      && Number.isSafeInteger(result.resetAt)
+      && result.resetAt >= now;
+
+    if (!isValid) {
+      this.throwRateLimitError({
+        status: 503,
+        subcode: 'STORE_RESULT_INVALID',
+        message: 'The rate-limit store returned an invalid permit decision.',
+        userMessage: 'Request protection is temporarily unavailable. Please try again later.',
+      });
+    }
+  }
+
+  private setResponseHeaders(
+    res: Response,
+    context: DyNTS_RateLimit_HeaderContext_Interface
+  ): void {
+    if (!this.isResponseHeadersEnabled) {
+      return;
+    }
+
+    const resetSeconds: string = Math.ceil(context.result.resetAt / 1_000).toString();
+
+    res.setHeader('X-RateLimit-Limit', context.policy.limit.toString());
+    res.setHeader('X-RateLimit-Remaining', context.result.remaining.toString());
+    res.setHeader('X-RateLimit-Reset', resetSeconds);
+    res.setHeader('RateLimit-Limit', context.policy.limit.toString());
+    res.setHeader('RateLimit-Remaining', context.result.remaining.toString());
+    res.setHeader(
+      'RateLimit-Reset',
+      Math.max(0, Math.ceil((context.result.resetAt - context.now) / 1_000)).toString()
+    );
+
+    if (!context.result.allowed) {
+      res.setHeader(
+        'Retry-After',
+        this.getRetryAfterSeconds(context.result.resetAt, context.now).toString()
+      );
+    }
+  }
+
+  private getRetryAfterSeconds(resetAt: number, now: number): number {
+    return Math.max(1, Math.ceil((resetAt - now) / 1_000));
+  }
+
+  private throwRateLimitError(context: DyNTS_RateLimit_ErrorContext_Interface): never {
+    const systemShortCode: string = DyNTS_global_settings.systemShortCodeName ?? 'DyNTS';
+
+    throw new DyFM_Error({
+      status: context.status,
+      errorCode: `${systemShortCode}|DyNTS-RL-${context.subcode}`,
+      addECToUserMsg: true,
+      message: context.message,
+      userMessage: context.userMessage,
+      issuerService: SERVICE_NAME,
+    });
   }
 }