Files
Tom Moor eff1a43d9b fix: Keep serving requests when Redis is unavailable (#14457)
* fix: Fail fast on Redis for cache and rate limits, lock migrations in Postgres

* fix: Use the fail-fast Redis client for locks

* fix: Require a database pool of at least two connections

* chore: Rename cache Redis client to ephemeralClient
2026-11-03 08:45:56 -05:00

231 lines
7.1 KiB
TypeScript

import { createHash } from "crypto";
import type { IRateLimiterStoreOptions } from "rate-limiter-flexible";
import { RateLimiterRedis, RateLimiterMemory } from "rate-limiter-flexible";
import { toError } from "@shared/utils/error";
import env from "@server/env";
import Logger from "@server/logging/Logger";
import Redis from "@server/storage/redis";
/**
* Manages rate limiters for API endpoints, backed by Redis with an in-memory
* insurance limiter as a fallback.
*/
export default class RateLimiter {
constructor() {
throw Error(`Cannot instantiate class!`);
}
static readonly RATE_LIMITER_REDIS_KEY_PREFIX = "rl";
static readonly TOKEN_CACHE_KEY_PREFIX = "rl:tok:";
static readonly TOKEN_CACHE_TTL_SECONDS = 3600;
/** Distinguishes credential-derived identifiers from user ids and IPs. */
static readonly CREDENTIAL_IDENTIFIER_PREFIX = "cred:";
static readonly rateLimiterMap = new Map<string, RateLimiterRedis>();
static readonly insuranceRateLimiter = new RateLimiterMemory({
points: env.RATE_LIMITER_REQUESTS,
duration: env.RATE_LIMITER_DURATION_WINDOW,
});
private static _defaultRateLimiter: RateLimiterRedis | undefined;
/**
* The default rate limiter, used for any path without a specific limiter
* registered.
*/
static get defaultRateLimiter(): RateLimiterRedis {
if (!this._defaultRateLimiter) {
this._defaultRateLimiter = new RateLimiterRedis({
storeClient: Redis.ephemeralClient,
points: env.RATE_LIMITER_REQUESTS,
duration: env.RATE_LIMITER_DURATION_WINDOW,
keyPrefix: this.RATE_LIMITER_REDIS_KEY_PREFIX,
insuranceLimiter: this.insuranceRateLimiter,
});
}
return this._defaultRateLimiter;
}
/**
* Normalizes a request path into the key that identifies its rate limiter.
* The router matches paths case-insensitively and with an optional trailing
* slash, so every one of those variants must collapse onto a single key.
*
* @param path the request path to normalize.
* @returns the normalized path.
*/
static normalizePath(path: string): string {
const lowercased = path.toLowerCase();
return lowercased.length > 1 && lowercased.endsWith("/")
? lowercased.slice(0, -1)
: lowercased;
}
/**
* Returns the rate limiter registered for a path, falling back to the
* default rate limiter. The path is normalized before lookup.
*
* @param path the request path to look up.
* @returns the rate limiter for the path.
*/
static getRateLimiter(path: string): RateLimiterRedis {
return (
this.rateLimiterMap.get(this.normalizePath(path)) ||
this.defaultRateLimiter
);
}
/**
* Registers a rate limiter with a custom configuration for a path. The path
* is normalized before registration.
*
* @param path the request path to register the rate limiter for.
* @param config the rate limiter configuration.
*/
static setRateLimiter(path: string, config: IRateLimiterStoreOptions): void {
const rateLimiter = new RateLimiterRedis(config);
this.rateLimiterMap.set(this.normalizePath(path), rateLimiter);
}
/**
* Checks whether a custom rate limiter is registered for a path. The path is
* normalized before lookup.
*
* @param path the request path to check.
* @returns true if a custom rate limiter is registered.
*/
static hasRateLimiter(path: string): boolean {
return this.rateLimiterMap.has(this.normalizePath(path));
}
/**
* Derives a stable rate limiting identifier for a long-lived credential such
* as an API key or OAuth access token. The credential itself is never used
* as an identifier so that it does not reach the rate limiter store.
*
* @param token The credential presented on the request.
* @returns An identifier scoped to the credential.
*/
static identifierForCredential(token: string): string {
return `${this.CREDENTIAL_IDENTIFIER_PREFIX}${this.hashToken(token)}`;
}
/**
* Caches the user id associated with a verified authentication token so that
* subsequent requests can be keyed by user without re-validating the token.
* Errors are swallowed — a failed cache write just means the next request
* falls back to IP-based keying.
*
* @param token The authentication token that was just verified.
* @param userId The id of the user the token belongs to.
*/
static async cacheUserForToken(token: string, userId: string): Promise<void> {
try {
await Redis.ephemeralClient.set(
this.tokenCacheKey(token),
userId,
"EX",
this.TOKEN_CACHE_TTL_SECONDS
);
} catch (err) {
Logger.warn("Failed to cache user for rate limiter token", toError(err));
}
}
/**
* Looks up the cached user id for a previously verified token. Returns null
* on cache miss or Redis error.
*
* @param token The authentication token presented on the current request.
* @returns The associated user id, or null if unknown.
*/
static async getCachedUserIdForToken(token: string): Promise<string | null> {
try {
return await Redis.ephemeralClient.get(this.tokenCacheKey(token));
} catch (err) {
Logger.warn(
"Failed to read cached user for rate limiter token",
toError(err)
);
return null;
}
}
/**
* Removes the cached user id for a token, for example on logout so that a
* revoked token immediately stops keying rate limits per user.
*
* @param token The authentication token being invalidated.
*/
static async clearCachedToken(token: string): Promise<void> {
try {
await Redis.ephemeralClient.del(this.tokenCacheKey(token));
} catch (err) {
Logger.warn("Failed to clear cached rate limiter token", toError(err));
}
}
private static tokenCacheKey(token: string): string {
return `${this.TOKEN_CACHE_KEY_PREFIX}${this.hashToken(token)}`;
}
private static hashToken(token: string): string {
return createHash("sha256").update(token).digest("hex");
}
}
/**
* Reusable configuration for rate limiter middleware.
*/
export const RateLimiterStrategy = {
/** Allows five requests per minute, per IP address */
FivePerMinute: {
duration: 60,
requests: 5,
},
/** Allows ten requests per minute, per IP address */
TenPerMinute: {
duration: 60,
requests: 10,
},
/** Allows twenty five requests per minute, per IP address */
TwentyFivePerMinute: {
duration: 60,
requests: 25,
},
/** Allows one hundred requests per minute, per IP address */
OneHundredPerMinute: {
duration: 60,
requests: 100,
},
/** Allows one thousand requests per hour, per IP address */
OneThousandPerHour: {
duration: 3600,
requests: 1000,
},
/** Allows one hunred requests per hour, per IP address */
OneHundredPerHour: {
duration: 3600,
requests: 100,
},
/** Allows fifty requests per hour, per IP address */
FiftyPerHour: {
duration: 3600,
requests: 50,
},
/** Allows ten requests per hour, per IP address */
TenPerHour: {
duration: 3600,
requests: 10,
},
/** Allows five requests per hour, per IP address */
FivePerHour: {
duration: 3600,
requests: 5,
},
};