python-ddd-framework 0.3.1__py3-none-any.whl

python_ddd_framework/fastapi/contracts.py

@@ -0,0 +1,275 @@
+"""Module-local Router metadata 与不可变 HTTP diagnostics contract。"""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass
+from typing import TypeVar
+
+from fastapi import APIRouter
+
+from ..application_services import ApplicationService, ApplicationServiceContract
+from ..diagnostics import SourceLocation
+from ..modularity import AppModule, ModuleKey
+from .errors import FastApiAdapterError
+
+_ROUTER_METADATA_ATTRIBUTE = "__python_ddd_framework_fastapi_routers__"
+_APPLICATION_SERVICE_EXPOSURE_ATTRIBUTE = (
+    "__python_ddd_framework_fastapi_application_service_exposure__"
+)
+_ModuleType = TypeVar("_ModuleType", bound=type[AppModule])
+_HTTP_VERBS = frozenset({"GET", "POST", "PUT", "DELETE", "PATCH"})
+_ROOT_PATH_SEGMENT_CHARACTERS = frozenset("abcdefghijklmnopqrstuvwxyz0123456789-")
+
+
+@dataclass(frozen=True, slots=True)
+class RouterRegistration:
+    owner: ModuleKey
+    source: SourceLocation
+    path: str
+    methods: tuple[str, ...]
+    operation_id: str
+    order: int
+    http_sources: tuple[tuple[str, str], ...] = ()
+
+
+@dataclass(frozen=True, slots=True)
+class WebSocketRouteRegistration:
+    owner: ModuleKey
+    source: SourceLocation
+    path: str
+    order: int
+
+
+class RouterCatalog:
+    """Application-local route 诊断目录；HTTP 与 WebSocket 保持独立视图。"""
+
+    __slots__ = ("_registrations", "_websocket_registrations")
+
+    def __init__(
+        self,
+        registrations: tuple[RouterRegistration, ...],
+        websocket_registrations: tuple[WebSocketRouteRegistration, ...] = (),
+    ) -> None:
+        self._registrations = registrations
+        self._websocket_registrations = websocket_registrations
+
+    @property
+    def registrations(self) -> tuple[RouterRegistration, ...]:
+        return self._registrations
+
+    def for_owner(self, owner: ModuleKey) -> tuple[RouterRegistration, ...]:
+        return tuple(item for item in self._registrations if item.owner == owner)
+
+    @property
+    def websocket_registrations(self) -> tuple[WebSocketRouteRegistration, ...]:
+        return self._websocket_registrations
+
+    def websockets_for_owner(
+        self,
+        owner: ModuleKey,
+    ) -> tuple[WebSocketRouteRegistration, ...]:
+        return tuple(item for item in self._websocket_registrations if item.owner == owner)
+
+
+@dataclass(frozen=True, slots=True)
+class ApplicationServiceRouteOverride:
+    """用 Protocol identity 覆盖单个 convention route，或排除整个 service。"""
+
+    service: type[object]
+    method: Callable[..., Awaitable[object]] | None = None
+    enabled: bool = True
+    path: str | None = None
+    verb: str | None = None
+    status_code: int | None = None
+    operation_id: str | None = None
+    include_in_schema: bool | None = None
+
+    def __post_init__(self) -> None:
+        _require_application_service_contract(self.service, role="route override service")
+        if self.method is not None and not callable(self.method):
+            raise FastApiAdapterError("route override method must be a Protocol method")
+        if not isinstance(self.enabled, bool):
+            raise FastApiAdapterError("route override enabled must be bool")
+        if self.path is not None and (
+            not isinstance(self.path, str)
+            or not self.path.startswith("/")
+            or self.path == "/"
+            or self.path.endswith("/")
+            or "//" in self.path
+        ):
+            raise FastApiAdapterError(
+                "route override path must be a non-root absolute path without a trailing slash"
+            )
+        _validate_schema_visibility(self.include_in_schema)
+        normalized_verb = self.verb.upper() if isinstance(self.verb, str) else self.verb
+        if normalized_verb is not None and normalized_verb not in _HTTP_VERBS:
+            raise FastApiAdapterError(
+                "route override verb must be GET, POST, PUT, DELETE, or PATCH"
+            )
+        if normalized_verb is not None:
+            object.__setattr__(self, "verb", normalized_verb)
+        if self.status_code is not None and (
+            not isinstance(self.status_code, int)
+            or isinstance(self.status_code, bool)
+            or not 100 <= self.status_code <= 599
+        ):
+            raise FastApiAdapterError("route override status_code must be between 100 and 599")
+        if self.operation_id is not None and (
+            not isinstance(self.operation_id, str)
+            or not self.operation_id
+            or self.operation_id != self.operation_id.strip()
+        ):
+            raise FastApiAdapterError(
+                "route override operation_id must be a non-empty trimmed string"
+            )
+        route_fields = (
+            self.path,
+            self.verb,
+            self.status_code,
+            self.operation_id,
+            self.include_in_schema,
+        )
+        if self.method is None and (self.enabled or any(item is not None for item in route_fields)):
+            raise FastApiAdapterError("service-level route override only supports enabled=False")
+        if not self.enabled and any(item is not None for item in route_fields):
+            raise FastApiAdapterError(
+                "disabled route override cannot also set path, verb, status_code, or operation_id"
+            )
+
+
+@dataclass(frozen=True, slots=True)
+class _ApplicationServiceExposure:
+    target_modules: tuple[type[AppModule], ...]
+    root_path: str
+    overrides: tuple[ApplicationServiceRouteOverride, ...]
+
+
+def contributes_routers(*routers: APIRouter) -> Callable[[_ModuleType], _ModuleType]:
+    """把 immutable router tuple 附着到当前 Module class，不建立 global registry。"""
+
+    if not routers:
+        raise FastApiAdapterError("router contribution must contain at least one APIRouter")
+    if any(not isinstance(router, APIRouter) for router in routers):
+        raise FastApiAdapterError("router contribution items must be FastAPI APIRouter instances")
+
+    def decorate(module_type: _ModuleType) -> _ModuleType:
+        if not isinstance(module_type, type) or not issubclass(module_type, AppModule):
+            raise FastApiAdapterError("contributes_routers target must be an AppModule class")
+        # vars() 强制 class-local；父类 metadata 不会被子 Module 隐式重复贡献。
+        if _ROUTER_METADATA_ATTRIBUTE in vars(module_type):
+            raise FastApiAdapterError(
+                f"{module_type.__module__}:{module_type.__qualname__} already declares routers"
+            )
+        setattr(module_type, _ROUTER_METADATA_ATTRIBUTE, routers)
+        return module_type
+
+    return decorate
+
+
+def exposes_application_services(
+    *target_modules: type[AppModule],
+    root_path: str = "",
+    overrides: tuple[ApplicationServiceRouteOverride, ...] = (),
+) -> Callable[[_ModuleType], _ModuleType]:
+    """让 HTTP Module 显式暴露其直接依赖 Module 拥有的 Application Services。"""
+
+    if not target_modules:
+        raise FastApiAdapterError(
+            "application service exposure must declare at least one target Module"
+        )
+    if any(
+        not isinstance(module_type, type) or not issubclass(module_type, AppModule)
+        for module_type in target_modules
+    ):
+        raise FastApiAdapterError("application service exposure targets must be AppModule classes")
+    if len(set(target_modules)) != len(target_modules):
+        raise FastApiAdapterError("application service exposure contains duplicate target Modules")
+    normalized_root_path = _validate_root_path(root_path)
+    if not isinstance(overrides, tuple) or any(
+        not isinstance(item, ApplicationServiceRouteOverride) for item in overrides
+    ):
+        raise FastApiAdapterError(
+            "application service exposure overrides must be an immutable tuple"
+        )
+    exposure = _ApplicationServiceExposure(
+        target_modules=target_modules,
+        root_path=normalized_root_path,
+        overrides=overrides,
+    )
+
+    def decorate(module_type: _ModuleType) -> _ModuleType:
+        if not isinstance(module_type, type) or not issubclass(module_type, AppModule):
+            raise FastApiAdapterError(
+                "exposes_application_services target must be an AppModule class"
+            )
+        if _APPLICATION_SERVICE_EXPOSURE_ATTRIBUTE in vars(module_type):
+            raise FastApiAdapterError(
+                f"{module_type.__module__}:{module_type.__qualname__} already declares "
+                "application service exposure"
+            )
+        setattr(module_type, _APPLICATION_SERVICE_EXPOSURE_ATTRIBUTE, exposure)
+        return module_type
+
+    return decorate
+
+
+def _routers_for(module_type: type[AppModule]) -> tuple[APIRouter, ...]:
+    raw_metadata = vars(module_type).get(_ROUTER_METADATA_ATTRIBUTE, ())
+    if not isinstance(raw_metadata, tuple) or any(
+        not isinstance(router, APIRouter) for router in raw_metadata
+    ):
+        raise FastApiAdapterError(
+            f"{module_type.__module__}:{module_type.__qualname__} router metadata "
+            "must remain an immutable tuple of APIRouter instances"
+        )
+    return raw_metadata
+
+
+def _application_service_exposure_for(
+    module_type: type[AppModule],
+) -> _ApplicationServiceExposure | None:
+    metadata = vars(module_type).get(_APPLICATION_SERVICE_EXPOSURE_ATTRIBUTE)
+    if metadata is None:
+        return None
+    if not isinstance(metadata, _ApplicationServiceExposure):
+        raise FastApiAdapterError(
+            f"{module_type.__module__}:{module_type.__qualname__} application service "
+            "exposure metadata has an invalid runtime shape"
+        )
+    return metadata
+
+
+def _validate_root_path(root_path: object) -> str:
+    if root_path == "":
+        return ""
+    if not isinstance(root_path, str) or root_path != root_path.strip("/") or "//" in root_path:
+        raise FastApiAdapterError("application service exposure root_path must be a relative path")
+    for segment in root_path.split("/"):
+        if (
+            not segment
+            or segment.startswith("-")
+            or segment.endswith("-")
+            or any(character not in _ROOT_PATH_SEGMENT_CHARACTERS for character in segment)
+        ):
+            raise FastApiAdapterError(
+                "application service exposure root_path must use lowercase kebab-case segments"
+            )
+    return root_path
+
+
+def _require_application_service_contract(candidate: object, *, role: str) -> None:
+    if isinstance(candidate, type) and issubclass(candidate, ApplicationService):
+        return
+    if (
+        not isinstance(candidate, type)
+        or not bool(getattr(candidate, "_is_protocol", False))
+        or ApplicationServiceContract not in candidate.__mro__
+        or candidate is ApplicationServiceContract
+    ):
+        raise FastApiAdapterError(f"{role} must be an ApplicationServiceContract Protocol")
+
+
+def _validate_schema_visibility(value: bool | None) -> None:
+    if value is not None and not isinstance(value, bool):
+        raise FastApiAdapterError("include_in_schema must be bool or None")

python_ddd_framework/fastapi/errors.py

@@ -0,0 +1,32 @@
+"""FastAPI adapter 安装与 route consistency 的结构化失败。"""
+
+from __future__ import annotations
+
+from ..diagnostics import SourceLocation
+from ..errors import FrameworkError
+
+
+class FastApiAdapterError(FrameworkError):
+    """Adapter 无法在不破坏 Application/HTTP 不变量时继续。"""
+
+    def __init__(self, reason: str) -> None:
+        self.reason = reason
+        super().__init__(f"FastAPI adapter rejected installation or startup: {reason}")
+
+
+class RouteConflictError(FastApiAdapterError):
+    """两个 HTTP/OpenAPI 声明竞争同一稳定 identity。"""
+
+    def __init__(
+        self,
+        *,
+        conflict_kind: str,
+        value: str,
+        sources: tuple[SourceLocation, SourceLocation],
+    ) -> None:
+        self.conflict_kind = conflict_kind
+        self.value = value
+        self.sources = sources
+        super().__init__(
+            f"duplicate {conflict_kind} {value!r} from {sources[0].owner} and {sources[1].owner}"
+        )

python_ddd_framework/fastapi/filters.py

@@ -0,0 +1,111 @@
+"""HTTP 已绑定参数与原始结果边界；不参与进程内服务调用。"""
+
+from __future__ import annotations
+
+import asyncio
+import inspect
+from collections.abc import Awaitable, Callable, Sequence
+from dataclasses import dataclass
+from typing import TypeVar
+
+from dishka import AsyncContainer, Scope
+from starlette.requests import Request
+
+from ..application_services.errors import (
+    ApplicationInvocationRejectedError,
+    CrossTaskInvocationError,
+)
+from ..invocation.callables import _dependency_key
+from .errors import FastApiAdapterError
+
+_T = TypeVar("_T")
+_FILTERS = "__python_ddd_framework_service_filters__"
+
+
+@dataclass(frozen=True, slots=True)
+class ServiceFilter:
+    filter_type: type[object]
+    order: int = 0
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.filter_type, type) or not isinstance(self.order, int):
+            raise TypeError("service_filter requires a type and integer order")
+
+
+def service_filter(filter_type: type[object], *, order: int = 0) -> Callable[[_T], _T]:
+    registration = ServiceFilter(filter_type, order)
+
+    def decorate(target: _T) -> _T:
+        # Python 由下向上应用装饰器；公开声明顺序仍按源码从上向下。
+        setattr(target, _FILTERS, (registration, *vars(target).get(_FILTERS, ())))
+        return target
+
+    return decorate
+
+
+def _filters_for(*targets: object) -> tuple[ServiceFilter, ...]:
+    return tuple(item for target in targets for item in vars(target).get(_FILTERS, ()))
+
+
+def _ordered_filters(*levels: Sequence[ServiceFilter]) -> tuple[ServiceFilter, ...]:
+    return tuple(
+        item[3]
+        for item in sorted(
+            (registration.order, level, index, registration)
+            for level, registrations in enumerate(levels)
+            for index, registration in enumerate(registrations)
+        )
+    )
+
+
+@dataclass(frozen=True, slots=True)
+class ActionFilterContext:
+    request: Request
+    endpoint: object
+    arguments: dict[str, object]
+
+
+class _FilterContinuation:
+    def __init__(self, callback: Callable[[], Awaitable[object]]) -> None:
+        self._callback = callback
+        self._task = asyncio.current_task()
+        self._consumed = False
+        self.active = True
+
+    async def __call__(self) -> object:
+        if asyncio.current_task() is not self._task:
+            raise CrossTaskInvocationError
+        if self._consumed or not self.active:
+            raise ApplicationInvocationRejectedError(reason="filter continuation is unavailable")
+        self._consumed = True
+        return await self._callback()
+
+
+async def _run_filters(
+    registrations: tuple[ServiceFilter, ...],
+    container: AsyncContainer,
+    context: ActionFilterContext,
+    target: Callable[[], Awaitable[object]],
+) -> object:
+    async def invoke(index: int) -> object:
+        if index == len(registrations):
+            return await target()
+        instance = await container.get(registrations[index].filter_type)
+        continuation = _FilterContinuation(lambda: invoke(index + 1))
+        try:
+            return await instance.invoke(context, continuation)  # type: ignore[attr-defined]
+        finally:
+            continuation.active = False
+
+    return await invoke(0)
+
+
+def _validate_filters(registrations: Sequence[ServiceFilter], container: AsyncContainer) -> None:
+    for registration in registrations:
+        if not isinstance(registration, ServiceFilter):
+            raise FastApiAdapterError("HTTP filters must be ServiceFilter declarations")
+        parameter = inspect.Parameter("filter", inspect.Parameter.KEYWORD_ONLY)
+        if _dependency_key(parameter, registration.filter_type, container, Scope.ACTION) is None:
+            raise FastApiAdapterError("HTTP filter type is not registered")
+        if not inspect.iscoroutinefunction(getattr(registration.filter_type, "invoke", None)):
+            raise FastApiAdapterError("HTTP filter requires async invoke(context, next_action)")

python_ddd_framework/fastapi/health.py

@@ -0,0 +1,44 @@
+"""Application lifecycle 导出的固定 HTTP health contract。"""
+
+from __future__ import annotations
+
+from fastapi import APIRouter
+from starlette.responses import JSONResponse
+
+from ..application import Application
+
+HEALTH_LIVE_PATH = "/health/live"
+HEALTH_READY_PATH = "/health/ready"
+HEALTH_LIVE_OPERATION_ID = "python_ddd_framework_health_live"
+HEALTH_READY_OPERATION_ID = "python_ddd_framework_health_ready"
+
+
+def _create_health_router(application: Application) -> APIRouter:
+    router = APIRouter(tags=["health"])
+
+    async def live() -> JSONResponse:
+        return JSONResponse(status_code=200, content={"status": "live"})
+
+    async def ready() -> JSONResponse:
+        is_ready = application.readiness.ready
+        return JSONResponse(
+            status_code=200 if is_ready else 503,
+            content={"status": "ready" if is_ready else "not_ready"},
+        )
+
+    router.add_api_route(
+        HEALTH_LIVE_PATH,
+        live,
+        methods=["GET"],
+        operation_id=HEALTH_LIVE_OPERATION_ID,
+        summary="Liveness",
+    )
+    router.add_api_route(
+        HEALTH_READY_PATH,
+        ready,
+        methods=["GET"],
+        operation_id=HEALTH_READY_OPERATION_ID,
+        summary="Readiness",
+        responses={503: {"description": "Application is not ready"}},
+    )
+    return router

python_ddd_framework/fastapi/http.py

@@ -0,0 +1,72 @@
+"""实现方法的 HTTP projection 声明；原生路由选项由 FastAPI 校验。"""
+
+from collections.abc import Callable, Mapping
+from functools import partial
+from types import MappingProxyType
+from typing import Any, TypeVar, cast
+
+from .contracts import _validate_root_path
+
+_T = TypeVar("_T")
+_HTTP_ATTRIBUTE = "__python_ddd_framework_http__"
+_REMOTE_ATTRIBUTE = "__python_ddd_framework_remote_service__"
+_SERVICE_PATH_ATTRIBUTE = "__python_ddd_framework_service_path__"
+
+
+def _declare(verb: str, path: str | None = None, **options: Any) -> Callable[[_T], _T]:
+    if path is not None and (not isinstance(path, str) or not path.startswith("/")):
+        raise ValueError("http path must be absolute")
+    declaration = MappingProxyType(
+        {**options, "verb": verb, **({"path": path} if path is not None else {})}
+    )
+
+    def decorate(target: _T) -> _T:
+        if not callable(target) or _HTTP_ATTRIBUTE in vars(target):
+            raise TypeError("http declaration requires a method declared once")
+        setattr(target, _HTTP_ATTRIBUTE, declaration)
+        return target
+
+    return decorate
+
+
+def _metadata(method: object) -> Mapping[str, Any]:
+    return cast(Mapping[str, Any], vars(method).get(_HTTP_ATTRIBUTE, MappingProxyType({})))
+
+
+def remote_service(
+    *, is_enabled: bool = True, is_metadata_enabled: bool = True, path: str | None = None
+) -> Callable[[_T], _T]:
+    if not isinstance(is_enabled, bool) or not isinstance(is_metadata_enabled, bool):
+        raise TypeError("remote_service switches must be bool")
+    if path is not None:
+        _validate_root_path(path)
+        if not path or "/" in path:
+            raise ValueError("remote_service path must be one non-empty service segment")
+
+    def decorate(target: _T) -> _T:
+        if path is not None and not isinstance(target, type):
+            raise TypeError("remote_service path requires an implementation class")
+        setattr(target, _REMOTE_ATTRIBUTE, (is_enabled, is_metadata_enabled))
+        if path is not None:
+            setattr(target, _SERVICE_PATH_ATTRIBUTE, path)
+        return target
+
+    return decorate
+
+
+def _remote(implementation: type[object], method: object) -> tuple[bool, bool]:
+    for target in (method, *implementation.__mro__):
+        if _REMOTE_ATTRIBUTE in vars(target):
+            return cast(tuple[bool, bool], vars(target)[_REMOTE_ATTRIBUTE])
+    return True, True
+
+
+def _service_segment(implementation: type[object]) -> str | None:
+    return cast(str | None, getattr(implementation, _SERVICE_PATH_ATTRIBUTE, None))
+
+
+get = partial(_declare, "GET")
+post = partial(_declare, "POST")
+put = partial(_declare, "PUT")
+patch = partial(_declare, "PATCH")
+delete = partial(_declare, "DELETE")