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

python_ddd_framework/fastapi/__init__.py

@@ -1,6 +1,7 @@
 """Optional FastAPI adapter public capability；不由 Kernel 根包重导出。"""
 
 from . import http as http
+from .access_options import FastApiAccessOptions
 from .adapter import FastApiAdapter
 from .contracts import (
     ApplicationServiceRouteOverride,
@@ -28,6 +29,7 @@ __all__ = (
     "ActionFilterContext",
     "ApplicationServiceRouteOverride",
     "DiMiddleware",
+    "FastApiAccessOptions",
     "FastApiAdapter",
     "FastApiAdapterError",
     "FastApiModule",

python_ddd_framework/fastapi/access.py

@@ -0,0 +1,127 @@
+"""持续访问的身份快照与串行复验；连接、取消和发送仍由各传输 owner 管理。"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+
+from dishka import AsyncContainer, Scope
+from starlette.requests import Request
+
+from ..authorization import AccessTokenAuthenticator, CurrentUser, UnauthenticatedError
+from ..authorization.checking import _check_authorization
+from ..authorization.contracts import _AuthorizationRequirement
+from ..invocation.runtime import _InvocationRuntime
+from ..invocation.scopes import _managed_request
+from ..options import Options
+from .access_options import FastApiAccessOptions
+
+_LOGGER = logging.getLogger(__name__)
+
+
+class _AccessRefresh:
+    """单连接复验状态：串行检查并锁定失败事实，传输的停止与释放由调用方拥有。"""
+
+    def __init__(
+        self,
+        parent: AsyncContainer,
+        runtime: _InvocationRuntime,
+        user: CurrentUser,
+        token: str | None,
+        correlation_id: str,
+        requirement: _AuthorizationRequirement,
+        interval: int,
+        *,
+        context: dict[type[object], object] | None = None,
+    ) -> None:
+        self._parent = parent
+        # 仅保存传输 owner 提供的原生 scope 输入，不继承长 REQUEST 的服务缓存。
+        self._context = context
+        self._runtime = runtime
+        self._token = token
+        self._correlation_id = correlation_id
+        self._requirement = requirement
+        self._interval = interval
+        self._lock = asyncio.Lock()
+        self._deadline = 0.0
+        self.user = user
+        self.failure: Exception | None = None
+
+    @property
+    def delay(self) -> float:
+        return max(0.0, self._deadline - asyncio.get_running_loop().time())
+
+    async def check(self, *, force: bool = False) -> CurrentUser:
+        """到期发送与后台检查共用一把锁；失败后所有调用观察同一终态。"""
+        async with self._lock:
+            if self.failure is not None:
+                raise self.failure
+            if not force and self.delay > 0:
+                return self.user
+            try:
+                user = await self._check()
+            except Exception as error:
+                # 失败事实先于传输关闭发布，发送侧不会在慢客户端恢复后继续提交旧数据。
+                self.failure = error
+                _LOGGER.warning(
+                    "continuous access check failed",
+                    extra={"access_exception_type": type(error).__name__},
+                )
+                raise
+            # 从成功完成时开始计时；检查与 scope 清理耗时不占用下一周期。
+            self.user = user
+            self._deadline = asyncio.get_running_loop().time() + self._interval
+            return user
+
+    async def _check(self) -> CurrentUser:
+        """重建短 scope 内的认证/授权依赖，身份绑定只覆盖本次权限检查。"""
+        # 每周期新 REQUEST；不复用长连接容器内缓存的 CurrentUser/PermissionChecker。
+        async with _managed_request(self._parent, context=self._context) as container:
+            with self._runtime.detached_execution(container):
+                user = CurrentUser.anonymous()
+                if self._token is not None:
+                    with self._runtime.authenticating():
+                        authenticator = await container.get(AccessTokenAuthenticator)
+                        user = await authenticator.authenticate_access_token(self._token)
+                    if not user.is_authenticated or (
+                        self.user.is_authenticated
+                        and (
+                            user.user_id != self.user.user_id
+                            or user.session_id != self.user.session_id
+                        )
+                    ):
+                        raise UnauthenticatedError
+                caller = self._runtime.bind_caller(user, self._correlation_id)
+                try:
+                    await _check_authorization(
+                        container, self._runtime.current_user, self._requirement
+                    )
+                finally:
+                    self._runtime.reset_caller(caller)
+                return user
+
+
+async def _http_access(
+    request: Request, requirement: _AuthorizationRequirement
+) -> _AccessRefresh | None:
+    """HTTP owner 提供请求上下文；每轮复验从 APP 新建独立 REQUEST。"""
+    if requirement.allows_anonymous or not requirement.requires_authenticated_user:
+        return None
+    container: AsyncContainer = request.state.dishka_container
+    parent = container
+    while parent.scope is not Scope.APP:
+        assert parent.parent_container is not None
+        parent = parent.parent_container
+    user, correlation = request.state.python_ddd_framework_identity
+    options = await container.get(Options[FastApiAccessOptions])
+    return _AccessRefresh(
+        parent,
+        await container.get(_InvocationRuntime),
+        user,
+        getattr(request.state, "python_ddd_framework_access_token", None),
+        correlation,
+        requirement,
+        options.value.authentication_refresh_seconds,
+        # 原生请求对象是 scope 输入，不共享长 REQUEST 已缓存的认证器或检查器。
+        context={Request: request},
+    )

python_ddd_framework/fastapi/access_options.py

@@ -0,0 +1,13 @@
+"""HTTP 与 WebSocket 共享的持续访问检查配置。"""
+
+from pydantic import ConfigDict, Field
+
+from ..options import BaseOptions
+
+
+class FastApiAccessOptions(BaseOptions):
+    """由 FastApiModule 声明、Host 配置的 HTTP/WebSocket 共用复验周期。"""
+
+    model_config = ConfigDict(extra="forbid")
+
+    authentication_refresh_seconds: int = Field(default=60, ge=1)

python_ddd_framework/fastapi/action.py

@@ -59,6 +59,11 @@ class _HttpActionOwner:
         self.failure: BaseException | None = None
         self.short_circuited = False
         self.audits: list[Callable[[BaseException | None], Awaitable[None]]] = []
+        # SSE 可提前创建生产任务；准备完成与获准发送是两道屏障，均通过后才读取源。
+        self.prepared = asyncio.Event()
+        self.sending = asyncio.Event()
+        request.state.python_ddd_framework_stream_ready = self.sending
+        self.stream_result: object = None
 
     @classmethod
     async def install(cls, request: Request) -> _HttpActionOwner:
@@ -158,6 +163,7 @@ class _HttpActionOwner:
             self.request.state.python_ddd_framework_action = None
         if primary is not None:
             raise primary
+        self.prepared.set()
         return False
 
 

python_ddd_framework/fastapi/adapter.py

@@ -15,7 +15,13 @@ from starlette.middleware import Middleware
 from ..application import Application
 from ..application_services import ApplicationServiceValidationError
 from ..authorization import PermissionDeniedError, UnauthenticatedError
-from ..errors import BusinessError, FrameworkError, ResourceConflictError, ResourceNotFoundError
+from ..errors import (
+    BusinessError,
+    FrameworkError,
+    InvalidApplicationStateError,
+    ResourceConflictError,
+    ResourceNotFoundError,
+)
 from ..lifecycle import ApplicationState
 from .contracts import RouterCatalog
 from .error_handlers import (
@@ -30,6 +36,7 @@ from .error_handlers import (
 )
 from .errors import FastApiAdapterError
 from .filters import ServiceFilter, _validate_filters
+from .health import _APPLICATION_STATE_ATTRIBUTE
 from .middleware import DiMiddleware, _compile_middlewares
 from .module import FastApiModule
 from .realtime.runtime import _FastApiRealtimeRuntime
@@ -174,6 +181,7 @@ class FastApiAdapter:
         app.state.python_ddd_framework_filters = self._filters
         app.state.python_ddd_framework_upload_limits = self._upload_limits
         app.state.dishka_container = self._application._container_for_integration()
+        setattr(app.state, _APPLICATION_STATE_ATTRIBUTE, self._application)
         app.user_middleware = [*middlewares, Middleware(_RequestTaskMiddleware)]
         app.add_middleware(_RequestContextMiddleware, application=self._application)
         _install_tracing(self._application, app)
@@ -191,17 +199,19 @@ class FastApiAdapter:
         try:
             self._validate_start_target(app)
         except BaseException:
-            if self._installed_app is app:
+            if self._installed_app is app and self._application.state is ApplicationState.COMPOSED:
                 try:
-                    if self._application.state is ApplicationState.COMPOSED:
-                        await self._application.stop()
+                    await self._application.stop()
                 finally:
-                    self._clear_container_bridge(app)
+                    self._clear_application_bridges(app)
             raise
         try:
             await self._application.start()
+        except InvalidApplicationStateError:
+            # Core 在取得转换 ownership 前拒绝重复/并发进入；不能撤销有效 lifespan 的桥。
+            raise
         except BaseException:
-            self._clear_container_bridge(app)
+            self._clear_application_bridges(app)
             raise
 
         try:
@@ -214,7 +224,7 @@ class FastApiAdapter:
                     await self._application.stop()
                 finally:
                     # Container 的 close 始终属于 Application；这里只撤销 Web 引用。
-                    self._clear_container_bridge(app)
+                    self._clear_application_bridges(app)
 
     def _validate_install_target(self, app: FastAPI) -> None:
         if not isinstance(app, FastAPI):
@@ -225,6 +235,8 @@ class FastApiAdapter:
             raise FastApiAdapterError("FastAPI instance already has a Python DDD Framework adapter")
         if hasattr(app.state, _DISHKA_CONTAINER_BRIDGE):
             raise FastApiAdapterError("FastAPI instance already has a Dishka container bridge")
+        if hasattr(app.state, _APPLICATION_STATE_ATTRIBUTE):
+            raise FastApiAdapterError("FastAPI instance already has an Application binding")
         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:
@@ -239,6 +251,8 @@ class FastApiAdapter:
             )
         if getattr(app.state, _INSTALLATION_MARKER, None) != str(self._application.id):
             raise FastApiAdapterError("FastAPI installation marker changed before startup")
+        if getattr(app.state, _APPLICATION_STATE_ATTRIBUTE, None) is not self._application:
+            raise FastApiAdapterError("FastAPI Application binding changed before startup")
         if app.state.python_ddd_framework_filters != self._filters:
             raise FastApiAdapterError("HTTP filters changed after adapter installation")
         if tuple(app.user_middleware) != self._installed_middleware:
@@ -258,9 +272,10 @@ class FastApiAdapter:
             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)
+    def _clear_application_bridges(app: FastAPI) -> None:
+        for attribute in (_DISHKA_CONTAINER_BRIDGE, _APPLICATION_STATE_ATTRIBUTE):
+            if hasattr(app.state, attribute):
+                delattr(app.state, attribute)
 
     async def _shutdown_realtime(self) -> None:
         try:

python_ddd_framework/fastapi/health.py

@@ -2,10 +2,13 @@
 
 from __future__ import annotations
 
-from fastapi import APIRouter
+from fastapi import APIRouter, Request
 from starlette.responses import JSONResponse
 
 from ..application import Application
+from .errors import FastApiAdapterError
+
+_APPLICATION_STATE_ATTRIBUTE = "_python_ddd_framework_application"
 
 HEALTH_LIVE_PATH = "/health/live"
 HEALTH_READY_PATH = "/health/ready"
@@ -13,18 +16,24 @@ 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(request: Request) -> JSONResponse:
+    # FastAPI 可长期缓存 callable；应用引用只在当前请求期间从实例状态取得。
+    application = getattr(request.app.state, _APPLICATION_STATE_ATTRIBUTE, None)
+    if not isinstance(application, Application):
+        raise FastApiAdapterError("FastAPI Application binding is unavailable")
+    is_ready = application.is_ready
+    return JSONResponse(
+        status_code=200 if is_ready else 503,
+        content={"status": "ready" if is_ready else "not_ready"},
+    )
 
-    async def live() -> JSONResponse:
-        return JSONResponse(status_code=200, content={"status": "live"})
 
-    async def ready() -> JSONResponse:
-        is_ready = application.is_ready
-        return JSONResponse(
-            status_code=200 if is_ready else 503,
-            content={"status": "ready" if is_ready else "not_ready"},
-        )
+def _create_health_router() -> APIRouter:
+    router = APIRouter(tags=["health"])
 
     router.add_api_route(
         HEALTH_LIVE_PATH,

python_ddd_framework/fastapi/manual_action.py

@@ -13,13 +13,16 @@ from fastapi.routing import APIRoute
 from starlette.concurrency import run_in_threadpool
 from starlette.requests import Request
 from starlette.responses import Response
+from starlette.types import Receive, Scope, Send
 
 from ..application_services.dispatcher import _ApplicationServiceDispatcher
 from ..authorization.contracts import _AuthorizationRequirement
 from ..unit_of_work.options import UnitOfWorkDeclaration
+from .access import _http_access
 from .action import _HttpActionOwner, _request_parameter
 from .filters import ServiceFilter, _ordered_filters
 from .parameters import _HttpParameterValidator
+from .streaming import _PreparedStream, _stream_endpoint
 from .transfer import _manage_stream
 from .uploads import _prepare_upload
 
@@ -40,6 +43,20 @@ class _ActionRoute(DishkaRoute):
         super().__init__(path, endpoint, **kwargs)
         setattr(self.endpoint, _ACTION, self._definition)
 
+    async def handle(self, scope: Scope, receive: Receive, send: Send) -> None:
+        # 原生 SSE task group 会把准备/依赖退出错误包成单成员 group。
+        # 只去掉单成员包装，复合失败仍整体传播；外层原生 handler 保留发送前状态映射。
+        try:
+            await super().handle(scope, receive, send)
+        except BaseExceptionGroup as group:
+            error: BaseException = group
+            while isinstance(error, BaseExceptionGroup) and len(error.exceptions) == 1:
+                error = error.exceptions[0]
+            if error is group:
+                raise
+            # 不把 group 设为其自身成员的 cause；尤其保留清理失败原有的取消 cause。
+            raise error from error.__cause__
+
     def get_route_handler(self) -> Callable[[Request], Any]:
         native = super().get_route_handler()
         definition = self._definition
@@ -49,8 +66,14 @@ class _ActionRoute(DishkaRoute):
             try:
                 dispatcher = await owner.container.get(_ApplicationServiceDispatcher)
                 await dispatcher._authorize(definition.authorization)
+                request.state.python_ddd_framework_access = await _http_access(
+                    request, definition.authorization
+                )
                 await _prepare_upload(request, definition.endpoint, self)
                 result = await native(request)
+                if isinstance(owner.stream_result, Response):
+                    # Filter 短路返回的 Response 优先于生成器路由构造的原生响应。
+                    result = owner.stream_result
                 _manage_stream(request, result)
                 owner.response_ready = True
                 return result
@@ -69,6 +92,9 @@ def _wrap_action(endpoint: Callable[..., Any], definition: _ActionDefinition) ->
     request_name = request_parameter.name
     if injected_request:
         parameters += (request_parameter,)
+    streaming = inspect.isgeneratorfunction(definition.endpoint) or inspect.isasyncgenfunction(
+        definition.endpoint
+    )
 
     @wraps(endpoint)
     async def target(**values: Any) -> Any:
@@ -89,13 +115,18 @@ def _wrap_action(endpoint: Callable[..., Any], definition: _ActionDefinition) ->
         filters = _ordered_filters(
             getattr(request.app.state, "python_ddd_framework_filters", ()), definition.filters
         )
-        return await owner.invoke(definition.endpoint, values, filters, invoke)
+        result = await owner.invoke(definition.endpoint, values, filters, invoke)
+        if streaming:
+            # 准备阶段只创建源；function 依赖与 Action/UoW 退出后才能开始迭代。
+            owner.stream_result = result
+            return _PreparedStream(owner, result)
+        return result
 
     target.__signature__ = signature.replace(parameters=parameters)  # type: ignore[attr-defined]
     target.__annotations__ = {p.name: p.annotation for p in parameters}
     target.__annotations__["return"] = signature.return_annotation
     setattr(target, _ACTION, definition)
-    return target
+    return _stream_endpoint(target, signature) if streaming else target
 
 
 def _action_route_type(native: type[APIRoute]) -> type[APIRoute]:

python_ddd_framework/fastapi/module.py

@@ -5,10 +5,12 @@ from dishka.integrations.fastapi import FastapiProvider
 from ..application_services.module import ApplicationServicesModule
 from ..lifecycle import ConfigureContext
 from ..modularity import AppModule
+from .access_options import FastApiAccessOptions
 
 
 class FastApiModule(AppModule):
     dependencies = (ApplicationServicesModule,)
 
     def configure(self, context: ConfigureContext) -> None:
+        context.configure(FastApiAccessOptions, section="fastapi_access")
         context.services.contribute(FastapiProvider(), reason="Native FastAPI request context")

python_ddd_framework/fastapi/realtime/authentication.py

@@ -15,8 +15,13 @@ from dishka.exceptions import NoFactoryError
 from fastapi import WebSocket, WebSocketException
 from starlette.websockets import WebSocketDisconnect
 
-from ...authorization import AccessTokenAuthenticator, CurrentUser
+from ...authorization import CurrentUser
+from ...authorization.contracts import _authorization_requirement
 from ...invocation.contracts import _is_safe_correlation_id
+from ...invocation.runtime import _InvocationRuntime
+from ...options import Options
+from ..access import _AccessRefresh
+from ..access_options import FastApiAccessOptions
 from .connection import WebSocketConnection, _WebSocketCloseCode
 from .options import FastApiRealtimeOptions
 from .runtime import _FastApiRealtimeRuntime, _RealtimeAdmissionError
@@ -34,16 +39,24 @@ async def websocket_connection(websocket: WebSocket) -> AsyncIterator[WebSocketC
     try:
         session = cast(AsyncContainer, websocket.state.dishka_container)
         runtime = await session.get(_FastApiRealtimeRuntime)
-        authenticator = cast(
-            AccessTokenAuthenticator,
-            await session.get(AccessTokenAuthenticator),
-        )
     except (AttributeError, NoFactoryError):
         raise WebSocketException(code=_WebSocketCloseCode.POLICY_VIOLATION) from None
 
     token = _credential(websocket, runtime.options)
+    correlation = _correlation_id(websocket)
+    options = await session.get(Options[FastApiAccessOptions])
+    # 握手与持续复验使用同一 endpoint 要求，不把调用过的方法权限累积为连接权限。
+    access = _AccessRefresh(
+        session,
+        await session.get(_InvocationRuntime),
+        CurrentUser.anonymous(),
+        token,
+        correlation,
+        _authorization_requirement(object, websocket.scope["endpoint"]),
+        options.value.authentication_refresh_seconds,
+    )
     try:
-        current_user = await authenticator.authenticate_access_token(token)
+        current_user = await access.check()
     except Exception as error:
         _log_handshake_failure("authentication", error)
         raise WebSocketException(code=_WebSocketCloseCode.POLICY_VIOLATION) from None
@@ -54,10 +67,8 @@ async def websocket_connection(websocket: WebSocket) -> AsyncIterator[WebSocketC
         connection = await runtime.connect(
             websocket,
             session,
-            authenticator,
-            token,
-            current_user,
-            _correlation_id(websocket),
+            access,
+            correlation,
         )
     except _RealtimeAdmissionError as error:
         raise WebSocketException(code=error.code) from None

python_ddd_framework/fastapi/realtime/options.py

@@ -15,7 +15,6 @@ class FastApiRealtimeOptions(BaseOptions):
     model_config = ConfigDict(extra="forbid")
 
     allowed_origins: tuple[str, ...] = ()
-    authentication_refresh_seconds: int = Field(default=60, ge=1)
     outbound_queue_capacity: int = Field(default=64, ge=1)
     max_connections: int = Field(default=128, ge=1)
     max_connections_per_user: int = Field(default=8, ge=1)

python_ddd_framework/fastapi/realtime/runtime.py

@@ -8,10 +8,11 @@ from dataclasses import dataclass
 from typing import cast
 from uuid import UUID, uuid4
 
+from anyio import CancelScope
 from dishka import AsyncContainer
 from fastapi import WebSocket
 
-from ...authorization import AccessTokenAuthenticator, CurrentUser, UnauthenticatedError
+from ...authorization import CurrentUser
 from ...invocation.runtime import _InvocationRuntime
 from ...options import Options
 from ...realtime import (
@@ -21,6 +22,7 @@ from ...realtime import (
     RealtimeSnapshot,
 )
 from ...realtime.messages import _encode_envelope, _message_envelope
+from ..access import _AccessRefresh
 from .connection import (
     WebSocketConnection,
     _FrameworkProblemMessage,
@@ -45,8 +47,7 @@ class _CloseFrame:
 class _ConnectionState:
     connection_id: UUID
     websocket: WebSocket
-    authenticator: AccessTokenAuthenticator
-    access_token: str
+    access: _AccessRefresh
     current_user: CurrentUser
     correlation_id: str
     outbound: asyncio.Queue[_TextFrame | _CloseFrame]
@@ -58,6 +59,7 @@ class _ConnectionState:
     closing: bool = False
     peer_disconnected: bool = False
     close_code: int = int(_WebSocketCloseCode.NORMAL)
+    send_cancel_scope: CancelScope | None = None
 
 
 class _RealtimeAdmissionError(Exception):
@@ -106,11 +108,10 @@ class _FastApiRealtimeRuntime:
         self,
         websocket: WebSocket,
         session: AsyncContainer,
-        authenticator: AccessTokenAuthenticator,
-        access_token: str,
-        current_user: CurrentUser,
+        access: _AccessRefresh,
         correlation_id: str,
     ) -> WebSocketConnection:
+        current_user = await access.check()
         if not current_user.is_authenticated or current_user.user_id is None:
             raise _RealtimeAdmissionError(_WebSocketCloseCode.POLICY_VIOLATION)
         endpoint_task = asyncio.current_task()
@@ -119,8 +120,7 @@ class _FastApiRealtimeRuntime:
         state = _ConnectionState(
             connection_id=uuid4(),
             websocket=websocket,
-            authenticator=authenticator,
-            access_token=access_token,
+            access=access,
             current_user=current_user,
             correlation_id=correlation_id,
             # 多出的一个槽只保留给 close frame；业务容量仍严格等于 Options。
@@ -179,7 +179,6 @@ class _FastApiRealtimeRuntime:
             task.cancel()
         if tasks:
             await asyncio.gather(*tasks, return_exceptions=True)
-        state.access_token = ""
         state.closed.set()
 
     async def finish(
@@ -324,12 +323,16 @@ class _FastApiRealtimeRuntime:
         *,
         discard_pending: bool = False,
     ) -> None:
-        if state.closing:
+        if state.closing and not discard_pending:
             return
+        # 在任何 await 前关闭入队准入；授权失效仍可覆盖正在排队的正常关闭。
         state.closing = True
         state.close_code = int(code)
         evicted = 0
         if discard_pending:
+            # 撤权同时取消在途慢发送并丢弃待发帧，writer 继续负责协议关闭。
+            if state.send_cancel_scope is not None:
+                state.send_cancel_scope.cancel()
             while True:
                 try:
                     frame = state.outbound.get_nowait()
@@ -344,18 +347,13 @@ class _FastApiRealtimeRuntime:
 
     async def _refresh_identity(self, state: _ConnectionState) -> CurrentUser:
         try:
-            refreshed = await state.authenticator.authenticate_access_token(state.access_token)
-        except Exception as error:
-            _log_connection_failure("authentication", error)
-            await self._request_close(state, _WebSocketCloseCode.POLICY_VIOLATION)
-            raise UnauthenticatedError from None
-        if (
-            not refreshed.is_authenticated
-            or refreshed.user_id != state.current_user.user_id
-            or refreshed.session_id != state.current_user.session_id
-        ):
-            await self._request_close(state, _WebSocketCloseCode.POLICY_VIOLATION)
-            raise UnauthenticatedError
+            # 每次业务调用都强制复验连接要求；方法自身权限仍归受控调用链判断。
+            refreshed = await state.access.check(force=True)
+        except Exception:
+            await self._request_close(
+                state, _WebSocketCloseCode.POLICY_VIOLATION, discard_pending=True
+            )
+            raise
         state.current_user = refreshed
         return refreshed
 
@@ -364,7 +362,20 @@ class _FastApiRealtimeRuntime:
             while True:
                 frame = await state.outbound.get()
                 if isinstance(frame, _TextFrame):
-                    await state.websocket.send_text(frame.text)
+                    try:
+                        # 到期复验先于发送；独立 watchdog 可取消被网络背压阻塞的这一帧。
+                        with CancelScope() as scope:
+                            state.send_cancel_scope = scope
+                            state.current_user = await state.access.check()
+                            await state.websocket.send_text(frame.text)
+                    except Exception:
+                        if state.access.failure is None:
+                            raise
+                        await self._request_close(
+                            state, _WebSocketCloseCode.POLICY_VIOLATION, discard_pending=True
+                        )
+                    finally:
+                        state.send_cancel_scope = None
                     continue
                 await state.websocket.close(code=int(frame.code))
                 return
@@ -378,18 +389,22 @@ class _FastApiRealtimeRuntime:
 
     async def _watchdog(self, state: _ConnectionState) -> None:
         try:
+            # 不依赖接收或发送进度；所有入口共享同一个复验锁、期限和失败状态。
             while not state.closing:
                 try:
                     await asyncio.wait_for(
                         state.closed.wait(),
-                        timeout=self._options.authentication_refresh_seconds,
+                        timeout=state.access.delay,
                     )
                     return
                 except TimeoutError:
                     pass
                 try:
-                    await self._refresh_identity(state)
-                except UnauthenticatedError:
+                    state.current_user = await state.access.check()
+                except Exception:
+                    await self._request_close(
+                        state, _WebSocketCloseCode.POLICY_VIOLATION, discard_pending=True
+                    )
                     return
         except asyncio.CancelledError:
             raise