python-platform 0.1.1__py3-none-any.whl

python_platform/hosted_services/bridge.py

@@ -0,0 +1,420 @@
+"""Hosted Service 到 Application Service pipeline 的限流、跨线程调用桥。"""
+
+from __future__ import annotations
+
+import asyncio
+import concurrent.futures
+import functools
+import inspect
+import threading
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass, field
+from typing import Concatenate, ParamSpec, TypeVar, cast
+from uuid import uuid4
+
+from dishka import AsyncContainer
+
+from ..application_services import ApplicationServiceCatalog, ApplicationServiceContract
+from ..application_services.invocation import _InvocationRuntime, _ScopedApplicationServiceInvoker
+from ..authorization import CurrentUser
+from ..invocation.contracts import _is_safe_correlation_id
+from ..invocation.function_runtime import _invoke_callable
+from .errors import HostedServiceInvocationRejectedError
+
+_P = ParamSpec("_P")
+_R = TypeVar("_R")
+_TContract = TypeVar("_TContract", bound=ApplicationServiceContract)
+
+
+@dataclass(slots=True)
+class _PendingInvocation:
+    external_future: concurrent.futures.Future[object] | None
+    task: asyncio.Task[object] | None = None
+
+
+class _HostedServiceBridge:
+    """每个 Runtime 独占 admission/capacity，pending 对象保留到 loop Task 真正结束。"""
+
+    __slots__ = (
+        "_accepting",
+        "_catalog",
+        "_container",
+        "_limit",
+        "_lock",
+        "_loop",
+        "_name",
+        "_pending",
+    )
+
+    def __init__(
+        self,
+        *,
+        name: str,
+        loop: asyncio.AbstractEventLoop,
+        container: AsyncContainer,
+        catalog: ApplicationServiceCatalog,
+        limit: int,
+    ) -> None:
+        self._name = name
+        self._loop = loop
+        self._container = container
+        self._catalog = catalog
+        self._limit = limit
+        self._lock = threading.RLock()
+        self._pending: dict[object, _PendingInvocation] = {}
+        self._accepting = False
+
+    def open(self) -> None:
+        with self._lock:
+            self._accepting = True
+
+    def close(self) -> None:
+        with self._lock:
+            self._accepting = False
+
+    async def invoke(
+        self,
+        correlation_id: str,
+        method: Callable[..., Awaitable[_R]],
+        args: tuple[object, ...],
+        kwargs: dict[str, object],
+        *,
+        callable_entry: bool = False,
+    ) -> _R:
+        operation = "invoke"
+        self._require_application_loop(operation)
+        self._validate_call(operation, correlation_id, method, callable_entry=callable_entry)
+        token = object()
+        with self._lock:
+            self._admit(token, operation, external_future=None)
+            task = asyncio.create_task(
+                self._invoke_pipeline(
+                    correlation_id, method, args, kwargs, callable_entry=callable_entry
+                ),
+                name=f"python-platform-hosted-service-invoke:{self._name}",
+            )
+            self._pending[token].task = task
+            task.add_done_callback(functools.partial(self._release_task, token))
+        return cast(_R, await task)
+
+    def submit(
+        self,
+        correlation_id: str,
+        method: Callable[..., Awaitable[_R]],
+        args: tuple[object, ...],
+        kwargs: dict[str, object],
+        *,
+        callable_entry: bool = False,
+    ) -> concurrent.futures.Future[_R]:
+        operation = "submit"
+        self._require_external_thread(operation)
+        self._validate_call(operation, correlation_id, method, callable_entry=callable_entry)
+        token = object()
+        with self._lock:
+            self._admit(token, operation, external_future=None)
+            invocation = self._invoke_submitted(
+                token, correlation_id, method, args, kwargs, callable_entry=callable_entry
+            )
+            try:
+                external = asyncio.run_coroutine_threadsafe(
+                    invocation,
+                    self._loop,
+                )
+            except RuntimeError:
+                invocation.close()
+                self._pending.pop(token, None)
+                raise HostedServiceInvocationRejectedError(
+                    service=self._name,
+                    operation=operation,
+                    error_type="EventLoopUnavailable",
+                ) from None
+            pending = self._pending[token]
+            pending.external_future = external
+            external.add_done_callback(functools.partial(self._observe_external_completion, token))
+        return cast(concurrent.futures.Future[_R], external)
+
+    async def drain(self, timeout: float) -> None:
+        """deadline 前自然 drain；超时后取消 loop Task 并等待 UoW/finalizer 收口。"""
+
+        self._require_application_loop("drain")
+        deadline = self._loop.time() + timeout
+        if await self._wait_for_natural_drain(deadline):
+            return
+        await self._cancel_pending_and_wait()
+
+    async def _wait_for_natural_drain(self, deadline: float) -> bool:
+        while True:
+            pending = self._pending_snapshot()
+            if not pending:
+                return True
+            tasks = tuple(item.task for item in pending if item.task is not None)
+            remaining = deadline - self._loop.time()
+            if remaining <= 0:
+                return False
+            if not tasks:
+                # submit 已占容量但 call_soon_threadsafe callback 尚未建立 Task。
+                await asyncio.sleep(0)
+                continue
+            await asyncio.wait(tasks, timeout=remaining)
+
+    async def _cancel_pending_and_wait(self) -> None:
+        pending = self._pending_snapshot()
+        for item in pending:
+            if item.external_future is not None:
+                item.external_future.cancel()
+            if item.task is not None:
+                item.task.cancel()
+
+        # Task cancellation 完成后，invocation owner 才确认 rollback/finalizer 已结束。
+        while True:
+            pending = self._pending_snapshot()
+            if not pending:
+                return
+            tasks = tuple(item.task for item in pending if item.task is not None)
+            if tasks:
+                await asyncio.gather(*tasks, return_exceptions=True)
+            else:
+                await asyncio.sleep(0)
+
+    def _admit(
+        self,
+        token: object,
+        operation: str,
+        *,
+        external_future: concurrent.futures.Future[object] | None,
+    ) -> None:
+        if not self._accepting:
+            raise HostedServiceInvocationRejectedError(
+                service=self._name,
+                operation=operation,
+                error_type="NotAccepting",
+            )
+        if len(self._pending) >= self._limit:
+            raise HostedServiceInvocationRejectedError(
+                service=self._name,
+                operation=operation,
+                error_type="CapacityExceeded",
+            )
+        self._pending[token] = _PendingInvocation(external_future=external_future)
+
+    async def _invoke_submitted(
+        self,
+        token: object,
+        correlation_id: str,
+        method: Callable[..., Awaitable[object]],
+        args: tuple[object, ...],
+        kwargs: dict[str, object],
+        *,
+        callable_entry: bool = False,
+    ) -> object:
+        task = asyncio.current_task()
+        assert task is not None
+        with self._lock:
+            pending = self._pending.get(token)
+            assert pending is not None
+            pending.task = cast(asyncio.Task[object], task)
+        try:
+            return await self._invoke_pipeline(
+                correlation_id, method, args, kwargs, callable_entry=callable_entry
+            )
+        finally:
+            # concurrent Future 可先进入 cancelled；只有 loop Task finalizer 完成才释放容量。
+            with self._lock:
+                self._pending.pop(token, None)
+
+    def _release_task(self, token: object, task: asyncio.Task[object]) -> None:
+        del task
+        with self._lock:
+            self._pending.pop(token, None)
+
+    def _observe_external_completion(
+        self,
+        token: object,
+        external: concurrent.futures.Future[object],
+    ) -> None:
+        if not external.cancelled():
+            return
+        try:
+            self._loop.call_soon_threadsafe(
+                self._defer_cancelled_release,
+                token,
+                external,
+            )
+        except RuntimeError:
+            # loop 已关闭时 coroutine 不可能再启动；只释放仍无 Task 的 reservation。
+            self._release_cancelled_if_unstarted(token, external)
+
+    def _defer_cancelled_release(
+        self,
+        token: object,
+        external: concurrent.futures.Future[object],
+    ) -> None:
+        # run_coroutine_threadsafe 的 callback 可能刚创建 Task；再让一轮以观察其启动或取消。
+        self._loop.call_soon(self._release_cancelled_if_unstarted, token, external)
+
+    def _release_cancelled_if_unstarted(
+        self,
+        token: object,
+        external: concurrent.futures.Future[object],
+    ) -> None:
+        with self._lock:
+            pending = self._pending.get(token)
+            if (
+                pending is not None
+                and pending.external_future is external
+                and pending.task is None
+                and external.cancelled()
+            ):
+                self._pending.pop(token, None)
+
+    async def _invoke_pipeline(
+        self,
+        correlation_id: str,
+        method: Callable[..., Awaitable[object]],
+        args: tuple[object, ...],
+        kwargs: dict[str, object],
+        *,
+        callable_entry: bool = False,
+    ) -> object:
+        if callable_entry:
+            service = await self._container.get(_InvocationRuntime)
+            return await _invoke_callable(
+                self._container,
+                service,
+                CurrentUser.anonymous(),
+                correlation_id,
+                method,
+                args,
+                kwargs,
+            )
+        invoker = await self._container.get(_ScopedApplicationServiceInvoker)
+        return await invoker.invoke(
+            self._container,
+            CurrentUser.anonymous(),
+            correlation_id,
+            method,
+            args,
+            kwargs,
+        )
+
+    def _validate_call(
+        self,
+        operation: str,
+        correlation_id: str,
+        method: object,
+        *,
+        callable_entry: bool = False,
+    ) -> None:
+        if not _is_safe_correlation_id(correlation_id):
+            raise HostedServiceInvocationRejectedError(
+                service=self._name,
+                operation=operation,
+                error_type="InvalidCorrelationId",
+            )
+        # immutable catalog 可安全在 SDK thread 先验校验，非法 method 不占用容量。
+        if callable_entry:
+            if not inspect.iscoroutinefunction(method):
+                raise TypeError(
+                    "HostedService callable must be an async function or bound async method"
+                )
+        else:
+            self._catalog._resolve_method(method)
+
+    def _require_application_loop(self, operation: str) -> None:
+        if asyncio.get_running_loop() is not self._loop:
+            raise HostedServiceInvocationRejectedError(
+                service=self._name,
+                operation=operation,
+                error_type="WrongEventLoop",
+            )
+
+    def _require_external_thread(self, operation: str) -> None:
+        try:
+            loop = asyncio.get_running_loop()
+        except RuntimeError:
+            return
+        if loop is self._loop:
+            raise HostedServiceInvocationRejectedError(
+                service=self._name,
+                operation=operation,
+                error_type="ApplicationEventLoop",
+            )
+
+    def _pending_snapshot(self) -> tuple[_PendingInvocation, ...]:
+        with self._lock:
+            return tuple(self._pending.values())
+
+
+@dataclass(frozen=True, slots=True)
+class HostedServiceContext:
+    """Runtime 的最小 capability；不暴露 Application、container 或 event loop。"""
+
+    name: str
+    _bridge: _HostedServiceBridge = field(repr=False, compare=False)
+
+    async def call(
+        self,
+        function: Callable[..., Awaitable[_R]],
+        /,
+        *args: object,
+        **kwargs: object,
+    ) -> _R:
+        return await self._bridge.invoke(str(uuid4()), function, args, kwargs, callable_entry=True)
+
+    def submit_call(
+        self,
+        function: Callable[..., Awaitable[_R]],
+        /,
+        *args: object,
+        **kwargs: object,
+    ) -> concurrent.futures.Future[_R]:
+        """外部线程继续经过同一 admission/drain bridge，不直接接触异步容器。"""
+        return self._bridge.submit(str(uuid4()), function, args, kwargs, callable_entry=True)
+
+    async def invoke(
+        self,
+        method: Callable[Concatenate[_TContract, _P], Awaitable[_R]],
+        /,
+        *args: _P.args,
+        **kwargs: _P.kwargs,
+    ) -> _R:
+        return await self.invoke_correlated(str(uuid4()), method, *args, **kwargs)
+
+    async def invoke_correlated(
+        self,
+        correlation_id: str,
+        method: Callable[Concatenate[_TContract, _P], Awaitable[_R]],
+        /,
+        *args: _P.args,
+        **kwargs: _P.kwargs,
+    ) -> _R:
+        return await self._bridge.invoke(
+            correlation_id,
+            method,
+            cast(tuple[object, ...], args),
+            cast(dict[str, object], kwargs),
+        )
+
+    def submit(
+        self,
+        method: Callable[Concatenate[_TContract, _P], Awaitable[_R]],
+        /,
+        *args: _P.args,
+        **kwargs: _P.kwargs,
+    ) -> concurrent.futures.Future[_R]:
+        return self.submit_correlated(str(uuid4()), method, *args, **kwargs)
+
+    def submit_correlated(
+        self,
+        correlation_id: str,
+        method: Callable[Concatenate[_TContract, _P], Awaitable[_R]],
+        /,
+        *args: _P.args,
+        **kwargs: _P.kwargs,
+    ) -> concurrent.futures.Future[_R]:
+        return self._bridge.submit(
+            correlation_id,
+            method,
+            cast(tuple[object, ...], args),
+            cast(dict[str, object], kwargs),
+        )

python_platform/hosted_services/catalog.py

@@ -0,0 +1,259 @@
+"""Module-owned Hosted Service metadata 的有序、不可变 Application catalog。"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from collections.abc import Iterator, Mapping
+from dataclasses import dataclass
+from types import MappingProxyType
+from typing import TYPE_CHECKING
+
+from dishka import DEFAULT_COMPONENT, DependencyKey, Provider, Scope
+
+from ..diagnostics import SourceLocation
+from ..modularity import AppModule, ModuleKey, ModuleRegistry
+from .contracts import HostedService, _validate_service_type
+from .errors import HostedServiceContractError, HostedServiceDefinitionError
+
+if TYPE_CHECKING:
+    from ..services.arbitration import _RegistrationDraft
+    from ..services.contribution import ServiceContributionRegistry, _ContributionEntry
+    from ..services.provider import _CollectionDefinition, _FactoryDefinition
+    from ..services.registration import RegistrationKind
+
+
+@dataclass(frozen=True, slots=True)
+class HostedServiceRegistration:
+    service_type: type[HostedService]
+    name: str
+    owner: ModuleKey
+    source: SourceLocation
+    declaration_index: int
+    run_in_background_processes: bool
+
+
+class HostedServiceCatalog:
+    """顺序来自 Module dependency order 与各 Module 的声明顺序。"""
+
+    __slots__ = ("_by_name", "_declarations", "_fingerprint", "_registrations")
+
+    def __init__(
+        self,
+        registrations: tuple[HostedServiceRegistration, ...],
+        *,
+        declarations: tuple[tuple[type[AppModule], tuple[type[HostedService], ...]], ...],
+    ) -> None:
+        self._registrations = registrations
+        self._by_name: Mapping[str, HostedServiceRegistration] = MappingProxyType(
+            {item.name: item for item in registrations}
+        )
+        self._declarations = declarations
+        encoded = json.dumps(
+            [
+                {
+                    "name": item.name,
+                    "service_type": (
+                        f"{item.service_type.__module__}.{item.service_type.__qualname__}"
+                    ),
+                    "owner": str(item.owner),
+                    "declaration_index": item.declaration_index,
+                    "run_in_background_processes": item.run_in_background_processes,
+                }
+                for item in registrations
+            ],
+            sort_keys=True,
+            separators=(",", ":"),
+        ).encode()
+        self._fingerprint = hashlib.sha256(encoded).hexdigest()
+
+    @property
+    def registrations(self) -> tuple[HostedServiceRegistration, ...]:
+        return self._registrations
+
+    @property
+    def service_types(self) -> tuple[type[HostedService], ...]:
+        return tuple(item.service_type for item in self._registrations)
+
+    @property
+    def fingerprint(self) -> str:
+        return self._fingerprint
+
+    def __iter__(self) -> Iterator[str]:
+        return iter(self._by_name)
+
+    def get(self, name: str) -> HostedServiceRegistration | None:
+        registration = self._by_name.get(name)
+        return registration
+
+    def owner_for(self, name: str) -> ModuleKey | None:
+        registration = self._by_name.get(name)
+        return registration.owner if registration is not None else None
+
+    def _assert_unchanged(self) -> None:
+        for item in self._registrations:
+            if (
+                item.service_type.run_in_background_processes
+                is not item.run_in_background_processes
+            ):
+                raise HostedServiceDefinitionError(
+                    service=item.name,
+                    reason="HostedService process metadata changed after build",
+                )
+        for module_type, declared in self._declarations:
+            if module_type.__dict__.get("hosted_services", ()) is not declared:
+                raise HostedServiceDefinitionError(
+                    service=f"{module_type.__module__}.{module_type.__qualname__}",
+                    reason="Module hosted_services metadata changed after build",
+                )
+
+
+def _build_hosted_service_catalog(registry: ModuleRegistry) -> HostedServiceCatalog:
+    registrations: list[HostedServiceRegistration] = []
+    declarations: list[tuple[type[AppModule], tuple[type[HostedService], ...]]] = []
+    names: dict[str, ModuleKey] = {}
+    for descriptor in registry.dependency_order:
+        declared = descriptor.module_type.__dict__.get("hosted_services", ())
+        if not isinstance(declared, tuple):
+            raise HostedServiceDefinitionError(
+                service=str(descriptor.key),
+                reason="Module hosted_services must be an immutable tuple",
+            )
+        declarations.append((descriptor.module_type, declared))
+        for declaration_index, candidate in enumerate(declared):
+            _validate_service_type(candidate)
+            name = f"{candidate.__module__}.{candidate.__qualname__}"
+            previous_name_owner = names.get(name)
+            if previous_name_owner is not None:
+                raise HostedServiceDefinitionError(
+                    service=name,
+                    reason=f"name is already owned by {previous_name_owner}",
+                )
+            names[name] = descriptor.key
+            registrations.append(
+                HostedServiceRegistration(
+                    service_type=candidate,
+                    name=name,
+                    owner=descriptor.key,
+                    source=descriptor.declaration_source,
+                    declaration_index=declaration_index,
+                    run_in_background_processes=candidate.run_in_background_processes,
+                )
+            )
+    return HostedServiceCatalog(tuple(registrations), declarations=tuple(declarations))
+
+
+def _contribute_hosted_service_defaults(
+    catalog: HostedServiceCatalog,
+    contributions: ServiceContributionRegistry,
+) -> None:
+    """默认 class factory 进入既有仲裁；显式 APP binding 因而能原生 back off。"""
+
+    for registration in catalog.registrations:
+        service_type = registration.service_type
+        provider = Provider()
+        provider.provide(service_type, provides=service_type, scope=Scope.APP)
+        contributions._add_framework_default(
+            provider=provider,
+            owner=registration.owner,
+            source=registration.source,
+            reason=f"Hosted Service default for {registration.name}",
+        )
+
+
+def _validate_hosted_service_entries(
+    entries: tuple[_ContributionEntry, ...],
+    catalog: HostedServiceCatalog,
+) -> None:
+    """在通用仲裁前识别 wrong-scope/multi，返回 Hosted Service 专属错误。"""
+
+    from ..services.provider import _NativeProviderInspector
+
+    names_by_key = {
+        DependencyKey(item.service_type, DEFAULT_COMPONENT): item.name
+        for item in catalog.registrations
+    }
+    explicit_counts: dict[DependencyKey, int] = {}
+    for entry in entries:
+        contribution = entry.contribution
+        validated = _NativeProviderInspector(
+            source=contribution.source,
+            kind=contribution.kind,
+        ).inspect(contribution.provider)
+        for factory in validated.factories:
+            _validate_hosted_service_factory(
+                factory,
+                contribution.kind,
+                names_by_key,
+                explicit_counts,
+            )
+        for collection in validated.collections:
+            _validate_hosted_service_collection(collection, names_by_key)
+    for key, count in explicit_counts.items():
+        if count > 1:
+            raise HostedServiceContractError(
+                service=names_by_key[key],
+                operation="bind",
+                error_type="MultipleBindings",
+            )
+
+
+def _validate_hosted_service_factory(
+    factory: _FactoryDefinition,
+    kind: RegistrationKind,
+    names_by_key: Mapping[DependencyKey, str],
+    explicit_counts: dict[DependencyKey, int],
+) -> None:
+    from ..services.registration import RegistrationKind
+
+    name = names_by_key.get(factory.key)
+    if name is None:
+        return
+    if kind is RegistrationKind.MULTI:
+        raise HostedServiceContractError(
+            service=name,
+            operation="bind",
+            error_type="MultiBinding",
+        )
+    if factory.scope is not Scope.APP:
+        raise HostedServiceContractError(
+            service=name,
+            operation="bind",
+            error_type="WrongScope",
+        )
+    if kind is RegistrationKind.EXPLICIT:
+        explicit_counts[factory.key] = explicit_counts.get(factory.key, 0) + 1
+
+
+def _validate_hosted_service_collection(
+    collection: _CollectionDefinition,
+    names_by_key: Mapping[DependencyKey, str],
+) -> None:
+    name = names_by_key.get(collection.key)
+    if name is not None:
+        raise HostedServiceContractError(
+            service=name,
+            operation="bind",
+            error_type="MultiBinding",
+        )
+
+
+def _validate_hosted_service_drafts(
+    drafts: tuple[_RegistrationDraft, ...],
+    catalog: HostedServiceCatalog,
+) -> None:
+    from ..services.registration import RegistrationDecision
+
+    for registration in catalog.registrations:
+        key = DependencyKey(registration.service_type, DEFAULT_COMPONENT)
+        winners = tuple(
+            draft
+            for draft in drafts
+            if draft.key == key and draft.decision is RegistrationDecision.ACCEPTED
+        )
+        if len(winners) != 1 or winners[0].scope is not Scope.APP or winners[0].is_collection:
+            raise HostedServiceContractError(
+                service=registration.name,
+                operation="bind",
+                error_type="InvalidBinding",
+            )