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

python_ddd_framework/fastapi/request_context.py

@@ -103,10 +103,12 @@ class _RequestContextMiddleware:
         current_user = CurrentUser.anonymous()
         status_code = 500
         failure: BaseException | None = None
+        response_started = False
 
         async def send_with_context(message: Message) -> None:
-            nonlocal status_code
+            nonlocal status_code, response_started
             if message["type"] == "http.response.start":
+                response_started = True
                 status_code = cast(int, message["status"])
                 headers = list(message.get("headers", ()))
                 if not any(name.lower() == _CORRELATION_HEADER for name, _ in headers):
@@ -132,6 +134,9 @@ class _RequestContextMiddleware:
                     await self._app(scope, receive, send_with_context)
             except UnauthenticatedError as original_error:
                 failure = original_error
+                if response_started:
+                    # 响应头已发出时不能再构造第二个 401；传输 owner 负责终止流与清理。
+                    raise
                 status_code = 401
                 response = JSONResponse(
                     status_code=401,
@@ -171,7 +176,10 @@ class _RequestContextMiddleware:
         except NoFactoryError:
             # Host 收到认证凭据却没有验证 authority 时必须 fail closed。
             raise UnauthenticatedError from None
-        return await authenticator.authenticate_access_token(token)
+        user = await authenticator.authenticate_access_token(token)
+        # 保留原凭据供长连接重新认证；握手身份快照不能代替后续有效性检查。
+        Request(scope).state.python_ddd_framework_access_token = token
+        return user
 
     async def _write_audit(
         self,

python_ddd_framework/fastapi/routing.py

@@ -14,6 +14,7 @@ from fastapi.routing import APIRoute, APIWebSocketRoute, RouteContext, iter_rout
 from starlette.routing import BaseRoute, WebSocketRoute
 
 from ..application import Application
+from ..authorization.contracts import _authorization_requirement
 from ..authorization.module import AuthorizationModule
 from ..diagnostics import SourceLocation
 from ..diagnostics.source import _source_file_line
@@ -106,16 +107,22 @@ def _build_route_plan(
                         route.operation_id = cast(_OpenApiRouteView, context).unique_id
         for context in iter_route_contexts(router.routes):
             route = context.original_route
-            if isinstance(route, _ActionRoute):
+            requirement = (
+                route._definition.authorization
+                if isinstance(route, _ActionRoute)
+                else _authorization_requirement(object, route.endpoint)
+                if isinstance(route, APIWebSocketRoute)
+                else None
+            )
+            if requirement is not None:
+                # 声明错误在路由安装时失败，不推迟到首个 HTTP 请求或 WebSocket 握手。
                 unknown = tuple(
                     permission
-                    for permission in route._definition.authorization.permissions
+                    for permission in requirement.permissions
                     if permission not in application.modules.instance(AuthorizationModule).catalog
                 )
                 if unknown:
-                    raise FastApiAdapterError(
-                        f"HTTP action references unknown permissions: {unknown}"
-                    )
+                    raise FastApiAdapterError(f"endpoint references unknown permissions: {unknown}")
         routers.append((router, prefix))
         route_start = len(preview.routes)
         preview.include_router(router, prefix=prefix)
@@ -128,7 +135,7 @@ def _build_route_plan(
             )
         )
 
-    health_router = _create_health_router(application)
+    health_router = _create_health_router()
     health_route_start = len(preview.routes)
     preview.include_router(health_router)
     health_candidates = _route_candidates(

python_ddd_framework/fastapi/server.py

@@ -153,11 +153,18 @@ def run_host(
     reload: bool = False,
     project: Path | None = None,
     environment: str | None = None,
+    timeout_graceful_shutdown: int = 10,
 ) -> None:
     """通过原生 Uvicorn 运行 Host factory，并守卫单实例、reload 与实际退出。"""
     # 保留原生 Config/Server/ChangeReload，平台仅补进程输出边界，不接管 ASGI 生命周期。
     # reload 的父进程持锁直到所有子进程 join；子进程不重复占用主 Host 位置。
     # 此边界早于 factory 加载和运行期初始化，DB CLI/TestApplication 不经过这里。
+    if (
+        not isinstance(timeout_graceful_shutdown, int)
+        or isinstance(timeout_graceful_shutdown, bool)
+        or timeout_graceful_shutdown < 0
+    ):
+        raise ValueError("timeout_graceful_shutdown must be a non-negative integer")
     project = Path.cwd() if project is None else project
     environment = (
         environment if environment is not None else os.getenv(ENVIRONMENT_VARIABLE, "development")
@@ -172,6 +179,8 @@ def run_host(
             reload=reload,
             log_config=None,
             access_log=False,
+            # 超时交给 Uvicorn 请求取消；平台仍等待实际清理与生命周期排空完成。
+            timeout_graceful_shutdown=timeout_graceful_shutdown,
         )
         shutdown_requested = (
             multiprocessing.get_context("spawn").Event() if config.should_reload else None

python_ddd_framework/fastapi/service_endpoints.py

@@ -16,6 +16,7 @@ from ..application_services.catalog import _CompiledApplicationService
 from ..application_services.dispatcher import _ApplicationServiceDispatcher
 from ..diagnostics import SourceLocation
 from ..invocation.methods import _CompiledMethod
+from .access import _http_access
 from .action import _HttpActionOwner, _request_parameter
 from .errors import FastApiAdapterError
 from .filters import _filters_for, _ordered_filters
@@ -69,6 +70,10 @@ class _ApplicationServiceRoute(DishkaRoute):
             dispatcher = await container.get(_ApplicationServiceDispatcher)
 
             async def bind() -> Response:
+                # 约定式服务返回原生流 Response 时，也沿用同一持续授权与传输 owner。
+                request.state.python_ddd_framework_access = await _http_access(
+                    request, method.authorization
+                )
                 await _prepare_upload(request, method.implementation_method, self)
                 return await native_handler(request)
 

python_ddd_framework/fastapi/streaming.py

@@ -0,0 +1,95 @@
+"""生成器端点的原生 Depends 准备与发送交接；协议编码仍由 FastAPI 完成。"""
+
+from __future__ import annotations
+
+import inspect
+from collections.abc import AsyncIterable, AsyncIterator, Callable, Iterable
+from functools import update_wrapper
+from typing import Annotated, Any
+
+from dishka.integrations.fastapi import inject
+from fastapi import Depends
+from starlette.concurrency import iterate_in_threadpool
+from starlette.responses import Response
+
+from ..unit_of_work import UnitOfWorkManager
+from .action import _HttpActionOwner
+from .transfer import _manage_source
+
+
+class _PreparedStream:
+    """保存准备阶段移交的源；原生 producer 取得发送许可后才允许读取正文。"""
+
+    def __init__(self, owner: _HttpActionOwner, result: object) -> None:
+        self._owner = owner
+        self._result = result
+        _manage_source(owner.request, result)
+
+    async def iterate(self) -> AsyncIterator[object]:
+        owner = self._owner
+        # SSE 在函数退出栈完成前启动原生 producer；不预读首项，也不携带准备期事务。
+        await owner.prepared.wait()
+        if isinstance(self._result, Response):
+            return
+        await owner.sending.wait()
+        manager = await owner.container.get(UnitOfWorkManager)
+        initial_user, correlation = owner.request.state.python_ddd_framework_identity
+        access = getattr(owner.request.state, "python_ddd_framework_access", None)
+        if isinstance(self._result, AsyncIterable):
+            iterator = aiter(self._result)
+        elif isinstance(self._result, Iterable):
+            iterator = iterate_in_threadpool(self._result)
+        else:
+            raise TypeError("a streaming action must produce an iterable or Response")
+        while True:
+            # ContextVar token 不跨 yield；每次读取单独取得可信发送许可，
+            # 避免原生包装器延迟 finalization 时在不同 task 恢复准备上下文。
+            with (
+                manager._detached_work(),
+                owner.runtime.detached_execution(owner.container),
+            ):
+                # SSE producer 的复验也可能执行短 UoW，必须先交接该 task 的调用许可。
+                with owner.runtime.trusted_http_task(
+                    owner.container, initial_user, correlation, owner.request.method
+                ):
+                    user = await access.check() if access is not None else initial_user
+                # 检查可能刷新身份；正文的短调用使用检查后的快照，不能沿用准备期身份。
+                with owner.runtime.trusted_http_task(
+                    owner.container, user, correlation, owner.request.method
+                ):
+                    try:
+                        item = await anext(iterator)
+                    except StopAsyncIteration:
+                        return
+            yield item
+
+
+def _stream_endpoint(
+    prepare: Callable[..., Any], signature: inspect.Signature
+) -> Callable[..., Any]:
+    """准备交给原生 Depends，外层仍暴露生成器供 FastAPI 选择编码与传输路径。"""
+    # Depends 必须看到真实 coroutine，不能沿 __wrapped__ 把准备函数误当 yield dependency。
+    del prepare.__wrapped__  # type: ignore[attr-defined]
+    prepare.__signature__ = inspect.signature(prepare).replace(  # type: ignore[attr-defined]
+        return_annotation=_PreparedStream
+    )
+    prepare.__annotations__["return"] = _PreparedStream
+    dependency = inject(prepare)
+
+    async def stream(_prepared: _PreparedStream) -> AsyncIterator[object]:
+        async for item in _prepared.iterate():
+            yield item
+
+    update_wrapper(stream, prepare)
+    delattr(stream, "__wrapped__")
+    parameter = inspect.Parameter(
+        "_prepared",
+        inspect.Parameter.KEYWORD_ONLY,
+        annotation=Annotated[_PreparedStream, Depends(dependency)],
+    )
+    stream.__signature__ = signature.replace(parameters=(parameter,))  # type: ignore[attr-defined]
+    stream.__annotations__ = {
+        "_prepared": parameter.annotation,
+        "return": signature.return_annotation,
+    }
+    return stream

python_ddd_framework/fastapi/transfer.py

@@ -4,7 +4,7 @@ from __future__ import annotations
 
 import asyncio
 import inspect
-from collections.abc import Awaitable, Callable
+from collections.abc import AsyncIterable, AsyncIterator, Awaitable, Callable, Iterable
 from contextlib import AsyncExitStack
 
 from anyio import CancelScope
@@ -12,9 +12,10 @@ from starlette.concurrency import iterate_in_threadpool, run_in_threadpool
 from starlette.datastructures import FormData, UploadFile
 from starlette.requests import ClientDisconnect, Request
 from starlette.responses import StreamingResponse
-from starlette.types import Send
+from starlette.types import Message, Send
 
 from ..invocation.runtime import _InvocationRuntime
+from .access import _AccessRefresh
 
 
 async def _close_form(form: FormData) -> None:
@@ -28,6 +29,7 @@ async def _close_form(form: FormData) -> None:
 
 def _manage_stream(request: Request, response: object) -> None:
     if not isinstance(response, StreamingResponse):
+        _manage_source(request, response)
         return
     if isinstance(getattr(response.stream_response, "__self__", None), _StreamLifetime):
         return
@@ -51,10 +53,84 @@ def _manage_stream(request: Request, response: object) -> None:
         response.body_iterator = iterator
         close = getattr(iterator, "aclose", None)
     lifetime = _StreamLifetime(request, response.stream_response, close)
+    if lifetime._access is not None:
+        response.body_iterator = lifetime.read(response.body_iterator)
     response.stream_response = lifetime.send  # type: ignore[method-assign]
     request.scope["fastapi_middleware_astack"].push_async_callback(lifetime.close)
 
 
+def _manage_source(request: Request, source: object) -> None:
+    if not isinstance(source, (AsyncIterable, Iterable)):
+        return
+    sources: dict[int, _SourceLifetime] | None = getattr(
+        request.state, "python_ddd_framework_stream_sources", None
+    )
+    if sources is None:
+        sources = {}
+        request.state.python_ddd_framework_stream_sources = sources
+    if id(source) in sources:
+        return
+    close = getattr(source, "aclose", None)
+    sync_close = getattr(source, "close", None)
+    if close is None and sync_close is None:
+        return
+    lifetime = _SourceLifetime(request, source, close, sync_close)
+    sources[id(source)] = lifetime
+    # 源在准备依赖执行后、原生 SSE task group 建立前登记：退出时先 join producer，
+    # 再关源，最后才释放先登记的订阅依赖。不能把源留到订阅退出后的 middleware 栈。
+    request.scope["fastapi_inner_astack"].push_async_callback(lifetime.close)
+
+
+class _SourceLifetime:
+    """在迭代退出后强持有唯一关闭任务，等待源清理真正完成。"""
+
+    def __init__(
+        self,
+        request: Request,
+        source: object,
+        close: Callable[[], Awaitable[None]] | None,
+        sync_close: Callable[[], None] | None,
+    ) -> None:
+        self._request = request
+        self.source = source
+        self._close = close
+        self._sync_close = sync_close
+        self._task: asyncio.Task[None] | None = None
+
+    async def _run(self) -> None:
+        container = self._request.state.dishka_container
+        runtime = await container.get(_InvocationRuntime)
+        user, correlation = self._request.state.python_ddd_framework_identity
+        with (
+            CancelScope(shield=True),
+            runtime.trusted_http_task(container, user, correlation, self._request.method),
+        ):
+            if self._close is not None:
+                await self._close()
+            elif self._sync_close is not None:
+                await run_in_threadpool(self._sync_close)
+
+    async def close(self) -> None:
+        if self._task is None:
+            self._task = asyncio.create_task(self._run())
+        # 重复取消只记下待传播的异常，不打断同一个清理任务或提前释放 REQUEST。
+        primary: asyncio.CancelledError | None = None
+        with CancelScope(shield=True):
+            while not self._task.done():
+                try:
+                    await asyncio.wait((self._task,))
+                except asyncio.CancelledError as error:
+                    primary = primary or error
+            try:
+                self._task.result()
+            except BaseException as error:
+                if primary is not None:
+                    raise error from primary
+                raise
+        if primary is not None:
+            raise primary
+
+
 class _StreamLifetime:
     """producer 串行拥有迭代与关闭；请求监督它结束后才允许 REQUEST/stop 退出。"""
 
@@ -67,6 +143,12 @@ class _StreamLifetime:
         self._request = request
         self._send = send
         self._close = close
+        self._access: _AccessRefresh | None = getattr(
+            request.state, "python_ddd_framework_access", None
+        )
+        self._ready: asyncio.Event | None = getattr(
+            request.state, "python_ddd_framework_stream_ready", None
+        )
 
     async def close(self) -> None:
         # 先取走回调，避免 producer finally 与请求退出栈重复关闭同一资源。
@@ -76,6 +158,24 @@ class _StreamLifetime:
             with CancelScope(shield=True):
                 await close()
 
+    async def read(
+        self, source: AsyncIterable[str | bytes | memoryview]
+    ) -> AsyncIterator[str | bytes | memoryview]:
+        assert self._access is not None
+        container = self._request.state.dishka_container
+        runtime = await container.get(_InvocationRuntime)
+        _, correlation = self._request.state.python_ddd_framework_identity
+        iterator = aiter(source)
+        while True:
+            user = await self._access.check()
+            # 原生 Response 的正文短调用也使用最新快照；DI 已注入的不可变值不原地修改。
+            with runtime.trusted_http_task(container, user, correlation, self._request.method):
+                try:
+                    item = await anext(iterator)
+                except StopAsyncIteration:
+                    return
+            yield item
+
     async def send(self, send: Send) -> None:
         # scope 可在 producer 启动前取消，但只能由 producer 自己进入/退出。
         cancel_scope = CancelScope()
@@ -111,6 +211,7 @@ class _StreamLifetime:
             raise
 
     async def _run(self, send: Send, cancel_scope: CancelScope) -> None:
+        """在所属 task 的可信许可内完成首检、发送和关闭，并等待后台复验退出。"""
         container = self._request.state.dishka_container
         runtime = await container.get(_InvocationRuntime)
         user, correlation = self._request.state.python_ddd_framework_identity
@@ -120,9 +221,43 @@ class _StreamLifetime:
             CancelScope(shield=True),
             runtime.trusted_http_task(container, user, correlation, self._request.method),
         ):
+            watchdog: asyncio.Task[None] | None = None
+
+            async def protected_send(message: Message) -> None:
+                if self._access is not None:
+                    await self._access.check()
+                await send(message)
+                if message["type"] == "http.response.start" and self._ready is not None:
+                    self._ready.set()
+
             try:
                 with cancel_scope:
-                    await self._send(send)
+                    # ASGI <2.4 的 Starlette 会在子 task 调用 send；首次复验也必须在
+                    # 当前受监督入口取得许可后执行，且仍先于实际 response.start。
+                    if self._access is not None:
+                        await self._access.check(force=True)
+                        watchdog = asyncio.create_task(self._watch_access(cancel_scope))
+                    await self._send(protected_send)
+                if self._access is not None and self._access.failure is not None:
+                    raise self._access.failure
             finally:
+                if watchdog is not None:
+                    watchdog.cancel()
+                    await asyncio.gather(watchdog, return_exceptions=True)
                 # 发送/next 已退出才能串行关闭；生成器内部 finally 的 await 由其自己 shield。
                 await self.close()
+
+    async def _watch_access(self, cancel_scope: CancelScope) -> None:
+        assert self._access is not None
+        container = self._request.state.dishka_container
+        runtime = await container.get(_InvocationRuntime)
+        user, correlation = self._request.state.python_ddd_framework_identity
+        try:
+            # create_task 只复制上下文；复验的短调用仍须由传输 owner 明确交接许可。
+            with runtime.trusted_http_task(container, user, correlation, self._request.method):
+                while True:
+                    await asyncio.sleep(self._access.delay)
+                    await self._access.check()
+        except Exception as error:
+            self._request.state.python_ddd_framework_transfer_failure = error
+            cancel_scope.cancel()

python_ddd_framework/invocation/dispatcher.py

@@ -19,13 +19,8 @@ from ..application_services.errors import (
 )
 from ..auditing import ApplicationServiceAuditRecord, AuditSink
 from ..auditing.control import AuditingControl, AuditingOptions
-from ..authorization import AuthorizationOptions, PermissionChecker
+from ..authorization.checking import _check_authorization
 from ..authorization.contracts import _AuthorizationRequirement
-from ..authorization.errors import (
-    PermissionCheckerUnavailableError,
-    PermissionDeniedError,
-    UnauthenticatedError,
-)
 from ..invocation.arguments import _validate_arguments
 from ..invocation.execution import _InterceptorPipeline
 from ..invocation.interceptors import InterceptionStage
@@ -271,21 +266,4 @@ class _MethodDispatcher:
             )
 
     async def _authorize(self, requirement: _AuthorizationRequirement) -> None:
-        if requirement.allows_anonymous or not requirement.requires_authenticated_user:
-            return
-        # 所有受管理入口共用此阶段；放行不改变认证器或 CurrentUser。
-        options = await self._container.get(Options[AuthorizationOptions])
-        if options.value.always_allow:
-            return
-        current_user = self._runtime.current_user()
-        if not current_user.is_authenticated:
-            raise UnauthenticatedError
-        if not requirement.permissions:
-            return
-        try:
-            checker = await self._container.get(PermissionChecker)
-        except NoFactoryError:
-            raise PermissionCheckerUnavailableError from None
-        for permission in requirement.permissions:
-            if not await checker.is_granted(current_user, permission):
-                raise PermissionDeniedError(permission=str(permission))
+        await _check_authorization(self._container, self._runtime.current_user, requirement)

python_ddd_framework/invocation/scopes.py

@@ -11,9 +11,11 @@ from .contracts import ApplicationInvocationContext
 
 
 @asynccontextmanager
-async def _managed_request(parent: AsyncContainer) -> AsyncIterator[AsyncContainer]:
-    """排空入口自己创建的 REQUEST；不推断业务事务是否已经提交。"""
-    request = parent(scope=Scope.REQUEST)
+async def _managed_request(
+    parent: AsyncContainer, *, context: dict[type[object], object] | None = None
+) -> AsyncIterator[AsyncContainer]:
+    """显式传入原生 scope 输入并排空独立 REQUEST；不复制父容器缓存或推断事务结果。"""
+    request = parent(context=context, scope=Scope.REQUEST)
     primary: BaseException | None = None
     try:
         yield request

python_ddd_framework/observability/formatting.py

@@ -17,6 +17,7 @@ _DIAGNOSTIC_FIELDS = (
     "audit_contract",
     "audit_method",
     "audit_route_template",
+    "access_exception_type",
 )
 _HTTP_DIAGNOSTIC_LOGGERS = ("httpx", "httpcore", "uvicorn.access")
 

python_ddd_framework/sqlalchemy/migration.py

@@ -332,6 +332,11 @@ def _validate_revision_graph(
     # walk_revisions 强制 Alembic 在任何 engine 创建前加载并校验组合 graph/depends_on。
     script = ScriptDirectory.from_config(config)
     revisions = tuple(script.walk_revisions())
+    empty_model_sources = {
+        (item.owner, item.registration.branch_label, item.migration_path)
+        for item in models.for_connection(connection_name)
+        if not item.registration.metadata.tables
+    }
     for source in migration_sources:
         if source.extension is not None:
             _validate_extension_prerequisites(models, connection_name, source, script)
@@ -341,7 +346,18 @@ def _validate_revision_graph(
             if Path(revision.path).resolve().parent == source.migration_path
         )
         if not owned_revisions:
-            if (owner is not None and source.owner != owner) or allow_empty:
+            # 仅全局操作豁免纯 ORM 骨架的缺失 revision；不跳过图或数据库 heads 检查。
+            # 同一 owner 可贡献多个来源，判定必须限定当前 connection 与具体分支/目录。
+            if (
+                (owner is not None and source.owner != owner)
+                or allow_empty
+                or (
+                    owner is None
+                    and source.extension is None
+                    and (source.owner, source.branch_label, source.migration_path)
+                    in empty_model_sources
+                )
+            ):
                 continue
             raise SqlAlchemyModelRegistrationError(
                 owner=str(source.owner),

python_ddd_framework/unit_of_work/manager.py

@@ -3,8 +3,8 @@
 from __future__ import annotations
 
 import asyncio
-from collections.abc import AsyncIterator, Callable
-from contextlib import AsyncExitStack, asynccontextmanager
+from collections.abc import AsyncIterator, Callable, Iterator
+from contextlib import AsyncExitStack, asynccontextmanager, contextmanager
 from contextvars import ContextVar
 from functools import partial
 from typing import TYPE_CHECKING
@@ -61,6 +61,15 @@ class UnitOfWorkManager:
             raise RuntimeError("operation requires a transactional UnitOfWork")
         return work
 
+    @contextmanager
+    def _detached_work(self) -> Iterator[None]:
+        """受监督的阶段交接不继承旧事务；普通子任务仍使用 current 的 task guard。"""
+        token = self._ambient.set(None)
+        try:
+            yield
+        finally:
+            self._ambient.reset(token)
+
     def _resolve_options(
         self, connection_name: str | None, declaration: UnitOfWorkDeclaration, method_name: str
     ) -> _ResolvedUnitOfWorkOptions: