mockstack 0.0.3__tar.gz

mockstack-0.0.3/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) [year] [fullname]
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mockstack-0.0.3/PKG-INFO

@@ -0,0 +1,13 @@
+Metadata-Version: 2.4
+Name: mockstack
+Version: 0.0.3
+Requires-Python: >=3.11
+License-File: LICENSE
+Requires-Dist: colorama>=0.4.6
+Requires-Dist: fastapi[standard]>=0.115.12
+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
+Dynamic: license-file

mockstack-0.0.3/README.md

@@ -0,0 +1,62 @@
+# mockstack
+
+[![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)
+
+An API mocking workhorse :racehorse:
+
+Enabling a sane development lifecycle for microservice-oriented architectures.
+
+Highlights include:
+
+* Multiple strategies for handling requests such as Jinja2 template files with intelligent URL request-to-template routing, proxy strategy, and mixed strategies. :game_die:
+* Observability via OpenTelemetry integration. Get detailed traces of your sessions instantly reported to backends such as Grafana, Jaeger, Zipkin, etc. :eyes:
+* Configurability via `pydantic-settings` supports customizing behaviour via environment variables and a `.env` file. :flags:
+* Comprehensive unit-tests, linting and formatting coverage as well as vulnerabilities and security scanning with full CI automation to ensure stability and a high-quality codebase for production-grade use. :+1:
+
+
+## Installation
+
+Install using [uv](https://docs.astral.sh/uv/). This will create a virtualenv for you and install all dependencies:
+
+    uv sync
+    uv pip install -e .
+
+
+## Usage
+
+Copy the included [.env.example](.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 fastapi dev mockstack/main.py
+
+Or, run in production mode:
+
+    uv run fastapi run mockstack/main.py
+
+Available configuration options are [here](./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 fastapi run mockstack/main.py
+
+Out of the box, you get the following behavior when using the default `filefixtures` strategy:
+
+- The HTTP request `GET /someservice/api/v1/user/c27f5b2b-6e81-420d-a4e4-6426e1c32db8` will try to find `<templates_dir>/someservice-api-v1-user.c27f5b2b-6e81-420d-a4e4-6426e1c32db8.j2`,
+  and will fallback to `<templates_dir>/someservice-api-v1-user.j2` (and finally to `index.j2` if exists). These are j2 files that have access to request body context variables.
+- The HTTP request `POST /someservice/api/v2/item` with a JSON body will attempt to intelligently simulate the creation of a resource, returning the appropriate status code and will echo back the provided request resource, after injecting additional metadata fields based on strategy configuration. This is useful for services that expect fields such as `id` and `created_at` on returned created resources.
+- HTTP requests for `DELETE` / `PUT` / `PATCH` are a no-op by default, simply returning the appropriate status code.
+- The HTTP request `POST /someservice/api/v2/embedding_search` will be handled as a search request rather than a resource creation, returning an appropriate http status code and mock results based on user-configurable formatting.
+
+Overall, the design philosophy is that things "just work". The framework attempts to intelligently deduce the intent of the request as much as possible and act accordingly,
+while leaving room for advanced users to go in and customize behavior using the configuration options.
+
+
+## Testing
+
+Invoke unit-tests with:
+
+    uv run python -m pytest
+
+Linting, formatting, static type checks etc. are all managed via [pre-commit](https://pre-commit.com/) hooks. These will run automatically on every commit. You can invoke these manually on all files with:
+
+    pre-commit run --all-files

mockstack-0.0.3/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-0.0.3/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-0.0.3/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-0.0.3/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-0.0.3/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-0.0.3/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-0.0.3/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-0.0.3/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-0.0.3/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-0.0.3/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-0.0.3/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