mocklimit 0.3.0

Configurable mock API server with realistic rate limiting for testing

mocklimit

Configurable mock API server with realistic rate limiting for testing. Point it at an OpenAPI spec, define rate limit policies in YAML, and get a local server that behaves like a rate-limited production API, complete with correct headers, 429 responses, and token usage estimation.

Features

• OpenAPI spec auto-routing - parses your spec and registers all endpoints with dummy responses
• Fixed window rate limiting with sub-second precision
• Quantized rate limiter for aligned reset windows
• Composite limits - stack multiple limits per endpoint (e.g. RPM + TPM)
• Provider-accurate headers - configurable header names (x-ratelimit-limit-requests, etc.)
• Token usage estimation for LLM API mocking
• Configurable response latency simulation
• Per-key scoping by API key or IP address
• Request statistics via /mocklimit/stats
• Prometheus metrics at /metrics -- request counts, latency histograms, rate limit gauges

Installation

pip install mocklimit

Or with uv:

uv add mocklimit

Quick start

1. Create a rate limit config

# limits.yaml
policies:
  openai_chat:
    strategy: fixed_window
    limits:
      - max_requests: 5
        window_seconds: 60
    scope: api_key
    response_latency_ms: [0, 0]
    headers:
      limit: x-ratelimit-limit-requests
      remaining: x-ratelimit-remaining-requests
      reset: x-ratelimit-reset-requests

endpoints:
  /chat/completions:
    methods: [POST]
    policy: openai_chat
    token_estimation:
      input: characters_div_4
      output: [50, 500]

2. Start the server

mocklimit serve --spec openapi.yaml --rate-config limits.yaml

The server reads your OpenAPI spec for route definitions and response schemas, then applies rate limiting according to the config. Requests beyond the limit get a 429 with appropriate Retry-After and rate limit headers.

3. Options

mocklimit serve --spec <path> --rate-config <path> [--host HOST] [--port PORT]

Flag	Default	Description
--spec	(required)	Path to OpenAPI spec (YAML)
--rate-config	(required)	Path to rate limit config (YAML)
--host	127.0.0.1	Host to bind to
--port	8000	Port to listen on

Rate limit config reference

Policies

Each policy defines a rate limiting strategy:

Field	Type	Description
strategy	"fixed_window"	Rate limiting algorithm
limits	list	One or more {max_requests, window_seconds} pairs
scope	"api_key" | "ip"	How to identify clients
response_latency_ms	[min, max]	Simulated response delay range (ms)
headers.limit	string	Header name for the request limit
headers.remaining	string	Header name for remaining requests
headers.reset	string	Header name for reset time

Endpoints

Map API paths to policies:

Field	Type	Description
methods	list of strings	HTTP methods to rate limit
policy	string	Name of the policy to apply
token_estimation	object (optional)	{input: "characters_div_4", output: [min, max]}

Prometheus metrics

mocklimit exposes a Prometheus-compatible scrape endpoint at /metrics/.

Exposed metrics

Metric	Type	Labels	Description
mocklimit_requests_total	Counter	endpoint, method, scope_key, status	Total requests to rate-limited endpoints
mocklimit_rate_limited_total	Counter	endpoint, method, scope_key	Requests denied with 429
mocklimit_request_duration_seconds	Histogram	endpoint, method, status	Handler latency including simulated delay
mocklimit_rate_limit_remaining	Gauge	endpoint, policy, scope_key	Remaining requests in the current window

Prometheus scrape config

scrape_configs:
  - job_name: mocklimit
    metrics_path: /metrics/
    static_configs:
      - targets: ["localhost:8000"]

Example output

After a few requests:

mocklimit_requests_total{endpoint="POST /chat/completions",method="POST",scope_key="my-key",status="200"} 5.0
mocklimit_requests_total{endpoint="POST /chat/completions",method="POST",scope_key="my-key",status="429"} 1.0
mocklimit_rate_limited_total{endpoint="POST /chat/completions",method="POST",scope_key="my-key"} 1.0
mocklimit_rate_limit_remaining{endpoint="POST /chat/completions",policy="chat",scope_key="my-key"} 0.0
mocklimit_request_duration_seconds_count{endpoint="POST /chat/completions",method="POST",status="200"} 5.0

Programmatic usage

You can also embed the server directly in tests:

from mocklimit.server import create_app

app = create_app("openapi.yaml", "limits.yaml")

This returns a standard FastAPI app that can be used with any ASGI test client.

License

MIT