python-platform 0.1.1__py3-none-any.whl

python_platform/fastapi/route_integrity.py

@@ -0,0 +1,88 @@
+"""安装完成后的 FastAPI route surface 完整性快照。"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from dataclasses import dataclass
+from typing import Any, Protocol, cast
+
+from fastapi.routing import APIRoute, APIWebSocketRoute, iter_route_contexts
+from starlette.routing import BaseRoute, WebSocketRoute
+
+
+class _RouteFingerprintView(Protocol):
+    operation_id: str | None
+    unique_id: str
+    include_in_schema: bool
+    summary: str | None
+    description: str
+    tags: list[object]
+    responses: dict[int | str, dict[str, Any]]
+    response_model: Any
+    status_code: int | None
+
+
+@dataclass(frozen=True, slots=True)
+class _RouteFingerprintEntry:
+    original_route_id: int
+    route_type: str
+    path: str | None
+    path_format: str | None
+    methods: tuple[str, ...]
+    endpoint_id: int | None
+    dependency_ids: tuple[int, ...]
+    schema_signature: str
+
+
+RouteFingerprint = tuple[_RouteFingerprintEntry, ...]
+
+
+def _route_fingerprint(routes: Sequence[BaseRoute]) -> RouteFingerprint:
+    entries: list[_RouteFingerprintEntry] = []
+    for context in iter_route_contexts(routes):
+        original_route = context.original_route
+        route_view = cast(_RouteFingerprintView, context)
+        methods = context.methods or set()
+        websocket_route = original_route if isinstance(original_route, WebSocketRoute) else None
+        endpoint = context.endpoint or getattr(websocket_route, "endpoint", None)
+        path = websocket_route.path if websocket_route is not None else context.path
+        path_format = (
+            websocket_route.path_format if websocket_route is not None else context.path_format
+        )
+        schema_signature = ""
+        dependency_ids: tuple[int, ...] = ()
+        if isinstance(original_route, APIRoute):
+            schema_signature = repr(
+                (
+                    route_view.operation_id,
+                    route_view.unique_id,
+                    route_view.include_in_schema,
+                    route_view.summary,
+                    route_view.description,
+                    route_view.tags,
+                    route_view.responses,
+                    route_view.response_model,
+                    route_view.status_code,
+                )
+            )
+        elif isinstance(original_route, APIWebSocketRoute):
+            dependency_ids = tuple(
+                id(dependency.call)
+                for dependency in original_route.dependant.dependencies
+                if dependency.call is not None
+            )
+        entries.append(
+            _RouteFingerprintEntry(
+                original_route_id=id(original_route),
+                route_type=(
+                    f"{type(original_route).__module__}:{type(original_route).__qualname__}"
+                ),
+                path=path,
+                path_format=path_format,
+                methods=tuple(sorted(method.upper() for method in methods)),
+                endpoint_id=id(endpoint) if endpoint is not None else None,
+                dependency_ids=dependency_ids,
+                schema_signature=schema_signature,
+            )
+        )
+    return tuple(entries)

python_platform/fastapi/routing.py

@@ -0,0 +1,410 @@
+"""Native FastAPI route 展开之上的 contribution plan、冲突与 schema 门禁。"""
+
+from __future__ import annotations
+
+import inspect
+import re
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass
+from enum import Enum
+from typing import Protocol, cast
+
+from dishka.integrations.fastapi import DishkaRoute
+from fastapi import APIRouter, FastAPI
+from fastapi.routing import APIRoute, APIWebSocketRoute, RouteContext, iter_route_contexts
+from starlette.routing import BaseRoute, WebSocketRoute
+
+from ..application import Application
+from ..diagnostics import SourceLocation
+from ..modularity import ModuleKey
+from .application_services import (
+    _ROUTE_SOURCE_ATTRIBUTE,
+    _application_service_routers,
+)
+from .contracts import (
+    RouterCatalog,
+    RouterRegistration,
+    WebSocketRouteRegistration,
+    _routers_for,
+)
+from .errors import FastApiAdapterError, RouteConflictError
+from .health import _create_health_router
+from .http_router import HttpRouter
+from .manual_action import _ActionRoute
+from .realtime import websocket_connection
+
+_PATH_PARAMETER = re.compile(r"\{[^{}:]+(?P<converter>:[^{}]+)?\}")
+
+
+class _OpenApiRouteView(Protocol):
+    operation_id: str | None
+    unique_id: str
+    include_in_schema: bool
+
+
+class _RouteKind(Enum):
+    HTTP = "http"
+    WEBSOCKET = "websocket"
+
+
+@dataclass(frozen=True, slots=True)
+class _RouteCandidate:
+    kind: _RouteKind
+    owner: ModuleKey | None
+    source: SourceLocation
+    path: str
+    normalized_path: str
+    methods: tuple[str, ...]
+    operation_id: str | None
+    include_in_schema: bool
+    http_sources: tuple[tuple[str, str], ...] = ()
+
+
+@dataclass(frozen=True, slots=True)
+class _RouteInstallationPlan:
+    routers: tuple[APIRouter, ...]
+    health_router: APIRouter
+    catalog: RouterCatalog
+    schema_candidates: tuple[_RouteCandidate, ...]
+
+
+def _build_route_plan(app: FastAPI, application: Application) -> _RouteInstallationPlan:
+    host_candidates = _route_candidates(
+        app.routes,
+        owner=None,
+        owner_label="fastapi-host",
+        require_managed=False,
+    )
+    preview = _preview_router(app)
+    contributed_candidates: list[_RouteCandidate] = []
+    routers: list[APIRouter] = []
+
+    # 手工 Router 永远先于 convention route，避免 module graph 偶然改变公开匹配顺序。
+    manual_routers = tuple(
+        (descriptor.key, router)
+        for descriptor in application.modules.dependency_order
+        for router in _routers_for(descriptor.module_type)
+    )
+    generated_routers = tuple(
+        (item.owner, item.router) for item in _application_service_routers(application)
+    )
+    for owner, router in (*manual_routers, *generated_routers):
+        if isinstance(router, HttpRouter):
+            router = router._compile(application._container_for_integration())
+        for context in iter_route_contexts(router.routes):
+            route = context.original_route
+            if isinstance(route, _ActionRoute):
+                unknown = tuple(
+                    permission
+                    for permission in route._definition.authorization.permissions
+                    if permission not in application.permission_catalog
+                )
+                if unknown:
+                    raise FastApiAdapterError(
+                        f"HTTP action references unknown permissions: {unknown}"
+                    )
+        routers.append(router)
+        route_start = len(preview.routes)
+        preview.include_router(router)
+        contributed_candidates.extend(
+            _route_candidates(
+                preview.routes[route_start:],
+                owner=owner,
+                owner_label=str(owner),
+                require_managed=True,
+            )
+        )
+
+    health_router = _create_health_router(application)
+    health_route_start = len(preview.routes)
+    preview.include_router(health_router)
+    health_candidates = _route_candidates(
+        preview.routes[health_route_start:],
+        owner=None,
+        owner_label="python-platform-health",
+        require_managed=False,
+    )
+    schema_candidates = tuple(
+        candidate
+        for candidate in (*contributed_candidates, *health_candidates)
+        if candidate.kind is _RouteKind.HTTP and candidate.include_in_schema
+    )
+    _validate_route_conflicts((*host_candidates, *contributed_candidates, *health_candidates))
+
+    registrations = tuple(
+        RouterRegistration(
+            owner=_required_owner(candidate),
+            source=candidate.source,
+            path=candidate.path,
+            methods=candidate.methods,
+            operation_id=_required_operation_id(candidate),
+            http_sources=candidate.http_sources,
+            order=order,
+        )
+        for order, candidate in enumerate(
+            item for item in contributed_candidates if item.kind is _RouteKind.HTTP
+        )
+    )
+    websocket_registrations = tuple(
+        WebSocketRouteRegistration(
+            owner=_required_owner(candidate),
+            source=candidate.source,
+            path=candidate.path,
+            order=order,
+        )
+        for order, candidate in enumerate(
+            item for item in contributed_candidates if item.kind is _RouteKind.WEBSOCKET
+        )
+    )
+    return _RouteInstallationPlan(
+        routers=tuple(routers),
+        health_router=health_router,
+        catalog=RouterCatalog(registrations, websocket_registrations),
+        schema_candidates=schema_candidates,
+    )
+
+
+def _preview_router(app: FastAPI) -> APIRouter:
+    # 让 FastAPI 自己计算 include context 与 effective operation ID，不复制其展开算法。
+    return APIRouter(
+        prefix=app.router.prefix,
+        tags=list(app.router.tags),
+        dependencies=list(app.router.dependencies),
+        default_response_class=app.router.default_response_class,
+        responses=dict(app.router.responses),
+        deprecated=app.router.deprecated,
+        include_in_schema=app.router.include_in_schema,
+        generate_unique_id_function=app.router.generate_unique_id_function,
+        dependency_overrides_provider=app,
+        strict_content_type=app.router.strict_content_type,
+    )
+
+
+def _route_candidates(
+    routes: Sequence[BaseRoute],
+    *,
+    owner: ModuleKey | None,
+    owner_label: str,
+    require_managed: bool,
+) -> tuple[_RouteCandidate, ...]:
+    candidates: list[_RouteCandidate] = []
+    for context in iter_route_contexts(routes):
+        original_route = context.original_route
+        if isinstance(original_route, WebSocketRoute):
+            candidates.append(
+                _websocket_route_candidate(
+                    context,
+                    owner=owner,
+                    owner_label=owner_label,
+                    require_managed=require_managed,
+                )
+            )
+            continue
+        if require_managed and not isinstance(original_route, DishkaRoute):
+            raise FastApiAdapterError(
+                f"{owner_label} contributes unsupported {type(original_route).__name__}; "
+                "HTTP routes must be APIRoute instances created with DishkaRoute"
+            )
+        if not isinstance(original_route, APIRoute):
+            # Host-native Mount/plain routes remain Host-owned but不进入 Module catalog。
+            if require_managed:
+                raise FastApiAdapterError(
+                    f"{owner_label} contributes unsupported {type(original_route).__name__}"
+                )
+            candidate = _plain_http_candidate(context, owner=owner, owner_label=owner_label)
+            if candidate is not None:
+                candidates.append(candidate)
+            continue
+        candidate = _api_route_candidate(context, owner=owner, owner_label=owner_label)
+        candidates.append(candidate)
+    return tuple(candidates)
+
+
+def _websocket_route_candidate(
+    context: RouteContext,
+    *,
+    owner: ModuleKey | None,
+    owner_label: str,
+    require_managed: bool,
+) -> _RouteCandidate:
+    route = context.original_route
+    path = getattr(route, "path", None)
+    if not isinstance(path, str) or not path:
+        raise FastApiAdapterError(f"{owner_label} contains a WebSocket route without path")
+    managed_dependency_count = 0
+    if isinstance(route, APIWebSocketRoute):
+        managed_dependency_count = sum(
+            1
+            for dependency in route.dependant.dependencies
+            if dependency.call is websocket_connection
+        )
+    if require_managed and managed_dependency_count != 1:
+        raise FastApiAdapterError(
+            f"{owner_label} WebSocket route {path!r} must declare Depends(websocket_connection)"
+        )
+    return _RouteCandidate(
+        kind=_RouteKind.WEBSOCKET,
+        owner=owner,
+        source=_source_for_context(context, owner_label),
+        path=path,
+        normalized_path=_normalize_path(path),
+        methods=(),
+        operation_id=None,
+        include_in_schema=False,
+    )
+
+
+def _plain_http_candidate(
+    context: RouteContext,
+    *,
+    owner: ModuleKey | None,
+    owner_label: str,
+) -> _RouteCandidate | None:
+    path = context.path
+    methods = context.methods
+    if path is None or not methods:
+        return None
+    source = _source_for_context(context, owner_label)
+    return _RouteCandidate(
+        kind=_RouteKind.HTTP,
+        owner=owner,
+        source=source,
+        path=path,
+        normalized_path=_normalize_path(path),
+        methods=tuple(sorted(method.upper() for method in methods)),
+        operation_id=None,
+        include_in_schema=False,
+    )
+
+
+def _api_route_candidate(
+    context: RouteContext,
+    *,
+    owner: ModuleKey | None,
+    owner_label: str,
+) -> _RouteCandidate:
+    path = context.path
+    methods = context.methods
+    if path is None or not methods:
+        raise FastApiAdapterError(f"{owner_label} contains an APIRoute without path or methods")
+    route_view = cast(_OpenApiRouteView, context)
+    operation_id = route_view.operation_id or route_view.unique_id
+    if not isinstance(operation_id, str) or not operation_id:
+        raise FastApiAdapterError(f"{owner_label} route {path!r} has no effective operation ID")
+    return _RouteCandidate(
+        kind=_RouteKind.HTTP,
+        owner=owner,
+        source=_source_for_context(context, owner_label),
+        path=path,
+        normalized_path=_normalize_path(path),
+        methods=tuple(sorted(method.upper() for method in methods)),
+        operation_id=operation_id,
+        include_in_schema=route_view.include_in_schema,
+        http_sources=tuple(
+            getattr(
+                cast(APIRoute, context.original_route).endpoint,
+                "__python_platform_http_sources__",
+                {},
+            ).items()
+        ),
+    )
+
+
+def _source_for_context(context: RouteContext, owner_label: str) -> SourceLocation:
+    endpoint = context.endpoint or getattr(context.original_route, "endpoint", None)
+    file_name: str | None = None
+    line: int | None = None
+    symbol: str | None = None
+    if endpoint is not None:
+        declared_source = getattr(endpoint, _ROUTE_SOURCE_ATTRIBUTE, None)
+        if isinstance(declared_source, SourceLocation):
+            return declared_source
+        symbol = getattr(endpoint, "__qualname__", getattr(endpoint, "__name__", None))
+        try:
+            file_name = inspect.getsourcefile(endpoint)
+            _, line = inspect.getsourcelines(endpoint)
+        except (OSError, TypeError):
+            pass
+    return SourceLocation(owner=owner_label, file=file_name, line=line, symbol=symbol)
+
+
+def _normalize_path(path: str) -> str:
+    def replace_parameter(match: re.Match[str]) -> str:
+        converter = match.group("converter") or ""
+        return "{" + converter + "}"
+
+    return _PATH_PARAMETER.sub(replace_parameter, path)
+
+
+def _validate_route_conflicts(candidates: Sequence[_RouteCandidate]) -> None:
+    by_method_path: dict[tuple[str, str], _RouteCandidate] = {}
+    by_websocket_path: dict[str, _RouteCandidate] = {}
+    by_operation_id: dict[str, _RouteCandidate] = {}
+    for candidate in candidates:
+        if candidate.kind is _RouteKind.WEBSOCKET:
+            existing_websocket = by_websocket_path.get(candidate.normalized_path)
+            if existing_websocket is not None:
+                raise RouteConflictError(
+                    conflict_kind="WebSocket path template",
+                    value=candidate.normalized_path,
+                    sources=(existing_websocket.source, candidate.source),
+                )
+            by_websocket_path[candidate.normalized_path] = candidate
+            continue
+        for method in candidate.methods:
+            method_path = (method, candidate.normalized_path)
+            existing_path = by_method_path.get(method_path)
+            if existing_path is not None:
+                raise RouteConflictError(
+                    conflict_kind="method/path template",
+                    value=f"{method} {candidate.normalized_path}",
+                    sources=(existing_path.source, candidate.source),
+                )
+            by_method_path[method_path] = candidate
+
+        if not candidate.include_in_schema or candidate.operation_id is None:
+            continue
+        existing_operation = by_operation_id.get(candidate.operation_id)
+        if existing_operation is not None:
+            raise RouteConflictError(
+                conflict_kind="OpenAPI operation ID",
+                value=candidate.operation_id,
+                sources=(existing_operation.source, candidate.source),
+            )
+        by_operation_id[candidate.operation_id] = candidate
+
+
+def _required_owner(candidate: _RouteCandidate) -> ModuleKey:
+    if candidate.owner is None:
+        raise AssertionError("Module route candidate lost its owner")
+    return candidate.owner
+
+
+def _required_operation_id(candidate: _RouteCandidate) -> str:
+    if candidate.operation_id is None:
+        raise AssertionError("Module route candidate lost its operation ID")
+    return candidate.operation_id
+
+
+def _verify_native_openapi(app: FastAPI, candidates: Sequence[_RouteCandidate]) -> None:
+    schema = app.openapi()
+    raw_paths = schema.get("paths")
+    if not isinstance(raw_paths, Mapping):
+        raise FastApiAdapterError("FastAPI native OpenAPI schema has no paths mapping")
+    for candidate in candidates:
+        if candidate.kind is not _RouteKind.HTTP:
+            raise AssertionError("WebSocket route cannot enter OpenAPI verification")
+        path_item = raw_paths.get(candidate.path)
+        if not isinstance(path_item, Mapping):
+            raise FastApiAdapterError(
+                f"FastAPI native OpenAPI omitted contributed path {candidate.path!r}"
+            )
+        for method in candidate.methods:
+            operation = path_item.get(method.lower())
+            if not isinstance(operation, Mapping) or operation.get("operationId") != (
+                candidate.operation_id
+            ):
+                raise FastApiAdapterError(
+                    f"FastAPI native OpenAPI omitted {method} {candidate.path} "
+                    f"operation {candidate.operation_id!r}"
+                )

python_platform/fastapi/server.py

@@ -0,0 +1,181 @@
+"""Uvicorn 进程输出 owner：覆盖 factory、reload child 与 Application 关闭之后。"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import multiprocessing
+import os
+import socket
+from collections.abc import Iterator
+from contextlib import contextmanager
+from multiprocessing.synchronize import Event
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from uvicorn import Config, Server
+
+if TYPE_CHECKING:
+    from uvicorn.supervisors.basereload import BaseReload as ChangeReload
+else:
+    from uvicorn.supervisors import ChangeReload
+
+from ..background_execution.locks import _check_previous_owners
+from ..hosting import ENVIRONMENT_VARIABLE
+from ..hosting.instance import _instance_lock
+from ..observability.formatting import _SafeTextFormatter
+
+
+class _BootstrapFilter(logging.Filter):
+    def filter(self, record: logging.LogRecord) -> bool:
+        # Application handler 接管期间不重复输出；关闭移除后自动恢复早期输出。
+        return not any(
+            getattr(item, "_application_logging", False)
+            for handler in logging.getLogger().handlers
+            for item in handler.filters
+        )
+
+
+@contextmanager
+def _host_logging() -> Iterator[None]:
+    root = logging.getLogger()
+    if any(
+        isinstance(item, _BootstrapFilter) for handler in root.handlers for item in handler.filters
+    ):
+        yield
+        return
+    handler = logging.StreamHandler()
+    handler.setFormatter(_SafeTextFormatter("%(levelname)s %(name)s %(message)s"))
+    handler.addFilter(_BootstrapFilter())
+    previous_level = root.level
+    root.setLevel(logging.INFO)
+    root.addHandler(handler)
+    try:
+        yield
+    except Exception:
+        # 不让 multiprocessing 或解释器在安全 handler 退出后再次打印原始 traceback。
+        logging.getLogger(__name__).exception("Host execution failed")
+        raise SystemExit(3) from None
+    finally:
+        root.removeHandler(handler)
+        handler.close()
+        root.setLevel(previous_level)
+
+
+class _HostServer(Server):
+    def __init__(
+        self,
+        config: Config,
+        shutdown_requested: Event | None = None,
+        *,
+        project: Path,
+        environment: str,
+    ) -> None:
+        super().__init__(config)
+        self._shutdown_requested = shutdown_requested
+        self._project = project
+        self._environment = environment
+
+    def run(self, sockets: list[socket.socket] | None = None) -> None:
+        # 原生 reload 使用 spawn；bound target 在每个子进程单独建立输出生命周期。
+        with _host_logging():
+            super().run(sockets=sockets)
+
+    async def serve(self, sockets: list[socket.socket] | None = None) -> None:
+        # 每次正式 Host／reload child 均在 factory 前核对，包括新目录已移除全部任务的情况。
+        _check_previous_owners(self._project, self._environment)
+        shutdown_requested = self._shutdown_requested
+        if shutdown_requested is None:
+            await super().serve(sockets)
+            return
+
+        async def watch_shutdown() -> None:
+            while not shutdown_requested.is_set():
+                await asyncio.sleep(self.config.reload_delay)
+            self.should_exit = True
+
+        # Uvicorn 的 Windows reload 依赖 console Ctrl+C 广播。显式的父子请求只改变
+        # 原生 should_exit，避免影响同一 console 中其他任务，也保留完整 ASGI 清理。
+        watcher = asyncio.create_task(watch_shutdown())
+        try:
+            await super().serve(sockets)
+        finally:
+            watcher.cancel()
+            await asyncio.gather(watcher, return_exceptions=True)
+
+
+class _HostReload(ChangeReload):
+    def __init__(
+        self,
+        config: Config,
+        server: _HostServer,
+        sockets: list[socket.socket],
+        shutdown_requested: Event,
+    ) -> None:
+        super().__init__(config, target=server.run, sockets=sockets)
+        self._shutdown_requested = shutdown_requested
+
+    def run(self) -> None:
+        try:
+            super().run()
+        finally:
+            # 原生监测循环异常时也必须等待子进程；否则退出父进程的 with 会过早释放位置。
+            process = getattr(self, "process", None)
+            if process is not None and process.is_alive():
+                self.shutdown()
+
+    def restart(self) -> None:
+        # 旧进程尚未退出就一直占位；不靠超时／PID 猜测，更不强杀后立即补位。
+        self._shutdown_requested.set()
+        self.process.join()
+        self._shutdown_requested.clear()
+        # 原生 startup 仍负责 spawn、信号接线和 socket 传递，不复制进程创建实现。
+        self.startup()
+
+    def shutdown(self) -> None:
+        self._shutdown_requested.set()
+        super().shutdown()
+
+
+def _run_host(
+    app: str,
+    *,
+    host: str,
+    port: int,
+    reload: bool = False,
+    project: Path | None = None,
+    environment: str | None = None,
+) -> None:
+    # 保留原生 Config/Server/ChangeReload，平台仅补进程输出边界，不接管 ASGI 生命周期。
+    # reload 的父进程持锁直到所有子进程 join；子进程不重复占用主 Host 位置。
+    # 此边界早于 factory 加载和运行期初始化，DB CLI/TestApplication 不经过这里。
+    project = Path.cwd() if project is None else project
+    environment = (
+        environment if environment is not None else os.getenv(ENVIRONMENT_VARIABLE, "development")
+    )
+    instance = _instance_lock(project, environment)
+    with _host_logging(), instance:
+        config = Config(
+            app,
+            factory=True,
+            host=host,
+            port=port,
+            reload=reload,
+            log_config=None,
+            access_log=False,
+        )
+        shutdown_requested = (
+            multiprocessing.get_context("spawn").Event() if config.should_reload else None
+        )
+        server = _HostServer(config, shutdown_requested, project=project, environment=environment)
+        if config.should_reload:
+            sock = config.bind_socket()
+            try:
+                assert shutdown_requested is not None
+                _HostReload(config, server, [sock], shutdown_requested).run()
+            finally:
+                sock.close()
+        else:
+            server.run()
+            if not server.started:
+                raise SystemExit(3)