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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mockserver-client
-Version: 7.1.0
+Version: 7.2.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
@@ -352,7 +352,7 @@ launcher_path = ensure_binary()  # returns Path to the launcher executable
 ```python
 from mockserver.launcher import start
 
-server = start(port=1080, version="7.1.0")
+server = start(port=1080, version="7.2.0")
 # ...
 server.stop()
 ```

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

@@ -322,7 +322,7 @@ launcher_path = ensure_binary()  # returns Path to the launcher executable
 ```python
 from mockserver.launcher import start
 
-server = start(port=1080, version="7.1.0")
+server = start(port=1080, version="7.2.0")
 # ...
 server.stop()
 ```

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

@@ -3,6 +3,8 @@ from mockserver.models import (
     BinaryResponse,
     Body,
     ConnectionOptions,
+    CrossProtocolScenario,
+    CrossProtocolTrigger,
     Delay,
     DelayDistribution,
     DnsRecord,
@@ -26,12 +28,18 @@ from mockserver.models import (
     HttpSseResponse,
     HttpTemplate,
     HttpWebSocketResponse,
+    JsonPathBody,
     JsonRpcBody,
     KeyToMultiValue,
+    LoadProfile,
+    LoadScenario,
+    LoadStage,
+    LoadStep,
     OpenAPIDefinition,
     OpenAPIExpectation,
     Ports,
     RequestDefinition,
+    ResponseMode,
     SocketAddress,
     SseEvent,
     TimeToLive,
@@ -41,6 +49,37 @@ from mockserver.models import (
     VerificationTimes,
     WebSocketMessage,
 )
+from mockserver.llm import (
+    Completion,
+    ConversationPredicates,
+    EmbeddingResponse,
+    HttpLlmResponse,
+    IsolationSource,
+    LlmChaosProfile,
+    LlmConversationBuilder,
+    LlmFailoverBuilder,
+    LlmMockBuilder,
+    NormalizationOptions,
+    Provider,
+    Role,
+    StreamingPhysics,
+    ToolUse,
+    TurnBuilder,
+    Usage,
+    completion,
+    conversation,
+    cookie,
+    embedding,
+    header,
+    llm_failover,
+    llm_mock,
+    llm_response,
+    query_parameter,
+    streaming_physics,
+    time_to_first_token,
+    tool_use,
+    usage,
+)
 from mockserver.exceptions import (
     MockServerCallbackError,
     MockServerConnectionError,
@@ -49,6 +88,13 @@ from mockserver.exceptions import (
     MockServerWebSocketError,
 )
 from mockserver.client import MockServerClient
+from mockserver.mcp import (
+    McpMockBuilder,
+    McpPromptBuilder,
+    McpResourceBuilder,
+    McpToolBuilder,
+    mcp_mock,
+)
 from mockserver.async_client import AsyncMockServerClient
 from mockserver.launcher import (
     MockServerProcess,
@@ -65,6 +111,8 @@ __all__ = [
     "BinaryResponse",
     "Body",
     "ConnectionOptions",
+    "CrossProtocolScenario",
+    "CrossProtocolTrigger",
     "Delay",
     "DelayDistribution",
     "DnsRecord",
@@ -88,8 +136,47 @@ __all__ = [
     "HttpSseResponse",
     "HttpTemplate",
     "HttpWebSocketResponse",
+    "JsonPathBody",
     "JsonRpcBody",
     "KeyToMultiValue",
+    "LoadProfile",
+    "LoadScenario",
+    "LoadStage",
+    "LoadStep",
+    "Completion",
+    "ConversationPredicates",
+    "EmbeddingResponse",
+    "HttpLlmResponse",
+    "IsolationSource",
+    "LlmChaosProfile",
+    "LlmConversationBuilder",
+    "LlmFailoverBuilder",
+    "LlmMockBuilder",
+    "NormalizationOptions",
+    "Provider",
+    "Role",
+    "StreamingPhysics",
+    "ToolUse",
+    "TurnBuilder",
+    "Usage",
+    "completion",
+    "conversation",
+    "cookie",
+    "embedding",
+    "header",
+    "llm_failover",
+    "llm_mock",
+    "llm_response",
+    "query_parameter",
+    "streaming_physics",
+    "time_to_first_token",
+    "tool_use",
+    "usage",
+    "McpMockBuilder",
+    "McpPromptBuilder",
+    "McpResourceBuilder",
+    "McpToolBuilder",
+    "mcp_mock",
     "MockServerCallbackError",
     "MockServerClient",
     "MockServerConnectionError",
@@ -100,6 +187,7 @@ __all__ = [
     "OpenAPIExpectation",
     "Ports",
     "RequestDefinition",
+    "ResponseMode",
     "SocketAddress",
     "SseEvent",
     "TimeToLive",

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

@@ -23,6 +23,7 @@ from mockserver.models import (
     HttpRequest,
     HttpRequestAndHttpResponse,
     HttpResponse,
+    LoadScenario,
     OpenAPIExpectation,
     Ports,
     TimeToLive,
@@ -36,6 +37,59 @@ from mockserver.websocket_client import MockServerWebSocketClient
 logger = logging.getLogger(__name__)
 
 
+class AsyncScenarioHandle:
+    """An async handle to a single named stateful scenario on the server.
+
+    Obtained via :meth:`AsyncMockServerClient.scenario`. Wraps the
+    ``/mockserver/scenario/{name}`` control-plane endpoints. Each method returns
+    the server's JSON response as a dict (with ``scenarioName`` and
+    ``currentState`` keys).
+    """
+
+    def __init__(self, client: AsyncMockServerClient, name: str) -> None:
+        self._client = client
+        self._name = name
+
+    @property
+    def name(self) -> str:
+        return self._name
+
+    async def state(self) -> str | None:
+        """GET the current state of this scenario (``None`` if not yet set)."""
+        result = await self._client._scenario_request(
+            "GET", f"/mockserver/scenario/{urllib.parse.quote(self._name, safe="")}"
+        )
+        return result.get("currentState")
+
+    async def set(
+        self,
+        state: str,
+        transition_after_ms: int | None = None,
+        next_state: str | None = None,
+    ) -> dict:
+        """PUT to set this scenario's state, optionally scheduling a timed
+        transition to ``next_state`` after ``transition_after_ms`` milliseconds.
+        """
+        payload: dict = {"state": state}
+        if transition_after_ms is not None:
+            payload["transitionAfterMs"] = transition_after_ms
+        if next_state is not None:
+            payload["nextState"] = next_state
+        return await self._client._scenario_request(
+            "PUT",
+            f"/mockserver/scenario/{urllib.parse.quote(self._name, safe="")}",
+            json.dumps(payload),
+        )
+
+    async def trigger(self, new_state: str) -> dict:
+        """PUT an external trigger advancing this scenario to ``new_state``."""
+        return await self._client._scenario_request(
+            "PUT",
+            f"/mockserver/scenario/{urllib.parse.quote(self._name, safe="")}/trigger",
+            json.dumps({"newState": new_state}),
+        )
+
+
 class AsyncMockServerClient:
     def __init__(
         self,
@@ -45,6 +99,10 @@ class AsyncMockServerClient:
         secure: bool = False,
         ca_cert_path: str | None = None,
         tls_verify: bool = True,
+        client_cert_path: str | None = None,
+        client_key_path: str | None = None,
+        control_plane_bearer_token: str | None = None,
+        control_plane_bearer_token_supplier: Callable[[], str] | None = None,
     ) -> None:
         self._host = host
         self._port = port
@@ -52,6 +110,10 @@ class AsyncMockServerClient:
         self._secure = secure
         self._ca_cert_path = ca_cert_path
         self._tls_verify = tls_verify
+        self._client_cert_path = client_cert_path
+        self._client_key_path = client_key_path
+        self._control_plane_bearer_token = control_plane_bearer_token
+        self._control_plane_bearer_token_supplier = control_plane_bearer_token_supplier
         self._websocket_clients: list[MockServerWebSocketClient] = []
 
         scheme = "https" if secure else "http"
@@ -68,30 +130,57 @@ class AsyncMockServerClient:
             elif not tls_verify:
                 self._ssl_context.check_hostname = False
                 self._ssl_context.verify_mode = ssl.CERT_NONE
+            if client_cert_path:
+                # Load the client certificate chain (and private key) for mTLS.
+                self._ssl_context.load_cert_chain(
+                    certfile=client_cert_path, keyfile=client_key_path
+                )
+
+    def _control_plane_bearer(self) -> str | None:
+        """Resolve the control-plane bearer token for the current request.
+
+        The supplier (if configured) is evaluated per request so rotating /
+        short-lived tokens are picked up; otherwise the static token is used.
+        """
+        if self._control_plane_bearer_token_supplier is not None:
+            return self._control_plane_bearer_token_supplier()
+        return self._control_plane_bearer_token
 
     async def _request(
         self,
         method: str,
         path: str,
-        body: str | None = None,
+        body: str | bytes | None = None,
         query_params: dict[str, str] | None = None,
+        content_type: str = "application/json; charset=utf-8",
     ) -> tuple[int, str]:
         url = f"{self._base_url}{path}"
         if query_params:
             url = f"{url}?{urllib.parse.urlencode(query_params)}"
 
-        data = body.encode("utf-8") if body else None
+        if isinstance(body, bytes):
+            data = body
+        elif body:
+            data = body.encode("utf-8")
+        else:
+            data = None
         req = urllib.request.Request(url, data=data, method=method)
-        req.add_header("Content-Type", "application/json; charset=utf-8")
+        req.add_header("Content-Type", content_type)
+        bearer = self._control_plane_bearer()
+        if bearer:
+            req.add_header("Authorization", f"Bearer {bearer}")
 
         def _do_request() -> tuple[int, str]:
             try:
-                response = urllib.request.urlopen(
+                with urllib.request.urlopen(
                     req, context=self._ssl_context, timeout=60
-                )
-                return response.status, response.read().decode("utf-8")
+                ) as response:
+                    return response.status, response.read().decode("utf-8")
             except urllib.error.HTTPError as e:
-                return e.code, e.read().decode("utf-8")
+                # HTTPError is itself a closeable, response-like object; reading
+                # its body without closing leaks the underlying socket/fd.
+                with e:
+                    return e.code, e.read().decode("utf-8")
             except socket.timeout as e:
                 raise MockServerConnectionError(
                     f"Request to MockServer at {self._base_url} timed out: {e}"
@@ -227,6 +316,53 @@ class AsyncMockServerClient:
             )
         return json.loads(response_body) if response_body else {}
 
+    async def upload_grpc_descriptor(self, descriptor_set_bytes: bytes) -> None:
+        """Upload a compiled protobuf descriptor set so gRPC requests can be matched.
+
+        *descriptor_set_bytes* must be the raw bytes of a
+        ``FileDescriptorSet`` (e.g. the output of
+        ``protoc --descriptor_set_out=... --include_imports``). The bytes are
+        sent verbatim (not base64-encoded) as the request body.
+        """
+        if not descriptor_set_bytes:
+            raise MockServerError("descriptor set bytes must not be empty")
+        status, response_body = await self._request(
+            "PUT",
+            "/mockserver/grpc/descriptors",
+            descriptor_set_bytes,
+            content_type="application/octet-stream",
+        )
+        if status >= 400:
+            raise MockServerError(
+                f"Failed to upload gRPC descriptor (status={status}): {response_body}"
+            )
+
+    async def retrieve_grpc_services(self) -> list[dict]:
+        """Retrieve the gRPC services registered from uploaded descriptor sets.
+
+        Returns a list of service dicts, each with a ``name`` and a list of
+        ``methods`` (``name``, ``inputType``, ``outputType``,
+        ``clientStreaming``, ``serverStreaming``).
+        """
+        status, response_body = await self._request(
+            "PUT", "/mockserver/grpc/services"
+        )
+        if status >= 400:
+            raise MockServerError(
+                f"Failed to retrieve gRPC services (status={status}): {response_body}"
+            )
+        return json.loads(response_body) if response_body else []
+
+    async def clear_grpc_descriptors(self) -> None:
+        """Clear all uploaded gRPC descriptor sets and registered services."""
+        status, response_body = await self._request(
+            "PUT", "/mockserver/grpc/clear"
+        )
+        if status >= 400:
+            raise MockServerError(
+                f"Failed to clear gRPC descriptors (status={status}): {response_body}"
+            )
+
     async def set_service_chaos(
         self, host: str, chaos: HttpChaosProfile, ttl_millis: int | None = None
     ) -> dict:
@@ -282,6 +418,188 @@ class AsyncMockServerClient:
             )
         return json.loads(response_body) if response_body else {}
 
+    @staticmethod
+    def _load_generation_disabled_error(action: str, response_body: str) -> MockServerError:
+        return MockServerError(
+            f"Failed to {action}: load generation is disabled "
+            "(start MockServer with loadGenerationEnabled to enable it) "
+            f"(status=403): {response_body}"
+        )
+
+    async def load_scenario(self, scenario: LoadScenario | dict) -> dict:
+        """Register (load) a load-injection scenario in the server-side registry.
+
+        *scenario* is a :class:`LoadScenario` (or an equivalent dict) and must
+        carry a unique ``name``. Registration adds the scenario in the ``LOADED``
+        state but does **not** start generating load; it is allowed even when the
+        server was started without ``loadGenerationEnabled``.
+
+        Returns the JSON ``{"name": ..., "state": ...}`` for the registered
+        scenario. Use :meth:`start_load_scenarios` to begin generating load.
+        """
+        payload = scenario.to_dict() if hasattr(scenario, "to_dict") else scenario
+        body = json.dumps(payload)
+        status, response_body = await self._request(
+            "PUT", "/mockserver/loadScenario", body
+        )
+        if status >= 400:
+            raise MockServerError(
+                f"Failed to register load scenario (status={status}): {response_body}"
+            )
+        return json.loads(response_body) if response_body else {}
+
+    async def load_scenarios(self) -> dict:
+        """List every registered load scenario.
+
+        Returns ``{"scenarios": [{"name", "state", "definition", "status"?}, ...]}``.
+        """
+        status, response_body = await self._request("GET", "/mockserver/loadScenario")
+        if status >= 400:
+            raise MockServerError(
+                f"Failed to list load scenarios (status={status}): {response_body}"
+            )
+        return json.loads(response_body) if response_body else {}
+
+    async def get_load_scenario(self, name: str) -> dict:
+        """Retrieve a single registered load scenario by *name*.
+
+        Raises :class:`MockServerError` if the scenario does not exist (``404``).
+        """
+        status, response_body = await self._request(
+            "GET", f"/mockserver/loadScenario/{urllib.parse.quote(name, safe='')}"
+        )
+        if status == 404:
+            raise MockServerError(
+                f"Load scenario '{name}' not found (status=404): {response_body}"
+            )
+        if status >= 400:
+            raise MockServerError(
+                f"Failed to get load scenario '{name}' (status={status}): {response_body}"
+            )
+        return json.loads(response_body) if response_body else {}
+
+    async def delete_load_scenario(self, name: str) -> dict:
+        """Remove a single registered load scenario by *name* (stops it if running)."""
+        status, response_body = await self._request(
+            "DELETE", f"/mockserver/loadScenario/{urllib.parse.quote(name, safe='')}"
+        )
+        if status == 404:
+            raise MockServerError(
+                f"Load scenario '{name}' not found (status=404): {response_body}"
+            )
+        if status >= 400:
+            raise MockServerError(
+                f"Failed to delete load scenario '{name}' (status={status}): {response_body}"
+            )
+        return json.loads(response_body) if response_body else {}
+
+    async def clear_load_scenarios(self) -> dict:
+        """Remove every registered load scenario (stopping any that are running)."""
+        status, response_body = await self._request(
+            "DELETE", "/mockserver/loadScenario"
+        )
+        if status >= 400:
+            raise MockServerError(
+                f"Failed to clear load scenarios (status={status}): {response_body}"
+            )
+        return json.loads(response_body) if response_body else {}
+
+    async def start_load_scenarios(self, names: str | list[str]) -> dict:
+        """Start one or more registered load scenarios.
+
+        *names* may be a single scenario name or a list of names. The server must
+        have been started with ``loadGenerationEnabled``; otherwise this raises
+        :class:`MockServerError` reporting the ``403`` response. Honours each
+        scenario's ``startDelayMillis``.
+
+        Returns ``{"started": [{"name", "state"}, ...], "status": ...}``.
+        """
+        if isinstance(names, str):
+            names = [names]
+        body = json.dumps({"names": list(names)})
+        status, response_body = await self._request(
+            "PUT", "/mockserver/loadScenario/start", body
+        )
+        if status == 403:
+            raise self._load_generation_disabled_error(
+                "start load scenarios", response_body
+            )
+        if status == 404:
+            raise MockServerError(
+                f"Unknown load scenario (status=404): {response_body}"
+            )
+        if status >= 400:
+            raise MockServerError(
+                f"Failed to start load scenarios (status={status}): {response_body}"
+            )
+        return json.loads(response_body) if response_body else {}
+
+    async def _scenario_request(
+        self, method: str, path: str, body: str | None = None
+    ) -> dict:
+        status, response_body = await self._request(method, path, body)
+        if status >= 400:
+            raise MockServerError(
+                f"Scenario request failed (status={status}): {response_body}"
+            )
+        return json.loads(response_body) if response_body else {}
+
+    def scenario(self, name: str) -> AsyncScenarioHandle:
+        """Return a handle to the named stateful scenario, wrapping the
+        ``/mockserver/scenario/{name}`` control-plane endpoints.
+        """
+        return AsyncScenarioHandle(self, name)
+
+    async def scenarios(self) -> list[dict]:
+        """List every known scenario and its current state.
+
+        Returns a list of dicts each with ``scenarioName`` and ``currentState``.
+        """
+        result = await self._scenario_request("GET", "/mockserver/scenario")
+        return result.get("scenarios", [])
+
+    async def stop_load_scenarios(self, names: str | list[str] | None = None) -> dict:
+        """Stop running load scenarios.
+
+        *names* may be a single name, a list of names, or ``None`` to stop every
+        running scenario.
+
+        Returns ``{"stopped": [...], "status": ...}``.
+        """
+        if names is None:
+            payload: dict = {}
+        elif isinstance(names, str):
+            payload = {"names": [names]}
+        else:
+            payload = {"names": list(names)}
+        body = json.dumps(payload)
+        status, response_body = await self._request(
+            "PUT", "/mockserver/loadScenario/stop", body
+        )
+        if status >= 400:
+            raise MockServerError(
+                f"Failed to stop load scenarios (status={status}): {response_body}"
+            )
+        return json.loads(response_body) if response_body else {}
+
+    async def run_load_scenario(self, scenario: LoadScenario | dict) -> dict:
+        """Convenience: register *scenario* then immediately start it.
+
+        Requires the server to have been started with ``loadGenerationEnabled``
+        (the start step responds ``403`` otherwise). Returns the start result
+        (``{"started": [...], "status": ...}``).
+        """
+        registered = await self.load_scenario(scenario)
+        name = registered.get("name") if isinstance(registered, dict) else None
+        if not name:
+            payload = scenario.to_dict() if hasattr(scenario, "to_dict") else scenario
+            name = payload.get("name") if isinstance(payload, dict) else None
+        if not name:
+            raise MockServerError(
+                "Cannot run load scenario: scenario has no name to start"
+            )
+        return await self.start_load_scenarios(name)
+
     async def verify(
         self,
         request: HttpRequest | None = None,
@@ -385,6 +703,49 @@ class AsyncMockServerClient:
                 return [Expectation.from_dict(e) for e in parsed]
         return []
 
+    async def retrieve_expectations_as_code(
+        self, fmt: str = "java", request: HttpRequest | None = None
+    ) -> str:
+        """Retrieve the active expectations as MockServer SDK setup code.
+
+        Returns the builder code that recreates the expectations, generated in
+        the requested language (``fmt`` is one of ``java``, ``javascript``,
+        ``python``, ``go``, ``csharp``, ``ruby``, ``rust`` or ``php``).
+        """
+        body = json.dumps(request.to_dict()) if request else ""
+        status, response_body = await self._request(
+            "PUT",
+            "/mockserver/retrieve",
+            body,
+            {"type": "ACTIVE_EXPECTATIONS", "format": fmt.upper()},
+        )
+        if status >= 400:
+            raise MockServerError(
+                f"Failed to retrieve expectations as code (status={status}): {response_body}"
+            )
+        return response_body or ""
+
+    async def retrieve_recorded_expectations_as_code(
+        self, fmt: str = "java", request: HttpRequest | None = None
+    ) -> str:
+        """Retrieve the recorded (proxied) request/response pairs as MockServer
+        SDK setup code, generated in the requested language (``fmt`` is one of
+        ``java``, ``javascript``, ``python``, ``go``, ``csharp``, ``ruby``,
+        ``rust`` or ``php``).
+        """
+        body = json.dumps(request.to_dict()) if request else ""
+        status, response_body = await self._request(
+            "PUT",
+            "/mockserver/retrieve",
+            body,
+            {"type": "RECORDED_EXPECTATIONS", "format": fmt.upper()},
+        )
+        if status >= 400:
+            raise MockServerError(
+                f"Failed to retrieve recorded expectations as code (status={status}): {response_body}"
+            )
+        return response_body or ""
+
     async def retrieve_recorded_requests_and_responses(
         self, request: HttpRequest | None = None
     ) -> list[HttpRequestAndHttpResponse]: