mocklimit 0.1.0__tar.gz

mocklimit-0.1.0/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.

mocklimit-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,128 @@
+# 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/pyproject.toml

@@ -0,0 +1,67 @@
+[project]
+name = "mocklimit"
+version = "0.1.0"
+description = "Configurable mock API server with realistic rate limiting for testing"
+readme = "README.md"
+authors = [
+    { name = "Stanislav Kosorin", email = "stanokosorin4@gmail.com" }
+]
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE"]
+keywords = ["mock", "rate-limiting", "api", "testing", "openapi"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Framework :: FastAPI",
+    "Intended Audience :: Developers",
+    "Topic :: Software Development :: Testing",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+]
+dependencies = [
+    "fastapi>=0.135.1",
+    "jsonref>=1.1.0",
+    "pydantic>=2.0",
+    "pyyaml>=6.0.3",
+    "uvicorn>=0.42.0",
+]
+
+[project.urls]
+Repository = "https://github.com/stano45/mocklimit"
+Documentation = "https://github.com/stano45/mocklimit#readme"
+Issues = "https://github.com/stano45/mocklimit/issues"
+
+[project.scripts]
+mocklimit = "mocklimit.main:main"
+
+[build-system]
+requires = ["uv_build>=0.8.23,<0.9.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "basedpyright>=1.38.3",
+    "httpx>=0.28.1",
+    "openai>=1.0.0",
+    "pytest>=9.0.2",
+    "pytest-asyncio>=1.3.0",
+    "ruff>=0.15.6",
+]
+
+[tool.ruff]
+src = ["src"]
+
+[tool.ruff.lint]
+select = ["ALL"]
+ignore = ["D203", "D213"]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**/*.py" = ["S101", "PLR2004"]
+
+[tool.basedpyright]
+typeCheckingMode = "strict"
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"

mocklimit-0.1.0/src/mocklimit/__init__.py

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

mocklimit-0.1.0/src/mocklimit/__main__.py

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

mocklimit-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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