src/rate-limit.ts

Functions

Imports

It imports src/log.ts. Imported by src/access-sync.ts, src/dcr.ts, src/public-data.ts, src/routes.ts.

Source

1import { logEvent } from "./log";
2
3// Best-effort, not exact. Each check reads both KV counters, compares, then writes
4// count + 1, with no compare-and-swap, so concurrent requests can read the same count
5// and a burst can pass somewhat over perHour or perDay. KV is also eventually
6// consistent across locations. A limit here bounds abuse in bulk; nothing may rely on
7// it as an exact ceiling.
8export interface RateLimitPolicy {
9  // Distinct per endpoint so one path cannot spend another's budget.
10  prefix: string;
11  perHour: number;
12  perDay: number;
13  label: string;
14  // What an unreadable counter means, decided per endpoint. Allowing on every KV
15  // failure gives one answer to two different questions, so the judgement is stated
16  // on the policy, next to the endpoint it is about, not in the limiter.
17  onUnavailable: "allow" | "refuse";
18}
19
20export const MAX_REPORTS_PER_HOUR = 300;
21export const MAX_REPORTS_PER_DAY = 1000;
22
23// Fail closed: /csp-report is unauthenticated and every accepted report writes log
24// lines, so failing open would let anyone fill the logs during an outage. A dropped
25// report costs one browser diagnostic, and the browser still gets its 204.
26export const CSP_REPORT_LIMIT: RateLimitPolicy = {
27  prefix: "csp:rate:",
28  perHour: MAX_REPORTS_PER_HOUR,
29  perDay: MAX_REPORTS_PER_DAY,
30  label: "CSP_REPORT",
31  onUnavailable: "refuse",
32};
33
34// A refusal is a spent budget or an unreadable one ("unavailable"), and every reader
35// must say which rather than print a count that was never measured.
36export type RateRefusal =
37  | { allowed: false; window: "hour" | "day"; count: number; limit: number }
38  | { allowed: false; window: "unavailable"; detail: string };
39
40export type RateVerdict = { allowed: true } | RateRefusal;
41
42function windowKeys(prefix: string, ip: string, now: Date): { hour: string; day: string } {
43  const iso = now.toISOString();
44  return { hour: `${prefix}h:${ip}:${iso.slice(0, 13)}`, day: `${prefix}d:${ip}:${iso.slice(0, 10)}` };
45}
46
47// Every path that cannot read or advance a counter ends here, and the policy's
48// `onUnavailable` decides. The log line is the only output on the allow side.
49function unavailable(policy: RateLimitPolicy, ip: string, detail: string): RateVerdict {
50  const event = `${policy.label}_RATE_LIMIT_UNAVAILABLE`;
51  logEvent("error", event, {
52    message: `${event} ${detail} for ${ip}, ${policy.onUnavailable === "allow" ? "allowing" : "refusing"}`,
53  });
54  return policy.onUnavailable === "allow" ? { allowed: true } : { allowed: false, window: "unavailable", detail };
55}
56
57export async function checkRate(
58  kv: KVNamespace | undefined,
59  ip: string,
60  now: Date,
61  policy: RateLimitPolicy
62): Promise<RateVerdict> {
63  // A deploy missing APP_KV, named apart from a read failure.
64  if (!kv) return unavailable(policy, ip, "no KV binding");
65
66  const keys = windowKeys(policy.prefix, ip, now);
67  let hourCount: number;
68  let dayCount: number;
69  try {
70    const [h, d] = await Promise.all([kv.get(keys.hour), kv.get(keys.day)]);
71    hourCount = Number(h ?? 0);
72    dayCount = Number(d ?? 0);
73    if (!Number.isFinite(hourCount) || !Number.isFinite(dayCount)) throw new Error("non-numeric counter");
74  } catch (err) {
75    return unavailable(policy, ip, `read failed: ${err instanceof Error ? err.message : String(err)}`);
76  }
77
78  // Refuse before the write, or retrying extends the block.
79  if (hourCount >= policy.perHour) return { allowed: false, window: "hour", count: hourCount, limit: policy.perHour };
80  if (dayCount >= policy.perDay) return { allowed: false, window: "day", count: dayCount, limit: policy.perDay };
81
82  try {
83    await Promise.all([
84      kv.put(keys.hour, String(hourCount + 1), { expirationTtl: 3600 }),
85      kv.put(keys.day, String(dayCount + 1), { expirationTtl: 86_400 }),
86    ]);
87  } catch (err) {
88    // A counter that does not advance is no ceiling, so the policy decides.
89    return unavailable(policy, ip, `write failed: ${err instanceof Error ? err.message : String(err)}`);
90  }
91  return { allowed: true };
92}
93
94export function callerIp(request: Request): string {
95  return request.headers.get("CF-Connecting-IP") ?? "unknown";
96}
97
98// 429, not 204: a dropped report must not look stored. 503 when the rate could not
99// be measured, which is a server problem. `noun` names what the endpoint counts.
100export function rateLimitedResponse(verdict: RateRefusal, noun = "reports"): Response {
101  if (verdict.window === "unavailable") {
102    return new Response(`rate limiting is unavailable, so ${noun} are refused: ${verdict.detail}`, {
103      status: 503,
104      headers: { "Content-Type": "text/plain;charset=utf-8", "Retry-After": "60" },
105    });
106  }
107  return new Response(`too many ${noun}: ${verdict.count} in the last ${verdict.window}, limit ${verdict.limit}`, {
108    status: 429,
109    headers: {
110      "Content-Type": "text/plain;charset=utf-8",
111      "Retry-After": verdict.window === "hour" ? "3600" : "86400",
112    },
113  });
114}