python-platform 0.1.1__py3-none-any.whl

python_platform/hosted_services/contracts.py

@@ -0,0 +1,55 @@
+"""主 Host 拥有的服务生命周期契约；连接恢复由服务实现负责。"""
+
+from __future__ import annotations
+
+import inspect
+from abc import ABC, abstractmethod
+from enum import Enum
+from typing import TYPE_CHECKING, ClassVar
+
+from .errors import HostedServiceDefinitionError
+
+if TYPE_CHECKING:
+    from ..lifecycle import ShutdownReason
+    from .bridge import HostedServiceContext
+
+
+class HostedService(ABC):
+    """APP 单例；start 返回即启动成功，stop 必须等待自身资源退出。"""
+
+    run_in_background_processes: ClassVar[bool] = False
+
+    @abstractmethod
+    async def start(self, context: HostedServiceContext) -> None:
+        raise NotImplementedError
+
+    @abstractmethod
+    async def stop(self, reason: ShutdownReason) -> None:
+        raise NotImplementedError
+
+
+class HostedServiceStatus(str, Enum):
+    STARTING = "starting"
+    RUNNING = "running"
+    STOPPING = "stopping"
+    STOPPED = "stopped"
+    FAILED = "failed"
+
+
+def _validate_service_type(candidate: type[HostedService]) -> None:
+    if not isinstance(candidate, type) or not issubclass(candidate, HostedService):
+        raise HostedServiceDefinitionError(
+            service=repr(candidate), reason="hosted_services must contain HostedService types"
+        )
+    name = f"{candidate.__module__}.{candidate.__qualname__}"
+    if not isinstance(candidate.run_in_background_processes, bool):
+        raise HostedServiceDefinitionError(
+            service=name, reason="run_in_background_processes must be bool"
+        )
+    if inspect.isabstract(candidate):
+        raise HostedServiceDefinitionError(service=name, reason="service type must be concrete")
+    for operation in ("start", "stop"):
+        if not inspect.iscoroutinefunction(getattr(candidate, operation, None)):
+            raise HostedServiceDefinitionError(
+                service=name, reason=f"{operation} must use async def"
+            )

python_platform/hosted_services/errors.py

@@ -0,0 +1,53 @@
+"""Hosted Service definition、lifecycle 与 bridge 的脱敏错误边界。"""
+
+from __future__ import annotations
+
+from ..errors.base import FrameworkError
+
+
+class HostedServiceDefinitionError(FrameworkError):
+    def __init__(self, *, service: str, reason: str) -> None:
+        self.service = service
+        self.reason = reason
+        super().__init__(f"Invalid Hosted Service {service!r}: {reason}")
+
+
+class HostedServiceContractError(FrameworkError):
+    """只发布 Service identity、操作与稳定错误类型，不保留 provider 异常正文。"""
+
+    def __init__(self, *, service: str, operation: str, error_type: str) -> None:
+        self.service = service
+        self.operation = operation
+        self.error_type = error_type
+        super().__init__(
+            f"Hosted Service {service!r} contract rejected {operation} with {error_type}"
+        )
+
+
+class HostedServiceLifecycleError(FrameworkError):
+    """Service 第三方异常在此终止传播，避免设备或 SDK 文本进入终态。"""
+
+    failure_id = None
+    stage = None
+    dependency_path: tuple[object, ...] = ()
+
+    def __init__(self, *, service: str, operation: str, error_type: str) -> None:
+        self.service = service
+        self.operation = operation
+        self.error_type = error_type
+        super().__init__(f"Hosted Service {service!r} {operation} failed with {error_type}")
+
+    @property
+    def original_error(self) -> BaseException:
+        # 与 ApplicationStartError 的统一 primary shape 对齐，但绝不返回第三方异常。
+        return self
+
+
+class HostedServiceInvocationRejectedError(FrameworkError):
+    def __init__(self, *, service: str, operation: str, error_type: str) -> None:
+        self.service = service
+        self.operation = operation
+        self.error_type = error_type
+        super().__init__(
+            f"Hosted Service {service!r} invocation {operation} rejected with {error_type}"
+        )

python_platform/hosted_services/options.py

@@ -0,0 +1,17 @@
+"""Hosted Service 的 Host-owned 容量与 lifecycle deadline。"""
+
+from datetime import timedelta
+
+from pydantic import ConfigDict, Field
+
+from ..options import BaseOptions
+
+HOSTED_SERVICE_OPTIONS_SECTION = "hosted_service"
+
+
+class HostedServiceOptions(BaseOptions):
+    model_config = ConfigDict(extra="forbid")
+
+    max_pending_invocations: int = Field(default=128, ge=1)
+    startup_timeout: timedelta = Field(default=timedelta(seconds=30), gt=timedelta(0))
+    shutdown_timeout: timedelta = Field(default=timedelta(seconds=30), gt=timedelta(0))

python_platform/hosted_services/runtime.py

@@ -0,0 +1,267 @@
+"""Hosted Service resolution、bootstrap 与逆序 shutdown owner。"""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass
+from typing import cast
+
+from dishka import AsyncContainer
+
+from ..application_services import ApplicationServiceCatalog
+from ..lifecycle import ApplicationState, ShutdownReason
+from .bridge import HostedServiceContext, _HostedServiceBridge
+from .catalog import HostedServiceCatalog, HostedServiceRegistration
+from .contracts import HostedService, HostedServiceStatus
+from .errors import HostedServiceDefinitionError, HostedServiceLifecycleError
+from .options import HostedServiceOptions
+from .state import ApplicationReadinessSnapshot, _HostedServiceStateOwner
+
+
+@dataclass(slots=True)
+class _HostedServiceEntry:
+    registration: HostedServiceRegistration
+    service: HostedService
+    context: HostedServiceContext
+    bridge: _HostedServiceBridge
+
+
+class _HostedServiceCoordinator:
+    """单 Application 的 Service/bridge/task owner；不强制终止实现拥有的 OS thread。"""
+
+    __slots__ = (
+        "_application_service_catalog",
+        "_catalog",
+        "_container",
+        "_entries",
+        "_options",
+        "_registrations",
+        "_started",
+        "_state_getter",
+        "_state_owner",
+    )
+
+    def __init__(
+        self,
+        *,
+        catalog: HostedServiceCatalog,
+        options: HostedServiceOptions,
+        state_getter: Callable[[], ApplicationState],
+    ) -> None:
+        self._catalog = catalog
+        self._options = options
+        self._state_getter = state_getter
+        self._registrations = catalog.registrations
+        self._state_owner = _HostedServiceStateOwner(self._registrations)
+        self._container: AsyncContainer | None = None
+        self._application_service_catalog: ApplicationServiceCatalog | None = None
+        self._entries: list[_HostedServiceEntry] = []
+        self._started = False
+
+    def attach_container(
+        self,
+        container: AsyncContainer,
+        application_service_catalog: ApplicationServiceCatalog,
+    ) -> None:
+        if self._container is not None:
+            raise RuntimeError("Hosted Service coordinator container is already attached")
+        self._container = container
+        self._application_service_catalog = application_service_catalog
+
+    def readiness(self) -> ApplicationReadinessSnapshot:
+        return self._state_owner.snapshot(self._state_getter())
+
+    def select_child(self) -> None:
+        if self._started:
+            raise RuntimeError("Hosted Service process selection must precede start")
+        # 先按 build 冻结的声明选择；解析、bridge、readiness 与 stop 共用同一进程集合。
+        self._registrations = tuple(
+            item for item in self._catalog.registrations if item.run_in_background_processes
+        )
+        self._state_owner = _HostedServiceStateOwner(self._registrations)
+
+    async def start(self) -> None:
+        if self._started:
+            raise RuntimeError("Hosted Service coordinator is already started")
+        try:
+            self._catalog._assert_unchanged()
+        except HostedServiceDefinitionError as original_error:
+            raise HostedServiceLifecycleError(
+                service=original_error.service,
+                operation="metadata",
+                error_type=type(original_error).__name__,
+            ) from None
+        container = self._container
+        application_service_catalog = self._application_service_catalog
+        if container is None or application_service_catalog is None:
+            raise RuntimeError("Hosted Service coordinator container is unavailable")
+        self._started = True
+        for registration in self._registrations:
+            self._state_owner.set_status(registration.name, HostedServiceStatus.STARTING)
+            try:
+                resolved = await container.get(registration.service_type)
+            except BaseException as original_error:
+                self._state_owner.set_status(registration.name, HostedServiceStatus.FAILED)
+                raise HostedServiceLifecycleError(
+                    service=registration.name,
+                    operation="resolve",
+                    error_type=type(original_error).__name__,
+                ) from None
+            if not isinstance(resolved, registration.service_type):
+                self._state_owner.set_status(registration.name, HostedServiceStatus.FAILED)
+                raise HostedServiceLifecycleError(
+                    service=registration.name,
+                    operation="resolve",
+                    error_type="InvalidRuntimeInstance",
+                )
+            bridge = _HostedServiceBridge(
+                name=registration.name,
+                loop=asyncio.get_running_loop(),
+                container=container,
+                catalog=application_service_catalog,
+                limit=self._options.max_pending_invocations,
+            )
+            context = HostedServiceContext(registration.name, bridge)
+            entry = _HostedServiceEntry(registration, resolved, context, bridge)
+            self._entries.append(entry)
+            bridge.open()
+            await self._start_entry(entry)
+
+    def close_admission(self) -> None:
+        for entry in self._entries:
+            entry.bridge.close()
+
+    async def stop(
+        self,
+        reason: ShutdownReason,
+    ) -> tuple[HostedServiceLifecycleError, ...]:
+        if not self._started and not self._entries:
+            return ()
+        self.close_admission()
+        failures: list[HostedServiceLifecycleError] = []
+        for entry in reversed(self._entries):
+            name = entry.registration.name
+            self._state_owner.set_status(name, HostedServiceStatus.STOPPING)
+            failure = await self._stop_entry(entry, reason)
+            if failure is not None:
+                failures.append(failure)
+
+        if self._entries:
+            await asyncio.gather(
+                *(
+                    entry.bridge.drain(self._options.shutdown_timeout.total_seconds())
+                    for entry in self._entries
+                )
+            )
+        failed_names = {failure.service for failure in failures}
+        for entry in self._entries:
+            name = entry.registration.name
+            self._state_owner.set_status(
+                name,
+                HostedServiceStatus.FAILED if name in failed_names else HostedServiceStatus.STOPPED,
+            )
+        self._started = False
+        return tuple(failures)
+
+    async def _start_entry(self, entry: _HostedServiceEntry) -> None:
+        name = entry.registration.name
+        callback = cast(
+            Callable[[HostedServiceContext], Awaitable[object]],
+            entry.service.start,
+        )
+
+        async def invoke_start() -> object:
+            return await callback(entry.context)
+
+        start_task = asyncio.create_task(
+            invoke_start(),
+            name=f"python-platform-hosted-service-start:{name}",
+        )
+        try:
+            done, _ = await asyncio.wait(
+                (start_task,),
+                timeout=self._options.startup_timeout.total_seconds(),
+                return_when=asyncio.FIRST_COMPLETED,
+            )
+        except BaseException as original_error:
+            # coordinator 创建的 start task 必须由 coordinator 收口；否则取消外层
+            # Application.start 会留下仍在运行、却已失去 owner 的 SDK bootstrap。
+            start_task.cancel()
+            await asyncio.gather(start_task, return_exceptions=True)
+            self._state_owner.set_status(name, HostedServiceStatus.FAILED)
+            raise HostedServiceLifecycleError(
+                service=name,
+                operation="start",
+                error_type=type(original_error).__name__,
+            ) from None
+        if start_task not in done:
+            start_task.cancel()
+            await asyncio.gather(start_task, return_exceptions=True)
+            self._state_owner.set_status(name, HostedServiceStatus.FAILED)
+            raise HostedServiceLifecycleError(
+                service=name, operation="start", error_type="TimeoutError"
+            )
+        try:
+            result = start_task.result()
+        except BaseException as original_error:
+            self._state_owner.set_status(name, HostedServiceStatus.FAILED)
+            raise HostedServiceLifecycleError(
+                service=name,
+                operation="start",
+                error_type=type(original_error).__name__,
+            ) from None
+        if result is not None:
+            self._state_owner.set_status(name, HostedServiceStatus.FAILED)
+            raise HostedServiceLifecycleError(
+                service=name,
+                operation="start",
+                error_type="InvalidReturnValue",
+            )
+        self._state_owner.set_status(name, HostedServiceStatus.RUNNING)
+
+    async def _stop_entry(
+        self,
+        entry: _HostedServiceEntry,
+        reason: ShutdownReason,
+    ) -> HostedServiceLifecycleError | None:
+        name = entry.registration.name
+        callback = cast(
+            Callable[[ShutdownReason], Awaitable[object]],
+            entry.service.stop,
+        )
+
+        async def invoke_stop() -> object:
+            return await callback(reason)
+
+        stop_task = asyncio.create_task(
+            invoke_stop(), name=f"python-platform-hosted-service-stop:{name}"
+        )
+        done, _ = await asyncio.wait(
+            (stop_task,), timeout=self._options.shutdown_timeout.total_seconds()
+        )
+        timed_out = not done
+        if timed_out:
+            # 取消只是一项请求。实现可能在 finally 中异步释放 SDK 资源；完成前不能释放容器。
+            stop_task.cancel()
+        try:
+            result = await stop_task
+        except BaseException as original_error:
+            return HostedServiceLifecycleError(
+                service=name,
+                operation="stop",
+                error_type="TimeoutError"
+                if timed_out and isinstance(original_error, asyncio.CancelledError)
+                else type(original_error).__name__,
+            )
+        if timed_out:
+            return HostedServiceLifecycleError(
+                service=name, operation="stop", error_type="TimeoutError"
+            )
+        if result is not None:
+            return HostedServiceLifecycleError(
+                service=name,
+                operation="stop",
+                error_type="InvalidReturnValue",
+            )
+        return None

python_platform/hosted_services/state.py

@@ -0,0 +1,40 @@
+"""Application 所属 loop 修改生命周期状态；公开快照不持有可变状态。"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from ..lifecycle import ApplicationState
+from .catalog import HostedServiceRegistration
+from .contracts import HostedServiceStatus
+
+
+@dataclass(frozen=True, slots=True)
+class HostedServiceSnapshot:
+    name: str
+    status: HostedServiceStatus
+
+
+@dataclass(frozen=True, slots=True)
+class ApplicationReadinessSnapshot:
+    ready: bool
+    services: tuple[HostedServiceSnapshot, ...]
+
+
+class _HostedServiceStateOwner:
+    def __init__(self, registrations: tuple[HostedServiceRegistration, ...]) -> None:
+        self._states = {item.name: HostedServiceStatus.STOPPED for item in registrations}
+
+    def set_status(self, name: str, status: HostedServiceStatus) -> None:
+        self._states[name] = status
+
+    def snapshot(self, application_state: ApplicationState) -> ApplicationReadinessSnapshot:
+        return ApplicationReadinessSnapshot(
+            # Module 已完成 runtime hook 时 Application 可能已为 RUNNING；全部服务
+            # start 返回之前仍不能报告启动完成，这不是服务自报的连接健康度。
+            ready=application_state is ApplicationState.RUNNING
+            and all(state is HostedServiceStatus.RUNNING for state in self._states.values()),
+            services=tuple(
+                HostedServiceSnapshot(name, state) for name, state in self._states.items()
+            ),
+        )

python_platform/hosting/__init__.py

@@ -0,0 +1,4 @@
+"""正式 Host 的进程身份与运行控制；测试 Application 不占用 Host 位置。"""
+
+# 控制变量不进入业务配置前缀，避免与严格 Options 字段发生冲突。
+ENVIRONMENT_VARIABLE = "PYTHON_PLATFORM_ENVIRONMENT"

python_platform/hosting/instance.py

@@ -0,0 +1,40 @@
+"""同一实际项目目录和环境的进程位置；占用事实由操作系统锁决定。"""
+
+from __future__ import annotations
+
+import hashlib
+import sys
+from pathlib import Path
+
+from filelock import BaseFileLock, UnixFileLock, WindowsFileLock
+
+
+def _instance_lock(project: Path, environment: str, position: str = "host") -> BaseFileLock:
+    # 锁放在解析后的项目下，避免相对路径、junction/symlink 或不同用户的临时目录分裂身份。
+    # environment/position 只参与摘要，不作为路径片段，且互相独立编码避免拼接碰撞。
+    identity = hashlib.sha256(repr((environment, position)).encode()).hexdigest()
+    path = project.resolve(strict=True) / ".python-platform" / "locks" / f"{identity}.lock"
+    return _native_lock(path)
+
+
+def _native_lock(path: Path) -> BaseFileLock:
+    path = _native_path(path)
+    lock_type = WindowsFileLock if sys.platform == "win32" else UnixFileLock
+    return lock_type(
+        path,
+        timeout=0,
+        fallback_to_soft=False,
+        preserve_lock_file=True,
+    )
+
+
+def _native_path(path: Path) -> Path:
+    # Windows Unicode 长路径语法不依赖进程 manifest／注册表；不 resolve 最后的锁文件，
+    # 保留 filelock 自身对 symlink/reparse point 的拒绝，实际项目目录已由调用方解析。
+    if sys.platform == "win32":
+        value = str(path)
+        if value.startswith("\\\\?\\"):
+            return path
+        return Path("\\\\?\\UNC\\" + value[2:] if value.startswith("\\\\") else "\\\\?\\" + value)
+    else:
+        return path

python_platform/identity/__init__.py

@@ -0,0 +1,73 @@
+from .contracts import (
+    IDENTITY_ROLES_MANAGE,
+    IDENTITY_USERS_MANAGE,
+    AuthenticationApplicationService,
+    CreateRoleCommand,
+    CreateUserCommand,
+    CurrentUserView,
+    IdentityAccessStore,
+    IdentityLoginStore,
+    IdentityManagementApplicationService,
+    IdentityOptions,
+    IdentityRepository,
+    IdentityRole,
+    IdentityUser,
+    LoginCommand,
+    RefreshRotationResult,
+    RefreshRotationStatus,
+    RefreshSession,
+    RefreshSessionStore,
+    RefreshTokenCommand,
+    RevokeTokenCommand,
+    RoleView,
+    SetRolePermissionsCommand,
+    SetUserRolesCommand,
+    TokenPair,
+    UserView,
+)
+from .errors import (
+    IdentityConflictError,
+    IdentityDefinitionError,
+    IdentityResourceNotFoundError,
+    InvalidCredentialsError,
+)
+from .module import IdentityModule
+from .passwords import PasswordHasher
+from .services import IdentityAuthenticator
+from .tokens import JwtTokenService
+
+__all__ = (
+    "IDENTITY_ROLES_MANAGE",
+    "IDENTITY_USERS_MANAGE",
+    "AuthenticationApplicationService",
+    "CreateRoleCommand",
+    "CreateUserCommand",
+    "CurrentUserView",
+    "IdentityAccessStore",
+    "IdentityAuthenticator",
+    "IdentityConflictError",
+    "IdentityDefinitionError",
+    "IdentityLoginStore",
+    "IdentityManagementApplicationService",
+    "IdentityModule",
+    "IdentityOptions",
+    "IdentityRepository",
+    "IdentityResourceNotFoundError",
+    "IdentityRole",
+    "IdentityUser",
+    "InvalidCredentialsError",
+    "JwtTokenService",
+    "LoginCommand",
+    "PasswordHasher",
+    "RefreshRotationResult",
+    "RefreshRotationStatus",
+    "RefreshSession",
+    "RefreshSessionStore",
+    "RefreshTokenCommand",
+    "RevokeTokenCommand",
+    "RoleView",
+    "SetRolePermissionsCommand",
+    "SetUserRolesCommand",
+    "TokenPair",
+    "UserView",
+)