mockstack 0.1.1__tar.gz → 0.2.0__tar.gz

{mockstack-0.1.1 → mockstack-0.2.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.2.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.2.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.2.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.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mockstack
-Version: 0.1.1
+Version: 0.2.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.2.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.2.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.2.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,14 @@ 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
 
     # metadata fields to inject into created resources.
     # A few template fields are available. See documentation for more details.
@@ -84,6 +93,26 @@ class Settings(BaseSettings):
         },
     }
 
+    @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.2.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.2.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.1.1 → mockstack-0.2.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.2.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.2.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.2.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"

{mockstack-0.1.1 → mockstack-0.2.0}/mockstack/strategies/filefixtures.py

@@ -11,6 +11,7 @@ from fastapi.responses import JSONResponse
 from jinja2 import Environment, FileSystemLoader
 
 from mockstack.config import Settings
+from mockstack.display import ANSIColors
 from mockstack.strategies.base import BaseStrategy
 from mockstack.templating import (
     iter_possible_template_arguments,
@@ -67,12 +68,25 @@ class FileFixturesStrategy(BaseStrategy):
     logger = logging.getLogger("FileFixturesStrategy")
 
     def __init__(self, settings: Settings, *args, **kwargs):
-        super().__init__(*args, **kwargs)
+        super().__init__(settings, *args, **kwargs)
+
+        if settings.templates_dir is None:
+            raise ValueError("templates_dir is not set")
+
         self.templates_dir = Path(settings.templates_dir)
         self.created_resource_metadata = settings.created_resource_metadata
         self.missing_resource_fields = settings.missing_resource_fields
 
-        self.env = Environment(loader=FileSystemLoader(settings.templates_dir))
+        self.env = Environment(loader=FileSystemLoader(self.templates_dir))
+
+    def __str__(self) -> str:
+        HIGHLIGHT = ANSIColors.HEADER
+        ENDC = ANSIColors.ENDC
+
+        return (
+            f"{HIGHLIGHT}[filefixtures]{ENDC} "
+            f"templates_dir: {HIGHLIGHT}{self.templates_dir}{ENDC}. "
+        )
 
     async def apply(self, request: Request) -> Response:
         match request.method:

mockstack-0.2.0/mockstack/strategies/proxyrules.py

@@ -0,0 +1,150 @@
+"""Strategy for using proxy rules."""
+
+import logging
+import re
+from functools import cached_property
+from typing import Self
+from urllib.parse import urlparse
+
+import httpx
+import yaml
+from fastapi import Request, Response, status
+from fastapi.responses import RedirectResponse
+from starlette.datastructures import Headers
+
+from mockstack.config import Settings
+from mockstack.constants import ProxyRulesRedirectVia
+from mockstack.display import ANSIColors
+from mockstack.strategies.base import BaseStrategy
+
+
+class Rule:
+    """A rule for the proxy rules strategy."""
+
+    def __init__(self, pattern: str, replacement: str, method: str | None = None):
+        self.pattern = pattern
+        self.replacement = replacement
+        self.method = method
+
+    @classmethod
+    def from_dict(cls, data: dict[str, str]) -> Self:
+        return cls(
+            pattern=data["pattern"],
+            replacement=data["replacement"],
+            method=data.get("method", None),
+        )
+
+    def matches(self, request: Request) -> bool:
+        """Check if the rule matches the request."""
+        if self.method is not None and request.method.lower() != self.method.lower():
+            # if rule is limited to a specific HTTP method, validate first.
+            return False
+
+        return re.match(self.pattern, request.url.path) is not None
+
+    def apply(self, request: Request) -> str:
+        """Apply the rule to the request."""
+        return self._url_for(request.url.path)
+
+    def _url_for(self, path: str) -> str:
+        return re.sub(self.pattern, self.replacement, path)
+
+
+class ProxyRulesStrategy(BaseStrategy):
+    """Strategy for using proxy rules."""
+
+    logger = logging.getLogger("ProxyRulesStrategy")
+
+    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
+
+    def __str__(self) -> str:
+        HIGHLIGHT = ANSIColors.HEADER
+        ENDC = ANSIColors.ENDC
+
+        return (
+            f"{HIGHLIGHT}[proxyrules]{ENDC} "
+            f"rules_filename: {HIGHLIGHT}{self.rules_filename}{ENDC}. "
+            f"redirect_via: {HIGHLIGHT}{self.proxyrules_redirect_via}{ENDC}"
+        )
+
+    @cached_property
+    def rules(self) -> list[Rule]:
+        return self.load_rules()
+
+    def load_rules(self) -> list[Rule]:
+        if self.rules_filename is None:
+            raise ValueError("rules_filename is not set")
+
+        with open(self.rules_filename, "r") as file:
+            data = yaml.safe_load(file)
+            return [Rule.from_dict(rule) for rule in data["rules"]]
+
+    def rule_for(self, request: Request) -> Rule | None:
+        try:
+            return next(rule for rule in self.rules if rule.matches(request))
+        except StopIteration:
+            return None
+
+    async def apply(self, request: Request) -> Response:
+        rule = self.rule_for(request)
+        if rule is None:
+            self.logger.warning(f"No rule found for request: {request.url.path=}")
+            return Response(status_code=status.HTTP_404_NOT_FOUND)
+
+        url = rule.apply(request)
+        self.logger.info(f"Redirecting to: {url}")
+
+        match self.proxyrules_redirect_via:
+            case ProxyRulesRedirectVia.HTTP_TEMPORARY_REDIRECT:
+                return RedirectResponse(
+                    url=url, status_code=status.HTTP_307_TEMPORARY_REDIRECT
+                )
+
+            case ProxyRulesRedirectVia.HTTP_PERMANENT_REDIRECT:
+                return RedirectResponse(
+                    url=url, status_code=status.HTTP_301_MOVED_PERMANENTLY
+                )
+
+            case ProxyRulesRedirectVia.REVERSE_PROXY:
+                response = await self.reverse_proxy(request, url)
+                return response
+
+            case _:
+                raise ValueError(
+                    f"Invalid redirect via: {self.proxyrules_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:
+            method = request.method
+            request_content = await request.body()
+            req = client.build_request(
+                method,
+                url,
+                content=request_content,
+                headers=self.reverse_proxy_headers(request.headers, url=url),
+                params=request.url.query,
+            )
+
+            resp = await client.send(req, stream=False)
+            content = resp.read()
+
+            return Response(
+                content=content,
+                status_code=resp.status_code,
+                headers=resp.headers,
+                media_type=resp.headers.get("content-type"),
+            )
+
+    def reverse_proxy_headers(self, headers: Headers, url: str) -> Headers:
+        """Mutate the request headers for the reverse proxy mode."""
+        _headers = headers.mutablecopy()
+
+        # When reverse proxying, we must alter the Host header to the target URL.
+        _headers["host"] = urlparse(url).netloc
+
+        return _headers