nene2-python 1.0.0__py3-none-any.whl

nene2/log/setup.py

@@ -0,0 +1,49 @@
+"""Configure structlog for the application.
+
+Call setup_logging() once at startup (in create_app).
+- production / test: JSON renderer
+- local (development): ConsoleRenderer with colors
+"""
+
+import logging
+import sys
+
+import structlog
+
+
+def setup_logging(app_env: str = "local") -> None:
+    shared_processors: list[structlog.types.Processor] = [
+        structlog.stdlib.add_log_level,
+        structlog.stdlib.add_logger_name,
+        structlog.processors.TimeStamper(fmt="iso"),
+        structlog.contextvars.merge_contextvars,
+        structlog.processors.StackInfoRenderer(),
+    ]
+
+    if app_env == "local":
+        renderer: structlog.types.Processor = structlog.dev.ConsoleRenderer()
+    else:
+        renderer = structlog.processors.JSONRenderer()
+
+    structlog.configure(
+        processors=[
+            *shared_processors,
+            structlog.stdlib.ProcessorFormatter.wrap_for_formatter,
+        ],
+        logger_factory=structlog.stdlib.LoggerFactory(),
+        wrapper_class=structlog.stdlib.BoundLogger,
+        cache_logger_on_first_use=True,
+    )
+
+    formatter = structlog.stdlib.ProcessorFormatter(
+        processor=renderer,
+        foreign_pre_chain=shared_processors,
+    )
+
+    handler = logging.StreamHandler(sys.stdout)
+    handler.setFormatter(formatter)
+
+    root = logging.getLogger()
+    root.handlers.clear()
+    root.addHandler(handler)
+    root.setLevel(logging.INFO)

nene2/mcp/__init__.py

@@ -0,0 +1,11 @@
+"""NENE2 MCP integration — expose UseCases as MCP tools."""
+
+from .http_client import HttpxMcpClient, McpHttpClientProtocol, McpHttpResponse
+from .server import LocalMcpServer
+
+__all__ = [
+    "HttpxMcpClient",
+    "LocalMcpServer",
+    "McpHttpClientProtocol",
+    "McpHttpResponse",
+]

nene2/mcp/http_client.py

@@ -0,0 +1,97 @@
+"""MCP HTTP client — equivalent to PHP LocalMcpHttpClientInterface.
+
+Provides a lightweight HTTP transport for calling a nene2 API from MCP tool handlers.
+The default implementation uses httpx; inject a custom McpHttpClientProtocol for tests.
+"""
+
+from dataclasses import dataclass
+from typing import Protocol, runtime_checkable
+
+import httpx
+from httpx import BaseTransport
+
+
+@dataclass(frozen=True, slots=True)
+class McpHttpResponse:
+    """HTTP response value object returned by McpHttpClientProtocol."""
+
+    status_code: int
+    headers: dict[str, str]
+    body: str
+
+    def is_successful(self) -> bool:
+        return 200 <= self.status_code < 300
+
+    def request_id(self) -> str | None:
+        return self.headers.get("x-request-id")
+
+
+@runtime_checkable
+class McpHttpClientProtocol(Protocol):
+    """Structural contract for MCP HTTP clients."""
+
+    def get(self, base_url: str, path: str) -> McpHttpResponse: ...
+
+    def post(self, base_url: str, path: str, body: dict[str, object]) -> McpHttpResponse: ...
+
+    def put(self, base_url: str, path: str, body: dict[str, object]) -> McpHttpResponse: ...
+
+    def delete(self, base_url: str, path: str) -> McpHttpResponse: ...
+
+    def has_authentication(self) -> bool: ...
+
+
+class HttpxMcpClient:
+    """httpx-backed MCP HTTP client with optional Bearer token authentication.
+
+    Pass a custom transport (e.g. httpx.MockTransport or httpx.WSGITransport)
+    for testing without making real network calls.
+    """
+
+    def __init__(
+        self,
+        bearer_token: str | None = None,
+        *,
+        transport: BaseTransport | None = None,
+    ) -> None:
+        self._bearer_token = bearer_token
+        self._transport = transport
+
+    def get(self, base_url: str, path: str) -> McpHttpResponse:
+        return self._request("GET", base_url, path, None)
+
+    def post(self, base_url: str, path: str, body: dict[str, object]) -> McpHttpResponse:
+        return self._request("POST", base_url, path, body)
+
+    def put(self, base_url: str, path: str, body: dict[str, object]) -> McpHttpResponse:
+        return self._request("PUT", base_url, path, body)
+
+    def delete(self, base_url: str, path: str) -> McpHttpResponse:
+        return self._request("DELETE", base_url, path, None)
+
+    def has_authentication(self) -> bool:
+        return self._bearer_token is not None
+
+    def _request(
+        self,
+        method: str,
+        base_url: str,
+        path: str,
+        body: dict[str, object] | None,
+    ) -> McpHttpResponse:
+        headers: dict[str, str] = {"Accept": "application/json"}
+        if self._bearer_token is not None:
+            headers["Authorization"] = f"Bearer {self._bearer_token}"
+
+        with httpx.Client(transport=self._transport) as client:
+            response = client.request(
+                method,
+                base_url.rstrip("/") + path,
+                json=body,
+                headers=headers,
+            )
+        return McpHttpResponse(
+            status_code=response.status_code,
+            headers=dict(response.headers),
+            body=response.text,
+        )

nene2/mcp/server.py

@@ -0,0 +1,25 @@
+"""LocalMcpServer — thin wrapper around FastMCP with NENE2 defaults.
+
+Provides the framework scaffolding; tool registration is done in the
+application layer (example/mcp.py) using the .tool() decorator.
+"""
+
+from collections.abc import Callable
+from typing import Any, Literal
+
+from mcp.server.fastmcp import FastMCP
+
+
+class LocalMcpServer:
+    """MCP server with sensible defaults for local / stdio transport."""
+
+    def __init__(self, name: str, instructions: str = "") -> None:
+        self._mcp = FastMCP(name, instructions=instructions)
+
+    def tool(self, description: str = "") -> Callable[[Any], Any]:
+        """Register a function as an MCP tool."""
+        return self._mcp.tool(description=description)
+
+    def run(self, transport: Literal["stdio", "sse", "streamable-http"] = "stdio") -> None:
+        """Start the MCP server. Blocks until the client disconnects."""
+        self._mcp.run(transport=transport)

nene2/middleware/__init__.py

@@ -0,0 +1,20 @@
+"""NENE2 middleware pipeline."""
+
+from .domain_exception import DomainExceptionHandlerProtocol
+from .error_handler import ErrorHandlerMiddleware
+from .request_id import RequestIdMiddleware, request_id_var
+from .request_logging import RequestLoggingMiddleware
+from .request_size_limit import RequestSizeLimitMiddleware
+from .security_headers import SecurityHeadersMiddleware
+from .throttle import ThrottleMiddleware
+
+__all__ = [
+    "DomainExceptionHandlerProtocol",
+    "ErrorHandlerMiddleware",
+    "RequestIdMiddleware",
+    "RequestLoggingMiddleware",
+    "RequestSizeLimitMiddleware",
+    "SecurityHeadersMiddleware",
+    "ThrottleMiddleware",
+    "request_id_var",
+]

nene2/middleware/domain_exception.py

@@ -0,0 +1,18 @@
+"""DomainExceptionHandlerProtocol — delegate domain errors to typed handlers."""
+
+from typing import Protocol, runtime_checkable
+
+from starlette.responses import Response
+
+
+@runtime_checkable
+class DomainExceptionHandlerProtocol(Protocol):
+    """Map a domain exception to an HTTP response."""
+
+    def handles(self, exc: Exception) -> bool:
+        """Return True if this handler is responsible for *exc*."""
+        ...
+
+    def handle(self, exc: Exception) -> Response:
+        """Convert *exc* to an HTTP response. Called only when handles() is True."""
+        ...

nene2/middleware/error_handler.py

@@ -0,0 +1,112 @@
+"""Error handler middleware.
+
+Equivalent to PHP Nene2\\Middleware\\ErrorHandlerMiddleware.
+Maps known exceptions to Problem Details responses; all others → 500.
+"""
+
+import logging
+from collections.abc import Awaitable, Callable, MutableMapping
+from typing import Any
+
+from fastapi import Request
+from fastapi.exceptions import RequestValidationError
+from fastapi.responses import JSONResponse
+from starlette.middleware.base import BaseHTTPMiddleware, RequestResponseEndpoint
+from starlette.responses import Response
+
+from nene2.http.problem_details import problem_details_response
+from nene2.validation.exceptions import ValidationError, ValidationException
+
+from .domain_exception import DomainExceptionHandlerProtocol
+
+_ASGIApp = Callable[
+    [
+        MutableMapping[str, Any],
+        Callable[[], Awaitable[MutableMapping[str, Any]]],
+        Callable[[MutableMapping[str, Any]], Awaitable[None]],
+    ],
+    Awaitable[None],
+]
+
+logger = logging.getLogger(__name__)
+
+
+class ErrorHandlerMiddleware(BaseHTTPMiddleware):
+    """Catch-all error handler that maps exceptions to Problem Details responses."""
+
+    def __init__(
+        self,
+        app: _ASGIApp,
+        *,
+        debug: bool = False,
+        domain_handlers: list[DomainExceptionHandlerProtocol] | None = None,
+    ) -> None:
+        super().__init__(app)
+        self.debug = debug
+        self._domain_handlers: list[DomainExceptionHandlerProtocol] = domain_handlers or []
+
+    async def dispatch(self, request: Request, call_next: RequestResponseEndpoint) -> Response:
+        try:
+            return await call_next(request)
+        except ValidationException as exc:
+            return problem_details_response(
+                "validation-failed",
+                "Validation Failed",
+                422,
+                "The request contains invalid values.",
+                extra={"errors": [e.to_dict() for e in exc.errors]},
+            )
+        except Exception as exc:
+            for handler in self._domain_handlers:
+                if handler.handles(exc):
+                    return handler.handle(exc)
+            logger.exception("Unhandled exception")
+            detail = str(exc) if self.debug else "The server encountered an unexpected condition."
+            return problem_details_response(
+                "internal-server-error",
+                "Internal Server Error",
+                500,
+                detail,
+            )
+
+    @staticmethod
+    async def handle_validation_exception(_request: Request, exc: Exception) -> JSONResponse:
+        if not isinstance(exc, ValidationException):
+            raise TypeError(f"Expected ValidationException, got {type(exc)}")
+        return problem_details_response(
+            "validation-failed",
+            "Validation Failed",
+            422,
+            "The request contains invalid values.",
+            extra={"errors": [e.to_dict() for e in exc.errors]},
+        )
+
+
+async def request_validation_error_handler(_request: Request, exc: Exception) -> JSONResponse:
+    """Convert FastAPI RequestValidationError to nene2 Problem Details (422).
+
+    Register with FastAPI to replace the default Pydantic validation error format::
+
+        from fastapi.exceptions import RequestValidationError
+        from nene2.middleware.error_handler import request_validation_error_handler
+
+        app.add_exception_handler(RequestValidationError, request_validation_error_handler)
+    """
+    if not isinstance(exc, RequestValidationError):
+        raise TypeError(f"Expected RequestValidationError, got {type(exc)}")
+
+    errors: list[ValidationError] = []
+    for raw in exc.errors():
+        loc = raw.get("loc", ())
+        field = ".".join(str(part) for part in loc if part != "body") or "request"
+        message = str(raw.get("msg", "Invalid value."))
+        code = str(raw.get("type", "invalid"))
+        errors.append(ValidationError(field=field or "request", message=message, code=code))
+
+    return problem_details_response(
+        "validation-failed",
+        "Validation Failed",
+        422,
+        "The request contains invalid values.",
+        extra={"errors": [e.to_dict() for e in errors]},
+    )

nene2/middleware/request_id.py

@@ -0,0 +1,45 @@
+"""Request ID middleware.
+
+Attaches a UUID v4 X-Request-Id to every request/response.
+Uses contextvars so downstream code (e.g. structlog) can read the ID.
+"""
+
+import re
+import uuid
+from contextvars import ContextVar
+
+from starlette.middleware.base import BaseHTTPMiddleware, RequestResponseEndpoint
+from starlette.requests import Request
+from starlette.responses import Response
+
+_REQUEST_ID_HEADER = "X-Request-Id"
+
+# UUID v4 canonical form — 8-4-4-4-12 hex, version=4, variant=8/9/a/b
+_UUID_V4_RE = re.compile(
+    r"^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$",
+    re.IGNORECASE,
+)
+
+request_id_var: ContextVar[str] = ContextVar("request_id", default="")
+
+
+def _validated_request_id(value: str | None) -> str:
+    """Return value if it is a valid UUID v4, otherwise generate a fresh one."""
+    if value and _UUID_V4_RE.match(value):
+        return value.lower()
+    return str(uuid.uuid4())
+
+
+class RequestIdMiddleware(BaseHTTPMiddleware):
+    """Generate or forward X-Request-Id and expose it via contextvars.
+
+    Client-supplied X-Request-Id is accepted only when it matches UUID v4
+    format, preventing log injection via arbitrary header values.
+    """
+
+    async def dispatch(self, request: Request, call_next: RequestResponseEndpoint) -> Response:
+        request_id = _validated_request_id(request.headers.get(_REQUEST_ID_HEADER))
+        request_id_var.set(request_id)
+        response = await call_next(request)
+        response.headers[_REQUEST_ID_HEADER] = request_id
+        return response

nene2/middleware/request_logging.py

@@ -0,0 +1,34 @@
+"""Request logging middleware using structlog."""
+
+import time
+
+import structlog
+from starlette.middleware.base import BaseHTTPMiddleware, RequestResponseEndpoint
+from starlette.requests import Request
+from starlette.responses import Response
+
+from .request_id import request_id_var
+
+logger: structlog.stdlib.BoundLogger = structlog.get_logger(__name__)
+
+
+class RequestLoggingMiddleware(BaseHTTPMiddleware):
+    """Log each request and response with method, path, status, and duration."""
+
+    async def dispatch(self, request: Request, call_next: RequestResponseEndpoint) -> Response:
+        start = time.perf_counter()
+        structlog.contextvars.clear_contextvars()
+        structlog.contextvars.bind_contextvars(
+            request_id=request_id_var.get(),
+            method=request.method,
+            path=request.url.path,
+        )
+        logger.info("request.received")
+        response = await call_next(request)
+        duration_ms = round((time.perf_counter() - start) * 1000, 1)
+        structlog.contextvars.bind_contextvars(
+            status_code=response.status_code,
+            duration_ms=duration_ms,
+        )
+        logger.info("request.completed")
+        return response

nene2/middleware/request_size_limit.py

@@ -0,0 +1,52 @@
+"""Request body size limit middleware.
+
+Rejects requests whose body exceeds the configured maximum.
+Protects against memory exhaustion from oversized payloads, including
+chunked-transfer requests that omit the Content-Length header.
+"""
+
+from starlette.middleware.base import BaseHTTPMiddleware, RequestResponseEndpoint
+from starlette.requests import Request
+from starlette.responses import Response
+
+from nene2.http.problem_details import problem_details_response
+
+_DEFAULT_MAX_BYTES = 1_048_576  # 1 MiB
+
+_TOO_LARGE = "Request body must not exceed {limit} bytes."
+
+
+class RequestSizeLimitMiddleware(BaseHTTPMiddleware):
+    """Reject requests whose body exceeds max_bytes.
+
+    Checks the Content-Length header first for a fast pre-flight reject,
+    then reads the actual body to catch chunked-transfer requests that
+    omit Content-Length entirely.
+    """
+
+    def __init__(self, app: object, *, max_bytes: int = _DEFAULT_MAX_BYTES) -> None:
+        super().__init__(app)  # type: ignore[arg-type]
+        self._max_bytes = max_bytes
+
+    async def dispatch(self, request: Request, call_next: RequestResponseEndpoint) -> Response:
+        content_length = request.headers.get("Content-Length")
+        if content_length is not None:
+            try:
+                if int(content_length) > self._max_bytes:
+                    return self._too_large()
+            except ValueError:
+                pass
+
+        body = await request.body()
+        if len(body) > self._max_bytes:
+            return self._too_large()
+
+        return await call_next(request)
+
+    def _too_large(self) -> Response:
+        return problem_details_response(
+            "payload-too-large",
+            "Payload Too Large",
+            413,
+            _TOO_LARGE.format(limit=self._max_bytes),
+        )

nene2/middleware/security_headers.py

@@ -0,0 +1,37 @@
+"""Security headers middleware.
+
+Adds defensive HTTP headers to every response.
+CSP is skipped for OpenAPI documentation paths (/docs, /redoc, /openapi.json)
+because Swagger UI loads assets from CDN which would be blocked by default-src 'self'.
+"""
+
+from starlette.middleware.base import BaseHTTPMiddleware, RequestResponseEndpoint
+from starlette.requests import Request
+from starlette.responses import Response
+
+_HEADERS: dict[str, str] = {
+    "X-Content-Type-Options": "nosniff",
+    "X-Frame-Options": "DENY",
+    "Referrer-Policy": "strict-origin-when-cross-origin",
+    "Content-Security-Policy": "default-src 'self'",
+    "Permissions-Policy": "geolocation=(), microphone=()",
+}
+
+_OPENAPI_PATHS: frozenset[str] = frozenset({"/docs", "/redoc", "/openapi.json"})
+
+
+class SecurityHeadersMiddleware(BaseHTTPMiddleware):
+    """Attach security headers to every HTTP response.
+
+    Content-Security-Policy is omitted for OpenAPI documentation paths so that
+    Swagger UI and ReDoc (which load assets from CDN) continue to work in development.
+    """
+
+    async def dispatch(self, request: Request, call_next: RequestResponseEndpoint) -> Response:
+        response = await call_next(request)
+        is_openapi_path = request.url.path in _OPENAPI_PATHS
+        for header, value in _HEADERS.items():
+            if is_openapi_path and header == "Content-Security-Policy":
+                continue
+            response.headers[header] = value
+        return response

nene2/middleware/throttle.py

@@ -0,0 +1,72 @@
+"""Fixed-window rate limiting middleware.
+
+Tracks request counts per client IP in an in-memory dict.
+Exceeding the limit returns 429 with a Retry-After header.
+
+.. warning::
+    ``X-Forwarded-For`` is trusted as-is when present.  In environments
+    **without** a trusted reverse proxy this header can be spoofed by clients,
+    allowing them to bypass the rate limit.  Deploy behind a proxy that strips
+    or overwrites the header (e.g. nginx ``proxy_set_header X-Forwarded-For
+    $remote_addr``) before enabling this middleware in production.
+"""
+
+import threading
+import time
+
+from starlette.middleware.base import BaseHTTPMiddleware, RequestResponseEndpoint
+from starlette.requests import Request
+from starlette.responses import Response
+
+from nene2.http.problem_details import problem_details_response
+
+_DEFAULT_LIMIT = 60
+_DEFAULT_WINDOW = 60  # seconds
+
+
+class ThrottleMiddleware(BaseHTTPMiddleware):
+    """Fixed-window rate limiter keyed by client IP."""
+
+    def __init__(
+        self,
+        app: object,
+        *,
+        limit: int = _DEFAULT_LIMIT,
+        window: int = _DEFAULT_WINDOW,
+    ) -> None:
+        super().__init__(app)  # type: ignore[arg-type]
+        self._limit = limit
+        self._window = window
+        self._counts: dict[str, tuple[int, float]] = {}
+        self._lock = threading.Lock()
+
+    def _client_key(self, request: Request) -> str:
+        forwarded = request.headers.get("X-Forwarded-For")
+        if forwarded:
+            return forwarded.split(",")[0].strip()
+        return request.client.host if request.client else "unknown"
+
+    def _is_allowed(self, key: str) -> tuple[bool, int]:
+        now = time.monotonic()
+        with self._lock:
+            count, window_start = self._counts.get(key, (0, now))
+            if now - window_start >= self._window:
+                count, window_start = 0, now
+            count += 1
+            self._counts[key] = (count, window_start)
+            remaining = max(0, self._window - int(now - window_start))
+        return count <= self._limit, remaining
+
+    async def dispatch(self, request: Request, call_next: RequestResponseEndpoint) -> Response:
+        key = self._client_key(request)
+        allowed, retry_after = self._is_allowed(key)
+        if not allowed:
+            response = problem_details_response(
+                "too-many-requests",
+                "Too Many Requests",
+                429,
+                f"Rate limit exceeded. Retry after {retry_after} seconds.",
+            )
+            response.headers["Retry-After"] = str(retry_after)
+            return response
+        return await call_next(request)

nene2/use_case/__init__.py

@@ -0,0 +1,5 @@
+"""UseCase contracts — synchronous and asynchronous Protocol definitions."""
+
+from .protocols import AsyncUseCaseProtocol, UseCaseProtocol
+
+__all__ = ["AsyncUseCaseProtocol", "UseCaseProtocol"]

nene2/use_case/protocols.py

@@ -0,0 +1,24 @@
+"""Structural type contracts for UseCase and AsyncUseCase.
+
+UseCaseProtocol — synchronous execute(input_) -> output
+AsyncUseCaseProtocol — async execute(input_) -> output (awaitable)
+
+Both use Python 3.12 generic syntax; any class with a matching
+execute() signature satisfies them structurally (no inheritance needed).
+"""
+
+from typing import Protocol, runtime_checkable
+
+
+@runtime_checkable
+class UseCaseProtocol[I, O](Protocol):
+    """Synchronous use-case contract."""
+
+    def execute(self, input_: I) -> O: ...
+
+
+@runtime_checkable
+class AsyncUseCaseProtocol[I, O](Protocol):
+    """Asynchronous use-case contract — execute must be a coroutine."""
+
+    async def execute(self, input_: I) -> O: ...

nene2/validation/__init__.py

@@ -0,0 +1,5 @@
+"""Validation exceptions — equivalent to PHP ValidationException / ValidationError."""
+
+from .exceptions import ValidationError, ValidationException
+
+__all__ = ["ValidationError", "ValidationException"]

nene2/validation/exceptions.py

@@ -0,0 +1,34 @@
+"""Validation exceptions.
+
+Equivalent to PHP Nene2\\Validation\\ValidationException and ValidationError.
+Raised by handlers or use-cases to produce a 422 validation-failed Problem Details response.
+"""
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True, slots=True)
+class ValidationError:
+    """A single field-level validation failure."""
+
+    field: str
+    message: str
+    code: str
+
+    def __post_init__(self) -> None:
+        if not self.field or not self.message or not self.code:
+            raise ValueError("field, message, and code must be non-empty strings")
+
+    def to_dict(self) -> dict[str, str]:
+        return {"field": self.field, "message": self.message, "code": self.code}
+
+
+class ValidationException(Exception):
+    """Raised when one or more validation rules fail.
+
+    ErrorHandlerMiddleware maps this to a 422 validation-failed Problem Details response.
+    """
+
+    def __init__(self, errors: list[ValidationError]) -> None:
+        super().__init__("Validation failed")
+        self.errors = errors