P0: Add per-IP request rate limiting (#166)

[dkijania]

What & why

Part of the production-readiness epic (#163). Closes #166.

A public GraphQL endpoint with no throttle lets a single client monopolise the server and the backing Postgres. This adds a global, per-client-IP rate limiter that runs on every request before GraphQL parsing, rejecting over-limit traffic with HTTP 429 as cheaply as possible.

Env var	Default	Meaning
RATE_LIMIT_MAX	600	Requests per client IP per window; 0 disables
RATE_LIMIT_WINDOW_MS	60000	Window length in ms

Design

• Client IP from X-Forwarded-For (first hop) → X-Real-IP → socket address → shared unknown bucket. Run behind a proxy that sets X-Forwarded-For for correct per-client identification (documented).
• Fixed-window in-memory counter, per-instance: with N replicas the effective limit is ~N × RATE_LIMIT_MAX. A shared store (Redis) for exact cross-replica limits is left as deployment hardening and noted in the docs.
• Health checks (/healthcheck) are never throttled.
• 429 responses carry Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining.

Why not @envelop/rate-limiter

That library is directive-based: limits are baked into the schema per field and it's per-field rather than a global per-IP bucket, plus it requires a schema/codegen change. A small custom plugin gives a true global per-IP DoS bucket that's env-tunable with no schema impact. (Discussed and chosen during implementation.)

Testing

• npm run build — clean
• npm run test:unit — all pass (config parsing; windowing/reset/prune with an injected clock; end-to-end through Yoga proving the (max+1)th request returns 429 and other clients are unaffected)
• npm run lint — clean
• npx prettier --debug-check . — exit 0

No new runtime dependency.

🤖 Generated with Claude Code

[SanabriaRusso]

Nice work — this lands the shape we want for the mina-explorer client: the 600 req / 60s default comfortably absorbs the Explorer's per-page fallback bursts (full→basic→minimal + per-block detail is well under 600/min), /healthcheck is exempt so liveness probes won't flap, RATE_LIMIT_MAX=0 is a clean off switch, and the 429 body is safely distinct from the Cannot query field string the Explorer keys on for fallback. 👍

One hardening worth doing before we call #166 done: X-Forwarded-For is trusted unconditionally, so a single abusive source can rotate the header to mint a fresh bucket per request and slip right past the limit — the exact thing #166 asks us to stop — and each forged value also adds a Map entry that only clears at window end (spoofable memory growth).

The subtlety is that honoring XFF is also what keeps NAT'd / LB-fronted Explorer users in their own buckets instead of collapsing onto one shared IP — so the fix isn't to drop XFF, it's to bound the trust with a hop-count knob and fall back to the socket address:

// TRUST_PROXY = number of trusted proxy hops in front of us.
// Behind an LB/ingress (our deployment): set it to the hop count so real client IPs are used
// (per-user Explorer buckets preserved). Set 0 on a directly-exposed server to ignore XFF.
function clientId(request, serverContext) {
  const hops = Number(process.env.TRUST_PROXY ?? 0);
  if (hops > 0) {
    const xff = request.headers.get('x-forwarded-for')?.split(',').map(s => s.trim()).filter(Boolean) ?? [];
    const ip = xff[xff.length - hops]; // count from the right → ignores attacker-prepended entries
    if (ip) return ip;
  }
  const ctx = serverContext;
  return ctx?.req?.socket?.remoteAddress ?? ctx?.socket?.remoteAddress ?? 'unknown';
}

Two smaller, non-blocking notes: (1) worth confirming the short-circuited 429 still picks up Access-Control-Allow-Origin from Yoga's useCORS (it runs on onResponse, so it should) — since the Explorer is cross-origin, an ACAO-less 429 would surface as an opaque CORS error instead of a clean 429; and (2) a quick test asserting /healthcheck never 429s would lock in the liveness exemption. Great addition overall.

[dkijania]

Thanks @SanabriaRusso — the XFF bypass was real and is fixed in 3932d3e / 9881c02. The framing that the fix is to bound the trust rather than drop the header was the useful part: dropping it would have collapsed NAT'd and LB-fronted clients onto one bucket, which is its own availability problem.

TRUST_PROXY hop count, counted from the right. Default 0 ignores forwarding headers entirely and keys on the socket address — the safe reading for a directly-exposed server. Set it to the hop count behind an LB and the client is read as the Nth entry from the right, so anything the caller prepended is ignored. X-Real-IP is gated the same way (it was equally spoofable), and a chain shorter than the hop count falls back to the socket rather than trusting a caller-supplied entry.

One deviation from your snippet: I threaded it through resolveRateLimitConfig instead of reading process.env inline, to keep the module's injectable-env convention — that's what let the bypass itself be tested rather than just reasoned about:

// one LB in front, so only the last entry is ours; varying the prepended value must not help
assert.strictEqual((await request('a.a.a.a, 7.7.7.7')).status, 200);
assert.strictEqual((await request('b.b.b.b, 7.7.7.7')).status, 200);
assert.strictEqual((await request('c.c.c.c, 7.7.7.7')).status, 429);

Your ACAO question — confirmed, no fix needed. Your reasoning was right: yoga's CORS runs on onResponse, so it applies to the short-circuited 429. Verified against a yoga instance configured the way production is:

allowed  -> 200 ACAO: "https://explorer.example.com"
limited  -> 429 ACAO: "https://explorer.example.com"

Pinned as a test, since it's the kind of thing a plugin-order change could quietly break. /healthcheck never 429s is now covered too.

One thing worth a second opinion: TRUST_PROXY=0 is secure-by-default but wrong for our own topology — the archives sit behind an LB, so an unset value buckets every client together. Rather than default to 1 (which would reintroduce the bypass for directly-exposed deployments), it warns once on the first forwarded request when TRUST_PROXY=0, so a misconfigured deploy says so instead of just throttling oddly. Same spirit as the startup warning you suggested for #184's CORS default. Shout if you'd rather it were louder — or an outright boot failure.

On /metrics and the exemption list (from your #191 note): leaving that for the #185↔#191 reconcile rather than exempting a path that 404s today — exempting a nonexistent route now would just be an unthrottled hole. Worth deciding there whether the fix is the exemption list or plugin ordering, since the merge plan currently assumes ordering and your note assumes the list; we should land one, not half of each.