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

cloud_dog_api_kit/errors/handler.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 — Error handler registration for FastAPI
+#
+# Licence: Proprietary — Cloud-Dog AI Platform
+# Owner: Cloud-Dog AI
+# Description: Registers exception handlers that convert APIError subclasses,
+#   RequestValidationError, and unhandled exceptions into standard error envelopes.
+# Related requirements: FR2.2, CS1.1, CS1.5
+# Related architecture: CC1.3
+
+"""Error handler registration for FastAPI applications."""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from fastapi import FastAPI, Request
+from fastapi.exceptions import RequestValidationError
+from starlette.responses import JSONResponse
+
+from cloud_dog_api_kit.errors.exceptions import APIError
+from cloud_dog_api_kit.envelopes.error import error_envelope
+
+logger = logging.getLogger("cloud_dog_api_kit.errors")
+
+
+def register_error_handlers(app: FastAPI) -> None:
+    """Register standard error handlers on a FastAPI application.
+
+    Converts:
+    - APIError subclasses into the standard error envelope with correct HTTP status.
+    - RequestValidationError into an INVALID_REQUEST envelope with field-level details.
+    - Unhandled Exception into a generic 500 with no leaked internals.
+
+    Args:
+        app: The FastAPI application instance.
+
+    Related tests: UT1.5_ErrorHandler, ST1.2_ErrorFlowEndToEnd, SEC1.6_ErrorSanitisation
+    """
+
+    @app.exception_handler(APIError)
+    async def _api_error_handler(request: Request, exc: APIError) -> JSONResponse:
+        request_id = getattr(request.state, "request_id", "")
+        correlation_id = getattr(request.state, "correlation_id", None)
+        body = error_envelope(
+            code=exc.code,
+            message=exc.message,
+            details=exc.details,
+            retryable=exc.retryable,
+            request_id=request_id,
+            correlation_id=correlation_id,
+        )
+        return JSONResponse(status_code=exc.status_code, content=body)
+
+    @app.exception_handler(RequestValidationError)
+    async def _validation_error_handler(request: Request, exc: RequestValidationError) -> JSONResponse:
+        request_id = getattr(request.state, "request_id", "")
+        correlation_id = getattr(request.state, "correlation_id", None)
+        field_errors: dict[str, Any] = {}
+        for error in exc.errors():
+            loc = ".".join(str(part) for part in error.get("loc", []))
+            field_errors[loc] = error.get("msg", "Validation error")
+        body = error_envelope(
+            code="INVALID_REQUEST",
+            message="Validation failure",
+            details=field_errors,
+            retryable=False,
+            request_id=request_id,
+            correlation_id=correlation_id,
+        )
+        return JSONResponse(status_code=422, content=body)
+
+    @app.exception_handler(Exception)
+    async def _generic_error_handler(request: Request, exc: Exception) -> JSONResponse:
+        request_id = getattr(request.state, "request_id", "")
+        correlation_id = getattr(request.state, "correlation_id", None)
+        logger.exception(
+            "Unhandled exception",
+            extra={"request_id": request_id, "path": request.url.path},
+        )
+        body = error_envelope(
+            code="INTERNAL_ERROR",
+            message="An internal error occurred",
+            retryable=False,
+            request_id=request_id,
+            correlation_id=correlation_id,
+        )
+        return JSONResponse(status_code=500, content=body)

cloud_dog_api_kit/errors/taxonomy.py

@@ -0,0 +1,62 @@
+# 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
+#
+# Licence: Proprietary — Cloud-Dog AI Platform
+# Owner: Cloud-Dog AI
+# Description: Stable error code taxonomy (9 codes) per PS-20.
+# Related requirements: FR1.3
+# Related architecture: SA1, CC1.3
+
+"""Error code taxonomy for cloud_dog_api_kit."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True, slots=True)
+class ErrorTaxonomyEntry:
+    """One error taxonomy entry."""
+
+    code: str
+    http_status: int
+    retryable: bool
+
+
+UNAUTHENTICATED = ErrorTaxonomyEntry(code="UNAUTHENTICATED", http_status=401, retryable=False)
+UNAUTHORISED = ErrorTaxonomyEntry(code="UNAUTHORISED", http_status=403, retryable=False)
+NOT_FOUND = ErrorTaxonomyEntry(code="NOT_FOUND", http_status=404, retryable=False)
+CONFLICT = ErrorTaxonomyEntry(code="CONFLICT", http_status=409, retryable=False)
+INVALID_REQUEST = ErrorTaxonomyEntry(code="INVALID_REQUEST", http_status=422, retryable=False)
+RATE_LIMITED = ErrorTaxonomyEntry(code="RATE_LIMITED", http_status=429, retryable=True)
+TIMEOUT = ErrorTaxonomyEntry(code="TIMEOUT", http_status=504, retryable=True)
+UPSTREAM_ERROR = ErrorTaxonomyEntry(code="UPSTREAM_ERROR", http_status=502, retryable=True)
+INTERNAL_ERROR = ErrorTaxonomyEntry(code="INTERNAL_ERROR", http_status=500, retryable=False)
+
+
+ALL_ENTRIES: tuple[ErrorTaxonomyEntry, ...] = (
+    UNAUTHENTICATED,
+    UNAUTHORISED,
+    NOT_FOUND,
+    CONFLICT,
+    INVALID_REQUEST,
+    RATE_LIMITED,
+    TIMEOUT,
+    UPSTREAM_ERROR,
+    INTERNAL_ERROR,
+)
+
+BY_CODE: dict[str, ErrorTaxonomyEntry] = {e.code: e for e in ALL_ENTRIES}

cloud_dog_api_kit/factory.py

@@ -0,0 +1,157 @@
+# 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 — FastAPI application factory
+#
+# Licence: Proprietary — Cloud-Dog AI Platform
+# Owner: Cloud-Dog AI
+# Description: `create_app()` wires standard middleware, error handlers,
+#   health routes, and version endpoint for Cloud-Dog services.
+# Related requirements: FR10.4, FR12.1, FR6.1
+# Related architecture: SA1
+
+"""FastAPI application factory for cloud_dog_api_kit."""
+
+from __future__ import annotations
+
+from contextlib import asynccontextmanager
+from typing import Any, Callable
+
+from fastapi import FastAPI
+
+from cloud_dog_api_kit.correlation import CorrelationMiddleware
+from cloud_dog_api_kit.errors import register_error_handlers
+from cloud_dog_logging.middleware.audit import AuditMiddleware
+from cloud_dog_api_kit.lifecycle import (
+    GracefulShutdownManager,
+    LifecycleHooks,
+    ShutdownDrainMiddleware,
+    install_shutdown_signal_handlers,
+)
+from cloud_dog_api_kit.middleware import RequestLoggingMiddleware, TimingMiddleware, TimeoutMiddleware, configure_cors
+from cloud_dog_api_kit.middleware.request_size_limit import RequestSizeLimitMiddleware
+from cloud_dog_api_kit.routers.health import create_health_router
+from cloud_dog_api_kit.versioning import VersionHeaderMiddleware
+
+
+def create_app(
+    title: str,
+    version: str = "0.0.0",
+    description: str = "",
+    api_prefix: str = "/api/v1",
+    base_path: str = "",
+    health_checks: dict[str, Callable] | None = None,
+    auth_verify_fn: Callable | None = None,
+    enable_request_logging: bool = True,
+    enable_cors: bool = True,
+    cors_origins: list[str] | None = None,
+    enable_docs: bool = True,
+    enable_streaming: bool = False,
+    lifecycle_hooks: LifecycleHooks | None = None,
+    enable_health: bool = True,
+    max_request_body_bytes: int | None = None,
+    timeout_seconds: float = 30.0,
+    shutdown_drain_timeout_seconds: float = 5.0,
+    register_signal_handlers_on_startup: bool = True,
+    enable_audit_logging: bool = True,
+) -> FastAPI:
+    """Create a fully configured FastAPI application.
+
+    Wires:
+    - Error handlers (APIError, validation, unhandled)
+    - Correlation ID middleware (X-Request-Id, X-Correlation-Id, X-App-Id)
+    - Request logging middleware
+    - CORS middleware (production-safe defaults)
+    - Health/ready/live/status routes
+    - /api/v1/version endpoint
+    - X-API-Version response header
+    - Swagger UI / ReDoc (disableable)
+    - Reverse proxy base path via ``root_path`` (DC-11)
+
+    Args:
+        base_path: URL prefix when behind a reverse proxy (e.g. "/api").
+            Passed as FastAPI ``root_path`` so generated URLs, OpenAPI docs,
+            and redirects include the prefix. Default "" (no prefix).
+    """
+    hooks = lifecycle_hooks or LifecycleHooks()
+    shutdown_manager = GracefulShutdownManager(drain_timeout_seconds=shutdown_drain_timeout_seconds)
+
+    @asynccontextmanager
+    async def _lifespan(app: FastAPI):
+        await hooks.run_startup(app)
+        if register_signal_handlers_on_startup:
+            install_shutdown_signal_handlers(shutdown_manager)
+        try:
+            yield
+        finally:
+            await shutdown_manager.initiate_shutdown()
+            await hooks.run_shutdown(app)
+
+    app = FastAPI(
+        title=title,
+        version=version,
+        description=description,
+        root_path=base_path,
+        docs_url="/docs" if enable_docs else None,
+        redoc_url="/redoc" if enable_docs else None,
+        lifespan=_lifespan,
+    )
+    app.state.lifecycle_hooks = hooks
+    app.state.shutdown_manager = shutdown_manager
+
+    register_error_handlers(app)
+
+    # Middleware ordering: outermost first.
+    app.add_middleware(VersionHeaderMiddleware, version="v1")
+    if enable_request_logging:
+        app.add_middleware(RequestLoggingMiddleware)
+    if enable_audit_logging:
+        app.add_middleware(AuditMiddleware)
+    app.add_middleware(TimingMiddleware)
+    app.add_middleware(TimeoutMiddleware, timeout_seconds=timeout_seconds)
+    if max_request_body_bytes is not None:
+        app.add_middleware(RequestSizeLimitMiddleware, max_bytes=max_request_body_bytes)
+    app.add_middleware(ShutdownDrainMiddleware, manager=shutdown_manager)
+    app.add_middleware(CorrelationMiddleware)
+    if enable_cors:
+        configure_cors(app, allowed_origins=cors_origins)
+
+    # Health routes. /status can be protected if a verify function is supplied.
+    # Set enable_health=False when the project defines its own custom health endpoints.
+    if enable_health:
+        from cloud_dog_api_kit.auth.dependency import create_auth_dependency
+
+        auth_dep = None
+        if auth_verify_fn:
+            auth_dep = create_auth_dependency(api_key_verify_fn=auth_verify_fn)
+
+        app.include_router(
+            create_health_router(
+                application_name=title,
+                version=version,
+                checks=health_checks,
+                auth_dependency=auth_dep,
+            )
+        )
+
+    @app.get(f"{api_prefix}/version", tags=["system"])
+    async def api_version() -> dict[str, Any]:
+        """Return the API version information."""
+        return {
+            "application": title,
+            "version": version,
+            "api_version": "v1",
+        }
+
+    return app

cloud_dog_api_kit/idempotency/__init__.py

@@ -0,0 +1,28 @@
+# 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 — Idempotency middleware and store
+#
+# Licence: Proprietary — Cloud-Dog AI Platform
+# Owner: Cloud-Dog AI
+# Description: Idempotency-Key header support with pluggable storage backend.
+# Related requirements: FR4.4
+# Related architecture: CC1.16
+
+"""Idempotency middleware and store for cloud_dog_api_kit."""
+
+from cloud_dog_api_kit.idempotency.middleware import IdempotencyMiddleware
+from cloud_dog_api_kit.idempotency.store import IdempotencyStore, InMemoryIdempotencyStore
+
+__all__ = ["IdempotencyMiddleware", "IdempotencyStore", "InMemoryIdempotencyStore"]

cloud_dog_api_kit/idempotency/middleware.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 — Idempotency middleware
+#
+# Licence: Proprietary — Cloud-Dog AI Platform
+# Owner: Cloud-Dog AI
+# Description: ASGI middleware that honours Idempotency-Key headers for
+#   creation endpoints, caching and replaying responses.
+# Related requirements: FR4.4
+# Related architecture: CC1.16
+
+"""Idempotency middleware for cloud_dog_api_kit."""
+
+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.idempotency.store import InMemoryIdempotencyStore
+
+
+class IdempotencyMiddleware(BaseHTTPMiddleware):
+    """Middleware that honours Idempotency-Key headers.
+
+    First request with a key executes normally and caches the response.
+    Subsequent requests with the same key return the cached response.
+    Expired keys re-execute. Missing keys pass through.
+
+    Args:
+        app: The ASGI application.
+        store: Pluggable idempotency store. Defaults to in-memory.
+        ttl_seconds: Time-to-live for cached responses. Defaults to 86400 (24h).
+
+    Related tests: UT1.28_IdempotencyMiddleware, ST1.10_IdempotencyEndToEnd
+    """
+
+    def __init__(
+        self,
+        app: Any,
+        store: Any | None = None,
+        ttl_seconds: int = 86400,
+    ) -> None:
+        super().__init__(app)
+        self._store = store or InMemoryIdempotencyStore()
+        self._ttl = ttl_seconds
+
+    async def dispatch(self, request: Request, call_next: Callable) -> Response:
+        """Process request with idempotency key support.
+
+        Args:
+            request: The incoming HTTP request.
+            call_next: The next middleware or handler.
+
+        Returns:
+            The HTTP response (cached or fresh).
+        """
+        # Only apply to POST/PUT methods
+        if request.method not in ("POST", "PUT"):
+            return await call_next(request)
+
+        idem_key = request.headers.get("idempotency-key", "").strip()
+        if not idem_key:
+            return await call_next(request)
+
+        # Check cache
+        cached = await self._store.get(idem_key)
+        if cached is not None:
+            return JSONResponse(
+                status_code=cached.get("status_code", 200),
+                content=cached.get("body"),
+            )
+
+        # Execute request
+        response = await call_next(request)
+
+        # Cache the response body
+        if 200 <= response.status_code < 300:
+            body_bytes = b""
+            async for chunk in response.body_iterator:
+                if isinstance(chunk, bytes):
+                    body_bytes += chunk
+                else:
+                    body_bytes += chunk.encode("utf-8")
+
+            try:
+                body_json = json.loads(body_bytes)
+            except (json.JSONDecodeError, ValueError):
+                body_json = body_bytes.decode("utf-8")
+
+            await self._store.set(
+                idem_key,
+                {"status_code": response.status_code, "body": body_json},
+                self._ttl,
+            )
+
+            return JSONResponse(
+                status_code=response.status_code,
+                content=body_json,
+                headers=dict(response.headers),
+            )
+
+        return response

cloud_dog_api_kit/idempotency/store.py

@@ -0,0 +1,100 @@
+# 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 — Idempotency store protocol and in-memory implementation
+#
+# Licence: Proprietary — Cloud-Dog AI Platform
+# Owner: Cloud-Dog AI
+# Description: Pluggable idempotency store with in-memory default implementation.
+# Related requirements: FR4.4
+# Related architecture: CC1.16
+
+"""Idempotency store protocol and in-memory implementation."""
+
+from __future__ import annotations
+
+import time
+from typing import Protocol
+
+
+class IdempotencyStore(Protocol):
+    """Protocol for idempotency key storage backends.
+
+    Related tests: UT1.29_IdempotencyStore
+    """
+
+    async def get(self, key: str) -> dict | None:
+        """Get a cached response by idempotency key.
+
+        Args:
+            key: The idempotency key.
+
+        Returns:
+            The cached response dict, or None if not found or expired.
+        """
+        ...
+
+    async def set(self, key: str, response: dict, ttl: int) -> None:
+        """Store a response with the given idempotency key.
+
+        Args:
+            key: The idempotency key.
+            response: The response dict to cache.
+            ttl: Time-to-live in seconds.
+        """
+        ...
+
+
+class InMemoryIdempotencyStore:
+    """In-memory idempotency store for development and testing.
+
+    Stores responses in a dictionary with TTL-based expiry.
+
+    Related tests: UT1.29_IdempotencyStore
+    """
+
+    def __init__(self) -> None:
+        self._store: dict[str, tuple[dict, float]] = {}
+
+    async def get(self, key: str) -> dict | None:
+        """Get a cached response, returning None if expired.
+
+        Args:
+            key: The idempotency key.
+
+        Returns:
+            The cached response dict or None.
+        """
+        entry = self._store.get(key)
+        if entry is None:
+            return None
+        response, expiry = entry
+        if time.monotonic() > expiry:
+            del self._store[key]
+            return None
+        return response
+
+    async def set(self, key: str, response: dict, ttl: int) -> None:
+        """Store a response with TTL.
+
+        Args:
+            key: The idempotency key.
+            response: The response dict.
+            ttl: Time-to-live in seconds.
+        """
+        self._store[key] = (response, time.monotonic() + ttl)
+
+    def clear(self) -> None:
+        """Clear all stored entries."""
+        self._store.clear()

cloud_dog_api_kit/lifecycle/__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 — Lifecycle integration exports
+#
+# Licence: Proprietary — Cloud-Dog AI Platform
+# Owner: Cloud-Dog AI
+# Description: Public lifecycle and graceful shutdown exports.
+# Related requirements: FR18.2, FR18.9
+# Related architecture: SA1
+
+"""Lifecycle exports for cloud_dog_api_kit."""
+
+from __future__ import annotations
+
+from cloud_dog_api_kit.lifecycle.hooks import LifecycleHooks
+from cloud_dog_api_kit.lifecycle.shutdown import (
+    GracefulShutdownManager,
+    ShutdownDrainMiddleware,
+    install_shutdown_signal_handlers,
+)
+
+__all__ = [
+    "GracefulShutdownManager",
+    "LifecycleHooks",
+    "ShutdownDrainMiddleware",
+    "install_shutdown_signal_handlers",
+]

cloud_dog_api_kit/lifecycle/hooks.py

@@ -0,0 +1,75 @@
+# 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 — Startup lifecycle hook definitions
+#
+# Licence: Proprietary — Cloud-Dog AI Platform
+# Owner: Cloud-Dog AI
+# Description: Deterministic startup/shutdown hook model for create_app()
+#   lifecycle integration.
+# Related requirements: FR18.2
+# Related architecture: SA1
+
+"""Lifecycle hook definitions for cloud_dog_api_kit."""
+
+from __future__ import annotations
+
+import inspect
+from dataclasses import dataclass
+from typing import Awaitable, Callable
+
+from fastapi import FastAPI
+
+LifecycleCallback = Callable[[FastAPI], Awaitable[None] | None]
+
+
+async def _run_callback(phase: str, app: FastAPI, callback: LifecycleCallback | None) -> None:
+    """Run a lifecycle callback if configured."""
+    if callback is None:
+        return
+    result = callback(app)
+    if inspect.isawaitable(result):
+        await result
+    if result is not None and not inspect.isawaitable(result):
+        # Guard against accidental non-None return values in lifecycle callbacks.
+        raise TypeError(f"Lifecycle callback for {phase} must return None or awaitable None")
+
+
+@dataclass(slots=True)
+class LifecycleHooks:
+    """Startup/shutdown lifecycle hook collection.
+
+    Phases:
+    - `on_pre_db`: pre-database bootstrap phase.
+    - `on_post_db`: post-database, pre-router phase.
+    - `on_post_router`: post-router registration, pre-serving phase.
+    - `on_shutdown`: graceful shutdown callback.
+
+    Related tests: UT1.38_StartupLifecycleHooks, ST1.13_StartupLifecycleIntegration
+    """
+
+    on_pre_db: LifecycleCallback | None = None
+    on_post_db: LifecycleCallback | None = None
+    on_post_router: LifecycleCallback | None = None
+    on_shutdown: LifecycleCallback | None = None
+
+    async def run_startup(self, app: FastAPI) -> None:
+        """Run startup phases in deterministic order."""
+        await _run_callback("on_pre_db", app, self.on_pre_db)
+        await _run_callback("on_post_db", app, self.on_post_db)
+        await _run_callback("on_post_router", app, self.on_post_router)
+
+    async def run_shutdown(self, app: FastAPI) -> None:
+        """Run shutdown hook."""
+        await _run_callback("on_shutdown", app, self.on_shutdown)