Testing and Validation: Load Tests, Headers, and Overrides

This guide shows how to validate behavior with load tests, which headers to expect, and how to verify MongoDB overrides are applied.

Prerequisites

• A running rate limiter service with Redis (and MongoDB if testing overrides)
• A load-testing tool such as k6

Load testing with k6

The design spec references k6 tests located under k6-tests/ with per-algorithm scenarios. If you have those scripts in your backend repo, run them as-is; if not, use the template below as a starting point.

Step 1: Create a basic test

import http from "k6/http";
import { check, sleep } from "k6";

export const options = {
  vus: 10,
  duration: "30s",
};

export default function () {
  const res = http.get("http://localhost:8080/api/test");
  check(res, {
    "status is 200 or 429": (r) => r.status === 200 || r.status === 429,
    "has rate limit headers": (r) => r.headers["X-RateLimit-Limit"] !== undefined,
  });
  sleep(0.1);
}

This sends a steady request stream and validates that responses include rate-limit headers. If you see mostly 429, reduce the rate or increase the configured limit.

Step 2: Run the test

k6 run load-test.js

If k6 is not installed, install it with your package manager or run it via Docker. A failing test usually means the service is not reachable or the endpoint is excluded from rate limiting.

Expected response headers

Rate-limited responses include:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-ResetOn: 1713091800000

X-RateLimit-ResetOn is a Unix timestamp in milliseconds when the limit resets. When X-RateLimit-Remaining reaches 0, the next request should return 429 with the same header fields.

If headers are missing:

• Confirm the endpoint is not excluded by the filter.
• Verify the request is reaching the rate limiter service and not a cache.
• Check that a gateway is not stripping response headers.

Verifying MongoDB overrides

Step 1: Create an override

curl -X POST http://localhost:8080/api/config/v2 \
  -H "Content-Type: application/json" \
  -d '{
    "ip": "192.168.1.100",
    "endpoint": "/api/test",
    "userTier": "premium",
    "method": "GET",
    "algorithm": "TOKEN_BUCKET",
    "parameters": {
      "capacity": 10,
      "refillRate": 1
    }
  }'

This stores a persistent override. The next request matching that IP, endpoint, tier, and method should use the new limits.

Step 2: Validate the override takes effect

Send requests from the matching IP (or configure the request origin to simulate it). You should observe a change in the X-RateLimit-Limit header and in the reject behavior.

If nothing changes:

• Confirm the IP and endpoint match exactly.
• Check that userTier is resolved to the same value at runtime.
• Ensure MongoDB is reachable and the document exists in rate_limit_config.

What to verify

• Load tests return 200 and 429 in expected proportions.
• All rate-limited responses include X-RateLimit-* headers.
• Overrides change behavior without restarting the service.