🔀 Pull Request Author Checklist

PR Description

Title

api: add IP-based rate limiting to public endpoints (100 req/min)

Description Body

Summary

Adds rate-limiting middleware to our public API endpoints, set to 100 req/min per IP. Authenticated requests bypass the limit. This prevents the kind of database lockup we hit yesterday from anonymous traffic bursts.

Why

Yesterday at ~14:30 UTC, an anonymous bot hammered /api/search at ~5,000 req/min. Our DB slowed dramatically, then locked entirely for 4 minutes. Production was effectively down for paying customers during that window.

Root cause: we had zero rate limiting on public API endpoints. Any client with no authentication could burst us. See ENG-1247 for the incident postmortem.

This PR adds the missing rate-limit layer. It does NOT solve all DDoS protection (we'd want Cloudflare or similar at the edge for that) — but it prevents the next casual-bot incident.

What Changed

• Added RateLimitMiddleware in src/middleware/rate-limit.ts — IP-based, in-memory token bucket
• Wired middleware into 3 public endpoint routers: /api/search, /api/feed, /api/public/*
• Added RATE_LIMIT_PER_MIN env var (default: 100), RATE_LIMIT_BYPASS_AUTH flag (default: true)
• Authenticated requests skip the limit (auth check happens before rate-limit middleware)
• 429 responses include Retry-After header per RFC 6585
• Updated README with rate-limit documentation
• Added 12 unit tests + 3 integration tests covering middleware behavior

Approach + Alternatives Considered

Considered: Redis-backed distributed rate limit. Rejected for v1 because (a) we run on a single API instance currently, in-memory is sufficient, (b) Redis dependency is cost we don't need yet. Migration to Redis-backed is a future PR if we go multi-instance — the middleware abstraction allows swapping the store cleanly.

Considered: nginx-level rate limiting. Rejected because (a) we don't currently have nginx in our stack (we're on Cloudflare → Vercel), (b) Cloudflare's rate-limit rules are paid-tier only at our scale. App-level rate limiting is right for now.

Considered: per-endpoint limits with different thresholds. Rejected for v1 (over-engineered). Single global limit is sufficient for the immediate problem; per-endpoint can be added later via the middleware's config option (already supported in code, just not yet exposed).

Testing

Automated (added in this PR):

• 12 unit tests in rate-limit.test.ts: covers token bucket math, time-window resets, IP normalization, X-Forwarded-For parsing, auth bypass, edge cases (missing IP, malformed headers, IPv6)
• 3 integration tests: verify middleware integrates correctly with each of the 3 routers

Manual testing in staging:

1. Burst test: `seq 1 200 | xargs -P 50 -I {} curl https://staging.../api/search` → confirmed first 100 succeed, requests 101-200 return 429 with `Retry-After: 60` header

2. Authenticated request burst: `for i in {1..500}; do curl -H 'Authorization: Bearer $TOKEN' ...; done` → all 500 succeed (bypass works)

3. Behind load balancer: verified `X-Forwarded-For` is parsed correctly (rate-limit per real client IP, not LB IP)

4. IPv6: tested with IPv6 client, limit correctly applies per IPv6 address

5. Verified existing endpoints still respond normally for non-bursting traffic

Screenshots / Recordings

N/A — API only, no UI.

Risk Assessment

What could break:

1. Legitimate users behind shared proxies/NATs hitting the limit (e.g., a corporate office with 50 users behind one NAT). Likelihood: low at 100/min unless heavy concurrent usage from same NAT. Mitigation: 100/min is generous; we'll watch metrics for false-positive blocks. Future: per-API-key authenticated limits would solve this entirely.

2. In-memory rate-limit store growing with high IP diversity. Worst case: ~10K unique IPs/hour, ~80 bytes each = ~800KB. Acceptable. Auto-expires entries older than rate-limit window.

3. Middleware bug blocking all traffic. Mitigated by 12 unit tests + manual staging test. If it does happen: revert PR + redeploy = ~5 min recovery.

Confidence: High. Test coverage solid, manual verification in staging, simple algorithm (token bucket).

Blast radius: API endpoints only. Frontend rendering unaffected. Authenticated users unaffected.

Rollback Plan

If production issues:

1. Revert this PR + redeploy. Reverting is safe — middleware is additive; removing it returns to pre-PR behavior. Estimated rollback time: 5-10 min via Vercel's instant rollback.

2. Or: kill switch. Set `RATE_LIMIT_PER_MIN=999999` env var to effectively disable without redeploy. Faster (1 min via Vercel env-var update + restart), preserves middleware for future re-enable.

No DB migrations to undo. No env-var to remove (default still works after revert).

Deploy Notes

• Set RATE_LIMIT_PER_MIN=100 in Vercel production env vars (already set in staging).
• No database migration.
• No coordinated deploy needed — frontend/backend independent.
• Watch the api.rate_limit.exceeded metric (added in this PR) for first 24h to verify limit is hitting bots, not legitimate users.

Follow-Up Tasks

Not in this PR but worth tracking:

• Per-endpoint custom limits (config supported, not yet exposed)
• Redis-backed distributed limit when we go multi-instance
• Per-API-key limits for authenticated traffic (future product feature)
• Cloudflare WAF rules for DDoS at the edge (separate effort)

Reviewer Asks

• Is the in-memory store the right call vs Redis at our scale? I made the call in the alternatives section; would value the second opinion.
• Should we expose per-endpoint configs in this PR or future? Leaning future to ship the basics fast; happy to add now if you'd prefer.

Optional: Slack/comment-style mini-version

> 📦 PR for ENG-1247 (yesterday's outage). Adds 100/min IP rate limit to public API endpoints; auth'd requests bypass. Tested in staging with curl burst — works. In-memory store (single-instance), Redis migration is future. Rollback: revert + redeploy or set RATE_LIMIT_PER_MIN=999999 to kill-switch. Senior eyes welcome on the Redis-vs-memory call. — [link to PR]