|
| 1 | +import Redis, { Cluster } from "ioredis"; |
| 2 | + |
| 3 | +/** |
| 4 | + * Options for configuring the RateLimiter. |
| 5 | + */ |
| 6 | +export interface GCRARateLimiterOptions { |
| 7 | + /** An instance of ioredis. */ |
| 8 | + redis: Redis | Cluster; |
| 9 | + /** |
| 10 | + * A string prefix to namespace keys in Redis. |
| 11 | + * Defaults to "ratelimit:". |
| 12 | + */ |
| 13 | + keyPrefix?: string; |
| 14 | + /** |
| 15 | + * The minimum interval between requests (the emission interval) in milliseconds. |
| 16 | + * For example, 1000 ms for one request per second. |
| 17 | + */ |
| 18 | + emissionInterval: number; |
| 19 | + /** |
| 20 | + * The burst tolerance in milliseconds. This represents how much “credit” can be |
| 21 | + * accumulated to allow short bursts beyond the average rate. |
| 22 | + * For example, if you want to allow 3 requests in a burst with an emission interval of 1000 ms, |
| 23 | + * you might set this to 3000. |
| 24 | + */ |
| 25 | + burstTolerance: number; |
| 26 | + /** |
| 27 | + * Expiration for the Redis key in milliseconds. |
| 28 | + * Defaults to the larger of 60 seconds or (emissionInterval + burstTolerance). |
| 29 | + */ |
| 30 | + keyExpiration?: number; |
| 31 | +} |
| 32 | + |
| 33 | +/** |
| 34 | + * The result of a rate limit check. |
| 35 | + */ |
| 36 | +export interface RateLimitResult { |
| 37 | + /** Whether the request is allowed. */ |
| 38 | + allowed: boolean; |
| 39 | + /** |
| 40 | + * If not allowed, this is the number of milliseconds the caller should wait |
| 41 | + * before retrying. |
| 42 | + */ |
| 43 | + retryAfter?: number; |
| 44 | +} |
| 45 | + |
| 46 | +/** |
| 47 | + * A rate limiter using Redis and the Generic Cell Rate Algorithm (GCRA). |
| 48 | + * |
| 49 | + * The GCRA is implemented using a Lua script that runs atomically in Redis. |
| 50 | + * |
| 51 | + * When a request comes in, the algorithm: |
| 52 | + * - Retrieves the current "Theoretical Arrival Time" (TAT) from Redis (or initializes it if missing). |
| 53 | + * - If the current time is greater than or equal to the TAT, the request is allowed and the TAT is updated to now + emissionInterval. |
| 54 | + * - Otherwise, if the current time plus the burst tolerance is at least the TAT, the request is allowed and the TAT is incremented. |
| 55 | + * - If neither condition is met, the request is rejected and a Retry-After value is returned. |
| 56 | + */ |
| 57 | +export class GCRARateLimiter { |
| 58 | + private redis: Redis | Cluster; |
| 59 | + private keyPrefix: string; |
| 60 | + private emissionInterval: number; |
| 61 | + private burstTolerance: number; |
| 62 | + private keyExpiration: number; |
| 63 | + |
| 64 | + constructor(options: GCRARateLimiterOptions) { |
| 65 | + this.redis = options.redis; |
| 66 | + this.keyPrefix = options.keyPrefix || "gcra:ratelimit:"; |
| 67 | + this.emissionInterval = options.emissionInterval; |
| 68 | + this.burstTolerance = options.burstTolerance; |
| 69 | + // Default expiration: at least 60 seconds or the sum of emissionInterval and burstTolerance |
| 70 | + this.keyExpiration = |
| 71 | + options.keyExpiration || Math.max(60_000, this.emissionInterval + this.burstTolerance); |
| 72 | + |
| 73 | + // Define a custom Redis command 'gcra' that implements the GCRA algorithm. |
| 74 | + // Using defineCommand ensures the Lua script is loaded once and run atomically. |
| 75 | + this.redis.defineCommand("gcra", { |
| 76 | + numberOfKeys: 1, |
| 77 | + lua: ` |
| 78 | +--[[ |
| 79 | + GCRA Lua script |
| 80 | + KEYS[1] - The rate limit key (e.g. "ratelimit:<identifier>") |
| 81 | + ARGV[1] - Current time in ms (number) |
| 82 | + ARGV[2] - Emission interval in ms (number) |
| 83 | + ARGV[3] - Burst tolerance in ms (number) |
| 84 | + ARGV[4] - Key expiration in ms (number) |
| 85 | + |
| 86 | + Returns: { allowedFlag, value } |
| 87 | + allowedFlag: 1 if allowed, 0 if rate-limited. |
| 88 | + value: 0 when allowed; if not allowed, the number of ms to wait. |
| 89 | +]]-- |
| 90 | +
|
| 91 | +local key = KEYS[1] |
| 92 | +local now = tonumber(ARGV[1]) |
| 93 | +local emission_interval = tonumber(ARGV[2]) |
| 94 | +local burst_tolerance = tonumber(ARGV[3]) |
| 95 | +local expire = tonumber(ARGV[4]) |
| 96 | +
|
| 97 | +-- Get the stored Theoretical Arrival Time (TAT) or default to 0. |
| 98 | +local tat = tonumber(redis.call("GET", key) or 0) |
| 99 | +if tat == 0 then |
| 100 | + tat = now |
| 101 | +end |
| 102 | +
|
| 103 | +local allowed, new_tat, retry_after |
| 104 | +
|
| 105 | +if now >= tat then |
| 106 | + -- No delay: request is on schedule. |
| 107 | + new_tat = now + emission_interval |
| 108 | + allowed = true |
| 109 | +elseif (now + burst_tolerance) >= tat then |
| 110 | + -- Within burst capacity: allow request. |
| 111 | + new_tat = tat + emission_interval |
| 112 | + allowed = true |
| 113 | +else |
| 114 | + -- Request exceeds the allowed burst; calculate wait time. |
| 115 | + allowed = false |
| 116 | + retry_after = tat - (now + burst_tolerance) |
| 117 | +end |
| 118 | +
|
| 119 | +if allowed then |
| 120 | + redis.call("SET", key, new_tat, "PX", expire) |
| 121 | + return {1, 0} |
| 122 | +else |
| 123 | + return {0, retry_after} |
| 124 | +end |
| 125 | +`, |
| 126 | + }); |
| 127 | + } |
| 128 | + |
| 129 | + /** |
| 130 | + * Checks whether a request associated with the given identifier is allowed. |
| 131 | + * |
| 132 | + * @param identifier A unique string identifying the subject of rate limiting (e.g. user ID, IP address, or domain). |
| 133 | + * @returns A promise that resolves to a RateLimitResult. |
| 134 | + * |
| 135 | + * @example |
| 136 | + * const result = await rateLimiter.check('user:12345'); |
| 137 | + * if (!result.allowed) { |
| 138 | + * // Tell the client to retry after result.retryAfter milliseconds. |
| 139 | + * } |
| 140 | + */ |
| 141 | + async check(identifier: string): Promise<RateLimitResult> { |
| 142 | + const key = `${this.keyPrefix}${identifier}`; |
| 143 | + const now = Date.now(); |
| 144 | + |
| 145 | + try { |
| 146 | + // Call the custom 'gcra' command. |
| 147 | + // The script returns an array: [allowedFlag, value] |
| 148 | + // - allowedFlag: 1 if allowed; 0 if rejected. |
| 149 | + // - value: 0 when allowed; if rejected, the number of ms to wait before retrying. |
| 150 | + // @ts-expect-error: The custom command is defined via defineCommand. |
| 151 | + const result: [number, number] = await this.redis.gcra( |
| 152 | + key, |
| 153 | + now, |
| 154 | + this.emissionInterval, |
| 155 | + this.burstTolerance, |
| 156 | + this.keyExpiration |
| 157 | + ); |
| 158 | + const allowed = result[0] === 1; |
| 159 | + if (allowed) { |
| 160 | + return { allowed: true }; |
| 161 | + } else { |
| 162 | + return { allowed: false, retryAfter: result[1] }; |
| 163 | + } |
| 164 | + } catch (error) { |
| 165 | + // In a production system you might log the error and either |
| 166 | + // allow the request (fail open) or deny it (fail closed). |
| 167 | + // Here we choose to propagate the error. |
| 168 | + throw error; |
| 169 | + } |
| 170 | + } |
| 171 | +} |
0 commit comments