@futdevpro/nts-dynamo 1.15.145 → 1.15.150

package/src/_modules/rate-limit/_models/rate-limit-config.interface.ts

@@ -1,6 +1,7 @@
 import { Request } from 'express';
 
 import { DyNTS_RateLimit_Policy } from './rate-limit-policy.interface';
+import { DyNTS_RateLimit_Store_Interface } from './rate-limit-store.interface';
 
 /**
  * Config a `DyNTS_RateLimit_Middleware.configure(...)`-hoz.
@@ -25,17 +26,17 @@ export interface DyNTS_RateLimit_Config {
    * Rate-limit subject-extractor. Visszater a karakterlanccal, ami azonositja
    * a rate-limit alanyat (pl. IP-cim, API-kulcs ID, account ID).
    *
-   * Default: a `req.headers['x-forwarded-for']` (csak az elso IP, ha lista)
-   * vagy ha hianyzik akkor `req.ip` vagy `'unknown'`. Ez webszerver elotti
-   * proxy/CDN-mentes setup-ra megfelelo; ha az nd-space mar identifikalja az
-   * API-kulcsot a `req`-ben, a host adhat sajat extractort ami a key-ID-t
-   * adja vissza.
+   * Default: az Express altal mar megbizhatonak minositett `req.ip`, vagy ha
+   * hianyzik akkor `'unknown'`. A middleware szandekosan nem olvassa kozvetlenul
+   * az ugyfel altal hamisithato `x-forwarded-for` headert. Production uzemben a
+   * shared-store gate explicit, opaque extractort kovetel.
    */
   keyExtractor?: (req: Request) => string;
 
   /**
    * Endpoint-csoportosito. Visszater a karakterlanccal, ami azonositja az
-   * adott endpoint-csoportot. A storage-key `${subject}|${endpoint}` lesz.
+   * adott endpoint-csoportot. A storage-key egyertelmuen hossz-prefixelt
+   * subject + endpoint kompozicio lesz.
    *
    * Default: `req.path` — minden uri-path kulon vodorbe kerul. Csoportositas
    * mas szempontok szerint (pl. "datasets" csoport = `/api/datasets/*`)
@@ -43,6 +44,18 @@ export interface DyNTS_RateLimit_Config {
    */
   endpointGrouper?: (req: Request) => string;
 
+  /** Optional permit cost per request. Default: one. */
+  costExtractor?: (req: Request) => number;
+
+  /** Atomic store. The default in-memory implementation is for tests and single-instance development only. */
+  store?: DyNTS_RateLimit_Store_Interface;
+
+  /** Fail configuration unless a shared store plus explicit opaque key/group extractors are supplied. */
+  requireSharedStore?: boolean;
+
+  /** Deterministic clock seam. Production callers normally omit it. */
+  clock?: () => number;
+
   /**
    * Beallitja-e a `X-RateLimit-Limit`, `X-RateLimit-Remaining`,
    * `X-RateLimit-Reset` (es a 429-re `Retry-After`) response header-eket.

package/src/_modules/rate-limit/_models/rate-limit-consume-request.interface.ts

@@ -0,0 +1,9 @@
+import { DyNTS_RateLimit_Policy } from './rate-limit-policy.interface';
+
+/** Atomic permit request passed to a rate-limit store. */
+export interface DyNTS_RateLimit_ConsumeRequest_Interface {
+  bucketKey: string;
+  policy: DyNTS_RateLimit_Policy;
+  cost: number;
+  now: number;
+}

package/src/_modules/rate-limit/_models/rate-limit-consume-result.interface.ts

@@ -0,0 +1,6 @@
+/** Content-free result of one atomically committed permit request. */
+export interface DyNTS_RateLimit_ConsumeResult_Interface {
+  allowed: boolean;
+  remaining: number;
+  resetAt: number;
+}

package/src/_modules/rate-limit/_models/rate-limit-store.interface.ts

@@ -0,0 +1,9 @@
+import { DyNTS_RateLimitStoreKind_Type } from '../_enums/rate-limit-store-kind.type-enum';
+import { DyNTS_RateLimit_ConsumeRequest_Interface } from './rate-limit-consume-request.interface';
+import { DyNTS_RateLimit_ConsumeResult_Interface } from './rate-limit-consume-result.interface';
+
+/** Atomic persistence seam. Production hosts can require `shared` scope at configuration time. */
+export interface DyNTS_RateLimit_Store_Interface {
+  readonly storeKind: DyNTS_RateLimitStoreKind_Type;
+  consume(request: DyNTS_RateLimit_ConsumeRequest_Interface): Promise<DyNTS_RateLimit_ConsumeResult_Interface>;
+}

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

@@ -1,3 +1,8 @@
 export { DyNTS_RateLimit_Middleware } from './rate-limit.middleware';
+export { DyNTS_RateLimit_InMemoryStore } from './rate-limit-in-memory.store';
 export { DyNTS_RateLimit_Config } from './_models/rate-limit-config.interface';
+export { DyNTS_RateLimit_ConsumeRequest_Interface } from './_models/rate-limit-consume-request.interface';
+export { DyNTS_RateLimit_ConsumeResult_Interface } from './_models/rate-limit-consume-result.interface';
 export { DyNTS_RateLimit_Policy } from './_models/rate-limit-policy.interface';
+export { DyNTS_RateLimit_Store_Interface } from './_models/rate-limit-store.interface';
+export { DyNTS_RateLimitStoreKind_Type } from './_enums/rate-limit-store-kind.type-enum';

package/src/_modules/rate-limit/rate-limit-in-memory.store.ts

@@ -0,0 +1,91 @@
+import { DyNTS_RateLimitStoreKind_Type } from './_enums/rate-limit-store-kind.type-enum';
+import { DyNTS_RateLimit_ConsumeRequest_Interface } from './_models/rate-limit-consume-request.interface';
+import { DyNTS_RateLimit_ConsumeResult_Interface } from './_models/rate-limit-consume-result.interface';
+import { DyNTS_RateLimit_Store_Interface } from './_models/rate-limit-store.interface';
+
+interface DyNTS_RateLimit_InMemoryRecord_Interface {
+  timestamps: number[];
+  windowMs: number;
+}
+
+/** Deterministic single-process store for tests and explicitly single-instance development. */
+export class DyNTS_RateLimit_InMemoryStore implements DyNTS_RateLimit_Store_Interface {
+  public readonly storeKind: DyNTS_RateLimitStoreKind_Type = DyNTS_RateLimitStoreKind_Type.inMemory;
+  private readonly records: Map<string, DyNTS_RateLimit_InMemoryRecord_Interface> = new Map();
+
+  /** Consumes permit units with exact sliding-window semantics and no background cleanup task. */
+  public async consume(
+    request: DyNTS_RateLimit_ConsumeRequest_Interface
+  ): Promise<DyNTS_RateLimit_ConsumeResult_Interface> {
+    this.assertRequest(request);
+
+    const windowStart: number = request.now - request.policy.windowMs;
+    const existing: DyNTS_RateLimit_InMemoryRecord_Interface | undefined = this.records.get(request.bucketKey);
+    const recent: number[] = (existing?.timestamps ?? []).filter(
+      (timestamp: number): boolean => timestamp > windowStart
+    );
+    const allowed: boolean = recent.length + request.cost <= request.policy.limit;
+
+    if (allowed) {
+      for (let index: number = 0; index < request.cost; index += 1) {
+        recent.push(request.now);
+      }
+    }
+
+    this.records.set(request.bucketKey, {
+      timestamps: recent,
+      windowMs: request.policy.windowMs,
+    });
+
+    return {
+      allowed: allowed,
+      remaining: Math.max(0, request.policy.limit - recent.length),
+      resetAt: (recent[0] ?? request.now) + request.policy.windowMs,
+    };
+  }
+
+  /** Opportunistically removes expired local records when explicitly invoked by the host. */
+  public cleanup(now: number): void {
+    for (const entry of this.records.entries()) {
+      const key: string = entry[0];
+      const record: DyNTS_RateLimit_InMemoryRecord_Interface = entry[1];
+      const recent: number[] = record.timestamps.filter(
+        (timestamp: number): boolean => timestamp > now - record.windowMs
+      );
+
+      if (!recent.length) {
+        this.records.delete(key);
+      } else {
+        this.records.set(key, { ...record, timestamps: recent });
+      }
+    }
+  }
+
+  /** Clears all local state for deterministic tests. */
+  public reset(): void {
+    this.records.clear();
+  }
+
+  /** Returns only the aggregate local bucket count for diagnostics. */
+  public getTrackedBucketCount(): number {
+    return this.records.size;
+  }
+
+  private assertRequest(request: DyNTS_RateLimit_ConsumeRequest_Interface): void {
+    const isValid: boolean = Boolean(request.bucketKey.trim())
+      && request.bucketKey.length <= 512
+      && Number.isSafeInteger(request.now)
+      && request.now >= 0
+      && Number.isSafeInteger(request.cost)
+      && request.cost > 0
+      && Number.isSafeInteger(request.policy.limit)
+      && request.policy.limit > 0
+      && Number.isSafeInteger(request.policy.windowMs)
+      && request.policy.windowMs > 0
+      && request.cost <= request.policy.limit;
+
+    if (!isValid) {
+      throw new Error('DYNTS_RATE_LIMIT_STORE_REQUEST_INVALID');
+    }
+  }
+}