proxy-mock 2.10.1__tar.gz

proxy_mock-2.10.1/.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+*.log
+*.pytest_*
+*.coverage*
+.venv/
+dist/
+.DS_Store
+.python-version

proxy_mock-2.10.1/CHANGELOG.md

@@ -0,0 +1,280 @@
+Migrating from 1.0.1
+====================
+
+The previously published 1.0.1 (Flask) and the current 2.10.1 (FastAPI) are not compatible.
+Five changes require edits in projects upgrading from 1.0.1:
+
+* **`GET /status` was renamed to `GET /proxy_mock`.** There is no alias: `/status` is now
+  handled by the any-catcher (`404`, or a user mock if one is configured)
+* **The client method `get_status()` was renamed to `get_proxy_mock()`.** There is no alias
+* **The dedicated `POST /configure_mock/binary` endpoint is gone.** A binary body is sent to
+  the regular `POST /configure_mock` with `Content-Type: application/octet-stream` (msgpack)
+* **The client method `configure_binary_mock()` was removed** — use `configure_mock()`, which
+  serialises the body to msgpack itself
+* **Error messages are now in English.** A missing mock returns
+  `{"error": "No mock found for /<path>"}` instead of the previous Russian text; code that
+  matches on message text needs updating
+
+Still compatible: `POST /configure_mock`, `GET /storage`, `POST /storage/clean`,
+`GET /traffic`, `POST /traffic/clean` and the client methods `configure_mock()`,
+`get_traffic()`, `get_storage()`, `clean_storage()`, `clean_traffic()`. `get_traffic()` gained
+optional filters (`path`, `method`, `limit`); calling it without arguments is unchanged.
+
+Environment requirements changed as well: Python >= 3.11 instead of 3.9, and uvicorn instead
+of gunicorn.
+
+Version 2.10.1
+==============
+
+* First public release of the 2.x line. The changes since 1.0.1 are listed below, and the upgrade path is in "Migrating from 1.0.1"
+* Functionality is unchanged relative to 2.10.0: code, API and clients were not modified
+* Documentation, code comments and API error messages are now in English
+* Added a license file (MIT) and a GitHub Actions build
+
+Version 2.10.0
+==============
+
+* **Breaking change.** The service endpoint `GET /status` was renamed to `GET /proxy_mock`. The old path is not even kept as an alias: `/status` is now handled by the any-catcher (`404` or a user mock)
+* **Breaking change.** In the `ProxyMock` and `AsyncProxyMock` clients the `get_status()` method was renamed to `get_proxy_mock()` with no alias, so consumer projects need fixing on upgrade
+
+* Fixed a `500` with a traceback when `proxy_host` was unreachable: the httpx2 transport error (DNS failure, refused connection, broken protocol) bubbled up to uvicorn. It now returns `502` with the reason, and `504` when the upstream host times out. Fixed in both proxy paths, for mocks and for rules. Failed responses are not cached and the request still lands in traffic
+* `GET /proxy_mock` returns an instance summary: the Python version (`python_version`), the number of configured mocks (`mocks_count`), the number of traffic records (`traffic_count`) and the current store limit (`traffic_max_items`)
+* The traffic store limit is adjustable at runtime through the `max_items` field of `POST /traffic/settings`. Lowering the limit trims the oldest records and keeps the freshest. The endpoint body is a partial update: any subset of fields is accepted, an empty body gives `422`
+
+* Recording of unknown traffic (requests that matched no mock) became switchable. The `PROXY_MOCK_RECORD_UNKNOWN_TRAFFIC` environment variable (default `true`, preserving 2.9.0 behaviour) accepts `1/0`, `true/false`, `yes/no`, `on/off`; an unrecognised value falls back to the default
+* New service endpoints `GET /traffic/settings` and `POST /traffic/settings` configure traffic capture at runtime, without restarting the service. The clients gained `get_traffic_settings()` and `set_traffic_settings()`
+* The `404` response itself and its logging do not change when recording is off: the flag only controls whether the request lands in traffic
+
+* The project moved from Poetry to uv: `uv.lock` instead of `poetry.lock`, dev dependencies in `[dependency-groups]` (PEP 735)
+* The build backend changed from `poetry-core` to `hatchling`; the sdist contents are listed explicitly so tests and repository service files are not shipped
+* The Dockerfile and the build moved to uv: `uv sync --locked` instead of `poetry sync`, `uv build` / `uv publish` instead of `poetry build` / `poetry publish`. The multi-stage layout did not change
+* The Makefile gained an `install` target (`uv sync`); `.venv/` and `dist/` were added to `.gitignore`
+
+Version 2.9.0
+=============
+
+* Requests that matched no mock (the 404 response) are recorded in traffic, with `status_code: 404` written to `extra_info`
+* `requested_at_ts` was dropped from traffic; only `requested_at` remains (Europe/Moscow, ISO-8601)
+* Protection against proxying "to self": the `x-proxy-mock-chain` marker header, with the loop aborted by a `508` response
+* An allowlist of proxy targets via `PROXY_MOCK_ALLOWED_PROXY_HOSTS` (disabled by default, so any host is allowed)
+* The traffic store limit was set to 1000 and made configurable through `PROXY_MOCK_TRAFFIC_MAX`
+* An explicit timeout for outgoing proxied requests, configurable through `PROXY_MOCK_PROXY_TIMEOUT` (30s by default)
+* A new `DELETE /storage` endpoint for deleting mocks: without `path` all of them, with `path` a single one (`404` if it does not exist). `POST /storage/clean` remains as a deprecated alias
+* Moved from `httpx` to `httpx2` (the httpx successor maintained under Pydantic) for the server HTTP clients, the async client and the benchmark
+
+* The Dockerfile became multi-stage: a slim server image without compilers, git and poetry, plus a separate `ci-image` target for CI tasks
+* Service version detection works when proxy_mock is installed as a library: first proxy_mock's own pyproject.toml, then the package metadata (previously `create_app()` failed without a pyproject.toml in the working directory)
+* README: a section on running without Docker (pip package plus a pytest fixture)
+* Lower dependency bounds were relaxed for compatibility when installed as a library: Python `>=3.11`, pydantic `>=2.6`, uvicorn `>=0.27`, requests `>=2.31`, aiocache `>=0.12.2`. FastAPI stays at `>=0.136`, because below that the service endpoint protection breaks
+* A regression test for service route protection (`tests/test_service_routes.py`)
+
+* Fixed a bug in full mock cleanup: runtime routes are now removed as well (previously a path kept answering with its mock after cleanup)
+* Fixed handling of malformed msgpack during configuration: it returns `400` instead of `500`
+* Removed unreachable code in binary data serialisation
+
+* Added a "Security" section to the README (no authentication, SSRF via `proxy_host`, sensitive data in traffic)
+* The API section of the README was simplified and brought up to date, with a link to the auto-generated OpenAPI docs (`/docs`, `/redoc`)
+* Increased test coverage, including the `AsyncProxyMock` async client
+
+Version 2.8.0
+=============
+
+* Migration to Python 3.14.6 with support for the free-threaded build (3.14.6t)
+* Updated FastAPI (>=0.136), uvicorn (>=0.44) and the remaining dependencies
+* TOML reading replaced with the stdlib `tomllib` (writing goes through `tomlkit` in the CI scripts)
+
+* The project structure was refactored:
+  * `app/` — application factory and lifespan
+  * `api/routes/` — HTTP routes
+  * `domain/` — schemas and domain constants
+  * `services/` — business logic (mock/proxy/rules/cache/parser/traffic)
+  * `repositories/` — in-memory stores
+  * `core/` — logging, settings, serialisation, time
+* `any_catcher.py` became a thin entrypoint
+* Reduced coupling and bloat in `utils.py`
+
+* Async upstream proxying via `httpx` instead of the blocking `requests` in the server
+* Traffic now stores the request time:
+  * `requested_at` (Europe/Moscow, ISO-8601)
+  * `requested_at_ts` (unix timestamp)
+* The traffic store is bounded: only the last 100 requests
+* Added concurrency protection (a lock) for the in-memory stores
+* Improved rule logic:
+  * `priority` support
+  * more stable condition matching
+* Added filters for `/traffic`: `path`, `method`, `limit`
+* Configurable request logging through `PROXY_MOCK_LOG_REQUESTS=full|minimal|off`
+
+* Sync client refactoring:
+  * less duplication between configure and patch
+  * better request/response handling
+* Added a new async client `AsyncProxyMock` built on `httpx`
+
+* Moved to public APIs, without relying on private fields such as `_dict` and `_url`
+* Behavioural compatibility was preserved for existing tests and mocking scenarios
+
+Version 2.5.4
+=============
+
+* Fixed the data type of the incoming request body
+
+Version 2.5.3
+=============
+
+* Fixed rule sorting
+
+Version 2.5.2
+=============
+
+* Mock rules are now sorted by creation time, newest first
+
+Version 2.5.1
+=============
+
+* Added proxying and delays inside mock rules
+
+Version 2.5.0
+=============
+
+* Updated helper packages and raised the minimum Python version to 3.10
+* Added caching of mocked responses
+* Added an endpoint for cache invalidation
+
+Version 2.4.3
+=============
+
+* Added the ability to pass extra information about a mock rule into traffic
+
+Version 2.4.2
+=============
+
+* Added the ability to pass HTTP request methods when configuring mock rules
+
+Version 2.4.1
+=============
+
+* Added the ability to specify the HTTP request method during configuration
+* Fixed coverage measurement for asynchronous code
+* `pyproject.toml` was converted to the new format used by the newer poetry
+* Added pre-commit to make linting easier
+
+Version 2.4.0
+=============
+
+* Merged the JSON and binary mock configuration endpoints into a single `/configure_mock`. By default client requests compress the payload into bytes and the server unpacks it back into a dict
+* Updated unit tests
+* Added msgpack, a library for working with binary data
+
+Version 2.3.1
+=============
+
+* Fixed automatic tag creation
+
+Version 2.3.0
+=============
+
+* Added new PATCH endpoints for updating already created mocks
+
+Version 2.2.0
+=============
+
+* Changed how rules work: when several conditions are given in one rule, the special response is returned only if all of them match
+* Added the ability to specify query parameters in rules
+* The Docker application now uses Python 3.13
+
+Version 2.1.2
+=============
+
+* Fixed a bug in how extra information was shown in traffic
+
+Version 2.1.1
+=============
+
+* Fixed formatting of incoming request bodies
+* Traffic now includes information about query parameters and the request method
+* Updated the returned content type for strings and protobufs
+
+Version 2.1.0
+=============
+
+* Added the ability to return different responses for one mock based on given conditions
+
+Version 2.0.0
+=============
+
+* Service routes were renamed:
+    /configure --> /configure_mock
+    /configure/binary --> /configure_mock/binary
+    /cleanup_params --> /traffic/clean
+    /cleanup_storage --> /storage/clean
+    /mock_params --> /traffic
+* The binary body of a mock configuration request must now be an encoded dict
+* Strict validation of POST requests
+* The client was moved into a separate directory (`/client/client.py`)
+* The server runs through uvicorn (ASGI) instead of gunicorn (WSGI)
+* FastAPI was integrated in place of Flask
+* Any request can now be mocked (the path is passed as a route argument)
+* The internal mock storage now only serves an informational purpose, while the mocks themselves are added dynamically through FastAPI
+
+Version 1.0.10
+==============
+
+* When a request is intercepted, its headers are recorded in mock_params
+
+Version 1.0.9
+=============
+
+* Removed unnecessary dependencies
+
+Version 1.0.8
+=============
+
+* Interception of requests without endpoints and recording of their data in a dedicated place
+* More methods supported for request interception
+* Changed the log format
+
+Version 1.0.7
+=============
+
+* Encode binary data as latin-1 for storage inside the proxy mock
+
+Version 1.0.6
+=============
+
+* Fixed a bug when reading the request parameter storage
+
+Version 1.0.5
+=============
+
+* Added the ability to proxy requests to a preconfigured host
+* A new key appeared in the `/configure` and `/configure/binary` endpoints: `proxy_host`
+* Added unit tests for the new and the existing functionality
+* Updated the service documentation
+
+Version 1.0.4
+=============
+
+* Added a new `/configure/binary` endpoint for configuring mocks with binary content
+* Added the ability to read data from the stores by a given key
+* Added the ability to delete data from the stores by a given key
+
+Version 1.0.3
+=============
+
+* Added the git module to the base Docker image
+* Hid unused dependencies of the client library
+
+Version 1.0.2
+=============
+
+* Allowed Python from version 3.9 onwards
+* Lowered dependency versions for maximum compatibility with other projects
+* Raised the poetry version to 1.8.2
+
+Version 1.0.1
+=============
+
+* Added the proxy mock client
+* Added tests for the proxy mock server
+* CI can run tests and linters, and build and publish the library
+* Added code linting

proxy_mock-2.10.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-2026 ivi.ru
+
+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.

proxy_mock-2.10.1/PKG-INFO

@@ -0,0 +1,352 @@
+Metadata-Version: 2.5
+Name: proxy_mock
+Version: 2.10.1
+Summary: Tool for proxying and mocking HTTP traffic
+Project-URL: Homepage, https://github.com/ivi-ru/proxy_mock
+Project-URL: Repository, https://github.com/ivi-ru/proxy_mock
+Project-URL: Changelog, https://github.com/ivi-ru/proxy_mock/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/ivi-ru/proxy_mock/issues
+Author-email: Andrey Ryabokon <aryabokon@ivi.ru>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: autotests,fastapi,http,mock,proxy,testing
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.11
+Requires-Dist: aiocache<0.13.0,>=0.12.2
+Requires-Dist: fastapi>=0.136.0
+Requires-Dist: httpx2<3.0.0,>=2.0.0
+Requires-Dist: msgpack<2.0.0,>=1.0.4
+Requires-Dist: pydantic<3.0.0,>=2.6.0
+Requires-Dist: requests<3.0.0,>=2.31.0
+Requires-Dist: uvicorn>=0.27.0
+Requires-Dist: yarl<2.0.0,>=1.8.0
+Description-Content-Type: text/markdown
+
+# 🛡️ Proxy Mock
+
+**Proxy Mock** is a tool that combines a proxy server and a mock server.
+It suits automated tests, integration scenarios and local debugging of service-to-service calls.
+
+---
+
+## 📋 Features
+
+- **Request proxying** to an upstream host (`proxy_host`)
+- **Endpoint mocking** with flexible response configuration
+- **Rules** for returning different responses on the same path
+- **Response delay** (`timeout`) and **caching** (`cache_time`)
+- **Traffic capture** of incoming requests for later inspection
+- **Bounded in-memory traffic storage** (the last 1000 records by default)
+
+---
+
+## ⚠️ Security
+
+The tool is meant for a **trusted, isolated test environment** and is not designed to be exposed publicly. Before deploying it, keep in mind:
+
+- **No authentication.** The service endpoints (`/configure_mock`, `/storage*`, `/traffic*`, `/cache/clean`) are open to anyone with network access. Anybody can create, read and delete mocks and traffic.
+- **SSRF via `proxy_host`.** By default a request can be proxied to **any** host, including your internal network and the cloud metadata address (`169.254.169.254`). The host list can be restricted with `PROXY_MOCK_ALLOWED_PROXY_HOSTS` (disabled by default, meaning any host is allowed).
+- **Traffic holds sensitive data.** `/traffic` stores the full headers and bodies of incoming requests (including `Authorization` and `Cookie`), and they can be read without authorisation. Requests that matched no mock (the `404` responses) are recorded as well.
+- **Loop protection.** Proxying "to self" is detected through the `x-proxy-mock-chain` marker header and is aborted with `508 Loop Detected`.
+
+**Recommendation:** run it inside a closed network perimeter only, never expose it to the internet, and narrow proxying with the allowlist where possible.
+
+---
+
+## ⬆️ Migrating from 1.0.1
+
+The previously published 1.0.1 ran on Flask. The current 2.10.1 runs on FastAPI, and four
+changes break compatibility. What to fix in a project upgrading from 1.0.1:
+
+| In 1.0.1 | In 2.10.1 |
+|---|---|
+| `GET /status` | `GET /proxy_mock` — no alias, the old path returns `404` |
+| `get_status()` | `get_proxy_mock()` — no alias |
+| `POST /configure_mock/binary` | `POST /configure_mock` with `Content-Type: application/octet-stream` |
+| `configure_binary_mock()` | `configure_mock()` — it serialises the body to msgpack itself |
+
+Error messages are now in English: a missing mock returns `{"error": "No mock found for /<path>"}`
+instead of the previous Russian text. Code that matches on the message text needs updating.
+
+Everything else stays compatible: `POST /configure_mock`, `GET /storage`, `POST /storage/clean`,
+`GET /traffic`, `POST /traffic/clean` and the methods `configure_mock()`, `get_traffic()`,
+`get_storage()`, `clean_storage()`, `clean_traffic()` work as before. `get_traffic()` gained
+optional filters (`path`, `method`, `limit`), and calling it without arguments is unchanged.
+
+Environment requirements changed too: Python >= 3.11 instead of 3.9, and uvicorn instead of
+gunicorn. The full history is in [CHANGELOG.md](CHANGELOG.md).
+
+---
+
+## 🚀 Getting started
+
+There are three ways to run proxy-mock:
+
+- **As a pip package** (simplest for automated tests, no Docker) — see "Running without Docker" below.
+- **In Docker** — see "Running in Docker" below.
+- **From source** (for working on proxy-mock itself) — see below.
+
+### 📦 Prerequisites (for running from source)
+
+Make sure the following are installed:
+
+- **Python** >= 3.11 (development happens on 3.14)
+- **uv** >= 0.9
+
+### ⚙️ Install and run from source
+
+1. **Install dependencies**
+
+    Create a virtual environment and install everything, including the dev group:
+    ```bash
+    uv sync
+    ```
+
+2. **Activate the virtual environment**
+
+    Activate the generated `.venv` (or prefix commands with `uv run`):
+    ```bash
+    source .venv/bin/activate
+    ```
+
+3. **Run the service**
+
+    Use the Makefile:
+    ```bash
+    make run
+    ```
+
+### 🐳 Running in Docker
+
+1. **Build the image and start the service**
+
+    ```bash
+    make docker_run
+    ```
+
+2. **Reach the service**
+
+    Once it is up, the service listens on:
+    ```
+    http://localhost:5000
+    ```
+
+### 🐍 Running without Docker (as a pip package)
+
+Docker is not required for automated tests: proxy-mock is published as an ordinary Python package containing both the server and the clients.
+
+```bash
+pip install proxy_mock
+uvicorn proxy_mock.any_catcher:app --host 0.0.0.0 --port 5000 --workers 1
+```
+
+You can also start it straight from your tests with a session-scoped pytest fixture (free port, automatic shutdown):
+
+```python
+import socket
+import threading
+import time
+
+import pytest
+import uvicorn
+
+from proxy_mock.app import create_app
+from proxy_mock.client import ProxyMock
+
+
+def _free_port() -> int:
+    with socket.socket() as sock:
+        sock.bind(("127.0.0.1", 0))
+        return sock.getsockname()[1]
+
+
+@pytest.fixture(scope="session")
+def proxy_mock_url():
+    port = _free_port()
+    config = uvicorn.Config(create_app(), host="127.0.0.1", port=port, log_level="warning")
+    server = uvicorn.Server(config)
+    thread = threading.Thread(target=server.run, daemon=True)
+    thread.start()
+
+    deadline = time.time() + 10
+    while not server.started:
+        if time.time() > deadline:
+            raise RuntimeError("proxy-mock failed to start in time")
+        time.sleep(0.05)
+
+    yield f"http://127.0.0.1:{port}"
+
+    server.should_exit = True
+    thread.join(timeout=5)
+
+
+@pytest.fixture(scope="session")
+def proxy_mock(proxy_mock_url):
+    return ProxyMock(proxy_mock_url)
+```
+
+Using it in a test:
+
+```python
+def test_external_service(proxy_mock):
+    proxy_mock.configure_mock(path="/external/api", body={"answer": 42})
+    # ... point the application under test at proxy_mock_url and assert on its behaviour
+    traffic = proxy_mock.get_traffic(path="/external/api")
+    assert traffic["count"] == 1
+```
+
+**Requirements and limitations:**
+
+- Python **>= 3.11** in the test environment; on older interpreters pip will not find an installable version.
+- The package pulls server dependencies (`fastapi>=0.136`, `pydantic>=2.6`, `uvicorn`, `httpx2`). If your test project pins older versions, the resolver may conflict. In that case install proxy-mock into a separate environment (`uv tool install` / `pipx`) and run it as a subprocess.
+- Under parallel runs (pytest-xdist) start one instance per worker: the mock and traffic stores are global to an instance.
+
+### Free-threaded Python (optional)
+
+The service also runs on a free-threaded build of the interpreter (3.14t). The official
+`python` images on Docker Hub do not publish free-threaded variants, so the interpreter has to
+be installed separately, for example with uv:
+
+```bash
+uv python install 3.14t
+uv sync --python 3.14t
+```
+
+Uvicorn should be started with a single worker (`--workers 1`). To confirm the GIL is really
+disabled:
+
+```bash
+python scripts/check_gil.py
+```
+
+### Environment variables
+
+| Variable | Values | Description |
+|----------|--------|-------------|
+| `PROXY_MOCK_LOG_REQUESTS` | `full` (default), `minimal`, `off` | Logging level for incoming requests |
+| `PROXY_MOCK_TRAFFIC_MAX` | integer > 0 (default `1000`) | Maximum number of records in the in-memory traffic store. Changeable at runtime via `POST /traffic/settings` |
+| `PROXY_MOCK_PROXY_TIMEOUT` | float, seconds (default `30`) | Timeout for outgoing proxied requests |
+| `PROXY_MOCK_ALLOWED_PROXY_HOSTS` | comma-separated host list (default: empty) | Allowlist of proxy targets. Empty means any host is allowed |
+| `PROXY_MOCK_RECORD_UNKNOWN_TRAFFIC` | `true` (default), `false` (`1/0`, `yes/no`, `on/off`) | Whether to record requests that matched no mock (the `404` response). Toggleable at runtime via `POST /traffic/settings` |
+
+---
+
+# 📡 API
+
+Full request and response schemas are available in the auto-generated documentation while the service is running:
+
+- **Swagger UI** — `http://localhost:5000/docs`
+- **ReDoc** — `http://localhost:5000/redoc`
+- **OpenAPI JSON** — `http://localhost:5000/openapi.json`
+
+A short reference and the key examples follow.
+
+## Service endpoints
+
+| Method | URL | Purpose | Success response |
+|--------|-----|---------|------------------|
+| `GET` | `/proxy_mock` | Server availability and an instance summary | `200` — `{"success": true, "version": "...", "python_version": "...", "mocks_count": N, "traffic_count": N, "traffic_max_items": N}` |
+| `POST` | `/configure_mock` | Create a mock | `201` — `{"success": true, "path": "...", "data": {...}}` |
+| `PATCH` | `/configure_mock` | Amend an existing mock (it must already exist) | `200` — same shape as POST |
+| `GET` | `/storage` | List mocks. Query: `path` filters by path | `200` — `{"success": true, "data": {...}}` |
+| `DELETE` | `/storage` | Delete mocks. Query: `path` for one mock; without `path` all of them | `200` — `{"success": true, "data": {...}}`; `404` if the given mock does not exist |
+| `POST` | `/storage/clean` | Deprecated alias of `DELETE /storage` (same effect) | `200` — `{"success": true, "data": {...}}` |
+| `GET` | `/traffic` | Show captured traffic. Query: `path`, `method`, `limit` | `200` — `{"success": true, "count": N, "data": [...]}` |
+| `POST` | `/traffic/clean` | Clear the traffic store | `200` — `{"success": true, "data": []}` |
+| `GET` | `/traffic/settings` | Current traffic recording settings | `200` — `{"success": true, "data": {"record_unknown_traffic": true, "max_items": 1000}}` |
+| `POST` | `/traffic/settings` | Change traffic settings. Body: `{"record_unknown_traffic": bool}` and/or `{"max_items": int > 0}`; the update is partial | `200` — same shape as GET; `400` on malformed JSON, `422` on an invalid or empty body |
+| `POST` | `/cache/clean` | Invalidate the entire cache | `200` — `{"success": true}` |
+| `*` | `/<any path>` | Catch-all: returns a mock, proxies, or `404` | depends on the configuration (see below) |
+
+**`/configure_mock` errors:**
+
+- `400` — empty body or malformed JSON/msgpack: `{"success": false, "error": "..."}`
+- `415` — unsupported `Content-Type` (`application/json` or `application/octet-stream` is required)
+- `422` — the body failed validation (for example the required `path` is missing): `{"success": false, "error": [...]}`
+
+## `/configure_mock` body
+
+Content type: `application/json` or `application/octet-stream` (msgpack). The PATCH body is identical to POST.
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `path` (required) | `string` | Path the mock applies to |
+| `methods` | `list[string]` | HTTP methods (all by default) |
+| `mock_data.body` | `string \| dict \| list \| bytes \| null` | Response body |
+| `mock_data.status_code` | `int` | Response code (default `200`) |
+| `mock_data.headers` | `dict` | Response headers |
+| `extra_info` | `dict` | Arbitrary metadata (ends up in traffic) |
+| `proxy_host` | `string` (**absolute URL**) | Proxy the request to this host |
+| `timeout` | `float` | Delay before responding, seconds |
+| `cache_time` | `int` | Response cache lifetime, seconds |
+| `rules` | `list[dict]` | Rules producing different responses on one path |
+
+Each entry in `rules`:
+
+- **`input_data`** — the match condition: `methods`, `body`, `headers`, `query`, `proxy_host` (absolute URL), `timeout`.
+- **`output_data`** — the response: `body`, `status_code`, `headers`.
+- **`extra_info`** — rule metadata (appears in traffic as `rule_extra_info`).
+- **`priority`** — `int`, higher values are checked earlier (default `0`).
+
+Rules are sorted by descending `priority`, then by insertion order; the first match wins.
+
+#### Example
+
+```json
+{
+    "path": "/test/endpoint",
+    "mock_data": {
+        "body": {"message": "Hello, World!"},
+        "status_code": 200,
+        "headers": {"Content-Type": "application/json"}
+    },
+    "extra_info": {"service": "example_service"},
+    "timeout": 1.5,
+    "cache_time": 600,
+    "rules": [
+        {
+            "input_data": {
+                "methods": ["POST", "PUT"],
+                "body": {"message": "any data"},
+                "headers": {"X-App-Version": "870"},
+                "query": {"user": "1"}
+            },
+            "output_data": {
+                "body": {"message": "other data"},
+                "status_code": 201,
+                "headers": {"X-Request-ID": "123456"}
+            },
+            "extra_info": {"rule_request_id": "Request-id"},
+            "priority": 10
+        }
+    ]
+}
+```
+
+## Catching requests on `/<path>`
+
+For any path that has a mock configured, the server processes the request in this order:
+
+1. Records the request in traffic.
+2. Checks the method, otherwise `405 Method Not Allowed`.
+3. Returns a cached response when `cache_time` is set and there is a cache hit.
+4. When `proxy_host` is set, proxies to the upstream host and returns its response (proxying "to self" is aborted with `508`). If the host is unreachable or does not resolve — `502`; if it did not answer within `PROXY_MOCK_PROXY_TIMEOUT` — `504`. Failed responses are not cached.
+5. Otherwise applies `timeout`, then `rules`, then the default `mock_data`.
+
+If no mock is configured for the path, the response is `404` with the body `{"error": "No mock found for /<path>"}`. By default such a request is recorded in traffic too (with `extra_info.status_code = 404`). Recording unknown traffic can be turned off with `PROXY_MOCK_RECORD_UNKNOWN_TRAFFIC=false` or at runtime via `POST /traffic/settings`.
+
+---
+
+## 📄 License
+
+[MIT](LICENSE)