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

cloud_dog_api_kit/testing/flows/__init__.py

@@ -0,0 +1,32 @@
+# 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 — Test flow templates
+#
+# Licence: Proprietary — Cloud-Dog AI Platform
+# Owner: Cloud-Dog AI
+# Description: Reusable test flow templates for auth, CRUD, jobs, and streaming.
+# Related requirements: FR17.1
+# Related architecture: SA1
+
+"""Reusable flow templates for cloud_dog_api_kit testing."""
+
+from __future__ import annotations
+
+from cloud_dog_api_kit.testing.flows.auth_flow import AuthFlow
+from cloud_dog_api_kit.testing.flows.crud_flow import CRUDFlow
+from cloud_dog_api_kit.testing.flows.job_flow import JobFlow
+from cloud_dog_api_kit.testing.flows.streaming_flow import StreamingFlow
+
+__all__ = ["AuthFlow", "CRUDFlow", "JobFlow", "StreamingFlow"]

cloud_dog_api_kit/testing/flows/auth_flow.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 — Auth flow template
+#
+# Licence: Proprietary — Cloud-Dog AI Platform
+# Owner: Cloud-Dog AI
+# Description: Reusable auth flow checks for services using cloud_dog_api_kit.
+# Related requirements: FR3.1, FR3.4
+# Related architecture: SA1
+
+"""Auth flow template for tests."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import httpx
+
+
+@dataclass(frozen=True, slots=True)
+class AuthFlow:
+    """Reusable auth flow assertions."""
+
+    protected_path: str
+
+    async def assert_unauthenticated(self, client: httpx.AsyncClient) -> None:
+        """Handle assert unauthenticated."""
+        r = await client.get(self.protected_path)
+        assert r.status_code == 401

cloud_dog_api_kit/testing/flows/crud_flow.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 — CRUD flow template
+#
+# Licence: Proprietary — Cloud-Dog AI Platform
+# Owner: Cloud-Dog AI
+# Description: Reusable CRUD flow checks for services using cloud_dog_api_kit.
+# Related requirements: FR4.2
+# Related architecture: SA1
+
+"""CRUD flow template for tests."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import httpx
+
+
+@dataclass(frozen=True, slots=True)
+class CRUDFlow:
+    """Reusable CRUD flow assertions.
+
+    This template is intentionally minimal; services can extend it for resource-specific behaviour.
+    """
+
+    collection_path: str
+
+    async def create_and_get(self, client: httpx.AsyncClient, payload: dict) -> dict:
+        """Create and get."""
+        created = await client.post(self.collection_path, json=payload)
+        created.raise_for_status()
+        created_data = created.json()["data"]
+        resource_id = created_data["id"]
+
+        fetched = await client.get(f"{self.collection_path}/{resource_id}")
+        fetched.raise_for_status()
+        return fetched.json()["data"]

cloud_dog_api_kit/testing/flows/job_flow.py

@@ -0,0 +1,42 @@
+# 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 — Job flow template
+#
+# Licence: Proprietary — Cloud-Dog AI Platform
+# Owner: Cloud-Dog AI
+# Description: Reusable job submission flow checks.
+# Related requirements: FR7.1
+# Related architecture: SA1
+
+"""Job flow template for tests."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import httpx
+
+
+@dataclass(frozen=True, slots=True)
+class JobFlow:
+    """Reusable job submission assertions."""
+
+    submit_path: str
+
+    async def submit(self, client: httpx.AsyncClient, payload: dict) -> str:
+        """Handle submit."""
+        r = await client.post(self.submit_path, json=payload)
+        r.raise_for_status()
+        return r.json()["data"]["job_id"]

cloud_dog_api_kit/testing/flows/streaming_flow.py

@@ -0,0 +1,42 @@
+# 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 — Streaming flow template
+#
+# Licence: Proprietary — Cloud-Dog AI Platform
+# Owner: Cloud-Dog AI
+# Description: Reusable streaming flow checks for SSE/JSONL endpoints.
+# Related requirements: FR8.1
+# Related architecture: SA1
+
+"""Streaming flow template for tests."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import httpx
+
+
+@dataclass(frozen=True, slots=True)
+class StreamingFlow:
+    """Reusable streaming flow assertions."""
+
+    path: str
+
+    async def fetch_stream(self, client: httpx.AsyncClient) -> str:
+        """Handle fetch stream."""
+        r = await client.get(self.path)
+        r.raise_for_status()
+        return r.text

cloud_dog_api_kit/traceability_ids.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.
+
+"""Requirement traceability annotations for implemented cloud_dog_api_kit behaviors."""
+
+# Implements: CS1.1, CS1.2, CS1.3, CS1.4, CS1.5, CS1.6, CS1.7
+# Implements: FR1.1, FR1.2, FR1.3, FR2.1, FR2.2, FR3.1, FR3.2, FR3.3, FR3.4, FR3.5
+# Implements: FR4.1, FR4.2, FR4.3, FR4.4, FR5.1, FR6.1, FR7.1, FR8.1, FR8.2, FR8.3
+# Implements: FR9.1, FR9.2, FR10.1, FR10.2, FR10.3, FR10.4, FR11.1, FR12.1, FR12.2
+# Implements: FR13.1, FR13.2, FR14.1, FR15.1, FR16.1, FR16.2, FR16.3, FR17.1, FR18.1
+# Implements: FR18.2, FR18.3, FR18.4, FR18.5, FR18.6, FR18.7, FR18.8, FR18.9
+# Implements: NF1.1, NF1.2, NF1.3, NF1.4, NF1.5
+
+TRACEABILITY_IDS = (
+    "CS1.1",
+    "CS1.2",
+    "CS1.3",
+    "CS1.4",
+    "CS1.5",
+    "CS1.6",
+    "CS1.7",
+    "FR1.1",
+    "FR1.2",
+    "FR1.3",
+    "FR2.1",
+    "FR2.2",
+    "FR3.1",
+    "FR3.2",
+    "FR3.3",
+    "FR3.4",
+    "FR3.5",
+    "FR4.1",
+    "FR4.2",
+    "FR4.3",
+    "FR4.4",
+    "FR5.1",
+    "FR6.1",
+    "FR7.1",
+    "FR8.1",
+    "FR8.2",
+    "FR8.3",
+    "FR9.1",
+    "FR9.2",
+    "FR10.1",
+    "FR10.2",
+    "FR10.3",
+    "FR10.4",
+    "FR11.1",
+    "FR12.1",
+    "FR12.2",
+    "FR13.1",
+    "FR13.2",
+    "FR14.1",
+    "FR15.1",
+    "FR16.1",
+    "FR16.2",
+    "FR16.3",
+    "FR17.1",
+    "FR18.1",
+    "FR18.2",
+    "FR18.3",
+    "FR18.4",
+    "FR18.5",
+    "FR18.6",
+    "FR18.7",
+    "FR18.8",
+    "FR18.9",
+    "NF1.1",
+    "NF1.2",
+    "NF1.3",
+    "NF1.4",
+    "NF1.5",
+)

cloud_dog_api_kit/versioning/__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 — Versioning helpers
+#
+# Licence: Proprietary — Cloud-Dog AI Platform
+# Owner: Cloud-Dog AI
+# Description: API versioning helpers, including X-API-Version response header
+#   middleware.
+# Related requirements: FR10.4
+# Related architecture: SA1, CC1.17
+
+"""Versioning helpers for cloud_dog_api_kit."""
+
+from __future__ import annotations
+
+from cloud_dog_api_kit.versioning.header import VersionHeaderMiddleware
+
+__all__ = ["VersionHeaderMiddleware"]

cloud_dog_api_kit/versioning/header.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 — X-API-Version header middleware
+#
+# Licence: Proprietary — Cloud-Dog AI Platform
+# Owner: Cloud-Dog AI
+# Description: Adds an `X-API-Version` header to all responses.
+# Related requirements: FR10.4
+# Related architecture: SA1
+
+"""API version header middleware."""
+
+from __future__ import annotations
+
+from typing import Any, Callable
+
+from starlette.middleware.base import BaseHTTPMiddleware
+from starlette.requests import Request
+from starlette.responses import Response
+
+
+class VersionHeaderMiddleware(BaseHTTPMiddleware):
+    """Middleware that adds X-API-Version header to all responses.
+
+    Args:
+        app: The ASGI application.
+        version: The API version string. Defaults to ``v1``.
+
+    Related tests: UT1.30_VersionHeader
+    """
+
+    def __init__(self, app: Any, version: str = "v1") -> None:
+        super().__init__(app)
+        self._version = version
+
+    async def dispatch(self, request: Request, call_next: Callable) -> Response:
+        """Add X-API-Version header to the response."""
+        response = await call_next(request)
+        response.headers["X-API-Version"] = self._version
+        return response

cloud_dog_api_kit/web/__init__.py

@@ -0,0 +1,7 @@
+# Copyright 2026 Cloud-Dog, Viewdeck Engineering Limited
+# Licensed under the Apache License, Version 2.0
+"""Web server utilities for cloud_dog_api_kit."""
+
+from .proxy import WebApiProxy
+
+__all__ = ["WebApiProxy"]

cloud_dog_api_kit/web/proxy.py

@@ -0,0 +1,222 @@
+# 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.
+
+"""
+WebApiProxy — Standard web→API proxy for Cloud-Dog services.
+
+Licence: Apache 2.0
+Ownership: Cloud-Dog, Viewdeck Engineering Limited
+Description: Shared proxy class that all web servers use to forward
+    requests to their API server. Replaces 9 bespoke implementations.
+Related Requirements: FR9.1, FR9.2
+Related Architecture: CC1.15
+Related Tests: UT1.XX_WebApiProxy
+
+Recent Changes (max 10):
+- 2026-04-08: W28A-849 — Initial implementation.
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass, field
+from typing import Any, Mapping
+
+import httpx
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class ProxyResponse:
+    """Structured response from the proxy."""
+
+    status_code: int
+    data: Any = None
+    error: str | None = None
+    headers: dict[str, str] = field(default_factory=dict)
+
+    @property
+    def ok(self) -> bool:
+        """True when status_code is in the 2xx–3xx range."""
+        return 200 <= self.status_code < 400
+
+
+class WebApiProxy:
+    """Standard web→API proxy backed by httpx.
+
+    Provides async methods (``get()``, ``post()``, etc.) and sync methods
+    (``get_sync()``, ``post_sync()``, etc.) that auto-inject the API key
+    and return structured ``ProxyResponse`` objects.
+
+    Async usage::
+
+        proxy = WebApiProxy(api_base_url="http://localhost:8083", api_key="abc")
+        result = await proxy.get("/health")
+
+    Sync usage (for mixed sync/async web servers)::
+
+        result = proxy.get_sync("/health")
+
+    From cloud_dog_config::
+
+        proxy = WebApiProxy.from_config(config)
+    """
+
+    def __init__(
+        self,
+        api_base_url: str,
+        api_key: str = "",
+        api_key_header: str = "X-API-Key",
+        verify_tls: bool = True,
+        timeout: float = 60.0,
+    ) -> None:
+        self._base_url = api_base_url.rstrip("/")
+        self._api_key = api_key
+        self._api_key_header = api_key_header
+        self._verify_tls = verify_tls
+        self._timeout = timeout
+
+    @classmethod
+    def from_config(cls, config: Any) -> "WebApiProxy":
+        """Create a proxy from a cloud_dog_config Config object.
+
+        Reads:
+            - ``web_server.api_base_url`` or ``api_server.base_url``
+            - ``api_server.api_key`` or ``auth.admin_token``
+            - ``api_server.api_key_header`` (default ``X-API-Key``)
+            - ``web_server.verify_tls`` (default True)
+            - ``web_server.proxy_timeout`` (default 60.0)
+        """
+        get = getattr(config, "get", lambda k, d=None: d)
+        api_base_url = str(
+            get("web_server.api_base_url")
+            or get("api_server.base_url")
+            or "http://localhost:8083"
+        )
+        api_key = str(get("api_server.api_key") or get("auth.admin_token") or "")
+        api_key_header = str(get("api_server.api_key_header") or "X-API-Key")
+        verify_tls = bool(get("web_server.verify_tls") if get("web_server.verify_tls") is not None else True)
+        timeout = float(get("web_server.proxy_timeout") or 60.0)
+        return cls(
+            api_base_url=api_base_url,
+            api_key=api_key,
+            api_key_header=api_key_header,
+            verify_tls=verify_tls,
+            timeout=timeout,
+        )
+
+    def _build_headers(
+        self, extra_headers: Mapping[str, str] | None = None
+    ) -> dict[str, str]:
+        """Build request headers with API key and optional extras.
+
+        Caller-supplied headers take precedence on case-insensitive name match,
+        so a forwarded X-API-Key from an authenticated user overrides the proxy's
+        service key (preserves caller identity for downstream RBAC).
+        """
+        headers: dict[str, str] = {}
+        if self._api_key:
+            headers[self._api_key_header] = self._api_key
+        if extra_headers:
+            for incoming_key, incoming_value in extra_headers.items():
+                normalised = incoming_key.lower()
+                for existing in [k for k in headers if k.lower() == normalised]:
+                    del headers[existing]
+                headers[incoming_key] = incoming_value
+        return headers
+
+    async def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: Any = None,
+        params: dict[str, Any] | None = None,
+        headers: Mapping[str, str] | None = None,
+        cookies: dict[str, str] | None = None,
+    ) -> ProxyResponse:
+        """Send a proxied request to the API server.
+
+        Args:
+            method: HTTP method (GET, POST, PUT, DELETE, PATCH).
+            path: API path (e.g. ``/users/123``).
+            json: JSON body for POST/PUT/PATCH.
+            params: Query parameters.
+            headers: Additional headers to forward.
+            cookies: Cookies to forward (for session-based auth proxying).
+
+        Returns:
+            ProxyResponse with status_code, data, and optional error.
+        """
+        url = f"{self._base_url}{path}"
+        merged_headers = self._build_headers(headers)
+        try:
+            async with httpx.AsyncClient(
+                verify=self._verify_tls,
+                timeout=httpx.Timeout(self._timeout),
+                cookies=cookies,
+            ) as client:
+                response = await client.request(
+                    method=method,
+                    url=url,
+                    json=json,
+                    params=params,
+                    headers=merged_headers,
+                )
+            try:
+                data = response.json()
+            except Exception:
+                data = response.text
+            if response.status_code >= 400:
+                return ProxyResponse(
+                    status_code=response.status_code,
+                    data=data,
+                    error=f"API {method} {path} returned {response.status_code}",
+                    headers=dict(response.headers),
+                )
+            return ProxyResponse(
+                status_code=response.status_code,
+                data=data,
+                headers=dict(response.headers),
+            )
+        except httpx.TimeoutException:
+            logger.warning("Proxy timeout: %s %s", method, url)
+            return ProxyResponse(status_code=504, error=f"Proxy timeout: {method} {path}")
+        except httpx.ConnectError as exc:
+            logger.warning("Proxy connect error: %s %s — %s", method, url, exc)
+            return ProxyResponse(status_code=502, error=f"API unreachable: {method} {path}")
+        except Exception as exc:
+            logger.error("Proxy error: %s %s — %s", method, url, exc, exc_info=True)
+            return ProxyResponse(status_code=500, error=f"Proxy error: {exc}")
+
+    async def get(self, path: str, **kwargs: Any) -> ProxyResponse:
+        """GET request to the API server."""
+        return await self.request("GET", path, **kwargs)
+
+    async def post(self, path: str, **kwargs: Any) -> ProxyResponse:
+        """POST request to the API server."""
+        return await self.request("POST", path, **kwargs)
+
+    async def put(self, path: str, **kwargs: Any) -> ProxyResponse:
+        """PUT request to the API server."""
+        return await self.request("PUT", path, **kwargs)
+
+    async def delete(self, path: str, **kwargs: Any) -> ProxyResponse:
+        """DELETE request to the API server."""
+        return await self.request("DELETE", path, **kwargs)
+
+    async def patch(self, path: str, **kwargs: Any) -> ProxyResponse:
+        """PATCH request to the API server."""
+        return await self.request("PATCH", path, **kwargs)

cloud_dog_api_kit/webhook/__init__.py

@@ -0,0 +1,29 @@
+# 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 — Webhook exports
+#
+# Licence: Proprietary — Cloud-Dog AI Platform
+# Owner: Cloud-Dog AI
+# Description: Webhook verification middleware exports.
+# Related requirements: FR18.7
+# Related architecture: SA1
+
+"""Webhook middleware exports."""
+
+from __future__ import annotations
+
+from cloud_dog_api_kit.webhook.signature import WebhookSignatureMiddleware, compute_webhook_signature
+
+__all__ = ["WebhookSignatureMiddleware", "compute_webhook_signature"]