mockstack 0.1.1__tar.gz → 0.3.0__tar.gz

mockstack-0.3.0/.env.example

@@ -0,0 +1,20 @@
+# Example environment variables for mockstack
+
+# 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 = "/some/path/templates/"
+
+# rules table for the proxyrules strategy.
+# see .mockstack/tests/fixtures/ for examples.
+MOCKSTACK__PROXYRULES_RULES_FILENAME="/some/path/proxyrules.yml"
+
+MOCKSTACK__PROXYRULES_SIMULATE_CREATE_ON_MISSING = true
+
+# OpenTelemetry settings
+MOCKSTACK__OPENTELEMETRY__ENABLED = true
+MOCKSTACK__OPENTELEMETRY__CAPTURE_RESPONSE_BODY = true

{mockstack-0.1.1 → mockstack-0.3.0}/.github/workflows/ci.yml

@@ -44,6 +44,8 @@ jobs:
         ruff check
         ruff format
     - name: Run mypy
-      run: uv run mypy mockstack
+      run: |
+        uv pip install types-pyyaml
+        uv run mypy mockstack
     - name: Run tests
       run: uv run pytest

mockstack-0.3.0/.github/workflows/publish-docs.yml

@@ -0,0 +1,35 @@
+name: Publish docs
+
+on:
+  push:
+    branches:
+      - main
+      - docs/**
+
+permissions:
+  contents: write
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Configure Git Credentials
+        run: |
+            git config --global user.name "${GITHUB_ACTOR}"
+            git config --global user.email "${GITHUB_ACTOR_ID}+${GITHUB_ACTOR}@users.noreply.github.com"
+      - uses: actions/setup-python@v5
+        with:
+          python-version: 3.x
+      - run: echo "cache_id=$(date --utc '+%V')" >> "${GITHUB_ENV}"
+      - uses: actions/cache@v4
+        with:
+          key: mkdocs-material-${{ env.cache_id }}
+          path: .cache
+          restore-keys: |
+            mkdocs-material-
+      - run: pip install mkdocs-material
+      - name: copy README.md to docs/
+        run: |
+          cp README.md docs/
+      - run: mkdocs gh-deploy --force

{mockstack-0.1.1 → mockstack-0.3.0}/.gitignore

@@ -1,3 +1,6 @@
+# MacOS
+.DS_Store
+
 # Byte-compiled / optimized / DLL files
 __pycache__/
 *.py[cod]
@@ -71,6 +74,9 @@ instance/
 # Sphinx documentation
 docs/_build/
 
+# Do not check in README.md under docs/ - it gets copied there by build-docs CI workflow.
+docs/README.md
+
 # PyBuilder
 .pybuilder/
 target/

{mockstack-0.1.1 → mockstack-0.3.0}/.pre-commit-config.yaml

@@ -1,5 +1,14 @@
 fail_fast: true
 repos:
+-   repo: local
+    hooks:
+    # do not allow commits with files containing certain blacklisted strings
+    -   id: dontship
+        name: detect blacklisted strings
+        exclude: ^.pre-commit-config.yaml
+        entry: codeartifact
+        language: pygrep
+        types: [text]
 - repo: https://github.com/pre-commit/pre-commit-hooks
   rev: v5.0.0
   hooks:
@@ -8,12 +17,12 @@ repos:
     - id: check-case-conflict
     - id: check-json
     - id: check-yaml
+      args: [ --unsafe ]
     - id: detect-aws-credentials
     - id: detect-private-key
     - id: end-of-file-fixer
     - id: trailing-whitespace
 - repo: https://github.com/astral-sh/ruff-pre-commit
-  # Ruff version.
   rev: v0.5.0
   hooks:
     # Run the linter.
@@ -25,6 +34,7 @@ repos:
   rev: v1.15.0
   hooks:
     - id: mypy
+      additional_dependencies: [types-pyyaml>=6.0.12]
 - repo: local
   hooks:
   - id: pytest

{mockstack-0.1.1 → mockstack-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mockstack
-Version: 0.1.1
+Version: 0.3.0
 Summary: An API mocking workhorse
 License-Expression: MIT
 Project-URL: Homepage, https://github.com/adamhadani/mockstack
@@ -11,16 +11,21 @@ Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: colorama>=0.4.6
 Requires-Dist: fastapi[standard]>=0.115.12
+Requires-Dist: httpx>=0.28.1
 Requires-Dist: jinja2>=3.1.6
 Requires-Dist: opentelemetry-distro[otlp]>=0.53b1
 Requires-Dist: opentelemetry-instrumentation-fastapi>=0.53b1
 Requires-Dist: pydantic>=2.11.3
 Requires-Dist: pydantic-settings>=2.9.1
+Requires-Dist: pyyaml>=6.0.2
 Requires-Dist: typer>=0.15.2
 Requires-Dist: uvicorn>=0.34.2
 Dynamic: license-file
 
-# mockstack
+![mockstack logo](https://github.com/adamhadani/mockstack/raw/main/docs/assets/mockstack.png)
+
+--------------------------------------------------------------------------------
+
 
 [![CI](https://github.com/adamhadani/mockstack/actions/workflows/ci.yml/badge.svg)](https://github.com/adamhadani/mockstack/actions/workflows/ci.yml)
 [![GitHub License](https://img.shields.io/github/license/adamhadani/mockstack)](https://github.com/adamhadani/mockstack/blob/main/LICENSE)
@@ -51,9 +56,14 @@ or install into a persistent environment and add it to the PATH with:
 
 ## Usage
 
-Available configuration options are [here](./mockstack/config.py). Setting individual options can be done with env. variables as in the following example:
+Available configuration options are [here](https://github.com/adamhadani/mockstack/blob/main/mockstack/config.py). Setting individual options can be done with env. variables as in the following example:
 
-    MOCKSTACK__OPENTELEMETRY__ENABLED=true MOCKSTACK__OPENTELEMETRY__CAPTURE_RESPONSE_BODY=true uv run
+```shell
+    export MOCKSTACK__TEMPLATES_DIR=~/mockstack-templates/
+    export MOCKSTACK__OPENTELEMETRY__ENABLED=true
+    export MOCKSTACK__OPENTELEMETRY__CAPTURE_RESPONSE_BODY=true
+    uv run
+```
 
 Out of the box, you get the following behavior when using the default `filefixtures` strategy:
 
@@ -87,7 +97,7 @@ If you are contributing to development, you will want to clone this project, and
     uv sync
     uv pip install -e .
 
-Copy the included [.env.example](.env.example) file to `.env` and fill in configuration as needed based on the given examples.
+Copy the included [.env.example](https://github.com/adamhadani/mockstack/blob/main/.env.example) file to `.env` and fill in configuration as needed based on the given examples.
 
 Run in development mode (for live-reload of changes when developing):
 

{mockstack-0.1.1 → mockstack-0.3.0}/README.md

@@ -1,4 +1,7 @@
-# mockstack
+![mockstack logo](https://github.com/adamhadani/mockstack/raw/main/docs/assets/mockstack.png)
+
+--------------------------------------------------------------------------------
+
 
 [![CI](https://github.com/adamhadani/mockstack/actions/workflows/ci.yml/badge.svg)](https://github.com/adamhadani/mockstack/actions/workflows/ci.yml)
 [![GitHub License](https://img.shields.io/github/license/adamhadani/mockstack)](https://github.com/adamhadani/mockstack/blob/main/LICENSE)
@@ -29,9 +32,14 @@ or install into a persistent environment and add it to the PATH with:
 
 ## Usage
 
-Available configuration options are [here](./mockstack/config.py). Setting individual options can be done with env. variables as in the following example:
+Available configuration options are [here](https://github.com/adamhadani/mockstack/blob/main/mockstack/config.py). Setting individual options can be done with env. variables as in the following example:
 
-    MOCKSTACK__OPENTELEMETRY__ENABLED=true MOCKSTACK__OPENTELEMETRY__CAPTURE_RESPONSE_BODY=true uv run
+```shell
+    export MOCKSTACK__TEMPLATES_DIR=~/mockstack-templates/
+    export MOCKSTACK__OPENTELEMETRY__ENABLED=true
+    export MOCKSTACK__OPENTELEMETRY__CAPTURE_RESPONSE_BODY=true
+    uv run
+```
 
 Out of the box, you get the following behavior when using the default `filefixtures` strategy:
 
@@ -65,8 +73,8 @@ If you are contributing to development, you will want to clone this project, and
     uv sync
     uv pip install -e .
 
-Copy the included [.env.example](.env.example) file to `.env` and fill in configuration as needed based on the given examples.
+Copy the included [.env.example](https://github.com/adamhadani/mockstack/blob/main/.env.example) file to `.env` and fill in configuration as needed based on the given examples.
 
 Run in development mode (for live-reload of changes when developing):
 
-    uv run uvicorn --factory mockstack.main:create_app --reload
+    uv run uvicorn --factory mockstack.main:create_app --reload

mockstack-0.3.0/mkdocs.yml

@@ -0,0 +1,58 @@
+site_name: mockstack
+site_url: https://adamhadani.github.io/mockstack
+repo_name: mockstack
+repo_url: https://github.com/adamhadani/mockstack
+
+theme:
+  name: material
+  logo: assets/logo.png
+  favicon: assets/favicon.ico
+  font:
+    text: Merriweather Sans
+    code: Red Hat Mono
+  palette:
+    # Dark Mode
+    - scheme: slate
+      toggle:
+        icon: material/weather-sunny
+        name: Dark mode
+      primary: amber
+      accent: deep purple
+    # Light Mode
+    - scheme: default
+      toggle:
+        icon: material/weather-night
+        name: Light mode
+      primary: blue
+      accent: deep orange
+  features:
+    - content.code.copy
+    - navigation.footer
+markdown_extensions:
+  - admonition
+  - attr_list
+  - pymdownx.details
+  - pymdownx.emoji:
+      emoji_index: !!python/name:material.extensions.emoji.twemoji
+      emoji_generator: !!python/name:material.extensions.emoji.to_svg
+  - pymdownx.highlight:
+      anchor_linenums: true
+      line_spans: __span
+      pygments_lang_class: true
+  - pymdownx.inlinehilite
+  - pymdownx.snippets
+  - pymdownx.superfences:
+      custom_fences:
+        - name: mermaid
+          class: mermaid
+          format: !!python/name:pymdownx.superfences.fence_code_format
+  - pymdownx.tabbed:
+      alternate_style: true
+
+
+extra:
+  social:
+    - icon: simple/github
+      link: https://github.com/adamhadani/mockstack
+
+copyright: Copyright © 2025 Adam Ever-Hadani

{mockstack-0.1.1 → mockstack-0.3.0}/mockstack/config.py

@@ -1,9 +1,11 @@
 from functools import lru_cache
-from typing import Any, Literal
+from typing import Any, Literal, Self
 
-from pydantic import DirectoryPath
+from pydantic import DirectoryPath, FilePath, model_validator
 from pydantic_settings import BaseSettings, SettingsConfigDict
 
+from mockstack.constants import ProxyRulesRedirectVia
+
 
 class OpenTelemetrySettings(BaseSettings):
     """Settings for OpenTelemetry."""
@@ -38,7 +40,18 @@ class Settings(BaseSettings):
     strategy: Literal["filefixtures", "proxyrules"] = "filefixtures"
 
     # base directory for templates used by strategies
-    templates_dir: DirectoryPath = "./templates"  # type: ignore[assignment]
+    templates_dir: DirectoryPath | None = None  # type: ignore[assignment]
+
+    # rules filename for proxyrules strategy
+    proxyrules_rules_filename: FilePath | None = None  # type: ignore[assignment]
+
+    # controls behavior of proxying. Whether to use HTTP status code redirects
+    # or reverse proxy the request to the target URL "silently".
+    proxyrules_redirect_via: ProxyRulesRedirectVia = ProxyRulesRedirectVia.REVERSE_PROXY
+
+    # 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: bool = False
 
     # metadata fields to inject into created resources.
     # A few template fields are available. See documentation for more details.
@@ -65,7 +78,8 @@ class Settings(BaseSettings):
         "disable_existing_loggers": False,
         "formatters": {
             "standard": {
-                "format": "     %(levelname)s   [%(name)s] %(message)s",
+                "()": "uvicorn.logging.DefaultFormatter",
+                "fmt": "%(levelprefix)s %(message)s",
             },
         },
         "handlers": {
@@ -77,13 +91,49 @@ class Settings(BaseSettings):
             },
         },
         "loggers": {
+            "uvicorn": {
+                "handlers": ["console"],
+                "level": "INFO",
+                "propagate": False,
+            },
             "FileFixturesStrategy": {
                 "handlers": ["console"],
                 "level": "INFO",
+                "propagate": False,
+            },
+            "ProxyRulesStrategy": {
+                "handlers": ["console"],
+                "level": "INFO",
+                "propagate": False,
             },
         },
+        "root": {
+            "handlers": ["console"],
+            "level": "INFO",
+            "propagate": False,
+        },
     }
 
+    @model_validator(mode="after")
+    def validate_strategy_parameters(self) -> Self:
+        """Validate the strategy parameters."""
+
+        # TODO: make this validation dynamic based on the strategy classes themselves.
+
+        if self.strategy == "proxyrules":
+            if self.proxyrules_rules_filename is None:
+                raise ValueError(
+                    "proxyrules_rules_filename is required when strategy is proxyrules"
+                )
+
+        elif self.strategy == "filefixtures":
+            if self.templates_dir is None:
+                raise ValueError(
+                    "templates_dir is required when strategy is proxyrules"
+                )
+
+        return self
+
 
 @lru_cache
 def settings_provider() -> Settings:

mockstack-0.3.0/mockstack/constants.py

@@ -0,0 +1,19 @@
+"""Constants for mockstack."""
+
+from enum import StrEnum
+
+# proxyrules strategy constants
+
+
+class ProxyRulesRedirectVia(StrEnum):
+    """The type of redirect to use for the proxy rules strategy.
+
+    - HTTP_* type redirects are handled by using a Http redirect response.
+    - REVERSE_PROXY type redirects are handled by using a reverse proxy to the target URL
+        which is opaque to the client.
+
+    """
+
+    HTTP_TEMPORARY_REDIRECT = "http_307_temporary"
+    HTTP_PERMANENT_REDIRECT = "http_301_permanent"
+    REVERSE_PROXY = "reverse_proxy"

{mockstack-0.1.1 → mockstack-0.3.0}/mockstack/display.py

@@ -2,6 +2,8 @@
 
 import logging
 
+from fastapi import FastAPI
+
 from mockstack.config import Settings
 
 
@@ -17,7 +19,7 @@ class ANSIColors:
     UNDERLINE = "\033[4m"
 
 
-def announce(settings: Settings):
+def announce(app: FastAPI, settings: Settings):
     """Log the startup message with the active settings."""
     HIGHLIGHT = ANSIColors.HEADER
     ENDC = ANSIColors.ENDC
@@ -26,8 +28,8 @@ def announce(settings: Settings):
     logger.info(
         f"{HIGHLIGHT}mockstack{ENDC} ready to roll. "
         f"Using strategy: {HIGHLIGHT}{settings.strategy}{ENDC}, "
-        f"templates_dir: {HIGHLIGHT}{settings.templates_dir}{ENDC}. "
     )
+    logger.info(str(app.state.strategy))
     logger.info(
         f"OpenTelemetry enabled: {HIGHLIGHT}{settings.opentelemetry.enabled}{ENDC}, "
         f"endpoint: {HIGHLIGHT}{settings.opentelemetry.endpoint}{ENDC}, "

mockstack-0.3.0/mockstack/intent.py

@@ -0,0 +1,53 @@
+"""Helpers for deducing user intent from a request."""
+
+from fastapi import Request
+
+
+def wants_json(request: Request) -> bool:
+    """Check if the request wants JSON response."""
+    content_type = request.headers.get("Content-Type", "")
+    return any(
+        (
+            content_type.startswith("application/json"),
+            content_type.startswith("text/json"),
+            request.url.path.endswith(".json"),
+        )
+    )
+
+
+def looks_like_a_search(request: Request) -> bool:
+    """Check if the request looks like a search.
+
+    This is a heuristic to try and identify cases where a POST
+    request is used for issuing a search rather than for creating
+    a new resource.
+
+    """
+    return any(
+        (
+            request.url.path.endswith("_search"),
+            request.url.path.endswith("/search"),
+            request.url.path.endswith("_query"),
+        )
+    )
+
+
+def looks_like_a_command(request: Request) -> bool:
+    """Check if the request looks like a command.
+
+    This is a heuristic to try and identify cases where a POST
+    request is used for issuing a command rather than for creating
+    a new resource.
+    """
+    return any(
+        (
+            request.url.path.endswith("_command"),
+            request.url.path.endswith("/command"),
+            request.url.path.endswith("_request"),
+            request.url.path.endswith("/request"),
+            request.url.path.endswith("_run"),
+            request.url.path.endswith("/run"),
+            request.url.path.endswith("_execute"),
+            request.url.path.endswith("/execute"),
+        )
+    )

{mockstack-0.1.1 → mockstack-0.3.0}/mockstack/lifespan.py

@@ -22,7 +22,7 @@ def lifespan_provider(
         This is the context manager that FastAPI will use to manage the lifecycle of the application.
         """
         config.dictConfig(settings.logging)
-        announce(settings)
+        announce(app, settings)
 
         yield
 

mockstack-0.3.0/mockstack/strategies/__init__.py

@@ -0,0 +1,5 @@
+from mockstack.strategies.base import BaseStrategy
+from mockstack.strategies.filefixtures import FileFixturesStrategy
+from mockstack.strategies.proxyrules import ProxyRulesStrategy
+
+__all__ = ["BaseStrategy", "FileFixturesStrategy", "ProxyRulesStrategy"]

{mockstack-0.1.1 → mockstack-0.3.0}/mockstack/strategies/base.py

@@ -4,10 +4,15 @@ from abc import ABC, abstractmethod
 
 from fastapi import Request, Response
 
+from mockstack.config import Settings
+
 
 class BaseStrategy(ABC):
     """Base strategy for MockStack."""
 
+    def __init__(self, settings: Settings, *args, **kwargs):
+        self.settings = settings
+
     @abstractmethod
     async def apply(self, request: Request) -> Response:
         """Apply the strategy to the request and response."""

mockstack-0.3.0/mockstack/strategies/create_mixin.py

@@ -0,0 +1,81 @@
+"""Create mixin class."""
+
+from datetime import datetime, timezone
+from uuid import uuid4
+
+from fastapi import Request, Response, status
+from fastapi.responses import JSONResponse
+from jinja2 import Environment
+
+from mockstack.intent import wants_json
+
+
+class CreateMixin:
+    """A mixin for strategies that need to simulate creation of resources."""
+
+    async def _create(
+        self, request: Request, *, env: Environment, created_resource_metadata: dict
+    ) -> Response:
+        if wants_json(request):
+            # We return a 201 CREATED response with the resource as the body,
+            # potentially injecting the resource ID into the response.
+            resource = await request.json()
+
+            return JSONResponse(
+                status_code=status.HTTP_201_CREATED,
+                content=self._content(
+                    resource,
+                    request=request,
+                    env=env,
+                    created_resource_metadata=created_resource_metadata,
+                ),
+            )
+        else:
+            # We return a 201 CREATED response with an empty body.
+            return Response(
+                status_code=status.HTTP_201_CREATED,
+                content=None,
+            )
+
+    def _content(
+        self,
+        resource: dict,
+        *,
+        env: Environment,
+        request: Request,
+        created_resource_metadata: dict,
+    ) -> dict:
+        """Create a new resource given a request resource.
+
+        We use the request resource as the basis for the new resource.
+        We then inject an identifier into the resource if it doesn't already have one,
+        as well as any other metadata fields that are configured for the strategy.
+
+        """
+
+        def with_metadata(resource: dict, copy=True) -> dict:
+            """Inject metadata fields into the resource."""
+            _resource = resource.copy() if copy else resource
+            for key, value in created_resource_metadata.items():
+                if isinstance(value, str):
+                    _resource[key] = env.from_string(value).render(
+                        self._metadata_context(request)
+                    )
+                else:
+                    _resource[key] = value
+            return _resource
+
+        return with_metadata(resource)
+
+    def _metadata_context(self, request: Request) -> dict:
+        """Context for injecting metadata fields into resources.
+
+        Some care is needed to ensure that we only expose the minimum amount
+        of information here since templates are user-defined.
+
+        """
+        return {
+            "utcnow": lambda: datetime.now(timezone.utc),
+            "uuid4": uuid4,
+            "request": request,
+        }

mockstack-0.3.0/mockstack/strategies/factory.py

@@ -0,0 +1,48 @@
+"""Factory for creating strategies."""
+
+from typing import Type
+
+from fastapi import FastAPI
+
+from mockstack.config import Settings
+from mockstack.strategies import BaseStrategy
+
+
+def name_for(cls: type[BaseStrategy]) -> str:
+    """Get the name of a strategy from its class.
+
+    we support class attributes for the name, otherwise we use the class name
+    without the "Strategy" suffix and convert to lowercase:
+
+    Example:
+
+    >>> name_for(FileFixturesStrategy)
+    "filefixtures"
+
+    """
+    return getattr(cls, "name", cls.__name__.replace("Strategy", "").lower())
+
+
+def available_strategies() -> dict[str, Type[BaseStrategy]]:
+    """Get all available strategies."""
+    return {name_for(subclass): subclass for subclass in BaseStrategy.__subclasses__()}  # type: ignore[type-abstract]
+
+
+def strategy_provider(app: FastAPI, settings: Settings) -> BaseStrategy:
+    """Factory for creating strategies."""
+    strategies = available_strategies()
+
+    if settings.strategy not in strategies:
+        raise ValueError(f"Unknown strategy: {settings.strategy}")
+
+    strategy = strategies[settings.strategy](settings)
+
+    # add strategy to app state for dependency injection
+    app.state.strategy = strategy
+
+    return strategy
+
+
+AVAILABLE_STRATEGIES = tuple(available_strategies().keys())
+
+DEFAULT_STRATEGY = "filefixtures"