python-platform 0.1.1__py3-none-any.whl

python_platform/fastapi/realtime/authentication.py

@@ -0,0 +1,181 @@
+"""Managed WebSocket credential、Origin 与 SESSION dependency boundary。"""
+
+from __future__ import annotations
+
+import asyncio
+import ipaddress
+import logging
+from collections.abc import AsyncIterator, MutableMapping
+from typing import cast
+from urllib.parse import parse_qsl, urlencode
+from uuid import uuid4
+
+from dishka import AsyncContainer
+from dishka.exceptions import NoFactoryError
+from fastapi import WebSocket, WebSocketException
+from starlette.websockets import WebSocketDisconnect
+
+from ...authorization import AccessTokenAuthenticator, CurrentUser
+from ...invocation.contracts import _is_safe_correlation_id
+from .connection import WebSocketConnection, _WebSocketCloseCode
+from .options import FastApiRealtimeOptions
+from .runtime import _FastApiRealtimeRuntime, _RealtimeAdmissionError
+
+_LOGGER = logging.getLogger(__name__)
+_AUTHORIZATION_HEADER = b"authorization"
+_ORIGIN_HEADER = b"origin"
+_CORRELATION_HEADER = b"x-correlation-id"
+_ACCESS_TOKEN_PARAMETER = "access_token"
+
+
+async def websocket_connection(websocket: WebSocket) -> AsyncIterator[WebSocketConnection]:
+    """认证握手并把 managed endpoint 生命周期绑定到 Dishka SESSION。"""
+
+    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)
+    try:
+        current_user = await authenticator.authenticate_access_token(token)
+    except Exception as error:
+        _log_handshake_failure("authentication", error)
+        raise WebSocketException(code=_WebSocketCloseCode.POLICY_VIOLATION) from None
+    if not isinstance(current_user, CurrentUser) or not current_user.is_authenticated:
+        raise WebSocketException(code=_WebSocketCloseCode.POLICY_VIOLATION)
+
+    try:
+        connection = await runtime.connect(
+            websocket,
+            session,
+            authenticator,
+            token,
+            current_user,
+            _correlation_id(websocket),
+        )
+    except _RealtimeAdmissionError as error:
+        raise WebSocketException(code=error.code) from None
+
+    try:
+        yield connection
+    except WebSocketDisconnect:
+        pass
+    except asyncio.CancelledError:
+        raise
+    except BaseException as error:
+        _log_handshake_failure("endpoint", error)
+        await runtime._request_close(
+            connection._state,
+            _WebSocketCloseCode.INTERNAL_ERROR,
+        )
+    finally:
+        # receive() 已把真实 peer disconnect 写入 state；framework 发起的 close 仍须由 writer 发送。
+        await runtime.finish(connection.id)
+
+
+def _credential(websocket: WebSocket, options: FastApiRealtimeOptions) -> str:
+    scope = websocket.scope
+    authorization_values = _headers(websocket, _AUTHORIZATION_HEADER)
+    origin_values = _headers(websocket, _ORIGIN_HEADER)
+    query_token = _remove_query_token(scope)
+    if len(authorization_values) > 1 or len(origin_values) > 1:
+        raise WebSocketException(code=_WebSocketCloseCode.POLICY_VIOLATION)
+    header_token = _bearer_token(authorization_values[0]) if authorization_values else None
+    if header_token is not None and query_token is not None:
+        raise WebSocketException(code=_WebSocketCloseCode.POLICY_VIOLATION)
+    if header_token is None and query_token is None:
+        raise WebSocketException(code=_WebSocketCloseCode.POLICY_VIOLATION)
+
+    origin = origin_values[0] if origin_values else None
+    if origin is not None and origin not in options.allowed_origins:
+        raise WebSocketException(code=_WebSocketCloseCode.POLICY_VIOLATION)
+    if query_token is not None and origin is None:
+        raise WebSocketException(code=_WebSocketCloseCode.POLICY_VIOLATION)
+    if websocket.scope.get("scheme") != "wss" and not _is_loopback(websocket):
+        raise WebSocketException(code=_WebSocketCloseCode.POLICY_VIOLATION)
+    token = header_token if header_token is not None else query_token
+    assert token is not None
+    return token
+
+
+def _remove_query_token(scope: MutableMapping[str, object]) -> str | None:
+    raw = scope.get("query_string", b"")
+    if not isinstance(raw, bytes):
+        scope["query_string"] = b""
+        raise WebSocketException(code=_WebSocketCloseCode.POLICY_VIOLATION)
+    try:
+        pairs = parse_qsl(
+            raw.decode("ascii"),
+            keep_blank_values=True,
+            encoding="utf-8",
+            errors="strict",
+        )
+    except (UnicodeError, ValueError):
+        scope["query_string"] = b""
+        raise WebSocketException(code=_WebSocketCloseCode.POLICY_VIOLATION) from None
+    token_values = tuple(value for key, value in pairs if key == _ACCESS_TOKEN_PARAMETER)
+    retained = tuple((key, value) for key, value in pairs if key != _ACCESS_TOKEN_PARAMETER)
+    scope["query_string"] = urlencode(retained).encode("ascii")
+    if not token_values:
+        return None
+    if len(token_values) != 1 or not token_values[0] or token_values[0] != token_values[0].strip():
+        raise WebSocketException(code=_WebSocketCloseCode.POLICY_VIOLATION)
+    return token_values[0]
+
+
+def _bearer_token(value: str) -> str:
+    scheme, separator, token = value.partition(" ")
+    if (
+        scheme.casefold() != "bearer"
+        or not separator
+        or not token
+        or token != token.strip()
+        or " " in token
+    ):
+        raise WebSocketException(code=_WebSocketCloseCode.POLICY_VIOLATION)
+    return token
+
+
+def _headers(websocket: WebSocket, name: bytes) -> tuple[str, ...]:
+    headers = cast(tuple[tuple[bytes, bytes], ...], websocket.scope.get("headers", ()))
+    return tuple(
+        raw.decode("latin-1") for header_name, raw in headers if header_name.lower() == name
+    )
+
+
+def _correlation_id(websocket: WebSocket) -> str:
+    values = _headers(websocket, _CORRELATION_HEADER)
+    if len(values) == 1:
+        supplied = values[0]
+        if _is_safe_correlation_id(supplied):
+            return supplied
+    return str(uuid4())
+
+
+def _is_loopback(websocket: WebSocket) -> bool:
+    client = websocket.scope.get("client")
+    if not isinstance(client, tuple) or not client or not isinstance(client[0], str):
+        return False
+    host = client[0]
+    if host.casefold() == "localhost":
+        return True
+    try:
+        return ipaddress.ip_address(host).is_loopback
+    except ValueError:
+        return False
+
+
+def _log_handshake_failure(component: str, error: BaseException) -> None:
+    _LOGGER.warning(
+        "managed WebSocket rejected",
+        extra={
+            "realtime_component": component,
+            "realtime_exception_type": type(error).__name__,
+        },
+    )

python_platform/fastapi/realtime/connection.py

@@ -0,0 +1,166 @@
+"""单个 managed WebSocket 的公开收发与 ApplicationService bridge。"""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Awaitable, Callable, Mapping
+from enum import IntEnum
+from typing import TYPE_CHECKING, Concatenate, ParamSpec, TypeVar, cast
+from uuid import UUID
+
+from dishka import AsyncContainer
+from pydantic import BaseModel, ValidationError
+from starlette.websockets import WebSocketDisconnect
+
+from ...application_services import (
+    ApplicationServiceContract,
+    ApplicationServiceValidationError,
+)
+from ...application_services.invocation import _ScopedApplicationServiceInvoker
+from ...authorization import CurrentUser, PermissionDeniedError, UnauthenticatedError
+from ...errors import FrameworkError, ResourceConflictError, ResourceNotFoundError
+from ...realtime import RealtimeDeliveryReport
+
+if TYPE_CHECKING:
+    from .runtime import _ConnectionState, _FastApiRealtimeRuntime
+
+_PLATFORM_PROBLEM_MESSAGE_TYPE = "platform.problem.v1"
+_TModel = TypeVar("_TModel", bound=BaseModel)
+_TContract = TypeVar("_TContract", bound=ApplicationServiceContract)
+_P = ParamSpec("_P")
+_R = TypeVar("_R")
+
+
+class _WebSocketCloseCode(IntEnum):
+    NORMAL = 1000
+    UNSUPPORTED_FRAME = 1003
+    POLICY_VIOLATION = 1008
+    MESSAGE_TOO_LARGE = 1009
+    INTERNAL_ERROR = 1011
+    APPLICATION_SHUTDOWN = 1012
+    TRY_AGAIN_LATER = 1013
+
+
+class WebSocketConnection:
+    """认证连接 facade；不暴露 Dishka container 或 transport state。"""
+
+    __slots__ = ("_runtime", "_session", "_state")
+
+    def __init__(
+        self,
+        runtime: _FastApiRealtimeRuntime,
+        state: _ConnectionState,
+        session: AsyncContainer,
+    ) -> None:
+        self._runtime = runtime
+        self._state = state
+        self._session = session
+
+    @property
+    def id(self) -> UUID:
+        return self._state.connection_id
+
+    @property
+    def current_user(self) -> CurrentUser:
+        return self._state.current_user
+
+    @property
+    def correlation_id(self) -> str:
+        return self._state.correlation_id
+
+    async def receive(self, model_type: type[_TModel]) -> _TModel:
+        """只接受 text JSON object；无效输入在连接内连续计数。"""
+
+        if not isinstance(model_type, type) or not issubclass(model_type, BaseModel):
+            raise TypeError("model_type must be a Pydantic model class")
+        while True:
+            if self._state.closing:
+                raise WebSocketDisconnect(self._state.close_code)
+            message = await self._state.websocket.receive()
+            message_kind = message.get("type")
+            if message_kind == "websocket.disconnect":
+                self._state.peer_disconnected = True
+                raise WebSocketDisconnect(message.get("code", int(_WebSocketCloseCode.NORMAL)))
+            text = message.get("text")
+            if message_kind != "websocket.receive" or not isinstance(text, str):
+                await self._runtime._request_close(
+                    self._state,
+                    _WebSocketCloseCode.UNSUPPORTED_FRAME,
+                )
+                raise WebSocketDisconnect(_WebSocketCloseCode.UNSUPPORTED_FRAME)
+            try:
+                raw = json.loads(text)
+                if not isinstance(raw, dict):
+                    raise ValueError
+                value = model_type.model_validate(raw)
+            except (TypeError, ValueError, ValidationError):
+                self._state.consecutive_invalid_messages += 1
+                await self._runtime._enqueue_problem(
+                    self._state,
+                    code="validation",
+                    status=422,
+                )
+                if (
+                    self._state.consecutive_invalid_messages
+                    >= self._runtime.options.max_consecutive_invalid_messages
+                ):
+                    await self._runtime._request_close(
+                        self._state,
+                        _WebSocketCloseCode.POLICY_VIOLATION,
+                    )
+                    raise WebSocketDisconnect(_WebSocketCloseCode.POLICY_VIOLATION) from None
+                continue
+            self._state.consecutive_invalid_messages = 0
+            return value
+
+    async def invoke(
+        self,
+        method: Callable[Concatenate[_TContract, _P], Awaitable[_R]],
+        /,
+        *args: _P.args,
+        **kwargs: _P.kwargs,
+    ) -> _R:
+        """每次调用先复验身份，再从连接 SESSION 建立 REQUEST/ACTION。"""
+
+        current_user = await self._runtime._refresh_identity(self._state)
+        invoker = await self._session.get(_ScopedApplicationServiceInvoker)
+        result = await invoker.invoke(
+            self._session,
+            current_user,
+            self._state.correlation_id,
+            cast(Callable[..., Awaitable[object]], method),
+            cast(tuple[object, ...], args),
+            cast(dict[str, object], kwargs),
+        )
+        return cast(_R, result)
+
+    async def send(
+        self,
+        message_type: str,
+        payload: Mapping[str, object],
+    ) -> RealtimeDeliveryReport:
+        return await self._runtime.send_to_connection(
+            self.id,
+            message_type=message_type,
+            payload=payload,
+        )
+
+    async def send_problem(self, error: FrameworkError) -> RealtimeDeliveryReport:
+        if not isinstance(error, FrameworkError):
+            raise TypeError("error must be FrameworkError")
+        code, status = _problem_descriptor(error)
+        return await self._runtime._enqueue_problem(self._state, code=code, status=status)
+
+
+def _problem_descriptor(error: FrameworkError) -> tuple[str, int]:
+    if isinstance(error, ApplicationServiceValidationError):
+        return "validation", 422
+    if isinstance(error, UnauthenticatedError):
+        return "authentication", 401
+    if isinstance(error, PermissionDeniedError):
+        return "forbidden", 403
+    if isinstance(error, ResourceNotFoundError):
+        return "not_found", 404
+    if isinstance(error, ResourceConflictError):
+        return "conflict", 409
+    return "internal", 500

python_platform/fastapi/realtime/module.py

@@ -0,0 +1,41 @@
+"""FastAPI realtime Module composition 与 lifecycle。"""
+
+from __future__ import annotations
+
+from dishka import Provider, Scope
+
+from ...lifecycle import ConfigureContext, InitializeContext, ShutdownContext
+from ...modularity import AppModule
+from ...realtime import RealtimePublisher
+from .options import FastApiRealtimeOptions
+from .runtime import _FastApiRealtimeRuntime, _realtime_publisher
+
+
+class FastApiRealtimeModule(AppModule):
+    def __init__(self) -> None:
+        self._runtime: _FastApiRealtimeRuntime | None = None
+
+    def configure(self, context: ConfigureContext) -> None:
+        context.configure(FastApiRealtimeOptions, section="fastapi_realtime")
+        provider = Provider()
+        provider.provide(
+            _FastApiRealtimeRuntime,
+            provides=_FastApiRealtimeRuntime,
+            scope=Scope.APP,
+        )
+        provider.provide(
+            _realtime_publisher,
+            provides=RealtimePublisher,
+            scope=Scope.APP,
+        )
+        context.services.contribute(provider, reason="FastAPI managed WebSocket runtime")
+
+    async def initialize(self, context: InitializeContext) -> None:
+        runtime = await context.container.get(_FastApiRealtimeRuntime)
+        self._runtime = runtime
+        await runtime.start_accepting()
+
+    async def shutdown(self, context: ShutdownContext) -> None:
+        runtime = self._runtime
+        if runtime is not None:
+            await runtime.shutdown()

python_platform/fastapi/realtime/options.py

@@ -0,0 +1,50 @@
+"""FastAPI realtime 的 Host-owned immutable options。"""
+
+from __future__ import annotations
+
+from urllib.parse import urlsplit
+
+from pydantic import ConfigDict, Field, field_validator, model_validator
+
+from ...options import BaseOptions
+
+
+class FastApiRealtimeOptions(BaseOptions):
+    """连接容量与安全边界；浏览器 Origin 必须由 Host 显式声明。"""
+
+    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)
+    max_consecutive_invalid_messages: int = Field(default=3, ge=1)
+    shutdown_timeout_seconds: int = Field(default=10, ge=1)
+
+    @field_validator("allowed_origins")
+    @classmethod
+    def _validate_allowed_origins(cls, origins: tuple[str, ...]) -> tuple[str, ...]:
+        if len(set(origins)) != len(origins):
+            raise ValueError("allowed_origins cannot contain duplicates")
+        for origin in origins:
+            parsed = urlsplit(origin)
+            if (
+                parsed.scheme not in {"http", "https"}
+                or not parsed.hostname
+                or parsed.username is not None
+                or parsed.password is not None
+                or parsed.path
+                or parsed.query
+                or parsed.fragment
+                or origin != f"{parsed.scheme}://{parsed.netloc}"
+                or "*" in origin
+            ):
+                raise ValueError("allowed_origins must contain canonical HTTP origins")
+        return origins
+
+    @model_validator(mode="after")
+    def _validate_connection_limits(self) -> FastApiRealtimeOptions:
+        if self.max_connections_per_user > self.max_connections:
+            raise ValueError("max_connections_per_user cannot exceed max_connections")
+        return self