python-platform 0.1.1__py3-none-any.whl

python_platform/background_execution/local.py

@@ -0,0 +1,127 @@
+"""单个本地任务的启停 owner；已接受操作由 Application 持有而不属于 HTTP request。"""
+
+from __future__ import annotations
+
+import asyncio
+import os
+from collections.abc import Callable
+from contextvars import Context
+
+from .contracts import BackgroundTaskOptions, BackgroundTaskSnapshot, BackgroundTaskState
+from .lifecycle import _BackgroundRuntimeFailure, _TaskExecution
+
+
+class _LocalTask:
+    def __init__(
+        self,
+        key: str,
+        options: BackgroundTaskOptions,
+        deadline: float,
+        failed: Callable[[_BackgroundRuntimeFailure], None],
+    ) -> None:
+        self.key = key
+        self.options = options
+        self.deadline = deadline
+        self.state = (
+            BackgroundTaskState.STOPPED if options.enabled else BackgroundTaskState.DISABLED
+        )
+        self.error_type: str | None = None
+        self.execution: _TaskExecution | None = None
+        self.operation: asyncio.Task[None] | None = None
+        self._failed = failed
+        self._monitor: asyncio.Task[None] | None = None
+
+    async def start(self) -> None:
+        self.state = BackgroundTaskState.STARTING
+        if self.execution is None:
+            raise RuntimeError("Task execution provider is unavailable")
+        await self.execution.start()
+        self.state = BackgroundTaskState.RUNNING
+        if self.execution.wait_for_failure is not None:
+            self._monitor = asyncio.create_task(
+                self._watch(), name=f"background-failure:{self.key}"
+            )
+
+    async def _watch(self) -> None:
+        assert self.execution is not None and self.execution.wait_for_failure is not None
+        fact = await self.execution.wait_for_failure()
+        self.state = BackgroundTaskState.FAILED
+        self.error_type = fact.error_type
+        self._failed(fact)
+
+    def snapshot(self) -> BackgroundTaskSnapshot:
+        return BackgroundTaskSnapshot(
+            id=self.key,
+            enabled=self.options.enabled,
+            mode=self.options.mode,
+            state=self.state,
+            process_id=os.getpid(),
+            error_type=self.error_type,
+        )
+
+    def request(self, start: bool) -> BackgroundTaskSnapshot:
+        if not self.options.enabled:
+            raise ValueError("Code-disabled tasks cannot be enabled at runtime")
+        target = BackgroundTaskState.RUNNING if start else BackgroundTaskState.STOPPED
+        if self.operation is not None and not self.operation.done():
+            # 同方向重复请求合并；反向操作等待当前操作结束后再由调用者明确提交。
+            requested = BackgroundTaskState.STARTING if start else BackgroundTaskState.STOPPING
+            if self.state is not requested:
+                raise ValueError("A different task operation is in progress")
+            return self.snapshot()
+        if self.state is target:
+            return self.snapshot()
+        self.state = BackgroundTaskState.STARTING if start else BackgroundTaskState.STOPPING
+        self.error_type = None
+        # 接受后属于 APP；使用空上下文，避免继承已结束 REQUEST 的 UoW／caller。
+        self.operation = asyncio.create_task(
+            self._operate(start), name=f"background-operation:{self.key}", context=Context()
+        )
+        return self.snapshot()
+
+    async def _operate(self, start: bool) -> None:
+        try:
+            if start:
+                await self.start()
+            else:
+                await self._drain()
+            self.state = BackgroundTaskState.RUNNING if start else BackgroundTaskState.STOPPED
+        except BaseException as error:
+            self.error_type = type(error).__name__
+            self.state = BackgroundTaskState.FAILED
+            # 失败转为 Application-owned 状态供查询；task 不留下未观察异常。
+
+    async def shutdown(self) -> None:
+        if self.operation is not None:
+            await self.operation
+        if self.state not in (BackgroundTaskState.STOPPED, BackgroundTaskState.DISABLED):
+            self.state = BackgroundTaskState.STOPPING
+            try:
+                await self._drain()
+            except BaseException as error:
+                self.state = BackgroundTaskState.FAILED
+                self.error_type = type(error).__name__
+                raise
+            self.state = BackgroundTaskState.STOPPED
+
+    async def _drain(self) -> None:
+        if self._monitor is not None:
+            self._monitor.cancel()
+            await asyncio.gather(self._monitor, return_exceptions=True)
+            self._monitor = None
+        execution = self.execution
+        if execution is None:
+            return
+        execution.stop_claiming()
+        draining = asyncio.ensure_future(execution.wait())
+        _, pending = await asyncio.wait((draining,), timeout=self.deadline)
+        if pending:
+            execution.cancel_for_deadline()
+        outcomes = await asyncio.gather(draining, return_exceptions=True)
+        failures = tuple(
+            x
+            for x in outcomes
+            if isinstance(x, BaseException) and not isinstance(x, asyncio.CancelledError)
+        )
+        if failures:
+            raise BaseExceptionGroup("Background task drain failed", failures)

python_platform/background_execution/locks.py

@@ -0,0 +1,31 @@
+"""本地进程位置的 OS 锁目录；记录用于发现遗留位置，占用仍只以原生系统锁为准。"""
+
+import hashlib
+from pathlib import Path
+
+from filelock import BaseFileLock
+
+from ..hosting.instance import _native_lock, _native_path
+
+_OWNER_SUFFIX = ".owner.lock"
+
+
+def _lock_directory(project: Path, environment: str) -> Path:
+    identity = hashlib.sha256(environment.encode()).hexdigest()
+    return _native_path(project.resolve(strict=True) / ".python-platform" / "background" / identity)
+
+
+def _position_lock(
+    project: Path, environment: str, position: str, *, reservation: bool = False
+) -> BaseFileLock:
+    identity = hashlib.sha256(position.encode()).hexdigest()
+    suffix = ".reservation.lock" if reservation else _OWNER_SUFFIX
+    return _native_lock(_lock_directory(project, environment) / f"{identity}{suffix}")
+
+
+def _check_previous_owners(project: Path, environment: str) -> None:
+    # 任务配置已删除／改名也必须发现旧进程。文件存在不表示占用；逐个尝试原生锁，
+    # 空闲历史文件保留即可，不把其内容当成任务清单，不根据 PID 猜测生命周期。
+    for path in _lock_directory(project, environment).glob(f"*{_OWNER_SUFFIX}"):
+        with _native_lock(path):
+            pass

python_platform/background_execution/management.py

@@ -0,0 +1,17 @@
+"""框架后台管理的权限与应用服务契约。"""
+
+from typing import Protocol
+
+from ..application_services import ApplicationServiceContract
+from ..authorization import PermissionName
+from .contracts import BackgroundTaskSnapshot
+
+BACKGROUND_VIEW = PermissionName("background.view")
+BACKGROUND_MANAGE = PermissionName("background.manage")
+
+
+class BackgroundManagementApplicationService(ApplicationServiceContract, Protocol):
+    async def get_list(self) -> tuple[BackgroundTaskSnapshot, ...]: ...
+    async def get(self, task_id: str) -> BackgroundTaskSnapshot: ...
+    async def start(self, task_id: str) -> BackgroundTaskSnapshot: ...
+    async def stop(self, task_id: str) -> BackgroundTaskSnapshot: ...

python_platform/background_execution/module.py

@@ -0,0 +1,10 @@
+"""后台管理由 Host 显式选择，业务任务声明保持独立。"""
+
+from ..modularity import AppModule
+
+
+class BackgroundManagementModule(AppModule):
+    scan_packages = (
+        "python_platform.background_execution.application",
+        "python_platform.background_execution.permissions",
+    )

python_platform/background_execution/permissions.py

@@ -0,0 +1,14 @@
+"""框架统一定义后台管理权限，业务 Module 无需重复贡献。"""
+
+from ..authorization import (
+    PermissionDefinition,
+    PermissionDefinitionContext,
+    PermissionDefinitionProvider,
+)
+from .management import BACKGROUND_MANAGE, BACKGROUND_VIEW
+
+
+class BackgroundPermissionDefinitionProvider(PermissionDefinitionProvider):
+    def define(self, context: PermissionDefinitionContext) -> None:
+        context.add(PermissionDefinition(BACKGROUND_VIEW, "View background tasks"))
+        context.add(PermissionDefinition(BACKGROUND_MANAGE, "Manage background tasks"))

python_platform/background_execution/processes.py

@@ -0,0 +1,331 @@
+"""Application 拥有的单个子进程位置：预占、IPC、有限恢复与退出确认。"""
+
+from __future__ import annotations
+
+import asyncio
+import multiprocessing
+from contextvars import Context
+from enum import Enum, auto
+from multiprocessing.process import BaseProcess
+from multiprocessing.reduction import ForkingPickler
+from typing import TYPE_CHECKING
+
+from ..application.build_spec import _ApplicationBuildSpec
+from .contracts import BackgroundTaskOptions, BackgroundTaskSnapshot, BackgroundTaskState
+from .locks import _position_lock
+
+if TYPE_CHECKING:
+    from multiprocessing.connection import _ConnectionBase as Connection
+
+    from ..background_workers import BackgroundExecutionOptions
+
+_POLL_INTERVAL = 0.05
+
+
+class _Message(Enum):
+    LOCKED = auto()
+    GO = auto()
+    READY = auto()
+    FAILED = auto()
+    CLEANUP_FAILED = auto()
+    SNAPSHOTS = auto()
+    RESULT = auto()
+    REJECTED = auto()
+    START = auto()
+    STOP = auto()
+    SHUTDOWN = auto()
+
+
+class _ProcessSlot:
+    def __init__(
+        self,
+        position: str,
+        tasks: dict[str, BackgroundTaskOptions],
+        spec: _ApplicationBuildSpec,
+        options: BackgroundExecutionOptions,
+    ) -> None:
+        self.position = position
+        self.tasks = tasks
+        self.spec = spec
+        self.options = options
+        self._reservation = _position_lock(
+            spec.project, spec.environment, position, reservation=True
+        )
+        self._process: BaseProcess | None = None
+        self._pipe: Connection | None = None
+        self._monitor: asyncio.Task[None] | None = None
+        self._boot: asyncio.Future[None] | None = None
+        self._bootstrapped = False
+        self._cleanup_error: str | None = None
+        self._exited = asyncio.Event()
+        self._exited.set()
+        self._stopping = False
+        self._restart_count = 0
+        self._wanted: set[str] = set()
+        self._serial = 0
+        self._pending: dict[int, asyncio.Future[BackgroundTaskSnapshot]] = {}
+        self._operations: dict[str, asyncio.Task[None]] = {}
+        self._send_lock = asyncio.Lock()
+        self._launch_lock = asyncio.Lock()
+        self._snapshots = {
+            key: self._snapshot(
+                key, BackgroundTaskState.STOPPED if value.enabled else BackgroundTaskState.DISABLED
+            )
+            for key, value in tasks.items()
+        }
+
+    def reserve(self) -> None:
+        # 两把系统锁分别证明父进程预占和子进程存活。父进程在整个位置生命周期持有预占，
+        # 子进程拿到 owner 锁后还须收到 GO 才允许 build；父进程崩溃不会留下无主的执行许可。
+        ForkingPickler.dumps(self.spec)
+        self._reservation.acquire()
+        try:
+            with _position_lock(self.spec.project, self.spec.environment, self.position):
+                pass
+        except BaseException:
+            self._reservation.release()
+            raise
+
+    def snapshots(self) -> tuple[BackgroundTaskSnapshot, ...]:
+        return tuple(self._snapshots.values())
+
+    def _snapshot(
+        self, key: str, state: BackgroundTaskState, error_type: str | None = None
+    ) -> BackgroundTaskSnapshot:
+        return BackgroundTaskSnapshot(
+            id=key,
+            enabled=self.tasks[key].enabled,
+            mode=self.tasks[key].mode,
+            state=state,
+            error_type=error_type,
+            restart_count=self._restart_count,
+            process_id=self._process.pid if self._process is not None else None,
+        )
+
+    async def start(self) -> None:
+        self._wanted = {key for key, options in self.tasks.items() if options.enabled}
+        if self._wanted:
+            await self._launch()
+
+    async def _launch(self) -> None:
+        if self._process is not None and not self._process.is_alive():
+            # monitor 是唯一 join/close owner；退出事件只在系统确认退出后发布。
+            await self._exited.wait()
+        async with self._launch_lock:
+            if self._stopping or not self._wanted:
+                return
+            if self._process is None:
+                self._spawn()
+            if self._monitor is None or self._monitor.done():
+                self._monitor = asyncio.create_task(
+                    self._watch(), name=f"background-process:{self.position}"
+                )
+        assert self._boot is not None
+        await asyncio.shield(self._boot)
+
+    def _spawn(self) -> None:
+        from .child import _run_child
+
+        parent, child = multiprocessing.get_context("spawn").Pipe()
+        process = multiprocessing.get_context("spawn").Process(
+            target=_run_child,
+            args=(self.spec, self.position, self.tasks, tuple(self._wanted), child),
+            name=f"python-platform:{self.position}",
+        )
+        self._boot = asyncio.get_running_loop().create_future()
+        self._bootstrapped = False
+        self._cleanup_error = None
+        self._exited.clear()
+        self._process, self._pipe = process, parent
+        try:
+            process.start()
+            for key in self._wanted:
+                self._snapshots[key] = self._snapshot(key, BackgroundTaskState.STARTING)
+        except BaseException:
+            parent.close()
+            self._process = None
+            self._pipe = None
+            self._exited.set()
+            raise
+        finally:
+            child.close()
+
+    def request(self, key: str, start: bool) -> BackgroundTaskSnapshot:
+        if not self.tasks[key].enabled:
+            raise ValueError("Code-disabled tasks cannot be enabled at runtime")
+        current = self._snapshots[key]
+        target = BackgroundTaskState.RUNNING if start else BackgroundTaskState.STOPPED
+        pending = BackgroundTaskState.STARTING if start else BackgroundTaskState.STOPPING
+        operation = self._operations.get(key)
+        if operation is not None and not operation.done():
+            if (key in self._wanted) != start:
+                raise ValueError("A different task operation is in progress")
+            return current
+        if current.state in (BackgroundTaskState.STARTING, BackgroundTaskState.STOPPING):
+            if current.state is not pending:
+                raise ValueError("A different task operation is in progress")
+            return current
+        if current.state is target:
+            return current
+        if start:
+            self._wanted.add(key)
+        else:
+            self._wanted.discard(key)
+        self._snapshots[key] = self._snapshot(key, pending)
+        self._operations[key] = asyncio.create_task(
+            self._operate(key, start),
+            name=f"background-process-operation:{key}",
+            context=Context(),
+        )
+        return self._snapshots[key]
+
+    async def _operate(self, key: str, start: bool) -> None:
+        try:
+            if start and (self._process is None or not self._process.is_alive()):
+                self._restart_count = 0
+                await self._launch()
+            if self._process is None:
+                if not start:
+                    self._snapshots[key] = self._snapshot(key, BackgroundTaskState.STOPPED)
+                return
+            if self._boot is not None:
+                await asyncio.shield(self._boot)
+            self._serial += 1
+            serial = self._serial
+            result: asyncio.Future[BackgroundTaskSnapshot] = (
+                asyncio.get_running_loop().create_future()
+            )
+            self._pending[serial] = result
+            try:
+                await self._send((_Message.START if start else _Message.STOP, serial, key))
+                await result
+            finally:
+                self._pending.pop(serial, None)
+        except BaseException as error:
+            self._snapshots[key] = self._snapshot(
+                key, BackgroundTaskState.FAILED, type(error).__name__
+            )
+
+    async def _send(self, message: object) -> None:
+        async with self._send_lock:
+            pipe = self._pipe
+            if pipe is None:
+                raise RuntimeError("Background process connection is closed")
+            await asyncio.to_thread(pipe.send, message)
+
+    async def _watch(self) -> None:
+        while self._process is not None:
+            pipe = self._pipe
+            try:
+                while pipe is not None and pipe.poll():
+                    await self._receive(pipe.recv())
+            except (EOFError, OSError):
+                # 管道中断不等于进程退出；仍等待系统确认，不能在此释放位置或补位。
+                if self._pipe is not None:
+                    self._pipe.close()
+                    self._pipe = None
+            if not self._process.is_alive():
+                await self._after_exit()
+            else:
+                await asyncio.sleep(_POLL_INTERVAL)
+
+    async def _receive(self, message: tuple[object, ...]) -> None:
+        kind = message[0]
+        if kind == _Message.LOCKED:
+            await self._send((_Message.GO,))
+        elif kind == _Message.READY:
+            self._bootstrapped = True
+            if self._boot is not None and not self._boot.done():
+                self._boot.set_result(None)
+        elif kind == _Message.FAILED:
+            error_type = str(message[1])
+            for key in self._wanted:
+                self._snapshots[key] = self._snapshot(key, BackgroundTaskState.FAILED, error_type)
+        elif kind == _Message.CLEANUP_FAILED:
+            self._cleanup_error = str(message[1])
+        elif kind == _Message.SNAPSHOTS:
+            self._publish_snapshots(message[1])
+        elif kind == _Message.RESULT:
+            serial, snapshot = message[1:]
+            assert isinstance(serial, int) and isinstance(snapshot, BackgroundTaskSnapshot)
+            waiter = self._pending.pop(serial)
+            self._snapshots[snapshot.id] = snapshot.model_copy(
+                update={"restart_count": self._restart_count}
+            )
+            waiter.set_result(self._snapshots[snapshot.id])
+        elif kind == _Message.REJECTED:
+            serial = message[1]
+            assert isinstance(serial, int)
+            self._pending.pop(serial).set_exception(RuntimeError(str(message[2])))
+        else:
+            raise RuntimeError("Unknown background process message")
+
+    def _publish_snapshots(self, snapshots: object) -> None:
+        assert isinstance(snapshots, tuple)
+        for snapshot in snapshots:
+            assert isinstance(snapshot, BackgroundTaskSnapshot)
+            self._snapshots[snapshot.id] = snapshot.model_copy(
+                update={"restart_count": self._restart_count}
+            )
+
+    def _observe_exit(self) -> None:
+        process = self._process
+        assert process is not None and not process.is_alive()
+        process.join()
+        process.close()
+        self._process = None
+        self._exited.set()
+        if self._pipe is not None:
+            self._pipe.close()
+            self._pipe = None
+
+    async def _after_exit(self) -> None:
+        bootstrapped = self._bootstrapped
+        process = self._process
+        assert process is not None
+        exit_code = process.exitcode
+        self._observe_exit()
+        for waiter in self._pending.values():
+            waiter.set_exception(RuntimeError("Background process exited"))
+        self._pending.clear()
+        for key in self._wanted:
+            previous = self._snapshots[key]
+            self._snapshots[key] = self._snapshot(
+                key, BackgroundTaskState.FAILED, previous.error_type or "ProcessExit"
+            )
+        if self._boot is not None and not self._boot.done():
+            # 初始化失败仅属于这个位置，主 Host 和其他位置继续启动。
+            self._boot.set_result(None)
+        if self._stopping:
+            if exit_code != 0 and self._cleanup_error is None:
+                self._cleanup_error = f"ProcessExit({exit_code})"
+            return
+        if bootstrapped and self._wanted and self._restart_count < self.options.max_restarts:
+            self._restart_count += 1
+            await asyncio.sleep(self.options.restart_interval.total_seconds())
+            async with self._launch_lock:
+                if not self._stopping and self._wanted and self._process is None:
+                    self._spawn()
+
+    async def shutdown(self) -> None:
+        self._stopping = True
+        self._set_enabled_state(BackgroundTaskState.STOPPING)
+        if self._process is not None and self._process.is_alive():
+            try:
+                await self._send((_Message.SHUTDOWN,))
+            except (EOFError, OSError):
+                pass
+        if self._monitor is not None:
+            await self._monitor
+        if self._operations:
+            await asyncio.gather(*self._operations.values())
+        self._reservation.release()
+        if self._cleanup_error is not None:
+            self._set_enabled_state(BackgroundTaskState.FAILED, self._cleanup_error)
+            raise RuntimeError(f"Background child cleanup failed with {self._cleanup_error}")
+        self._set_enabled_state(BackgroundTaskState.STOPPED)
+
+    def _set_enabled_state(self, state: BackgroundTaskState, error_type: str | None = None) -> None:
+        for key, value in self.tasks.items():
+            if value.enabled:
+                self._snapshots[key] = self._snapshot(key, state, error_type)

python_platform/background_jobs/__init__.py

@@ -0,0 +1,31 @@
+"""Provider-neutral durable background job capability。"""
+
+from ..invocation import BackgroundSystemCaller
+from .catalog import BackgroundJobCatalog
+from .contracts import (
+    BackgroundJobContext,
+    BackgroundJobDefinition,
+    BackgroundJobEnqueuer,
+    BackgroundJobHandler,
+    BackgroundJobRetryPolicy,
+    BackgroundJobSchedule,
+)
+from .errors import (
+    BackgroundJobDefinitionError,
+    BackgroundJobExecutionError,
+    BackgroundJobPayloadError,
+)
+
+__all__ = (
+    "BackgroundJobCatalog",
+    "BackgroundJobContext",
+    "BackgroundJobDefinition",
+    "BackgroundJobDefinitionError",
+    "BackgroundJobEnqueuer",
+    "BackgroundJobExecutionError",
+    "BackgroundJobHandler",
+    "BackgroundJobPayloadError",
+    "BackgroundJobRetryPolicy",
+    "BackgroundJobSchedule",
+    "BackgroundSystemCaller",
+)