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

cloud_dog_api_kit/clients/http_client.py

@@ -0,0 +1,127 @@
+# 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 — Configured HTTP client with retry and timeouts
+#
+# Licence: Proprietary — Cloud-Dog AI Platform
+# Owner: Cloud-Dog AI
+# Description: Standard HTTP client module for service-to-service calls with
+#   configurable timeouts, retry policy with exponential backoff + jitter,
+#   and automatic header propagation (X-Request-Id, X-App-Id, API key).
+# Related requirements: FR9.1, FR9.2
+# Related architecture: CC1.15
+
+"""Configured HTTP client for service-to-service calls."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import httpx
+
+from cloud_dog_api_kit.correlation.context import get_request_id, get_app_id
+from cloud_dog_api_kit.clients.retry import RetryPolicy, RetryTransport
+
+
+@dataclass
+class ClientTimeout:
+    """HTTP client timeout configuration.
+
+    Attributes:
+        connect: Connection timeout in seconds.
+        read: Read timeout in seconds.
+        total: Total request timeout in seconds.
+
+    Related tests: UT1.23_HTTPClient
+    """
+
+    connect: float = 5.0
+    read: float = 30.0
+    total: float = 60.0
+
+
+def create_http_client(
+    base_url: str | None = None,
+    timeout: ClientTimeout | None = None,
+    retry_policy: RetryPolicy | None = None,
+    app_id: str | None = None,
+    api_key: str | None = None,
+) -> httpx.AsyncClient:
+    """Create a configured async HTTP client for service-to-service calls.
+
+    The client automatically propagates X-Request-Id and X-App-Id headers
+    and attaches an API key if provided.
+
+    Args:
+        base_url: Base URL for all requests.
+        timeout: Timeout configuration. Uses defaults if None.
+        retry_policy: Retry policy. Uses defaults if None.
+        app_id: Calling service application ID.
+        api_key: API key for authentication.
+
+    Returns:
+        A configured httpx.AsyncClient.
+
+    Related tests: UT1.23_HTTPClient, ST1.11_HTTPClientEndToEnd
+    """
+    ct = timeout or ClientTimeout()
+    policy = retry_policy or RetryPolicy()
+
+    httpx_timeout = httpx.Timeout(
+        timeout=ct.total,
+        connect=ct.connect,
+        read=ct.read,
+        pool=ct.total,
+    )
+
+    headers: dict[str, str] = {}
+    if app_id:
+        headers["X-App-Id"] = app_id
+    if api_key:
+        headers["X-API-Key"] = api_key
+
+    return httpx.AsyncClient(
+        base_url=base_url or "",
+        timeout=httpx_timeout,
+        headers=headers,
+        transport=RetryTransport(policy=policy, transport=httpx.AsyncHTTPTransport()),
+        event_hooks={
+            "request": [_inject_correlation_headers],
+        },
+    )
+
+
+async def _inject_correlation_headers(request: httpx.Request) -> None:
+    """Event hook to inject correlation headers into outgoing requests.
+
+    Args:
+        request: The outgoing HTTP request.
+    """
+    try:
+        request_id = get_request_id()
+        request.headers["X-Request-Id"] = request_id
+    except Exception:
+        pass
+
+    try:
+        app_id = get_app_id()
+        if app_id:
+            request.headers["X-App-Id"] = app_id
+    except Exception:
+        pass
+
+
+def create_retry_transport(policy: RetryPolicy, transport: httpx.AsyncBaseTransport) -> RetryTransport:
+    """Create a retry transport wrapper for httpx."""
+    return RetryTransport(policy=policy, transport=transport)

cloud_dog_api_kit/clients/retry.py

@@ -0,0 +1,83 @@
+# 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 — Retry policy
+#
+# Licence: Proprietary — Cloud-Dog AI Platform
+# Owner: Cloud-Dog AI
+# Description: Retry policy with exponential backoff + jitter for HTTP clients.
+# Related requirements: FR9.2
+# Related architecture: SA1
+
+"""Retry policy utilities for cloud_dog_api_kit."""
+
+from __future__ import annotations
+
+import asyncio
+import random
+from dataclasses import dataclass
+
+import httpx
+
+
+@dataclass
+class RetryPolicy:
+    """Retry policy for idempotent operations.
+
+    Related tests: UT1.24_RetryPolicy
+    """
+
+    max_retries: int = 3
+    backoff_base: float = 0.5
+    backoff_max: float = 30.0
+    jitter: bool = True
+    retry_status_codes: tuple[int, ...] = (502, 503, 504)
+
+    def get_delay(self, attempt: int) -> float:
+        """Return delay."""
+        delay = min(self.backoff_base * (2**attempt), self.backoff_max)
+        if self.jitter:
+            delay = delay * (0.5 + random.random() * 0.5)
+        return delay
+
+
+class RetryTransport(httpx.AsyncBaseTransport):
+    """HTTP transport wrapper with retry logic."""
+
+    def __init__(self, policy: RetryPolicy, transport: httpx.AsyncBaseTransport) -> None:
+        self._policy = policy
+        self._transport = transport
+
+    async def handle_async_request(self, request: httpx.Request) -> httpx.Response:
+        """Handle handle async request."""
+        last_response: httpx.Response | None = None
+        last_exc: Exception | None = None
+
+        for attempt in range(self._policy.max_retries + 1):
+            try:
+                response = await self._transport.handle_async_request(request)
+                if response.status_code not in self._policy.retry_status_codes:
+                    return response
+                last_response = response
+            except (httpx.ConnectError, httpx.ReadTimeout) as exc:
+                last_exc = exc
+
+            if attempt < self._policy.max_retries:
+                await asyncio.sleep(self._policy.get_delay(attempt))
+
+        if last_response is not None:
+            return last_response
+        if last_exc is not None:
+            raise last_exc
+        raise httpx.ConnectError("All retry attempts exhausted")

cloud_dog_api_kit/compat/__init__.py

@@ -0,0 +1,37 @@
+# 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 — Compatibility and migration exports
+#
+# Licence: Proprietary — Cloud-Dog AI Platform
+# Owner: Cloud-Dog AI
+# Description: Migration compatibility middleware exports.
+# Related requirements: FR18.3, FR18.4, FR18.6
+# Related architecture: SA1
+
+"""Compatibility middleware exports."""
+
+from __future__ import annotations
+
+from cloud_dog_api_kit.compat.envelope import LegacyEnvelopeMiddleware, legacy_envelope_route
+from cloud_dog_api_kit.compat.profile import ProfileContextMiddleware
+from cloud_dog_api_kit.compat.routes import LegacyRouteAdapter, LegacyRouteAdapterMiddleware
+
+__all__ = [
+    "LegacyEnvelopeMiddleware",
+    "LegacyRouteAdapter",
+    "LegacyRouteAdapterMiddleware",
+    "ProfileContextMiddleware",
+    "legacy_envelope_route",
+]

cloud_dog_api_kit/compat/envelope.py

@@ -0,0 +1,120 @@
+# 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 — Legacy envelope compatibility middleware
+#
+# Licence: Proprietary — Cloud-Dog AI Platform
+# Owner: Cloud-Dog AI
+# Description: Middleware to wrap legacy non-enveloped responses into standard
+#   success/error envelopes during phased migrations.
+# Related requirements: FR18.3
+# Related architecture: SA1
+
+"""Legacy response envelope compatibility middleware."""
+
+from __future__ import annotations
+
+import json
+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 import error_envelope, success_envelope
+
+
+def legacy_envelope_route(func: Callable) -> Callable:
+    """Mark a route endpoint as legacy-envelope compatible."""
+    setattr(func, "__legacy_envelope__", True)
+    return func
+
+
+class LegacyEnvelopeMiddleware(BaseHTTPMiddleware):
+    """Wrap legacy responses in standard envelopes for opt-in routes.
+
+    Args:
+        app: ASGI app.
+        opt_in_paths: Exact route paths that require envelope wrapping.
+        opt_in_header: Optional request header to force legacy envelope mode.
+    """
+
+    def __init__(
+        self,
+        app: Any,
+        *,
+        opt_in_paths: set[str] | None = None,
+        opt_in_header: str = "X-Legacy-Envelope",
+    ) -> None:
+        super().__init__(app)
+        self._opt_in_paths = set(opt_in_paths or set())
+        self._opt_in_header = opt_in_header.lower()
+
+    async def dispatch(self, request: Request, call_next: Callable) -> Response:
+        """Apply compatibility envelopes on opt-in routes."""
+        response = await call_next(request)
+        if not self._should_wrap(request):
+            return response
+        if response.status_code == 204:
+            return response
+
+        body_bytes = b""
+        async for chunk in response.body_iterator:
+            body_bytes += chunk
+
+        payload: Any
+        if body_bytes:
+            try:
+                payload = json.loads(body_bytes)
+            except json.JSONDecodeError:
+                payload = {"message": body_bytes.decode("utf-8", errors="replace")}
+        else:
+            payload = {}
+
+        request_id = getattr(request.state, "request_id", "")
+        correlation_id = getattr(request.state, "correlation_id", None)
+
+        if isinstance(payload, dict) and "ok" in payload and ("data" in payload or "error" in payload):
+            envelope = payload
+        elif response.status_code >= 400:
+            message = "Request failed"
+            details = None
+            if isinstance(payload, dict):
+                message = str(payload.get("message", payload.get("error", message)))
+                details = payload.get("details")
+            envelope = error_envelope(
+                code="INVALID_REQUEST" if response.status_code < 500 else "INTERNAL_ERROR",
+                message=message,
+                details=details,
+                request_id=request_id,
+                correlation_id=correlation_id,
+            )
+        else:
+            envelope = success_envelope(
+                data=payload,
+                request_id=request_id,
+                correlation_id=correlation_id,
+            )
+
+        headers = {k: v for k, v in response.headers.items() if k.lower() != "content-length"}
+        return JSONResponse(status_code=response.status_code, content=envelope, headers=headers)
+
+    def _should_wrap(self, request: Request) -> bool:
+        """Determine whether current request should be wrapped."""
+        endpoint = request.scope.get("endpoint")
+        if endpoint is not None and bool(getattr(endpoint, "__legacy_envelope__", False)):
+            return True
+        if request.url.path in self._opt_in_paths:
+            return True
+        return request.headers.get(self._opt_in_header, "").strip().lower() in {"1", "true", "yes"}

cloud_dog_api_kit/compat/profile.py

@@ -0,0 +1,102 @@
+# 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 — Profile context middleware
+#
+# Licence: Proprietary — Cloud-Dog AI Platform
+# Owner: Cloud-Dog AI
+# Description: Middleware that resolves request profile context from headers,
+#   path patterns, or query parameters and stores it in request.state.
+# Related requirements: FR18.6
+# Related architecture: SA1
+
+"""Profile context resolution middleware."""
+
+from __future__ import annotations
+
+import re
+from typing import Any, Callable, Pattern
+
+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
+
+DEFAULT_PATH_PATTERNS = (
+    re.compile(r"/profiles/(?P<profile>[A-Za-z0-9._-]+)"),
+    re.compile(r"/profile/(?P<profile>[A-Za-z0-9._-]+)"),
+)
+
+
+class ProfileContextMiddleware(BaseHTTPMiddleware):
+    """Resolve per-request profile context.
+
+    Resolution order:
+    1. Header (default: `X-Profile`)
+    2. Path pattern match
+    3. Query parameter (default: `profile`)
+    4. Default profile
+    """
+
+    def __init__(
+        self,
+        app: Any,
+        *,
+        header_name: str = "X-Profile",
+        query_param: str = "profile",
+        default_profile: str | None = None,
+        allowed_profiles: set[str] | None = None,
+        path_patterns: tuple[Pattern[str], ...] | None = None,
+    ) -> None:
+        super().__init__(app)
+        self._header_name = header_name
+        self._query_param = query_param
+        self._default_profile = default_profile
+        self._allowed_profiles = allowed_profiles
+        self._path_patterns = path_patterns or DEFAULT_PATH_PATTERNS
+
+    async def dispatch(self, request: Request, call_next: Callable) -> Response:
+        """Resolve profile context and validate allowed profile list."""
+        profile = (
+            request.headers.get(self._header_name)
+            or self._profile_from_path(request.url.path)
+            or request.query_params.get(self._query_param)
+            or self._default_profile
+        )
+
+        if self._allowed_profiles is not None and profile and profile not in self._allowed_profiles:
+            request_id = getattr(request.state, "request_id", "")
+            correlation_id = getattr(request.state, "correlation_id", None)
+            return JSONResponse(
+                status_code=400,
+                content=error_envelope(
+                    code="INVALID_REQUEST",
+                    message="Invalid profile",
+                    details={"profile": profile},
+                    request_id=request_id,
+                    correlation_id=correlation_id,
+                ),
+            )
+
+        request.state.profile = profile
+        return await call_next(request)
+
+    def _profile_from_path(self, path: str) -> str | None:
+        """Extract profile identifier from known path patterns."""
+        for pattern in self._path_patterns:
+            match = pattern.search(path)
+            if match:
+                return match.group("profile")
+        return None

cloud_dog_api_kit/compat/routes.py

@@ -0,0 +1,90 @@
+# 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 — Legacy route migration adapter
+#
+# Licence: Proprietary — Cloud-Dog AI Platform
+# Owner: Cloud-Dog AI
+# Description: Route migration adapter that maps legacy non-versioned paths to
+#   versioned API paths and adds deprecation headers.
+# Related requirements: FR18.4
+# Related architecture: SA1
+
+"""Legacy route migration helpers."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Callable
+
+from fastapi import FastAPI
+from starlette.middleware.base import BaseHTTPMiddleware
+from starlette.requests import Request
+from starlette.responses import RedirectResponse, Response
+
+
+@dataclass(slots=True)
+class LegacyRouteAdapter:
+    """Adapter mapping legacy routes to versioned paths."""
+
+    route_map: dict[str, str]
+    sunset: str | None = None
+    link: str | None = None
+    redirect: bool = False
+    deprecation: str = "true"
+    methods: set[str] = field(default_factory=lambda: {"GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS"})
+
+    def resolve(self, path: str) -> str | None:
+        """Resolve a legacy path to a versioned path."""
+        return self.route_map.get(path)
+
+    def deprecation_headers(self) -> dict[str, str]:
+        """Build response headers for legacy route responses."""
+        headers = {"Deprecation": self.deprecation}
+        if self.sunset:
+            headers["Sunset"] = self.sunset
+        if self.link:
+            headers["Link"] = self.link
+        return headers
+
+    def register(self, app: FastAPI) -> None:
+        """Register legacy route adapter middleware on an app."""
+        app.add_middleware(LegacyRouteAdapterMiddleware, adapter=self)
+
+
+class LegacyRouteAdapterMiddleware(BaseHTTPMiddleware):
+    """Middleware implementing legacy route mapping and deprecation headers."""
+
+    def __init__(self, app: Any, adapter: LegacyRouteAdapter) -> None:
+        super().__init__(app)
+        self._adapter = adapter
+
+    async def dispatch(self, request: Request, call_next: Callable) -> Response:
+        """Map legacy route to versioned path and add deprecation headers."""
+        target_path = self._adapter.resolve(request.url.path)
+        if target_path is None or request.method.upper() not in self._adapter.methods:
+            return await call_next(request)
+
+        headers = self._adapter.deprecation_headers()
+        if self._adapter.redirect:
+            query = request.url.query
+            location = target_path if not query else f"{target_path}?{query}"
+            return RedirectResponse(url=location, status_code=307, headers=headers)
+
+        request.scope["path"] = target_path
+        request.scope["raw_path"] = target_path.encode("utf-8")
+        response = await call_next(request)
+        for name, value in headers.items():
+            response.headers[name] = value
+        return response

cloud_dog_api_kit/config.py

@@ -0,0 +1,54 @@
+# 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 — Configuration model
+#
+# Licence: Proprietary — Cloud-Dog AI Platform
+# Owner: Cloud-Dog AI
+# Description: Settings model for wiring cloud_dog_api_kit in a service. This
+#   module intentionally keeps configuration minimal and provider-agnostic.
+# Related requirements: FR10.3, FR11.1, FR13.1
+# Related architecture: SA1
+
+"""Configuration model for cloud_dog_api_kit."""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, Field
+
+
+class APIKitSettings(BaseModel):
+    """Settings for cloud_dog_api_kit.
+
+    These settings can be sourced from `cloud_dog_config` when available, but
+    are also usable standalone (e.g. local tests).
+    """
+
+    api_prefix: str = Field(default="/api/v1", description="API prefix for versioned routes")
+    api_version: str = Field(default="v1", description="API version string for headers and metadata")
+    enable_docs: bool = Field(default=True, description="Whether to enable /docs and /redoc")
+    enable_request_logging: bool = Field(default=True, description="Whether to enable request logging middleware")
+    enable_cors: bool = Field(default=True, description="Whether to enable CORS middleware")
+    cors_origins: list[str] = Field(default_factory=list, description="Allowed CORS origins")
+    timeout_seconds: float = Field(default=30.0, ge=0.1, description="Request timeout in seconds")
+    max_request_body_bytes: int | None = Field(
+        default=None,
+        ge=1,
+        description="Maximum request body size in bytes; None disables size checks",
+    )
+    shutdown_drain_timeout_seconds: float = Field(
+        default=5.0,
+        ge=0.0,
+        description="Graceful shutdown request-drain timeout in seconds",
+    )

cloud_dog_api_kit/correlation/__init__.py

@@ -0,0 +1,50 @@
+# 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 — Correlation ID context and middleware
+#
+# Licence: Proprietary — Cloud-Dog AI Platform
+# Owner: Cloud-Dog AI
+# Description: Context-local correlation ID, app ID, and host ID management
+#   with ASGI middleware for automatic extraction/propagation.
+# Related requirements: FR5.1, FR3.2
+# Related architecture: CC1.8
+
+"""Correlation ID context and middleware for cloud_dog_api_kit."""
+
+from cloud_dog_api_kit.correlation.context import (
+    get_app_id,
+    get_correlation_id,
+    get_host_id,
+    get_request_id,
+    set_app_id,
+    set_correlation_id,
+    set_host_id,
+    set_request_id,
+    clear_context,
+)
+from cloud_dog_api_kit.correlation.middleware import CorrelationMiddleware
+
+__all__ = [
+    "get_app_id",
+    "get_correlation_id",
+    "get_host_id",
+    "get_request_id",
+    "set_app_id",
+    "set_correlation_id",
+    "set_host_id",
+    "set_request_id",
+    "clear_context",
+    "CorrelationMiddleware",
+]