mockstack 0.5.1__tar.gz → 0.6.0__tar.gz

{mockstack-0.5.1 → mockstack-0.6.0}/.env.example

@@ -9,6 +9,10 @@ MOCKSTACK__STRATEGY = filefixtures
 # and other hybrid strategies utilizing templates.
 MOCKSTACK__TEMPLATES_DIR = "/some/path/templates/"
 
+# When using filefixtures strategy, controls whether to enable
+# using templates for POST requests or go directly to simulate a create.
+FILEFIXTURES_ENABLE_TEMPLATES_FOR_POST = false
+
 # rules table for the proxyrules strategy.
 # see .mockstack/tests/fixtures/ for examples.
 MOCKSTACK__PROXYRULES_RULES_FILENAME="/some/path/proxyrules.yml"

{mockstack-0.5.1 → mockstack-0.6.0}/.pre-commit-config.yaml

@@ -39,7 +39,7 @@ repos:
   hooks:
   - id: pytest
     name: pytest [with coverage, without slow]
-    entry: bash -ec "uv run python -m pytest --cov=mockstack mockstack/tests --cov-fail-under='75' -m 'not slow'"
+    entry: bash -ec "uv run python -m pytest --cov=mockstack mockstack/tests --cov-fail-under='85' -m 'not slow'"
     language: system
     types: [python]
     pass_filenames: false

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mockstack
-Version: 0.5.1
+Version: 0.6.0
 Summary: An API mocking workhorse
 License-Expression: MIT
 Project-URL: Homepage, https://github.com/adamhadani/mockstack

mockstack-0.6.0/docs/configuration.md

@@ -0,0 +1,103 @@
+# Configuration
+
+mockstack can be configured through multiple methods, in order of priority:
+
+- Command-line arguments
+- Environment variables
+- `.env` file
+
+
+All configuration options are prefixed with `MOCKSTACK__` when using environment variables or the `.env` file.
+
+## General Settings
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `debug` | boolean | `false` | Whether to run in debug mode |
+| `host` | string | `0.0.0.0` | Host to run the server on |
+| `port` | integer | `8000` | Port to run the server on |
+| `strategy` | string | `filefixtures` | Strategy to use for handling requests. Options: `filefixtures`, `proxyrules` |
+
+## OpenTelemetry Settings
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `opentelemetry.enabled` | boolean | `false` | Whether to enable OpenTelemetry integration |
+| `opentelemetry.endpoint` | string | `http://localhost:4317/` | OpenTelemetry endpoint |
+| `opentelemetry.capture_response_body` | boolean | `false` | Whether to capture response body in traces |
+
+## Strategy-Specific Settings
+
+### FileFixtures Strategy
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `templates_dir` | string | - | Base directory for templates used by the strategy |
+| `filefixtures_enable_templates_for_post` | boolean | `false` | Whether to enable template-based responses for POST requests |
+
+### ProxyRules Strategy
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `proxyrules_rules_filename` | string | - | Rules filename for proxyrules strategy |
+| `proxyrules_redirect_via` | string | `reverse_proxy` | Controls behavior of proxying. Options: `reverse_proxy`, `http_307_temporary`, `http_301_permanent` |
+| `proxyrules_reverse_proxy_timeout` | float | `10.0` | Default timeout for reverse proxy requests in seconds |
+| `proxyrules_simulate_create_on_missing` | boolean | `false` | Whether to simulate creation of resources when a POST request is made to a resource that doesn't match any rules |
+
+## Resource Creation Settings
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `created_resource_metadata` | object | See below | Metadata fields to inject into created resources |
+| `missing_resource_fields` | object | See below | Fields to inject into missing resources response JSON |
+
+### Default created_resource_metadata
+```json
+{
+    "id": "{{ uuid4() }}",
+    "createdAt": "{{ utcnow().isoformat() }}",
+    "updatedAt": "{{ utcnow().isoformat() }}",
+    "createdBy": "{{ request.headers.get('X-User-Id', uuid4()) }}",
+    "status": {
+        "code": "OK",
+        "error_code": null
+    }
+}
+```
+
+### Default missing_resource_fields
+```json
+{
+    "code": 404,
+    "message": "mockstack: resource not found",
+    "retryable": false
+}
+```
+
+## Logging Configuration
+
+The logging configuration follows the Python logging configuration schema. By default, it includes:
+
+- Rich console handler
+- Uvicorn formatter
+- Separate loggers for different components
+- Debug level logging for strategy-specific loggers
+
+## Example Configuration
+
+Here's an example `.env` file:
+
+```env
+MOCKSTACK__STRATEGY=filefixtures
+MOCKSTACK__TEMPLATES_DIR=~/mockstack-templates/
+MOCKSTACK__OPENTELEMETRY__ENABLED=true
+MOCKSTACK__OPENTELEMETRY__CAPTURE_RESPONSE_BODY=true
+```
+
+## Command Line Usage
+
+You can also set configuration options via command line arguments:
+
+```bash
+uvx mockstack --strategy filefixtures --templates-dir ~/mockstack-templates/
+```

mockstack-0.6.0/docs/strategies/base.md

@@ -0,0 +1,55 @@
+# Base Strategy
+
+The `BaseStrategy` class serves as the foundation for all mockstack strategies. It defines the core interface that all strategies must implement.
+
+## Interface
+
+### Constructor
+
+```python
+def __init__(self, settings: Settings, *args, **kwargs)
+```
+
+Initializes the strategy with the provided settings.
+
+### Methods
+
+#### `apply`
+
+```python
+async def apply(self, request: Request) -> Response
+```
+
+This is the main method that all strategies must implement. It takes a FastAPI `Request` object and returns a FastAPI `Response` object. This is where the strategy's core logic for handling requests is implemented.
+
+#### `update_opentelemetry`
+
+```python
+def update_opentelemetry(self, request: Request, *args, **kwargs) -> None
+```
+
+This method allows strategies to add strategy-specific attributes to the OpenTelemetry span. The span is available on `request.state.span`. When OpenTelemetry is not enabled, this span will exist but will not be reported.
+
+## Creating Custom Strategies
+
+To create a custom strategy, you should:
+
+1. Inherit from `BaseStrategy`
+2. Implement the `apply` method
+3. Optionally override `update_opentelemetry` to add strategy-specific telemetry
+
+Example:
+
+```python
+from mockstack.strategies.base import BaseStrategy
+from fastapi import Request, Response
+
+class CustomStrategy(BaseStrategy):
+    async def apply(self, request: Request) -> Response:
+        # Implement your custom logic here
+        pass
+
+    def update_opentelemetry(self, request: Request, *args, **kwargs) -> None:
+        # Add custom telemetry attributes
+        request.state.span.set_attribute("custom.attribute", "value")
+```

mockstack-0.6.0/docs/strategies/filefixtures.md

@@ -0,0 +1,109 @@
+# FileFixtures Strategy
+
+The `FileFixturesStrategy` is a template-based strategy that uses Jinja2 templates to generate responses. It's particularly useful for creating consistent mock responses for your API endpoints.
+
+## Overview
+
+This strategy:
+
+- Uses Jinja2 templates stored in a specified directory
+- Intelligently matches requests to templates based on the request path
+- Supports all HTTP methods (GET, POST, PUT, PATCH, DELETE)
+- Simulates resource creation for POST requests which are not handled by proxying rules (behavior controlled via configuration)
+- Provides OpenTelemetry integration for observability
+
+## Template Resolution
+
+For a given request path like `/api/v1/projects/1234`, the strategy will look for templates in the following order:
+
+1. `api-v1-projects.1234.j2` (specific to the resource ID)
+2. `api-v1-projects.j2` (generic for the resource type)
+3. `index.j2` (fallback template)
+
+## HTTP Method Handling
+
+### GET Requests
+- Attempts to find and render a matching template
+- Returns 404 if no matching template is found
+
+### POST Requests
+The strategy intelligently handles POST requests based on the request context:
+
+1. **Search Requests**: If the request looks like a search (based on URL and body), returns a template response
+2. **Command Requests**: If the request looks like a command, returns a 201 CREATED status with template response
+3. **Resource Creation**: Otherwise, simulates resource creation with injected metadata
+
+### DELETE/PUT/PATCH Requests
+- Returns 204 NO CONTENT by default
+- These are no-op operations in the default implementation
+
+## Template Context
+
+Templates have access to the following context variables:
+
+- `request`: The FastAPI Request object
+- `request.body`: The parsed request body
+- `request.headers`: The request headers
+- `request.query_params`: The query parameters
+- `request.path_params`: The path parameters
+
+## Resource Creation
+
+When simulating resource creation (POST requests), the strategy injects the following metadata fields by default:
+
+```json
+{
+    "id": "{{ uuid4() }}",
+    "createdAt": "{{ utcnow().isoformat() }}",
+    "updatedAt": "{{ utcnow().isoformat() }}",
+    "createdBy": "{{ request.headers.get('X-User-Id', uuid4()) }}",
+    "status": {
+        "code": "OK",
+        "error_code": null
+    }
+}
+```
+
+## Configuration
+
+The strategy requires the following configuration:
+
+```python
+settings = Settings(
+    strategy="filefixtures",
+    templates_dir="/path/to/templates",
+    filefixtures_enable_templates_for_post=True  # Optional: Enables template-based responses for POST requests
+)
+```
+
+## Example Template
+
+Here's an example template for a user resource:
+
+```jinja2
+{
+    "id": "{{ uuid4() }}",
+    "name": "{{ request.body.name }}",
+    "email": "{{ request.body.email }}",
+    "createdAt": "{{ utcnow().isoformat() }}",
+    "updatedAt": "{{ utcnow().isoformat() }}"
+}
+```
+
+## OpenTelemetry Integration
+
+The strategy automatically adds the following OpenTelemetry attributes:
+
+- `mockstack.filefixtures.template_name`: The name of the template being rendered
+
+## Error Handling
+
+When no matching template is found, the strategy returns a 404 response with the following structure:
+
+```json
+{
+    "code": 404,
+    "message": "mockstack: resource not found",
+    "retryable": false
+}
+```

mockstack-0.6.0/docs/strategies/proxyrules.md

@@ -0,0 +1,123 @@
+# ProxyRules Strategy
+
+The `ProxyRulesStrategy` is a powerful strategy that allows you to define rules for redirecting or proxying requests to other services. It's particularly useful when you need to mix mock responses with real service calls.
+
+## Overview
+
+This strategy:
+
+- Uses a YAML configuration file to define routing rules
+- Supports multiple redirection methods (HTTP redirects or reverse proxy)
+- Can simulate resource creation for unmatched requests
+- Provides OpenTelemetry integration for observability
+
+## Configuration
+
+The strategy requires the following configuration:
+
+```python
+settings = Settings(
+    strategy="proxyrules",
+    proxyrules_rules_filename="/path/to/rules.yaml",
+    proxyrules_redirect_via="REVERSE_PROXY",  # or "HTTP_TEMPORARY_REDIRECT" or "HTTP_PERMANENT_REDIRECT"
+    proxyrules_reverse_proxy_timeout=10.0,
+    proxyrules_simulate_create_on_missing=False
+)
+```
+
+## Rules Configuration
+
+Rules are defined in a YAML file with the following structure:
+
+```yaml
+rules:
+  - name: "user-service"
+    pattern: "^/api/v1/users/(.*)"
+    replacement: "http://user-service/api/v1/users/\1"
+    method: "GET"  # optional, if not specified matches all methods
+```
+
+### Rule Properties
+
+- `name`: Optional identifier for the rule (used in telemetry)
+- `pattern`: Regular expression pattern to match against the request path
+- `replacement`: URL template to redirect to (can use capture groups from pattern)
+- `method`: Optional HTTP method to match (if not specified, matches all methods)
+
+## Redirection Methods
+
+The strategy supports three redirection methods:
+
+1. **HTTP Temporary Redirect (307)**
+    - Client makes a new request to the target URL
+    - Preserves the original HTTP method
+
+2. **HTTP Permanent Redirect (301)**
+    - Client makes a new request to the target URL
+    - Browsers may cache the redirect
+
+3. **Reverse Proxy**
+    - Server forwards the request to the target service
+    - Client is unaware of the redirection
+    - Useful when you need to work with clients that do not handle HTTP redirects gracefully.
+
+## Resource Creation Simulation
+
+When `proxyrules_simulate_create_on_missing` is enabled and a POST request doesn't match any rules, the strategy will simulate resource creation by:
+
+1. Injecting metadata fields into the response
+2. Returning a 201 CREATED status code
+3. Echoing back the request body with added metadata
+
+The default metadata fields are controlled via the configuration file and at the time of writing are as follows:
+
+```json
+{
+    "id": "{{ uuid4() }}",
+    "createdAt": "{{ utcnow().isoformat() }}",
+    "updatedAt": "{{ utcnow().isoformat() }}",
+    "createdBy": "{{ request.headers.get('X-User-Id', uuid4()) }}",
+    "status": {
+        "code": "OK",
+        "error_code": null
+    }
+}
+```
+
+## OpenTelemetry Integration
+
+The strategy automatically adds the following OpenTelemetry attributes:
+
+- `mockstack.proxyrules.rule_name`: The name of the matched rule (if specified)
+- `mockstack.proxyrules.rule_method`: The HTTP method the rule matches (if specified)
+- `mockstack.proxyrules.rule_pattern`: The pattern used to match the request
+- `mockstack.proxyrules.rule_replacement`: The replacement URL template
+- `mockstack.proxyrules.rewritten_url`: The final URL after applying the rule
+
+## Example Rules
+
+Here are some example rules:
+
+```yaml
+rules:
+  # Redirect all GET requests to /api/v1/users/* to the user service
+  - name: "user-service-get"
+    pattern: "^/api/v1/users/(.*)"
+    replacement: "http://user-service/api/v1/users/\1"
+    method: "GET"
+
+  # Proxy all POST requests to /api/v1/orders to the order service
+  - name: "order-service-post"
+    pattern: "^/api/v1/orders"
+    replacement: "http://order-service/api/v1/orders"
+    method: "POST"
+
+  # Redirect all requests to /api/v1/products to the product service
+  - name: "product-service"
+    pattern: "^/api/v1/products/(.*)"
+    replacement: "http://product-service/api/v1/products/\1"
+```
+
+## Error Handling
+
+When no matching rule is found and resource creation simulation is disabled, the strategy returns a 404 NOT FOUND response.

{mockstack-0.5.1 → mockstack-0.6.0}/examples/filefixtures-with-templates/.env.example

@@ -9,5 +9,9 @@ MOCKSTACK__STRATEGY = filefixtures
 # and other hybrid strategies utilizing templates.
 MOCKSTACK__TEMPLATES_DIR = "./templates/"
 
+# When using filefixtures strategy, controls whether to enable
+# using templates for POST requests or go directly to simulate a create.
+FILEFIXTURES_ENABLE_TEMPLATES_FOR_POST = false
+
 # OpenTelemetry settings
 MOCKSTACK__OPENTELEMETRY__ENABLED = false

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

@@ -0,0 +1,17 @@
+# 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 by a configurationkey 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.
+* A configuration value in controllable via `.env` / environment variables lets you also decide whether to allow using templates for POST requests or try to simulate a createion. When templates are allowed, mockstaack will first try to find a suitable template for the request based on the URL, and if it fails will fallback to the create simulation behavior.

mockstack-0.6.0/examples/llm/README.md

@@ -0,0 +1,11 @@
+# LLMs
+
+**mockstack** can be a great tool for the development of LLM-based flows.
+
+A lot of current applications involve a sort of DAG of API calls to LLM APIs and various "tool" APIs, sometimes serially, sometimes in parallel, and sometimes in a "iterative" fashion (e.g. see [Agents](https://langchain-ai.github.io/langgraph/agents/overview/) documentation on LangGraph website).
+
+you can mock any of these parts out to accelerate development, debugging and integration testing of such workflows.
+
+Mocking out the LLMs themselves can be a particularly effective method to make sure no costs are incurred in early stages of development and in debugging scenarios that don't critically rely on the semantic content of the responses.
+
+This example shows a few possible scenarios involving mockstack and (mostly LangChain-based) LLM workflows.

mockstack-0.6.0/examples/llm/mockstack-langchain-example.ipynb

@@ -0,0 +1,128 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# LLMs + mockstack\n",
+    "\n",
+    "A few simple examples for using `mockstack` to mock various components in typical LLM-driven use cases."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 26,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Install langchain dependencies with the following or using `uv` depending on your venv setup:\n",
+    "\n",
+    "#!pip install -q langchain langchain-openai\n",
+    "# or:\n",
+    "#!uv pip install langchain langchain-openai"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Example #1: Template-based mocking (`filefixtures` strategy)\n",
+    "\n",
+    "Here we simply use the **filefixtures** strategy to route requesets coming in for a certain URL to a template file with the appropriate name.\n",
+    "\n",
+    "For the below example you'll want to make sure:\n",
+    "\n",
+    "- mockstack is running at http://localhost:8000 which are the default settings\n",
+    "- `MOCKSTACK__TEMPLATES_DIR` is pointing to a valid directory with a template file called `openai-v1-chat-completions.j2`. See the [included file](./templates/openai-v1-chat-completions.j2) with same name in the ./templates sub-directory of this example for a a template with a valid response based on [OpenAI API reference](https://platform.openai.com/docs/api-reference/chat/create).\n",
+    "- the `MOCKSTACK__FILEFIXTURES_ENABLE_TEMPLATES_FOR_POST` flag is set to true (which it should be by default)\n",
+    "\n",
+    "\n",
+    "If everything is setup correctly, you should get back the mocked response in the correct format from the template and the below assert should pass."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 31,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from langchain_openai import ChatOpenAI\n",
+    "\n",
+    "\n",
+    "llm = ChatOpenAI(\n",
+    "    model=\"gpt-4o\",\n",
+    "    temperature=0,\n",
+    "    max_tokens=None,\n",
+    "    timeout=None,\n",
+    "    max_retries=2,\n",
+    "    base_url=\"http://localhost:8000/openai/v1\",\n",
+    "    api_key=\"SOME_STRING_THAT_DOES_NOT_MATTER\",\n",
+    ")\n",
+    "\n",
+    "messages = [\n",
+    "    (\n",
+    "        \"system\",\n",
+    "        \"You are a helpful assistant that translates English to French. Translate the user sentence.\",\n",
+    "    ),\n",
+    "    (\"human\", \"I love programming.\"),\n",
+    "]\n",
+    "ai_msg = llm.invoke(messages)\n",
+    "\n",
+    "assert ai_msg.content == \"Hello! How can I assist you today?\""
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Example #2: `llm` strategy\n",
+    "\n",
+    "** COMING SOON **"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": []
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Example #3: mocking out a tool call\n",
+    "\n",
+    "** COMING SOON **"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": []
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": ".venv",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.13.3"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2
+}

mockstack-0.6.0/examples/llm/templates/openai-v1-chat-completions.j2

@@ -0,0 +1,35 @@
+ {
+   "id": "chatcmpl-B9MBs8CjcvOU2jLn4n570S5qMJKcT",
+   "object": "chat.completion",
+   "created": 1741569952,
+   "model": "gpt-4.1-2025-04-14",
+   "choices": [
+     {
+       "index": 0,
+       "message": {
+         "role": "assistant",
+         "content": "Hello! How can I assist you today?",
+         "refusal": null,
+         "annotations": []
+       },
+       "logprobs": null,
+       "finish_reason": "stop"
+     }
+   ],
+   "usage": {
+     "prompt_tokens": 19,
+     "completion_tokens": 10,
+     "total_tokens": 29,
+     "prompt_tokens_details": {
+       "cached_tokens": 0,
+       "audio_tokens": 0
+     },
+     "completion_tokens_details": {
+       "reasoning_tokens": 0,
+       "audio_tokens": 0,
+       "accepted_prediction_tokens": 0,
+       "rejected_prediction_tokens": 0
+     }
+   },
+   "service_tier": "default"
+ }

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

@@ -61,6 +61,13 @@ class Settings(BaseSettings):
     # base directory for templates used by strategies
     templates_dir: DirectoryPath | None = None  # type: ignore[assignment]
 
+    # whether to enable templates for POST requests.
+    # By default, templates are not used for POSTs, and instead we try to
+    # simulate a create (or search) operation. If turned on, we will first
+    # try to materialize a template for the response, and if that fails
+    # with a 404, we will then try to simulate creation of the resource.
+    filefixtures_enable_templates_for_post: CliImplicitFlag[bool] = True
+
     # rules filename for proxyrules strategy
     proxyrules_rules_filename: FilePath | None = None  # type: ignore[assignment]
 

{mockstack-0.5.1 → mockstack-0.6.0}/mockstack/display.py

@@ -20,8 +20,8 @@ def announce(app: FastAPI, settings: Settings):
     )
     logger.info(str(app.state.strategy), extra=extra)
     logger.info(
-        f"OpenTelemetry enabled: [medium_purple]{settings.opentelemetry.enabled}[/medium_purple], "
-        f"endpoint: [medium_purple]{settings.opentelemetry.endpoint}[/medium_purple], "
+        f"[medium_purple]OpenTelemetry[/medium_purple] enabled: [medium_purple]{settings.opentelemetry.enabled}[/medium_purple],\n "
+        f"endpoint: [medium_purple]{settings.opentelemetry.endpoint}[/medium_purple],\n "
         f"capture_response_body: [medium_purple]{settings.opentelemetry.capture_response_body}[/medium_purple]",
         extra=extra,
     )