Skip to content

Open-source status page, incident response and uptime monitoring

chore: web checker ratelimit tier (#2579)

Maximilian Kaske444a06b851fc
diff --git a/apps/web/src/app/(landing)/play/cdn-checker/api/route.ts b/apps/web/src/app/(landing)/play/cdn-checker/api/route.ts
index 8381fdd5d..d529001cb 100644
--- a/apps/web/src/app/(landing)/play/cdn-checker/api/route.ts
+++ b/apps/web/src/app/(landing)/play/cdn-checker/api/route.ts
@@ -6,14 +6,16 @@ import { z } from "zod";
import { devProbeCdnRegion } from "@/lib/cdn-checker/dev-probe";
import { validateCdnUrl } from "@/lib/cdn-checker/guards";
import { probeCdnRegion } from "@/lib/cdn-checker/probe";
-import {
- MAX_REQUESTS_PER_WINDOW,
- RATE_LIMIT_WINDOW,
- rateLimitCdnRequest,
- rateLimitHeaders,
-} from "@/lib/cdn-checker/ratelimit";
import type { CdnRegionResponse } from "@/lib/cdn-checker/schema";
import { computeCdnSummary } from "@/lib/cdn-checker/summary";
+import {
+ PLAY_RATE_LIMIT_TIERS,
+ getClientIP,
+ rateLimitMessage,
+ ratelimitTiers,
+ retryAfterHeader,
+ tieredRateLimitHeaders,
+} from "@/lib/ratelimit";
import { iteratorToStream, yieldMany } from "@/lib/stream";
export const runtime = "edge";
@@ -95,24 +97,26 @@ export async function POST(request: Request) {
return errorResponse("INVALID_REQUEST", guard.error, guard.status);
}
- const rl = await rateLimitCdnRequest("play-cdn", request.headers);
- if (rl.status === "no-client-ip") {
+ const clientIP = getClientIP(request.headers);
+ if (!clientIP) {
return errorResponse(
"NO_CLIENT_IP",
"Unable to determine client IP address",
400,
);
}
- if (rl.status === "limited") {
+
+ const rl = await ratelimitTiers(
+ `play-cdn:${clientIP}`,
+ PLAY_RATE_LIMIT_TIERS,
+ );
+ if (!rl.success) {
return errorResponse(
"RATE_LIMIT_EXCEEDED",
- `You have exceeded the rate limit of ${MAX_REQUESTS_PER_WINDOW} requests per ${RATE_LIMIT_WINDOW} seconds`,
+ rateLimitMessage(rl.tier),
429,
{ limit: rl.limit, remaining: rl.remaining, reset: rl.reset },
- {
- ...rateLimitHeaders(rl),
- "Retry-After": Math.ceil((rl.reset - Date.now()) / 1000).toString(),
- },
+ { ...tieredRateLimitHeaders(rl), ...retryAfterHeader(rl) },
);
}
@@ -134,7 +138,7 @@ export async function POST(request: Request) {
headers: {
"Content-Type": "application/x-ndjson",
"Cache-Control": "no-store",
- ...rateLimitHeaders(rl),
+ ...tieredRateLimitHeaders(rl),
},
});
}
diff --git a/apps/web/src/app/(landing)/play/checker/api/route.ts b/apps/web/src/app/(landing)/play/checker/api/route.ts
index 14230857e..13ba62af3 100644
--- a/apps/web/src/app/(landing)/play/checker/api/route.ts
+++ b/apps/web/src/app/(landing)/play/checker/api/route.ts
@@ -11,15 +11,19 @@ import {
storeBaseCheckerData,
storeCheckerData,
} from "../../../../../lib/checker/utils";
-import { getClientIP, ratelimit } from "../../../../../lib/ratelimit";
+import {
+ PLAY_RATE_LIMIT_TIERS,
+ getClientIP,
+ rateLimitMessage,
+ ratelimitTiers,
+ retryAfterHeader,
+ tieredRateLimitHeaders,
+} from "../../../../../lib/ratelimit";
import { iteratorToStream, yieldMany } from "../../../../../lib/stream";
import { wait } from "../../../../../lib/utils";
export const runtime = "edge";
-const RATE_LIMIT_WINDOW = 60; // 60 seconds
-const MAX_REQUESTS_PER_WINDOW = 3;
-
// Request schema validation
const playCheckerRequestSchema = z.object({
url: z.url("Invalid URL format"),
@@ -218,15 +222,15 @@ export async function POST(request: Request) {
);
}
- const rateLimitResult = await ratelimit(`play-checker:${clientIP}`, {
- window: RATE_LIMIT_WINDOW,
- limit: MAX_REQUESTS_PER_WINDOW,
- });
+ const rateLimitResult = await ratelimitTiers(
+ `play-checker:${clientIP}`,
+ PLAY_RATE_LIMIT_TIERS,
+ );
if (!rateLimitResult.success) {
return createErrorResponse(
"RATE_LIMIT_EXCEEDED",
- `You have exceeded the rate limit of ${MAX_REQUESTS_PER_WINDOW} requests per ${RATE_LIMIT_WINDOW} seconds`,
+ rateLimitMessage(rateLimitResult.tier),
429,
{
limit: rateLimitResult.limit,
@@ -234,12 +238,8 @@ export async function POST(request: Request) {
reset: rateLimitResult.reset,
},
{
- "X-RateLimit-Limit": rateLimitResult.limit.toString(),
- "X-RateLimit-Remaining": rateLimitResult.remaining.toString(),
- "X-RateLimit-Reset": rateLimitResult.reset.toString(),
- "Retry-After": Math.ceil(
- (rateLimitResult.reset - Date.now()) / 1000,
- ).toString(),
+ ...tieredRateLimitHeaders(rateLimitResult),
+ ...retryAfterHeader(rateLimitResult),
},
);
}
@@ -261,10 +261,6 @@ export async function POST(request: Request) {
});
const stream = iteratorToStream(iterator);
return new Response(stream, {
- headers: {
- "X-RateLimit-Limit": rateLimitResult.limit.toString(),
- "X-RateLimit-Remaining": rateLimitResult.remaining.toString(),
- "X-RateLimit-Reset": rateLimitResult.reset.toString(),
- },
+ headers: tieredRateLimitHeaders(rateLimitResult),
});
}
diff --git a/apps/web/src/app/(landing)/play/mcp-health/api/route.ts b/apps/web/src/app/(landing)/play/mcp-health/api/route.ts
index 71ced0d50..1332df096 100644
--- a/apps/web/src/app/(landing)/play/mcp-health/api/route.ts
+++ b/apps/web/src/app/(landing)/play/mcp-health/api/route.ts
@@ -10,15 +10,19 @@ import {
storeHealthReport,
toPersistedReport,
} from "../../../../../lib/mcp/health-check";
-import { getClientIP, ratelimit } from "../../../../../lib/ratelimit";
+import {
+ PLAY_RATE_LIMIT_TIERS,
+ getClientIP,
+ rateLimitMessage,
+ ratelimitTiers,
+ retryAfterHeader,
+ tieredRateLimitHeaders,
+} from "../../../../../lib/ratelimit";
export const runtime = "edge";
// Worst-case 16s of step time + metadata fetch + analytics; give some slack.
export const maxDuration = 30;
-const RATE_LIMIT_WINDOW = 60;
-const MAX_REQUESTS_PER_WINDOW = 3;
-
const requestSchema = z.object({
url: z.url("Invalid URL format"),
headers: z
@@ -124,22 +128,17 @@ export async function POST(request: Request) {
);
}
- const rl = await ratelimit(`play-mcp-health:${clientIP}`, {
- window: RATE_LIMIT_WINDOW,
- limit: MAX_REQUESTS_PER_WINDOW,
- });
+ const rl = await ratelimitTiers(
+ `play-mcp-health:${clientIP}`,
+ PLAY_RATE_LIMIT_TIERS,
+ );
if (!rl.success) {
return errorResponse(
"RATE_LIMIT_EXCEEDED",
- `You have exceeded the rate limit of ${MAX_REQUESTS_PER_WINDOW} requests per ${RATE_LIMIT_WINDOW} seconds`,
+ rateLimitMessage(rl.tier),
429,
{ limit: rl.limit, remaining: rl.remaining, reset: rl.reset },
- {
- "X-RateLimit-Limit": rl.limit.toString(),
- "X-RateLimit-Remaining": rl.remaining.toString(),
- "X-RateLimit-Reset": rl.reset.toString(),
- "Retry-After": Math.ceil((rl.reset - Date.now()) / 1000).toString(),
- },
+ { ...tieredRateLimitHeaders(rl), ...retryAfterHeader(rl) },
);
}
@@ -183,12 +182,6 @@ export async function POST(request: Request) {
return Response.json(
{ id, report: persisted },
- {
- headers: {
- "X-RateLimit-Limit": rl.limit.toString(),
- "X-RateLimit-Remaining": rl.remaining.toString(),
- "X-RateLimit-Reset": rl.reset.toString(),
- },
- },
+ { headers: tieredRateLimitHeaders(rl) },
);
}
diff --git a/apps/web/src/lib/cdn-checker/ratelimit.ts b/apps/web/src/lib/cdn-checker/ratelimit.ts
deleted file mode 100644
index 71c70959b..000000000
--- a/apps/web/src/lib/cdn-checker/ratelimit.ts
+++ /dev/null
@@ -1,47 +0,0 @@
-export const RATE_LIMIT_WINDOW = 60;
-export const MAX_REQUESTS_PER_WINDOW = 3;
-
-type CdnRateLimit =
- | { status: "skipped" }
- | { status: "no-client-ip" }
- | {
- status: "ok" | "limited";
- limit: number;
- remaining: number;
- reset: number;
- };
-
-// dev runs without Upstash credentials and the redis client throws at module
-// evaluation, so the limiter is only imported (and enforced) in production
-export async function rateLimitCdnRequest(
- prefix: string,
- headers: Headers,
-): Promise<CdnRateLimit> {
- if (process.env.NODE_ENV !== "production") return { status: "skipped" };
-
- const { getClientIP, ratelimit } = await import("@/lib/ratelimit");
-
- const clientIP = getClientIP(headers);
- if (!clientIP) return { status: "no-client-ip" };
-
- const rl = await ratelimit(`${prefix}:${clientIP}`, {
- window: RATE_LIMIT_WINDOW,
- limit: MAX_REQUESTS_PER_WINDOW,
- });
-
- return {
- status: rl.success ? "ok" : "limited",
- limit: rl.limit,
- remaining: rl.remaining,
- reset: rl.reset,
- };
-}
-
-export function rateLimitHeaders(rl: CdnRateLimit): Record<string, string> {
- if (rl.status !== "ok" && rl.status !== "limited") return {};
- return {
- "X-RateLimit-Limit": rl.limit.toString(),
- "X-RateLimit-Remaining": rl.remaining.toString(),
- "X-RateLimit-Reset": rl.reset.toString(),
- };
-}
diff --git a/apps/web/src/lib/ratelimit-config.test.ts b/apps/web/src/lib/ratelimit-config.test.ts
new file mode 100644
index 000000000..d5ce55db4
--- /dev/null
+++ b/apps/web/src/lib/ratelimit-config.test.ts
@@ -0,0 +1,133 @@
+import { expect } from "@std/expect";
+import { describe, test } from "@std/testing/bdd";
+
+import {
+ PLAY_RATE_LIMIT_TIERS,
+ parseTieredResult,
+ rateLimitMessage,
+ retryAfterHeader,
+ tieredRateLimitHeaders,
+ tightestTierIndex,
+} from "./ratelimit-config";
+
+const [BURST, SUSTAINED] = PLAY_RATE_LIMIT_TIERS;
+const NOW = 1_760_000_000_000;
+
+/** Reply shape of RATELIMIT_TIERS_SCRIPT for the two play tiers. */
+function reply(
+ blocked: number,
+ counts: [number, number],
+ ttls: [number, number],
+) {
+ return [blocked, ...counts, ...ttls];
+}
+
+describe("parseTieredResult", () => {
+ test("admits a first request and reports the burst tier", () => {
+ const result = parseTieredResult(
+ PLAY_RATE_LIMIT_TIERS,
+ reply(0, [1, 1], [60, 3600]),
+ NOW,
+ );
+ expect(result.success).toBe(true);
+ expect(result.tier).toEqual(BURST);
+ expect(result.remaining).toBe(2);
+ expect(result.reset).toBe(NOW + 60_000);
+ });
+
+ test("reports the sustained tier once it has the least headroom", () => {
+ const result = parseTieredResult(
+ PLAY_RATE_LIMIT_TIERS,
+ reply(0, [1, 9], [58, 1200]),
+ NOW,
+ );
+ expect(result.success).toBe(true);
+ expect(result.tier).toEqual(SUSTAINED);
+ expect(result.remaining).toBe(1);
+ expect(result.reset).toBe(NOW + 1_200_000);
+ });
+
+ test("surfaces the burst tier when it is what blocked", () => {
+ const result = parseTieredResult(
+ PLAY_RATE_LIMIT_TIERS,
+ reply(1, [3, 3], [42, 3400]),
+ NOW,
+ );
+ expect(result.success).toBe(false);
+ expect(result.tier).toEqual(BURST);
+ expect(result.limit).toBe(3);
+ expect(result.remaining).toBe(0);
+ expect(result.reset).toBe(NOW + 42_000);
+ });
+
+ // the case that motivated the tiers: paced automation never trips the burst
+ // tier, so only the sustained tier can stop it
+ test("surfaces the sustained tier when paced automation is blocked", () => {
+ const result = parseTieredResult(
+ PLAY_RATE_LIMIT_TIERS,
+ reply(2, [1, 10], [30, 2400]),
+ NOW,
+ );
+ expect(result.success).toBe(false);
+ expect(result.tier).toEqual(SUSTAINED);
+ expect(result.limit).toBe(10);
+ expect(result.reset).toBe(NOW + 2_400_000);
+ });
+
+ test("falls back to a full window when redis reports no ttl", () => {
+ const blocked = parseTieredResult(
+ PLAY_RATE_LIMIT_TIERS,
+ reply(1, [3, 3], [-1, -2]),
+ NOW,
+ );
+ expect(blocked.reset).toBe(NOW + BURST.window * 1000);
+ });
+});
+
+describe("tightestTierIndex", () => {
+ test("reports the burst tier while it is the binding constraint", () => {
+ expect(tightestTierIndex(PLAY_RATE_LIMIT_TIERS, [2, 4])).toBe(0);
+ });
+
+ test("reports the sustained tier once it has the least headroom", () => {
+ expect(tightestTierIndex(PLAY_RATE_LIMIT_TIERS, [1, 10])).toBe(1);
+ });
+});
+
+describe("rateLimitMessage", () => {
+ test("names the window that tripped", () => {
+ expect(rateLimitMessage(BURST)).toBe(
+ "You have exceeded the rate limit of 3 requests per minute",
+ );
+ expect(rateLimitMessage(SUSTAINED)).toBe(
+ "You have exceeded the rate limit of 10 requests per hour",
+ );
+ });
+});
+
+describe("tieredRateLimitHeaders", () => {
+ test("emits the reset as unix seconds, not the ms epoch", () => {
+ const headers = tieredRateLimitHeaders({
+ limit: 3,
+ remaining: 0,
+ reset: NOW,
+ });
+ expect(headers["X-RateLimit-Reset"]).toBe("1760000000");
+ });
+});
+
+describe("retryAfterHeader", () => {
+ test("is at least one second even when the reset is in the past", () => {
+ expect(retryAfterHeader({ reset: Date.now() - 5_000 })["Retry-After"]).toBe(
+ "1",
+ );
+ });
+
+ test("rounds up to the remaining seconds", () => {
+ const header = retryAfterHeader({ reset: Date.now() + 42_400 })[
+ "Retry-After"
+ ];
+ expect(Number(header)).toBeGreaterThan(41);
+ expect(Number(header)).toBeLessThanOrEqual(43);
+ });
+});
diff --git a/apps/web/src/lib/ratelimit-config.ts b/apps/web/src/lib/ratelimit-config.ts
new file mode 100644
index 000000000..31d066ec2
--- /dev/null
+++ b/apps/web/src/lib/ratelimit-config.ts
@@ -0,0 +1,112 @@
+// redis-free half of the limiter: importable from modules that must not
+// evaluate the upstash client (it throws without credentials in dev)
+
+export interface RateLimitTier {
+ name: string; // part of the redis key, must be stable
+ window: number; // in seconds
+ limit: number; // max requests per window
+}
+
+export interface TieredRateLimitResult {
+ success: boolean;
+ limit: number;
+ remaining: number;
+ reset: number; // timestamp when the window resets
+ tier: RateLimitTier; // the tier that blocked, or the one closest to its limit
+}
+
+/**
+ * Shared tiers for the public /play tools. The burst tier stops hammering, the
+ * sustained tier stops automation that paces itself just under the burst limit.
+ */
+export const PLAY_RATE_LIMIT_TIERS: RateLimitTier[] = [
+ { name: "burst", window: 60, limit: 3 },
+ { name: "sustained", window: 3600, limit: 10 },
+];
+
+/** Index of the tier with the least headroom left, so headers report the real cap. */
+export function tightestTierIndex(
+ tiers: RateLimitTier[],
+ counts: number[],
+): number {
+ let tightest = 0;
+ for (let i = 1; i < tiers.length; i++) {
+ if (tiers[i].limit - counts[i] < tiers[tightest].limit - counts[tightest]) {
+ tightest = i;
+ }
+ }
+ return tightest;
+}
+
+/**
+ * Decode the flat reply of RATELIMIT_TIERS_SCRIPT:
+ * [blocked (1-based, 0 = admitted), ...counts, ...ttls]
+ */
+export function parseTieredResult(
+ tiers: RateLimitTier[],
+ reply: number[],
+ now: number,
+): TieredRateLimitResult {
+ const counts = reply.slice(1, 1 + tiers.length);
+ const ttls = reply.slice(1 + tiers.length, 1 + tiers.length * 2);
+
+ // TTL replies -1 (no expiry) and -2 (no key); fall back to a full window
+ const resetOf = (i: number) =>
+ now + (ttls[i] > 0 ? ttls[i] * 1000 : tiers[i].window * 1000);
+
+ const blocked = reply[0];
+ if (blocked > 0) {
+ const i = blocked - 1;
+ return {
+ success: false,
+ limit: tiers[i].limit,
+ remaining: 0,
+ reset: resetOf(i),
+ tier: tiers[i],
+ };
+ }
+
+ const i = tightestTierIndex(tiers, counts);
+ return {
+ success: true,
+ limit: tiers[i].limit,
+ remaining: Math.max(0, tiers[i].limit - counts[i]),
+ reset: resetOf(i),
+ tier: tiers[i],
+ };
+}
+
+function formatWindow(seconds: number): string {
+ if (seconds === 60) return "minute";
+ if (seconds === 3600) return "hour";
+ if (seconds === 86400) return "day";
+ return `${seconds} seconds`;
+}
+
+export function rateLimitMessage(tier: RateLimitTier): string {
+ return `You have exceeded the rate limit of ${tier.limit} requests per ${formatWindow(tier.window)}`;
+}
+
+export function tieredRateLimitHeaders(result: {
+ limit: number;
+ remaining: number;
+ reset: number; // ms epoch
+}): Record<string, string> {
+ return {
+ "X-RateLimit-Limit": result.limit.toString(),
+ "X-RateLimit-Remaining": result.remaining.toString(),
+ // the header convention is unix seconds, unlike the ms epoch we pass around
+ "X-RateLimit-Reset": Math.ceil(result.reset / 1000).toString(),
+ };
+}
+
+export function retryAfterHeader(result: {
+ reset: number;
+}): Record<string, string> {
+ return {
+ "Retry-After": Math.max(
+ 1,
+ Math.ceil((result.reset - Date.now()) / 1000),
+ ).toString(),
+ };
+}
diff --git a/apps/web/src/lib/ratelimit.ts b/apps/web/src/lib/ratelimit.ts
index 35e9ac8d3..bae5c3337 100644
--- a/apps/web/src/lib/ratelimit.ts
+++ b/apps/web/src/lib/ratelimit.ts
@@ -1,4 +1,17 @@
-import { redis } from "@openstatus/upstash";
+import {
+ type RateLimitTier,
+ type TieredRateLimitResult,
+ parseTieredResult,
+} from "@/lib/ratelimit-config";
+
+export * from "@/lib/ratelimit-config";
+
+// @openstatus/upstash builds its client at module scope and throws without
+// credentials, so it is loaded lazily to keep this module importable in dev
+async function getRedis() {
+ const { redis } = await import("@openstatus/upstash");
+ return redis;
+}
interface RateLimitConfig {
window: number; // in seconds
@@ -24,6 +37,7 @@ export async function ratelimit(
): Promise<RateLimitResult> {
const key = `ratelimit:${identifier}`;
const now = Date.now();
+ const redis = await getRedis();
// Increment the counter
const count = await redis.incr(key);
@@ -48,6 +62,84 @@ export async function ratelimit(
};
}
+/**
+ * Admission must be atomic: checking counters and then incrementing in a second
+ * round trip lets concurrent requests all observe room and all pass. Consuming
+ * only when every tier has room is what keeps a rejected request from burning
+ * quota in the tiers that were still under their limit.
+ *
+ * KEYS: one per tier. ARGV: limit, window per tier.
+ * Reply: [blocked (1-based, 0 = admitted), ...counts, ...ttls]
+ */
+const RATELIMIT_TIERS_SCRIPT = `
+local n = #KEYS
+local blocked = 0
+for i = 1, n do
+ local limit = tonumber(ARGV[(i - 1) * 2 + 1])
+ local count = tonumber(redis.call('GET', KEYS[i]) or '0')
+ if count >= limit then
+ blocked = i
+ break
+ end
+end
+
+local reply = {blocked}
+for i = 1, n do
+ local count
+ if blocked == 0 then
+ count = redis.call('INCR', KEYS[i])
+ -- anchor the window to its first request instead of letting it slide
+ if count == 1 then
+ redis.call('EXPIRE', KEYS[i], tonumber(ARGV[(i - 1) * 2 + 2]))
+ end
+ else
+ count = tonumber(redis.call('GET', KEYS[i]) or '0')
+ end
+ reply[#reply + 1] = count
+end
+for i = 1, n do
+ reply[#reply + 1] = redis.call('TTL', KEYS[i])
+end
+return reply
+`;
+
+/**
+ * Fixed window rate limiter enforcing several windows at once. A request passes
+ * only if every tier has room. Not enforced outside production, so the /play
+ * tools stay usable locally without Upstash credentials.
+ * @param identifier - Unique identifier for the rate limit (e.g., IP address)
+ * @param tiers - Windows to enforce, each with its own redis key
+ */
+export async function ratelimitTiers(
+ identifier: string,
+ tiers: RateLimitTier[],
+): Promise<TieredRateLimitResult> {
+ const now = Date.now();
+
+ if (process.env.NODE_ENV !== "production") {
+ const tier = tiers[0];
+ return {
+ success: true,
+ limit: tier.limit,
+ remaining: tier.limit,
+ reset: now + tier.window * 1000,
+ tier,
+ };
+ }
+
+ const keys = tiers.map((tier) => `ratelimit:${identifier}:${tier.name}`);
+ const args = tiers.flatMap((tier) => [tier.limit, tier.window]);
+
+ const redis = await getRedis();
+ const reply = await redis.eval<number[], number[]>(
+ RATELIMIT_TIERS_SCRIPT,
+ keys,
+ args,
+ );
+
+ return parseTieredResult(tiers, reply, now);
+}
+
/**
* Extract IP address from request headers
* @param headers - Request headers