rate-limit/limit.mjs

Functions

Imports

It imports no other module of this repo. Imported by mcp-server.mjs, rate-limit/index.mjs.

Source

1/**
2 * @typedef {"ok" | "limited" | "unavailable"} Status
3 * @typedef {{ status: Status, used: number, limit: number, retryAfterSeconds: number, window?: number, detail?: string }} Verdict
4 */
5
6/**
7 * One use of `key` against `rules`. `onUnavailable` is required, with no default, so every call site
8 * states whether a missing or failing counter lets the request through. "allow" still returns
9 * status "unavailable" and logs a structured line: the failure is reported, never swallowed.
10 *
11 * @param {{ idFromName: (name: string) => any, get: (id: any) => { hit: (rules: import("./core.mjs").Rule[]) => Promise<import("./core.mjs").Hit> } } | undefined} namespace
12 * @param {string} key
13 * @param {import("./core.mjs").Rule[]} rules
14 * @param {{ onUnavailable: "allow" | "refuse" }} options
15 * @returns {Promise<Verdict>}
16 */
17export async function limit(namespace, key, rules, options) {
18  if (options?.onUnavailable !== "allow" && options?.onUnavailable !== "refuse") {
19    throw new TypeError('onUnavailable must be "allow" or "refuse"');
20  }
21  const first = rules?.[0];
22  /** @param {string} detail @returns {Verdict} */
23  const unavailable = (detail) => {
24    console.error(JSON.stringify({ event: "rate-limit-unavailable", bucket: bucket(key), onUnavailable: options.onUnavailable, detail }));
25    return { status: "unavailable", used: 0, limit: first?.limit ?? 0, retryAfterSeconds: 60, detail };
26  };
27  if (!namespace) return unavailable("no Durable Object binding");
28  try {
29    const hit = await namespace.get(namespace.idFromName(key)).hit(rules);
30    return { status: hit.ok ? "ok" : "limited", used: hit.used, limit: hit.limit, retryAfterSeconds: hit.retryAfterSeconds, window: hit.window };
31  } catch (error) {
32    return unavailable(error instanceof Error ? error.message : String(error));
33  }
34}
35
36/**
37 * The key without its last part, so a log line never carries an IP or an account.
38 * @param {string} key
39 */
40function bucket(key) {
41  const parts = String(key).split(":");
42  return parts.length > 1 ? parts.slice(0, -1).join(":") : parts[0];
43}
44
45/**
46 * Whether the caller must stop here: `limited` always, `unavailable` only when the site chose to refuse.
47 * @param {Verdict} verdict
48 * @param {"allow" | "refuse"} onUnavailable
49 */
50export function mustStop(verdict, onUnavailable) {
51  return verdict.status === "limited" || (verdict.status === "unavailable" && onUnavailable === "refuse");
52}
53
54/**
55 * The refusal: 429 with the time left in the window, or 503 with Retry-After 60 when the counter is
56 * unavailable and the site refuses. Never a success code.
57 * @param {Verdict} verdict
58 */
59export function limitedResponse(verdict) {
60  const unavailable = verdict.status === "unavailable";
61  return new Response(unavailable ? "Temporarily unavailable" : "Too many requests", {
62    status: unavailable ? 503 : 429,
63    headers: { "Retry-After": String(verdict.retryAfterSeconds), "Content-Type": "text/plain; charset=utf-8", "Cache-Control": "no-store" },
64  });
65}
66
67/**
68 * A key for a request: `prefix:ip`. Without a client IP header the request shares one `prefix:anon`
69 * bucket and `anonymous` is true, so a site can see it happened.
70 * @param {string} prefix
71 * @param {Request} request
72 */
73export function ipKey(prefix, request) {
74  const ip = request.headers.get("CF-Connecting-IP")?.trim();
75  return { key: `${prefix}:${ip || "anon"}`, anonymous: !ip };
76}
77
78/**
79 * A path as the router sees it: percent-decoded, repeated slashes collapsed, no trailing slash, lower case.
80 * @param {string} pathname
81 */
82export function normalizePath(pathname) {
83  let path = pathname;
84  try {
85    path = decodeURIComponent(pathname);
86  } catch {
87    // A malformed escape is matched as written; it cannot be a decoded match for a rule.
88  }
89  path = path.replace(/\/{2,}/g, "/").toLowerCase();
90  return path.length > 1 ? path.replace(/\/+$/, "") : path;
91}
92
93/**
94 * The first rule whose path matches the request, so `/LOGIN`, `/login///` and `/%4cogin` cannot slip
95 * past a rule for `/login`. A rule is `{ path, prefix?, methods? }`.
96 * @template {{ path: string, prefix?: boolean, methods?: string[] }} R
97 * @param {Request} request
98 * @param {R[]} rules
99 * @returns {R | undefined}
100 */
101export function matchRule(request, rules) {
102  const path = normalizePath(new URL(request.url).pathname);
103  return rules.find((rule) => {
104    if (rule.methods && !rule.methods.includes(request.method)) return false;
105    const target = normalizePath(rule.path);
106    return rule.prefix ? path === target || path.startsWith(`${target}/`) : path === target;
107  });
108}