@futdevpro/nts-dynamo 1.15.145 → 1.15.151

package/build/_modules/rate-limit/rate-limit.middleware.js

@@ -2,288 +2,377 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DyNTS_RateLimit_Middleware = void 0;
 const fsm_dynamo_1 = require("@futdevpro/fsm-dynamo");
-const singleton_service_base_1 = require("../../_services/base/singleton.service-base");
 const global_settings_const_1 = require("../../_collections/global-settings.const");
-/** Default request-limit per default-window. */
+const singleton_service_base_1 = require("../../_services/base/singleton.service-base");
+const rate_limit_store_kind_type_enum_1 = require("./_enums/rate-limit-store-kind.type-enum");
+const rate_limit_in_memory_store_1 = require("./rate-limit-in-memory.store");
 const DEFAULT_LIMIT = 100;
-/** Default sliding-window hossza ms-ben (1 perc). */
-const DEFAULT_WINDOW_MS = 60000;
-/** Default response-header allitas. */
+const DEFAULT_WINDOW_MS = 60_000;
 const DEFAULT_RESPONSE_HEADERS = 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 = 5 * 60 * 1000;
-/** Service-nev az error-okhoz. */
+const MAX_LIMIT = 1_000_000;
+const MAX_WINDOW_MS = 7 * 24 * 60 * 60 * 1_000;
+const MAX_BUCKET_PART_LENGTH = 240;
 const SERVICE_NAME = 'DyNTS_RateLimit_Middleware';
-/** ErrorCode-builder — system shortcode + sajat kod. */
-const buildErrorCode = (subcode) => {
-    const sys = global_settings_const_1.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.
- */
+/** Atomic HTTP rate-limit boundary with an explicit shared-store production gate. */
 class DyNTS_RateLimit_Middleware extends singleton_service_base_1.DyNTS_SingletonServiceBase {
-    static getInstance() {
-        return DyNTS_RateLimit_Middleware.getSingletonInstance();
-    }
     defaultLimit = DEFAULT_LIMIT;
     defaultWindowMs = DEFAULT_WINDOW_MS;
-    responseHeaders = DEFAULT_RESPONSE_HEADERS;
-    keyExtractor = (req) => this.defaultKeyExtractor(req);
+    isResponseHeadersEnabled = DEFAULT_RESPONSE_HEADERS;
+    isSharedStoreRequired = false;
+    isKeyExtractorExplicit = false;
+    isEndpointGrouperExplicit = false;
+    keyExtractor = (req) => req.ip ?? 'unknown';
     endpointGrouper = (req) => req.path;
-    /** request-log: storageKey → timestamp-tomb (Date.now() ms). */
-    requestLog = new Map();
-    /** Per-kulcs egyedi policy-k. */
+    costExtractor = (req) => {
+        void req;
+        return 1;
+    };
+    clock = () => Date.now();
+    store = new rate_limit_in_memory_store_1.DyNTS_RateLimit_InMemoryStore();
     keyPolicies = new Map();
-    /** Per-endpoint(-csoport) egyedi policy-k (a `endpointGrouper` outputjara kulcsolva). */
     endpointPolicies = new Map();
-    /** GC timer handle. */
-    gcTimer = null;
-    /**
-     * Konfig override. Hianyzo mezok a default-okat orzik. Hivhato barmikor —
-     * a `check()` a friss config-ot olvassa.
-     */
+    /** Returns the process-wide rate-limit middleware. */
+    static getInstance() {
+        return DyNTS_RateLimit_Middleware.getSingletonInstance();
+    }
+    /** Applies a validated configuration atomically; invalid settings do not partially mutate the service. */
     configure(config) {
-        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();
+        const snapshot = 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).
-     */
+    /** Returns content-free configuration diagnostics. */
     getConfig() {
         return {
             defaultLimit: this.defaultLimit,
             defaultWindowMs: this.defaultWindowMs,
-            responseHeaders: this.responseHeaders,
+            responseHeaders: this.isResponseHeadersEnabled,
             activeKeyPolicies: this.keyPolicies.size,
             activeEndpointPolicies: this.endpointPolicies.size,
-            trackedStorageKeys: this.requestLog.size,
+            trackedStorageKeys: this.store instanceof rate_limit_in_memory_store_1.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.
-     */
+    /** Sets one validated subject policy. */
     setPolicyForKey(key, policy) {
-        this.keyPolicies.set(key, policy);
+        this.assertBucketPart(key);
+        this.assertPolicy(policy);
+        this.keyPolicies.set(key, { ...policy });
     }
-    /**
-     * Per-kulcs policy torlese (visszaall a default-ra).
-     */
+    /** Removes one subject policy. */
     clearPolicyForKey(key) {
         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.
-     */
+    /** Sets one validated endpoint-group policy. */
     setPolicyForEndpoint(endpoint, policy) {
-        this.endpointPolicies.set(endpoint, policy);
+        this.assertBucketPart(endpoint);
+        this.assertPolicy(policy);
+        this.endpointPolicies.set(endpoint, { ...policy });
     }
-    /**
-     * Per-endpoint policy torlese (visszaall a default-ra).
-     */
+    /** Removes one endpoint-group policy. */
     clearPolicyForEndpoint(endpoint) {
         this.endpointPolicies.delete(endpoint);
     }
-    /**
-     * 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.
-     */
+    /** Atomically consumes one request permit or raises a stable content-free error. */
     check = async (req, res) => {
-        const subject = this.keyExtractor(req);
-        const endpoint = this.endpointGrouper(req);
-        const storageKey = `${subject}|${endpoint}`;
-        // precedencia: per-kulcs policy (legspecifikusabb, pl. subscriber-tier) > per-endpoint policy > default
-        const policy = this.keyPolicies.get(subject) ??
-            this.endpointPolicies.get(endpoint) ??
-            {
-                limit: this.defaultLimit,
-                windowMs: this.defaultWindowMs,
-            };
-        const now = Date.now();
-        const windowStart = now - policy.windowMs;
-        // sliding-window: tartomanyon kivuli timestamp-eket eldobjuk
-        const existing = this.requestLog.get(storageKey) ?? [];
-        const recent = existing.filter((t) => t > windowStart);
-        if (recent.length >= policy.limit) {
-            const oldest = recent[0];
-            const resetAt = oldest + policy.windowMs;
-            const retryAfterSec = 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 fsm_dynamo_1.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,
+        const subject = this.extractBucketPart(this.keyExtractor, req);
+        const endpoint = this.extractBucketPart(this.endpointGrouper, req);
+        const cost = this.extractCost(req);
+        const policy = this.keyPolicies.get(subject)
+            ?? this.endpointPolicies.get(endpoint)
+            ?? { limit: this.defaultLimit, windowMs: this.defaultWindowMs };
+        this.assertPolicy(policy);
+        this.assertCost(cost, policy);
+        const now = this.getNow();
+        let result;
+        try {
+            result = await this.store.consume({
+                bucketKey: this.buildBucketKey(subject, endpoint),
+                policy: policy,
+                cost: cost,
+                now: now,
             });
         }
-        // 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());
+        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.',
+            });
+        }
+        this.assertStoreResult(result, policy, now);
+        this.setResponseHeaders(res, {
+            policy: policy,
+            result: result,
+            now: now,
+        });
+        if (!result.allowed) {
+            const retryAfterSeconds = 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.`,
+            });
         }
     };
-    /**
-     * 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.
-     */
-    defaultKeyExtractor(req) {
-        const xff = req.headers['x-forwarded-for'];
-        if (typeof xff === 'string' && xff.length > 0) {
-            const first = xff.split(',')[0]?.trim() ?? '';
-            if (first.length > 0) {
-                return first;
-            }
+    /** Performs explicit opportunistic cleanup only for the local test/development store. */
+    runGc() {
+        if (this.store instanceof rate_limit_in_memory_store_1.DyNTS_RateLimit_InMemoryStore) {
+            this.store.cleanup(this.clock());
         }
-        if (Array.isArray(xff) && xff.length > 0) {
-            const first = xff[0]?.split(',')[0]?.trim() ?? '';
-            if (first.length > 0) {
-                return first;
-            }
+    }
+    /** Backward-compatible no-op: this implementation never starts a timer. */
+    stopGcTimer() { }
+    /** Resets all state to deterministic local defaults for tests. */
+    _resetForTesting() {
+        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) => req.ip ?? 'unknown';
+        this.endpointGrouper = (req) => req.path;
+        this.costExtractor = (req) => {
+            void req;
+            return 1;
+        };
+        this.clock = () => Date.now();
+        this.store = new rate_limit_in_memory_store_1.DyNTS_RateLimit_InMemoryStore();
+        this.keyPolicies.clear();
+        this.endpointPolicies.clear();
+    }
+    buildConfigSnapshot(config) {
+        const defaultLimit = config.defaultLimit ?? this.defaultLimit;
+        const defaultWindowMs = config.defaultWindowMs ?? this.defaultWindowMs;
+        const store = config.store ?? this.store;
+        const isSharedStoreRequired = config.requireSharedStore ?? this.isSharedStoreRequired;
+        const isKeyExtractorExplicit = config.keyExtractor !== undefined || this.isKeyExtractorExplicit;
+        const isEndpointGrouperExplicit = config.endpointGrouper !== undefined
+            || this.isEndpointGrouperExplicit;
+        const keyPolicies = new Map(this.keyPolicies);
+        const endpointPolicies = 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 !== rate_limit_store_kind_type_enum_1.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 req.ip ?? 'unknown';
+        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,
+        };
     }
-    /**
-     * GC timer inditasa (idempotent). Periodikusan eltavolitja az inaktiv
-     * storage-key-eket a request-log-bol — memory-leak prevention.
-     */
-    startGcTimer() {
-        if (this.gcTimer !== null) {
+    addInitialPolicies(target, policies) {
+        if (!policies) {
             return;
         }
-        this.gcTimer = setInterval(() => {
-            this.runGc();
-        }, GC_INTERVAL_MS);
-        // unref hogy a process ne maradjon eletben a timer miatt
-        if (typeof this.gcTimer.unref === 'function') {
-            this.gcTimer.unref();
+        for (const entry of Object.entries(policies)) {
+            const key = entry[0];
+            const policy = entry[1];
+            this.assertBucketPart(key);
+            this.assertPolicy(policy);
+            target.set(key, { ...policy });
         }
     }
-    /**
-     * GC sweep — minden storage-key-rol levagja a regi timestamp-eket, es
-     * eltavolitja az ureseket. Hivhato kulonosen test-bol.
-     */
-    runGc() {
-        const now = Date.now();
-        const horizon = now - this.defaultWindowMs;
-        for (const [key, timestamps] of this.requestLog) {
-            const recent = timestamps.filter((t) => t > horizon);
-            if (recent.length === 0) {
-                this.requestLog.delete(key);
-            }
-            else {
-                this.requestLog.set(key, recent);
-            }
+    assertPolicy(policy) {
+        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.',
+            });
+        }
+    }
+    assertCost(cost, policy) {
+        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 leallitasa (graceful shutdown vagy test-cleanup).
-     */
-    stopGcTimer() {
-        if (this.gcTimer !== null) {
-            clearInterval(this.gcTimer);
-            this.gcTimer = null;
+    assertConfigurationFunctions(config) {
+        const hasInvalidFunction = (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.',
+            });
         }
     }
-    /**
-     * 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() {
-        this.defaultLimit = DEFAULT_LIMIT;
-        this.defaultWindowMs = DEFAULT_WINDOW_MS;
-        this.responseHeaders = DEFAULT_RESPONSE_HEADERS;
-        this.keyExtractor = (req) => this.defaultKeyExtractor(req);
-        this.endpointGrouper = (req) => req.path;
-        this.requestLog.clear();
-        this.keyPolicies.clear();
-        this.endpointPolicies.clear();
-        this.stopGcTimer();
+    assertStore(store) {
+        const hasKnownKind = store?.storeKind === rate_limit_store_kind_type_enum_1.DyNTS_RateLimitStoreKind_Type.inMemory
+            || store?.storeKind === rate_limit_store_kind_type_enum_1.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.',
+            });
+        }
+    }
+    extractBucketPart(extractor, req) {
+        let value;
+        try {
+            value = extractor(req);
+        }
+        catch {
+            value = undefined;
+        }
+        if (typeof value !== 'string') {
+            this.throwBucketKeyInvalid();
+        }
+        const normalized = value.trim();
+        this.assertBucketPart(normalized);
+        return normalized;
+    }
+    extractCost(req) {
+        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.',
+            });
+        }
+    }
+    buildBucketKey(subject, endpoint) {
+        return `${subject.length}:${subject}${endpoint.length}:${endpoint}`;
+    }
+    getNow() {
+        let now;
+        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;
+    }
+    assertBucketPart(value) {
+        if (!value || value.length > MAX_BUCKET_PART_LENGTH) {
+            this.throwBucketKeyInvalid();
+        }
+    }
+    throwBucketKeyInvalid() {
+        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.',
+        });
+    }
+    assertStoreResult(result, policy, now) {
+        const isValid = 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.',
+            });
+        }
+    }
+    setResponseHeaders(res, context) {
+        if (!this.isResponseHeadersEnabled) {
+            return;
+        }
+        const resetSeconds = 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());
+        }
+    }
+    getRetryAfterSeconds(resetAt, now) {
+        return Math.max(1, Math.ceil((resetAt - now) / 1_000));
+    }
+    throwRateLimitError(context) {
+        const systemShortCode = global_settings_const_1.DyNTS_global_settings.systemShortCodeName ?? 'DyNTS';
+        throw new fsm_dynamo_1.DyFM_Error({
+            status: context.status,
+            errorCode: `${systemShortCode}|DyNTS-RL-${context.subcode}`,
+            addECToUserMsg: true,
+            message: context.message,
+            userMessage: context.userMessage,
+            issuerService: SERVICE_NAME,
+        });
     }
 }
 exports.DyNTS_RateLimit_Middleware = DyNTS_RateLimit_Middleware;