mockserver-client 7.0.0__tar.gz → 7.1.0__tar.gz

{mockserver_client-7.0.0 → mockserver_client-7.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mockserver-client
-Version: 7.0.0
+Version: 7.1.0
 Summary: Official Python client for MockServer — create expectations, verify requests, and register dynamic callbacks via WebSocket
 Author-email: James Bloom <jamesdbloom@gmail.com>
 License-Expression: Apache-2.0
@@ -273,6 +273,118 @@ response = (
 )
 ```
 
+## Interactive Breakpoints
+
+The client supports matcher-driven interactive breakpoints over the callback WebSocket. Register a breakpoint matcher to pause forwarded/proxied exchanges at specific phases and inspect/modify/continue them via callback handlers.
+
+### Register a breakpoint (sync client)
+
+```python
+from mockserver import MockServerClient, HttpRequest, HttpResponse
+
+client = MockServerClient("localhost", 1080)
+
+# REQUEST phase only
+bp_id = client.add_request_breakpoint(
+    HttpRequest(path="/api/.*"),
+    lambda request: request,  # continue unchanged (or return HttpResponse to abort)
+)
+
+# REQUEST + RESPONSE
+bp_id = client.add_request_and_response_breakpoint(
+    HttpRequest(path="/api/.*"),
+    lambda request: request,                      # REQUEST handler
+    lambda request, response: response,           # RESPONSE handler
+)
+
+# All phases with stream frame handler
+bp_id = client.add_breakpoint(
+    HttpRequest(path="/stream/.*"),
+    ["REQUEST", "RESPONSE", "RESPONSE_STREAM", "INBOUND_STREAM"],
+    request_handler=lambda request: request,
+    response_handler=lambda request, response: response,
+    stream_frame_handler=lambda frame: {"action": "CONTINUE"},
+    # Other actions: MODIFY (with body), DROP, INJECT (with body), CLOSE
+)
+```
+
+### Manage breakpoints
+
+```python
+# List all matchers
+matchers = client.list_breakpoint_matchers()  # {"matchers": [...]}
+
+# Remove a specific matcher
+client.remove_breakpoint_matcher(bp_id)
+
+# Clear all matchers
+client.clear_breakpoint_matchers()
+```
+
+The async client (`AsyncMockServerClient`) exposes the same methods as coroutines.
+
+## Start / Launch MockServer
+
+The Python client can download and launch a local MockServer instance directly -- no Java installation and no Docker required. The launcher downloads a self-contained platform bundle (`mockserver-<version>-<os>-<arch>`) from the GitHub Release, verifies its SHA-256, caches it per-user, and starts it.
+
+### Quick start
+
+```python
+from mockserver.launcher import start, MockServerProcess
+
+# Download (first run) and start MockServer on port 1080
+with start(port=1080) as server:
+    print(f"MockServer running on port {server.port}, PID {server.pid}")
+    # ... use MockServer ...
+# Server is stopped automatically when the context manager exits
+```
+
+### Just ensure the binary is present
+
+```python
+from mockserver.launcher import ensure_binary
+
+launcher_path = ensure_binary()  # returns Path to the launcher executable
+```
+
+### Specify a version
+
+```python
+from mockserver.launcher import start
+
+server = start(port=1080, version="7.1.0")
+# ...
+server.stop()
+```
+
+### API reference
+
+| Function / Class | Description |
+|---|---|
+| `ensure_binary(version=None, *, log=True)` | Download, verify, cache, and return the launcher `Path`. Defaults to the client's own version. |
+| `start(port, version=None, *, extra_args=None, log=True)` | Ensure the binary and start MockServer. Returns a `MockServerProcess`. |
+| `MockServerProcess` | Handle to the running process. Properties: `port`, `pid`, `launcher`, `returncode`. Methods: `stop(timeout=10.0)`. Supports `with` statement. |
+
+### Supported platforms
+
+| OS | Architecture |
+|---|---|
+| Linux | x86_64, aarch64 |
+| macOS (darwin) | x86_64, aarch64 |
+| Windows | x86_64, aarch64 |
+
+### Environment variables
+
+| Variable | Purpose |
+|---|---|
+| `MOCKSERVER_BINARY_BASE_URL` | Mirror host for the release assets (corporate / air-gapped networks) |
+| `MOCKSERVER_BINARY_CACHE` | Override the cache directory (default: `~/.cache/mockserver/binaries` on Unix) |
+| `MOCKSERVER_SKIP_BINARY_DOWNLOAD` | Fail instead of downloading (use with a pre-seeded cache in CI) |
+
+### Version
+
+By default the launcher downloads the MockServer version matching this client package (currently the version set in `pyproject.toml`). Pass an explicit `version` argument to override.
+
 ## Requirements
 
 - Python 3.9+

{mockserver_client-7.0.0 → mockserver_client-7.1.0}/README.md

@@ -243,6 +243,118 @@ response = (
 )
 ```
 
+## Interactive Breakpoints
+
+The client supports matcher-driven interactive breakpoints over the callback WebSocket. Register a breakpoint matcher to pause forwarded/proxied exchanges at specific phases and inspect/modify/continue them via callback handlers.
+
+### Register a breakpoint (sync client)
+
+```python
+from mockserver import MockServerClient, HttpRequest, HttpResponse
+
+client = MockServerClient("localhost", 1080)
+
+# REQUEST phase only
+bp_id = client.add_request_breakpoint(
+    HttpRequest(path="/api/.*"),
+    lambda request: request,  # continue unchanged (or return HttpResponse to abort)
+)
+
+# REQUEST + RESPONSE
+bp_id = client.add_request_and_response_breakpoint(
+    HttpRequest(path="/api/.*"),
+    lambda request: request,                      # REQUEST handler
+    lambda request, response: response,           # RESPONSE handler
+)
+
+# All phases with stream frame handler
+bp_id = client.add_breakpoint(
+    HttpRequest(path="/stream/.*"),
+    ["REQUEST", "RESPONSE", "RESPONSE_STREAM", "INBOUND_STREAM"],
+    request_handler=lambda request: request,
+    response_handler=lambda request, response: response,
+    stream_frame_handler=lambda frame: {"action": "CONTINUE"},
+    # Other actions: MODIFY (with body), DROP, INJECT (with body), CLOSE
+)
+```
+
+### Manage breakpoints
+
+```python
+# List all matchers
+matchers = client.list_breakpoint_matchers()  # {"matchers": [...]}
+
+# Remove a specific matcher
+client.remove_breakpoint_matcher(bp_id)
+
+# Clear all matchers
+client.clear_breakpoint_matchers()
+```
+
+The async client (`AsyncMockServerClient`) exposes the same methods as coroutines.
+
+## Start / Launch MockServer
+
+The Python client can download and launch a local MockServer instance directly -- no Java installation and no Docker required. The launcher downloads a self-contained platform bundle (`mockserver-<version>-<os>-<arch>`) from the GitHub Release, verifies its SHA-256, caches it per-user, and starts it.
+
+### Quick start
+
+```python
+from mockserver.launcher import start, MockServerProcess
+
+# Download (first run) and start MockServer on port 1080
+with start(port=1080) as server:
+    print(f"MockServer running on port {server.port}, PID {server.pid}")
+    # ... use MockServer ...
+# Server is stopped automatically when the context manager exits
+```
+
+### Just ensure the binary is present
+
+```python
+from mockserver.launcher import ensure_binary
+
+launcher_path = ensure_binary()  # returns Path to the launcher executable
+```
+
+### Specify a version
+
+```python
+from mockserver.launcher import start
+
+server = start(port=1080, version="7.1.0")
+# ...
+server.stop()
+```
+
+### API reference
+
+| Function / Class | Description |
+|---|---|
+| `ensure_binary(version=None, *, log=True)` | Download, verify, cache, and return the launcher `Path`. Defaults to the client's own version. |
+| `start(port, version=None, *, extra_args=None, log=True)` | Ensure the binary and start MockServer. Returns a `MockServerProcess`. |
+| `MockServerProcess` | Handle to the running process. Properties: `port`, `pid`, `launcher`, `returncode`. Methods: `stop(timeout=10.0)`. Supports `with` statement. |
+
+### Supported platforms
+
+| OS | Architecture |
+|---|---|
+| Linux | x86_64, aarch64 |
+| macOS (darwin) | x86_64, aarch64 |
+| Windows | x86_64, aarch64 |
+
+### Environment variables
+
+| Variable | Purpose |
+|---|---|
+| `MOCKSERVER_BINARY_BASE_URL` | Mirror host for the release assets (corporate / air-gapped networks) |
+| `MOCKSERVER_BINARY_CACHE` | Override the cache directory (default: `~/.cache/mockserver/binaries` on Unix) |
+| `MOCKSERVER_SKIP_BINARY_DOWNLOAD` | Fail instead of downloading (use with a pre-seeded cache in CI) |
+
+### Version
+
+By default the launcher downloads the MockServer version matching this client package (currently the version set in `pyproject.toml`). Pass an explicit `version` argument to override.
+
 ## Requirements
 
 - Python 3.9+

{mockserver_client-7.0.0 → mockserver_client-7.1.0}/mockserver/__init__.py

@@ -50,6 +50,14 @@ from mockserver.exceptions import (
 )
 from mockserver.client import MockServerClient
 from mockserver.async_client import AsyncMockServerClient
+from mockserver.launcher import (
+    MockServerProcess,
+    bundle_base_name,
+    cache_dir,
+    ensure_binary,
+    resolve_platform,
+    start as start_server,
+)
 
 __all__ = [
     "AfterAction",
@@ -100,4 +108,10 @@ __all__ = [
     "VerificationSequence",
     "VerificationTimes",
     "WebSocketMessage",
+    "MockServerProcess",
+    "bundle_base_name",
+    "cache_dir",
+    "ensure_binary",
+    "resolve_platform",
+    "start_server",
 ]

{mockserver_client-7.0.0 → mockserver_client-7.1.0}/mockserver/async_client.py

@@ -284,10 +284,12 @@ class AsyncMockServerClient:
 
     async def verify(
         self,
-        request: HttpRequest,
+        request: HttpRequest | None = None,
         times: VerificationTimes | None = None,
+        *,
+        response: HttpResponse | None = None,
     ) -> None:
-        verification = Verification(http_request=request, times=times)
+        verification = Verification(http_request=request, http_response=response, times=times)
         body = json.dumps(verification.to_dict())
         status, response_body = await self._request("PUT", "/mockserver/verify", body)
         if status == 406:
@@ -297,9 +299,14 @@ class AsyncMockServerClient:
                 f"Failed to verify (status={status}): {response_body}"
             )
 
-    async def verify_sequence(self, *requests: HttpRequest) -> None:
+    async def verify_sequence(
+        self,
+        *requests: HttpRequest,
+        responses: list[HttpResponse] | None = None,
+    ) -> None:
         verification = VerificationSequence(
-            http_requests=list(requests)
+            http_requests=list(requests) if requests else None,
+            http_responses=responses,
         )
         body = json.dumps(verification.to_dict())
         status, response_body = await self._request(
@@ -504,6 +511,180 @@ class AsyncMockServerClient:
         )
         return await self.upsert(expectation)
 
+    # -------------------------------------------------------------------
+    # Breakpoint matcher management
+    # -------------------------------------------------------------------
+
+    async def _ensure_breakpoint_websocket(self) -> MockServerWebSocketClient:
+        """Ensure a callback WS is connected for breakpoint use, returning it."""
+        # Serialise lazy creation so concurrent add_breakpoint coroutines
+        # (e.g. via asyncio.gather) cannot each create a duplicate breakpoint WS
+        # across the await in connect(). Creating/assigning the lock has no await
+        # between the check and the set, so it is atomic on the event loop.
+        lock = getattr(self, '_breakpoint_ws_lock', None)
+        if lock is None:
+            lock = asyncio.Lock()
+            self._breakpoint_ws_lock = lock  # type: ignore[attr-defined]
+        async with lock:
+            # Reuse the first WS client tagged as breakpoint, or create one
+            for ws in self._websocket_clients:
+                if getattr(ws, '_is_breakpoint_ws', False):
+                    return ws
+
+            ws_client = MockServerWebSocketClient()
+            await ws_client.connect(
+                self._host,
+                self._port,
+                self._context_path,
+                self._secure,
+                self._ca_cert_path,
+                tls_verify=self._tls_verify,
+            )
+            ws_client._is_breakpoint_ws = True  # type: ignore[attr-defined]
+            ws_client._listen_task = asyncio.create_task(ws_client.listen())
+            self._websocket_clients.append(ws_client)
+            return ws_client
+
+    async def add_breakpoint(
+        self,
+        matcher: HttpRequest,
+        phases: list[str],
+        request_handler: Callable | None = None,
+        response_handler: Callable | None = None,
+        stream_frame_handler: Callable | None = None,
+    ) -> str:
+        """Register a breakpoint matcher with callback handlers.
+
+        The callback WebSocket is opened lazily on the first call and reused.
+
+        Args:
+            matcher: the request definition to match (same as expectation matcher)
+            phases: list of phase strings: "REQUEST", "RESPONSE",
+                    "RESPONSE_STREAM", "INBOUND_STREAM"
+            request_handler: callable(HttpRequest) -> HttpRequest|HttpResponse
+                             for REQUEST phase (optional)
+            response_handler: callable(HttpRequest, HttpResponse) -> HttpResponse
+                              for RESPONSE phase (optional)
+            stream_frame_handler: callable(dict) -> dict for streaming phases
+                                  (optional). Receives PausedStreamFrameDTO dict,
+                                  returns StreamFrameDecisionDTO dict.
+
+        Returns:
+            The server-assigned breakpoint matcher id (UUID string).
+        """
+        if matcher is None:
+            raise ValueError("add_breakpoint requires a non-None matcher")
+        if not phases:
+            raise ValueError("add_breakpoint requires a non-empty phases list")
+
+        ws_client = await self._ensure_breakpoint_websocket()
+        client_id = ws_client.client_id
+
+        body = json.dumps({
+            "httpRequest": matcher.to_dict(),
+            "phases": phases,
+            "clientId": client_id,
+        })
+        status, response_body = await self._request(
+            "PUT", "/mockserver/breakpoint/matcher", body
+        )
+        if status >= 400:
+            raise MockServerError(
+                f"Failed to register breakpoint matcher (status={status}): {response_body}"
+            )
+
+        parsed = json.loads(response_body) if response_body else {}
+        breakpoint_id = parsed.get("id")
+        if not breakpoint_id:
+            raise MockServerError("Server did not return a breakpoint id")
+
+        # Install per-breakpoint-id handlers
+        if request_handler:
+            ws_client.set_breakpoint_request_handler(breakpoint_id, request_handler)
+        if response_handler:
+            ws_client.set_breakpoint_response_handler(breakpoint_id, response_handler)
+        if stream_frame_handler:
+            ws_client.set_breakpoint_stream_frame_handler(breakpoint_id, stream_frame_handler)
+
+        return breakpoint_id
+
+    async def add_request_breakpoint(
+        self,
+        matcher: HttpRequest,
+        request_handler: Callable,
+    ) -> str:
+        """Convenience: register a REQUEST-only breakpoint."""
+        return await self.add_breakpoint(
+            matcher, ["REQUEST"], request_handler=request_handler
+        )
+
+    async def add_request_and_response_breakpoint(
+        self,
+        matcher: HttpRequest,
+        request_handler: Callable,
+        response_handler: Callable,
+    ) -> str:
+        """Convenience: register a REQUEST+RESPONSE breakpoint."""
+        return await self.add_breakpoint(
+            matcher,
+            ["REQUEST", "RESPONSE"],
+            request_handler=request_handler,
+            response_handler=response_handler,
+        )
+
+    async def list_breakpoint_matchers(self) -> dict:
+        """List all registered breakpoint matchers.
+
+        Returns a dict: {"matchers": [{id, httpRequest, phases, clientId}, ...]}.
+        """
+        status, response_body = await self._request(
+            "GET", "/mockserver/breakpoint/matchers"
+        )
+        if status >= 400:
+            raise MockServerError(
+                f"Failed to list breakpoint matchers (status={status}): {response_body}"
+            )
+        return json.loads(response_body) if response_body else {}
+
+    async def remove_breakpoint_matcher(self, breakpoint_id: str) -> dict:
+        """Remove a breakpoint matcher by id.
+
+        Returns a dict: {"status": "removed", "id": "..."} or raises on 404.
+        """
+        if not breakpoint_id:
+            raise ValueError("remove_breakpoint_matcher requires a non-empty id")
+        body = json.dumps({"id": breakpoint_id})
+        status, response_body = await self._request(
+            "PUT", "/mockserver/breakpoint/matcher/remove", body
+        )
+        if status >= 400:
+            raise MockServerError(
+                f"Failed to remove breakpoint matcher (status={status}): {response_body}"
+            )
+        # Remove client-side handlers
+        for ws in self._websocket_clients:
+            if getattr(ws, '_is_breakpoint_ws', False):
+                ws.remove_breakpoint_handlers(breakpoint_id)
+        return json.loads(response_body) if response_body else {}
+
+    async def clear_breakpoint_matchers(self) -> dict:
+        """Clear all registered breakpoint matchers.
+
+        Returns a dict: {"status": "cleared", "count": N}.
+        """
+        status, response_body = await self._request(
+            "PUT", "/mockserver/breakpoint/matcher/clear"
+        )
+        if status >= 400:
+            raise MockServerError(
+                f"Failed to clear breakpoint matchers (status={status}): {response_body}"
+            )
+        # Clear client-side handlers
+        for ws in self._websocket_clients:
+            if getattr(ws, '_is_breakpoint_ws', False):
+                ws.clear_breakpoint_handlers()
+        return json.loads(response_body) if response_body else {}
+
     async def _register_websocket_callback(
         self,
         callback_type: str,

{mockserver_client-7.0.0 → mockserver_client-7.1.0}/mockserver/client.py

@@ -169,13 +169,19 @@ class MockServerClient:
 
     def verify(
         self,
-        request: HttpRequest,
+        request: HttpRequest | None = None,
         times: VerificationTimes | None = None,
+        *,
+        response: HttpResponse | None = None,
     ) -> None:
-        return self._run(self._async_client.verify(request, times))
+        return self._run(self._async_client.verify(request, times, response=response))
 
-    def verify_sequence(self, *requests: HttpRequest) -> None:
-        return self._run(self._async_client.verify_sequence(*requests))
+    def verify_sequence(
+        self,
+        *requests: HttpRequest,
+        responses: list[HttpResponse] | None = None,
+    ) -> None:
+        return self._run(self._async_client.verify_sequence(*requests, responses=responses))
 
     def verify_zero_interactions(self) -> None:
         return self._run(self._async_client.verify_zero_interactions())
@@ -237,6 +243,58 @@ class MockServerClient:
             self._async_client.mock_with_callback(request, callback, times, time_to_live)
         )
 
+    # -------------------------------------------------------------------
+    # Breakpoint matcher management
+    # -------------------------------------------------------------------
+
+    def add_breakpoint(
+        self,
+        matcher,
+        phases: list[str],
+        request_handler=None,
+        response_handler=None,
+        stream_frame_handler=None,
+    ) -> str:
+        """Register a breakpoint matcher with callback handlers.
+
+        Returns the server-assigned breakpoint matcher id (UUID string).
+        """
+        return self._run(
+            self._async_client.add_breakpoint(
+                matcher, phases, request_handler, response_handler, stream_frame_handler
+            )
+        )
+
+    def add_request_breakpoint(self, matcher, request_handler) -> str:
+        """Convenience: register a REQUEST-only breakpoint."""
+        return self._run(
+            self._async_client.add_request_breakpoint(matcher, request_handler)
+        )
+
+    def add_request_and_response_breakpoint(
+        self, matcher, request_handler, response_handler
+    ) -> str:
+        """Convenience: register a REQUEST+RESPONSE breakpoint."""
+        return self._run(
+            self._async_client.add_request_and_response_breakpoint(
+                matcher, request_handler, response_handler
+            )
+        )
+
+    def list_breakpoint_matchers(self) -> dict:
+        """List all registered breakpoint matchers."""
+        return self._run(self._async_client.list_breakpoint_matchers())
+
+    def remove_breakpoint_matcher(self, breakpoint_id: str) -> dict:
+        """Remove a breakpoint matcher by id."""
+        return self._run(
+            self._async_client.remove_breakpoint_matcher(breakpoint_id)
+        )
+
+    def clear_breakpoint_matchers(self) -> dict:
+        """Clear all registered breakpoint matchers."""
+        return self._run(self._async_client.clear_breakpoint_matchers())
+
     def mock_with_forward_callback(
         self,
         request: HttpRequest,