Add Rate Limiting

Problem this prompt solves

An unbounded “Generate” button is a credit-card drain. In-memory Maps fail on serverless (each isolate has its own memory), and IP-only limits punish offices while missing authenticated abuse. You need durable limits — per user and per IP — on the routes that cost money or create accounts.

When to use it

• You are about to open a public beta and AI routes have no throttle.
• You already saw a spike in OpenAI usage from retries, bots, or one power user.
• Auth endpoints (signup/login) need basic abuse protection.
• You deploy on Vercel and need a shared store (e.g. Upstash Redis) for counters.

Add rate limiting to this Next.js App Router app, prioritising expensive AI routes and auth endpoints.

Context: deployed on Vercel (serverless). In-memory rate limits are not sufficient. Prefer Upstash Redis + @upstash/ratelimit if it fits the repo; if another durable store already exists, use that instead of adding a new vendor.

Implement:
1) A reusable server helper, e.g. limitRequest({ key, limit, window }), that returns { success, remaining, reset }.
2) Apply limits to:
   - AI generation Route Handlers / Server Actions (stricter)
   - Auth-related routes that can be spammed (signup, magic link, password reset) if present
3) Keying strategy:
   - Authenticated AI routes: primarily by user id; also apply a coarser IP limit for unauthenticated edge cases
   - Auth routes: by IP (+ email identifier where available) to slow credential stuffing
4) On limit exceeded: return HTTP 429 with a clear JSON/error message and Retry-After when practical. UI should show a human-readable “try again in X seconds/minutes.”
5) Emit structured logs: route, key type (user/ip), remaining, without logging secrets or full prompts.
6) Env vars in .env.example (e.g. UPSTASH_REDIS_REST_URL, UPSTASH_REDIS_REST_TOKEN) and README setup steps.
7) Choose explicit numeric limits and windows for MVP (document assumptions). Example starting point: AI 10 req / 10 min / user; auth 5 req / 10 min / IP — adjust to the product and explain why.

Do not:
- Rate-limit only in middleware for POST bodies you cannot classify
- Fail open silently without logging when Redis is misconfigured in production — fail closed on AI routes or degrade with a clear 503
- Add a complex enterprise quota system; keep it MVP-solid

After implementation, list how to tune limits per plan tier later (even if billing is not built yet).

Expected result

Durable rate limiting on AI (and auth) routes with user/IP keys, 429 responses the UI understands, env documentation for Upstash (or equivalent), and sane default limits you can tune.

Implementation notes

• Put the limiter as early as possible in the handler — before zod-heavy work and before OpenAI calls.
• Use separate namespaces/prefixes for ai vs auth so you can tune independently.
• In local dev, document a bypass or higher limits so you do not hate your own DX — but never bypass in production.
• Combine with max_tokens and input size limits; rate limits alone do not cap cost per request.
• If you use Server Actions, remember they can be invoked directly — protect the action, not only a pretty UI route.
• Reserve headroom for retries: clients double-click; debounce UI and still enforce server limits.

Testing checklist

• Exceed the AI limit as a signed-in user; receive 429 and see UI messaging.
• Wait for the window to elapse (or adjust temporarily) and confirm requests succeed again.
• Confirm remaining/limit headers or payload fields match the helper’s accounting.
• With Redis credentials removed in a preview, confirm AI routes fail safely (not unlimited).
• Verify auth route limiting does not permanently lock a single NAT IP with absurdly low limits during normal testing.
• Ensure successful AI calls still persist runs — limiter should not break happy path.
• Check logs for rate-limit events without prompt contents.

Common mistakes

• In-memory Map rate limiter on Vercel — effectively no limit under load.
• IP-only limits on authenticated AI routes — easy to bypass and harsh on shared networks.
• Returning 500 with a stack trace when the limiter says exceeded.
• Applying limits after the OpenAI call — you still pay.
• Same global bucket for all routes — login storms block generations or vice versa.
• No UI handling for 429 — users hammer retry and worsen the problem.