cloud-dog-api-kit 0.13.0__py3-none-any.whl

cloud_dog_api_kit/middleware/__init__.py

@@ -0,0 +1,39 @@
+# Copyright 2026 Cloud-Dog, Viewdeck Engineering Limited
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# cloud_dog_api_kit — Middleware components
+#
+# Licence: Proprietary — Cloud-Dog AI Platform
+# Owner: Cloud-Dog AI
+# Description: Standard middleware components (logging, CORS, timing, timeout).
+# Related requirements: FR11.1, FR12.1, FR13.1
+# Related architecture: SA1
+
+"""Middleware components for cloud_dog_api_kit."""
+
+from __future__ import annotations
+
+from cloud_dog_api_kit.middleware.cors import configure_cors
+from cloud_dog_api_kit.middleware.logging import RequestLoggingMiddleware
+from cloud_dog_api_kit.middleware.request_size_limit import RequestSizeLimitMiddleware
+from cloud_dog_api_kit.middleware.timing import TimingMiddleware
+from cloud_dog_api_kit.middleware.timeout import TimeoutMiddleware
+
+__all__ = [
+    "RequestLoggingMiddleware",
+    "RequestSizeLimitMiddleware",
+    "TimingMiddleware",
+    "TimeoutMiddleware",
+    "configure_cors",
+]

cloud_dog_api_kit/middleware/cors.py

@@ -0,0 +1,74 @@
+# Copyright 2026 Cloud-Dog, Viewdeck Engineering Limited
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# cloud_dog_api_kit — CORS configuration helper
+#
+# Licence: Proprietary — Cloud-Dog AI Platform
+# Owner: Cloud-Dog AI
+# Description: CORS middleware configuration with production-safe defaults.
+#   Does not use wildcard origins unless explicitly configured.
+# Related requirements: FR11.1, CS1.4
+# Related architecture: CC1.12
+
+"""CORS configuration helper for cloud_dog_api_kit."""
+
+from __future__ import annotations
+
+
+from fastapi import FastAPI
+from starlette.middleware.cors import CORSMiddleware
+
+
+def configure_cors(
+    app: FastAPI,
+    allowed_origins: list[str] | None = None,
+    allow_credentials: bool = True,
+    allow_methods: list[str] | None = None,
+    allow_headers: list[str] | None = None,
+) -> None:
+    """Configure CORS middleware on a FastAPI application.
+
+    Production-safe defaults: explicit origins only, not wildcard ``*``
+    unless explicitly provided.
+
+    Args:
+        app: The FastAPI application.
+        allowed_origins: List of allowed origins. Defaults to empty (no CORS).
+        allow_credentials: Whether to allow credentials. Defaults to True.
+        allow_methods: Allowed HTTP methods. Defaults to standard set.
+        allow_headers: Allowed headers. Defaults to standard set.
+
+    Related tests: UT1.25_CORSHelper
+    """
+    origins = allowed_origins or []
+    methods = allow_methods or ["GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS"]
+    headers = allow_headers or [
+        "Authorization",
+        "X-API-Key",
+        "X-Request-Id",
+        "X-Correlation-Id",
+        "X-App-Id",
+        "X-Host-Id",
+        "Content-Type",
+        "Accept",
+        "Idempotency-Key",
+    ]
+
+    app.add_middleware(
+        CORSMiddleware,
+        allow_origins=origins,
+        allow_credentials=allow_credentials,
+        allow_methods=methods,
+        allow_headers=headers,
+    )

cloud_dog_api_kit/middleware/logging.py

@@ -0,0 +1,98 @@
+# Copyright 2026 Cloud-Dog, Viewdeck Engineering Limited
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# cloud_dog_api_kit — Request/response logging middleware
+#
+# Licence: Proprietary — Cloud-Dog AI Platform
+# Owner: Cloud-Dog AI
+# Description: Middleware that logs request/response details with header
+#   redaction for sensitive values (Authorization, X-API-Key, Cookie).
+# Related requirements: FR12.1, CS1.2, CS1.6
+# Related architecture: CC1.13
+
+"""Request/response logging middleware for cloud_dog_api_kit."""
+
+from __future__ import annotations
+
+import logging
+import time
+from typing import Callable
+
+from starlette.middleware.base import BaseHTTPMiddleware
+from starlette.requests import Request
+from starlette.responses import Response
+
+REDACTED_HEADERS = frozenset({"authorization", "x-api-key", "cookie"})
+
+logger = logging.getLogger("cloud_dog_api_kit.request_logging")
+
+
+class RequestLoggingMiddleware(BaseHTTPMiddleware):
+    """Request/response logging middleware with header redaction.
+
+    Logs: request_id, correlation_id, user/system identity, method, path,
+    status code, duration (ms), client IP. Redacts sensitive headers.
+
+    Args:
+        app: The ASGI application.
+
+    Related tests: UT1.26_RequestLogging, SEC1.5_SecretRedaction
+    """
+
+    async def dispatch(self, request: Request, call_next: Callable) -> Response:
+        """Log request and response details.
+
+        Args:
+            request: The incoming HTTP request.
+            call_next: The next middleware or handler.
+
+        Returns:
+            The HTTP response.
+        """
+        request_id = getattr(request.state, "request_id", "")
+        correlation_id = getattr(request.state, "correlation_id", None)
+        user = getattr(request.state, "user", None)
+        client_ip = request.client.host if request.client else "unknown"
+
+        logger.info(
+            "Request started",
+            extra={
+                "request_id": request_id,
+                "correlation_id": correlation_id,
+                "user": user,
+                "method": request.method,
+                "path": request.url.path,
+                "client_ip": client_ip,
+            },
+        )
+
+        start_time = time.monotonic()
+        response = await call_next(request)
+        duration_ms = round((time.monotonic() - start_time) * 1000, 2)
+
+        logger.info(
+            "Request completed",
+            extra={
+                "request_id": request_id,
+                "correlation_id": correlation_id,
+                "user": user,
+                "method": request.method,
+                "path": request.url.path,
+                "status_code": response.status_code,
+                "duration_ms": duration_ms,
+                "client_ip": client_ip,
+            },
+        )
+
+        return response

cloud_dog_api_kit/middleware/request_size_limit.py

@@ -0,0 +1,86 @@
+# Copyright 2026 Cloud-Dog, Viewdeck Engineering Limited
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# cloud_dog_api_kit — Request size limit middleware
+#
+# Licence: Proprietary — Cloud-Dog AI Platform
+# Owner: Cloud-Dog AI
+# Description: Middleware that enforces a maximum request body size and
+#   returns a standard envelope with HTTP 413 when exceeded.
+# Related requirements: FR18.8
+# Related architecture: SA1
+
+"""Request body size limit middleware for cloud_dog_api_kit."""
+
+from __future__ import annotations
+
+from typing import Any, Callable
+
+from starlette.middleware.base import BaseHTTPMiddleware
+from starlette.requests import Request
+from starlette.responses import JSONResponse, Response
+
+from cloud_dog_api_kit.envelopes.error import error_envelope
+
+
+class RequestSizeLimitMiddleware(BaseHTTPMiddleware):
+    """Enforce a maximum request body size.
+
+    The middleware checks `Content-Length` when available and validates the
+    effective byte size by reading the request body when needed.
+
+    Args:
+        app: The ASGI application.
+        max_bytes: Maximum allowed body size in bytes.
+
+    Related tests: UT1.44_RequestSizeLimit
+    """
+
+    def __init__(self, app: Any, max_bytes: int) -> None:
+        if max_bytes < 1:
+            raise ValueError("max_bytes must be >= 1")
+        super().__init__(app)
+        self._max_bytes = max_bytes
+
+    async def dispatch(self, request: Request, call_next: Callable) -> Response:
+        """Reject requests larger than the configured threshold."""
+        content_length = request.headers.get("content-length")
+        if content_length:
+            try:
+                if int(content_length) > self._max_bytes:
+                    return self._too_large_response(request)
+            except ValueError:
+                # Non-integer content length is treated as invalid request size.
+                return self._too_large_response(request)
+
+        body = await request.body()
+        if len(body) > self._max_bytes:
+            return self._too_large_response(request)
+        return await call_next(request)
+
+    def _too_large_response(self, request: Request) -> JSONResponse:
+        """Build a standard 413 error response."""
+        request_id = getattr(request.state, "request_id", "")
+        correlation_id = getattr(request.state, "correlation_id", None)
+        return JSONResponse(
+            status_code=413,
+            content=error_envelope(
+                code="INVALID_REQUEST",
+                message=f"Request body exceeds maximum size ({self._max_bytes} bytes)",
+                details={"max_bytes": self._max_bytes},
+                retryable=False,
+                request_id=request_id,
+                correlation_id=correlation_id,
+            ),
+        )

cloud_dog_api_kit/middleware/timeout.py

@@ -0,0 +1,78 @@
+# Copyright 2026 Cloud-Dog, Viewdeck Engineering Limited
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# cloud_dog_api_kit — Request timeout middleware
+#
+# Licence: Proprietary — Cloud-Dog AI Platform
+# Owner: Cloud-Dog AI
+# Description: Configurable request timeout middleware that returns a standard
+#   TIMEOUT error envelope when a request exceeds the configured duration.
+# Related requirements: FR13.1
+# Related architecture: CC1.13
+
+"""Request timeout middleware for cloud_dog_api_kit."""
+
+from __future__ import annotations
+
+import asyncio
+from typing import Any, Callable
+
+from starlette.middleware.base import BaseHTTPMiddleware
+from starlette.requests import Request
+from starlette.responses import JSONResponse, Response
+
+from cloud_dog_api_kit.envelopes.error import error_envelope
+
+
+class TimeoutMiddleware(BaseHTTPMiddleware):
+    """Request timeout middleware.
+
+    Returns a standard TIMEOUT error envelope when a request exceeds
+    the configured duration. Streaming endpoints should use jobs instead.
+
+    Args:
+        app: The ASGI application.
+        timeout_seconds: Default request timeout in seconds. Defaults to 30.
+
+    Related tests: UT1.27_TimeoutMiddleware
+    """
+
+    def __init__(self, app: Any, timeout_seconds: float = 30.0) -> None:
+        super().__init__(app)
+        self._timeout = timeout_seconds
+
+    async def dispatch(self, request: Request, call_next: Callable) -> Response:
+        """Process request with timeout enforcement.
+
+        Args:
+            request: The incoming HTTP request.
+            call_next: The next middleware or handler.
+
+        Returns:
+            The HTTP response or a TIMEOUT error envelope.
+        """
+        try:
+            return await asyncio.wait_for(
+                call_next(request),
+                timeout=self._timeout,
+            )
+        except asyncio.TimeoutError:
+            request_id = getattr(request.state, "request_id", "")
+            body = error_envelope(
+                code="TIMEOUT",
+                message=f"Request timed out after {self._timeout}s",
+                retryable=True,
+                request_id=request_id,
+            )
+            return JSONResponse(status_code=504, content=body)

cloud_dog_api_kit/middleware/timing.py

@@ -0,0 +1,52 @@
+# Copyright 2026 Cloud-Dog, Viewdeck Engineering Limited
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# cloud_dog_api_kit — Timing middleware
+#
+# Licence: Proprietary — Cloud-Dog AI Platform
+# Owner: Cloud-Dog AI
+# Description: Measures request duration and exposes it via response header.
+# Related requirements: FR12.1
+# Related architecture: SA1
+
+"""Request timing middleware for cloud_dog_api_kit."""
+
+from __future__ import annotations
+
+import time
+from typing import Any, Callable
+
+from starlette.middleware.base import BaseHTTPMiddleware
+from starlette.requests import Request
+from starlette.responses import Response
+
+
+class TimingMiddleware(BaseHTTPMiddleware):
+    """Measures request duration and sets response header.
+
+    Adds `X-Response-Time-Ms` header and stores `request.state.duration_ms`.
+    """
+
+    def __init__(self, app: Any, header_name: str = "X-Response-Time-Ms") -> None:
+        super().__init__(app)
+        self._header_name = header_name
+
+    async def dispatch(self, request: Request, call_next: Callable) -> Response:
+        """Handle dispatch."""
+        start = time.monotonic()
+        response = await call_next(request)
+        duration_ms = round((time.monotonic() - start) * 1000, 2)
+        setattr(request.state, "duration_ms", duration_ms)
+        response.headers[self._header_name] = str(duration_ms)
+        return response

cloud_dog_api_kit/openapi/__init__.py

@@ -0,0 +1,30 @@
+# Copyright 2026 Cloud-Dog, Viewdeck Engineering Limited
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# cloud_dog_api_kit — OpenAPI customisation helpers
+#
+# Licence: Proprietary — Cloud-Dog AI Platform
+# Owner: Cloud-Dog AI
+# Description: Helpers for OpenAPI schema customisation and versioning.
+# Related requirements: FR10.1, FR10.2, FR10.4
+# Related architecture: CC1.17
+
+"""OpenAPI customisation helpers for cloud_dog_api_kit."""
+
+from __future__ import annotations
+
+from cloud_dog_api_kit.openapi.customise import configure_openapi
+from cloud_dog_api_kit.openapi.route import create_openapi_router
+
+__all__ = ["configure_openapi", "create_openapi_router"]

cloud_dog_api_kit/openapi/customise.py

@@ -0,0 +1,69 @@
+# Copyright 2026 Cloud-Dog, Viewdeck Engineering Limited
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# cloud_dog_api_kit — OpenAPI customisation
+#
+# Licence: Proprietary — Cloud-Dog AI Platform
+# Owner: Cloud-Dog AI
+# Description: Helpers for OpenAPI schema customisation, security schemes,
+#   and documentation behaviours.
+# Related requirements: FR10.1, FR10.2
+# Related architecture: SA1, CC1.17
+
+"""OpenAPI customisation helpers."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from fastapi import FastAPI
+
+
+def configure_openapi(
+    app: FastAPI,
+    tags: list[dict] | None = None,
+    security_schemes: dict | None = None,
+) -> None:
+    """Configure OpenAPI schema customisation on a FastAPI application.
+
+    Args:
+        app: The FastAPI application.
+        tags: OpenAPI tag metadata for endpoint grouping.
+        security_schemes: Security scheme definitions.
+
+    Related tests: UT1.31_OpenAPICustomise
+    """
+    if tags:
+        app.openapi_tags = tags
+
+    if security_schemes:
+
+        def _custom_openapi() -> dict[str, Any]:
+            if app.openapi_schema:
+                return app.openapi_schema
+            from fastapi.openapi.utils import get_openapi
+
+            schema = get_openapi(
+                title=app.title,
+                version=app.version,
+                description=app.description,
+                routes=app.routes,
+                tags=app.openapi_tags,
+            )
+            schema.setdefault("components", {})
+            schema["components"]["securitySchemes"] = security_schemes
+            app.openapi_schema = schema
+            return schema
+
+        app.openapi = _custom_openapi  # type: ignore[method-assign]

cloud_dog_api_kit/openapi/route.py

@@ -0,0 +1,46 @@
+# Copyright 2026 Cloud-Dog, Viewdeck Engineering Limited
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# cloud_dog_api_kit — OpenAPI spec route helper
+#
+# Licence: Proprietary — Cloud-Dog AI Platform
+# Owner: Cloud-Dog AI
+# Description: Provides a helper for serving an OpenAPI schema via a stable
+#   endpoint.
+# Related requirements: FR10.1
+# Related architecture: SA1
+
+"""OpenAPI spec route helper for cloud_dog_api_kit."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from fastapi import APIRouter, FastAPI
+
+
+def create_openapi_router(
+    app: FastAPI,
+    path: str = "/openapi.json",
+    tags: list[str] | None = None,
+) -> APIRouter:
+    """Create a router that serves the OpenAPI schema for the given app."""
+    router = APIRouter(tags=tags or ["openapi"])
+
+    @router.get(path)
+    async def openapi_schema() -> dict[str, Any]:
+        """Return the OpenAPI schema."""
+        return app.openapi()
+
+    return router

cloud_dog_api_kit/routers/__init__.py

@@ -0,0 +1,41 @@
+# Copyright 2026 Cloud-Dog, Viewdeck Engineering Limited
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# cloud_dog_api_kit — Router helpers
+#
+# Licence: Proprietary — Cloud-Dog AI Platform
+# Owner: Cloud-Dog AI
+# Description: Router factories (CRUD, health, jobs, version) for consistent
+#   API structure.
+# Related requirements: FR4.1, FR4.2, FR6.1, FR7.1
+# Related architecture: SA1
+
+"""Router helpers for cloud_dog_api_kit."""
+
+from __future__ import annotations
+
+from cloud_dog_api_kit.routers.crud import CRUDService, create_crud_router, create_versioned_router
+from cloud_dog_api_kit.routers.health import HealthCheck, create_health_router
+from cloud_dog_api_kit.routers.jobs import create_job_endpoint
+from cloud_dog_api_kit.routers.version import create_version_router
+
+__all__ = [
+    "CRUDService",
+    "create_crud_router",
+    "create_versioned_router",
+    "HealthCheck",
+    "create_health_router",
+    "create_job_endpoint",
+    "create_version_router",
+]