mockstack 0.4.2__tar.gz → 0.5.1__tar.gz

{mockstack-0.4.2 → mockstack-0.5.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mockstack
-Version: 0.4.2
+Version: 0.5.1
 Summary: An API mocking workhorse
 License-Expression: MIT
 Project-URL: Homepage, https://github.com/adamhadani/mockstack
@@ -34,7 +34,17 @@ Dynamic: license-file
 
 An API mocking workhorse :racehorse:
 
-Enabling a sane development lifecycle for microservice-oriented architectures.
+Enabling a sane development lifecycle for microservice-oriented architectures and LLM-driven tool chains.
+
+Use mockstack for:
+
+* **Development** :pencil2:. Simulating HTTP-based interactions between a particular component you're developing or debugging locally and multiple other components it depends on during execution of a particular flow. You can create template-based mock responses, simulate creation of resources in a realistic way, as well as proxy to other services using a rich rules DSL. Full request and response metadata and payloads can be observed via OpenTelemetry integration.
+
+* **Integration Testing** :ok_hand:. Creating a consistent environment for running integration tests on a single component, using fixture responses.
+
+* **LLM-powered Workflows** :alien:. Speeding up development of LLM-based workflows and tools for use with frameworks such as [LangChain](https://python.langchain.com/docs/introduction/), [LangGraph](https://www.langchain.com/langgraph) and others. When developing LLM-driven execution graphs, you often want to have a consistent response from a tool while you're tuning prompts or debugging other aspects of a particular trace. `mockstack` can give you a solid foundation for this.
+
+* **Chaos Engineering** :boom:. mockstack can simulate various real-world runtime error scenarios such as timeouts, http error codes, and invalid response payloads. This can be a great way to do some upfront "chaos monkey" type of testing on software components.
 
 Highlights include:
 
@@ -57,6 +67,8 @@ or install into a persistent environment and add it to the PATH with:
 
 ## Usage
 
+See the [examples](https://github.com/adamhadani/mockstack/blob/main/examples/) directory for complete examples with documentation.
+
 Available configuration options are [here](https://github.com/adamhadani/mockstack/blob/main/mockstack/config.py).
 
 Setting individual options can be done either through an `.env` file, individual environment variables, or command-line arguments. For example:

{mockstack-0.4.2 → mockstack-0.5.1}/README.md

@@ -9,7 +9,17 @@
 
 An API mocking workhorse :racehorse:
 
-Enabling a sane development lifecycle for microservice-oriented architectures.
+Enabling a sane development lifecycle for microservice-oriented architectures and LLM-driven tool chains.
+
+Use mockstack for:
+
+* **Development** :pencil2:. Simulating HTTP-based interactions between a particular component you're developing or debugging locally and multiple other components it depends on during execution of a particular flow. You can create template-based mock responses, simulate creation of resources in a realistic way, as well as proxy to other services using a rich rules DSL. Full request and response metadata and payloads can be observed via OpenTelemetry integration.
+
+* **Integration Testing** :ok_hand:. Creating a consistent environment for running integration tests on a single component, using fixture responses.
+
+* **LLM-powered Workflows** :alien:. Speeding up development of LLM-based workflows and tools for use with frameworks such as [LangChain](https://python.langchain.com/docs/introduction/), [LangGraph](https://www.langchain.com/langgraph) and others. When developing LLM-driven execution graphs, you often want to have a consistent response from a tool while you're tuning prompts or debugging other aspects of a particular trace. `mockstack` can give you a solid foundation for this.
+
+* **Chaos Engineering** :boom:. mockstack can simulate various real-world runtime error scenarios such as timeouts, http error codes, and invalid response payloads. This can be a great way to do some upfront "chaos monkey" type of testing on software components.
 
 Highlights include:
 
@@ -32,6 +42,8 @@ or install into a persistent environment and add it to the PATH with:
 
 ## Usage
 
+See the [examples](https://github.com/adamhadani/mockstack/blob/main/examples/) directory for complete examples with documentation.
+
 Available configuration options are [here](https://github.com/adamhadani/mockstack/blob/main/mockstack/config.py).
 
 Setting individual options can be done either through an `.env` file, individual environment variables, or command-line arguments. For example:

mockstack-0.5.1/examples/filefixtures-with-templates/.env.example

@@ -0,0 +1,13 @@
+# Example environment variables for using filefixtures strategy
+
+# the strategy to use
+MOCKSTACK__STRATEGY = filefixtures
+
+# strategy-specific settings
+
+# base dir for all templates. Used by 'filefixtures' strategy
+# and other hybrid strategies utilizing templates.
+MOCKSTACK__TEMPLATES_DIR = "./templates/"
+
+# OpenTelemetry settings
+MOCKSTACK__OPENTELEMETRY__ENABLED = false

mockstack-0.5.1/examples/filefixtures-with-templates/README.md

@@ -0,0 +1,10 @@
+# filefixtures example
+
+This folder shows an example setup for using mockstack with the `filefixtures` strategy which lets you route
+requests to template files.
+
+The folder is comprised of the following:
+
+* An `.env.example` file which you would rename `.env` and contains the relevant configuration options needed to run. When you have that file in the working directory when invoking mockstack it will automatically pick up the settings from this file.
+* A `templates/` dir, pointed to be a configuration in the env file, which contains our templates. We have a few example templates showcasing some of the capabilities of template-based mocking. One template file shows how you can have Jinja2 templating conditionals in the template e.g. to handle different responses based on request query parameters. Another template shows the naming convention for templates that depend on an identifier embedded in the request URL, e.g. `GET
+    /someservice/api/v1/item/ae420979-33f3-4c99-bc42-9d7cdee5259e` would get routed to the template file `someservice-api-v1-item.ae420979-33f3-4c99-bc42-9d7cdee5259e.j2`. Multiple identifiers in the path are also supported and would appear in filenames separated by dots, according to the order in which they appear in the URL.

mockstack-0.5.1/examples/filefixtures-with-templates/templates/servicename-api-v1-items.j2

@@ -0,0 +1,19 @@
+{% if query.item_id == "533ec889-7c68-45c8-b21e-4a7e455de123" %}
+{
+    "items": [
+            "createdAt": "2023-05-02T11:48:16.708081+00:00",
+            "id": "533ec889-7c68-45c8-b21e-4a7e455de123",
+        },
+    ],
+    "count": 1,
+    "limit": 20,
+    "offset": 0
+}
+{% else %}
+{
+  "items": [],
+  "count": 0,
+  "limit": 20,
+  "offset": 0
+}
+{% endif %}

mockstack-0.5.1/examples/filefixtures-with-templates/templates/servicename2-api-v2-user.533ec889-7c68-45c8-b21e-4a7e455d1234.j2

@@ -0,0 +1,14 @@
+{
+  "address": {
+    "city": "San Francisco",
+    "country": "United States",
+    "region": "California",
+    "streetAddress1": "123 market st.",
+    "streetAddress2": "null",
+    "zipCode": ""
+  },
+  "aliases": [],
+  "id": "533ec889-7c68-45c8-b21e-4a7e455d1234",
+  "name": "John Doe",
+  "updatedAt": "2025-04-15T18:34:17.067320+00:00"
+}

mockstack-0.5.1/examples/proxyrules-with-rules-file/.env.example

@@ -0,0 +1,13 @@
+# Example environment variables for using filefixtures strategy
+
+# the strategy to use
+MOCKSTACK__STRATEGY = proxyrules
+
+# strategy-specific settings
+
+MOCKSTACK__PROXYRULES_RULES_FILENAME = "./proxyrules.yml"
+MOCKSTACK__PROXYRULES_SIMULATE_CREATE_ON_MISSING = true
+
+
+# OpenTelemetry settings
+MOCKSTACK__OPENTELEMETRY__ENABLED = false

mockstack-0.5.1/examples/proxyrules-with-rules-file/README.md

@@ -0,0 +1,15 @@
+# proxyrules
+
+This example shows how to use the `proxyrules` strategy. This strategy lets you define rules in a YAML-based microformat that control how to proxy requests coming into mockstack to the other services.
+
+* The included `.env.example` file should be renamed `.env` and contains the needed configuration to use this strategy and point to the rules file.
+* The rules file `rules.yml` showcases some of the capabilities supported for rule-based proxying.
+
+
+Some of the notable features for this strategy are:
+
+* Can configure whether proxuying is done via Http redirects (Temporary Redirect, Permanent Redirect) or reverse proxying (e.g. silently re-routing request). Default is to reverse proxy.
+* Can configure rules per URL mask and optionally limit a rule to specific HTTP methods.
+* Can use regular expression capture groups to refer to matched groups in the "pattern" field when constructring the destination URL.
+* All request metadata and content, including headers, query parameters, and request body when applicable (e.g. for POSTs) will be proxied through.
+* Can simulate creation of resources for cases where we do not wish to proxy the request to a "real" service where creation might have undesirable sideeffects, and instead wish to simply simulate a realistic flow of creating a new resource. This is powered by the same mixin functionality thats used by the other strategies for simulation creation.

mockstack-0.5.1/examples/proxyrules-with-rules-file/rules.yml

@@ -0,0 +1,13 @@
+rules:
+  - name: someservice-get
+    method: GET
+    pattern: ^/someservice/(.*)
+    replacement: https://someservice.development.mycoolstartup.io/\1
+  - name: someservice-items-search
+    method: POST
+    pattern: ^/someservice/api/v1/items_search
+    replacement: https://someservice.development.mycoolstartup.io/api/v1/items_search
+  - name: someotherservice-get
+    method: GET
+    pattern: ^/someotherservice/(.*)
+    replacement: https://someotherservice.development.mycoolstartup.io/\1

{mockstack-0.4.2 → mockstack-0.5.1}/mockstack/config.py

@@ -68,6 +68,9 @@ class Settings(BaseSettings):
     # or reverse proxy the request to the target URL "silently".
     proxyrules_redirect_via: ProxyRulesRedirectVia = ProxyRulesRedirectVia.REVERSE_PROXY
 
+    # Default timeout for reverse proxy requests. given in seconds. None disables timeouts.
+    proxyrules_reverse_proxy_timeout: float | None = 10.0
+
     # controls behavior of proxying. Whether to simulate creation of resources
     # when a POST request is made to a resource that doesn't match any rules..
     proxyrules_simulate_create_on_missing: CliImplicitFlag[bool] = False

{mockstack-0.4.2 → mockstack-0.5.1}/mockstack/constants.py

@@ -20,3 +20,6 @@ class ProxyRulesRedirectVia(StrEnum):
     HTTP_TEMPORARY_REDIRECT = "http_307_temporary"
     HTTP_PERMANENT_REDIRECT = "http_301_permanent"
     REVERSE_PROXY = "reverse_proxy"
+
+
+SENSITIVE_HEADERS = ["authorization", "cookie", "set-cookie"]

{mockstack-0.4.2 → mockstack-0.5.1}/mockstack/lifespan.py

@@ -10,6 +10,20 @@ from mockstack.config import Settings
 from mockstack.display import announce
 
 
+def logging_dict_config_from(settings: Settings) -> dict:
+    """Get the logging config from the settings."""
+
+    def enable_debug_logging(settings: Settings):
+        """Enable verbose debug logging."""
+        settings.logging["handlers"]["console"]["level"] = DEBUG
+
+    if settings.debug:
+        # Enable verbose debug logging if debug mode is set.
+        enable_debug_logging(settings)
+
+    return settings.logging
+
+
 def lifespan_provider(
     settings: Settings,
 ) -> Callable:
@@ -21,11 +35,8 @@ def lifespan_provider(
 
         This is the context manager that FastAPI will use to manage the lifecycle of the application.
         """
-        if settings.debug:
-            # Enable verbose debug logging if debug mode is set.
-            settings.logging["handlers"]["console"]["level"] = DEBUG
 
-        config.dictConfig(settings.logging)
+        config.dictConfig(logging_dict_config_from(settings))
 
         announce(app, settings)
 

mockstack-0.5.1/mockstack/middleware.py

@@ -0,0 +1,53 @@
+"""Middleware definitionsfor the mockstack app."""
+
+import time
+
+from fastapi import FastAPI, Request
+from opentelemetry import trace
+from opentelemetry.propagate import extract
+
+from mockstack.config import Settings
+from mockstack.constants import SENSITIVE_HEADERS
+from mockstack.telemetry import (
+    span_name_for,
+    with_request_attributes,
+    with_response_attributes,
+    with_response_body,
+)
+
+
+def middleware_provider(app: FastAPI, settings: Settings) -> None:
+    """Instrument the middlewares to the mockstack app."""
+
+    @app.middleware("http")
+    async def add_process_time_header(request: Request, call_next):
+        start_time = time.time()
+        response = await call_next(request)
+        process_time = time.time() - start_time
+        response.headers["X-Process-Time"] = str(process_time)
+        return response
+
+    @app.middleware("http")
+    async def instrument_opentelemetry(request: Request, call_next):
+        tracer = trace.get_tracer(__name__)
+        ctx = extract(request.headers)
+        with tracer.start_as_current_span(span_name_for(request), context=ctx) as span:
+            span = with_request_attributes(
+                request, span, sensitive_headers=SENSITIVE_HEADERS
+            )
+
+            # Make the current opentelemetry span available to the request.
+            # This is useful for strategies that need to add custom attributes
+            # to the span associated with the request.
+            request.state.span = span
+
+            response = await call_next(request)
+
+            span = with_response_attributes(
+                response, span, sensitive_headers=SENSITIVE_HEADERS
+            )
+
+            if settings.opentelemetry.capture_response_body:
+                response, span = await with_response_body(response, span)
+
+            return response

{mockstack-0.4.2 → mockstack-0.5.1}/mockstack/strategies/base.py

@@ -17,3 +17,12 @@ class BaseStrategy(ABC):
     async def apply(self, request: Request) -> Response:
         """Apply the strategy to the request and response."""
         pass
+
+    def update_opentelemetry(self, request: Request, *args, **kwargs) -> None:
+        """Update the opentelemetry span with strategy-specific attributes.
+
+        A span is made available on `request.state.span` to use.
+        When OpenTelemetry is not enabled, this span will exist but will not be reported.
+
+        """
+        pass

{mockstack-0.4.2 → mockstack-0.5.1}/mockstack/strategies/filefixtures.py

@@ -129,6 +129,7 @@ class FileFixturesStrategy(BaseStrategy, CreateMixin):
                 continue
 
             self.logger.debug("Found template filename: %s", filename)
+            self.update_opentelemetry(request, template_args)
             template = self.env.get_template(template_args["name"])
 
             return Response(
@@ -149,3 +150,11 @@ class FileFixturesStrategy(BaseStrategy, CreateMixin):
             status_code=status.HTTP_404_NOT_FOUND,
         )
         """
+
+    def update_opentelemetry(self, request: Request, template_args: dict) -> None:
+        """Update the opentelemetry span with the file fixtures details."""
+        span = request.state.span
+
+        span.set_attribute(
+            "mockstack.filefixtures.template_name", template_args["name"]
+        )

{mockstack-0.4.2 → mockstack-0.5.1}/mockstack/strategies/proxyrules.py

@@ -23,10 +23,17 @@ from mockstack.strategies.create_mixin import CreateMixin
 class Rule:
     """A rule for the proxy rules strategy."""
 
-    def __init__(self, pattern: str, replacement: str, method: str | None = None):
+    def __init__(
+        self,
+        pattern: str,
+        replacement: str,
+        method: str | None = None,
+        name: str | None = None,
+    ):
         self.pattern = pattern
         self.replacement = replacement
         self.method = method
+        self.name = name
 
     @classmethod
     def from_dict(cls, data: dict[str, str]) -> Self:
@@ -34,6 +41,7 @@ class Rule:
             pattern=data["pattern"],
             replacement=data["replacement"],
             method=data.get("method", None),
+            name=data.get("name", None),
         )
 
     def matches(self, request: Request) -> bool:
@@ -60,10 +68,9 @@ class ProxyRulesStrategy(BaseStrategy, CreateMixin):
     def __init__(self, settings: Settings, *args, **kwargs):
         super().__init__(settings, *args, **kwargs)
         self.rules_filename = settings.proxyrules_rules_filename
-        self.proxyrules_redirect_via = settings.proxyrules_redirect_via
-        self.proxyrules_simulate_create_on_missing = (
-            settings.proxyrules_simulate_create_on_missing
-        )
+        self.redirect_via = settings.proxyrules_redirect_via
+        self.reverse_proxy_timeout = settings.proxyrules_reverse_proxy_timeout
+        self.simulate_create_on_missing = settings.proxyrules_simulate_create_on_missing
         self.created_resource_metadata = settings.created_resource_metadata
 
         self.env = Environment()
@@ -72,8 +79,8 @@ class ProxyRulesStrategy(BaseStrategy, CreateMixin):
         return (
             f"[medium_purple]proxyrules[/medium_purple] "
             f"rules_filename: [medium_purple]{self.rules_filename}[/medium_purple]. "
-            f"redirect_via: [medium_purple]{self.proxyrules_redirect_via}[/medium_purple]. "
-            f"simulate_create_on_missing: [medium_purple]{self.proxyrules_simulate_create_on_missing}[/medium_purple]"
+            f"redirect_via: [medium_purple]{self.redirect_via}[/medium_purple]. "
+            f"simulate_create_on_missing: [medium_purple]{self.simulate_create_on_missing}[/medium_purple]"
         )
 
     @cached_property
@@ -101,9 +108,7 @@ class ProxyRulesStrategy(BaseStrategy, CreateMixin):
                 f"No rule found for request: {request.method} {request.url.path}"
             )
 
-            if self.proxyrules_simulate_create_on_missing and looks_like_a_create(
-                request
-            ):
+            if self.simulate_create_on_missing and looks_like_a_create(request):
                 self.logger.info(
                     f"Simulating resource creation for missing rule for {request.method} {request.url.path}"
                 )
@@ -118,8 +123,9 @@ class ProxyRulesStrategy(BaseStrategy, CreateMixin):
 
         url = rule.apply(request)
         self.logger.info(f"Redirecting to: {url}")
+        self.update_opentelemetry(request, rule, url)
 
-        match self.proxyrules_redirect_via:
+        match self.redirect_via:
             case ProxyRulesRedirectVia.HTTP_TEMPORARY_REDIRECT:
                 return RedirectResponse(
                     url=url, status_code=status.HTTP_307_TEMPORARY_REDIRECT
@@ -135,13 +141,11 @@ class ProxyRulesStrategy(BaseStrategy, CreateMixin):
                 return response
 
             case _:
-                raise ValueError(
-                    f"Invalid redirect via value: {self.proxyrules_redirect_via=}"
-                )
+                raise ValueError(f"Invalid redirect via value: {self.redirect_via=}")
 
     async def reverse_proxy(self, request: Request, url: str) -> Response:
         """Reverse proxy the request to the target URL."""
-        async with httpx.AsyncClient() as client:
+        async with httpx.AsyncClient(timeout=self.reverse_proxy_timeout) as client:
             request_content = await request.body()
             request_headers = self.reverse_proxy_headers(request.headers, url=url)
             req = client.build_request(
@@ -170,3 +174,15 @@ class ProxyRulesStrategy(BaseStrategy, CreateMixin):
         _headers["host"] = urlparse(url).netloc
 
         return _headers
+
+    def update_opentelemetry(self, request: Request, rule: Rule, url: str) -> None:
+        """Update the opentelemetry span with the proxy rules rule details."""
+        span = request.state.span
+        if rule.name is not None:
+            span.set_attribute("mockstack.proxyrules.rule_name", rule.name)
+        if rule.method is not None:
+            span.set_attribute("mockstack.proxyrules.rule_method", rule.method)
+
+        span.set_attribute("mockstack.proxyrules.rule_pattern", rule.pattern)
+        span.set_attribute("mockstack.proxyrules.rule_replacement", rule.replacement)
+        span.set_attribute("mockstack.proxyrules.rewritten_url", url)

mockstack-0.5.1/mockstack/telemetry.py

@@ -0,0 +1,141 @@
+"""OpenTelemetry integration."""
+
+from importlib import metadata
+from typing import List, Tuple
+
+from fastapi import FastAPI, Request
+from opentelemetry import trace
+from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import OTLPSpanExporter
+from opentelemetry.sdk.resources import Resource
+from opentelemetry.sdk.trace import TracerProvider
+from opentelemetry.sdk.trace.export import BatchSpanProcessor
+from opentelemetry.trace import Span
+from starlette.responses import StreamingResponse, Response
+
+from mockstack.config import Settings
+
+
+def span_name_for(request: Request) -> str:
+    """Get the span name for a request."""
+    return f"{request.method.upper()} {request.url.path}"
+
+
+def with_request_attributes(
+    request: Request, span: Span, *, sensitive_headers: List[str] = []
+) -> Span:
+    """Add request attributes to the span."""
+    span.set_attribute("http.method", request.method)
+    span.set_attribute("http.url", str(request.url))
+    span.set_attribute("http.scheme", request.url.scheme)
+    if request.url.hostname:
+        span.set_attribute("http.host", request.url.hostname)
+    span.set_attribute("http.target", request.url.path)
+    if request.url.port:
+        span.set_attribute("http.server_port", request.url.port)
+
+    # Client information
+    if request.client:
+        span.set_attribute("net.peer.ip", request.client.host)
+        if request.client.port:
+            span.set_attribute("net.peer.port", request.client.port)
+
+    # Request headers (excluding sensitive headers)
+    for header_name, header_value in request.headers.items():
+        if header_name.lower() not in sensitive_headers:
+            span.set_attribute(
+                f"http.request.header.{header_name.lower()}", header_value
+            )
+
+    # Query parameters
+    if request.query_params:
+        for param_name, param_value in request.query_params.items():
+            span.set_attribute(f"http.request.query.{param_name}", param_value)
+
+    return span
+
+
+def with_response_attributes(
+    response: Response, span: Span, *, sensitive_headers: List[str] = []
+) -> Span:
+    """Add response attributes to the span."""
+    # Response attributes
+    span.set_attribute("http.status_code", response.status_code)
+    span.set_attribute(
+        "http.response_content_length", response.headers.get("content-length", 0)
+    )
+
+    # Response headers
+    for header_name, header_value in response.headers.items():
+        if header_name.lower() not in sensitive_headers:
+            span.set_attribute(
+                f"http.response.header.{header_name.lower()}", header_value
+            )
+
+    return span
+
+
+async def with_response_body(
+    response: StreamingResponse, span: Span
+) -> Tuple[Response, Span]:
+    """Add the response body to the span."""
+    body = await extract_body(response)
+
+    # for semantics of payload attribute naming see:
+    # https://github.com/open-telemetry/oteps/pull/234
+    span.set_attribute("http.response.body", body)
+
+    # recreate response with the same body since when consuming it to log it above
+    # we effectively "deplete" the iterator.
+    _response = Response(
+        content=body,
+        status_code=response.status_code,
+        headers=dict(response.headers),
+        media_type=response.media_type,
+    )
+
+    return _response, span
+
+
+async def extract_body(response: StreamingResponse) -> str:
+    """Extract the body of a response."""
+
+    async def read_response_body(response: StreamingResponse) -> bytes:
+        """Helper function to read response body asynchronously into memory."""
+        body = b""
+        async for chunk in response.body_iterator:
+            if isinstance(chunk, str):
+                body += chunk.encode()
+            else:
+                body += chunk
+        return body
+
+    body = await read_response_body(response)
+
+    return body.decode()
+
+
+def opentelemetry_provider(app: FastAPI, settings: Settings) -> None:
+    """Initialize OpenTelemetry for the mockstack app."""
+    if not settings.opentelemetry.enabled:
+        return
+
+    # Initialize OpenTelemetry
+    distribution = metadata.distribution("mockstack")
+    resource = Resource(
+        attributes={
+            "service.name": distribution.name,
+            "service.version": distribution.version,
+        }
+    )
+
+    tracer_provider = TracerProvider(resource=resource)
+    trace.set_tracer_provider(tracer_provider)
+
+    # Set up OTLP exporter
+    otlp_exporter = OTLPSpanExporter(endpoint=settings.opentelemetry.endpoint)
+    span_processor = BatchSpanProcessor(otlp_exporter)
+    tracer_provider.add_span_processor(span_processor)
+
+    # Nb. we do not actually use the default FastAPIInstrumentor here
+    # because we use custom tracing in various places.
+    # FastAPIInstrumentor.instrument_app(app)

{mockstack-0.4.2 → mockstack-0.5.1}/mockstack/tests/conftest.py

@@ -1,6 +1,7 @@
 """Shared fixtures for the unit-tests."""
 
 import os
+from unittest.mock import MagicMock
 
 import pytest
 from fastapi import FastAPI
@@ -11,10 +12,19 @@ from mockstack.strategies.filefixtures import FileFixturesStrategy
 
 
 @pytest.fixture
-def app(settings):
+def span():
+    """Create a mock span object for testing."""
+    span = MagicMock()
+    span.set_attribute = MagicMock()
+    return span
+
+
+@pytest.fixture
+def app(settings, span):
     """Create a FastAPI app for testing."""
     app = FastAPI()
     app.state.strategy = FileFixturesStrategy(settings)
+    app.state.span = span
     return app
 
 

{mockstack-0.4.2 → mockstack-0.5.1}/mockstack/tests/strategies/test_filefixtures.py

@@ -18,7 +18,7 @@ def test_filefixtures_strategy_init(settings):
 
 
 @pytest.mark.asyncio
-async def test_filefixtures_strategy_apply(settings):
+async def test_filefixtures_strategy_apply(settings, span):
     """Test the FileFixturesStrategy apply method."""
     strategy = FileFixturesStrategy(settings)
     request = Request(
@@ -30,6 +30,7 @@ async def test_filefixtures_strategy_apply(settings):
             "headers": [],
         }
     )
+    request.state.span = span
 
     with pytest.raises(HTTPException) as exc_info:
         await strategy.apply(request)
@@ -38,7 +39,7 @@ async def test_filefixtures_strategy_apply(settings):
 
 
 @pytest.mark.asyncio
-async def test_file_fixtures_strategy_apply_success(settings):
+async def test_file_fixtures_strategy_apply_success(settings, span):
     """Test the FileFixturesStrategy apply method when template exists."""
     # Setup
     strategy = FileFixturesStrategy(settings)
@@ -61,6 +62,7 @@ async def test_file_fixtures_strategy_apply_success(settings):
                 "headers": [],
             }
         )
+        request.state.span = span
 
         # Execute
         response = await strategy.apply(request)
@@ -72,7 +74,7 @@ async def test_file_fixtures_strategy_apply_success(settings):
 
 
 @pytest.mark.asyncio
-async def test_file_fixtures_strategy_apply_template_not_found(settings):
+async def test_file_fixtures_strategy_apply_template_not_found(settings, span):
     """Test the FileFixturesStrategy apply method when template doesn't exist."""
     # Setup
     strategy = FileFixturesStrategy(settings)
@@ -88,6 +90,7 @@ async def test_file_fixtures_strategy_apply_template_not_found(settings):
                 "headers": [],
             }
         )
+        request.state.span = span
 
         # Execute and Assert
         with pytest.raises(HTTPException) as exc_info:

{mockstack-0.4.2 → mockstack-0.5.1}/mockstack/tests/strategies/test_proxyrules.py

@@ -124,7 +124,7 @@ def test_proxy_rules_strategy_load_rules(settings):
     assert all(isinstance(rule, Rule) for rule in rules)
 
 
-def test_proxy_rules_strategy_rule_for(settings):
+def test_proxy_rules_strategy_rule_for(settings, span):
     """Test finding a matching rule for a request."""
     strategy = ProxyRulesStrategy(settings)
     request = Request(
@@ -136,12 +136,13 @@ def test_proxy_rules_strategy_rule_for(settings):
             "headers": [],
         }
     )
+    request.state.span = span
     rule = strategy.rule_for(request)
     assert rule is not None
     assert isinstance(rule, Rule)
 
 
-def test_proxy_rules_strategy_rule_for_no_match(settings):
+def test_proxy_rules_strategy_rule_for_no_match(settings, span):
     """Test when no rule matches a request."""
     strategy = ProxyRulesStrategy(settings)
     request = Request(
@@ -153,12 +154,13 @@ def test_proxy_rules_strategy_rule_for_no_match(settings):
             "headers": [],
         }
     )
+    request.state.span = span
     rule = strategy.rule_for(request)
     assert rule is None
 
 
 @pytest.mark.asyncio
-async def test_proxy_rules_strategy_apply(settings):
+async def test_proxy_rules_strategy_apply(settings, span):
     """Test applying a rule to a request."""
     strategy = ProxyRulesStrategy(settings)
     request = Request(
@@ -170,13 +172,14 @@ async def test_proxy_rules_strategy_apply(settings):
             "headers": [],
         }
     )
+    request.state.span = span
     response = await strategy.apply(request)
     assert isinstance(response, RedirectResponse)
     assert response.headers["location"] == "/projects/123"
 
 
 @pytest.mark.asyncio
-async def test_proxy_rules_strategy_apply_no_match(settings):
+async def test_proxy_rules_strategy_apply_no_match(settings, span):
     """Test applying strategy when no rule matches."""
     strategy = ProxyRulesStrategy(settings)
     request = Request(
@@ -188,13 +191,14 @@ async def test_proxy_rules_strategy_apply_no_match(settings):
             "headers": [],
         }
     )
+    request.state.span = span
     response = await strategy.apply(request)
     assert response.status_code == 404
 
 
 @pytest.mark.asyncio
 @pytest.mark.skip(reason="TODO: Fix this test")
-async def test_proxy_rules_strategy_apply_reverse_proxy(settings_reverse_proxy):
+async def test_proxy_rules_strategy_apply_reverse_proxy(settings_reverse_proxy, span):
     """Test applying a rule to a request with reverse proxy enabled."""
     # Mock the httpx.AsyncClient to avoid making real HTTP requests
     mock_response = MagicMock()  # Use MagicMock for response to avoid async attributes
@@ -218,6 +222,7 @@ async def test_proxy_rules_strategy_apply_reverse_proxy(settings_reverse_proxy):
                 "headers": [("host", "example.com")],
             }
         )
+        request.state.span = span
         response = await strategy.apply(request)
 
         # Verify the response

{mockstack-0.4.2 → mockstack-0.5.1}/mockstack.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mockstack
-Version: 0.4.2
+Version: 0.5.1
 Summary: An API mocking workhorse
 License-Expression: MIT
 Project-URL: Homepage, https://github.com/adamhadani/mockstack
@@ -34,7 +34,17 @@ Dynamic: license-file
 
 An API mocking workhorse :racehorse:
 
-Enabling a sane development lifecycle for microservice-oriented architectures.
+Enabling a sane development lifecycle for microservice-oriented architectures and LLM-driven tool chains.
+
+Use mockstack for:
+
+* **Development** :pencil2:. Simulating HTTP-based interactions between a particular component you're developing or debugging locally and multiple other components it depends on during execution of a particular flow. You can create template-based mock responses, simulate creation of resources in a realistic way, as well as proxy to other services using a rich rules DSL. Full request and response metadata and payloads can be observed via OpenTelemetry integration.
+
+* **Integration Testing** :ok_hand:. Creating a consistent environment for running integration tests on a single component, using fixture responses.
+
+* **LLM-powered Workflows** :alien:. Speeding up development of LLM-based workflows and tools for use with frameworks such as [LangChain](https://python.langchain.com/docs/introduction/), [LangGraph](https://www.langchain.com/langgraph) and others. When developing LLM-driven execution graphs, you often want to have a consistent response from a tool while you're tuning prompts or debugging other aspects of a particular trace. `mockstack` can give you a solid foundation for this.
+
+* **Chaos Engineering** :boom:. mockstack can simulate various real-world runtime error scenarios such as timeouts, http error codes, and invalid response payloads. This can be a great way to do some upfront "chaos monkey" type of testing on software components.
 
 Highlights include:
 
@@ -57,6 +67,8 @@ or install into a persistent environment and add it to the PATH with:
 
 ## Usage
 
+See the [examples](https://github.com/adamhadani/mockstack/blob/main/examples/) directory for complete examples with documentation.
+
 Available configuration options are [here](https://github.com/adamhadani/mockstack/blob/main/mockstack/config.py).
 
 Setting individual options can be done either through an `.env` file, individual environment variables, or command-line arguments. For example:

{mockstack-0.4.2 → mockstack-0.5.1}/mockstack.egg-info/SOURCES.txt

@@ -14,6 +14,13 @@ uv.lock
 docs/assets/favicon.ico
 docs/assets/logo.png
 docs/assets/mockstack.png
+examples/filefixtures-with-templates/.env.example
+examples/filefixtures-with-templates/README.md
+examples/filefixtures-with-templates/templates/servicename-api-v1-items.j2
+examples/filefixtures-with-templates/templates/servicename2-api-v2-user.533ec889-7c68-45c8-b21e-4a7e455d1234.j2
+examples/proxyrules-with-rules-file/.env.example
+examples/proxyrules-with-rules-file/README.md
+examples/proxyrules-with-rules-file/rules.yml
 mockstack/__init__.py
 mockstack/config.py
 mockstack/constants.py

mockstack-0.4.2/mockstack/middleware.py

@@ -1,55 +0,0 @@
-"""Middleware definitionsfor the mockstack app."""
-
-import time
-
-from fastapi import FastAPI, Request, Response
-from opentelemetry import trace
-from opentelemetry.propagate import extract
-
-from mockstack.config import Settings
-from mockstack.telemetry import extract_body, span_name_for
-
-
-def middleware_provider(app: FastAPI, settings: Settings) -> None:
-    """Instrument the middlewares to the mockstack app."""
-
-    @app.middleware("http")
-    async def add_process_time_header(request: Request, call_next):
-        start_time = time.time()
-        response = await call_next(request)
-        process_time = time.time() - start_time
-        response.headers["X-Process-Time"] = str(process_time)
-        return response
-
-    @app.middleware("http")
-    async def instrument_opentelemetry(request: Request, call_next):
-        tracer = trace.get_tracer(__name__)
-        ctx = extract(request.headers)
-        with tracer.start_as_current_span(span_name_for(request), context=ctx) as span:
-            span.set_attribute("http.method", request.method)
-            span.set_attribute("http.url", str(request.url))
-
-            response = await call_next(request)
-
-            span.set_attribute("http.status_code", response.status_code)
-
-            # Nb. persisting response body can hamper performance,
-            # expose sensitive / PII data, and / or may not be needed.
-            # it is therefore an opt-in setting.
-            if settings.opentelemetry.capture_response_body:
-                body = await extract_body(response)
-
-                # for semantics of payload collection see:
-                # https://github.com/open-telemetry/oteps/pull/234
-                span.set_attribute("http.response.body", body)
-
-                # recreate response with the same body since when consuming it to log it above
-                # we effectively "deplete" the iterator.
-                response = Response(
-                    content=body,
-                    status_code=response.status_code,
-                    headers=dict(response.headers),
-                    media_type=response.media_type,
-                )
-
-            return response

mockstack-0.4.2/mockstack/telemetry.py

@@ -1,63 +0,0 @@
-"""OpenTelemetry integration."""
-
-from importlib import metadata
-
-from fastapi import FastAPI, Request
-from opentelemetry import trace
-from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import OTLPSpanExporter
-from opentelemetry.sdk.resources import Resource
-from opentelemetry.sdk.trace import TracerProvider
-from opentelemetry.sdk.trace.export import BatchSpanProcessor
-from starlette.responses import StreamingResponse
-
-from mockstack.config import Settings
-
-
-def span_name_for(request: Request) -> str:
-    """Get the span name for a request."""
-    return f"{request.method.upper()} {request.url.path}"
-
-
-async def extract_body(response: StreamingResponse) -> str:
-    """Extract the body of a response."""
-
-    async def read_response_body(response: StreamingResponse) -> bytes:
-        """Helper function to read response body asynchronously into memory."""
-        body = b""
-        async for chunk in response.body_iterator:
-            if isinstance(chunk, str):
-                body += chunk.encode()
-            else:
-                body += chunk
-        return body
-
-    body = await read_response_body(response)
-
-    return body.decode()
-
-
-def opentelemetry_provider(app: FastAPI, settings: Settings) -> None:
-    """Initialize OpenTelemetry for the mockstack app."""
-    if not settings.opentelemetry.enabled:
-        return
-
-    # Initialize OpenTelemetry
-    distribution = metadata.distribution("mockstack")
-    resource = Resource(
-        attributes={
-            "service.name": distribution.name,
-            "service.version": distribution.version,
-        }
-    )
-
-    tracer_provider = TracerProvider(resource=resource)
-    trace.set_tracer_provider(tracer_provider)
-
-    # Set up OTLP exporter
-    otlp_exporter = OTLPSpanExporter(endpoint=settings.opentelemetry.endpoint)
-    span_processor = BatchSpanProcessor(otlp_exporter)
-    tracer_provider.add_span_processor(span_processor)
-
-    # Nb. we do not actually use the default FastAPIInstrumentor here
-    # because we use custom tracing in various places.
-    # FastAPIInstrumentor.instrument_app(app)