mockstack 0.0.3__py3-none-any.whl

mockstack/config.py

@@ -0,0 +1,91 @@
+from functools import lru_cache
+from typing import Any, Literal
+
+from pydantic import DirectoryPath
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class OpenTelemetrySettings(BaseSettings):
+    """Settings for OpenTelemetry."""
+
+    enabled: bool = False
+
+    endpoint: str = "http://localhost:4317/"
+
+    # whether to capture the response body.
+    # this can be heavy, sensitive (PII) and/or not needed depending on the use case.
+    capture_response_body: bool = False
+
+
+class Settings(BaseSettings):
+    """Settings for mockstack.
+
+    Default values are defined below and can be overwritten using an .env file
+    or with environment variables.
+
+    """
+
+    model_config = SettingsConfigDict(
+        env_prefix="mockstack__",
+        env_file=".env",
+        env_nested_delimiter="__",
+    )
+
+    # OpenTelemetry configuration
+    opentelemetry: OpenTelemetrySettings = OpenTelemetrySettings()
+
+    # strategy to use for handling requests
+    strategy: Literal["filefixtures", "proxyrules"] = "filefixtures"
+
+    # base directory for templates used by strategies
+    templates_dir: DirectoryPath = "./templates"  # type: ignore[assignment]
+
+    # metadata fields to inject into created resources.
+    # A few template fields are available. See documentation for more details.
+    created_resource_metadata: dict[str, Any] = {
+        "id": "{{ uuid4() }}",
+        "createdAt": "{{ utcnow().isoformat() }}",
+        "updatedAt": "{{ utcnow().isoformat() }}",
+        "createdBy": "{{ request.headers.get('X-User-Id', uuid4()) }}",
+        "status": dict(code="OK", error_code=None),
+    }
+
+    # fields to inject into missing resources response json.
+    # some services may require such additional fields to be present in the response.
+    missing_resource_fields: dict[str, Any] = dict(
+        code=404,
+        message="mockstack: resource not found",
+        retryable=False,
+    )
+
+    # logging configuration. schema is based on the logging configuration schema:
+    # https://docs.python.org/3/library/logging.config.html#logging-config-dictschema
+    logging: dict[str, Any] = {
+        "version": 1,
+        "disable_existing_loggers": False,
+        "formatters": {
+            "standard": {
+                "format": "     %(levelname)s   [%(name)s] %(message)s",
+            },
+        },
+        "handlers": {
+            "console": {
+                "class": "logging.StreamHandler",
+                "level": "DEBUG",
+                "formatter": "standard",
+                "stream": "ext://sys.stdout",
+            },
+        },
+        "loggers": {
+            "FileFixturesStrategy": {
+                "handlers": ["console"],
+                "level": "INFO",
+            },
+        },
+    }
+
+
+@lru_cache
+def settings_provider() -> Settings:
+    """Provide the settings for the application."""
+    return Settings()

mockstack/display.py

@@ -0,0 +1,35 @@
+"""Display and logging functionality."""
+
+import logging
+
+from mockstack.config import Settings
+
+
+class ANSIColors:
+    HEADER = "\033[95m"
+    OKBLUE = "\033[94m"
+    OKCYAN = "\033[96m"
+    OKGREEN = "\033[92m"
+    WARNING = "\033[93m"
+    FAIL = "\033[91m"
+    ENDC = "\033[0m"
+    BOLD = "\033[1m"
+    UNDERLINE = "\033[4m"
+
+
+def announce(settings: Settings):
+    """Log the startup message with the active settings."""
+    HIGHLIGHT = ANSIColors.HEADER
+    ENDC = ANSIColors.ENDC
+
+    logger = logging.getLogger("uvicorn")
+    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(
+        f"OpenTelemetry enabled: {HIGHLIGHT}{settings.opentelemetry.enabled}{ENDC}, "
+        f"endpoint: {HIGHLIGHT}{settings.opentelemetry.endpoint}{ENDC}, "
+        f"capture_response_body: {HIGHLIGHT}{settings.opentelemetry.capture_response_body}{ENDC}"
+    )

mockstack/identifiers.py

@@ -0,0 +1,84 @@
+"""Identifiers helpers."""
+
+import itertools
+
+
+def prefixes(iterable, reverse=False):
+    """Return an iterator of the prefixes of the iterable.
+
+    Examples:
+    ---------
+    >>> list(prefixes([1, 2, 3]))
+    [(1,), (1, 2), (1, 2, 3)]
+
+    >>> list(prefixes([1, 2, 3], reverse=True))
+    [(1, 2, 3), (1, 2), (1,)]
+
+    """
+    iterator = itertools.accumulate(map(lambda x: (x,), iterable))
+    if reverse:
+        return reversed(list(iterator))
+    return iterator
+
+
+def looks_like_id(segment: str) -> bool:
+    """Check if a URL path segment looks like an ID.
+
+    Identifiers are typically numeric or hexadecimal (e.g. UUIDs) and are used to identify a resource.
+
+    We apply a few simple heuristics to try and provide a good balance between false positives and false negatives.
+
+    Examples:
+    ---------
+    >>> looks_like_id("123")
+    False  # Odd length numeric
+
+    >>> looks_like_id("1234567890")
+    True   # Even length numeric
+
+    >>> looks_like_id("1234567890abcdef")
+    True   # Even length hex
+
+    >>> looks_like_id("3a4e5ad9-17ee-41af-972f-864dfccd4856")
+    True   # UUID with dashes
+
+    >>> looks_like_id("3a4e5ad917ee41af972f864dfccd4856")
+    True   # UUID without dashes
+
+    >>> looks_like_id("project")
+    False  # Not a valid ID format
+
+    >>> looks_like_id("api")
+    False  # Not a valid ID format
+
+    >>> looks_like_id("v1")
+    False  # Not a valid ID format
+
+    """
+    if not segment or segment.isspace():
+        return False
+
+    # Check for special characters that aren't allowed in IDs
+    if any(c in segment for c in "_./+@"):
+        return False
+
+    N = len(segment)
+
+    # Check for UUID format (with or without dashes)
+    if N == 36:
+        # UUID with dashes
+        parts = segment.lower().split("-")
+        if len(parts) == 5 and all(
+            all(c in "0123456789abcdef" for c in p) for p in parts
+        ):
+            lengths = [len(p) for p in parts]
+            if lengths == [8, 4, 4, 4, 12]:
+                return True
+    elif N == 32:
+        # UUID without dashes
+        return all(c in "0123456789abcdefABCDEF" for c in segment)
+
+    # Check for even length numeric or hex
+    return (N % 2 == 0 and segment.isdigit()) or (
+        N % 2 == 0 and all(c in "0123456789abcdefABCDEF" for c in segment)
+    )

mockstack/lifespan.py

@@ -0,0 +1,29 @@
+"""FastAPI application lifecycle management."""
+
+from contextlib import asynccontextmanager
+from logging import config
+from typing import Callable
+
+from fastapi import FastAPI
+
+from mockstack.config import Settings
+from mockstack.display import announce
+
+
+def lifespan_provider(
+    settings: Settings,
+) -> Callable:
+    """Provide the lifespan context manager."""
+
+    @asynccontextmanager
+    async def lifespan(app: FastAPI):
+        """FastAPI application lifespan management.
+
+        This is the context manager that FastAPI will use to manage the lifecycle of the application.
+        """
+        config.dictConfig(settings.logging)
+        announce(settings)
+
+        yield
+
+    return lifespan

mockstack/main.py

@@ -0,0 +1,31 @@
+"""Application entrypoints."""
+
+from fastapi import FastAPI
+
+from mockstack.config import settings_provider
+from mockstack.lifespan import lifespan_provider
+from mockstack.middleware import middleware_provider
+from mockstack.opentelemetry import opentelemetry_provider
+from mockstack.routers.catchall import catchall_router_provider
+from mockstack.routers.homepage import homepage_router_provider
+from mockstack.strategies.factory import strategy_provider
+
+
+def create_app() -> FastAPI:
+    """Create the FastAPI app."""
+    settings = settings_provider()
+
+    app = FastAPI(lifespan=lifespan_provider(settings))
+
+    strategy_provider(app, settings)
+    middleware_provider(app, settings)
+    opentelemetry_provider(app, settings)
+
+    homepage_router_provider(app, settings)
+    catchall_router_provider(app, settings)
+
+    return app
+
+
+# expose top-level app object for fastapi cli
+app = create_app()

mockstack/middleware.py

@@ -0,0 +1,19 @@
+"""Middleware definitionsfor the mockstack app."""
+
+import time
+
+from fastapi import FastAPI, Request
+
+from mockstack.config import Settings
+
+
+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

mockstack/opentelemetry.py

@@ -0,0 +1,45 @@
+"""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.instrumentation.fastapi import FastAPIInstrumentor
+from opentelemetry.sdk.resources import Resource
+from opentelemetry.sdk.trace import TracerProvider
+from opentelemetry.sdk.trace.export import BatchSpanProcessor
+
+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 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/routers/catchall.py

@@ -0,0 +1,33 @@
+"""Routes for the mockstack app."""
+
+from fastapi import FastAPI, Request
+from opentelemetry import trace
+from opentelemetry.propagate import extract
+
+from mockstack.config import Settings
+from mockstack.opentelemetry import span_name_for
+
+
+def catchall_router_provider(app: FastAPI, settings: Settings) -> None:
+    """Create the catch-all routes for the mockstack app."""
+
+    @app.route("/{full_path:path}", methods=["GET", "PATCH", "POST", "PUT", "DELETE"])
+    async def catch_all(request: Request):
+        """Catch all requests and delegate to the strategy."""
+        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 app.state.strategy.apply(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:
+                span.set_attribute("response", response.body)
+
+            return response

mockstack/routers/homepage.py

@@ -0,0 +1,18 @@
+"""Routes for the homepage."""
+
+from fastapi import APIRouter, FastAPI
+
+from mockstack.config import Settings
+
+
+def homepage_router_provider(app: FastAPI, settings: Settings) -> APIRouter:
+    """Provide the homepage routes."""
+
+    router = APIRouter()
+
+    @router.get("/")
+    async def homepage():
+        """Root endpoint."""
+        return {"Hello": "World"}
+
+    return router

mockstack/strategies/base.py

@@ -0,0 +1,14 @@
+"""Base strategy for MockStack."""
+
+from abc import ABC, abstractmethod
+
+from fastapi import Request, Response
+
+
+class BaseStrategy(ABC):
+    """Base strategy for MockStack."""
+
+    @abstractmethod
+    async def apply(self, request: Request) -> Response:
+        """Apply the strategy to the request and response."""
+        pass

mockstack/strategies/factory.py

@@ -0,0 +1,21 @@
+"""Factory for creating strategies."""
+
+from fastapi import FastAPI
+
+from mockstack.config import Settings
+from mockstack.strategies.base import BaseStrategy
+from mockstack.strategies.filefixtures import FileFixturesStrategy
+
+
+def strategy_provider(app: FastAPI, settings: Settings) -> BaseStrategy:
+    """Factory for creating strategies."""
+
+    if settings.strategy == "filefixtures":
+        strategy = FileFixturesStrategy(settings)
+    else:
+        raise ValueError(f"Unknown strategy: {settings.strategy}")
+
+    # add strategy to app state for dependency injection
+    app.state.strategy = strategy
+
+    return strategy

mockstack/strategies/filefixtures.py

@@ -0,0 +1,230 @@
+"""MockStack strategy for using file-based fixtures."""
+
+import logging
+import os
+from datetime import datetime, timezone
+from pathlib import Path
+from uuid import uuid4
+
+from fastapi import HTTPException, Request, Response, status
+from fastapi.responses import JSONResponse
+from jinja2 import Environment, FileSystemLoader
+
+from mockstack.config import Settings
+from mockstack.strategies.base import BaseStrategy
+from mockstack.templating import (
+    iter_possible_template_arguments,
+    missing_template_detail,
+)
+
+
+def is_json_media_type(media_type: str) -> bool:
+    """Check if the media type is JSON."""
+    return media_type in ("application/json", "text/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"),
+        )
+    )
+
+
+class FileFixturesStrategy(BaseStrategy):
+    """Strategy for using file-based fixtures."""
+
+    logger = logging.getLogger("FileFixturesStrategy")
+
+    def __init__(self, settings: Settings, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        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))
+
+    async def apply(self, request: Request) -> Response:
+        match request.method:
+            case "GET":
+                return await self._get(request)
+            case "POST":
+                return await self._post(request)
+            case "PATCH":
+                return await self._patch(request)
+            case "PUT":
+                return await self._put(request)
+            case "DELETE":
+                return await self._delete(request)
+            case _:
+                raise HTTPException(status_code=405, detail="Method not allowed")
+
+    async def _post(self, request: Request) -> Response:
+        """Apply the strategy for POST requests.
+
+        POST requests are typically used for a few different purposes:
+
+        - Creating a new resource
+        - Searching for resources with a complex query that cannot be expressed in a URI
+        - Executing a 'command' of some sort, like a workflow or a batch job
+
+        We try to infer the intent from the request URI and body.
+        We also allow a configuration to specify a default intent.
+
+        """
+        if looks_like_a_search(request):
+            # Searching for resources with a complex query that cannot be expressed in a URI.
+            return self._response_from_template(request)
+        elif looks_like_a_command(request):
+            # Executing a 'command' of some sort, like a workflow or a batch job.
+            # We return a 201 CREATED status code with response from template.
+            return self._response_from_template(
+                request, status_code=status.HTTP_201_CREATED
+            )
+        else:
+            # Creating a new resource.
+            media_type = request.headers.get("Content-Type", "application/json")
+
+            if is_json_media_type(media_type):
+                # 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._created(resource, request=request),
+                )
+            else:
+                # We return a 201 CREATEDresponse with an empty body.
+                return Response(
+                    status_code=status.HTTP_201_CREATED,
+                    content=None,
+                )
+
+    async def _get(self, request: Request) -> Response:
+        """Apply the strategy for GET requests.
+
+        We try to find a template that matches the request.
+
+        for a URI path like `/api/v1/projects/1234`, we try the following templates:
+
+        - api-v1-projects.1234.j2
+        - api-v1-projects.j2
+        - index.j2
+
+        where `1234` is the identifier of the project.
+
+        If we find one, we render it and return the response.
+        If we don't find one, we raise a 404 error.
+
+        """
+        return self._response_from_template(request)
+
+    async def _delete(self, request: Request) -> Response:
+        """Apply the strategy for DELETE requests."""
+        return Response(status_code=status.HTTP_204_NO_CONTENT)
+
+    async def _patch(self, request: Request) -> Response:
+        """Apply the strategy for PATCH requests."""
+        return Response(status_code=status.HTTP_204_NO_CONTENT)
+
+    async def _put(self, request: Request) -> Response:
+        """Apply the strategy for PUT requests."""
+        return Response(status_code=status.HTTP_204_NO_CONTENT)
+
+    def _created(self, resource: dict, *, request: Request) -> 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 self.created_resource_metadata.items():
+                if isinstance(value, str):
+                    _resource[key] = self.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,
+        }
+
+    def _response_from_template(
+        self, request: Request, status_code: int = status.HTTP_200_OK
+    ) -> Response:
+        for template_args in iter_possible_template_arguments(request):
+            filename = self.templates_dir / template_args["name"]
+            self.logger.debug("Looking for template filename: %s", filename)
+            if not os.path.exists(filename):
+                continue
+
+            self.logger.debug("Found template filename: %s", filename)
+            template = self.env.get_template(template_args["name"])
+
+            return Response(
+                template.render(**template_args["context"]),
+                media_type=template_args["media_type"],
+                status_code=status_code,
+            )
+
+        # if we get here, we have no template to render.
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=missing_template_detail(request, templates_dir=self.templates_dir),
+        )
+        """
+        # TODO: return custom fields from settings
+        return JSONResponse(
+            content=self.missing_resource_fields,
+            status_code=status.HTTP_404_NOT_FOUND,
+        )
+        """