python-platform 0.1.1__py3-none-any.whl

python_platform/fastapi/__init__.py

@@ -0,0 +1,49 @@
+"""Optional FastAPI adapter public capability；不由 Kernel 根包重导出。"""
+
+from . import http as http
+from .adapter import FastApiAdapter
+from .contracts import (
+    ApplicationServiceRouteOverride,
+    RouterCatalog,
+    RouterRegistration,
+    WebSocketRouteRegistration,
+    contributes_routers,
+    exposes_application_services,
+)
+from .errors import FastApiAdapterError, RouteConflictError
+from .filters import ActionFilterContext, ServiceFilter, service_filter
+from .http import remote_service
+from .http_router import HttpRouter
+from .middleware import DiMiddleware
+from .realtime import (
+    FastApiRealtimeModule,
+    FastApiRealtimeOptions,
+    WebSocketConnection,
+    websocket_connection,
+)
+from .upload_limits import UploadLimits, upload_limits
+
+__all__ = (
+    "ActionFilterContext",
+    "ApplicationServiceRouteOverride",
+    "DiMiddleware",
+    "FastApiAdapter",
+    "FastApiAdapterError",
+    "FastApiRealtimeModule",
+    "FastApiRealtimeOptions",
+    "HttpRouter",
+    "RouteConflictError",
+    "RouterCatalog",
+    "RouterRegistration",
+    "ServiceFilter",
+    "UploadLimits",
+    "WebSocketConnection",
+    "WebSocketRouteRegistration",
+    "contributes_routers",
+    "exposes_application_services",
+    "http",
+    "remote_service",
+    "service_filter",
+    "upload_limits",
+    "websocket_connection",
+)

python_platform/fastapi/action.py

@@ -0,0 +1,175 @@
+"""原生 function exit stack 上的 HTTP 调用 owner；响应发送前完成并释放资源。"""
+
+from __future__ import annotations
+
+import asyncio
+import inspect
+from collections.abc import AsyncIterator, Awaitable, Callable
+from contextlib import AbstractAsyncContextManager, AsyncExitStack, asynccontextmanager
+from types import TracebackType
+from typing import Annotated, TypeVar, get_args, get_origin
+from uuid import uuid4
+
+from anyio import CancelScope
+from dishka import AsyncContainer
+from starlette.requests import Request
+
+from ..application_services.contracts import _DEFAULT_CONNECTION_NAME
+from ..application_services.invocation import _InvocationRuntime, _InvocationState, _managed_action
+from ..invocation import ApplicationInvocationContext
+from ..unit_of_work import UnitOfWork, UnitOfWorkManager
+from ..unit_of_work.options import UnitOfWorkDeclaration
+from .errors import FastApiAdapterError
+from .filters import ActionFilterContext, ServiceFilter, _run_filters
+from .transfer import _manage_stream
+
+_T = TypeVar("_T")
+
+
+class _FunctionDependencyStack(AsyncExitStack):
+    def __init__(self, owner: _HttpActionOwner) -> None:
+        super().__init__()
+        self._owner = owner
+
+    async def enter_async_context(self, cm: AbstractAsyncContextManager[_T, bool | None]) -> _T:
+        @asynccontextmanager
+        async def observe() -> AsyncIterator[_T]:
+            try:
+                async with cm as value:
+                    yield value
+            except BaseException as error:
+                # 保存每个依赖退出失败的事实，不能让更外层依赖吞异常后误提交。
+                self._owner.failure = error
+                raise
+
+        return await super().enter_async_context(observe())
+
+
+class _HttpActionOwner:
+    def __init__(
+        self, request: Request, container: AsyncContainer, runtime: _InvocationRuntime
+    ) -> None:
+        self.request = request
+        self.container = container
+        self.runtime = runtime
+        self.stack = AsyncExitStack()
+        self.work: UnitOfWork | None = None
+        self.action: AsyncContainer | None = None
+        self.response_ready = False
+        self.failure: BaseException | None = None
+        self.short_circuited = False
+        self.audits: list[Callable[[BaseException | None], Awaitable[None]]] = []
+
+    @classmethod
+    async def install(cls, request: Request) -> _HttpActionOwner:
+        # 唯一版本耦合点：原生函数栈尚未登记本次 Depends，因此 owner 最后退出。
+        native_stack = request.scope.get("fastapi_function_astack")
+        if not isinstance(native_stack, AsyncExitStack):
+            raise FastApiAdapterError("native FastAPI function exit stack is unavailable")
+        container = request.state.dishka_container
+        owner = cls(request, container, await container.get(_InvocationRuntime))
+        native_stack.callback(request.scope.__setitem__, "fastapi_function_astack", native_stack)
+        native_stack.push_async_exit(owner.finish)
+        observed = await native_stack.enter_async_context(_FunctionDependencyStack(owner))
+        request.scope["fastapi_function_astack"] = observed
+        request.state.python_platform_action = owner
+        return owner
+
+    async def activate(
+        self,
+        declaration: UnitOfWorkDeclaration,
+        method_name: str,
+        connection_name: str = _DEFAULT_CONNECTION_NAME,
+    ) -> AsyncContainer:
+        if self.action is not None:
+            raise FastApiAdapterError("HTTP action was already activated")
+        context = ApplicationInvocationContext(
+            application_id=self.runtime.application_id,
+            invocation_id=uuid4(),
+            parent_invocation_id=None,
+            connection_name=connection_name,
+        )
+        action = await self.stack.enter_async_context(
+            _managed_action(
+                self.container,
+                context,
+                committed=lambda: self.work is not None and self.work.committed,
+            )
+        )
+        self.action = action
+        task = asyncio.current_task()
+        assert task is not None
+        token = self.runtime.bind(_InvocationState(context, task, action))
+        self.stack.callback(self.runtime.reset, token)
+        manager = await action.get(UnitOfWorkManager)
+        if declaration.disabled:
+            manager._check_current(connection_name)
+        else:
+            self.work = await self.stack.enter_async_context(
+                manager._begin(manager._resolve_options(connection_name, declaration, method_name))
+            )
+        return action
+
+    async def invoke(
+        self,
+        endpoint: object,
+        values: dict[str, object],
+        filters: tuple[ServiceFilter, ...],
+        callback: Callable[[dict[str, object]], Awaitable[object]],
+    ) -> object:
+        assert self.action is not None
+        executed = False
+
+        async def target() -> object:
+            nonlocal executed
+            executed = True
+            result = await callback(values)
+            # 接受业务移交后立即登记，后置 Filter 或响应准备失败也不能遗失 iterator。
+            _manage_stream(self.request, result)
+            return result
+
+        result = await _run_filters(
+            filters, self.action, ActionFilterContext(self.request, endpoint, values), target
+        )
+        self.short_circuited = not executed
+        return result
+
+    async def finish(
+        self,
+        exc_type: type[BaseException] | None,
+        error: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> bool:
+        primary = error or self.failure
+        try:
+            try:
+                if primary is None and self.response_ready and self.work is not None:
+                    await self.work.complete()
+            except BaseException as failure:
+                primary = failure
+            with CancelScope(shield=True):
+                await self.stack.__aexit__(type(primary) if primary else None, primary, traceback)
+        except BaseException as failure:
+            primary = failure
+        finally:
+            with CancelScope(shield=True):
+                for audit in self.audits:
+                    await audit(primary)
+            self.request.state.python_platform_action = None
+        if primary is not None:
+            raise primary
+        return False
+
+
+def _request_parameter(parameters: tuple[inspect.Parameter, ...]) -> tuple[inspect.Parameter, bool]:
+    for parameter in parameters:
+        annotation = parameter.annotation
+        base = get_args(annotation)[0] if get_origin(annotation) is Annotated else annotation
+        # Request 注入只接受具体类型，不将参数化注解当作可注入的 Request 子类。
+        if get_origin(base) is None and isinstance(base, type) and issubclass(base, Request):
+            return parameter, False
+    name = "_python_platform_request"
+    names = {parameter.name for parameter in parameters}
+    while name in names:
+        name = "_" + name
+    return inspect.Parameter(name, inspect.Parameter.KEYWORD_ONLY, annotation=Request), True

python_platform/fastapi/adapter.py

@@ -0,0 +1,381 @@
+"""Application lifecycle、Dishka FastAPI integration 与 HTTP surface 的单次装配。"""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import AsyncIterator, Iterator, Sequence
+from contextlib import asynccontextmanager, contextmanager
+from typing import Any, cast, get_args
+
+from dishka.exceptions import NoFactoryError
+from fastapi import FastAPI
+from fastapi.exception_handlers import request_validation_exception_handler
+from fastapi.exceptions import RequestValidationError
+from pydantic_core.core_schema import ErrorType
+from starlette.middleware import Middleware
+from starlette.requests import Request
+from starlette.responses import JSONResponse
+
+from ..application import Application
+from ..application_services import ApplicationServiceValidationError
+from ..authorization import PermissionDeniedError, UnauthenticatedError
+from ..errors import BusinessError, FrameworkError, ResourceConflictError, ResourceNotFoundError
+from ..lifecycle import ApplicationState
+from .contracts import RouterCatalog
+from .errors import FastApiAdapterError
+from .filters import ServiceFilter, _validate_filters
+from .middleware import DiMiddleware, _compile_middlewares
+from .realtime.runtime import _FastApiRealtimeRuntime
+from .request_context import (
+    _RequestContextMiddleware,
+    _RequestScopeMiddleware,
+    _RequestTaskMiddleware,
+)
+from .route_integrity import RouteFingerprint, _route_fingerprint
+from .routing import (
+    _build_route_plan,
+    _RouteInstallationPlan,
+    _verify_native_openapi,
+)
+from .tracing import _install_tracing, _tracing_rollback
+from .upload_limits import UploadLimits
+
+_LOGGER = logging.getLogger(__name__)
+_INSTALLATION_MARKER = "_python_platform_fastapi_installed"
+_DISHKA_CONTAINER_BRIDGE = "dishka_container"
+_SAFE_REQUEST_LOCATION_ROOTS = frozenset({"body", "cookie", "header", "path", "query"})
+_TRUSTED_VALIDATION_ERROR_TYPES = frozenset(get_args(ErrorType))
+
+
+class FastApiAdapter:
+    """把一个 composed Application 安装到一个 FastAPI instance。"""
+
+    __slots__ = (
+        "_application",
+        "_catalog",
+        "_filters",
+        "_installed_app",
+        "_installed_middleware",
+        "_installed_stack",
+        "_middleware",
+        "_route_fingerprint",
+        "_upload_limits",
+    )
+
+    def __init__(
+        self,
+        application: Application,
+        *,
+        middleware: Sequence[Middleware | DiMiddleware] = (),
+        filters: Sequence[ServiceFilter] = (),
+        upload_limits: UploadLimits | None = None,
+    ) -> None:
+        if not isinstance(application, Application):
+            raise TypeError("application must be python_platform.Application")
+        self._filters = tuple(filters)
+        if upload_limits is not None and not isinstance(upload_limits, UploadLimits):
+            raise TypeError("upload_limits must be UploadLimits")
+        self._upload_limits = UploadLimits() if upload_limits is None else upload_limits
+        self._middleware = tuple(middleware)
+        self._installed_middleware: tuple[Middleware, ...] = ()
+        self._installed_stack: _RequestScopeMiddleware | None = None
+        self._application = application
+        self._catalog: RouterCatalog | None = None
+        self._installed_app: FastAPI | None = None
+        self._route_fingerprint: RouteFingerprint | None = None
+
+    def install(self, app: FastAPI) -> RouterCatalog:
+        self._validate_install_target(app)
+        middlewares = _compile_middlewares(
+            (*self._middleware, *app.user_middleware),
+            self._application._container_for_integration(),
+        )
+        _validate_filters(self._filters, self._application._container_for_integration())
+        plan = _build_route_plan(app, self._application)
+
+        with _installation_state(app), _tracing_rollback(app):
+            stack = self._apply_installation(app, plan, middlewares)
+            fingerprint = _route_fingerprint(app.routes)
+            setattr(app.state, _INSTALLATION_MARKER, str(self._application.id))
+
+        # 安装状态仅在所有原生构造与校验成功后发布；失败可以修正配置后重试。
+        self._installed_stack = stack
+        self._installed_middleware = tuple(app.user_middleware)
+        self._catalog = plan.catalog
+        self._installed_app = app
+        self._route_fingerprint = fingerprint
+        return plan.catalog
+
+    def _apply_installation(
+        self, app: FastAPI, plan: _RouteInstallationPlan, middlewares: tuple[Middleware, ...]
+    ) -> _RequestScopeMiddleware:
+        for router in plan.routers:
+            app.include_router(router)
+        app.include_router(plan.health_router)
+        if (
+            BusinessError not in app.exception_handlers
+            and FrameworkError not in app.exception_handlers
+        ):
+            app.add_exception_handler(BusinessError, _business_error_handler)
+        if (
+            ApplicationServiceValidationError not in app.exception_handlers
+            and FrameworkError not in app.exception_handlers
+        ):
+            app.add_exception_handler(
+                ApplicationServiceValidationError,
+                _application_service_validation_handler,
+            )
+        if (
+            UnauthenticatedError not in app.exception_handlers
+            and FrameworkError not in app.exception_handlers
+        ):
+            app.add_exception_handler(UnauthenticatedError, _unauthenticated_handler)
+        if (
+            PermissionDeniedError not in app.exception_handlers
+            and FrameworkError not in app.exception_handlers
+        ):
+            app.add_exception_handler(PermissionDeniedError, _permission_denied_handler)
+        if (
+            ResourceConflictError not in app.exception_handlers
+            and FrameworkError not in app.exception_handlers
+        ):
+            app.add_exception_handler(ResourceConflictError, _resource_conflict_handler)
+        if (
+            ResourceNotFoundError not in app.exception_handlers
+            and FrameworkError not in app.exception_handlers
+        ):
+            app.add_exception_handler(ResourceNotFoundError, _resource_not_found_handler)
+        if FrameworkError not in app.exception_handlers:
+            app.add_exception_handler(FrameworkError, _framework_error_handler)
+        request_validation_handler = app.exception_handlers.get(RequestValidationError)
+        if request_validation_handler in (None, request_validation_exception_handler):
+            app.add_exception_handler(RequestValidationError, _request_validation_handler)
+
+        app.state.python_platform_filters = self._filters
+        app.state.python_platform_upload_limits = self._upload_limits
+        app.state.dishka_container = self._application._container_for_integration()
+        app.user_middleware = [*middlewares, Middleware(_RequestTaskMiddleware)]
+        app.add_middleware(_RequestContextMiddleware, application=self._application)
+        _install_tracing(self._application, app)
+        app.openapi_schema = None
+        _verify_native_openapi(app, plan.schema_candidates)
+
+        # lease/REQUEST 包住原生 ServerErrorMiddleware；未处理异常的 500 发送也在 drain 内。
+        # 直接组装原生栈，不复制错误处理或替换全局 routing 函数。
+        stack = _RequestScopeMiddleware(app.build_middleware_stack(), application=self._application)
+        app.middleware_stack = stack
+        return stack
+
+    @asynccontextmanager
+    async def lifespan(self, app: FastAPI) -> AsyncIterator[None]:
+        try:
+            self._validate_start_target(app)
+        except BaseException:
+            if self._installed_app is app:
+                try:
+                    if self._application.state is ApplicationState.COMPOSED:
+                        await self._application.stop()
+                finally:
+                    self._clear_container_bridge(app)
+            raise
+        try:
+            await self._application.start()
+        except BaseException:
+            self._clear_container_bridge(app)
+            raise
+
+        try:
+            yield
+        finally:
+            try:
+                await self._shutdown_realtime()
+            finally:
+                try:
+                    await self._application.stop()
+                finally:
+                    # Container 的 close 始终属于 Application；这里只撤销 Web 引用。
+                    self._clear_container_bridge(app)
+
+    def _validate_install_target(self, app: FastAPI) -> None:
+        if not isinstance(app, FastAPI):
+            raise TypeError("app must be fastapi.FastAPI")
+        if self._installed_app is not None:
+            raise FastApiAdapterError("one adapter can only be installed once")
+        if hasattr(app.state, _INSTALLATION_MARKER):
+            raise FastApiAdapterError("FastAPI instance already has a Python Platform adapter")
+        if hasattr(app.state, _DISHKA_CONTAINER_BRIDGE):
+            raise FastApiAdapterError("FastAPI instance already has a Dishka container bridge")
+        if app.middleware_stack is not None:
+            raise FastApiAdapterError("FastAPI middleware stack was already built before install")
+        if self._application.state is not ApplicationState.COMPOSED:
+            raise FastApiAdapterError(
+                f"install requires composed Application, got {self._application.state.value}"
+            )
+
+    def _validate_start_target(self, app: FastAPI) -> None:
+        if self._installed_app is not app:
+            raise FastApiAdapterError(
+                "lifespan app is not this adapter's installed FastAPI instance"
+            )
+        if getattr(app.state, _INSTALLATION_MARKER, None) != str(self._application.id):
+            raise FastApiAdapterError("FastAPI installation marker changed before startup")
+        if app.state.python_platform_filters != self._filters:
+            raise FastApiAdapterError("HTTP filters changed after adapter installation")
+        if tuple(app.user_middleware) != self._installed_middleware:
+            raise FastApiAdapterError("FastAPI middleware changed after adapter installation")
+        if app.middleware_stack is not self._installed_stack:
+            raise FastApiAdapterError("FastAPI middleware stack changed after adapter installation")
+        expected_fingerprint = self._route_fingerprint
+        if expected_fingerprint is None or _route_fingerprint(app.routes) != expected_fingerprint:
+            raise FastApiAdapterError("FastAPI routes changed after adapter installation")
+        try:
+            container = self._application._container_for_integration()
+        except RuntimeError as original_error:
+            raise FastApiAdapterError("Application container is unavailable before startup") from (
+                original_error
+            )
+        if getattr(app.state, _DISHKA_CONTAINER_BRIDGE, None) is not container:
+            raise FastApiAdapterError("Dishka container bridge changed before startup")
+
+    @staticmethod
+    def _clear_container_bridge(app: FastAPI) -> None:
+        if hasattr(app.state, _DISHKA_CONTAINER_BRIDGE):
+            delattr(app.state, _DISHKA_CONTAINER_BRIDGE)
+
+    async def _shutdown_realtime(self) -> None:
+        try:
+            container = self._application._container_for_integration()
+        except RuntimeError:
+            return
+        try:
+            runtime = await container.get(_FastApiRealtimeRuntime)
+        except NoFactoryError:
+            return
+        await runtime.shutdown()
+
+
+@contextmanager
+def _installation_state(app: FastAPI) -> Iterator[None]:
+    # 原生 include_router 还修改 lifespan、回调和路由缓存；从实例状态发现这些字段，
+    # 保留既有 list/dict 身份，不维护随 FastAPI 版本漂移的字段第二清单。
+    namespaces = (vars(app), vars(app.router), vars(app.state))
+    snapshots = [(namespace, dict(namespace)) for namespace in namespaces]
+    collections: list[tuple[Any, Any]] = [
+        (value, value.copy())
+        for _, snapshot in snapshots
+        for value in snapshot.values()
+        if type(value) in (dict, list)
+    ]
+    try:
+        yield
+    except BaseException:
+        for value, original in collections:
+            if isinstance(value, list):
+                value[:] = original
+            else:
+                value.clear()
+                value.update(original)
+        for namespace, snapshot in snapshots:
+            namespace.clear()
+            namespace.update(snapshot)
+        raise
+
+
+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],
+            }
+        },
+    )
+
+
+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"})