mockserver-client 5.16.0__py3-none-any.whl

mockserver/websocket_client.py

@@ -0,0 +1,314 @@
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import uuid
+from typing import Any, Callable
+
+import websockets
+import websockets.client
+import websockets.exceptions
+
+from mockserver.exceptions import MockServerCallbackError, MockServerWebSocketError
+from mockserver.models import (
+    HttpRequest,
+    HttpRequestAndHttpResponse,
+    HttpResponse,
+    KeyToMultiValue,
+)
+
+logger = logging.getLogger(__name__)
+
+WEB_SOCKET_CORRELATION_ID_HEADER_NAME = "WebSocketCorrelationId"
+CLIENT_REGISTRATION_ID_HEADER = "X-CLIENT-REGISTRATION-ID"
+
+WEBSOCKET_PATH = "/_mockserver_callback_websocket"
+
+TYPE_HTTP_REQUEST = "org.mockserver.model.HttpRequest"
+TYPE_HTTP_RESPONSE = "org.mockserver.model.HttpResponse"
+TYPE_HTTP_REQUEST_AND_RESPONSE = "org.mockserver.model.HttpRequestAndHttpResponse"
+TYPE_CLIENT_ID_DTO = "org.mockserver.serialization.model.WebSocketClientIdDTO"
+TYPE_ERROR_DTO = "org.mockserver.serialization.model.WebSocketErrorDTO"
+
+MAX_RECONNECT_ATTEMPTS = 3
+
+
+def _extract_correlation_id(request: HttpRequest) -> str | None:
+    if request.headers is None:
+        return None
+    for header in request.headers:
+        if header.name == WEB_SOCKET_CORRELATION_ID_HEADER_NAME:
+            if header.values:
+                return header.values[0]
+    return None
+
+
+def _add_correlation_id_header(
+    message: HttpResponse | HttpRequest, correlation_id: str
+) -> HttpResponse | HttpRequest:
+    if message.headers is None:
+        message.headers = []
+    for header in message.headers:
+        if header.name == WEB_SOCKET_CORRELATION_ID_HEADER_NAME:
+            header.values = [correlation_id]
+            return message
+    message.headers.append(
+        KeyToMultiValue(name=WEB_SOCKET_CORRELATION_ID_HEADER_NAME, values=[correlation_id])
+    )
+    return message
+
+
+def _build_ws_message(type_name: str, value_dict: dict) -> str:
+    return json.dumps({
+        "type": type_name,
+        "value": json.dumps(value_dict),
+    })
+
+
+def _build_error_message(error_msg: str, correlation_id: str) -> str:
+    return json.dumps({
+        "type": TYPE_ERROR_DTO,
+        "value": json.dumps({
+            "message": error_msg,
+            "webSocketCorrelationId": correlation_id,
+        }),
+    })
+
+
+def _clean_context_path(context_path: str) -> str:
+    if not context_path:
+        return ""
+    if not context_path.startswith("/"):
+        return "/" + context_path
+    return context_path
+
+
+class MockServerWebSocketClient:
+    def __init__(self) -> None:
+        self._ws: websockets.client.WebSocketClientProtocol | None = None
+        self._client_id: str | None = None
+        self._response_callback: Callable | None = None
+        self._forward_callback: Callable | None = None
+        self._forward_response_callback: Callable | None = None
+        self._stopped = False
+        self._listen_task: asyncio.Task | None = None
+        self._host: str = ""
+        self._port: int = 0
+        self._context_path: str = ""
+        self._secure: bool = False
+        self._ssl_context: Any = None
+
+    @property
+    def is_connected(self) -> bool:
+        return self._ws is not None and self._ws.open
+
+    @property
+    def client_id(self) -> str | None:
+        return self._client_id
+
+    async def connect(
+        self,
+        host: str,
+        port: int,
+        context_path: str = "",
+        secure: bool = False,
+        ca_cert_path: str | None = None,
+        client_id: str | None = None,
+        tls_verify: bool = True,
+    ) -> str:
+        self._host = host
+        self._port = port
+        self._context_path = context_path
+        self._secure = secure
+
+        if secure:
+            import ssl
+            self._ssl_context = ssl.create_default_context()
+            if ca_cert_path:
+                self._ssl_context.load_verify_locations(ca_cert_path)
+            elif not tls_verify:
+                self._ssl_context.check_hostname = False
+                self._ssl_context.verify_mode = ssl.CERT_NONE
+
+        registration_id = client_id or str(uuid.uuid4())
+
+        await self._do_connect(registration_id)
+        return self._client_id
+
+    async def _do_connect(self, registration_id: str) -> None:
+        scheme = "wss" if self._secure else "ws"
+        path = _clean_context_path(self._context_path) + WEBSOCKET_PATH
+        uri = f"{scheme}://{self._host}:{self._port}{path}"
+
+        extra_headers = {CLIENT_REGISTRATION_ID_HEADER: registration_id}
+
+        self._ws = await websockets.client.connect(
+            uri,
+            additional_headers=extra_headers,
+            ssl=self._ssl_context if self._secure else None,
+            open_timeout=10,
+            ping_interval=20,
+            ping_timeout=20,
+            close_timeout=5,
+        )
+
+        registration_msg = await asyncio.wait_for(self._ws.recv(), timeout=10.0)
+        parsed = json.loads(registration_msg)
+        if parsed.get("type") == TYPE_CLIENT_ID_DTO:
+            value = json.loads(parsed["value"])
+            self._client_id = value["clientId"]
+        else:
+            raise MockServerWebSocketError(
+                f"Expected WebSocketClientIdDTO but received: {parsed.get('type')}"
+            )
+
+    def register_response_callback(self, callback_fn: Callable) -> None:
+        self._response_callback = callback_fn
+
+    def register_forward_callback(
+        self,
+        forward_fn: Callable,
+        response_fn: Callable | None = None,
+    ) -> None:
+        self._forward_callback = forward_fn
+        self._forward_response_callback = response_fn
+
+    async def listen(self) -> None:
+        reconnect_attempts = 0
+        while not self._stopped:
+            try:
+                async for raw_message in self._ws:
+                    await self._handle_message(raw_message)
+            except websockets.exceptions.ConnectionClosed:
+                if self._stopped:
+                    break
+                reconnect_attempts += 1
+                if reconnect_attempts > MAX_RECONNECT_ATTEMPTS:
+                    logger.error("Max reconnect attempts reached, giving up")
+                    break
+                logger.warning(
+                    "WebSocket disconnected, reconnecting (attempt %d/%d)",
+                    reconnect_attempts,
+                    MAX_RECONNECT_ATTEMPTS,
+                )
+                try:
+                    await self._do_connect(self._client_id or str(uuid.uuid4()))
+                    reconnect_attempts = 0
+                except Exception:
+                    logger.exception("Reconnection failed")
+                    await asyncio.sleep(1.0)
+            except Exception:
+                if self._stopped:
+                    break
+                logger.exception("Unexpected error in WebSocket listen loop")
+                break
+
+    async def _handle_message(self, raw_message: str) -> None:
+        parsed = json.loads(raw_message)
+        msg_type = parsed.get("type")
+        msg_value = parsed.get("value")
+
+        if msg_type == TYPE_CLIENT_ID_DTO:
+            value = json.loads(msg_value)
+            self._client_id = value["clientId"]
+            return
+
+        if msg_type == TYPE_HTTP_REQUEST:
+            request = HttpRequest.from_dict(json.loads(msg_value))
+            correlation_id = _extract_correlation_id(request)
+
+            if self._forward_callback is not None:
+                await self._handle_forward_request(request, correlation_id)
+            elif self._response_callback is not None:
+                await self._handle_response_request(request, correlation_id)
+            return
+
+        if msg_type == TYPE_HTTP_REQUEST_AND_RESPONSE:
+            req_and_resp = HttpRequestAndHttpResponse.from_dict(json.loads(msg_value))
+            correlation_id = _extract_correlation_id(req_and_resp.http_request)
+
+            if self._forward_response_callback is not None:
+                await self._handle_forward_response(req_and_resp, correlation_id)
+            return
+
+        logger.warning("Received unhandled WebSocket message type: %s", msg_type)
+
+    async def _handle_response_request(
+        self, request: HttpRequest, correlation_id: str | None
+    ) -> None:
+        try:
+            result = self._response_callback(request)
+            if asyncio.iscoroutine(result) or asyncio.isfuture(result):
+                result = await result
+            if not isinstance(result, HttpResponse):
+                raise MockServerCallbackError(
+                    f"Response callback must return HttpResponse, got {type(result)}"
+                )
+            if correlation_id:
+                _add_correlation_id_header(result, correlation_id)
+            msg = _build_ws_message(TYPE_HTTP_RESPONSE, result.to_dict())
+            await self._ws.send(msg)
+        except Exception as exc:
+            logger.exception("Error in response callback")
+            if correlation_id:
+                error_msg = _build_error_message(str(exc), correlation_id)
+                await self._ws.send(error_msg)
+
+    async def _handle_forward_request(
+        self, request: HttpRequest, correlation_id: str | None
+    ) -> None:
+        try:
+            result = self._forward_callback(request)
+            if asyncio.iscoroutine(result) or asyncio.isfuture(result):
+                result = await result
+            if not isinstance(result, HttpRequest):
+                raise MockServerCallbackError(
+                    f"Forward callback must return HttpRequest, got {type(result)}"
+                )
+            if correlation_id:
+                _add_correlation_id_header(result, correlation_id)
+            msg = _build_ws_message(TYPE_HTTP_REQUEST, result.to_dict())
+            await self._ws.send(msg)
+        except Exception as exc:
+            logger.exception("Error in forward callback")
+            if correlation_id:
+                error_msg = _build_error_message(str(exc), correlation_id)
+                await self._ws.send(error_msg)
+
+    async def _handle_forward_response(
+        self,
+        req_and_resp: HttpRequestAndHttpResponse,
+        correlation_id: str | None,
+    ) -> None:
+        try:
+            result = self._forward_response_callback(
+                req_and_resp.http_request, req_and_resp.http_response
+            )
+            if asyncio.iscoroutine(result) or asyncio.isfuture(result):
+                result = await result
+            if not isinstance(result, HttpResponse):
+                raise MockServerCallbackError(
+                    f"Forward response callback must return HttpResponse, got {type(result)}"
+                )
+            if correlation_id:
+                _add_correlation_id_header(result, correlation_id)
+            msg = _build_ws_message(TYPE_HTTP_RESPONSE, result.to_dict())
+            await self._ws.send(msg)
+        except Exception as exc:
+            logger.exception("Error in forward response callback")
+            if correlation_id:
+                error_msg = _build_error_message(str(exc), correlation_id)
+                await self._ws.send(error_msg)
+
+    async def close(self) -> None:
+        self._stopped = True
+        if self._listen_task and not self._listen_task.done():
+            self._listen_task.cancel()
+            try:
+                await self._listen_task
+            except asyncio.CancelledError:
+                pass
+        if self._ws and self._ws.open:
+            await self._ws.close()
+        self._ws = None

mockserver_client-5.16.0.dist-info/METADATA

@@ -0,0 +1,291 @@
+Metadata-Version: 2.4
+Name: mockserver-client
+Version: 5.16.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
+Project-URL: Homepage, https://www.mock-server.com
+Project-URL: Repository, https://github.com/mock-server/mockserver-monorepo
+Project-URL: Documentation, https://www.mock-server.com/mock_server/getting_started.html
+Project-URL: Changelog, https://www.mock-server.com/mock_server/changelog.html
+Project-URL: Bug Tracker, https://github.com/mock-server/mockserver-monorepo/issues
+Keywords: MockServer,HTTP Mock,Proxy,Testing,API,WebSocket,Callback,MCP,AI
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Testing
+Classifier: Topic :: Internet :: WWW/HTTP
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: websockets>=15.0.1
+Provides-Extra: dev
+Requires-Dist: pytest>=8.4.2; extra == "dev"
+Requires-Dist: pytest-asyncio>=1.2.0; extra == "dev"
+Requires-Dist: pytest-cov>=7.1.0; extra == "dev"
+
+# MockServer Python Client
+
+Python client for [MockServer](https://www.mock-server.com) with full WebSocket callback support.
+
+## Features
+
+- **Full REST API**: Create expectations, verify requests, clear/reset, retrieve recorded data
+- **Response Callbacks**: Register Python functions that dynamically generate responses via WebSocket
+- **Forward Callbacks**: Modify requests before they are forwarded to the real server
+- **Forward+Response Callbacks**: Modify both the forwarded request and the response
+- **Fluent API**: `client.when(request).respond(callback)` — mirrors the Java client
+- **Async + Sync**: Native asyncio API with a synchronous wrapper for non-async code
+- **Minimal Dependencies**: Only `websockets` (for callback support)
+
+## Installation
+
+```bash
+pip install mockserver-client
+```
+
+## Quick Start
+
+### Synchronous API
+
+```python
+from mockserver import MockServerClient, HttpRequest, HttpResponse
+
+client = MockServerClient("localhost", 1080)
+
+# Static expectation
+client.when(
+    HttpRequest.request("/api/users").with_method("GET")
+).respond(
+    HttpResponse.response('{"users": []}', status_code=200)
+)
+
+# Verify
+client.verify(
+    HttpRequest.request("/api/users").with_method("GET"),
+    VerificationTimes.at_least(1)
+)
+
+# Clean up
+client.reset()
+client.close()
+```
+
+### Context Manager
+
+```python
+with MockServerClient("localhost", 1080) as client:
+    client.when(
+        HttpRequest.request("/hello")
+    ).respond(
+        HttpResponse.response("world")
+    )
+```
+
+### Async API
+
+```python
+import asyncio
+from mockserver import AsyncMockServerClient, HttpRequest, HttpResponse
+
+async def main():
+    async with AsyncMockServerClient("localhost", 1080) as client:
+        await client.when(
+            HttpRequest.request("/api/data")
+        ).respond(
+            HttpResponse.response('{"key": "value"}')
+        )
+
+asyncio.run(main())
+```
+
+## Response Callbacks
+
+Register a Python function that generates responses dynamically when matching requests arrive:
+
+```python
+from mockserver import MockServerClient, HttpRequest, HttpResponse
+
+def handle_request(request):
+    if request.method == "POST":
+        return HttpResponse.response("created", status_code=201)
+    return HttpResponse.not_found_response()
+
+client = MockServerClient("localhost", 1080)
+client.mock_with_callback(
+    HttpRequest.request("/api/callback"),
+    handle_request
+)
+```
+
+Or with the fluent API:
+
+```python
+client.when(
+    HttpRequest.request("/api/callback")
+).respond(handle_request)
+```
+
+## Forward Callbacks
+
+Modify requests before they are forwarded to the real server:
+
+```python
+def modify_request(request):
+    return request.with_header("X-Forwarded", "true").with_path("/modified" + request.path)
+
+client.mock_with_forward_callback(
+    HttpRequest.request("/proxy/.*"),
+    modify_request
+)
+```
+
+## Forward+Response Callbacks
+
+Modify both the forwarded request and the response:
+
+```python
+def modify_request(request):
+    return request.with_header("X-Proxied", "true")
+
+def modify_response(request, response):
+    return response.with_header("X-Modified", "true")
+
+client.mock_with_forward_callback(
+    HttpRequest.request("/proxy/.*"),
+    modify_request,
+    modify_response
+)
+```
+
+## Verification
+
+```python
+from mockserver import VerificationTimes
+
+# Verify a request was received at least once
+client.verify(
+    HttpRequest.request("/api/users").with_method("GET"),
+    VerificationTimes.at_least(1)
+)
+
+# Verify exact count
+client.verify(
+    HttpRequest.request("/api/users"),
+    VerificationTimes.exactly(3)
+)
+
+# Verify request sequence (order matters)
+client.verify_sequence(
+    HttpRequest.request("/first"),
+    HttpRequest.request("/second"),
+    HttpRequest.request("/third"),
+)
+
+# Verify no interactions
+client.verify_zero_interactions()
+```
+
+## Retrieval
+
+```python
+# Get recorded requests
+requests = client.retrieve_recorded_requests(
+    HttpRequest.request("/api/.*")
+)
+
+# Get active expectations
+expectations = client.retrieve_active_expectations()
+
+# Get log messages
+logs = client.retrieve_log_messages()
+```
+
+## Control
+
+```python
+# Clear specific expectations
+client.clear(HttpRequest.request("/api/users"))
+
+# Clear by type
+client.clear(HttpRequest.request("/api/users"), clear_type="LOG")
+
+# Reset everything
+client.reset()
+
+# Bind additional ports
+client.bind(1081, 1082)
+
+# Check if running
+if client.has_started():
+    print("MockServer is running")
+
+# Stop
+client.stop()
+```
+
+## TLS Support
+
+```python
+# Uses system trust store (default — verifies certificates)
+client = MockServerClient("localhost", 1080, secure=True)
+
+# Custom CA certificate
+client = MockServerClient(
+    "localhost", 1080,
+    secure=True,
+    ca_cert_path="/path/to/ca.pem"
+)
+
+# Disable certificate verification (testing only — NOT recommended for production)
+client = MockServerClient(
+    "localhost", 1080,
+    secure=True,
+    tls_verify=False
+)
+```
+
+## Domain Model
+
+All domain model classes support builder-style chaining:
+
+```python
+request = (
+    HttpRequest.request("/api/users")
+    .with_method("POST")
+    .with_header("Content-Type", "application/json")
+    .with_header("Authorization", "Bearer token")
+    .with_body('{"name": "test"}')
+    .with_query_param("page", "1")
+    .with_secure(True)
+)
+
+response = (
+    HttpResponse.response()
+    .with_status_code(201)
+    .with_header("Location", "/api/users/1")
+    .with_body('{"id": 1, "name": "test"}')
+    .with_delay(Delay(time_unit="SECONDS", value=1))
+)
+```
+
+## Requirements
+
+- Python 3.9+
+- `websockets` >= 12.0 (for callback support)
+
+## License
+
+Apache 2.0
+
+## AI Assistant Integration
+
+MockServer includes a built-in [MCP](https://modelcontextprotocol.io) (Model Context Protocol) server that enables AI coding assistants to create expectations, verify requests, and debug HTTP traffic programmatically.
+
+- **MCP Endpoint:** `http://localhost:1080/mockserver/mcp`
+- **AI Documentation:** [llms.txt](https://www.mock-server.com/llms.txt)
+- **Setup Guide:** [AI Integration](https://www.mock-server.com/mock_server/ai_mcp_setup.html)

mockserver_client-5.16.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+mockserver/__init__.py,sha256=RtSodGAfkPBxKhCyWiYRjUi5WVf-XLfIDrP3fpWHyKk,1875
+mockserver/async_client.py,sha256=mabjFlRI8eC59FCCx2c2G9uAFCDsSkbcCTEaDjmzm0s,15005
+mockserver/client.py,sha256=etC8LV7qmFsnmWCkRzQfzj4dYaWVSaySDrdsxIvdFbc,6858
+mockserver/exceptions.py,sha256=aWrjzXgYgAHzLdRDhbcEFu1-Fojcd7bkH6UDy82Hlsw,339
+mockserver/fluent.py,sha256=HFa4mqtw2u_EWooS0xWlk8y9aSXk--U6F7z1UqUHWYA,4534
+mockserver/models.py,sha256=7IKvHzp16BOKQTJnUiJNnzvmLl7OSRB8QvheF0SRR5s,46520
+mockserver/websocket_client.py,sha256=p366vgMmoDfKOGWXOoab81yvXzVYZzS8Q5SmmpqpQSo,11397
+mockserver_client-5.16.0.dist-info/METADATA,sha256=4LLGgu7f5wjwx6YTkQnQkuu-ulN__IrhyQnS-3cStyY,7545
+mockserver_client-5.16.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+mockserver_client-5.16.0.dist-info/top_level.txt,sha256=MvCCh3LtK2uqvpmaxJVmKv3b1tlbpVFOCK8NFeDBJkU,11
+mockserver_client-5.16.0.dist-info/RECORD,,

mockserver_client-5.16.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

mockserver_client-5.16.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+mockserver