python-ddd-framework 0.4.0__py3-none-any.whl → 0.6.0__py3-none-any.whl

python_ddd_framework/fastapi/error_handlers.py

@@ -0,0 +1,128 @@
+"""HTTP 错误状态映射与安全字段输出；安装和退出仍归 Adapter。"""
+
+from __future__ import annotations
+
+import logging
+from typing import cast, get_args
+
+from fastapi.exceptions import RequestValidationError
+from pydantic_core.core_schema import ErrorType
+from starlette.requests import Request
+from starlette.responses import JSONResponse
+
+from ..application_services import ApplicationServiceValidationError
+from ..errors import BusinessError, FrameworkError
+
+# 保留已有日志类别，避免纯职责搬迁改变 Host 的日志筛选行为。
+_LOGGER = logging.getLogger(f"{__package__}.adapter")
+_SAFE_REQUEST_LOCATION_ROOTS = frozenset({"body", "cookie", "header", "path", "query"})
+_TRUSTED_VALIDATION_ERROR_TYPES = frozenset(get_args(ErrorType))
+
+
+async def _business_error_handler(request: Request, error: Exception) -> JSONResponse:
+    business_error = cast(BusinessError, error)
+    return JSONResponse(
+        status_code=400,
+        content={
+            "error": {
+                "code": business_error.definition.code,
+                "message": business_error.definition.message,
+                "fields": [field.name for field in business_error.fields],
+                **(
+                    {
+                        "data": business_error.data.model_dump(
+                            mode="json", by_alias=True, warnings="error"
+                        )
+                    }
+                    if business_error.data is not None
+                    else {}
+                ),
+            }
+        },
+    )
+
+
+async def _framework_error_handler(request: Request, error: Exception) -> JSONResponse:
+    framework_error = cast(FrameworkError, error)
+    _LOGGER.error(
+        "Unhandled FrameworkError for %s %s",
+        request.method,
+        request.url.path,
+        exc_info=(type(framework_error), framework_error, framework_error.__traceback__),
+    )
+    return JSONResponse(status_code=500, content={"detail": "Internal Server Error"})
+
+
+async def _application_service_validation_handler(
+    request: Request,
+    error: Exception,
+) -> JSONResponse:
+    validation_error = cast(ApplicationServiceValidationError, error)
+    return JSONResponse(
+        status_code=422,
+        content={
+            "detail": [
+                {
+                    "loc": list(issue.location),
+                    "msg": issue.message,
+                    "type": issue.error_type,
+                }
+                for issue in validation_error.issues
+            ]
+        },
+    )
+
+
+async def _request_validation_handler(request: Request, error: Exception) -> JSONResponse:
+    validation_error = cast(RequestValidationError, error)
+    return JSONResponse(
+        status_code=422,
+        content={
+            "detail": [
+                {
+                    "loc": list(_safe_request_validation_location(detail.get("loc"))),
+                    "msg": "Input validation failed",
+                    "type": _trusted_request_validation_error_type(detail.get("type")),
+                }
+                for detail in validation_error.errors()
+            ]
+        },
+    )
+
+
+def _safe_request_validation_location(location: object) -> tuple[str, ...]:
+    if (
+        isinstance(location, tuple)
+        and location
+        and isinstance(location[0], str)
+        and location[0] in _SAFE_REQUEST_LOCATION_ROOTS
+    ):
+        # 后续 segment 可能来自用户控制的 mapping key；只发布 FastAPI 自有位置类别。
+        return (location[0],)
+    return ()
+
+
+def _trusted_request_validation_error_type(error_type: object) -> str:
+    if isinstance(error_type, str) and error_type in _TRUSTED_VALIDATION_ERROR_TYPES:
+        return error_type
+    return "value_error"
+
+
+async def _unauthenticated_handler(request: Request, error: Exception) -> JSONResponse:
+    return JSONResponse(
+        status_code=401,
+        content={"detail": "Not authenticated"},
+        headers={"WWW-Authenticate": "Bearer"},
+    )
+
+
+async def _permission_denied_handler(request: Request, error: Exception) -> JSONResponse:
+    return JSONResponse(status_code=403, content={"detail": "Forbidden"})
+
+
+async def _resource_conflict_handler(request: Request, error: Exception) -> JSONResponse:
+    return JSONResponse(status_code=409, content={"detail": "Resource conflict"})
+
+
+async def _resource_not_found_handler(request: Request, error: Exception) -> JSONResponse:
+    return JSONResponse(status_code=404, content={"detail": "Resource not found"})

python_ddd_framework/fastapi/realtime/runtime.py

@@ -11,8 +11,8 @@ from uuid import UUID, uuid4
 from dishka import AsyncContainer
 from fastapi import WebSocket
 
-from ...application_services.invocation import _InvocationRuntime
 from ...authorization import AccessTokenAuthenticator, CurrentUser, UnauthenticatedError
+from ...invocation.runtime import _InvocationRuntime
 from ...options import Options
 from ...realtime import (
     RealtimeDeliveryReport,

python_ddd_framework/fastapi/request_context.py

@@ -18,15 +18,12 @@ from starlette.responses import JSONResponse
 from starlette.types import ASGIApp, Message, Receive, Scope, Send
 
 from ..application import Application
-from ..application_services.invocation import (
-    _close_action,
-    _InvocationRuntime,
-    _raise_scope_failure,
-)
 from ..auditing import AuditSink, RequestAuditRecord
 from ..authorization import AccessTokenAuthenticator, CurrentUser, UnauthenticatedError
 from ..invocation.contracts import _is_safe_correlation_id
 from ..invocation.entrypoints import http_request_lease
+from ..invocation.runtime import _InvocationRuntime
+from ..invocation.scopes import _close_action, _raise_scope_failure
 from ..unit_of_work import UnitOfWorkManager
 from .errors import FastApiAdapterError
 

python_ddd_framework/fastapi/routing.py

@@ -2,7 +2,6 @@
 
 from __future__ import annotations
 
-import inspect
 import re
 from collections.abc import Mapping, Sequence
 from dataclasses import dataclass
@@ -17,11 +16,9 @@ from starlette.routing import BaseRoute, WebSocketRoute
 from ..application import Application
 from ..authorization.module import AuthorizationModule
 from ..diagnostics import SourceLocation
+from ..diagnostics.source import _source_file_line
 from ..modularity import ModuleKey
-from .application_services import (
-    _ROUTE_SOURCE_ATTRIBUTE,
-    _application_service_routers,
-)
+from .application_services import _application_service_routers
 from .contracts import (
     RouterCatalog,
     RouterRegistration,
@@ -33,6 +30,7 @@ from .health import _create_health_router
 from .http_router import HttpRouter
 from .manual_action import _ActionRoute
 from .realtime import websocket_connection
+from .service_endpoints import _ROUTE_SOURCE_ATTRIBUTE
 
 _PATH_PARAMETER = re.compile(r"\{[^{}:]+(?P<converter>:[^{}]+)?\}")
 
@@ -335,11 +333,7 @@ def _source_for_context(context: RouteContext, owner_label: str) -> SourceLocati
         if isinstance(declared_source, SourceLocation):
             return declared_source
         symbol = getattr(endpoint, "__qualname__", getattr(endpoint, "__name__", None))
-        try:
-            file_name = inspect.getsourcefile(endpoint)
-            _, line = inspect.getsourcelines(endpoint)
-        except (OSError, TypeError):
-            pass
+        file_name, line = _source_file_line(endpoint)
     return SourceLocation(owner=owner_label, file=file_name, line=line, symbol=symbol)
 
 

python_ddd_framework/fastapi/service_endpoints.py

@@ -0,0 +1,182 @@
+"""约定服务 endpoint 的请求执行、原生绑定与 ACTION 生命周期接入。"""
+
+from __future__ import annotations
+
+import inspect
+from collections.abc import Awaitable, Callable, Coroutine
+from dataclasses import dataclass
+from typing import Any, cast
+
+from dishka import AsyncContainer
+from dishka.integrations.fastapi import DishkaRoute, FromDishka
+from starlette.requests import Request
+from starlette.responses import Response
+
+from ..application_services.catalog import _CompiledApplicationService
+from ..application_services.dispatcher import _ApplicationServiceDispatcher
+from ..diagnostics import SourceLocation
+from ..invocation.methods import _CompiledMethod
+from .action import _HttpActionOwner, _request_parameter
+from .errors import FastApiAdapterError
+from .filters import _filters_for, _ordered_filters
+from .parameters import _HttpParameterValidator
+from .service_routes import _RouteMethod
+from .transfer import _manage_stream
+from .uploads import _prepare_upload
+
+_ROUTE_SOURCE_ATTRIBUTE = "__python_ddd_framework_fastapi_route_source__"
+_INVOCATION_IDENTITY_ATTRIBUTE = "__python_ddd_framework_fastapi_invocation_identity__"
+
+
+@dataclass(frozen=True, slots=True)
+class _ApplicationServiceRouteIdentity:
+    service: _CompiledApplicationService
+    method: _CompiledMethod
+
+
+class _ApplicationServiceRoute(DishkaRoute):
+    """在 native FastAPI binding 前建立 catalog-identity invocation boundary。"""
+
+    __slots__ = ("_compiled_method", "_compiled_service")
+
+    def __init__(
+        self,
+        path: str,
+        endpoint: Callable[..., Any],
+        **kwargs: Any,
+    ) -> None:
+        identity = getattr(endpoint, _INVOCATION_IDENTITY_ATTRIBUTE, None)
+        if not isinstance(identity, _ApplicationServiceRouteIdentity):
+            raise FastApiAdapterError("generated Application Service route lost its identity")
+        self._compiled_service = identity.service
+        self._compiled_method = identity.method
+        sources = getattr(endpoint, "__python_ddd_framework_http_sources__", None)
+        super().__init__(path, endpoint, **kwargs)
+        cast(Any, self.endpoint).__python_ddd_framework_http_sources__ = sources
+        # include_router 会以已注入 endpoint 重建 route；显式把 identity 传递给下一次构造。
+        setattr(self.endpoint, _INVOCATION_IDENTITY_ATTRIBUTE, identity)
+
+    def get_route_handler(
+        self,
+    ) -> Callable[[Request], Coroutine[Any, Any, Response]]:
+        native_handler = super().get_route_handler()
+        service = self._compiled_service
+        method = self._compiled_method
+
+        async def route_handler(request: Request) -> Response:
+            owner = await _HttpActionOwner.install(request)
+            container = cast(AsyncContainer, request.state.dishka_container)
+            dispatcher = await container.get(_ApplicationServiceDispatcher)
+
+            async def bind() -> Response:
+                await _prepare_upload(request, method.implementation_method, self)
+                return await native_handler(request)
+
+            try:
+                result = await dispatcher.invoke_http_request(
+                    service,
+                    method,
+                    bind,
+                    is_short_circuited=lambda: owner.short_circuited,
+                    defer_audit=owner.audits.append,
+                )
+                owner.response_ready = isinstance(result, Response)
+            except BaseException as error:
+                owner.failure = error
+                raise
+            if not isinstance(result, Response):
+                raise FastApiAdapterError(
+                    "an interceptor outside HTTP binding must return a native Response"
+                )
+            _manage_stream(request, result)
+            return result
+
+        return route_handler
+
+
+def _create_endpoint(
+    service: _CompiledApplicationService,
+    method: _CompiledMethod,
+    route_method: _RouteMethod,
+    source: SourceLocation,
+) -> Callable[..., Awaitable[object]]:
+    """保留 Protocol 原签名供 FastAPI binding，并注入同一 REQUEST dispatcher。"""
+
+    contract = service.registration.contract
+    method_name = method.name
+    parameter_names = {parameter.name for parameter in route_method.parameters}
+    dispatcher_parameter_name = "_python_ddd_framework_application_service_dispatcher"
+    while dispatcher_parameter_name in parameter_names:
+        dispatcher_parameter_name = f"_{dispatcher_parameter_name}"
+
+    declared_filters = _ordered_filters(
+        _filters_for(*reversed(service.registration.implementation.__mro__)),
+        _filters_for(method.implementation_method),
+    )
+    validator = _HttpParameterValidator(
+        route_method.signature.replace(parameters=route_method.parameters)
+    )
+
+    async def endpoint(**values: object) -> object:
+        dispatcher = cast(_ApplicationServiceDispatcher, values.pop(dispatcher_parameter_name))
+        request = cast(
+            Request,
+            values.pop(request_parameter_name)
+            if injected_request
+            else values[request_parameter_name],
+        )
+        owner: _HttpActionOwner = request.state.python_ddd_framework_action
+        await owner.activate(
+            method.descriptor.unit_of_work, method.name, service.registration.connection_name
+        )
+        filters = _ordered_filters(
+            getattr(request.app.state, "python_ddd_framework_filters", ()), declared_filters
+        )
+        snapshots = validator.capture(values)
+
+        async def invoke(actual: dict[str, object]) -> object:
+            if filters:
+                validator.validate_changes(actual, snapshots)
+            return await dispatcher.invoke_http(service, method, actual)
+
+        return await owner.invoke(
+            method.implementation_method,
+            values,
+            filters,
+            invoke,
+        )
+
+    request_parameter, injected_request = _request_parameter(route_method.parameters)
+    request_parameter_name = request_parameter.name
+    http_parameters = (
+        (*route_method.parameters, request_parameter)
+        if injected_request
+        else route_method.parameters
+    )
+
+    dispatcher_parameter = inspect.Parameter(
+        dispatcher_parameter_name,
+        kind=inspect.Parameter.KEYWORD_ONLY,
+        annotation=cast(Any, FromDishka)[_ApplicationServiceDispatcher],
+    )
+    # 动态 endpoint 的 signature/annotations 同时发布，兼容 FastAPI 与 postponed annotations。
+    signature = route_method.signature.replace(parameters=(*http_parameters, dispatcher_parameter))
+    endpoint_name = f"{contract.__name__}_{method_name}"
+    endpoint.__name__ = endpoint_name
+    endpoint.__qualname__ = endpoint_name
+    endpoint.__module__ = contract.__module__
+    cast(Any, endpoint).__signature__ = signature
+    endpoint.__annotations__ = {
+        **{
+            parameter.name: parameter.annotation
+            for parameter in (*http_parameters, dispatcher_parameter)
+        },
+        "return": signature.return_annotation,
+    }
+    setattr(endpoint, _ROUTE_SOURCE_ATTRIBUTE, source)
+    setattr(
+        endpoint,
+        _INVOCATION_IDENTITY_ATTRIBUTE,
+        _ApplicationServiceRouteIdentity(service, method),
+    )
+    return endpoint

python_ddd_framework/fastapi/service_routes.py

@@ -0,0 +1,237 @@
+"""约定服务的名称、路径和 HTTP 签名编译；不处理请求生命周期。"""
+
+from __future__ import annotations
+
+import inspect
+import re
+import types
+from dataclasses import dataclass, is_dataclass
+from datetime import date, datetime, time
+from decimal import Decimal
+from enum import Enum
+from typing import Annotated, Any, Literal, Union, get_args, get_origin
+from uuid import UUID
+
+from dishka.integrations.base import default_parse_dependency
+from fastapi.params import Body, Param, Path, Query
+from fastapi.params import Depends as DependsParameter
+from pydantic import BaseModel
+from pydantic.fields import FieldInfo
+
+from .contracts import ApplicationServiceRouteOverride
+from .errors import FastApiAdapterError
+from .http import _metadata
+
+_APPLICATION_SERVICE_SUFFIX = "ApplicationService"
+_PATH_PARAMETER = re.compile(r"\{(?P<name>[^{}:]+)(?::[^{}]+)?\}")
+_WORD_BOUNDARY_1 = re.compile(r"(.)([A-Z][a-z]+)")
+_WORD_BOUNDARY_2 = re.compile(r"([a-z0-9])([A-Z])")
+_VERB_PREFIXES: tuple[tuple[str, str], ...] = (
+    ("get_list", "GET"),
+    ("get_all", "GET"),
+    ("get", "GET"),
+    ("create", "POST"),
+    ("add", "POST"),
+    ("insert", "POST"),
+    ("post", "POST"),
+    ("update", "PUT"),
+    ("put", "PUT"),
+    ("delete", "DELETE"),
+    ("remove", "DELETE"),
+    ("patch", "PATCH"),
+)
+_SCALAR_TYPES = (str, int, float, bool, UUID, Decimal, date, datetime, time)
+
+
+@dataclass(frozen=True, slots=True)
+class _RouteMethod:
+    signature: inspect.Signature
+    parameters: tuple[inspect.Parameter, ...]
+
+
+def _inspect_route_method(
+    contract: type[object],
+    method_name: str,
+    signature: inspect.Signature,
+) -> _RouteMethod:
+    """在真实 FastAPI app 变更前解析并收窄动态 typing boundary。"""
+
+    # 共享方法编译已解释本 Application 的扩展 DTO；HTTP 不另建字段权威。
+    resolved_parameters = tuple(signature.parameters.values())
+    parameters = resolved_parameters[1:]
+    for parameter in parameters:
+        if parameter.kind in (
+            inspect.Parameter.POSITIONAL_ONLY,
+            inspect.Parameter.VAR_POSITIONAL,
+            inspect.Parameter.VAR_KEYWORD,
+        ):
+            raise FastApiAdapterError(
+                f"HTTP method {contract.__module__}.{contract.__qualname__}.{method_name} "
+                "cannot use positional-only, *args, or **kwargs parameters"
+            )
+        if parameter.annotation is inspect.Signature.empty:
+            raise FastApiAdapterError(
+                f"HTTP method {contract.__module__}.{contract.__qualname__}.{method_name} "
+                f"parameter {parameter.name!r} requires a type annotation"
+            )
+    if signature.return_annotation is inspect.Signature.empty:
+        raise FastApiAdapterError(
+            f"HTTP method {contract.__module__}.{contract.__qualname__}.{method_name} "
+            "requires a return type annotation"
+        )
+    return _RouteMethod(signature=signature, parameters=parameters)
+
+
+def _query_model_parameter(parameter: inspect.Parameter, verb: str) -> inspect.Parameter:
+    hint = parameter.annotation
+    metadata = get_args(hint)[1:] if get_origin(hint) is Annotated else ()
+    model = get_args(hint)[0] if metadata else hint
+    if (
+        verb == "GET"
+        and isinstance(model, type)
+        and issubclass(model, BaseModel)
+        and not any(
+            isinstance(value, (FieldInfo, DependsParameter))
+            for value in (*metadata, parameter.default)
+        )
+        and default_parse_dependency(parameter, hint) is None
+    ):
+        # 仅补原生 Query 元数据；字段展开、校验和 OpenAPI 均交给 FastAPI/Pydantic。
+        return parameter.replace(annotation=Annotated[hint, Query()])
+    return parameter
+
+
+def _uses_non_path_binding(parameter: inspect.Parameter) -> bool:
+    metadata = (
+        get_args(parameter.annotation)[1:] if get_origin(parameter.annotation) is Annotated else ()
+    )
+    return any(
+        isinstance(item, (Param, Body)) and not isinstance(item, Path)
+        for item in (*metadata, parameter.default)
+    )
+
+
+def _route_path(
+    service_path: str,
+    parameters: tuple[inspect.Parameter, ...],
+    override_path: str | None,
+    *,
+    contract: type[object],
+    method_name: str,
+) -> str:
+    # 只有唯一 required scalar id 才能无歧义进入 convention path；
+    # 其余情况保持 query 或要求 override。
+    id_candidates = tuple(
+        parameter
+        for parameter in parameters
+        if _is_required_path_parameter(parameter)
+        and (parameter.name == "id" or parameter.name.endswith("_id"))
+        and _is_scalar_annotation(parameter.annotation)
+        and not _uses_non_path_binding(parameter)
+    )
+    if override_path is None:
+        if len(id_candidates) > 1:
+            raise FastApiAdapterError(
+                f"HTTP method {contract.__module__}.{contract.__qualname__}.{method_name} "
+                "has ambiguous required id parameters and requires an explicit path override"
+            )
+        path = service_path
+        if len(id_candidates) == 1:
+            path = f"{path}/{{{id_candidates[0].name}}}"
+        # 只有集中定义的 CRUD 名称省略动作；审批/取消等领域动作保持其 contract 名称。
+        if method_name not in {prefix for prefix, _ in _VERB_PREFIXES}:
+            path = f"{path}/{method_name.replace('_', '-')}"
+        return path
+
+    if "?" in override_path or "#" in override_path or "//" in override_path:
+        raise FastApiAdapterError("route override path cannot contain query or fragment syntax")
+    rendered_parameters = tuple(
+        match.group("name") for match in _PATH_PARAMETER.finditer(override_path)
+    )
+    if override_path.count("{") != len(rendered_parameters) or override_path.count("}") != len(
+        rendered_parameters
+    ):
+        raise FastApiAdapterError(f"route override path {override_path!r} is malformed")
+    parameters_by_name = {parameter.name: parameter for parameter in parameters}
+    for name in rendered_parameters:
+        parameter = parameters_by_name.get(name)
+        if (
+            parameter is None
+            or not _is_required_path_parameter(parameter)
+            or not _is_scalar_annotation(parameter.annotation)
+            or _uses_non_path_binding(parameter)
+        ):
+            raise FastApiAdapterError(
+                f"route override path parameter {name!r} must name a required scalar "
+                f"Protocol parameter on {contract.__qualname__}.{method_name}"
+            )
+    if len(set(rendered_parameters)) != len(rendered_parameters):
+        raise FastApiAdapterError(f"route override path {override_path!r} repeats a path parameter")
+    return override_path
+
+
+def _is_required_path_parameter(parameter: inspect.Parameter) -> bool:
+    return parameter.default is inspect.Signature.empty or isinstance(parameter.default, Path)
+
+
+def _is_scalar_annotation(annotation: object) -> bool:
+    current = annotation
+    if get_origin(current) is Annotated:
+        current = get_args(current)[0]
+    origin = get_origin(current)
+    if origin in (types.UnionType, Union):
+        members = tuple(item for item in get_args(current) if item is not type(None))
+        return len(members) == 1 and _is_scalar_annotation(members[0])
+    if origin is Literal:
+        return all(isinstance(item, (str, int, float, bool)) for item in get_args(current))
+    if not isinstance(current, type):
+        return False
+    if issubclass(current, BaseModel) or is_dataclass(current):
+        return False
+    return issubclass(current, (*_SCALAR_TYPES, Enum))
+
+
+def _service_path(root_path: str, contract: type[object], segment: str | None = None) -> str:
+    service_name = contract.__name__
+    if service_name.endswith(_APPLICATION_SERVICE_SUFFIX):
+        service_name = service_name[: -len(_APPLICATION_SERVICE_SUFFIX)]
+    if not service_name:
+        raise FastApiAdapterError("application service contract has no routable name")
+    return "/" + "/".join(
+        part for part in (root_path, segment or _kebab_case(service_name)) if part
+    )
+
+
+def _operation_id(contract: type[object], method_name: str) -> str:
+    service_path = _service_path("", contract).rsplit("/", maxsplit=1)[-1]
+    return f"{service_path.replace('-', '_')}_{method_name}"
+
+
+def _kebab_case(value: str) -> str:
+    first_pass = _WORD_BOUNDARY_1.sub(r"\1-\2", value)
+    return _WORD_BOUNDARY_2.sub(r"\1-\2", first_pass).lower().replace("_", "-")
+
+
+def _conventional_verb(method_name: str) -> str:
+    for prefix, verb in _VERB_PREFIXES:
+        if method_name == prefix or method_name.startswith(f"{prefix}_"):
+            return verb
+    return "POST"
+
+
+def _route_projection(
+    method: object, override: ApplicationServiceRouteOverride | None
+) -> tuple[dict[str, Any], dict[str, str]]:
+    projection = dict(_metadata(method))
+    provenance = {key: "method" for key in projection}
+    if override is not None:
+        from dataclasses import fields
+
+        for field in fields(override):
+            if field.name in ("service", "method", "enabled"):
+                continue
+            value = getattr(override, field.name)
+            if value is not None:
+                projection[field.name] = value
+                provenance[field.name] = "module_override"
+    return projection, provenance

python_ddd_framework/fastapi/transfer.py

@@ -14,7 +14,7 @@ from starlette.requests import ClientDisconnect, Request
 from starlette.responses import StreamingResponse
 from starlette.types import Send
 
-from ..application_services.invocation import _InvocationRuntime
+from ..invocation.runtime import _InvocationRuntime
 
 
 async def _close_form(form: FormData) -> None: