[EXAMPLE]: Add rate limiting to /api/health

[bronz3beard]

add a rate limit for this endpoint to ensure ddos is not possible

[github-actions]

✅ Reflexion Loop Approved

The plan has been approved. The finalized prompt is below:

ide-prompt.md

# IDE Implementation Prompt (reviewed by the Reflexion Loop — score 8/10)

You are implementing a plan that has ALREADY been generated and critiqued
against the Four Pillars (G-Stack / Atomic Batches / Production Ethos / Modern
Web). Do not re-plan from scratch. Implement it as atomic commits (<100 LOC
each), running the stated verification gate after every slice before moving on.

## Original brief
Add rate limiting to /api/health

add a rate limit for this endpoint to ensure ddos is not possible

## Reviewed plan to implement
## Phase 0 - Stack Diagnosis

- **Detected Stack**: Next.js App Router (TypeScript, Node.js >=22.0.0). Path mappings defined as `@/*` to `./src/*` in `tsconfig.json`.
- **Existing Constraints**: 
  - Strict type-checking is enabled (`"strict": true`).
  - Next.js Edge and Node runtimes are active. Rate limiter logic must rely on standard Web APIs (`fetch`, `Request`, `Response`, `NextRequest`, `NextResponse`).
  - The runtime targets serverless environments (like Vercel) where ephemeral, per-instance memory state is cleared frequently and isolates do not share local memory. An in-memory-only rate limiter would allow bypasses across instances, failing to protect against distributed DDoS.

---

## Architecture

To safely handle both serverless scaling (Vercel) and traditional server targets, we introduce an **Adapter-based Rate Limiting Architecture** with a strict configuration gate. Before execution, the system must resolve whether it is running on a distributed serverless platform (requiring a shared data store) or a single-instance container.

              ┌──────────────────────┐
              │ NextRequest (Header) │
              └──────────┬───────────┘
                         ▼
            ┌──────────────────────────┐
            │   src/lib/ip-resolver    │
            └──────────┬───────────┘
                         ▼
            ┌──────────────────────────┐
            │src/lib/rate-limit/factory│
            └──────────┬───────────┘
                       ├──────────────────────────────┐
                       ▼                              ▼
         [UPSTASH_REDIS_REST_URL present]    [ALLOW_IN_MEMORY_RATE_LIMIT=true]
           ┌────────────────────────┐         ┌────────────────────────┐
           │       RedisStore       │         │      InMemoryStore     │
           │ (Standard Fetch/Edge)  │         │   (Pruning Cache Map)  │
           └────────────────────────┘         └────────────────────────┘

1. **`src/lib/rate-limit/types.ts`**: Formalizes the rate limiter contract:
   ```typescript
   export interface RateLimitResult {
     success: boolean;
     limit: number;
     remaining: number;
     reset: number;
   }
   export interface RateLimitStore {
     check(ip: string): Promise<RateLimitResult>;
   }

2. src/lib/rate-limit/factory.ts: The execution gate.
   • If UPSTASH_REDIS_REST_URL and UPSTASH_REDIS_REST_TOKEN are present, it returns the serverless-safe RedisStore.
   • If missing, it checks for an explicit escape hatch environment variable: ALLOW_IN_MEMORY_RATE_LIMIT=true. If this is absent, it throws a runtime configuration error at startup, ensuring that serverless deployments cannot be misconfigured with leaky in-memory limiters by default.
3. src/lib/rate-limit/redis-store.ts: Utilizes the modern, edge-native standard fetch API to run lightweight atomic increments and expirations on Upstash Redis over HTTP. Zero heavy runtime npm dependencies.
4. src/lib/rate-limit/in-memory-store.ts: An in-memory Map structure with active passive-pruning of expired entries, used only for local development or explicitly signed-off single-instance containers.
5. src/lib/ip-resolver.ts: Safely parses x-forwarded-for and standard headers to determine the correct client origin.
6. src/app/api/health/route.ts: Resolves client IP, processes rate limiting via the factory-instantiated store, and returns RFC-compliant headers:
   • X-RateLimit-Limit
   • X-RateLimit-Remaining
   • X-RateLimit-Reset

---

Atomic Task List

1. Define Rate Limiting Interfaces & Configuration Gate

• What: Create types file src/lib/rate-limit/types.ts and the initialization factory src/lib/rate-limit/factory.ts.
• Why: Enforces compile-time contracts and implements the strict safety gate preventing un-vetted in-memory fallback on serverless platforms. <60 LOC.
• Verification Gate:
  • Run a typecheck with npx tsc --noEmit.
  • Create a unit test src/lib/rate-limit/__tests__/factory.test.ts. Verify that if both Redis env variables are absent and ALLOW_IN_MEMORY_RATE_LIMIT is not set to "true", the factory throws a clear configuration error. Verify it successfully returns correct instances under proper env setups.

2. Implement the In-Memory Store Adapter (src/lib/rate-limit/in-memory-store.ts)

• What: Write the InMemoryStore class implementing the RateLimitStore interface. Features a JavaScript Map with a TTL-based passive pruning routine during access and active interval-based cleanup.
• Why: Provides a high-performance local/single-instance fallback. <80 LOC.
• Verification Gate:
  • Create src/lib/rate-limit/__tests__/in-memory-store.test.ts.
  • Assert that calling check("127.0.0.1") sequentially decrements the remaining limit.
  • Mock timers to advance time past the window limit, and assert that the limit resets back to its maximum value.

3. Implement the Edge-Compatible Redis Store Adapter (src/lib/rate-limit/redis-store.ts)

• What: Write the RedisStore class implementing RateLimitStore using raw fetch calls to the Upstash Redis REST API.
• Why: Essential for production multi-instance serverless hosting (e.g., Vercel) where standard HTTP fetch guarantees zero cold-start latency and absolute rate-limiting synchronization. <80 LOC.
• Verification Gate:
  • Create src/lib/rate-limit/__tests__/redis-store.test.ts mocking the global fetch API.
  • Assert that the adapter constructs the correct HTTP request (with Authorization headers and payload) to the Upstash Redis HTTP API.
  • Assert that it processes valid Redis JSON responses correctly to return expected RateLimitResult structures.

4. Create the Secure IP Address Resolver (src/lib/ip-resolver.ts)

• What: Implement a secure utility parsing the true client IP from standard proxy headers (x-forwarded-for, x-real-ip) or the runtime socket.
• Why: Prevents spoofing while ensuring rate limits target correct individual users rather than proxy servers. <40 LOC.
• Verification Gate:
  • Create unit tests in src/lib/__tests__/ip-resolver.test.ts.
  • Verify that when given a mock NextRequest with multiple IPs in x-forwarded-for, it selects the leftmost IP.
  • Verify fallback behavior when headers are absent.

5. Integrate Rate Limiting into /api/health Route Handler

• What: Update src/app/api/health/route.ts to utilize the IP resolver and the rate-limiter factory.
• Why: Connects the architecture to the target endpoint, applying protection. <50 LOC.
• Verification Gate:
  • Create an integration test src/app/api/health/__tests__/route.test.ts. Mock the factory to return a controlled mock store.
  • Assert that a valid rate-limited request returns 200 OK with headers X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset.
  • Assert that a rejected request returns 429 Too Many Requests status, rate-limit headers, and a JSON payload {"error": "Too Many Requests"}.

---

Risks & Verification

Risks:

1. Unintentional Bypass in Serverless Production Deployments:
   • Risk: A developer deploys to Vercel and forgets to configure Redis, leading to silent fallback to an in-memory store that is highly ineffective under a distributed load.
   • Mitigation: The strict safety check in factory.ts mandates that if Redis environment variables are absent, the application will throw an error on route execution unless ALLOW_IN_MEMORY_RATE_LIMIT=true is explicitly set in production environments (representing a signed-off acceptance of single-instance limitation).
2. Upstash REST API Network Latency / Outages:
   • Risk: If the shared Redis instance is slow, health check route latency rises.
   • Mitigation: We place a strict AbortController timeout of 500ms on the fetch call to Upstash. If the database call times out or fails with an internal server error (e.g., 5xx), the adapter will fail-open (allow the health check to proceed with logging) rather than blocking legitimate status monitors.

Verification Plan:

1. Automated Unit Testing (CI Gate):
   • Run the full test suite asserting all isolated components:

     npm run test # Executes Vitest/Jest suite covering IP resolution, stores, and mock-routed requests.

2. Environment Configuration Audit:
   • Simulate a serverless execution environment without Upstash credentials or the fallback variable. Confirm that requests to /api/health throw an informative 500 configuration error.
   • Enable local testing with ALLOW_IN_MEMORY_RATE_LIMIT=true. Verify rate-limiting mechanics locally.
3. Manual Siege Verification:
   • Spin up the Next.js server locally and execute:

     for i in {1..105}; do curl -s -i http://localhost:3000/api/health | grep -E "HTTP/|x-ratelimit"; done

   • Confirm that requests 1 to 100 return 200 OK with decreasing x-ratelimit-remaining headers, and requests 101 to 105 return 429 Too Many Requests along with x-ratelimit-reset timestamps.

Execution rules

• One vertical slice per commit; never batch unrelated changes.
• After each slice, run its verification gate and paste the evidence.
• If reality diverges from the plan, stop and surface the conflict before coding.

</details>


*Total tokens: 0 (Cost: $0)*