python-platform 0.1.1__py3-none-any.whl

python_platform/fastapi/settings.py

@@ -0,0 +1,40 @@
+"""管理路由复用正式 Application Service 认证、权限与参数绑定。"""
+
+from ..modularity import AppModule
+from ..settings.management import SettingsManagementApplicationService
+from ..settings.module import SettingsManagementModule
+from . import ApplicationServiceRouteOverride, exposes_application_services
+
+
+@exposes_application_services(
+    SettingsManagementModule,
+    root_path="settings",
+    overrides=(
+        ApplicationServiceRouteOverride(
+            SettingsManagementApplicationService,
+            method=SettingsManagementApplicationService.get_list,
+            path="/api/settings",
+            verb="GET",
+        ),
+        ApplicationServiceRouteOverride(
+            SettingsManagementApplicationService,
+            method=SettingsManagementApplicationService.get,
+            path="/api/settings/{name}",
+            verb="GET",
+        ),
+        ApplicationServiceRouteOverride(
+            SettingsManagementApplicationService,
+            method=SettingsManagementApplicationService.update,
+            path="/api/settings/{name}",
+            verb="PUT",
+        ),
+        ApplicationServiceRouteOverride(
+            SettingsManagementApplicationService,
+            method=SettingsManagementApplicationService.reset,
+            path="/api/settings/{name}/reset",
+            verb="POST",
+        ),
+    ),
+)
+class SettingsManagementHttpApiModule(AppModule):
+    dependencies = (SettingsManagementModule,)

python_platform/fastapi/tracing.py

@@ -0,0 +1,62 @@
+"""FastAPI 官方 instrumentation 的 Application provider 接线。"""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from contextlib import contextmanager
+
+from fastapi import FastAPI
+from starlette.background import BackgroundTask
+
+from ..application import Application
+from ..observability.options import TracingOptions
+from ..options import Options
+
+
+@contextmanager
+def _tracing_rollback(app: FastAPI) -> Iterator[None]:
+    already_instrumented = getattr(app, "_is_instrumented_by_opentelemetry", False)
+    background_call = BackgroundTask.__call__
+    original_call = getattr(BackgroundTask, "_otel_original_call", None)
+    try:
+        yield
+    except BaseException:
+        if not already_instrumented and getattr(app, "_is_instrumented_by_opentelemetry", False):
+            from opentelemetry.instrumentation.fastapi import FastAPIInstrumentor
+
+            # 官方撤销会重建栈；失败的 Host 构造器不能在撤销时再次执行。
+            # 外层安装事务随后恢复原 middleware、stack 和实例属性。
+            app.user_middleware = []
+            try:
+                FastAPIInstrumentor.uninstrument_app(app)
+            finally:
+                # 0.65b0 撤销会修改全局 BackgroundTask；保留其他 Host 已有接线。
+                BackgroundTask.__call__ = background_call  # type: ignore[method-assign]
+                if original_call is not None:
+                    BackgroundTask._otel_original_call = original_call  # type: ignore[attr-defined]
+        raise
+
+
+def _install_tracing(application: Application, app: FastAPI) -> None:
+    if TracingOptions not in application.options.values or getattr(
+        app, "_is_instrumented_by_opentelemetry", False
+    ):
+        return
+    from opentelemetry.instrumentation.fastapi import FastAPIInstrumentor
+
+    from ..observability.tracing import TracingModule
+
+    # provider 来自正式 Module 实例；不建立应用级 tracer registry 或全局 SDK provider。
+    module = next(
+        descriptor.instance
+        for descriptor in application.modules.dependency_order
+        if isinstance(descriptor.instance, TracingModule)
+    )
+    provider = module._prepare(Options(application.options.get(TracingOptions)))
+    FastAPIInstrumentor.instrument_app(
+        app,
+        tracer_provider=provider,
+        http_capture_headers_server_request=[],
+        http_capture_headers_server_response=[],
+        exclude_spans=["receive", "send"],
+    )

python_platform/fastapi/transfer.py

@@ -0,0 +1,128 @@
+"""原生传输资源的退出边界，早于 REQUEST 退出，晚于业务 UoW。"""
+
+from __future__ import annotations
+
+import asyncio
+import inspect
+from collections.abc import Awaitable, Callable
+from contextlib import AsyncExitStack
+
+from anyio import CancelScope
+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 ..application_services.invocation import _InvocationRuntime
+
+
+async def _close_form(form: FormData) -> None:
+    # native 正常 close 已执行时无需再关；取消导致 native close 中断时补齐剩余文件。
+    with CancelScope(shield=True):
+        async with AsyncExitStack() as stack:
+            for _, value in form.multi_items():
+                if isinstance(value, UploadFile) and not value.file.closed:
+                    stack.push_async_callback(value.close)
+
+
+def _manage_stream(request: Request, response: object) -> None:
+    if not isinstance(response, StreamingResponse):
+        return
+    if isinstance(getattr(response.stream_response, "__self__", None), _StreamLifetime):
+        return
+    iterator = response.body_iterator
+    close: Callable[[], Awaitable[None]] | None = None
+    # Starlette 同步流已经转换为原生线程池生成器；在第一次迭代前取得其输入。
+    # 按实际函数签名读取，不复制参数名称或线程池算法。此处是锁定版本的集成接点。
+    if inspect.isasyncgen(iterator) and iterator.ag_code is iterate_in_threadpool.__code__:
+        frame = iterator.ag_frame
+        assert frame is not None
+        arguments = inspect.getargvalues(frame)
+        source = iter(arguments.locals[arguments.args[0]])
+        response.body_iterator = iterate_in_threadpool(source)
+        sync_close = getattr(source, "close", None)
+        if sync_close is not None:
+
+            async def close() -> None:
+                await run_in_threadpool(sync_close)
+    else:
+        iterator = aiter(iterator)
+        response.body_iterator = iterator
+        close = getattr(iterator, "aclose", None)
+    lifetime = _StreamLifetime(request, response.stream_response, close)
+    response.stream_response = lifetime.send  # type: ignore[method-assign]
+    request.scope["fastapi_middleware_astack"].push_async_callback(lifetime.close)
+
+
+class _StreamLifetime:
+    """producer 串行拥有迭代与关闭；请求监督它结束后才允许 REQUEST/stop 退出。"""
+
+    def __init__(
+        self,
+        request: Request,
+        send: Callable[[Send], Awaitable[None]],
+        close: Callable[[], Awaitable[None]] | None,
+    ) -> None:
+        self._request = request
+        self._send = send
+        self._close = close
+
+    async def close(self) -> None:
+        # 先取走回调，避免 producer finally 与请求退出栈重复关闭同一资源。
+        # 这里只保护平台调用的 close；生成器在迭代中进入的 finally 必须自行 shield。
+        close, self._close = self._close, None
+        if close is not None:
+            with CancelScope(shield=True):
+                await close()
+
+    async def send(self, send: Send) -> None:
+        # scope 可在 producer 启动前取消，但只能由 producer 自己进入/退出。
+        cancel_scope = CancelScope()
+        task = asyncio.create_task(self._run(send, cancel_scope))
+        try:
+            # wait 不向 producer 传播 raw cancel，也不把已监督的清理异常重复报告给 loop。
+            await asyncio.wait((task,))
+            task.result()
+        except asyncio.CancelledError as primary:
+            # ASGI <2.4 的原生 task group 会吞掉 disconnect 引发的取消；保留请求失败事实，
+            # 审计可以记录它，但不能在已发送响应后重新生成错误 body。
+            self._request.state.python_platform_transfer_failure = ClientDisconnect()
+            # 原生 scope 尊重线程池等待和生成器自己的 shield；raw task.cancel 会绕过它们。
+            # 强引用并等待 producer，重复请求取消不得使 REQUEST 提前退出。
+            cancel_scope.cancel()
+            with CancelScope(shield=True):
+                while not task.done():
+                    try:
+                        await asyncio.wait((task,))
+                    except asyncio.CancelledError:
+                        # 原生 shield 阻挡 AnyIO 的重复取消；raw asyncio 取消仍可能到达监督者。
+                        # 继续等待同一个 producer，不重发取消、不重启或放弃清理。
+                        pass
+                try:
+                    task.result()
+                except asyncio.CancelledError:
+                    # producer 已结束；对调用方保留首次取消，而不是替换成内部 scope 的取消。
+                    pass
+                except BaseException as failure:
+                    # ASGI <2.4 的 task group 会吞 CancelledError，即使它带有失败 cause。
+                    # 让清理失败穿过原生 task group，原始取消保留在异常链中，不重发响应。
+                    raise failure from primary
+            raise
+
+    async def _run(self, send: Send, cancel_scope: CancelScope) -> None:
+        container = self._request.state.dishka_container
+        runtime = await container.get(_InvocationRuntime)
+        user, correlation = self._request.state.python_platform_identity
+        # 可信 REQUEST 许可覆盖发送和关闭；内层取消 scope 只控制发送。
+        # 先退出内层 scope 再执行 finalizer，避免重复取消破坏关闭顺序。
+        with (
+            CancelScope(shield=True),
+            runtime.trusted_http_task(container, user, correlation, self._request.method),
+        ):
+            try:
+                with cancel_scope:
+                    await self._send(send)
+            finally:
+                # 发送/next 已退出才能串行关闭；生成器内部 finally 的 await 由其自己 shield。
+                await self.close()

python_platform/fastapi/upload_limits.py

@@ -0,0 +1,63 @@
+"""不可变上传策略；默认值、字段和覆盖语义的唯一权威。"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass, fields, replace
+from enum import Enum
+from types import MappingProxyType
+from typing import TypeVar
+
+_F = TypeVar("_F", bound=Callable[..., object])
+_LIMITS = "__python_platform_upload_limits__"
+
+
+class _Unset(Enum):
+    VALUE = "unset"
+
+
+@dataclass(frozen=True, slots=True)
+class UploadLimits:
+    """Host 默认；总量含编码开销，max_file_size=None 表示不另限单文件。"""
+
+    max_request_size: int = 30_000_000
+    max_file_size: int | None = None
+    max_files: int = 1000
+    max_fields: int = 1000
+    max_part_size: int = 1024 * 1024
+
+    def __post_init__(self) -> None:
+        for field in fields(self):
+            value = getattr(self, field.name)
+            if value is None and field.default is None:
+                continue
+            if type(value) is not int or value < 0:
+                raise ValueError(f"{field.name} must be a non-negative integer")
+
+
+def upload_limits(
+    *,
+    max_request_size: int | _Unset = _Unset.VALUE,
+    max_file_size: int | _Unset | None = _Unset.VALUE,
+    max_files: int | _Unset = _Unset.VALUE,
+    max_fields: int | _Unset = _Unset.VALUE,
+    max_part_size: int | _Unset = _Unset.VALUE,
+) -> Callable[[_F], _F]:
+    """只覆盖显式字段；单文件 None 显式取消 Host 的单文件上限。"""
+    values = locals()
+    overrides = {
+        field.name: values[field.name]
+        for field in fields(UploadLimits)
+        if values[field.name] is not _Unset.VALUE
+    }
+    replace(UploadLimits(), **overrides)
+
+    def decorate(method: _F) -> _F:
+        setattr(method, _LIMITS, MappingProxyType(overrides))
+        return method
+
+    return decorate
+
+
+def _limits_for(host: UploadLimits, method: object) -> UploadLimits:
+    return replace(host, **getattr(method, _LIMITS, {}))

python_platform/fastapi/uploads.py

@@ -0,0 +1,94 @@
+"""Starlette 上传 parser 接线；不拥有业务持久化文件。"""
+
+from __future__ import annotations
+
+from collections.abc import AsyncGenerator
+
+from fastapi.params import Form
+from fastapi.routing import APIRoute
+from python_multipart.exceptions import MultipartParseError
+from python_multipart.multipart import parse_options_header
+from starlette.exceptions import HTTPException
+from starlette.formparsers import FormParser, MultiPartException, MultiPartParser
+from starlette.requests import Request
+
+from .transfer import _close_form
+from .upload_limits import UploadLimits, _limits_for
+
+
+class _LimitedMultipartParser(MultiPartParser):
+    def __init__(
+        self, request: Request, stream: AsyncGenerator[bytes, None], limits: UploadLimits
+    ) -> None:
+        self._ended = False
+        super().__init__(
+            request.headers,
+            self._complete_stream(stream),
+            max_files=limits.max_files,
+            max_fields=limits.max_fields,
+            max_part_size=limits.max_part_size,
+        )
+        self._max_file_size = limits.max_file_size
+        self._file_size = 0
+
+    async def _complete_stream(
+        self, stream: AsyncGenerator[bytes, None]
+    ) -> AsyncGenerator[bytes, None]:
+        async for chunk in stream:
+            yield chunk
+        # 上游 finalize 不拒绝被截断的最后一个 part；在 native parse 的 try 内拒绝，
+        # 仍由它的 BaseException 路径关闭全部已创建 spool。
+        if not self._ended:
+            raise MultiPartException("Incomplete multipart body")
+
+    def on_end(self) -> None:
+        super().on_end()
+        self._ended = True
+
+    def on_part_begin(self) -> None:
+        super().on_part_begin()
+        self._file_size = 0
+
+    def on_part_data(self, data: bytes, start: int, end: int) -> None:
+        if self._current_part.file is not None:
+            self._file_size += end - start
+            if self._max_file_size is not None and self._file_size > self._max_file_size:
+                raise HTTPException(413, "Upload size limit exceeded")
+        super().on_part_data(data, start, end)
+
+
+async def _prepare_upload(request: Request, method: object, route: APIRoute) -> None:
+    # 只接管原生表单绑定；原始 Request/body endpoint 保留自己的读取语义。
+    if route.body_field is None or not isinstance(route.body_field.field_info, Form):
+        return
+    content_type, _ = parse_options_header(request.headers.get("content-type"))
+    if content_type not in (b"multipart/form-data", b"application/x-www-form-urlencoded"):
+        return
+    limits = _limits_for(request.app.state.python_platform_upload_limits, method)
+
+    async def counted() -> AsyncGenerator[bytes, None]:
+        total = 0
+        async for chunk in request.stream():
+            total += len(chunk)
+            if total > limits.max_request_size:
+                raise HTTPException(413, "Upload size limit exceeded")
+            yield chunk
+
+    try:
+        parser = (
+            _LimitedMultipartParser(request, counted(), limits)
+            if content_type == b"multipart/form-data"
+            else FormParser(
+                request.headers,
+                counted(),
+                max_fields=limits.max_fields,
+                max_part_size=limits.max_part_size,
+            )
+        )
+        form = await parser.parse()
+    except (MultiPartException, MultipartParseError) as error:
+        raise HTTPException(400, "Invalid form data") from error
+    # 唯一缓存接点：原生绑定复用已解析表单；原生文件栈拥有请求结束时的关闭。
+    # 先登记受保护的关闭，再进入 native，覆盖绑定前失败；关闭只处理尚未释放的句柄。
+    request._form = form
+    request.scope["fastapi_middleware_astack"].push_async_callback(_close_form, form)

python_platform/hosted_services/__init__.py

@@ -0,0 +1,29 @@
+"""通用外部 Hosted Service、readiness 与 Application Service bridge。"""
+
+from .bridge import HostedServiceContext
+from .catalog import HostedServiceCatalog, HostedServiceRegistration
+from .contracts import HostedService, HostedServiceStatus
+from .errors import (
+    HostedServiceContractError,
+    HostedServiceDefinitionError,
+    HostedServiceInvocationRejectedError,
+    HostedServiceLifecycleError,
+)
+from .options import HOSTED_SERVICE_OPTIONS_SECTION, HostedServiceOptions
+from .state import ApplicationReadinessSnapshot, HostedServiceSnapshot
+
+__all__ = (
+    "HOSTED_SERVICE_OPTIONS_SECTION",
+    "ApplicationReadinessSnapshot",
+    "HostedService",
+    "HostedServiceCatalog",
+    "HostedServiceContext",
+    "HostedServiceContractError",
+    "HostedServiceDefinitionError",
+    "HostedServiceInvocationRejectedError",
+    "HostedServiceLifecycleError",
+    "HostedServiceOptions",
+    "HostedServiceRegistration",
+    "HostedServiceSnapshot",
+    "HostedServiceStatus",
+)