python-platform 0.1.1__py3-none-any.whl

python_platform/background_jobs/catalog.py

@@ -0,0 +1,287 @@
+"""Durable job versions 与 Cron schedules 的 immutable Application catalog。"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from collections.abc import Iterator, Mapping
+from dataclasses import replace
+from datetime import UTC, datetime
+from types import MappingProxyType
+
+from pydantic import BaseModel, ValidationError
+
+from ..modularity import AppModule, ModuleDescriptor, ModuleKey, ModuleRegistry
+from .contracts import BackgroundJobDefinition, BackgroundJobSchedule
+from .errors import BackgroundJobDefinitionError, BackgroundJobPayloadError
+
+
+class BackgroundJobCatalog:
+    __slots__ = (
+        "_current",
+        "_declarations",
+        "_definitions",
+        "_fingerprint",
+        "_schedules",
+    )
+
+    def __init__(
+        self,
+        definitions: tuple[BackgroundJobDefinition[BaseModel], ...],
+        schedules: tuple[BackgroundJobSchedule, ...],
+        *,
+        declarations: tuple[tuple[type[AppModule], str, tuple[object, ...]], ...],
+        owners: Mapping[tuple[str, int], ModuleKey],
+    ) -> None:
+        self._definitions = MappingProxyType(
+            {(item.name, item.version): item for item in definitions}
+        )
+        self._current = MappingProxyType({item.name: item for item in definitions if item.current})
+        self._schedules = MappingProxyType({item.name: item for item in schedules})
+        self._declarations = declarations
+        encoded = json.dumps(
+            {
+                "definitions": [
+                    {
+                        "name": item.name,
+                        "version": item.version,
+                        "current": item.current,
+                        "owner": str(owners[(item.name, item.version)]),
+                        "timeout_seconds": item.timeout.total_seconds(),
+                        "max_attempts": item.retry_policy.max_attempts,
+                        "initial_delay_seconds": item.retry_policy.initial_delay.total_seconds(),
+                        "max_delay_seconds": item.retry_policy.max_delay.total_seconds(),
+                        "backoff_multiplier": item.retry_policy.backoff_multiplier,
+                    }
+                    for item in definitions
+                ],
+                "schedules": [
+                    {
+                        "name": item.name,
+                        "cron": item.cron,
+                        "job_name": item.job_name,
+                        "job_version": item.job_version,
+                        "payload": item.payload.decode(),
+                    }
+                    for item in schedules
+                ],
+            },
+            sort_keys=True,
+            separators=(",", ":"),
+        ).encode()
+        self._fingerprint = hashlib.sha256(encoded).hexdigest()
+
+    @property
+    def definitions(self) -> tuple[BackgroundJobDefinition[BaseModel], ...]:
+        return tuple(self._definitions.values())
+
+    @property
+    def schedules(self) -> tuple[BackgroundJobSchedule, ...]:
+        return tuple(self._schedules.values())
+
+    @property
+    def fingerprint(self) -> str:
+        return self._fingerprint
+
+    def __iter__(self) -> Iterator[tuple[str, int]]:
+        return iter(self._definitions)
+
+    def get(self, name: str, version: int) -> BackgroundJobDefinition[BaseModel] | None:
+        return self._definitions.get((name, version))
+
+    def current(self, name: str) -> BackgroundJobDefinition[BaseModel] | None:
+        return self._current.get(name)
+
+    def get_schedule(self, name: str) -> BackgroundJobSchedule | None:
+        return self._schedules.get(name)
+
+    def owns(self, definition: BackgroundJobDefinition[BaseModel]) -> bool:
+        return self._definitions.get((definition.name, definition.version)) is definition
+
+    def _assert_unchanged(self) -> None:
+        for module_type, attribute, declared in self._declarations:
+            if module_type.__dict__.get(attribute, ()) is not declared:
+                raise BackgroundJobDefinitionError(
+                    job=f"{module_type.__module__}.{module_type.__qualname__}",
+                    reason=f"Module {attribute} metadata changed after build",
+                )
+
+
+def _build_background_job_catalog(registry: ModuleRegistry) -> BackgroundJobCatalog:
+    builder = _BackgroundJobCatalogBuilder()
+    for descriptor in registry.dependency_order:
+        builder.add_module(descriptor)
+    return builder.build()
+
+
+class _BackgroundJobCatalogBuilder:
+    """拥有 catalog build 期间的 mutable arbitration state，产物仍为 immutable。"""
+
+    __slots__ = (
+        "_declarations",
+        "_definitions",
+        "_name_owners",
+        "_owners",
+        "_raw_schedules",
+        "_schedule_owners",
+    )
+
+    def __init__(self) -> None:
+        self._definitions: list[BackgroundJobDefinition[BaseModel]] = []
+        self._raw_schedules: list[BackgroundJobSchedule] = []
+        self._owners: dict[tuple[str, int], ModuleKey] = {}
+        self._name_owners: dict[str, ModuleKey] = {}
+        self._schedule_owners: dict[str, ModuleKey] = {}
+        self._declarations: list[tuple[type[AppModule], str, tuple[object, ...]]] = []
+
+    def add_module(self, descriptor: ModuleDescriptor) -> None:
+        declared_definitions = descriptor.module_type.__dict__.get("background_job_definitions", ())
+        declared_schedules = descriptor.module_type.__dict__.get("background_job_schedules", ())
+        _validate_metadata_tuple(
+            declared_definitions,
+            owner=str(descriptor.key),
+            attribute="background_job_definitions",
+        )
+        _validate_metadata_tuple(
+            declared_schedules,
+            owner=str(descriptor.key),
+            attribute="background_job_schedules",
+        )
+        self._declarations.extend(
+            (
+                (descriptor.module_type, "background_job_definitions", declared_definitions),
+                (descriptor.module_type, "background_job_schedules", declared_schedules),
+            )
+        )
+        for definition in declared_definitions:
+            self._add_definition(definition, descriptor.key)
+        for schedule in declared_schedules:
+            self._add_schedule(schedule, descriptor.key)
+
+    def build(self) -> BackgroundJobCatalog:
+        by_name: dict[str, list[BackgroundJobDefinition[BaseModel]]] = {}
+        by_identity = {(item.name, item.version): item for item in self._definitions}
+        for definition in self._definitions:
+            by_name.setdefault(definition.name, []).append(definition)
+        for name, versions in by_name.items():
+            if sum(item.current for item in versions) != 1:
+                raise BackgroundJobDefinitionError(
+                    job=name,
+                    reason="job versions must declare exactly one current definition",
+                )
+        schedules = tuple(_canonicalize_schedule(item, by_identity) for item in self._raw_schedules)
+        return BackgroundJobCatalog(
+            tuple(self._definitions),
+            schedules,
+            declarations=tuple(self._declarations),
+            owners=self._owners,
+        )
+
+    def _add_definition(self, candidate: object, owner: ModuleKey) -> None:
+        if not isinstance(candidate, BackgroundJobDefinition):
+            raise BackgroundJobDefinitionError(
+                job=str(owner),
+                reason="Module background_job_definitions contains an invalid item",
+            )
+        definition = candidate
+        identity = (definition.name, definition.version)
+        if identity in self._owners:
+            raise BackgroundJobDefinitionError(
+                job=definition.name,
+                reason=f"version {definition.version} is declared more than once",
+            )
+        previous_owner = self._name_owners.get(definition.name)
+        if previous_owner is not None and previous_owner != owner:
+            raise BackgroundJobDefinitionError(
+                job=definition.name,
+                reason=f"all versions must be owned by {previous_owner}",
+            )
+        self._owners[identity] = owner
+        self._name_owners[definition.name] = owner
+        self._definitions.append(definition)
+
+    def _add_schedule(self, candidate: object, owner: ModuleKey) -> None:
+        if not isinstance(candidate, BackgroundJobSchedule):
+            raise BackgroundJobDefinitionError(
+                job=str(owner),
+                reason="Module background_job_schedules contains an invalid item",
+            )
+        schedule = candidate
+        if schedule.name in self._schedule_owners:
+            raise BackgroundJobDefinitionError(
+                job=schedule.name,
+                reason=f"schedule is already owned by {self._schedule_owners[schedule.name]}",
+            )
+        self._schedule_owners[schedule.name] = owner
+        self._raw_schedules.append(schedule)
+
+
+def _validate_metadata_tuple(value: object, *, owner: str, attribute: str) -> None:
+    if not isinstance(value, tuple):
+        raise BackgroundJobDefinitionError(
+            job=owner,
+            reason=f"Module {attribute} must be an immutable tuple",
+        )
+
+
+def _canonicalize_schedule(
+    schedule: BackgroundJobSchedule,
+    definitions: Mapping[tuple[str, int], BackgroundJobDefinition[BaseModel]],
+) -> BackgroundJobSchedule:
+    definition = definitions.get((schedule.job_name, schedule.job_version))
+    if definition is None:
+        raise BackgroundJobDefinitionError(
+            job=schedule.name,
+            reason="schedule target does not exist in the Application catalog",
+        )
+    cron = _normalize_cron(schedule.name, schedule.cron)
+    try:
+        payload = definition.payload_type.model_validate_json(schedule.payload)
+    except ValidationError:
+        raise BackgroundJobPayloadError(
+            job=definition.name,
+            version=definition.version,
+            reason="scheduled payload failed schema validation",
+        ) from None
+    canonical = json.dumps(
+        payload.model_dump(mode="json"),
+        sort_keys=True,
+        separators=(",", ":"),
+        ensure_ascii=False,
+    ).encode()
+    return replace(schedule, cron=cron, payload=canonical)
+
+
+def _normalize_cron(schedule_name: str, expression: str) -> str:
+    normalized = " ".join(expression.split())
+    fields = normalized.split(" ")
+    if len(fields) not in (5, 6) or any(
+        not field or any(character not in "0123456789*/,-" for character in field)
+        for field in fields
+    ):
+        raise BackgroundJobDefinitionError(
+            job=schedule_name,
+            reason="cron must use numeric five-field or trailing-second six-field grammar",
+        )
+    try:
+        from croniter import croniter  # type: ignore[import-untyped]
+    except ImportError:
+        raise BackgroundJobDefinitionError(
+            job=schedule_name,
+            reason="Cron schedules require the background-jobs extra",
+        ) from None
+    try:
+        valid = croniter.is_valid(normalized, strict=True)
+        if valid:
+            croniter(
+                normalized,
+                start_time=datetime.now(UTC),
+            ).get_next(datetime)
+    except (TypeError, ValueError):
+        valid = False
+    if not valid:
+        raise BackgroundJobDefinitionError(
+            job=schedule_name,
+            reason="cron expression is outside the supported UTC grammar",
+        )
+    return normalized

python_platform/background_jobs/contracts.py

@@ -0,0 +1,202 @@
+"""Provider-neutral durable job identity、payload 与 enqueue contracts。"""
+
+from __future__ import annotations
+
+import asyncio
+import inspect
+from abc import ABC, abstractmethod
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass, field
+from datetime import datetime, timedelta
+from typing import Generic, Protocol, TypeVar, cast
+
+from pydantic import BaseModel
+
+from ..invocation import BackgroundSystemCaller
+from .errors import BackgroundJobDefinitionError
+
+_TPayload = TypeVar("_TPayload", bound=BaseModel)
+
+
+class BackgroundJobHandler(ABC, Generic[_TPayload]):
+    """一次 durable delivery 的业务边界；queue loop/retry 由 provider 独占。"""
+
+    @abstractmethod
+    async def execute(self, payload: _TPayload, context: BackgroundJobContext) -> None:
+        raise NotImplementedError
+
+
+@dataclass(frozen=True, slots=True)
+class BackgroundJobContext:
+    job_id: str
+    name: str
+    version: int
+    attempt: int
+    scheduled_at: datetime
+    system_caller: BackgroundSystemCaller
+    _cancellation_event: asyncio.Event = field(repr=False, compare=False)
+
+    @property
+    def cancellation_requested(self) -> bool:
+        return self._cancellation_event.is_set()
+
+
+@dataclass(frozen=True, slots=True)
+class BackgroundJobRetryPolicy:
+    max_attempts: int = 5
+    initial_delay: timedelta = timedelta(seconds=1)
+    max_delay: timedelta = timedelta(minutes=5)
+    backoff_multiplier: float = 2.0
+
+    def __post_init__(self) -> None:
+        if (
+            not isinstance(self.max_attempts, int)
+            or isinstance(self.max_attempts, bool)
+            or self.max_attempts < 1
+        ):
+            raise BackgroundJobDefinitionError(
+                job="<retry-policy>",
+                reason="max_attempts must be a positive integer",
+            )
+        if not isinstance(self.initial_delay, timedelta) or self.initial_delay.total_seconds() <= 0:
+            raise BackgroundJobDefinitionError(
+                job="<retry-policy>",
+                reason="initial_delay must be a positive timedelta",
+            )
+        if not isinstance(self.max_delay, timedelta) or self.max_delay < self.initial_delay:
+            raise BackgroundJobDefinitionError(
+                job="<retry-policy>",
+                reason="max_delay must be a timedelta no smaller than initial_delay",
+            )
+        if (
+            not isinstance(self.backoff_multiplier, (int, float))
+            or isinstance(self.backoff_multiplier, bool)
+            or self.backoff_multiplier < 1
+        ):
+            raise BackgroundJobDefinitionError(
+                job="<retry-policy>",
+                reason="backoff_multiplier must be at least 1",
+            )
+
+    def delay_for_attempt(self, attempt: int) -> timedelta:
+        if not isinstance(attempt, int) or isinstance(attempt, bool) or attempt < 0:
+            raise ValueError("attempt must be a non-negative integer")
+        seconds = self.initial_delay.total_seconds() * (self.backoff_multiplier**attempt)
+        return timedelta(seconds=min(seconds, self.max_delay.total_seconds()))
+
+
+@dataclass(frozen=True, slots=True)
+class BackgroundJobDefinition(Generic[_TPayload]):
+    name: str
+    version: int
+    payload_type: type[_TPayload]
+    handler_type: type[BackgroundJobHandler[_TPayload]] | Callable[..., Awaitable[None]]
+    timeout: timedelta
+    current: bool = False
+    retry_policy: BackgroundJobRetryPolicy = BackgroundJobRetryPolicy()
+
+    def __post_init__(self) -> None:
+        _validate_name(self.name)
+        if not isinstance(self.version, int) or isinstance(self.version, bool) or self.version < 1:
+            raise BackgroundJobDefinitionError(
+                job=self.name,
+                reason="version must be a positive integer",
+            )
+        if not isinstance(self.payload_type, type) or not issubclass(self.payload_type, BaseModel):
+            raise BackgroundJobDefinitionError(
+                job=self.name,
+                reason="payload_type must be a Pydantic BaseModel class",
+            )
+        is_class = isinstance(self.handler_type, type) and issubclass(
+            self.handler_type, BackgroundJobHandler
+        )
+        if not is_class and not inspect.iscoroutinefunction(self.handler_type):
+            raise BackgroundJobDefinitionError(
+                job=self.name,
+                reason="handler_type must be a BackgroundJobHandler class or async function",
+            )
+        if isinstance(self.handler_type, type) and not inspect.iscoroutinefunction(
+            cast(type[BackgroundJobHandler[_TPayload]], self.handler_type).execute
+        ):
+            raise BackgroundJobDefinitionError(
+                job=self.name,
+                reason="execute must be async",
+            )
+        if not isinstance(self.timeout, timedelta) or self.timeout.total_seconds() <= 0:
+            raise BackgroundJobDefinitionError(
+                job=self.name,
+                reason="timeout must be a positive timedelta",
+            )
+        if not isinstance(self.current, bool):
+            raise BackgroundJobDefinitionError(job=self.name, reason="current must be bool")
+        if not isinstance(self.retry_policy, BackgroundJobRetryPolicy):
+            raise BackgroundJobDefinitionError(
+                job=self.name,
+                reason="retry_policy must be BackgroundJobRetryPolicy",
+            )
+
+
+@dataclass(frozen=True, slots=True)
+class BackgroundJobSchedule:
+    name: str
+    cron: str
+    job_name: str
+    job_version: int
+    payload: bytes
+
+    def __post_init__(self) -> None:
+        _validate_name(self.name)
+        _validate_name(self.job_name)
+        if (
+            not isinstance(self.job_version, int)
+            or isinstance(self.job_version, bool)
+            or self.job_version < 1
+        ):
+            raise BackgroundJobDefinitionError(
+                job=self.name,
+                reason="job_version must be a positive integer",
+            )
+        if not isinstance(self.cron, str) or not self.cron.strip():
+            raise BackgroundJobDefinitionError(
+                job=self.name,
+                reason="cron must be a non-empty string",
+            )
+        if not isinstance(self.payload, bytes):
+            raise BackgroundJobDefinitionError(
+                job=self.name,
+                reason="payload must be immutable UTF-8 JSON bytes",
+            )
+        try:
+            self.payload.decode("utf-8")
+        except UnicodeDecodeError:
+            raise BackgroundJobDefinitionError(
+                job=self.name,
+                reason="payload must be UTF-8 JSON bytes",
+            ) from None
+
+
+class BackgroundJobEnqueuer(Protocol):
+    async def enqueue(
+        self,
+        definition: BackgroundJobDefinition[_TPayload],
+        payload: _TPayload,
+        *,
+        priority: int = 0,
+        delay: timedelta | None = None,
+    ) -> str: ...
+
+
+def _validate_name(name: str) -> None:
+    if (
+        not isinstance(name, str)
+        or not name
+        or name != name.strip()
+        or name.startswith(".")
+        or name.endswith(".")
+        or ".." in name
+        or any(not (character.isalnum() or character in "._-") for character in name)
+    ):
+        raise BackgroundJobDefinitionError(
+            job=name if isinstance(name, str) else repr(name),
+            reason="name must be a trimmed stable identifier",
+        )

python_platform/background_jobs/errors.py

@@ -0,0 +1,28 @@
+"""Durable background job definition、payload 与 provider-neutral failures。"""
+
+from __future__ import annotations
+
+from ..errors.base import FrameworkError
+
+
+class BackgroundJobDefinitionError(FrameworkError):
+    def __init__(self, *, job: str, reason: str) -> None:
+        self.job = job
+        self.reason = reason
+        super().__init__(f"Invalid background job {job!r}: {reason}")
+
+
+class BackgroundJobPayloadError(FrameworkError):
+    def __init__(self, *, job: str, version: int, reason: str) -> None:
+        self.job = job
+        self.version = version
+        self.reason = reason
+        super().__init__(f"Invalid payload for background job {job!r} v{version}: {reason}")
+
+
+class BackgroundJobExecutionError(FrameworkError):
+    def __init__(self, *, job: str, version: int, error_type: str) -> None:
+        self.job = job
+        self.version = version
+        self.error_type = error_type
+        super().__init__(f"Background job {job!r} v{version} failed with {error_type}")