proxy-mock 2.12.0__tar.gz → 2.13.0__tar.gz

{proxy_mock-2.12.0 → proxy_mock-2.13.0}/CHANGELOG.md

@@ -1,3 +1,22 @@
+Version 2.13.0
+==============
+
+Released on 2026-09-18.
+
+* Added opt-in administrative resource paths, enabled by `PROXY_MOCK_ADMIN_PREFIX`, with
+  matching `admin_prefix` options on `ProxyMock` and `AsyncProxyMock`. Legacy paths and their
+  JSON/msgpack contracts remain available. Aliases are disabled by default to avoid shadowing
+  existing user mocks. Invalid or overlapping prefixes fail at startup.
+* Every legacy administrative operation now carries a migration link and a RFC 9745
+  `Deprecation` date. This corrects the previous non-standard `true` value; handled error
+  responses are marked as well. Server warnings are limited to once per operation per process.
+* Added Python `DeprecationWarning` notices for the upcoming sync-client transport change and
+  explicit `cache_time` use. The synchronous client still returns `requests.Response`, and
+  cached responses and existing deprecated operations retain their 2.x behaviour.
+* Added `MIGRATING.md` covering the staged HTTP migration, transport compatibility, planned
+  installation split, cache removal and the required 3.0 record/replay and response sequences.
+  No 3.0 release date or automatic update check is introduced.
+
 Version 2.12.0
 ==============
 

proxy_mock-2.13.0/MIGRATING.md

@@ -0,0 +1,128 @@
+# Migrating from 2.x to 3.0
+
+Version 2.13 is the compatibility preparation release. **3.0 is planned, not released.**
+All existing 2.x routes, response bodies, status codes and client transports still work in
+2.13. Record & replay, response sequences and the client/server installation split belong to
+3.0; they are not available in 2.13.
+
+## Stay on 2.x until you are ready
+
+Pin `proxy_mock>=2.13,<3` in a test project that needs the existing contract. Upgrade the server
+first, then the clients. A 2.13 client without `admin_prefix` still uses the legacy paths and
+can talk to an older 2.x server. Keep `requests` behaviour until you have checked your callers.
+Already installed old versions do not acquire warnings remotely: read release notes and update
+to 2.13 to see these notices. There is no network update check or telemetry.
+
+## Try the new administrative paths in 2.13
+
+Aliases are **opt-in** so that an existing mock at `/__admin` is not unexpectedly shadowed.
+Start the server with:
+
+```sh
+PROXY_MOCK_ADMIN_PREFIX=/__admin proxy-mock --host 127.0.0.1 --port 5000
+```
+
+Use the same prefix explicitly in either client:
+
+```python
+from proxy_mock.client import ProxyMock, AsyncProxyMock
+
+with ProxyMock("http://127.0.0.1:5000", admin_prefix="/__admin") as client:
+    client.configure_mock(path="/inventory", body={"available": True})
+    assert client.execute_request("GET", "/inventory").json()["available"]
+
+# In async code:
+# async with AsyncProxyMock("http://127.0.0.1:5000", admin_prefix="/__admin") as client:
+#     await client.get_storage()
+```
+
+The prefix must be an absolute path of letters, digits, underscores, hyphens and optional
+path segments, without a trailing slash. It must not overlap an existing service path such as
+`/storage`, `/traffic`, `/docs` or their children. A prefix is not authentication. Reserve its
+administrative paths for the server and choose a prefix that does not collide with your mocks.
+Leaving the environment variable unset disables aliases; an explicitly empty value is invalid.
+Generic `execute_request()` calls always use the route you provide, without rewriting mock URLs.
+The pytest fixture continues using the legacy routes in 2.13; construct a client explicitly to
+exercise the aliases.
+
+| Legacy operation | 2.13 opt-in alias / planned 3.0 path |
+| --- | --- |
+| `GET /proxy_mock` | `GET /__admin` |
+| `POST /configure_mock` | `POST /__admin/mocks` |
+| `PATCH /configure_mock` | `PATCH /__admin/mocks` |
+| `GET /storage` | `GET /__admin/mocks` |
+| `DELETE /storage` | `DELETE /__admin/mocks` |
+| `POST /storage/clean` | `DELETE /__admin/mocks` |
+| `GET /traffic` | `GET /__admin/traffic` |
+| `DELETE /traffic`, `POST /traffic/clean` | `DELETE /__admin/traffic` |
+| `GET /traffic/settings` | `GET /__admin/settings` |
+| `PATCH /traffic/settings`, `POST /traffic/settings` | `PATCH /__admin/settings` |
+| `GET /storage/snapshot` | `GET /__admin/snapshot` |
+| `POST /storage/snapshot` | `POST /__admin/snapshot` |
+| `POST /cache/clean` | No replacement; removed with caching in 3.0 |
+
+In 2.13 aliases keep the existing JSON/msgpack bodies, query parameters and status codes.
+`?path=...`, traffic filters and snapshot `?mode=merge|replace` work unchanged. The full RESTful
+review for 3.0 may refine contracts; check the final 3.0 migration notes before upgrading.
+Old paths remain available even when aliases are enabled. A 3.0 server will default to
+`/__admin` and remove the legacy paths.
+
+`clean_storage(path=...)` still calls its legacy endpoint, even with `admin_prefix`, because
+it returns `200` with `success: false` for a missing mock. Switch to `delete_mock(path)`, which
+returns `404` when the mock is missing. `clean_cache()` also stays on its legacy path in 2.13.
+
+## Understand the warnings
+
+Every matched legacy service operation returns `Deprecation: @1789603200` (the announcement
+date, 2026-09-17 UTC) and a `Link` with `rel="deprecation"` pointing to this guide. The date
+syntax follows [RFC 9745](https://www.rfc-editor.org/rfc/rfc9745.html); it replaces the old
+non-standard `Deprecation: true` value. When aliases are enabled, another link with
+`rel="successor-version"` points to the replacement resource. Consult the table for the HTTP
+method: a URI alone does not tell you to change `POST` to `DELETE` or `PATCH`.
+The same notices accompany handled error responses. User mock responses are not marked.
+Aliases themselves have no route-deprecation header. Server warnings are logged once per
+operation per process, rather than for every request. No `Sunset` date is promised yet.
+
+Python emits `DeprecationWarning` for the synchronous client's upcoming transport change,
+`cache_time`, `clean_cache()` and `clean_storage(path=...)`. Python's standard warning filters
+control repetition and visibility; use `python -W default::DeprecationWarning -m pytest` to
+review them. Warnings do not change successful responses or retries. Projects treating warnings
+as errors should review these notices before enabling that policy for a dependency upgrade.
+
+## Synchronous client transport in 3.0
+
+In 2.13, `ProxyMock` still uses `requests.Session` and returns `requests.Response` from
+`execute_request()`. Async transport remains `httpx2`. In 3.0 both clients will use `httpx2`.
+Before migrating, audit code that relies on:
+
+- The concrete `requests.Response` type, `.ok`, response truth testing, or `isinstance` checks.
+  Prefer explicit `status_code` checks now, with the exact success range your test requires.
+- `requests` exceptions. The current sync transport wraps connection/timeouts in
+  `ProxyMockRequestError`; other transport exceptions can still come from `requests`.
+  The 3.0 exception contract must be documented and tested before release.
+- Request keyword arguments, body encoding, redirects, timeouts, streaming, cookies and
+  session customisation (including adapters and direct `.session` access). Do not assume
+  requests-specific arguments or defaults transfer unchanged to `httpx2`.
+
+Exact 3.0 transport defaults and exception mappings are not implemented by 2.13. They must be
+specified in this guide when 3.0 ships, with executable before/after examples.
+
+## Installation and startup in 3.0
+
+The planned base install, `proxy_mock`, contains only clients; use `proxy_mock[server]` when
+running the server, CLI or the pytest fixture that starts a local server. **Do not use this
+extra as a migration step in 2.13: that release still installs the server by default.**
+Switch existing uvicorn entry points from `proxy_mock.any_catcher:app` to the supported factory
+`uvicorn proxy_mock.app:create_app --factory`, or use the `proxy-mock` console command already
+available in 2.x. Only one worker is supported because storage is in process memory.
+
+## Response caching and new 3.0 features
+
+`cache_time`, `clean_cache()` and `POST /cache/clean` will be removed. Remove caching from static
+mocks now; their configured response already remains available until the mock is changed or
+removed. For cached upstream responses, stay on 2.x until record & replay is available, then
+explicitly record a response as a mock and replay it. There is no record & replay API in 2.13.
+
+Record & replay and ordered response sequences are required for 3.0. Their concrete API,
+sequence exhaustion/reset behaviour and examples will be documented with implementation.
+gRPC and an authentication token are outside the 3.0 scope.

{proxy_mock-2.12.0 → proxy_mock-2.13.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: proxy_mock
-Version: 2.12.0
+Version: 2.13.0
 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
@@ -40,7 +40,11 @@ Description-Content-Type: text/markdown
 **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.
 
-[Roadmap](ROADMAP.md) · [Contributing](CONTRIBUTING.md) · [Changelog](CHANGELOG.md) · [Security policy](SECURITY.md)
+[Migration to 3.0](MIGRATING.md) · [Roadmap](ROADMAP.md) · [Contributing](CONTRIBUTING.md) · [Changelog](CHANGELOG.md) · [Security policy](SECURITY.md)
+
+> **Preparing for 3.0:** 2.13 preserves the 2.x API and adds migration warnings and opt-in
+> administrative aliases. Pin `proxy_mock>=2.13,<3` to retain compatibility while upgrading.
+> See [Migrating from 2.x to 3.0](MIGRATING.md) for routes, client transport and installation.
 
 ## Quick start
 
@@ -288,6 +292,7 @@ Binary bodies cannot be written as JSON, so they travel base64-encoded in `body_
 
 | Variable | Values | Description |
 |----------|--------|-------------|
+| `PROXY_MOCK_ADMIN_PREFIX` | unset (aliases disabled in 2.13); e.g. `/__admin` | Opt-in administrative resource paths; old paths keep working. See [migration guide](MIGRATING.md) |
 | `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 `PATCH /traffic/settings` |
 | `PROXY_MOCK_PROXY_TIMEOUT` | float, seconds (default `30`) | Timeout for outgoing proxied requests |
@@ -323,8 +328,10 @@ A short reference and the key examples follow.
 | `GET` | `/traffic/settings` | Current traffic recording settings | `200` — `{"success": true, "data": {"record_unknown_traffic": true, "max_items": 1000}}` |
 | `PATCH` | `/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 |
 
-**Deprecated, removed in 3.0.** They still work and answer exactly as before, but send a
-`Deprecation: true` response header and a `Link` to the replacement:
+**All legacy administrative paths move in 3.0.** In 2.13 they keep their response bodies and
+status codes and return a `Deprecation` date header and a migration `Link`. The following
+action-style operations also have replacements already available in 2.x. See
+[the migration guide](MIGRATING.md) for opt-in `/__admin` aliases:
 
 | Method | URL | Replacement |
 |--------|-----|-------------|

{proxy_mock-2.12.0 → proxy_mock-2.13.0}/README.md

@@ -8,7 +8,11 @@
 **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.
 
-[Roadmap](ROADMAP.md) · [Contributing](CONTRIBUTING.md) · [Changelog](CHANGELOG.md) · [Security policy](SECURITY.md)
+[Migration to 3.0](MIGRATING.md) · [Roadmap](ROADMAP.md) · [Contributing](CONTRIBUTING.md) · [Changelog](CHANGELOG.md) · [Security policy](SECURITY.md)
+
+> **Preparing for 3.0:** 2.13 preserves the 2.x API and adds migration warnings and opt-in
+> administrative aliases. Pin `proxy_mock>=2.13,<3` to retain compatibility while upgrading.
+> See [Migrating from 2.x to 3.0](MIGRATING.md) for routes, client transport and installation.
 
 ## Quick start
 
@@ -256,6 +260,7 @@ Binary bodies cannot be written as JSON, so they travel base64-encoded in `body_
 
 | Variable | Values | Description |
 |----------|--------|-------------|
+| `PROXY_MOCK_ADMIN_PREFIX` | unset (aliases disabled in 2.13); e.g. `/__admin` | Opt-in administrative resource paths; old paths keep working. See [migration guide](MIGRATING.md) |
 | `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 `PATCH /traffic/settings` |
 | `PROXY_MOCK_PROXY_TIMEOUT` | float, seconds (default `30`) | Timeout for outgoing proxied requests |
@@ -291,8 +296,10 @@ A short reference and the key examples follow.
 | `GET` | `/traffic/settings` | Current traffic recording settings | `200` — `{"success": true, "data": {"record_unknown_traffic": true, "max_items": 1000}}` |
 | `PATCH` | `/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 |
 
-**Deprecated, removed in 3.0.** They still work and answer exactly as before, but send a
-`Deprecation: true` response header and a `Link` to the replacement:
+**All legacy administrative paths move in 3.0.** In 2.13 they keep their response bodies and
+status codes and return a `Deprecation` date header and a migration `Link`. The following
+action-style operations also have replacements already available in 2.x. See
+[the migration guide](MIGRATING.md) for opt-in `/__admin` aliases:
 
 | Method | URL | Replacement |
 |--------|-----|-------------|

proxy_mock-2.13.0/proxy_mock/api/routes/admin.py

@@ -0,0 +1,25 @@
+"""Opt-in 3.0 resource paths, retaining the existing 2.x request/response contracts."""
+
+from fastapi import APIRouter
+
+from proxy_mock.api.routes import configure, service, storage, traffic
+
+
+def create_admin_router(prefix: str) -> APIRouter:
+    router = APIRouter()
+    # Keep the full paths on the original router: runtime mock cleanup must never remove them.
+    for suffix, method, endpoint in [
+        ("", "GET", service.get_proxy_mock),
+        ("/mocks", "POST", configure.configure_mock),
+        ("/mocks", "PATCH", configure.patch_mock_configuration),
+        ("/mocks", "GET", storage.get_storage),
+        ("/mocks", "DELETE", storage.delete_storage),
+        ("/traffic", "GET", traffic.get_traffic),
+        ("/traffic", "DELETE", traffic.delete_traffic),
+        ("/settings", "GET", traffic.get_traffic_settings),
+        ("/settings", "PATCH", traffic.patch_traffic_settings),
+        ("/snapshot", "GET", storage.get_storage_snapshot),
+        ("/snapshot", "POST", storage.post_storage_snapshot),
+    ]:
+        router.add_api_route(prefix + suffix, endpoint, methods=[method], name="admin_" + endpoint.__name__)
+    return router

{proxy_mock-2.12.0 → proxy_mock-2.13.0}/proxy_mock/api/routes/configure.py

@@ -5,12 +5,13 @@ from fastapi import APIRouter, Request
 from fastapi.responses import JSONResponse
 from pydantic import ValidationError
 
+from proxy_mock.core.deprecation import LegacyAdminRoute
 from proxy_mock.domain.constants import ParseError
 from proxy_mock.domain.models import ConfigureMockRequestSchema
 from proxy_mock.services.mock_service import mock_initialization, patch_mock_data, return_mock_data
 from proxy_mock.services.request_parser import parse_configure
 
-router = APIRouter()
+router = APIRouter(route_class=LegacyAdminRoute, deprecated=True)
 
 
 @router.post("/configure_mock")

{proxy_mock-2.12.0 → proxy_mock-2.13.0}/proxy_mock/api/routes/service.py

@@ -3,9 +3,10 @@ import platform
 from fastapi import APIRouter, Request
 from fastapi.responses import JSONResponse
 
+from proxy_mock.core.deprecation import LegacyAdminRoute
 from proxy_mock.services.mock_service import count_mocks
 
-router = APIRouter()
+router = APIRouter(route_class=LegacyAdminRoute, deprecated=True)
 
 
 @router.get("/proxy_mock")

{proxy_mock-2.12.0 → proxy_mock-2.13.0}/proxy_mock/api/routes/storage.py

@@ -1,7 +1,7 @@
 from fastapi import APIRouter, Request
 from fastapi.responses import JSONResponse
 
-from proxy_mock.core.deprecation import mark_deprecated
+from proxy_mock.core.deprecation import LegacyAdminRoute
 from proxy_mock.core.serializers import convert_bytes_to_str
 from proxy_mock.services.mock_service import (
     cleanup_storage,
@@ -12,7 +12,7 @@ from proxy_mock.services.mock_service import (
 )
 from proxy_mock.services.snapshot import SnapshotError, export_snapshot, import_snapshot
 
-router = APIRouter()
+router = APIRouter(route_class=LegacyAdminRoute, deprecated=True)
 
 
 @router.get("/storage")
@@ -85,4 +85,4 @@ async def clean_storage(request: Request):
         result = await cleanup_storage(request.app)
 
     response = JSONResponse({"success": result, "data": convert_bytes_to_str(await return_storage())}, 200)
-    return mark_deprecated(response, "POST /storage/clean", "DELETE /storage")
+    return response

{proxy_mock-2.12.0 → proxy_mock-2.13.0}/proxy_mock/api/routes/traffic.py

@@ -4,10 +4,10 @@ from fastapi import APIRouter, Request
 from fastapi.responses import JSONResponse
 from pydantic import ValidationError
 
-from proxy_mock.core.deprecation import mark_deprecated
+from proxy_mock.core.deprecation import LegacyAdminRoute
 from proxy_mock.domain.models import TrafficSettingsSchema
 
-router = APIRouter()
+router = APIRouter(route_class=LegacyAdminRoute, deprecated=True)
 
 
 def _traffic_settings(request: Request) -> dict:
@@ -39,7 +39,7 @@ async def clean_traffic(request: Request):
     """Deprecated alias for clearing traffic. The RESTful variant is `DELETE /traffic`."""
     await request.app.state.traffic_store.clear()
     response = JSONResponse({"success": True, "data": []}, 200)
-    return mark_deprecated(response, "POST /traffic/clean", "DELETE /traffic")
+    return response
 
 
 @router.get("/traffic/settings")
@@ -60,7 +60,7 @@ async def patch_traffic_settings(request: Request):
 async def set_traffic_settings(request: Request):
     """Deprecated alias for updating the settings. The RESTful variant is `PATCH /traffic/settings`."""
     response = await _update_traffic_settings(request)
-    return mark_deprecated(response, "POST /traffic/settings", "PATCH /traffic/settings")
+    return response
 
 
 async def _update_traffic_settings(request: Request) -> JSONResponse:
@@ -95,4 +95,4 @@ async def _update_traffic_settings(request: Request) -> JSONResponse:
 async def clean_cache(request: Request):
     """Deprecated: response caching is removed in 3.0 together with this endpoint."""
     await request.app.state.cache.clear()
-    return mark_deprecated(JSONResponse({"success": True}, 200), "POST /cache/clean")
+    return JSONResponse({"success": True}, 200)

{proxy_mock-2.12.0 → proxy_mock-2.13.0}/proxy_mock/app/factory.py

@@ -5,10 +5,12 @@ import httpx2
 from fastapi import FastAPI, Request
 from fastapi.responses import JSONResponse
 
+from proxy_mock.api.routes.admin import create_admin_router
 from proxy_mock.api.routes.configure import router as configure_router
 from proxy_mock.api.routes.service import router as service_router
 from proxy_mock.api.routes.storage import router as storage_router
 from proxy_mock.api.routes.traffic import router as traffic_router
+from proxy_mock.client.migration import validate_admin_prefix
 from proxy_mock.core.logging import app_logger
 from proxy_mock.core.settings import get_version_from_pyproject, record_unknown_traffic_default
 from proxy_mock.repositories.traffic_store import TrafficStore
@@ -70,6 +72,10 @@ def create_app() -> ProxyMockApp:
     app = ProxyMockApp(title="Proxy Mock")
     app.state.version = get_version_from_pyproject(app.logger)
 
+    app.state.admin_prefix = validate_admin_prefix(os.getenv("PROXY_MOCK_ADMIN_PREFIX"))
+    if app.state.admin_prefix is not None:
+        app.include_router(create_admin_router(app.state.admin_prefix))
+
     app.include_router(service_router)
     app.include_router(configure_router)
     app.include_router(storage_router)

{proxy_mock-2.12.0 → proxy_mock-2.13.0}/proxy_mock/client/async_client.py

@@ -6,6 +6,7 @@ from urllib.parse import urlencode
 import httpx2
 import msgpack
 
+from proxy_mock.client.migration import MIGRATION_URL, service_endpoint, validate_admin_prefix
 from proxy_mock.client.service_endpoints import Endpoints
 
 CONFIGURE_CONTENT_TYPE = "application/octet-stream"
@@ -30,11 +31,15 @@ class AsyncProxyMockResponseError(Exception):
 
 
 class AsyncProxyMock:
-    def __init__(self, host: str, timeout: float = 10.0) -> None:
+    def __init__(self, host: str, timeout: float = 10.0, *, admin_prefix: str | None = None) -> None:
+        self.admin_prefix = validate_admin_prefix(admin_prefix)
         self.host = host.rstrip("/")
         self.timeout = timeout
         self._client = httpx2.AsyncClient(base_url=self.host, timeout=timeout)
 
+    def _service_endpoint(self, endpoint: str) -> str:
+        return service_endpoint(endpoint, self.admin_prefix)
+
     async def aclose(self) -> None:
         await self._client.aclose()
 
@@ -122,6 +127,11 @@ class AsyncProxyMock:
         if rules is not None:
             request_data["rules"] = rules
         if cache_time is not None:
+            warnings.warn(
+                f"cache_time is deprecated and will be removed in 3.0; see {MIGRATION_URL}",
+                DeprecationWarning,
+                stacklevel=3,
+            )
             request_data["cache_time"] = cache_time
 
         request_data.update(kwargs)
@@ -130,13 +140,15 @@ class AsyncProxyMock:
     async def _send_configure(self, method: HTTPMethod, payload: dict):
         return await self.execute_request_and_get_response_body(
             method=method,
-            route=Endpoints.CONFIGURE_MOCK,
+            route=self._service_endpoint(Endpoints.CONFIGURE_MOCK),
             content=msgpack.packb(payload),
             headers={"Content-Type": CONFIGURE_CONTENT_TYPE},
         )
 
     async def get_proxy_mock(self):
-        return await self.execute_request_and_get_response_body(HTTPMethod.GET, Endpoints.PROXY_MOCK)
+        return await self.execute_request_and_get_response_body(
+            HTTPMethod.GET, self._service_endpoint(Endpoints.PROXY_MOCK)
+        )
 
     async def configure_mock(
         self,
@@ -204,12 +216,12 @@ class AsyncProxyMock:
             **({"method": method} if method else {}),
             **({"limit": limit} if limit is not None else {}),
         }
-        full_path = f"{Endpoints.TRAFFIC}?{urlencode(query_params)}"
+        full_path = f"{self._service_endpoint(Endpoints.TRAFFIC)}?{urlencode(query_params)}"
         return await self.execute_request_and_get_response_body(HTTPMethod.GET, full_path)
 
     async def get_storage(self, path: str | None = None):
         query_params = {**({"path": path} if path else {})}
-        full_path = f"{Endpoints.STORAGE}?{urlencode(query_params)}"
+        full_path = f"{self._service_endpoint(Endpoints.STORAGE)}?{urlencode(query_params)}"
         return await self.execute_request_and_get_response_body(HTTPMethod.GET, full_path)
 
     async def clean_storage(self, path: str | None = None):
@@ -224,34 +236,42 @@ class AsyncProxyMock:
                 DeprecationWarning,
                 stacklevel=2,
             )
-            full_path = f"{Endpoints.STORAGE_CLEAN}?{urlencode({'path': path})}"
+            full_path = f"{self._service_endpoint(Endpoints.STORAGE_CLEAN)}?{urlencode({'path': path})}"
             return await self.execute_request_and_get_response_body(HTTPMethod.POST, full_path)
 
-        return await self.execute_request_and_get_response_body(HTTPMethod.DELETE, Endpoints.STORAGE)
+        return await self.execute_request_and_get_response_body(
+            HTTPMethod.DELETE, self._service_endpoint(Endpoints.STORAGE)
+        )
 
     async def export_mocks(self):
         """Export every configured mock as a snapshot document."""
-        return await self.execute_request_and_get_response_body(HTTPMethod.GET, Endpoints.STORAGE_SNAPSHOT)
+        return await self.execute_request_and_get_response_body(
+            HTTPMethod.GET, self._service_endpoint(Endpoints.STORAGE_SNAPSHOT)
+        )
 
     async def import_mocks(self, snapshot: dict, mode: str = "merge"):
         """Load a snapshot: `merge` keeps the configured mocks, `replace` clears them first."""
-        full_path = f"{Endpoints.STORAGE_SNAPSHOT}?{urlencode({'mode': mode})}"
+        full_path = f"{self._service_endpoint(Endpoints.STORAGE_SNAPSHOT)}?{urlencode({'mode': mode})}"
         return await self.execute_request_and_get_response_body(HTTPMethod.POST, full_path, json=snapshot)
 
     async def delete_mock(self, path: str):
-        full_path = f"{Endpoints.STORAGE}?{urlencode({'path': path})}"
+        full_path = f"{self._service_endpoint(Endpoints.STORAGE)}?{urlencode({'path': path})}"
         return await self.execute_request_and_get_response_body(HTTPMethod.DELETE, full_path)
 
     async def clean_traffic(self):
-        return await self.execute_request_and_get_response_body(HTTPMethod.DELETE, Endpoints.TRAFFIC)
+        return await self.execute_request_and_get_response_body(
+            HTTPMethod.DELETE, self._service_endpoint(Endpoints.TRAFFIC)
+        )
 
     async def get_traffic_settings(self):
-        return await self.execute_request_and_get_response_body(HTTPMethod.GET, Endpoints.TRAFFIC_SETTINGS)
+        return await self.execute_request_and_get_response_body(
+            HTTPMethod.GET, self._service_endpoint(Endpoints.TRAFFIC_SETTINGS)
+        )
 
     async def set_traffic_settings(self, record_unknown_traffic: bool | None = None, max_items: int | None = None):
         return await self.execute_request_and_get_response_body(
             HTTPMethod.PATCH,
-            Endpoints.TRAFFIC_SETTINGS,
+            self._service_endpoint(Endpoints.TRAFFIC_SETTINGS),
             json=_build_traffic_settings_payload(record_unknown_traffic, max_items),
         )
 
@@ -262,4 +282,6 @@ class AsyncProxyMock:
             DeprecationWarning,
             stacklevel=2,
         )
-        return await self.execute_request_and_get_response_body(HTTPMethod.POST, Endpoints.CACHE_CLEAN)
+        return await self.execute_request_and_get_response_body(
+            HTTPMethod.POST, self._service_endpoint(Endpoints.CACHE_CLEAN)
+        )

{proxy_mock-2.12.0 → proxy_mock-2.13.0}/proxy_mock/client/client.py

@@ -5,6 +5,7 @@ from urllib.parse import urlencode
 
 import msgpack
 
+from proxy_mock.client.migration import MIGRATION_URL
 from proxy_mock.client.route import Route
 from proxy_mock.client.service_endpoints import Endpoints
 
@@ -23,7 +24,9 @@ def _build_traffic_settings_payload(record_unknown_traffic: bool | None, max_ite
 
 class ProxyMock(Route):
     def get_proxy_mock(self):
-        return super().execute_request_and_get_response_body(HTTPMethod.GET, Endpoints.PROXY_MOCK)
+        return super().execute_request_and_get_response_body(
+            HTTPMethod.GET, self._service_endpoint(Endpoints.PROXY_MOCK)
+        )
 
     def _build_mock_request_data(
         self,
@@ -62,6 +65,11 @@ class ProxyMock(Route):
         if rules is not None:
             request_data["rules"] = rules
         if cache_time is not None:
+            warnings.warn(
+                f"cache_time is deprecated and will be removed in 3.0; see {MIGRATION_URL}",
+                DeprecationWarning,
+                stacklevel=3,
+            )
             request_data["cache_time"] = cache_time
 
         request_data.update(kwargs)
@@ -70,7 +78,7 @@ class ProxyMock(Route):
     def _send_configure(self, method: HTTPMethod, payload: dict):
         return super().execute_request_and_get_response_body(
             method=method,
-            route=Endpoints.CONFIGURE_MOCK,
+            route=self._service_endpoint(Endpoints.CONFIGURE_MOCK),
             data=msgpack.packb(payload),
             headers={"Content-Type": CONFIGURE_CONTENT_TYPE},
         )
@@ -141,12 +149,12 @@ class ProxyMock(Route):
             **({"method": method} if method else {}),
             **({"limit": limit} if limit is not None else {}),
         }
-        full_path = f"{Endpoints.TRAFFIC}?{urlencode(query_params)}"
+        full_path = f"{self._service_endpoint(Endpoints.TRAFFIC)}?{urlencode(query_params)}"
         return super().execute_request_and_get_response_body(HTTPMethod.GET, full_path)
 
     def get_storage(self, path: str | None = None):
         query_params = {**({"path": path} if path else {})}
-        full_path = f"{Endpoints.STORAGE}?{urlencode(query_params)}"
+        full_path = f"{self._service_endpoint(Endpoints.STORAGE)}?{urlencode(query_params)}"
         return super().execute_request_and_get_response_body(HTTPMethod.GET, full_path)
 
     def clean_storage(self, path: str | None = None):
@@ -161,34 +169,42 @@ class ProxyMock(Route):
                 DeprecationWarning,
                 stacklevel=2,
             )
-            full_path = f"{Endpoints.STORAGE_CLEAN}?{urlencode({'path': path})}"
+            full_path = f"{self._service_endpoint(Endpoints.STORAGE_CLEAN)}?{urlencode({'path': path})}"
             return super().execute_request_and_get_response_body(HTTPMethod.POST, full_path)
 
-        return super().execute_request_and_get_response_body(HTTPMethod.DELETE, Endpoints.STORAGE)
+        return super().execute_request_and_get_response_body(
+            HTTPMethod.DELETE, self._service_endpoint(Endpoints.STORAGE)
+        )
 
     def export_mocks(self):
         """Export every configured mock as a snapshot document."""
-        return super().execute_request_and_get_response_body(HTTPMethod.GET, Endpoints.STORAGE_SNAPSHOT)
+        return super().execute_request_and_get_response_body(
+            HTTPMethod.GET, self._service_endpoint(Endpoints.STORAGE_SNAPSHOT)
+        )
 
     def import_mocks(self, snapshot: dict, mode: str = "merge"):
         """Load a snapshot: `merge` keeps the configured mocks, `replace` clears them first."""
-        full_path = f"{Endpoints.STORAGE_SNAPSHOT}?{urlencode({'mode': mode})}"
+        full_path = f"{self._service_endpoint(Endpoints.STORAGE_SNAPSHOT)}?{urlencode({'mode': mode})}"
         return super().execute_request_and_get_response_body(HTTPMethod.POST, full_path, json=snapshot)
 
     def delete_mock(self, path: str):
-        full_path = f"{Endpoints.STORAGE}?{urlencode({'path': path})}"
+        full_path = f"{self._service_endpoint(Endpoints.STORAGE)}?{urlencode({'path': path})}"
         return super().execute_request_and_get_response_body(HTTPMethod.DELETE, full_path)
 
     def clean_traffic(self):
-        return super().execute_request_and_get_response_body(HTTPMethod.DELETE, Endpoints.TRAFFIC)
+        return super().execute_request_and_get_response_body(
+            HTTPMethod.DELETE, self._service_endpoint(Endpoints.TRAFFIC)
+        )
 
     def get_traffic_settings(self):
-        return super().execute_request_and_get_response_body(HTTPMethod.GET, Endpoints.TRAFFIC_SETTINGS)
+        return super().execute_request_and_get_response_body(
+            HTTPMethod.GET, self._service_endpoint(Endpoints.TRAFFIC_SETTINGS)
+        )
 
     def set_traffic_settings(self, record_unknown_traffic: bool | None = None, max_items: int | None = None):
         return super().execute_request_and_get_response_body(
             HTTPMethod.PATCH,
-            Endpoints.TRAFFIC_SETTINGS,
+            self._service_endpoint(Endpoints.TRAFFIC_SETTINGS),
             json=_build_traffic_settings_payload(record_unknown_traffic, max_items),
         )
 
@@ -199,4 +215,6 @@ class ProxyMock(Route):
             DeprecationWarning,
             stacklevel=2,
         )
-        return super().execute_request_and_get_response_body(HTTPMethod.POST, Endpoints.CACHE_CLEAN)
+        return super().execute_request_and_get_response_body(
+            HTTPMethod.POST, self._service_endpoint(Endpoints.CACHE_CLEAN)
+        )

proxy_mock-2.13.0/proxy_mock/client/migration.py

@@ -0,0 +1,42 @@
+"""Migration helpers shared by the clients without importing server dependencies."""
+
+import re
+
+MIGRATION_URL = "https://github.com/ivi-ru/proxy_mock/blob/main/MIGRATING.md"
+
+
+def validate_admin_prefix(prefix: str | None) -> str | None:
+    if prefix is None:
+        return None
+    if not re.fullmatch(r"/[A-Za-z0-9_-]+(?:/[A-Za-z0-9_-]+)*", prefix):
+        raise ValueError("admin_prefix must be an absolute path without trailing slash, query, or URL escapes")
+    # An alias must not replace a legacy service route or the built-in API documentation.
+    if prefix.split("/")[1] in {
+        "proxy_mock",
+        "configure_mock",
+        "storage",
+        "traffic",
+        "cache",
+        "docs",
+        "redoc",
+        "openapi.json",
+    }:
+        raise ValueError("admin_prefix overlaps an existing service path")
+    return prefix
+
+
+ADMIN_SUFFIXES = {
+    "/proxy_mock": "",
+    "/configure_mock": "/mocks",
+    "/storage": "/mocks",
+    "/traffic": "/traffic",
+    "/traffic/settings": "/settings",
+    "/storage/snapshot": "/snapshot",
+}
+
+
+def service_endpoint(endpoint: str, prefix: str | None) -> str:
+    # Removed operations keep their legacy path and semantics throughout 2.x.
+    if prefix is not None and endpoint in ADMIN_SUFFIXES:
+        return prefix + ADMIN_SUFFIXES[endpoint]
+    return endpoint

{proxy_mock-2.12.0 → proxy_mock-2.13.0}/proxy_mock/client/route.py

@@ -1,8 +1,11 @@
 import json
+import warnings
 from typing import Any
 
 import requests
 
+from proxy_mock.client.migration import MIGRATION_URL, service_endpoint, validate_admin_prefix
+
 
 class ProxyMockRequestError(Exception):
     """Error while performing a request to the proxy-mock server."""
@@ -13,11 +16,21 @@ class ProxyMockResponseError(Exception):
 
 
 class Route:
-    def __init__(self, host: str, timeout: float = 10.0) -> None:
+    def __init__(self, host: str, timeout: float = 10.0, *, admin_prefix: str | None = None) -> None:
+        self.admin_prefix = validate_admin_prefix(admin_prefix)
+        warnings.warn(
+            "ProxyMock will use httpx2 instead of requests in 3.0; response types, exceptions, "
+            f"and transport options will change. See {MIGRATION_URL}",
+            DeprecationWarning,
+            stacklevel=2,
+        )
         self.host = host.rstrip("/")
         self.timeout = timeout
         self.session = requests.Session()
 
+    def _service_endpoint(self, endpoint: str) -> str:
+        return service_endpoint(endpoint, self.admin_prefix)
+
     def _build_url(self, command: str) -> str:
         command = command.strip("/")
         return f"{self.host}/{command}"

proxy_mock-2.13.0/proxy_mock/core/deprecation.py

@@ -0,0 +1,51 @@
+"""Deprecation notices for the 3.0 migration (RFC 9745)."""
+
+from fastapi import Request, Response
+from fastapi.routing import APIRoute
+
+from proxy_mock.client.migration import ADMIN_SUFFIXES, MIGRATION_URL
+from proxy_mock.core.logging import app_logger
+
+REMOVED_IN = "3.0"
+# Announcement date: 2026-09-17 UTC. No removal date is promised by a Sunset header.
+DEPRECATION_DATE = "@1789603200"
+_warned: set[str] = set()
+
+
+def mark_deprecated(response: Response, endpoint: str, replacement: str | None = None) -> Response:
+    response.headers["Deprecation"] = DEPRECATION_DATE
+    links = [f'<{MIGRATION_URL}>; rel="deprecation"']
+    if replacement:
+        links.append(f'<{replacement}>; rel="successor-version"')
+    existing = response.headers.get("Link")
+    response.headers["Link"] = ", ".join(([existing] if existing else []) + links)
+    if endpoint not in _warned:
+        _warned.add(endpoint)
+        successor = f"; replacement resource: {replacement}" if replacement else ""
+        app_logger.warning(f"{endpoint} is deprecated and will be removed in {REMOVED_IN}{successor}; {MIGRATION_URL}")
+    return response
+
+
+class LegacyAdminRoute(APIRoute):
+    """Mark only a matched legacy service operation, never a user mock at the same path."""
+
+    def get_route_handler(self):
+        handler = super().get_route_handler()
+
+        async def deprecated_handler(request: Request) -> Response:
+            response = await handler(request)
+            prefix = request.app.state.admin_prefix
+            legacy_path = {"/storage/clean": "/storage", "/traffic/clean": "/traffic"}.get(self.path, self.path)
+            suffix = ADMIN_SUFFIXES.get(legacy_path)
+            replacement = prefix + suffix if prefix is not None and suffix is not None else None
+            return mark_deprecated(response, f"{request.method} {self.path}", replacement)
+
+        return deprecated_handler
+
+
+def warn_deprecated_field(field: str, detail: str) -> None:
+    """Warn once per process about a deprecated field in the configuration payload."""
+    if field in _warned:
+        return
+    _warned.add(field)
+    app_logger.warning(f"Field '{field}' is deprecated and will be removed in {REMOVED_IN}: {detail}; {MIGRATION_URL}")

{proxy_mock-2.12.0 → proxy_mock-2.13.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "proxy_mock"
-version = "2.12.0"
+version = "2.13.0"
 description = "Tool for proxying and mocking HTTP traffic"
 authors = [
     { name = "Andrey Ryabokon", email = "aryabokon@ivi.ru" }
@@ -61,7 +61,7 @@ build-backend = "hatchling.build"
 packages = ["proxy_mock"]
 
 [tool.hatch.build.targets.sdist]
-include = ["proxy_mock", "README.md", "CHANGELOG.md", "LICENSE", "pyproject.toml"]
+include = ["proxy_mock", "README.md", "CHANGELOG.md", "MIGRATING.md", "LICENSE", "pyproject.toml"]
 
 [tool.ruff]
 line-length = 120

proxy_mock-2.12.0/proxy_mock/core/deprecation.py

@@ -1,36 +0,0 @@
-"""Marking of endpoints that 3.0 removes.
-
-A deprecated endpoint keeps working unchanged; it only gains the RFC 8594 ``Deprecation``
-header, a ``Link`` to its replacement and a one-off warning in the log, so that the removal in
-3.0 does not come as a surprise.
-"""
-
-from fastapi import Response
-
-from proxy_mock.core.logging import app_logger
-
-REMOVED_IN = "3.0"
-
-_warned: set[str] = set()
-
-
-def mark_deprecated(response: Response, endpoint: str, replacement: str | None = None) -> Response:
-    response.headers["Deprecation"] = "true"
-    if replacement:
-        response.headers["Link"] = f'<{replacement}>; rel="successor-version"'
-
-    if endpoint not in _warned:
-        _warned.add(endpoint)
-        successor = f"; use {replacement} instead" if replacement else ""
-        app_logger.warning(f"{endpoint} is deprecated and will be removed in {REMOVED_IN}{successor}")
-
-    return response
-
-
-def warn_deprecated_field(field: str, detail: str) -> None:
-    """Warn once per process about a deprecated field in the configuration payload."""
-    if field in _warned:
-        return
-
-    _warned.add(field)
-    app_logger.warning(f"Field '{field}' is deprecated and will be removed in {REMOVED_IN}: {detail}")