@stimulcross/rate-limiter 0.0.1 → 0.0.3

package/src/limiters/generic-cell/generic-cell.limiter.ts

@@ -1,108 +0,0 @@
-import { LogLevel } from '@stimulcross/logger';
-import { GenericCellPolicy } from './generic-cell.policy.js';
-import { AbstractRateLimiter, type ExecutionContext } from '../abstract-rate-limiter.js';
-import { type GenericCellOptions } from './generic-cell.options.js';
-import { type GenericCellState } from './generic-cell.state.js';
-import { type GenericCellStatus } from './generic-cell.status.js';
-import { type Decision } from '../../core/decision.js';
-import { RateLimitErrorCode } from '../../enums/rate-limit-error-code.js';
-import { RateLimitError } from '../../errors/rate-limit.error.js';
-import { type LimitBehavior } from '../../types/limit-behavior.js';
-
-/**
- * Generic Cell (GCRA) rate limiter.
- *
- * Designed primarily for client-side use to respect third-party limits or protect resources.
- * While this can be used as a server-side limiter with custom distributed storage
- * (e.g., Redis), it is best-effort and not recommended due to high network round-trip latency.
- *
- * Key features:
- * - **Queueing & overflow** - optionally enqueues excess requests up to a maximum allowed overflow capacity
- * - **Concurrency** - limits how many requests can be executed simultaneously
- * - **Priority** - supports task priorities (with fairness and custom policy) to execute critical requests first
- * - **Cancellation** - supports `AbortSignal` to safely remove pending requests from the queue
- * - **Expiration** - automatically drops queued requests that wait longer than the allowed `maxWaitMs`
- * - **Auto-rollback** - reverts spent quota if an enqueued task is canceled or expired
- */
-export class GenericCellLimiter extends AbstractRateLimiter<GenericCellState, GenericCellStatus> {
-	private readonly _defaultLimitBehaviour: LimitBehavior;
-	private readonly _defaultMaxWaitMs: number | undefined;
-
-	protected override readonly _policy: GenericCellPolicy;
-
-	constructor(options: GenericCellOptions) {
-		super(options);
-
-		this._defaultLimitBehaviour = options.limitBehavior ?? 'reject';
-
-		if (options.queue?.maxWaitMs) {
-			this._defaultMaxWaitMs = options.queue.maxWaitMs;
-		}
-
-		this._policy = new GenericCellPolicy(options.intervalMs, options.burst);
-	}
-
-	protected override async _runInternal<T>(fn: () => T | Promise<T>, ctx: ExecutionContext): Promise<T> {
-		const now = this._clock.now();
-		const baseTtlMs: number = Math.ceil(this._policy.burst * this._policy.intervalMs);
-
-		let runAt: number;
-		let storeTtlMs: number;
-
-		await this._store.acquireLock?.(ctx.key);
-
-		try {
-			const state = (await this._store.get(ctx.key)) ?? this._policy.getInitialState();
-			const finalLimitBehavior = ctx.limitBehavior ?? this._defaultLimitBehaviour;
-
-			const { decision, nextState } = this._policy.evaluate(
-				state,
-				now,
-				ctx.cost,
-				finalLimitBehavior === 'enqueue',
-			);
-
-			if (decision.kind === 'deny') {
-				this._logger.debug(`[DENY] [id: ${ctx.id}, key: ${ctx.key}] - Retry: +${decision.retryAt - now}ms`);
-				throw new RateLimitError(RateLimitErrorCode.LimitExceeded, decision.retryAt);
-			}
-
-			runAt = decision.kind === 'delay' ? decision.runAt : now;
-			storeTtlMs = Math.max(baseTtlMs, runAt - now + baseTtlMs);
-
-			await this._store.set(ctx.key, nextState, storeTtlMs);
-
-			this._printSuccessDebug(decision, nextState, now, ctx);
-		} finally {
-			await this._store.releaseLock?.(ctx.key);
-		}
-
-		const finalMaxWaitMs = ctx.maxWaitMs ?? this._defaultMaxWaitMs;
-		const expiresAt = finalMaxWaitMs ? now + finalMaxWaitMs : undefined;
-
-		return await this._execute<T>(fn, runAt, storeTtlMs, ctx, expiresAt);
-	}
-
-	protected override _getDebugStateString(state: GenericCellState): string {
-		return String(state.tat);
-	}
-
-	private _printSuccessDebug(
-		decision: Decision,
-		nextState: GenericCellState,
-		now: number,
-		ctx: ExecutionContext,
-	): void {
-		if (this._logger.minLevel < LogLevel.DEBUG) {
-			return;
-		}
-
-		if (decision.kind === 'delay') {
-			this._logger.debug(
-				`[DELAY] [id: ${ctx.id}, key: ${ctx.key}] +${decision.runAt - now}ms - tat: ${nextState.tat}`,
-			);
-		} else {
-			this._logger.debug(`[ALLOW] [id: ${ctx.id}, key: ${ctx.key}] - tat: ${nextState.tat}`);
-		}
-	}
-}

package/src/limiters/generic-cell/generic-cell.options.ts

@@ -1,23 +0,0 @@
-import { type GenericCellState } from './generic-cell.state.js';
-import { type RateLimiterOptions } from '../../interfaces/rate-limiter-options.js';
-
-/**
- * Options for the Generic Cell Rate Algorithm (GCRA) limiter.
- */
-export interface GenericCellOptions extends RateLimiterOptions<GenericCellState> {
-	/**
-	 * The minimum interval between requests (in milliseconds).
-	 *
-	 * This defines the emission interval.
-	 * For example, if you want to allow 10 requests per second, set this to 100ms (1000ms / 10).
-	 */
-	intervalMs: number;
-
-	/**
-	 * The maximum burst size.
-	 *
-	 * This defines how many requests can be made immediately in quick succession before rate limiting kicks in.
-	 * The burst capacity allows temporary spikes in traffic.
-	 */
-	burst: number;
-}

package/src/limiters/generic-cell/generic-cell.policy.ts

@@ -1,115 +0,0 @@
-import { type GenericCellState } from './generic-cell.state.js';
-import { type GenericCellStatus } from './generic-cell.status.js';
-import { type RateLimitPolicy, type RateLimitPolicyResult } from '../../core/rate-limit-policy.js';
-import { validateCost } from '../../utils/validate-cost.js';
-
-/** @internal */
-export class GenericCellPolicy implements RateLimitPolicy<GenericCellState, GenericCellStatus> {
-	constructor(
-		private readonly _intervalMs: number,
-		private readonly _burst: number,
-		private readonly _maxDelayMs: number = Number.POSITIVE_INFINITY,
-	) {
-		if (!Number.isFinite(_intervalMs) || !Number.isSafeInteger(_intervalMs) || _intervalMs <= 0) {
-			throw new Error(`Invalid intervalMs: ${_intervalMs}. Must be a positive integer.`);
-		}
-
-		if (!Number.isFinite(_burst) || !Number.isSafeInteger(_burst) || _burst <= 0) {
-			throw new Error(`Invalid burst: ${_burst}. Must be a positive integer.`);
-		}
-
-		if (_maxDelayMs < 0 || (!Number.isSafeInteger(_maxDelayMs) && _maxDelayMs !== Number.POSITIVE_INFINITY)) {
-			throw new Error(`Invalid maxDelayMs: ${_maxDelayMs}. Must be a non-negative integer or Infinity.`);
-		}
-	}
-
-	public get burst(): number {
-		return this._burst;
-	}
-
-	public get intervalMs(): number {
-		return this._intervalMs;
-	}
-
-	public getInitialState(): GenericCellState {
-		return { tat: 0 };
-	}
-
-	public getStatus(state: GenericCellState, now: number): GenericCellStatus {
-		const tat = Math.max(state.tat, now);
-		const burstOffset = this._burst * this._intervalMs;
-
-		const availableTimeDebt = burstOffset + now - tat;
-		const remaining = Math.max(0, Math.floor(availableTimeDebt / this._intervalMs));
-
-		const nextAvailableAt = Math.max(now, tat + this._intervalMs - burstOffset);
-
-		const resetAt = tat;
-
-		return {
-			intervalMs: this._intervalMs,
-			burst: this._burst,
-			tat,
-			remaining,
-			nextAvailableAt,
-			resetAt,
-		};
-	}
-
-	public evaluate(
-		state: GenericCellState,
-		now: number,
-		cost: number,
-		shouldReserve?: boolean,
-	): RateLimitPolicyResult<GenericCellState> {
-		const absoluteMax = shouldReserve ? this._burst + Math.floor(this._maxDelayMs / this._intervalMs) : this._burst;
-
-		validateCost(cost, absoluteMax);
-
-		const tat = Math.max(state.tat, now);
-		const costInterval = cost * this._intervalMs;
-		const burstOffset = this._burst * this._intervalMs;
-
-		const newTat = tat + costInterval;
-
-		const minNow = newTat - burstOffset;
-
-		if (now >= minNow) {
-			return {
-				decision: { kind: 'allow' },
-				nextState: { tat: newTat },
-			};
-		}
-
-		if (shouldReserve) {
-			const waitMs = minNow - now;
-
-			if (waitMs > this._maxDelayMs) {
-				const retryAt = minNow - this._maxDelayMs;
-				return this._deny(state.tat, retryAt);
-			}
-
-			const runAt = minNow;
-			return {
-				decision: { kind: 'delay', runAt },
-				nextState: { tat: newTat },
-			};
-		}
-
-		return this._deny(state.tat, minNow);
-	}
-
-	public revert(state: GenericCellState, cost: number): GenericCellState {
-		const costInterval = cost * this._intervalMs;
-		return {
-			tat: Math.max(0, state.tat - costInterval),
-		};
-	}
-
-	private _deny(tat: number, retryAt: number): RateLimitPolicyResult<GenericCellState> {
-		return {
-			decision: { kind: 'deny', retryAt },
-			nextState: { tat },
-		};
-	}
-}

package/src/limiters/generic-cell/generic-cell.status.ts

@@ -1,54 +0,0 @@
-import { type RateLimiterStatus } from '../../core/rate-limiter-status.js';
-
-/**
- * The status of the Generic Cell rate limiter.
- */
-export interface GenericCellStatus extends RateLimiterStatus {
-	/**
-	 * The minimum interval between tokens (in milliseconds).
-	 *
-	 * It represents the emission interval - the time period between
-	 * successive token emissions at the steady-state rate.
-	 */
-	readonly intervalMs: number;
-
-	/**
-	 * The maximum burst size (maximum number of tokens that can be accumulated).
-	 *
-	 * It represents the burst capacity - the maximum number of requests
-	 * that can be made instantaneously when the bucket is full.
-	 */
-	readonly burst: number;
-
-	/**
-	 * Theoretical Arrival Time (TAT) - the virtual time when the bucket will be empty.
-	 *
-	 * TAT represents the earliest time at which a future request could be allowed.
-	 *
-	 * Value is in milliseconds.
-	 */
-	readonly tat: number;
-
-	/**
-	 * The number of tokens that can be used immediately.
-	 *
-	 * Calculated as the time allowance available between now and TAT, divided by
-	 * the emission interval.
-	 */
-	readonly remaining: number;
-
-	/**
-	 * The timestamp (in milliseconds) when the next token will be available for use.
-	 *
-	 * This is the earliest time when a request can be accepted if no tokens are currently available.
-	 */
-	readonly nextAvailableAt: number;
-
-	/**
-	 * The timestamp when all tokens will be available for use again.
-	 *
-	 * It is when the TAT returns to the current time, meaning the bucket has fully recovered to its
-	 * maximum burst capacity.
-	 */
-	readonly resetAt: number;
-}

package/src/limiters/http-response-based/http-limit.info.ts

@@ -1,41 +0,0 @@
-/**
- * Rate limit information extracted from the HTTP response headers.
- */
-export interface HttpLimitInfo {
-	/**
-	 * The maximum number of requests allowed within the time window.
-	 *
-	 * It usually corresponds to `RateLimit-Limit` or `X-RateLimit-Limit` headers.
-	 */
-	limit: number;
-
-	/**
-	 * The number of requests remaining in the current time window.
-	 *
-	 * It usually corresponds to `RateLimit-Remaining` or `X-RateLimit-Remaining` headers.
-	 */
-	remaining: number;
-
-	/**
-	 * The timestamp (in milliseconds) when the current time window resets.
-	 *
-	 * It usually corresponds to `RateLimit-Reset`, `X-RateLimit-Reset`, or `Retry-After` headers.
-	 *
-	 * **WARNING:** these headers can be either delta (usually in seconds) or UNIX epoche
-	 * timestamp (usually in seconds) depending on the target API specs.
-	 *
-	 *The library expects a UNIX epoche timestamp in milliseconds. Refer to the API docs to
-	 * determine the header format and properly convert it to UNIX epoche timestamp in milliseconds.
-	 *
-	 * For example,
-	 *   - delta in seconds: `Date.now() + delta * 1000`
-	 *   - UNIX timestamp in seconds: `timestamp * 1000`
-	 *
-	 */
-	resetAt?: number | null;
-
-	/**
-	 * HTTP status code of the response.
-	 */
-	statusCode: number;
-}

package/src/limiters/http-response-based/http-response-based-limiter.state.ts

@@ -1,13 +0,0 @@
-/**
- * The state of the HTTP Response Based rate limiter.
- *
- * When using a distributed state store, make sure it properly serializes and deserializes the state.
- */
-export interface HttpResponseBasedLimiterState {
-	isProbing: boolean;
-	isUnlimited: boolean;
-	lastKnownLimit: number | null;
-	lastKnownRemaining: number | null;
-	lastKnownResetAt: number | null;
-	lastSyncedAt: number | null;
-}

package/src/limiters/http-response-based/http-response-based-limiter.status.ts

@@ -1,74 +0,0 @@
-/**
- * The status of the HTTP Response Based rate limiter.
- *
- * This interface represents rate limit information extracted from HTTP response headers,
- * such as RateLimit headers (RFC 6585) or custom headers provided by APIs (X-RateLimit-*).
- *
- * @remarks
- * The status is updated after each API response and reflects the server-side rate limit state.
- * Can be useful to check how many requests remain before hitting the rate limit.
- */
-export interface HttpResponseBasedLimiterStatus {
-	/**
-	 * Indicates whether the rate limiter is currently probing for the server's limit state.
-	 *
-	 * This is `true` when the rate limiter is waiting for the first response from the server
-	 * to extract rate limit headers.
-	 */
-	isProbing: boolean;
-
-	/**
-	 * Indicates whether the rate limiter is in unlimited mode.
-	 *
-	 * This is `true` if a server did not send any rate limit headers.
-	 *
-	 * If this is `true`, the `lastKnownLimit`, `lastKnownRemaining`, and `lastKnownResetAt` values are `null`.
-	 */
-	isUnlimited: boolean;
-
-	/**
-	 * The number of requests remaining in the current rate limit window.
-	 *
-	 * @remarks
-	 * This value is extracted from response headers such as `X-RateLimit-Remaining`
-	 * or `RateLimit-Remaining`. It decrements with each request and resets when
-	 * the time window expires.
-	 *
-	 * When this reaches 0, later requests may be delayed or rejected until the reset time.
-	 */
-	lastKnownRemaining: number | null;
-
-	/**
-	 * The maximum number of requests allowed in the current rate limit window.
-	 *
-	 * @remarks
-	 * This value is extracted from response headers such as `X-RateLimit-Limit`
-	 * or `RateLimit-Limit`. It represents the total quota allocated by the API
-	 * and typically remains constant across requests within the same window.
-	 */
-	lastKnownLimit: number | null;
-
-	/**
-	 * The timestamp (in milliseconds since Unix epoch) when the rate limit window resets.
-	 *
-	 * `null` if the reset time is not known or not applicable.
-	 *
-	 * @remarks
-	 * This value is extracted from response headers such as `X-RateLimit-Reset`
-	 * or `RateLimit-Reset`. The exact semantics depend on the API specification:
-	 *
-	 * - **Full window reset**: When the entire rate limit quota is restored
-	 * - **Next request availability**: When the next single request slot becomes available
-	 * - **Sliding window**: When the oldest request in the window expires
-	 *
-	 * Always refer to your API's documentation to understand the reset behavior.
-	 */
-	lastKnownResetAt: number | null;
-
-	/**
-	 * The timestamp (in milliseconds since Unix epoch) when the status was last synced with the server.
-	 *
-	 * `null` if the status has never been synced.
-	 */
-	lastSyncedAt: number | null;
-}