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

cloud_dog_api_kit/correlation/context.py

@@ -0,0 +1,118 @@
+# 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 context using contextvars
+#
+# Licence: Proprietary — Cloud-Dog AI Platform
+# Owner: Cloud-Dog AI
+# Description: Context-local storage for request ID, correlation ID, app ID,
+#   and host ID. Uses contextvars for async-safe propagation.
+# Related requirements: FR5.1, FR3.2, NF1.3
+# Related architecture: CC1.8
+
+"""Correlation context management using contextvars."""
+
+from __future__ import annotations
+
+import uuid
+from contextvars import ContextVar
+
+_request_id_var: ContextVar[str | None] = ContextVar("request_id", default=None)
+_correlation_id_var: ContextVar[str | None] = ContextVar("correlation_id", default=None)
+_app_id_var: ContextVar[str | None] = ContextVar("app_id", default=None)
+_host_id_var: ContextVar[str | None] = ContextVar("host_id", default=None)
+
+
+def get_request_id() -> str:
+    """Get the current request ID, generating one if not set.
+
+    Returns:
+        The request ID string.
+    """
+    rid = _request_id_var.get()
+    if rid is None:
+        rid = uuid.uuid4().hex
+        _request_id_var.set(rid)
+    return rid
+
+
+def set_request_id(rid: str) -> None:
+    """Set the request ID for the current context.
+
+    Args:
+        rid: The request ID to set.
+    """
+    _request_id_var.set(rid)
+
+
+def get_correlation_id() -> str | None:
+    """Get the cross-service correlation ID, if set.
+
+    Returns:
+        The correlation ID string or None.
+    """
+    return _correlation_id_var.get()
+
+
+def set_correlation_id(cid: str) -> None:
+    """Set the cross-service correlation ID.
+
+    Args:
+        cid: The correlation ID to set.
+    """
+    _correlation_id_var.set(cid)
+
+
+def get_app_id() -> str | None:
+    """Get the calling application ID, if set.
+
+    Returns:
+        The app ID string or None.
+    """
+    return _app_id_var.get()
+
+
+def set_app_id(app_id: str) -> None:
+    """Set the calling application ID.
+
+    Args:
+        app_id: The app ID to set.
+    """
+    _app_id_var.set(app_id)
+
+
+def get_host_id() -> str | None:
+    """Get the host ID, if set.
+
+    Returns:
+        The host ID string or None.
+    """
+    return _host_id_var.get()
+
+
+def set_host_id(host_id: str) -> None:
+    """Set the host ID.
+
+    Args:
+        host_id: The host ID to set.
+    """
+    _host_id_var.set(host_id)
+
+
+def clear_context() -> None:
+    """Clear all correlation context variables."""
+    _request_id_var.set(None)
+    _correlation_id_var.set(None)
+    _app_id_var.set(None)
+    _host_id_var.set(None)

cloud_dog_api_kit/correlation/middleware.py

@@ -0,0 +1,133 @@
+# 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 ASGI middleware
+#
+# Licence: Proprietary — Cloud-Dog AI Platform
+# Owner: Cloud-Dog AI
+# Description: ASGI middleware that extracts X-Request-Id, X-Correlation-Id,
+#   X-App-Id, and X-Host-Id from request headers, stores them in contextvars,
+#   and attaches X-Request-Id to response headers.
+# Related requirements: FR5.1, FR3.2
+# Related architecture: CC1.8
+
+"""Correlation ID ASGI middleware for cloud_dog_api_kit."""
+
+from __future__ import annotations
+
+import logging
+import uuid
+from typing import Callable
+
+from starlette.middleware.base import BaseHTTPMiddleware
+from starlette.requests import Request
+from starlette.responses import JSONResponse, Response
+
+from cloud_dog_api_kit.correlation.context import (
+    clear_context,
+    set_app_id,
+    set_correlation_id,
+    set_host_id,
+    set_request_id,
+)
+
+_logger = logging.getLogger("cloud_dog_api_kit.correlation")
+
+
+class CorrelationMiddleware(BaseHTTPMiddleware):
+    """ASGI middleware for correlation ID extraction and propagation.
+
+    On each request:
+    1. Extracts ``X-Request-Id`` (generates UUID if absent).
+    2. Extracts ``X-Correlation-Id`` if provided, propagates unchanged.
+    3. Extracts ``X-App-Id`` and ``X-Host-Id`` if provided.
+    4. Stores all in contextvars for the duration of the request.
+    5. Attaches ``X-Request-Id`` to response headers.
+    6. Sets ``request.state.request_id`` and ``request.state.correlation_id``.
+
+    Related tests: UT1.11_CorrelationContext, UT1.12_CorrelationMiddleware
+    """
+
+    async def dispatch(self, request: Request, call_next: Callable) -> Response:
+        """Process the request and propagate correlation context.
+
+        Args:
+            request: The incoming HTTP request.
+            call_next: The next middleware or handler.
+
+        Returns:
+            The HTTP response with X-Request-Id header attached.
+        """
+        # Extract or generate request ID
+        request_id = request.headers.get("x-request-id", "").strip()
+        if not request_id:
+            request_id = uuid.uuid4().hex
+        set_request_id(request_id)
+
+        # Extract optional correlation headers
+        correlation_id = request.headers.get("x-correlation-id", "").strip() or None
+        if correlation_id:
+            set_correlation_id(correlation_id)
+
+        app_id = request.headers.get("x-app-id", "").strip() or None
+        if app_id:
+            set_app_id(app_id)
+
+        host_id = request.headers.get("x-host-id", "").strip() or None
+        if host_id:
+            set_host_id(host_id)
+
+        # Store on request.state for downstream handlers
+        request.state.request_id = request_id
+        request.state.correlation_id = correlation_id
+        request.state.app_id = app_id
+        request.state.host_id = host_id
+
+        try:
+            response = await call_next(request)
+            response.headers["X-Request-Id"] = request_id
+            if correlation_id:
+                response.headers["X-Correlation-Id"] = correlation_id
+            return response
+        except Exception as exc:
+            # Catch unhandled exceptions that escape FastAPI's exception handlers
+            # when BaseHTTPMiddleware is in the stack. Return a safe 500 envelope.
+            from cloud_dog_api_kit.errors.exceptions import APIError
+
+            if isinstance(exc, APIError):
+                body = {
+                    "ok": False,
+                    "error": {
+                        "code": exc.code,
+                        "message": exc.message,
+                        "details": exc.details,
+                        "retryable": exc.retryable,
+                    },
+                    "meta": {"request_id": request_id, "correlation_id": correlation_id},
+                }
+                return JSONResponse(status_code=exc.status_code, content=body)
+            _logger.exception("Unhandled exception", extra={"request_id": request_id})
+            body = {
+                "ok": False,
+                "error": {
+                    "code": "INTERNAL_ERROR",
+                    "message": "An internal error occurred",
+                    "details": None,
+                    "retryable": False,
+                },
+                "meta": {"request_id": request_id, "correlation_id": correlation_id},
+            }
+            return JSONResponse(status_code=500, content=body)
+        finally:
+            clear_context()

cloud_dog_api_kit/envelopes/__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 — Response envelopes
+#
+# Licence: Proprietary — Cloud-Dog AI Platform
+# Owner: Cloud-Dog AI
+# Description: Standard success and error response envelopes per PS-20.
+# Related requirements: FR1.1, FR1.2
+# Related architecture: CC1.1
+
+"""Standard response envelopes for cloud_dog_api_kit."""
+
+from __future__ import annotations
+
+from cloud_dog_api_kit.envelopes.error import ErrorDetail, ErrorResponse, error_envelope
+from cloud_dog_api_kit.envelopes.success import Meta, SuccessResponse, success_envelope
+
+__all__ = [
+    "ErrorDetail",
+    "ErrorResponse",
+    "Meta",
+    "SuccessResponse",
+    "success_envelope",
+    "error_envelope",
+]

cloud_dog_api_kit/envelopes/error.py

@@ -0,0 +1,87 @@
+# 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 — Error response envelopes
+#
+# Licence: Proprietary — Cloud-Dog AI Platform
+# Owner: Cloud-Dog AI
+# Description: Standard error envelope models and helpers.
+# Related requirements: FR1.2
+# Related architecture: SA1, CC1.1
+
+"""Error response envelope models for cloud_dog_api_kit."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+from cloud_dog_api_kit.envelopes.success import Meta
+
+
+class ErrorDetail(BaseModel):
+    """Standard error detail within the error envelope.
+
+    Attributes:
+        code: Stable, machine-readable error code from the taxonomy.
+        message: Human-readable summary (no secrets, no stack traces).
+        details: Optional field-level error details.
+        retryable: Whether the client can retry the request.
+
+    Related tests: UT1.2_ErrorEnvelope, UT1.3_ErrorTaxonomy
+    """
+
+    code: str
+    message: str
+    details: dict[str, Any] | None = None
+    retryable: bool = False
+
+
+class ErrorResponse(BaseModel):
+    """Standard error response envelope.
+
+    Related tests: UT1.2_ErrorEnvelope
+    """
+
+    ok: bool = False
+    error: ErrorDetail
+    meta: Meta = Field(default_factory=Meta)
+
+
+def error_envelope(
+    code: str,
+    message: str,
+    details: dict[str, Any] | None = None,
+    retryable: bool = False,
+    request_id: str = "",
+    correlation_id: str | None = None,
+) -> dict[str, Any]:
+    """Build an error response envelope dictionary.
+
+    Related tests: UT1.2_ErrorEnvelope
+    """
+    return {
+        "ok": False,
+        "error": {
+            "code": code,
+            "message": message,
+            "details": details,
+            "retryable": retryable,
+        },
+        "meta": {
+            "request_id": request_id,
+            "correlation_id": correlation_id,
+        },
+    }

cloud_dog_api_kit/envelopes/success.py

@@ -0,0 +1,84 @@
+# 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 — Success response envelopes
+#
+# Licence: Proprietary — Cloud-Dog AI Platform
+# Owner: Cloud-Dog AI
+# Description: Standard success envelope models and helpers.
+# Related requirements: FR1.1
+# Related architecture: SA1, CC1.1
+
+"""Success response envelope models for cloud_dog_api_kit."""
+
+from __future__ import annotations
+
+from typing import Any, Generic, TypeVar
+
+from pydantic import BaseModel, Field
+
+T = TypeVar("T")
+
+
+class Meta(BaseModel):
+    """Response metadata included in every envelope.
+
+    Attributes:
+        request_id: The unique request identifier (correlation ID).
+        correlation_id: Optional cross-service correlation identifier.
+        version: API version string.
+
+    Related tests: UT1.1_SuccessEnvelope
+    """
+
+    request_id: str = ""
+    correlation_id: str | None = None
+    version: str = "v1"
+
+
+class SuccessResponse(BaseModel, Generic[T]):
+    """Standard success response envelope.
+
+    Attributes:
+        ok: Always True for success responses.
+        data: The response payload.
+        meta: Response metadata.
+
+    Related tests: UT1.1_SuccessEnvelope
+    """
+
+    ok: bool = True
+    data: T
+    meta: Meta = Field(default_factory=Meta)
+
+
+def success_envelope(
+    data: Any,
+    request_id: str = "",
+    correlation_id: str | None = None,
+    version: str = "v1",
+) -> dict[str, Any]:
+    """Build a success response envelope dictionary.
+
+    Related tests: UT1.1_SuccessEnvelope
+    """
+    return {
+        "ok": True,
+        "data": data,
+        "meta": {
+            "request_id": request_id,
+            "correlation_id": correlation_id,
+            "version": version,
+        },
+    }

cloud_dog_api_kit/errors/__init__.py

@@ -0,0 +1,51 @@
+# 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 — Error taxonomy and exception hierarchy
+#
+# Licence: Proprietary — Cloud-Dog AI Platform
+# Owner: Cloud-Dog AI
+# Description: Typed exception classes mapping to the PS-20 error taxonomy.
+# Related requirements: FR1.3, FR2.1, FR2.2
+# Related architecture: CC1.3
+
+"""Error taxonomy and exception hierarchy for cloud_dog_api_kit."""
+
+from cloud_dog_api_kit.errors.exceptions import (
+    APIError,
+    ConflictError,
+    InternalError,
+    NotFoundError,
+    RateLimitError,
+    TimeoutError,
+    UnauthenticatedError,
+    UnauthorisedError,
+    UpstreamError,
+    ValidationError,
+)
+from cloud_dog_api_kit.errors.handler import register_error_handlers
+
+__all__ = [
+    "APIError",
+    "ConflictError",
+    "InternalError",
+    "NotFoundError",
+    "RateLimitError",
+    "TimeoutError",
+    "UnauthenticatedError",
+    "UnauthorisedError",
+    "UpstreamError",
+    "ValidationError",
+    "register_error_handlers",
+]

cloud_dog_api_kit/errors/exceptions.py

@@ -0,0 +1,184 @@
+# 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 — Typed exception classes
+#
+# Licence: Proprietary — Cloud-Dog AI Platform
+# Owner: Cloud-Dog AI
+# Description: Exception hierarchy mapping to the PS-20 error taxonomy.
+#   Each exception carries code, message, retryable, and optional details.
+# Related requirements: FR2.1
+# Related architecture: CC1.3
+
+"""Typed exception classes for the PS-20 error taxonomy."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+class APIError(Exception):
+    """Base exception for all API errors.
+
+    Attributes:
+        status_code: HTTP status code.
+        code: Machine-readable error code from the taxonomy.
+        message: Human-readable error message.
+        retryable: Whether the client can retry.
+        details: Optional field-level error details.
+
+    Related tests: UT1.4_ErrorExceptions
+    """
+
+    status_code: int = 500
+    code: str = "INTERNAL_ERROR"
+    retryable: bool = False
+
+    def __init__(
+        self,
+        message: str = "An internal error occurred",
+        details: dict[str, Any] | None = None,
+        retryable: bool | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.details = details
+        if retryable is not None:
+            self.retryable = retryable
+
+
+class UnauthenticatedError(APIError):
+    """Missing or invalid credentials (401).
+
+    Related tests: UT1.4_ErrorExceptions
+    """
+
+    status_code = 401
+    code = "UNAUTHENTICATED"
+    retryable = False
+
+    def __init__(self, message: str = "Missing or invalid credentials", **kwargs: Any) -> None:
+        super().__init__(message=message, **kwargs)
+
+
+class UnauthorisedError(APIError):
+    """Insufficient permissions (403).
+
+    Related tests: UT1.4_ErrorExceptions
+    """
+
+    status_code = 403
+    code = "UNAUTHORISED"
+    retryable = False
+
+    def __init__(self, message: str = "Insufficient permissions", **kwargs: Any) -> None:
+        super().__init__(message=message, **kwargs)
+
+
+class NotFoundError(APIError):
+    """Resource does not exist (404).
+
+    Related tests: UT1.4_ErrorExceptions
+    """
+
+    status_code = 404
+    code = "NOT_FOUND"
+    retryable = False
+
+    def __init__(self, message: str = "Resource not found", **kwargs: Any) -> None:
+        super().__init__(message=message, **kwargs)
+
+
+class ConflictError(APIError):
+    """Resource state conflict (409).
+
+    Related tests: UT1.4_ErrorExceptions
+    """
+
+    status_code = 409
+    code = "CONFLICT"
+    retryable = False
+
+    def __init__(self, message: str = "Resource state conflict", **kwargs: Any) -> None:
+        super().__init__(message=message, **kwargs)
+
+
+class ValidationError(APIError):
+    """Validation failure (422).
+
+    Related tests: UT1.4_ErrorExceptions
+    """
+
+    status_code = 422
+    code = "INVALID_REQUEST"
+    retryable = False
+
+    def __init__(self, message: str = "Validation failure", **kwargs: Any) -> None:
+        super().__init__(message=message, **kwargs)
+
+
+class RateLimitError(APIError):
+    """Too many requests (429).
+
+    Related tests: UT1.4_ErrorExceptions
+    """
+
+    status_code = 429
+    code = "RATE_LIMITED"
+    retryable = True
+
+    def __init__(self, message: str = "Too many requests", **kwargs: Any) -> None:
+        super().__init__(message=message, **kwargs)
+
+
+class TimeoutError(APIError):
+    """Operation timed out (504).
+
+    Related tests: UT1.4_ErrorExceptions
+    """
+
+    status_code = 504
+    code = "TIMEOUT"
+    retryable = True
+
+    def __init__(self, message: str = "Operation timed out", **kwargs: Any) -> None:
+        super().__init__(message=message, **kwargs)
+
+
+class UpstreamError(APIError):
+    """Downstream service failure (502).
+
+    Related tests: UT1.4_ErrorExceptions
+    """
+
+    status_code = 502
+    code = "UPSTREAM_ERROR"
+    retryable = True
+
+    def __init__(self, message: str = "Downstream service failure", **kwargs: Any) -> None:
+        super().__init__(message=message, **kwargs)
+
+
+class InternalError(APIError):
+    """Unhandled server error (500).
+
+    Related tests: UT1.4_ErrorExceptions
+    """
+
+    status_code = 500
+    code = "INTERNAL_ERROR"
+    retryable = False
+
+    def __init__(self, message: str = "An internal error occurred", **kwargs: Any) -> None:
+        super().__init__(message=message, **kwargs)