python-platform 0.1.1__py3-none-any.whl

python_platform/authorization/contracts.py

@@ -0,0 +1,241 @@
+"""不可变身份、Permission contract 与静态授权 metadata。"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Protocol, TypeVar, runtime_checkable
+from uuid import UUID
+
+from .errors import AuthorizationDefinitionError, PermissionDefinitionError
+
+_AUTHORIZATION_ATTRIBUTE = "__python_platform_authorization__"
+_ALLOW_ANONYMOUS_ATTRIBUTE = "__python_platform_allow_anonymous__"
+_TDecorated = TypeVar("_TDecorated")
+
+
+@dataclass(frozen=True, order=True, slots=True)
+class PermissionName:
+    value: str
+
+    def __post_init__(self) -> None:
+        if (
+            not isinstance(self.value, str)
+            or not self.value
+            or self.value != self.value.strip()
+            or self.value.startswith(".")
+            or self.value.endswith(".")
+            or ".." in self.value
+            or any(not (item.isalnum() or item in "._-") for item in self.value)
+        ):
+            raise PermissionDefinitionError(
+                permission=self.value if isinstance(self.value, str) else repr(self.value),
+                reason="name must be a trimmed dotted identifier",
+            )
+
+    def __str__(self) -> str:
+        return self.value
+
+
+@dataclass(frozen=True, slots=True)
+class PermissionDefinition:
+    name: PermissionName
+    display_name: str
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.name, PermissionName):
+            raise PermissionDefinitionError(
+                permission=repr(self.name),
+                reason="name must be PermissionName",
+            )
+        if (
+            not isinstance(self.display_name, str)
+            or not self.display_name
+            or self.display_name != self.display_name.strip()
+        ):
+            raise PermissionDefinitionError(
+                permission=str(self.name),
+                reason="display_name must be a non-empty trimmed string",
+            )
+
+
+@dataclass(frozen=True, order=True, slots=True)
+class RolePermissionVersion:
+    role_id: UUID
+    version: int
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.role_id, UUID):
+            raise TypeError("role_id must be UUID")
+        if not isinstance(self.version, int) or isinstance(self.version, bool) or self.version < 0:
+            raise ValueError("role permission version must be a non-negative integer")
+
+
+@dataclass(frozen=True, slots=True)
+class CurrentUser:
+    """一次可信入口已验证的身份快照；不携带权限集合。"""
+
+    user_id: UUID | None = None
+    session_id: UUID | None = None
+    username: str | None = None
+    permission_version: int = 0
+    role_versions: tuple[RolePermissionVersion, ...] = ()
+
+    def __post_init__(self) -> None:
+        identity_values = (self.user_id, self.session_id, self.username)
+        is_anonymous = all(value is None for value in identity_values)
+        if not is_anonymous and (
+            not isinstance(self.user_id, UUID)
+            or not isinstance(self.session_id, UUID)
+            or not isinstance(self.username, str)
+            or not self.username
+            or self.username != self.username.strip()
+        ):
+            raise ValueError("authenticated CurrentUser requires user_id, session_id and username")
+        if is_anonymous and (self.permission_version != 0 or self.role_versions):
+            raise ValueError("anonymous CurrentUser cannot carry authorization versions")
+        if not isinstance(self.permission_version, int) or isinstance(
+            self.permission_version, bool
+        ):
+            raise TypeError("permission_version must be int")
+        if self.permission_version < 0:
+            raise ValueError("permission_version must be non-negative")
+        if not isinstance(self.role_versions, tuple) or any(
+            not isinstance(item, RolePermissionVersion) for item in self.role_versions
+        ):
+            raise TypeError("role_versions must be an immutable RolePermissionVersion tuple")
+        if tuple(sorted(self.role_versions)) != self.role_versions:
+            raise ValueError("role_versions must be sorted by role_id and version")
+        if len({item.role_id for item in self.role_versions}) != len(self.role_versions):
+            raise ValueError("role_versions cannot contain duplicate role ids")
+
+    @property
+    def is_authenticated(self) -> bool:
+        return self.user_id is not None
+
+    @classmethod
+    def anonymous(cls) -> CurrentUser:
+        return cls()
+
+
+@runtime_checkable
+class PermissionChecker(Protocol):
+    async def is_granted(self, user: CurrentUser, permission: PermissionName) -> bool: ...
+
+
+@runtime_checkable
+class AccessTokenAuthenticator(Protocol):
+    async def authenticate_access_token(self, token: str) -> CurrentUser: ...
+
+
+@dataclass(frozen=True, slots=True)
+class _AuthorizationMetadata:
+    permissions: tuple[PermissionName, ...]
+
+
+@dataclass(frozen=True, slots=True)
+class _AuthorizationRequirement:
+    requires_authenticated_user: bool
+    permissions: tuple[PermissionName, ...]
+    allows_anonymous: bool
+
+
+def authorize(*permissions: PermissionName) -> Callable[[_TDecorated], _TDecorated]:
+    """声明登录或 all-of Permission 要求；只接受集中定义的 PermissionName。"""
+
+    if any(not isinstance(permission, PermissionName) for permission in permissions):
+        raise AuthorizationDefinitionError(
+            symbol="<decorator>",
+            reason="authorize permissions must be PermissionName values",
+        )
+    if len(set(permissions)) != len(permissions):
+        raise AuthorizationDefinitionError(
+            symbol="<decorator>",
+            reason="authorize permissions cannot contain duplicates",
+        )
+    metadata = _AuthorizationMetadata(permissions=permissions)
+
+    def decorate(target: _TDecorated) -> _TDecorated:
+        _validate_authorization_target(target)
+        namespace = vars(target)
+        symbol = _symbol(target)
+        if _AUTHORIZATION_ATTRIBUTE in namespace or _ALLOW_ANONYMOUS_ATTRIBUTE in namespace:
+            raise AuthorizationDefinitionError(
+                symbol=symbol,
+                reason="authorization metadata may only be declared once",
+            )
+        setattr(target, _AUTHORIZATION_ATTRIBUTE, metadata)
+        return target
+
+    return decorate
+
+
+def allow_anonymous(target: _TDecorated) -> _TDecorated:
+    """Method metadata 明确覆盖 class 级授权；不靠命名或默认回退推断。"""
+
+    _validate_authorization_target(target)
+    namespace = vars(target)
+    symbol = _symbol(target)
+    if _AUTHORIZATION_ATTRIBUTE in namespace or _ALLOW_ANONYMOUS_ATTRIBUTE in namespace:
+        raise AuthorizationDefinitionError(
+            symbol=symbol,
+            reason="authorization metadata may only be declared once",
+        )
+    setattr(target, _ALLOW_ANONYMOUS_ATTRIBUTE, True)
+    return target
+
+
+def _authorization_requirement(
+    implementation: type[object],
+    method: object,
+) -> _AuthorizationRequirement:
+    # 只从仲裁胜出的实现继承链合并类声明；Contract 不再是策略来源。
+    class_metadata = tuple(
+        metadata
+        for owner in reversed(implementation.__mro__)
+        if (metadata := _metadata_for(owner)) is not None
+    )
+    method_metadata = _metadata_for(method)
+    method_allows_anonymous = vars(method).get(_ALLOW_ANONYMOUS_ATTRIBUTE, False)
+    if method_allows_anonymous:
+        return _AuthorizationRequirement(False, (), True)
+    permissions: list[PermissionName] = []
+    for metadata in (*class_metadata, method_metadata):
+        if metadata is None:
+            continue
+        for permission in metadata.permissions:
+            if permission not in permissions:
+                permissions.append(permission)
+    requires_user = bool(class_metadata) or method_metadata is not None
+    return _AuthorizationRequirement(requires_user, tuple(permissions), False)
+
+
+def _metadata_for(target: object) -> _AuthorizationMetadata | None:
+    namespace = vars(target)
+    metadata = namespace.get(_AUTHORIZATION_ATTRIBUTE)
+    anonymous = namespace.get(_ALLOW_ANONYMOUS_ATTRIBUTE, False)
+    if metadata is not None and not isinstance(metadata, _AuthorizationMetadata):
+        raise AuthorizationDefinitionError(
+            symbol=_symbol(target),
+            reason="authorization metadata has an invalid runtime shape",
+        )
+    if not isinstance(anonymous, bool):
+        raise AuthorizationDefinitionError(
+            symbol=_symbol(target),
+            reason="allow_anonymous metadata has an invalid runtime shape",
+        )
+    return metadata
+
+
+def _validate_authorization_target(target: object) -> None:
+    if not isinstance(target, type) and not callable(target):
+        raise AuthorizationDefinitionError(
+            symbol=repr(target),
+            reason="authorization decorator target must be a class or callable",
+        )
+
+
+def _symbol(target: object) -> str:
+    module = getattr(target, "__module__", type(target).__module__)
+    qualname = getattr(target, "__qualname__", type(target).__qualname__)
+    return f"{module}.{qualname}"

python_platform/authorization/definition_discovery.py

@@ -0,0 +1,81 @@
+"""从冻结类型结果解释权限定义，拥有贡献顺序、来源与冲突检查。"""
+
+from __future__ import annotations
+
+import inspect
+from collections.abc import Callable
+from typing import cast
+
+from ..diagnostics import SourceLocation
+from ..modularity import ModuleRegistry
+from ..modularity.discovery import _DiscoveredType
+from .contracts import PermissionDefinition, PermissionName
+from .definitions import PermissionDefinitionContext, PermissionDefinitionProvider
+from .errors import PermissionDefinitionError
+
+
+def _collect_permission_definitions(
+    registry: ModuleRegistry,
+    discoveries: tuple[_DiscoveredType, ...],
+) -> tuple[PermissionDefinition, ...]:
+    positions = {item.key: index for index, item in enumerate(registry.dependency_order)}
+    providers: dict[type[object], SourceLocation] = {}
+    sources: dict[PermissionName, SourceLocation] = {}
+    definitions: list[PermissionDefinition] = []
+    for discovery in sorted(
+        discoveries,
+        key=lambda item: (
+            positions[item.owner],
+            f"{item.candidate.__module__}.{item.candidate.__qualname__}",
+        ),
+    ):
+        candidate = discovery.candidate
+        if not issubclass(candidate, PermissionDefinitionProvider) or inspect.isabstract(candidate):
+            continue
+        previous = providers.get(candidate)
+        if previous is not None:
+            if previous.owner != discovery.source.owner:
+                raise PermissionDefinitionError(
+                    permission=candidate.__qualname__,
+                    reason=f"provider is already owned by {previous}",
+                    source=discovery.source,
+                )
+            continue
+        providers[candidate] = discovery.source
+        for definition in _define(candidate, discovery.source):
+            if definition.name in sources:
+                raise PermissionDefinitionError(
+                    permission=str(definition.name),
+                    reason=f"permission is already owned by {sources[definition.name]}",
+                    source=discovery.source,
+                )
+            sources[definition.name] = discovery.source
+            definitions.append(definition)
+    return tuple(definitions)
+
+
+def _define(
+    provider_type: type[PermissionDefinitionProvider],
+    source: SourceLocation,
+) -> tuple[PermissionDefinition, ...]:
+    context = PermissionDefinitionContext(source)
+    try:
+        provider = provider_type()
+        callback = cast(Callable[[PermissionDefinitionContext], object], provider.define)
+        if inspect.iscoroutinefunction(callback) or inspect.isasyncgenfunction(callback):
+            raise TypeError("define must be synchronous")
+        result = callback(context)
+        if result is not None:
+            if inspect.iscoroutine(result) or inspect.isgenerator(result):
+                result.close()
+            raise TypeError("define must return None")
+    except Exception as error:
+        raise PermissionDefinitionError(
+            permission=provider_type.__qualname__,
+            reason=f"definition provider failed: {type(error).__name__}: {error}",
+            source=source,
+        ) from error
+    finally:
+        # 即使构造或贡献失败，已逸出的上下文也不可再写入。
+        definitions = context._close()
+    return definitions

python_platform/authorization/definitions.py

@@ -0,0 +1,43 @@
+"""权限定义的同步贡献契约；上下文由单次 Application build 独占。"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+from ..diagnostics import SourceLocation
+from .contracts import PermissionDefinition
+from .errors import PermissionDefinitionError
+
+
+class PermissionDefinitionProvider(ABC):
+    @abstractmethod
+    def define(self, context: PermissionDefinitionContext) -> None:
+        """同步贡献静态权限定义；无构造注入、I/O 或运行期服务解析。"""
+
+
+class PermissionDefinitionContext:
+    __slots__ = ("_closed", "_definitions", "_source")
+
+    def __init__(self, source: SourceLocation) -> None:
+        self._source = source
+        self._definitions: list[PermissionDefinition] = []
+        self._closed = False
+
+    def add(self, definition: PermissionDefinition) -> None:
+        if self._closed:
+            raise PermissionDefinitionError(
+                permission="context",
+                reason="definition context is closed",
+                source=self._source,
+            )
+        if not isinstance(definition, PermissionDefinition):
+            raise PermissionDefinitionError(
+                permission="context",
+                reason="expected PermissionDefinition",
+                source=self._source,
+            )
+        self._definitions.append(definition)
+
+    def _close(self) -> tuple[PermissionDefinition, ...]:
+        self._closed = True
+        return tuple(self._definitions)

python_platform/authorization/errors.py

@@ -0,0 +1,40 @@
+"""Authorization metadata、身份与权限判定的公开失败语义。"""
+
+from __future__ import annotations
+
+from ..diagnostics import SourceLocation
+from ..errors.base import FrameworkError
+
+
+class PermissionDefinitionError(FrameworkError):
+    def __init__(
+        self, *, permission: str, reason: str, source: SourceLocation | None = None
+    ) -> None:
+        self.permission = permission
+        self.reason = reason
+        self.source = source
+        location = "" if source is None else f" at {source}"
+        super().__init__(f"Invalid permission {permission!r}{location}: {reason}")
+
+
+class AuthorizationDefinitionError(FrameworkError):
+    def __init__(self, *, symbol: str, reason: str) -> None:
+        self.symbol = symbol
+        self.reason = reason
+        super().__init__(f"Invalid authorization metadata for {symbol}: {reason}")
+
+
+class UnauthenticatedError(FrameworkError):
+    def __init__(self) -> None:
+        super().__init__("Authentication is required")
+
+
+class PermissionDeniedError(FrameworkError):
+    def __init__(self, *, permission: str) -> None:
+        self.permission = permission
+        super().__init__(f"Permission {permission!r} is required")
+
+
+class PermissionCheckerUnavailableError(FrameworkError):
+    def __init__(self) -> None:
+        super().__init__("A protected Application Service requires a PermissionChecker")

python_platform/background_execution/__init__.py

@@ -0,0 +1,15 @@
+"""任务执行位置、状态与管理的稳定契约。"""
+
+from .contracts import (
+    BackgroundExecutionMode,
+    BackgroundTaskOptions,
+    BackgroundTaskSnapshot,
+    BackgroundTaskState,
+)
+
+__all__ = (
+    "BackgroundExecutionMode",
+    "BackgroundTaskOptions",
+    "BackgroundTaskSnapshot",
+    "BackgroundTaskState",
+)

python_platform/background_execution/application.py

@@ -0,0 +1,41 @@
+"""授权后将操作交给 Application owner；不等待任务业务，也不保留 REQUEST 资源。"""
+
+from ..application_services import ApplicationService, application_service
+from ..authorization import authorize
+from ..background_workers.runtime import _BackgroundCoordinator
+from ..errors import ResourceConflictError, ResourceNotFoundError
+from .contracts import BackgroundTaskSnapshot
+from .management import BACKGROUND_MANAGE, BACKGROUND_VIEW, BackgroundManagementApplicationService
+
+
+@application_service(provides=BackgroundManagementApplicationService)
+class _BackgroundManagementApplicationService(ApplicationService):
+    def __init__(self, coordinator: _BackgroundCoordinator) -> None:
+        self._coordinator = coordinator
+
+    @authorize(BACKGROUND_VIEW)
+    async def get_list(self) -> tuple[BackgroundTaskSnapshot, ...]:
+        return self._coordinator.snapshots()
+
+    @authorize(BACKGROUND_VIEW)
+    async def get(self, task_id: str) -> BackgroundTaskSnapshot:
+        for snapshot in self._coordinator.snapshots():
+            if snapshot.id == task_id:
+                return snapshot
+        raise ResourceNotFoundError("Background task does not exist")
+
+    @authorize(BACKGROUND_MANAGE)
+    async def start(self, task_id: str) -> BackgroundTaskSnapshot:
+        return self._request(task_id, start=True)
+
+    @authorize(BACKGROUND_MANAGE)
+    async def stop(self, task_id: str) -> BackgroundTaskSnapshot:
+        return self._request(task_id, start=False)
+
+    def _request(self, task_id: str, *, start: bool) -> BackgroundTaskSnapshot:
+        try:
+            return self._coordinator.request(task_id, start=start)
+        except KeyError:
+            raise ResourceNotFoundError("Background task does not exist") from None
+        except ValueError as error:
+            raise ResourceConflictError(str(error)) from None

python_platform/background_execution/child.py

@@ -0,0 +1,123 @@
+"""spawn 子进程入口；管道是父进程许可与存活边界，Application 独立重建。"""
+
+from __future__ import annotations
+
+import asyncio
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from multiprocessing.connection import _ConnectionBase as Connection
+
+from ..application import Application
+from ..application.build_spec import _ApplicationBuildSpec
+from ..errors import ApplicationStartError
+from ..lifecycle import ApplicationState
+from .contracts import BackgroundTaskOptions
+from .locks import _position_lock
+from .processes import _POLL_INTERVAL, _Message
+
+
+def _run_child(
+    spec: _ApplicationBuildSpec,
+    position: str,
+    tasks: dict[str, BackgroundTaskOptions],
+    initial: tuple[str, ...],
+    pipe: Connection,
+) -> None:
+    try:
+        with _position_lock(spec.project, spec.environment, position):
+            pipe.send((_Message.LOCKED,))
+            if pipe.recv() != (_Message.GO,):
+                raise RuntimeError("Background process has no parent permission")
+            asyncio.run(_serve_child(spec, tasks, initial, pipe))
+    except (EOFError, BrokenPipeError):
+        # 父进程已退出，执行许可已撤销；异步入口的 finally 仍先完成 Application 清理。
+        pass
+    except BaseException as error:
+        try:
+            if isinstance(error, ApplicationStartError) and error.cleanup_failures:
+                pipe.send((_Message.CLEANUP_FAILED, type(error).__name__))
+            pipe.send((_Message.FAILED, type(error).__name__))
+        except (EOFError, OSError):
+            pass
+    finally:
+        pipe.close()
+
+
+async def _serve_child(
+    spec: _ApplicationBuildSpec,
+    tasks: dict[str, BackgroundTaskOptions],
+    initial: tuple[str, ...],
+    pipe: Connection,
+) -> None:
+    application = spec.build()
+    application._root.require_hosted_service_coordinator().select_child()
+    coordinator = application._root.require_background_coordinator()
+    coordinator.select_child(tasks, initial)
+    try:
+        await _start_while_parent_present(application, pipe)
+        previous = coordinator.snapshots()
+        while True:
+            if pipe.poll():
+                command = pipe.recv()
+                if command[0] == _Message.SHUTDOWN:
+                    break
+                action, serial, key = command
+                if action not in (_Message.START, _Message.STOP):
+                    raise RuntimeError("Unknown background process command")
+                try:
+                    snapshot = coordinator.request(key, start=action == _Message.START)
+                except (KeyError, ValueError) as error:
+                    pipe.send((_Message.REJECTED, serial, type(error).__name__))
+                else:
+                    pipe.send((_Message.RESULT, serial, snapshot))
+            snapshots = coordinator.snapshots()
+            if snapshots != previous:
+                pipe.send((_Message.SNAPSHOTS, snapshots))
+                previous = snapshots
+            if application.state in (
+                ApplicationState.STOPPED,
+                ApplicationState.STOPPED_WITH_ERRORS,
+            ):
+                await application.wait_for_termination()
+                break
+            await asyncio.sleep(_POLL_INTERVAL)
+    finally:
+        await _stop_child(application, pipe)
+
+
+async def _start_while_parent_present(application: Application, pipe: Connection) -> None:
+    async def start() -> None:
+        await application.start()
+        # 启动确认与 start 返回处于同一 task 连续段；首轮业务崩溃不能被误判为初始化失败。
+        pipe.send(
+            (_Message.SNAPSHOTS, application._root.require_background_coordinator().snapshots())
+        )
+        pipe.send((_Message.READY,))
+
+    starting = asyncio.create_task(start())
+    try:
+        while not starting.done():
+            if pipe.poll():
+                if pipe.recv() != (_Message.SHUTDOWN,):
+                    raise RuntimeError("Unexpected command during child initialization")
+                starting.cancel()
+                break
+            await asyncio.sleep(_POLL_INTERVAL)
+        await starting
+    finally:
+        if not starting.done():
+            # EOF／父进程 shutdown 只请求一次取消，Application 仍独占 partial-start 清理。
+            starting.cancel()
+            await starting
+
+
+async def _stop_child(application: Application, pipe: Connection) -> None:
+    try:
+        await application.stop()
+    except BaseException as error:
+        try:
+            pipe.send((_Message.CLEANUP_FAILED, type(error).__name__))
+        except (EOFError, OSError):
+            pass
+        raise

python_platform/background_execution/contracts.py

@@ -0,0 +1,39 @@
+"""执行模式与只读状态；不依赖 provider、进程或编排实现。"""
+
+from enum import Enum
+
+from pydantic import BaseModel, ConfigDict
+
+from ..options import BaseOptions
+
+
+class BackgroundExecutionMode(str, Enum):
+    HOST = "host"
+    SHARED = "shared"
+    EXCLUSIVE = "exclusive"
+
+
+class BackgroundTaskOptions(BaseOptions):
+    enabled: bool = True
+    mode: BackgroundExecutionMode = BackgroundExecutionMode.HOST
+
+
+class BackgroundTaskState(str, Enum):
+    DISABLED = "disabled"
+    STARTING = "starting"
+    RUNNING = "running"
+    STOPPING = "stopping"
+    STOPPED = "stopped"
+    FAILED = "failed"
+
+
+class BackgroundTaskSnapshot(BaseModel):
+    model_config = ConfigDict(frozen=True)
+
+    id: str
+    enabled: bool
+    mode: BackgroundExecutionMode
+    state: BackgroundTaskState
+    process_id: int | None = None
+    restart_count: int = 0
+    error_type: str | None = None

python_platform/background_execution/lifecycle.py

@@ -0,0 +1,22 @@
+"""本进程执行单元的生命周期回调及失败事实；由 Worker／持久队列提供。"""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass, field
+
+
+@dataclass(frozen=True, slots=True)
+class _BackgroundRuntimeFailure:
+    component: str
+    error_type: str
+    _source: object = field(default_factory=object, repr=False, compare=False)
+
+
+@dataclass(frozen=True, slots=True)
+class _TaskExecution:
+    start: Callable[[], Awaitable[None]]
+    stop_claiming: Callable[[], None]
+    wait: Callable[[], Awaitable[None]]
+    wait_for_failure: Callable[[], Awaitable[_BackgroundRuntimeFailure]] | None
+    cancel_for_deadline: Callable[[], None]