@stimulcross/rate-limiter 0.0.1

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

@@ -0,0 +1,74 @@
+/**
+ * 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;
+}

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

@@ -0,0 +1,512 @@
+import { Priority } from '@stimulcross/ds-policy-priority-queue';
+import { createLogger, type Logger, LogLevel } from '@stimulcross/logger';
+import { type HttpLimitInfoExtractor } from './http-limit-info.extractor.js';
+import { type HttpLimitInfo } from './http-limit.info.js';
+import { type HttpResponseBasedLimiterOptions } from './http-response-based-limiter.options.js';
+import { type HttpResponseBasedLimiterState } from './http-response-based-limiter.state.js';
+import { type HttpResponseBasedLimiterStatus } from './http-response-based-limiter.status.js';
+import { type Clock } from '../../core/clock.js';
+import { type RateLimiter } from '../../core/rate-limiter.js';
+import { type StateStorage } from '../../core/state-storage.js';
+import { RateLimitErrorCode } from '../../enums/rate-limit-error-code.js';
+import { RateLimitError } from '../../errors/rate-limit.error.js';
+import { RateLimiterDestroyedError } from '../../errors/rate-limiter-destroyed.error.js';
+import { type IdGenerator, type KeyResolver } from '../../interfaces/rate-limiter-options.js';
+import { type RateLimiterRunOptions } from '../../interfaces/rate-limiter-run-options.js';
+import { defaultClock } from '../../runtime/default-clock.js';
+import { InMemoryStateStore } from '../../runtime/in-memory-state-store.js';
+import { RateLimiterExecutor } from '../../runtime/rate-limiter.executor.js';
+import { type LimitBehavior } from '../../types/limit-behavior.js';
+import { generateRandomString } from '../../utils/generate-random-string.js';
+import { sanitizeError } from '../../utils/sanitize-error.js';
+
+const TOO_MANY_REQUESTS_ERROR_CODE = 429;
+
+const enum TokenReservationAction {
+	Probe = 1,
+	Follow = 2,
+	Wait = 3,
+}
+
+interface RequestContext {
+	readonly id: string;
+	readonly key: string;
+	readonly signal?: AbortSignal;
+	startedAt: number;
+	isProbing: boolean;
+}
+
+/**
+ *  The options for single request execution.
+ */
+export type HttpHeadersLimiterRunOptions = Omit<RateLimiterRunOptions, 'cost'>;
+
+/**
+ * HTTP Response Based rate limiter.
+ *
+ * Designed for outbound requests to safely respect dynamic third-party API limits.
+ *
+ * This limiter synchronizes its internal state by extracting rate limit headers directly from the HTTP responses.
+ *
+ * Key features:
+ * - **Dynamic synchronization** - updates local capacity and reset schedules based on actual server responses
+ * - **Probing** - prevents 429 floods by pausing queued requests while a single "probe" fetches the latest limits
+ * - **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`
+ */
+export class HttpResponseBasedLimiter<TResponse> implements RateLimiter<HttpResponseBasedLimiterStatus> {
+	private readonly _logger: Logger;
+	private readonly _clock: Clock;
+	private readonly _store: StateStorage<HttpResponseBasedLimiterState>;
+	private readonly _executor: RateLimiterExecutor;
+
+	private readonly _pendingSyncs = new Map<string, { promise: Promise<void>; resolve: () => void }>();
+	private readonly _getStoreKey: KeyResolver;
+	private readonly _generateId: IdGenerator;
+	private readonly _extractLimitInfo: HttpLimitInfoExtractor<TResponse>;
+	private readonly _defaultLimitBehavior: LimitBehavior;
+	private readonly _maxWaitMs: number | undefined;
+	private readonly _fallbackResetDelayMs: number;
+
+	private _isDestroyed = false;
+
+	constructor(options: HttpResponseBasedLimiterOptions<TResponse>) {
+		this._logger = createLogger(new.target.name, { minLevel: 'WARNING', ...options.loggerOptions });
+		this._clock = options.clock ?? defaultClock;
+		this._store = options.store ?? new InMemoryStateStore<HttpResponseBasedLimiterState>(this._clock);
+		this._executor = new RateLimiterExecutor(this._logger, this._clock, options.queue);
+
+		this._getStoreKey =
+			typeof options.key === 'function'
+				? options.key
+				: (key?: string): string => (key ? `limiter:${key}` : 'limiter');
+		this._generateId = options.idGenerator ?? generateRandomString;
+
+		this._extractLimitInfo = options.limitInfoExtractor;
+		this._defaultLimitBehavior = options.limitBehavior ?? 'reject';
+		this._maxWaitMs = options.queue?.maxWaitMs;
+		this._fallbackResetDelayMs = options.fallbackResetDelayMs ?? 60_000;
+	}
+
+	public async getStatus(key?: string): Promise<HttpResponseBasedLimiterStatus> {
+		const storeKey = this._getStoreKey(key);
+		const state = await this._store.get(storeKey);
+
+		if (state?.isUnlimited) {
+			return {
+				isProbing: false,
+				isUnlimited: true,
+				lastKnownLimit: null,
+				lastKnownRemaining: null,
+				lastKnownResetAt: null,
+				lastSyncedAt: state.lastSyncedAt,
+			};
+		}
+
+		return {
+			isProbing: state?.isProbing ?? false,
+			isUnlimited: false,
+			lastKnownLimit: state?.lastKnownLimit ?? null,
+			lastKnownRemaining: state?.lastKnownRemaining ?? null,
+			lastKnownResetAt: state?.lastKnownResetAt ?? null,
+			lastSyncedAt: state?.lastSyncedAt ?? null,
+		};
+	}
+
+	public async run<T = TResponse>(fn: () => T | Promise<T>, options: HttpHeadersLimiterRunOptions = {}): Promise<T> {
+		const ctx: RequestContext = {
+			id: options.id ?? this._generateId(),
+			key: this._getStoreKey(options.key),
+			signal: options.signal,
+			startedAt: 0,
+			isProbing: false,
+		};
+
+		this._ensureCanExecute(ctx);
+
+		const { priority, limitBehavior, maxWaitMs } = options;
+		const finalLimitBehavior = limitBehavior ?? this._defaultLimitBehavior;
+		const finalMaxWaitMs = maxWaitMs ?? this._maxWaitMs;
+		const expiresAt = finalMaxWaitMs ? this._clock.now() + finalMaxWaitMs : undefined;
+
+		let currentRunAt = this._clock.now();
+
+		while (true) {
+			this._ensureCanExecute(ctx, priority);
+
+			if (ctx.signal?.aborted) {
+				throw new RateLimitError(RateLimitErrorCode.Cancelled);
+			}
+
+			try {
+				return await this._executor.execute<T>(() => this._executeSingleRequest<T>(fn, ctx), currentRunAt, {
+					id: ctx.id,
+					key: ctx.key,
+					expiresAt,
+					priority,
+					signal: ctx.signal,
+				});
+			} catch (e) {
+				if (e instanceof RateLimitError && e.code === RateLimitErrorCode.LimitExceeded) {
+					if (finalLimitBehavior === 'reject') {
+						throw e;
+					}
+
+					currentRunAt = e.retryAt ?? this._clock.now() + this._fallbackResetDelayMs;
+
+					this._shouldLogDebug &&
+						this._logger.debug(`[REQUEUE] [id: ${ctx.id}, key: ${ctx.key}] - Requeued to ${currentRunAt}`);
+
+					continue;
+				}
+
+				throw e;
+			}
+		}
+	}
+
+	public async clear(key?: string): Promise<void> {
+		this._executor.clear();
+		const storeKey = this._getStoreKey(key);
+
+		await this._store.acquireLock?.(storeKey);
+
+		try {
+			await this._store.delete(storeKey);
+		} finally {
+			await this._store.releaseLock?.(storeKey);
+		}
+	}
+
+	public async destroy(): Promise<void> {
+		if (this._isDestroyed) {
+			return;
+		}
+
+		this._isDestroyed = true;
+		this._executor.clear();
+
+		for (const pending of this._pendingSyncs.values()) {
+			pending.resolve();
+		}
+
+		this._pendingSyncs.clear();
+
+		await this._store.destroy?.();
+	}
+
+	private get _shouldLogDebug(): boolean {
+		return this._logger.minLevel >= LogLevel.DEBUG;
+	}
+
+	private async _executeSingleRequest<T>(fn: () => T | Promise<T>, ctx: RequestContext): Promise<T> {
+		while (true) {
+			await this._waitForSync(ctx);
+
+			ctx.startedAt = this._clock.now();
+			const action = await this._reserveLocalToken(ctx);
+
+			if (action === TokenReservationAction.Wait) {
+				continue;
+			}
+
+			ctx.isProbing = action === TokenReservationAction.Probe;
+			break;
+		}
+
+		try {
+			let response: TResponse | null = null;
+			let responseError: Error | null = null;
+
+			try {
+				response = (await fn()) as TResponse;
+			} catch (e) {
+				responseError = sanitizeError(e);
+			}
+
+			const extractFinishedAt = this._clock.now();
+			const limitInfo = this._extractLimitInfo(response, responseError, extractFinishedAt);
+
+			await this._processLimitHeaders(ctx, limitInfo, responseError, extractFinishedAt);
+
+			if (responseError) {
+				throw responseError;
+			}
+
+			return response as T;
+		} finally {
+			if (ctx.isProbing) {
+				this._resolvePendingSync(ctx);
+			}
+		}
+	}
+
+	private async _waitForSync(ctx: RequestContext): Promise<void> {
+		while (this._pendingSyncs.has(ctx.key)) {
+			if (ctx.signal?.aborted) {
+				throw new RateLimitError(RateLimitErrorCode.Cancelled);
+			}
+
+			const pending = this._pendingSyncs.get(ctx.key);
+
+			if (!pending) {
+				break;
+			}
+
+			this._shouldLogDebug &&
+				this._logger.debug(`[WAIT] [id: ${ctx.id}, key: ${ctx.key}] - Waiting for probe to sync state`);
+
+			await new Promise<void>((resolve, reject) => {
+				const onAbort = (): void => reject(new RateLimitError(RateLimitErrorCode.Cancelled));
+
+				if (ctx.signal) {
+					ctx.signal.addEventListener('abort', onAbort, { once: true });
+				}
+
+				void pending.promise.then(() => {
+					if (ctx.signal) {
+						ctx.signal.removeEventListener('abort', onAbort);
+					}
+
+					resolve();
+				});
+			});
+		}
+	}
+
+	private async _reserveLocalToken(ctx: RequestContext): Promise<TokenReservationAction> {
+		await this._store.acquireLock?.(ctx.key);
+
+		try {
+			const state = await this._store.get(ctx.key);
+
+			if (state?.isUnlimited) {
+				return TokenReservationAction.Follow;
+			}
+
+			const lastKnownRemaining = state?.lastKnownRemaining ?? null;
+			const lastKnownResetAt = state?.lastKnownResetAt ?? Infinity;
+			const lastKnownLimit = state?.lastKnownLimit ?? 1;
+
+			const hasLocalProbe = this._pendingSyncs.has(ctx.key);
+
+			if (!state || ctx.startedAt >= lastKnownResetAt) {
+				this._setupLocalProbeLock(ctx.key);
+
+				const probeState: HttpResponseBasedLimiterState = {
+					isProbing: true,
+					isUnlimited: false,
+					lastKnownLimit,
+					lastKnownRemaining: 0,
+					lastKnownResetAt: ctx.startedAt + this._fallbackResetDelayMs,
+					lastSyncedAt: ctx.startedAt,
+				};
+
+				await this._store.set(ctx.key, probeState, this._fallbackResetDelayMs);
+
+				this._shouldLogDebug &&
+					this._logger.debug(
+						`[PROBE] [id: ${ctx.id}, key: ${ctx.key}] - Probing API for limits - ${this._getDebugStateString(probeState)}`,
+					);
+
+				return TokenReservationAction.Probe;
+			}
+
+			if (state.isProbing) {
+				if (hasLocalProbe) {
+					return TokenReservationAction.Wait;
+				}
+
+				throw new RateLimitError(RateLimitErrorCode.LimitExceeded, lastKnownResetAt);
+			}
+
+			if (lastKnownRemaining !== null && lastKnownRemaining <= 0) {
+				throw new RateLimitError(RateLimitErrorCode.LimitExceeded, lastKnownResetAt);
+			}
+
+			const newState: HttpResponseBasedLimiterState = {
+				isProbing: false,
+				isUnlimited: state.isUnlimited,
+				lastKnownLimit,
+				lastKnownRemaining: (lastKnownRemaining ?? 1) - 1,
+				lastKnownResetAt,
+				lastSyncedAt: state.lastSyncedAt,
+			};
+
+			const ttl = Math.max(1000, lastKnownResetAt - ctx.startedAt);
+			await this._store.set(ctx.key, newState, ttl);
+
+			this._shouldLogDebug &&
+				this._logger.debug(
+					`[RSRV] [id: ${ctx.id}, key: ${ctx.key}] - Local state - ${this._getDebugStateString(newState)}`,
+				);
+
+			return TokenReservationAction.Follow;
+		} finally {
+			await this._store.releaseLock?.(ctx.key);
+		}
+	}
+
+	private _setupLocalProbeLock(key: string): void {
+		if (!this._pendingSyncs.has(key)) {
+			let resolveSync!: () => void;
+
+			const promise = new Promise<void>(resolve => {
+				resolveSync = resolve;
+			});
+
+			this._pendingSyncs.set(key, { promise, resolve: resolveSync });
+		}
+	}
+
+	private _resolvePendingSync(ctx: RequestContext): void {
+		const pending = this._pendingSyncs.get(ctx.key);
+
+		if (pending) {
+			this._shouldLogDebug && this._logger.debug(`[UNLOCK] [id: ${ctx.id}, key: ${ctx.key}] - Probing completed`);
+
+			pending.resolve();
+			this._pendingSyncs.delete(ctx.key);
+		}
+	}
+
+	private async _processLimitHeaders(
+		ctx: RequestContext,
+		limitInfo: HttpLimitInfo | null,
+		responseError: Error | null,
+		extractFinishedAt: number,
+	): Promise<void> {
+		if (limitInfo) {
+			await this._syncStateWithServer(ctx, limitInfo, extractFinishedAt);
+
+			if (limitInfo.statusCode === TOO_MANY_REQUESTS_ERROR_CODE) {
+				const resetAt = limitInfo.resetAt ?? 0;
+				const retryAt = extractFinishedAt >= resetAt ? extractFinishedAt + this._fallbackResetDelayMs : resetAt;
+
+				throw new RateLimitError(RateLimitErrorCode.LimitExceeded, retryAt);
+			}
+		} else if (responseError) {
+			if (ctx.isProbing) {
+				await this._rollbackProbingState(ctx);
+			}
+		} else {
+			await this._setUnlimited(ctx, extractFinishedAt);
+		}
+	}
+
+	private async _rollbackProbingState(ctx: RequestContext): Promise<void> {
+		await this._store.acquireLock?.(ctx.key);
+
+		try {
+			const state = await this._store.get(ctx.key);
+
+			if (state?.isProbing) {
+				await this._store.delete(ctx.key);
+
+				this._shouldLogDebug &&
+					this._logger.debug(
+						`[ROLLBACK] [id: ${ctx.id}, key: ${ctx.key}] - Probing failed, state cleared for next follower`,
+					);
+			}
+		} finally {
+			await this._store.releaseLock?.(ctx.key);
+		}
+	}
+
+	private async _syncStateWithServer(ctx: RequestContext, info: Partial<HttpLimitInfo>, now: number): Promise<void> {
+		await this._store.acquireLock?.(ctx.key);
+
+		try {
+			const currentState = await this._store.get(ctx.key);
+
+			if (currentState && (currentState.lastSyncedAt ?? 0) > ctx.startedAt) {
+				this._shouldLogDebug &&
+					this._logger.trace(
+						`[SYNC SKIP] [id: ${ctx.id}, key: ${ctx.key}] - Newer request already updated state - ${this._getDebugStateString(currentState)}`,
+					);
+				return;
+			}
+
+			const actualResetAt =
+				info.resetAt ??
+				(currentState?.isProbing ? undefined : currentState?.lastKnownResetAt) ??
+				now + this._fallbackResetDelayMs;
+			const isExhausted = info.statusCode === TOO_MANY_REQUESTS_ERROR_CODE || info.remaining === 0;
+
+			const newState: HttpResponseBasedLimiterState = {
+				isProbing: false,
+				isUnlimited: false,
+				lastKnownLimit: info.limit ?? currentState?.lastKnownLimit ?? 1,
+				lastKnownRemaining: isExhausted ? 0 : (info.remaining ?? currentState?.lastKnownRemaining ?? 1),
+				lastKnownResetAt: actualResetAt,
+				lastSyncedAt: ctx.startedAt,
+			};
+
+			const ttl = Math.max(1000, actualResetAt - now + 60_000);
+			await this._store.set(ctx.key, newState, ttl);
+
+			this._shouldLogDebug &&
+				this._logger.debug(`[SYNC] [id: ${ctx.id}, key: ${ctx.key}] - ${this._getDebugStateString(newState)}`);
+		} catch (e) {
+			this._logger.error(`[ERR] [id: ${ctx.id}, key: ${ctx.key}] - Failed to sync state with server limits}`, e);
+		} finally {
+			await this._store.releaseLock?.(ctx.key);
+		}
+	}
+
+	private async _setUnlimited(ctx: RequestContext, now: number): Promise<void> {
+		await this._store.acquireLock?.(ctx.key);
+
+		try {
+			const currentState = await this._store.get(ctx.key);
+
+			if (currentState && (currentState.lastSyncedAt ?? 0) > ctx.startedAt) {
+				this._shouldLogDebug &&
+					this._logger.debug(
+						`[SYNC SKIP] [id: ${ctx.id}, key: ${ctx.key}] - Newer request already updated state - ${this._getDebugStateString(currentState)}`,
+					);
+				return;
+			}
+
+			const ttl = this._fallbackResetDelayMs;
+			const unlimitedState: HttpResponseBasedLimiterState = {
+				isProbing: false,
+				isUnlimited: true,
+				lastKnownLimit: null,
+				lastKnownRemaining: null,
+				lastKnownResetAt: now + ttl,
+				lastSyncedAt: ctx.startedAt,
+			};
+			await this._store.set(ctx.key, unlimitedState, ttl);
+
+			this._shouldLogDebug &&
+				this._logger.debug(
+					`[UNLM] [id: ${ctx.id}, key: ${ctx.key}] - Set to unlimited - ${this._getDebugStateString(unlimitedState)}`,
+				);
+		} finally {
+			await this._store.releaseLock?.(ctx.key);
+		}
+	}
+
+	private _ensureCanExecute(ctx: RequestContext, priority?: Priority): void {
+		if (this._isDestroyed) {
+			throw new RateLimiterDestroyedError();
+		}
+
+		if (this._executor.isQueueFull) {
+			this._shouldLogDebug &&
+				this._logger.debug(
+					`[DROP OVERFLOW] [id: ${ctx.id}, key: ${ctx.key}] - prt: ${priority ?? Priority.Normal} | q: ${this._executor.queueSize}/${this._executor.queueCapacity}`,
+				);
+
+			throw new RateLimitError(RateLimitErrorCode.QueueOverflow);
+		}
+	}
+
+	private _getDebugStateString(state: HttpResponseBasedLimiterState): string {
+		return `probe: ${state.isProbing}, unl: ${state.isUnlimited}, lim: ${state.lastKnownLimit}, rem: ${state.lastKnownRemaining}, rst: ${state.lastKnownResetAt}, sync: ${state.lastSyncedAt}`;
+	}
+}

package/src/limiters/http-response-based/index.ts

@@ -0,0 +1,6 @@
+export type { HttpResponseBasedLimiterState } from './http-response-based-limiter.state.js';
+export type { HttpResponseBasedLimiterStatus } from './http-response-based-limiter.status.js';
+export type { HttpResponseBasedLimiterOptions } from './http-response-based-limiter.options.js';
+export type { HttpLimitInfo } from './http-limit.info.js';
+export type { HttpLimitInfoExtractor } from './http-limit-info.extractor.js';
+export { type HttpHeadersLimiterRunOptions, HttpResponseBasedLimiter } from './http-response-based.limiter.js';

package/src/limiters/leaky-bucket/index.ts

@@ -0,0 +1,4 @@
+export type { LeakyBucketState } from './leaky-bucket.state.js';
+export type { LeakyBucketStatus } from './leaky-bucket.status.js';
+export type { LeakyBucketOptions } from './leaky-bucket.options.js';
+export { LeakyBucketLimiter } from './leaky-bucket.limiter.js';

package/src/limiters/leaky-bucket/leaky-bucket.limiter.ts

@@ -0,0 +1,105 @@
+import { LogLevel } from '@stimulcross/logger';
+import { type LeakyBucketOptions } from './leaky-bucket.options.js';
+import { LeakyBucketPolicy } from './leaky-bucket.policy.js';
+import { type LeakyBucketState } from './leaky-bucket.state.js';
+import { type LeakyBucketStatus } from './leaky-bucket.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';
+import { AbstractRateLimiter, type ExecutionContext } from '../abstract-rate-limiter.js';
+
+/**
+ * Leaky Bucket 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 LeakyBucketLimiter extends AbstractRateLimiter<LeakyBucketState, LeakyBucketStatus> {
+	private readonly _defaultLimitBehaviour: LimitBehavior;
+	private readonly _maxWaitMs: number | undefined;
+
+	protected override readonly _policy: LeakyBucketPolicy;
+
+	constructor(options: LeakyBucketOptions) {
+		super(options);
+
+		this._defaultLimitBehaviour = options.limitBehavior ?? 'reject';
+
+		if (options.queue?.maxWaitMs) {
+			this._maxWaitMs = options.queue.maxWaitMs;
+		}
+
+		this._policy = new LeakyBucketPolicy(options.capacity, options.leakRate);
+	}
+
+	protected override async _runInternal<T>(fn: () => T | Promise<T>, ctx: ExecutionContext): Promise<T> {
+		const now = this._clock.now();
+		const baseTtlMs = Math.ceil(this._policy.capacity / (this._policy.leakRate / 1000));
+
+		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._printDebug(decision, nextState, now, ctx);
+		} finally {
+			await this._store.releaseLock?.(ctx.key);
+		}
+
+		const finalMaxWaitMs = ctx.maxWaitMs ?? this._maxWaitMs;
+		const expiresAt = finalMaxWaitMs ? now + finalMaxWaitMs : undefined;
+
+		return await this._execute(fn, runAt, storeTtlMs, ctx, expiresAt);
+	}
+
+	protected override _getDebugStateString(state: LeakyBucketState): string {
+		return `lvl: ${state.level.toFixed(2)}/${this._policy.capacity}`;
+	}
+
+	private _printDebug(decision: Decision, nextState: LeakyBucketState, now: number, ctx: ExecutionContext): void {
+		if (this._logger.minLevel < LogLevel.DEBUG) {
+			return;
+		}
+
+		const debugStateString = `lvl: ${nextState.level.toFixed(2)}/${this._policy.capacity}`;
+
+		if (decision.kind === 'delay') {
+			this._logger.debug(
+				`[DELAY] [id: ${ctx.id}, key: ${ctx.key}] +${decision.runAt - now}ms - ${debugStateString}`,
+			);
+		} else {
+			this._logger.debug(`[ALLOW] [id: ${ctx.id}, key: ${ctx.key}] - ${debugStateString} `);
+		}
+	}
+}