mocklimit 0.1.0__py3-none-any.whl

mocklimit/__init__.py

@@ -0,0 +1,3 @@
+"""mocklimit — configurable mock API server with realistic rate limiting."""
+
+__version__ = "0.1.0"

mocklimit/__main__.py

@@ -0,0 +1,5 @@
+"""Allow ``python -m mocklimit``."""
+
+from mocklimit.main import main
+
+main()

mocklimit/main.py

@@ -0,0 +1,52 @@
+"""CLI entry point for the mocklimit server."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+import uvicorn
+
+from .server.app import create_app
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    """Construct the top-level argument parser."""
+    parser = argparse.ArgumentParser(
+        prog="mocklimit",
+        description="Configurable mock API server with realistic rate limiting",
+    )
+    sub = parser.add_subparsers(dest="command")
+
+    serve = sub.add_parser("serve", help="Start the mock server")
+    serve.add_argument("--spec", required=True, help="Path to the OpenAPI spec YAML")
+    serve.add_argument(
+        "--rate-config",
+        required=True,
+        help="Path to the rate-limit config YAML",
+    )
+    serve.add_argument(
+        "--port",
+        type=int,
+        default=8000,
+        help="Port to listen on (default: 8000)",
+    )
+    serve.add_argument(
+        "--host",
+        default="127.0.0.1",
+        help="Host to bind to (default: 127.0.0.1)",
+    )
+    return parser
+
+
+def main(argv: list[str] | None = None) -> None:
+    """Parse arguments and run the requested command."""
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+
+    if args.command != "serve":
+        parser.print_help()
+        sys.exit(1)
+
+    app = create_app(args.spec, args.rate_config)
+    uvicorn.run(app, host=args.host, port=args.port)

mocklimit/openapi/__init__.py

@@ -0,0 +1,12 @@
+"""OpenAPI spec parsing."""
+
+from .models import RouteDefinition
+from .parser import parse_spec
+from .response_generator import generate_all_responses, generate_dummy_response
+
+__all__ = [
+    "RouteDefinition",
+    "generate_all_responses",
+    "generate_dummy_response",
+    "parse_spec",
+]

mocklimit/openapi/models.py

@@ -0,0 +1,18 @@
+"""OpenAPI route definition models."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+__all__ = ["RouteDefinition"]
+
+
+@dataclass(frozen=True, slots=True)
+class RouteDefinition:
+    """A single API route extracted from an OpenAPI spec."""
+
+    path: str
+    method: str
+    response_schema: dict[str, Any] = field(default_factory=dict)
+    operation_id: str | None = None

mocklimit/openapi/parser.py

@@ -0,0 +1,88 @@
+"""OpenAPI spec parser for extracting route definitions."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, cast
+
+import jsonref
+import yaml
+
+from .models import RouteDefinition
+
+__all__ = ["parse_spec"]
+
+_HTTP_METHODS = frozenset({
+    "get", "put", "post", "delete",
+    "options", "head", "patch", "trace",
+})
+
+
+def _as_str_dict(value: object) -> dict[str, Any] | None:
+    """Cast *value* to a string-keyed dict if it is one, else ``None``."""
+    if isinstance(value, dict):
+        return cast("dict[str, Any]", value)
+    return None
+
+
+def _extract_response_schema(operation: dict[str, Any]) -> dict[str, Any]:
+    """Return the JSON schema for the first 2xx response, or empty dict."""
+    responses = _as_str_dict(operation.get("responses"))
+    if not responses:
+        return {}
+
+    for status_code in sorted(responses):
+        if not status_code.startswith("2"):
+            continue
+        response_dict = _as_str_dict(responses[status_code])
+        if response_dict is None:
+            continue
+        content = _as_str_dict(response_dict.get("content"))
+        if content is None:
+            continue
+        json_media = _as_str_dict(content.get("application/json"))
+        if json_media is None:
+            continue
+        schema = _as_str_dict(json_media.get("schema"))
+        if schema is not None:
+            return schema
+
+    return {}
+
+
+def parse_spec(path: str) -> list[RouteDefinition]:
+    """Parse an OpenAPI YAML/JSON file and return route definitions.
+
+    Iterates over all paths and HTTP methods, extracting the response schema
+    from the first 2xx response with ``application/json`` content.  Missing
+    responses or schemas are represented as empty dicts.
+    """
+    raw = Path(path).read_text(encoding="utf-8")
+    spec: dict[str, Any] = jsonref.replace_refs(yaml.safe_load(raw))
+
+    paths: dict[str, Any] | None = spec.get("paths")
+    if not paths:
+        return []
+
+    routes: list[RouteDefinition] = []
+    for route_path, path_item_raw in paths.items():
+        path_item = _as_str_dict(path_item_raw)
+        if path_item is None:
+            continue
+        for method, operation_raw in path_item.items():
+            if method not in _HTTP_METHODS:
+                continue
+            operation = _as_str_dict(operation_raw)
+            if operation is None:
+                continue
+            op_id: str | None = operation.get("operationId")
+            routes.append(
+                RouteDefinition(
+                    path=route_path,
+                    method=method.upper(),
+                    response_schema=_extract_response_schema(operation),
+                    operation_id=op_id,
+                ),
+            )
+
+    return routes

mocklimit/openapi/response_generator.py

@@ -0,0 +1,196 @@
+"""Generate minimal valid JSON responses from OpenAPI JSON schemas."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, cast
+
+import yaml
+
+__all__ = ["generate_all_responses", "generate_dummy_response"]
+
+_HTTP_METHODS = frozenset({
+    "get", "put", "post", "delete",
+    "options", "head", "patch", "trace",
+})
+
+
+def _as_str_dict(value: object) -> dict[str, Any] | None:
+    """Cast *value* to a string-keyed dict if it is one, else ``None``."""
+    if isinstance(value, dict):
+        return cast("dict[str, Any]", value)
+    return None
+
+
+_PRIMITIVE_DEFAULTS: dict[str, str | int | float | bool] = {
+    "string": "mock_string",
+    "integer": 1,
+    "number": 1.0,
+    "boolean": True,
+}
+
+
+def _resolve_ref(ref: str, all_schemas: dict[str, Any]) -> dict[str, Any]:
+    """Resolve a ``$ref`` string like ``#/components/schemas/Foo``."""
+    name = ref.rsplit("/", maxsplit=1)[-1]
+    schema = all_schemas.get(name)
+    if isinstance(schema, dict):
+        return cast("dict[str, Any]", schema)
+    return {}
+
+
+def _generate_array(
+    schema: dict[str, Any],
+    all_schemas: dict[str, Any] | None,
+) -> list[Any]:
+    """Generate a single-element array from *schema*'s ``items``."""
+    items_schema = schema.get("items")
+    if isinstance(items_schema, dict):
+        return [_generate_value(cast("dict[str, Any]", items_schema), all_schemas)]
+    return [None]
+
+
+def _generate_for_type(
+    schema_type: str,
+    schema: dict[str, Any],
+    all_schemas: dict[str, Any] | None,
+) -> str | int | float | bool | list[Any] | dict[str, Any] | None:
+    """Dispatch value generation based on the JSON Schema ``type``."""
+    if schema_type in _PRIMITIVE_DEFAULTS:
+        return _PRIMITIVE_DEFAULTS[schema_type]
+    if schema_type == "array":
+        return _generate_array(schema, all_schemas)
+    if schema_type == "object":
+        return _generate_object(schema, all_schemas)
+    return None
+
+
+def _generate_value(
+    schema: dict[str, Any],
+    all_schemas: dict[str, Any] | None,
+) -> str | int | float | bool | list[Any] | dict[str, Any] | None:
+    """Recursively generate a dummy value matching *schema*."""
+    if "$ref" in schema:
+        if all_schemas is None:
+            return None
+        return _generate_value(_resolve_ref(schema["$ref"], all_schemas), all_schemas)
+
+    if "enum" in schema:
+        values: list[Any] = schema["enum"]
+        return cast("str | int | float | bool", values[0]) if values else None
+
+    schema_type: str | None = schema.get("type")
+    if schema_type is None:
+        return None
+    return _generate_for_type(schema_type, schema, all_schemas)
+
+
+def _generate_object(
+    schema: dict[str, Any],
+    all_schemas: dict[str, Any] | None,
+) -> dict[str, Any]:
+    """Build a dummy object from the ``properties`` declared in *schema*."""
+    properties: dict[str, Any] = schema.get("properties", {})
+    required: list[str] | None = schema.get("required")
+
+    result: dict[str, Any] = {}
+
+    keys = [k for k in properties if k in required] if required else list(properties)
+    for key in keys:
+        prop_schema = properties[key]
+        if isinstance(prop_schema, dict):
+            result[key] = _generate_value(
+                cast("dict[str, Any]", prop_schema),
+                all_schemas,
+            )
+        else:
+            result[key] = None
+
+    return result
+
+
+def generate_dummy_response(
+    schema: dict[str, Any],
+    all_schemas: dict[str, Any] | None = None,
+) -> dict[str, Any]:
+    """Generate a minimal valid JSON object from a JSON schema.
+
+    Rules:
+    - ``string`` -> ``"mock_string"``
+    - ``integer`` -> ``1``
+    - ``number`` -> ``1.0``
+    - ``boolean`` -> ``True``
+    - ``array`` -> single-element list with a dummy item
+    - ``enum`` -> first value
+    - ``object`` -> recurse into properties
+    - ``$ref`` -> resolved via *all_schemas*
+    - no type -> ``None``
+
+    When ``required`` is specified only required fields are generated.
+    """
+    value = _generate_value(schema, all_schemas)
+    return value if isinstance(value, dict) else {}
+
+
+def _extract_raw_response_schema(operation: dict[str, Any]) -> dict[str, Any]:
+    """Return the raw response schema for the first 2xx response."""
+    responses = _as_str_dict(operation.get("responses"))
+    if not responses:
+        return {}
+
+    for status_code in sorted(responses):
+        if not status_code.startswith("2"):
+            continue
+        response_obj = _as_str_dict(responses[status_code])
+        if response_obj is None:
+            continue
+        content = _as_str_dict(response_obj.get("content"))
+        if content is None:
+            continue
+        json_media = _as_str_dict(content.get("application/json"))
+        if json_media is None:
+            continue
+        schema = _as_str_dict(json_media.get("schema"))
+        if schema is not None:
+            return schema
+
+    return {}
+
+
+def generate_all_responses(spec_path: str) -> dict[str, dict[str, Any]]:
+    """Parse an OpenAPI spec and return dummy responses for every route.
+
+    Returns a mapping of ``"METHOD /path"`` to a generated response dict.
+    ``$ref`` values are resolved against the spec's ``components/schemas``.
+    """
+    raw = Path(spec_path).read_text(encoding="utf-8")
+    spec: dict[str, Any] = yaml.safe_load(raw)
+
+    components = _as_str_dict(spec.get("components"))
+    all_schemas: dict[str, Any] = (
+        cast("dict[str, Any]", components.get("schemas", {}))
+        if components is not None
+        else {}
+    )
+
+    paths: dict[str, Any] | None = _as_str_dict(spec.get("paths"))
+    if not paths:
+        return {}
+
+    result: dict[str, dict[str, Any]] = {}
+    for route_path, path_item_raw in paths.items():
+        path_item = _as_str_dict(path_item_raw)
+        if path_item is None:
+            continue
+        for method, operation_raw in path_item.items():
+            if method not in _HTTP_METHODS:
+                continue
+            operation = _as_str_dict(operation_raw)
+            if operation is None:
+                continue
+            response_schema = _extract_raw_response_schema(operation)
+            if response_schema:
+                key = f"{method.upper()} {route_path}"
+                result[key] = generate_dummy_response(response_schema, all_schemas)
+
+    return result

mocklimit/ratelimit/__init__.py

@@ -0,0 +1,14 @@
+"""Rate limiting engine."""
+
+from .composite import CompositeLimit
+from .fixed_window import FixedWindowLimiter
+from .models import CompositeLimitResult, LimitResult
+from .quantized import QuantizedLimiter
+
+__all__ = [
+    "CompositeLimit",
+    "CompositeLimitResult",
+    "FixedWindowLimiter",
+    "LimitResult",
+    "QuantizedLimiter",
+]

mocklimit/ratelimit/composite.py

@@ -0,0 +1,71 @@
+"""Composite rate limiter that enforces multiple limits atomically."""
+
+from __future__ import annotations
+
+import threading
+from typing import TYPE_CHECKING
+
+from .models import CompositeLimitResult, LimitResult
+
+if TYPE_CHECKING:
+    from .fixed_window import FixedWindowLimiter
+
+__all__ = ["CompositeLimit"]
+
+
+class CompositeLimit:
+    """Enforce several named limiters atomically per key.
+
+    Uses a per-key ``threading.Lock`` so that the peek-then-consume
+    sequence cannot be interleaved by another thread for the same key.
+    """
+
+    __slots__ = ("_limiters", "_lock_map_lock", "_locks")
+
+    def __init__(self, limiters: list[tuple[str, FixedWindowLimiter]]) -> None:
+        """Create a composite from *limiters* ``(name, limiter)`` pairs."""
+        self._limiters = limiters
+        self._lock_map_lock = threading.Lock()
+        self._locks: dict[str, threading.Lock] = {}
+
+    def _get_lock(self, key: str) -> threading.Lock:
+        """Return the per-key lock, creating it if necessary."""
+        with self._lock_map_lock:
+            lock = self._locks.get(key)
+            if lock is None:
+                lock = threading.Lock()
+                self._locks[key] = lock
+            return lock
+
+    def check(self, key: str, costs: dict[str, int]) -> CompositeLimitResult:
+        """Atomically check all limiters and consume only if every one allows.
+
+        Returns a `CompositeLimitResult` with per-limiter details.
+        """
+        lock = self._get_lock(key)
+        with lock:
+            per_limit: dict[str, LimitResult] = {}
+            denied_by: str | None = None
+
+            for name, limiter in self._limiters:
+                result = limiter.peek(key, costs[name])
+                per_limit[name] = result
+                if not result.allowed and denied_by is None:
+                    denied_by = name
+
+            if denied_by is not None:
+                return CompositeLimitResult(
+                    allowed=False,
+                    denied_by=denied_by,
+                    per_limit=per_limit,
+                )
+
+            for name, limiter in self._limiters:
+                result = limiter.check(key, costs[name])
+                per_limit[name] = result
+
+            return CompositeLimitResult(
+                allowed=True,
+                denied_by=None,
+                per_limit=per_limit,
+            )

mocklimit/ratelimit/fixed_window.py

@@ -0,0 +1,95 @@
+"""Fixed-window rate limiter implementation."""
+
+from __future__ import annotations
+
+import time
+
+from .models import LimitResult
+
+__all__ = ["FixedWindowLimiter"]
+
+
+class FixedWindowLimiter:
+    """Fixed-window in-memory rate limiter.
+
+    Divides time into consecutive windows of ``window_seconds`` length and
+    allows up to ``max_requests`` units of cost per key per window.
+    """
+
+    __slots__ = ("_max_requests", "_window_seconds", "_windows")
+
+    def __init__(self, max_requests: int, window_seconds: float) -> None:
+        """Create a limiter allowing *max_requests* per *window_seconds*."""
+        self._max_requests = max_requests
+        self._window_seconds = window_seconds
+        self._windows: dict[str, dict[int, int]] = {}
+
+    def _get_window_state(self, key: str) -> tuple[int, int, float]:
+        """Return ``(current_window, current_count, reset_after)`` for *key*.
+
+        Cleans up stale windows as a side-effect.
+        """
+        now = time.time()
+        current_window = int(now // self._window_seconds)
+        next_window_start = (current_window + 1) * self._window_seconds
+        reset_after = next_window_start - now
+
+        key_windows = self._windows.get(key)
+        if key_windows is None:
+            key_windows = {}
+            self._windows[key] = key_windows
+        else:
+            stale = [w for w in key_windows if w < current_window]
+            for w in stale:
+                del key_windows[w]
+
+        current_count = key_windows.get(current_window, 0)
+        return current_window, current_count, reset_after
+
+    def peek(self, key: str, cost: int = 1) -> LimitResult:
+        """Return what `check` would return without consuming budget."""
+        _, current_count, reset_after = self._get_window_state(key)
+
+        if current_count + cost > self._max_requests:
+            return LimitResult(
+                allowed=False,
+                remaining=self._max_requests - current_count,
+                limit=self._max_requests,
+                reset_after_seconds=reset_after,
+                retry_after_seconds=reset_after,
+            )
+
+        return LimitResult(
+            allowed=True,
+            remaining=self._max_requests - (current_count + cost),
+            limit=self._max_requests,
+            reset_after_seconds=reset_after,
+            retry_after_seconds=0.0,
+        )
+
+    def check(self, key: str, cost: int = 1) -> LimitResult:
+        """Check whether *key* may consume *cost* units of the budget.
+
+        Returns a `LimitResult` describing the decision and timing metadata.
+        """
+        current_window, current_count, reset_after = self._get_window_state(key)
+
+        if current_count + cost > self._max_requests:
+            return LimitResult(
+                allowed=False,
+                remaining=self._max_requests - current_count,
+                limit=self._max_requests,
+                reset_after_seconds=reset_after,
+                retry_after_seconds=reset_after,
+            )
+
+        new_count = current_count + cost
+        self._windows[key][current_window] = new_count
+
+        return LimitResult(
+            allowed=True,
+            remaining=self._max_requests - new_count,
+            limit=self._max_requests,
+            reset_after_seconds=reset_after,
+            retry_after_seconds=0.0,
+        )

mocklimit/ratelimit/models.py

@@ -0,0 +1,27 @@
+"""Rate limiting result models."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+__all__ = ["CompositeLimitResult", "LimitResult"]
+
+
+@dataclass(frozen=True, slots=True)
+class LimitResult:
+    """Outcome of a rate limit check."""
+
+    allowed: bool
+    remaining: int
+    limit: int
+    reset_after_seconds: float
+    retry_after_seconds: float
+
+
+@dataclass(frozen=True, slots=True)
+class CompositeLimitResult:
+    """Outcome of a composite rate limit check across multiple limiters."""
+
+    allowed: bool
+    denied_by: str | None
+    per_limit: dict[str, LimitResult]

mocklimit/ratelimit/quantized.py

@@ -0,0 +1,98 @@
+"""Quantized rate limiter that enforces an outer limit at a finer inner granularity."""
+
+from __future__ import annotations
+
+import threading
+
+from .fixed_window import FixedWindowLimiter
+from .models import LimitResult
+
+__all__ = ["QuantizedLimiter"]
+
+
+class QuantizedLimiter:
+    """Enforce an outer rate limit using a finer-grained inner window.
+
+    Simulates behaviour like OpenAI's "600 RPM enforced as 10 RPS":
+    the *outer* window defines the headline limit while the *inner*
+    window prevents sub-window bursts that the outer window alone
+    would allow.
+
+    Uses a per-key ``threading.Lock`` so that the peek-then-consume
+    sequence cannot be interleaved by another thread for the same key.
+    """
+
+    __slots__ = ("_inner", "_lock_map_lock", "_locks", "_outer")
+
+    def __init__(
+        self,
+        outer_max_requests: int,
+        outer_window_seconds: float,
+        inner_max_requests: int,
+        inner_window_seconds: float,
+    ) -> None:
+        """Create a quantized limiter with *outer* and *inner* windows."""
+        self._outer = FixedWindowLimiter(outer_max_requests, outer_window_seconds)
+        self._inner = FixedWindowLimiter(inner_max_requests, inner_window_seconds)
+        self._lock_map_lock = threading.Lock()
+        self._locks: dict[str, threading.Lock] = {}
+
+    def _get_lock(self, key: str) -> threading.Lock:
+        """Return the per-key lock, creating it if necessary."""
+        with self._lock_map_lock:
+            lock = self._locks.get(key)
+            if lock is None:
+                lock = threading.Lock()
+                self._locks[key] = lock
+            return lock
+
+    @staticmethod
+    def _merge_allowed(outer: LimitResult, inner: LimitResult) -> LimitResult:
+        """Combine two allowed results into a single merged result."""
+        return LimitResult(
+            allowed=True,
+            remaining=min(outer.remaining, inner.remaining),
+            limit=outer.limit,
+            reset_after_seconds=min(
+                outer.reset_after_seconds,
+                inner.reset_after_seconds,
+            ),
+            retry_after_seconds=0.0,
+        )
+
+    @staticmethod
+    def _pick_denial(outer: LimitResult, inner: LimitResult) -> LimitResult:
+        """Return the most relevant denial when at least one limiter denied."""
+        if not outer.allowed and not inner.allowed:
+            return min(
+                outer,
+                inner,
+                key=lambda r: r.retry_after_seconds,
+            )
+        if not outer.allowed:
+            return outer
+        return inner
+
+    def peek(self, key: str, cost: int = 1) -> LimitResult:
+        """Return what `check` would return without consuming budget."""
+        outer = self._outer.peek(key, cost)
+        inner = self._inner.peek(key, cost)
+
+        if outer.allowed and inner.allowed:
+            return self._merge_allowed(outer, inner)
+        return self._pick_denial(outer, inner)
+
+    def check(self, key: str, cost: int = 1) -> LimitResult:
+        """Atomically check both windows and consume only if both allow."""
+        lock = self._get_lock(key)
+        with lock:
+            outer_peek = self._outer.peek(key, cost)
+            inner_peek = self._inner.peek(key, cost)
+
+            if not outer_peek.allowed or not inner_peek.allowed:
+                return self._pick_denial(outer_peek, inner_peek)
+
+            outer_result = self._outer.check(key, cost)
+            inner_result = self._inner.check(key, cost)
+
+            return self._merge_allowed(outer_result, inner_result)

mocklimit/server/__init__.py

@@ -0,0 +1,6 @@
+"""FastAPI server."""
+
+from .app import create_app
+from .config import RateLimitConfig
+
+__all__ = ["RateLimitConfig", "create_app"]

mocklimit/server/app.py

@@ -0,0 +1,267 @@
+"""FastAPI application factory."""
+
+from __future__ import annotations
+
+import asyncio
+import math
+import random
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+from urllib.parse import urlparse
+
+import yaml
+from fastapi import APIRouter, FastAPI, Request
+from fastapi.responses import JSONResponse
+
+from mocklimit.openapi import RouteDefinition, generate_all_responses, parse_spec
+from mocklimit.ratelimit import (
+    CompositeLimit,
+    CompositeLimitResult,
+    FixedWindowLimiter,
+    LimitResult,
+)
+
+from .config import EndpointConfig, PolicyConfig, RateLimitConfig, load_config
+from .stats import StatsTracker
+
+__all__ = ["create_app"]
+
+_BEARER_PREFIX = "Bearer "
+_RNG = random.SystemRandom()
+
+
+@dataclass
+class _RouteContext:
+    """Everything a rate-limited handler needs, bundled for readability."""
+
+    route_key: str
+    dummy_body: dict[str, Any]
+    ep_cfg: EndpointConfig
+    policy: PolicyConfig
+    limiter: CompositeLimit
+    costs: dict[str, int]
+    stats: StatsTracker
+
+
+def _extract_scope_key(request: Request, policy: PolicyConfig) -> str:
+    """Derive the rate-limit key from the request based on policy scope."""
+    if policy.scope == "api_key":
+        auth: str | None = request.headers.get("authorization")
+        if auth and auth.startswith(_BEARER_PREFIX):
+            return auth[len(_BEARER_PREFIX) :]
+        return "anonymous"
+    client = request.client
+    if client is not None:
+        return client.host
+    return "unknown"
+
+
+def _most_restrictive(result: CompositeLimitResult) -> LimitResult:
+    """Return the single ``LimitResult`` most relevant for response headers."""
+    if result.denied_by is not None:
+        return result.per_limit[result.denied_by]
+    return min(result.per_limit.values(), key=lambda r: r.remaining)
+
+
+def _rate_limit_headers(
+    lr: LimitResult,
+    headers_cfg: PolicyConfig,
+) -> dict[str, str]:
+    """Build rate-limit response headers from a ``LimitResult``."""
+    hdr = headers_cfg.headers
+    out: dict[str, str] = {
+        hdr.limit: str(lr.limit),
+        hdr.remaining: str(lr.remaining),
+        hdr.reset: f"{lr.reset_after_seconds:.1f}s",
+    }
+    if not lr.allowed:
+        out["Retry-After"] = str(math.ceil(lr.retry_after_seconds))
+    return out
+
+
+def _build_limiters(config: RateLimitConfig) -> dict[str, CompositeLimit]:
+    """Instantiate a ``CompositeLimit`` for every policy in *config*."""
+    limiters: dict[str, CompositeLimit] = {}
+    for name, policy in config.policies.items():
+        pairs: list[tuple[str, FixedWindowLimiter]] = [
+            (
+                f"limit_{i}",
+                FixedWindowLimiter(
+                    max_requests=lc.max_requests,
+                    window_seconds=lc.window_seconds,
+                ),
+            )
+            for i, lc in enumerate(policy.limits)
+        ]
+        limiters[name] = CompositeLimit(pairs)
+    return limiters
+
+
+def _build_route_table(
+    routes: list[RouteDefinition],
+    config: RateLimitConfig,
+) -> list[dict[str, str | None]]:
+    """Build the JSON-serializable route listing for ``/mocklimit/routes``."""
+    table: list[dict[str, str | None]] = []
+    for route in routes:
+        ep_cfg = config.endpoints.get(route.path)
+        policy_name: str | None = None
+        if ep_cfg is not None and route.method in ep_cfg.methods:
+            policy_name = ep_cfg.policy
+        table.append({
+            "path": route.path,
+            "method": route.method,
+            "policy": policy_name,
+        })
+    return table
+
+
+async def _estimate_tokens(
+    request: Request,
+    ep_cfg: EndpointConfig,
+) -> dict[str, int]:
+    """Compute estimated token usage for a request."""
+    te = ep_cfg.token_estimation
+    if te is None:
+        return {}
+    body = await request.body()
+    prompt_tokens = len(body) // 4
+    completion_tokens = _RNG.randint(te.output[0], te.output[1])
+    return {
+        "prompt_tokens": prompt_tokens,
+        "completion_tokens": completion_tokens,
+        "total_tokens": prompt_tokens + completion_tokens,
+    }
+
+
+def _extract_base_path(spec_path: str) -> str:
+    """Read the first ``servers[].url`` from the spec and return its path.
+
+    For example ``https://api.openai.com/v1`` yields ``/v1``.
+    Returns an empty string when no server URL is defined.
+    """
+    raw = Path(spec_path).read_text(encoding="utf-8")
+    spec: dict[str, Any] = yaml.safe_load(raw)
+    servers: list[dict[str, Any]] = spec.get("servers", [])
+    if not servers:
+        return ""
+    url: str = servers[0].get("url", "")
+    return urlparse(url).path.rstrip("/")
+
+
+def create_app(spec_path: str, rate_config_path: str) -> FastAPI:
+    """Build a fully-wired FastAPI application.
+
+    Parses the OpenAPI *spec_path* for route definitions and dummy
+    responses, reads the rate-limit YAML at *rate_config_path*, and
+    registers all routes under the spec's server base path (e.g.
+    ``/v1``) with the appropriate rate-limiting behaviour.
+    """
+    routes = parse_spec(spec_path)
+    responses = generate_all_responses(spec_path)
+    config = load_config(rate_config_path)
+    limiters = _build_limiters(config)
+    stats = StatsTracker()
+    route_table = _build_route_table(routes, config)
+    base_path = _extract_base_path(spec_path)
+
+    app = FastAPI(title="mocklimit")
+    router = APIRouter(prefix=base_path)
+
+    for route in routes:
+        route_key = f"{route.method} {route.path}"
+        dummy_body = responses.get(route_key, {})
+        ep_cfg = config.endpoints.get(route.path)
+
+        if ep_cfg is not None and route.method in ep_cfg.methods:
+            policy = config.policies[ep_cfg.policy]
+            ctx = _RouteContext(
+                route_key=route_key,
+                dummy_body=dummy_body,
+                ep_cfg=ep_cfg,
+                policy=policy,
+                limiter=limiters[ep_cfg.policy],
+                costs={f"limit_{i}": 1 for i in range(len(policy.limits))},
+                stats=stats,
+            )
+            _register_limited_route(router, route, ctx)
+        else:
+            _register_plain_route(router, route, dummy_body)
+
+    app.include_router(router)
+
+    async def get_stats(_request: Request) -> JSONResponse:
+        """Return per-endpoint, per-key request statistics."""
+        return JSONResponse(content=stats.snapshot())
+
+    async def get_routes(_request: Request) -> JSONResponse:
+        """Return the list of registered routes and their policies."""
+        return JSONResponse(content=route_table)
+
+    app.add_api_route("/mocklimit/stats", get_stats, methods=["GET"])
+    app.add_api_route("/mocklimit/routes", get_routes, methods=["GET"])
+
+    return app
+
+
+def _register_limited_route(
+    router: APIRouter,
+    route: RouteDefinition,
+    ctx: _RouteContext,
+) -> None:
+    """Register a rate-limited route on *router*."""
+
+    async def handler(request: Request) -> JSONResponse:
+        scope_key = _extract_scope_key(request, ctx.policy)
+        ctx.stats.record_request(ctx.route_key, scope_key)
+
+        result = ctx.limiter.check(scope_key, ctx.costs)
+        lr = _most_restrictive(result)
+        headers = _rate_limit_headers(lr, ctx.policy)
+
+        if not result.allowed:
+            ctx.stats.record_limited(ctx.route_key, scope_key)
+            return JSONResponse(
+                status_code=429,
+                content=ctx.dummy_body,
+                headers=headers,
+            )
+
+        latency_min, latency_max = ctx.policy.response_latency_ms
+        if latency_max > 0:
+            delay_s = _RNG.uniform(latency_min / 1000, latency_max / 1000)
+            await asyncio.sleep(delay_s)
+
+        body: dict[str, Any] = dict(ctx.dummy_body)
+        usage = await _estimate_tokens(request, ctx.ep_cfg)
+        if usage:
+            body["usage"] = usage
+
+        return JSONResponse(content=body, headers=headers)
+
+    router.add_api_route(
+        route.path,
+        handler,
+        methods=[route.method],
+        name=route.operation_id or ctx.route_key,
+    )
+
+
+def _register_plain_route(
+    router: APIRouter,
+    route: RouteDefinition,
+    dummy_body: dict[str, Any],
+) -> None:
+    """Register a route that returns the dummy response with no limits."""
+    body = dict(dummy_body)
+
+    async def handler(_request: Request) -> JSONResponse:
+        return JSONResponse(content=body)
+
+    router.add_api_route(
+        route.path,
+        handler,
+        methods=[route.method],
+        name=route.operation_id or f"{route.method} {route.path}",
+    )

mocklimit/server/config.py

@@ -0,0 +1,65 @@
+"""Rate limit configuration models and loader."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Literal
+
+import yaml
+from pydantic import BaseModel
+
+__all__ = ["EndpointConfig", "RateLimitConfig", "load_config"]
+
+
+class LimitConfig(BaseModel):
+    """A single rate limit window definition."""
+
+    max_requests: int
+    window_seconds: float
+
+
+class HeadersConfig(BaseModel):
+    """Mapping of semantic header roles to header names."""
+
+    limit: str
+    remaining: str
+    reset: str
+
+
+class PolicyConfig(BaseModel):
+    """A named rate limiting policy."""
+
+    strategy: Literal["fixed_window"]
+    limits: list[LimitConfig]
+    scope: Literal["api_key", "ip"]
+    response_latency_ms: tuple[int, int]
+    headers: HeadersConfig
+
+
+class TokenEstimationConfig(BaseModel):
+    """Token estimation strategy for an endpoint."""
+
+    input: Literal["characters_div_4"]
+    output: tuple[int, int]
+
+
+class EndpointConfig(BaseModel):
+    """Configuration for a single API endpoint."""
+
+    methods: list[str]
+    policy: str
+    token_estimation: TokenEstimationConfig | None = None
+
+
+class RateLimitConfig(BaseModel):
+    """Top-level rate limiting configuration."""
+
+    policies: dict[str, PolicyConfig]
+    endpoints: dict[str, EndpointConfig]
+
+
+def load_config(path: str) -> RateLimitConfig:
+    """Read a YAML config file and return a validated ``RateLimitConfig``."""
+    raw = Path(path).read_text(encoding="utf-8")
+    data: dict[str, Any] = yaml.safe_load(raw)
+    return RateLimitConfig.model_validate(data)

mocklimit/server/stats.py

@@ -0,0 +1,68 @@
+"""Thread-safe request statistics tracker."""
+
+from __future__ import annotations
+
+import threading
+from dataclasses import dataclass, field
+from typing import Any
+
+__all__ = ["StatsTracker"]
+
+
+@dataclass
+class _KeyStats:
+    """Mutable counters for a single (endpoint, key) pair."""
+
+    total_requests: int = 0
+    total_429s: int = 0
+
+
+@dataclass
+class StatsTracker:
+    """Per-endpoint, per-key request statistics.
+
+    All mutating methods are guarded by a lock so the tracker is safe
+    to use from FastAPI's thread-pool backed sync handlers.
+    """
+
+    _data: dict[str, dict[str, _KeyStats]] = field(default_factory=dict)
+    _lock: threading.Lock = field(default_factory=threading.Lock)
+
+    def record_request(self, endpoint: str, key: str) -> None:
+        """Increment the total-requests counter for *endpoint* / *key*."""
+        with self._lock:
+            self._ensure(endpoint, key).total_requests += 1
+
+    def record_limited(self, endpoint: str, key: str) -> None:
+        """Increment the total-429s counter for *endpoint* / *key*."""
+        with self._lock:
+            self._ensure(endpoint, key).total_429s += 1
+
+    def snapshot(self) -> dict[str, Any]:
+        """Return a JSON-serializable copy of current statistics."""
+        with self._lock:
+            return {
+                endpoint: {
+                    key: {
+                        "total_requests": ks.total_requests,
+                        "total_429s": ks.total_429s,
+                    }
+                    for key, ks in keys.items()
+                }
+                for endpoint, keys in self._data.items()
+            }
+
+    def _ensure(self, endpoint: str, key: str) -> _KeyStats:
+        """Return the ``_KeyStats`` for *endpoint* / *key*, creating if needed.
+
+        Must be called while holding ``self._lock``.
+        """
+        by_key = self._data.get(endpoint)
+        if by_key is None:
+            by_key = {}
+            self._data[endpoint] = by_key
+        ks = by_key.get(key)
+        if ks is None:
+            ks = _KeyStats()
+            by_key[key] = ks
+        return ks

mocklimit-0.1.0.dist-info/METADATA

@@ -0,0 +1,156 @@
+Metadata-Version: 2.4
+Name: mocklimit
+Version: 0.1.0
+Summary: Configurable mock API server with realistic rate limiting for testing
+Keywords: mock,rate-limiting,api,testing,openapi
+Author: Stanislav Kosorin
+Author-email: Stanislav Kosorin <stanokosorin4@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Testing
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Dist: fastapi>=0.135.1
+Requires-Dist: jsonref>=1.1.0
+Requires-Dist: pydantic>=2.0
+Requires-Dist: pyyaml>=6.0.3
+Requires-Dist: uvicorn>=0.42.0
+Requires-Python: >=3.11
+Project-URL: Documentation, https://github.com/stano45/mocklimit#readme
+Project-URL: Issues, https://github.com/stano45/mocklimit/issues
+Project-URL: Repository, https://github.com/stano45/mocklimit
+Description-Content-Type: text/markdown
+
+# mocklimit
+
+[![CI](https://github.com/stano45/mocklimit/actions/workflows/ci.yml/badge.svg)](https://github.com/stano45/mocklimit/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/mocklimit)](https://pypi.org/project/mocklimit/)
+[![Python](https://img.shields.io/pypi/pyversions/mocklimit)](https://pypi.org/project/mocklimit/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+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`
+
+## Installation
+
+```bash
+pip install mocklimit
+```
+
+Or with [uv](https://docs.astral.sh/uv/):
+
+```bash
+uv add mocklimit
+```
+
+## Quick start
+
+### 1. Create a rate limit config
+
+```yaml
+# 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
+
+```bash
+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]}` |
+
+## Programmatic usage
+
+You can also embed the server directly in tests:
+
+```python
+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

mocklimit-0.1.0.dist-info/RECORD

@@ -0,0 +1,22 @@
+mocklimit/__init__.py,sha256=723dDOXsGEq_6G0IHOjkdTpbyNMEfkKYqpQiAZaICfA,102
+mocklimit/__main__.py,sha256=3Q9oAalS7PCIDeddDFNsNCEI2ItvK0vbY_2mjWHN9e8,78
+mocklimit/main.py,sha256=SxBcqZdv0WRrCq3QAh0ty2xHE3PPLBNOakGxsCXkcEA,1389
+mocklimit/openapi/__init__.py,sha256=NGzkIx1eDEYWU85IQg74YVN7oWX1dTlQ6DSyZXy_2K8,293
+mocklimit/openapi/models.py,sha256=t0WXt-polAx8bGvjV2x2bnA2GnZcAwETOja0dkeHSOQ,426
+mocklimit/openapi/parser.py,sha256=yw5UMr0EHqyB9hdDK-zXQOLfh5_Vj8CsCX24Hkaltw4,2753
+mocklimit/openapi/response_generator.py,sha256=6zdSTPxPbAlYAWfGV0TnEbaI_SjwuyQZyyzJ0LtGeww,6311
+mocklimit/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+mocklimit/ratelimit/__init__.py,sha256=BP8Uee18o4d4ZOqdRQ84CuJ88EhpCQ7J2BBs3TZ9c8g,340
+mocklimit/ratelimit/composite.py,sha256=F4_6yYuVTu1W5glzS4merXjupUUCLi8xvsy48XcPU34,2367
+mocklimit/ratelimit/fixed_window.py,sha256=KUqUQOza9yQNwnvT2WrZ5ppraV4SDpu2HXoMvioOcpw,3337
+mocklimit/ratelimit/models.py,sha256=XVr7NZf-dJeuobnP8laeJMNfeCg_0BiQGFqJuC3NI9A,595
+mocklimit/ratelimit/quantized.py,sha256=x1pnPJjZ1HkhKzsratbLTyS-6dMj0clnuMysWSKZzwU,3555
+mocklimit/server/__init__.py,sha256=vRyy3RQ1u1cumfdLbLs6yOSdpUrRShz8UHcljjQr1s8,132
+mocklimit/server/app.py,sha256=HmWPPyWuvLEFDgq7yyTRsjgNRm7on7FfA8AxmQEUvyo,8503
+mocklimit/server/config.py,sha256=enGTVAA0QvIfTRSp8cBo7PYdqhVuy3Dd6t9qTtf2YHM,1555
+mocklimit/server/stats.py,sha256=GIOF9clvGQFemDWEmrHLZbfKlz3BkyKvuZopwJMagRc,2095
+mocklimit-0.1.0.dist-info/licenses/LICENSE,sha256=7B4MJojwUbjwMYF83vyzgFOZ2kxtwELEC5vTHvfvYmg,1074
+mocklimit-0.1.0.dist-info/WHEEL,sha256=eh7sammvW2TypMMMGKgsM83HyA_3qQ5Lgg3ynoecH3M,79
+mocklimit-0.1.0.dist-info/entry_points.txt,sha256=MZ637eliIcbeWlDP_KGRuj8zRzoflPHvW25SMDXNSQ0,51
+mocklimit-0.1.0.dist-info/METADATA,sha256=bLdDn4KnZ0ziCuCDz9A5nwCLeOxY3SDMQC6uWtl_br8,4935
+mocklimit-0.1.0.dist-info/RECORD,,

mocklimit-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.8.24
+Root-Is-Purelib: true
+Tag: py3-none-any

mocklimit-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+mocklimit = mocklimit.main:main
+

mocklimit-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Stanislav Kosorin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.