aiogram-idle 0.1.0__py3-none-any.whl

aiogram_idle/__init__.py

@@ -0,0 +1,146 @@
+"""Standalone inactivity policies for aiogram 3; no navigation or Redis dependency."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+from .activity import IdleContext
+from .clock import Clock, ManualClock, SystemClock
+from .config import AmbiguousSendPolicy, IdleConfig
+from .controls import (
+    CommandPromptControls,
+    ControlContext,
+    ControlResult,
+    InlinePromptControls,
+    ReplyPromptControls,
+)
+from .coordinator import AiogramMemoryCoordinator, MemoryCoordinator
+from .errors import (
+    ActivityConflict,
+    BackendInconsistent,
+    CommitUnknown,
+    ConfigurationError,
+    ConfigurationMismatch,
+    EffectUnknown,
+    IdleError,
+    OperationIdConflict,
+    Overloaded,
+    OwnershipLost,
+    PersistenceUnavailable,
+    SchemaUnsupported,
+    SessionExpired,
+    UnsupportedContext,
+    VersionConflict,
+)
+from .models import (
+    ActionReceipt,
+    ActivityGuard,
+    ActivitySnapshot,
+    ActivitySpec,
+    ConfigManifest,
+    ConfigUpdate,
+    FlowContext,
+    FlowEligibility,
+    IdleConversationKey,
+    IdleEvent,
+    IdleSnapshot,
+    IdleStatus,
+    MessageRef,
+    PendingOperation,
+    Phase,
+    PollReport,
+    ReconcileReport,
+    RuntimeSnapshot,
+    SessionGuard,
+    SessionSnapshot,
+)
+from .policies import ExemptPolicy, IdlePolicies, PromptPolicy, QuietRestorePolicy
+from .presentation import (
+    DeliveryReceipt,
+    FinishRequest,
+    PromptReceipt,
+    PromptRequest,
+    PromptTexts,
+    QuietHours,
+    QuietHoursResolver,
+    TelegramPromptPresenter,
+)
+from .protocols import Coordinator, EffectRecorder, FlowAdapter, PromptPresenter, SessionAuthority
+from .runtime import IdleRuntime
+from .storage.base import IdleBackend
+from .storage.memory import MemoryIdleBackend
+from .storage.state import OperationLookup
+
+try:
+    __version__ = version("aiogram-idle")
+except PackageNotFoundError:  # Allow direct source imports before installation.
+    __version__ = "0+unknown"
+__all__ = [
+    "ActionReceipt",
+    "ActivityConflict",
+    "ActivityGuard",
+    "ActivitySnapshot",
+    "ActivitySpec",
+    "AiogramMemoryCoordinator",
+    "AmbiguousSendPolicy",
+    "BackendInconsistent",
+    "Clock",
+    "CommandPromptControls",
+    "CommitUnknown",
+    "ConfigManifest",
+    "ConfigUpdate",
+    "ConfigurationError",
+    "ConfigurationMismatch",
+    "ControlContext",
+    "ControlResult",
+    "Coordinator",
+    "DeliveryReceipt",
+    "EffectRecorder",
+    "EffectUnknown",
+    "ExemptPolicy",
+    "FinishRequest",
+    "FlowAdapter",
+    "FlowContext",
+    "FlowEligibility",
+    "IdleBackend",
+    "IdleConfig",
+    "IdleContext",
+    "IdleConversationKey",
+    "IdleError",
+    "IdleEvent",
+    "IdlePolicies",
+    "IdleRuntime",
+    "IdleSnapshot",
+    "IdleStatus",
+    "InlinePromptControls",
+    "ManualClock",
+    "MemoryCoordinator",
+    "MemoryIdleBackend",
+    "MessageRef",
+    "OperationIdConflict",
+    "OperationLookup",
+    "Overloaded",
+    "OwnershipLost",
+    "PendingOperation",
+    "PersistenceUnavailable",
+    "Phase",
+    "PollReport",
+    "PromptPolicy",
+    "PromptPresenter",
+    "PromptReceipt",
+    "PromptRequest",
+    "PromptTexts",
+    "QuietHours",
+    "QuietHoursResolver",
+    "QuietRestorePolicy",
+    "ReconcileReport",
+    "ReplyPromptControls",
+    "RuntimeSnapshot",
+    "SchemaUnsupported",
+    "SessionAuthority",
+    "SessionExpired",
+    "SessionGuard",
+    "SessionSnapshot",
+    "SystemClock",
+    "TelegramPromptPresenter",
+    "UnsupportedContext",
+    "VersionConflict",
+]

aiogram_idle/activity.py

@@ -0,0 +1,122 @@
+"""Guarded activity entry points; never infer acceptance from an incoming update."""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Mapping
+from datetime import datetime
+from typing import TYPE_CHECKING
+
+from .models import (
+    ActivityGuard,
+    ActivitySnapshot,
+    IdleConversationKey,
+    SessionGuard,
+    SessionSnapshot,
+)
+
+logger = logging.getLogger(__name__)
+
+if TYPE_CHECKING:
+    from .runtime import IdleRuntime
+
+
+class IdleContext:
+    def __init__(self, runtime: IdleRuntime, key: IdleConversationKey) -> None:
+        self.runtime = runtime
+        self.key = key
+
+    async def open_session(self, *, operation_id: str, lifetime_seconds: float) -> SessionSnapshot:
+        async with self.runtime.coordinator.hold(self.key):
+            await self.runtime.initialize()
+            return await self.runtime.backend.open_session(
+                self.key, lifetime_seconds=lifetime_seconds, operation_id=operation_id
+            )
+
+    async def replace_session(
+        self, *, expected: SessionGuard, operation_id: str, lifetime_seconds: float
+    ) -> SessionSnapshot:
+        async with self.runtime.coordinator.hold(self.key):
+            await self.runtime.initialize()
+            return await self.runtime.backend.replace_session(
+                self.key,
+                expected=expected,
+                lifetime_seconds=lifetime_seconds,
+                operation_id=operation_id,
+            )
+
+    async def current(self) -> ActivitySnapshot | None:
+        async with self.runtime.coordinator.hold(self.key):
+            snapshot = await self.runtime.backend.load(self.key)
+            if snapshot is None or snapshot.session.expires_at <= self.runtime.clock.now():
+                return None
+            if (
+                snapshot.activity is not None
+                and snapshot.activity.expires_at <= self.runtime.clock.now()
+            ):
+                return None
+            return snapshot.activity
+
+    async def enter(
+        self,
+        activity_key: str,
+        *,
+        policy_id: str,
+        adapter_key: str,
+        params: Mapping[str, object],
+        session_id: str,
+        expires_at: datetime | float,
+        operation_id: str,
+        expected: ActivityGuard | None = None,
+    ) -> ActivitySnapshot:
+        async with self.runtime.coordinator.hold(self.key):
+            await self.runtime.initialize()
+            self.runtime.adapter(adapter_key)
+            manifest = await self.runtime.manifest()
+            previous = await self.runtime.current_prompt(self.key)
+            result = await self.runtime.backend.enter(
+                self.key,
+                activity_key=activity_key,
+                policy_id=policy_id,
+                policy=self.runtime.policies[policy_id],
+                adapter_key=adapter_key,
+                params=params,
+                session_id=session_id,
+                expires_at=expires_at,
+                operation_id=operation_id,
+                expected=expected,
+                enabled=manifest.enabled,
+                expected_manifest=manifest.generation,
+            )
+            if previous is not None:
+                try:
+                    await self.runtime.presenter.strip(previous)
+                except Exception:
+                    logger.warning("Superseded prompt cleanup unavailable")
+            return result
+
+    async def touch(self, *, expected: ActivityGuard, operation_id: str) -> ActivitySnapshot:
+        async with self.runtime.coordinator.hold(self.key):
+            await self.runtime.initialize()
+            manifest = await self.runtime.manifest()
+            previous = await self.runtime.current_prompt(self.key)
+            result = await self.runtime.backend.touch(
+                self.key,
+                expected=expected,
+                operation_id=operation_id,
+                enabled=manifest.enabled,
+                expected_manifest=manifest.generation,
+            )
+            if previous is not None:
+                try:
+                    await self.runtime.presenter.strip(previous)
+                except Exception:
+                    logger.warning("Superseded prompt cleanup unavailable")
+            return result
+
+    async def clear(self, *, expected: ActivityGuard, reason: str, operation_id: str) -> None:
+        async with self.runtime.coordinator.hold(self.key):
+            await self.runtime.initialize()
+            await self.runtime.backend.clear(
+                self.key, expected=expected, operation_id=operation_id, reason=reason
+            )

aiogram_idle/clock.py

@@ -0,0 +1,69 @@
+"""Injectable wall and monotonic clocks for live runtimes and deterministic tests."""
+
+from __future__ import annotations
+
+import asyncio
+import math
+import time
+from typing import Protocol
+
+
+class Clock(Protocol):
+    def now(self) -> float: ...
+    def monotonic(self) -> float: ...
+    async def sleep(self, seconds: float) -> None: ...
+
+
+class SystemClock:
+    def now(self) -> float:
+        return time.time()
+
+    def monotonic(self) -> float:
+        return time.monotonic()
+
+    async def sleep(self, seconds: float) -> None:
+        await asyncio.sleep(seconds)
+
+
+class ManualClock:
+    """Advance explicitly; sleeping tasks wake without real-time delays."""
+
+    def __init__(self, now: float = 1_700_000_000.0) -> None:
+        if not math.isfinite(now):
+            raise ValueError("clock time must be finite")
+        self._now = now
+        self._monotonic = 0.0
+        self._waiters: list[tuple[float, asyncio.Future[None]]] = []
+
+    def now(self) -> float:
+        return self._now
+
+    def monotonic(self) -> float:
+        return self._monotonic
+
+    def advance(self, seconds: float) -> None:
+        if not math.isfinite(seconds) or seconds < 0:
+            raise ValueError("clock advance must be finite and nonnegative")
+        self._now += seconds
+        self._monotonic += seconds
+        remaining: list[tuple[float, asyncio.Future[None]]] = []
+        for deadline, future in self._waiters:
+            if deadline <= self._monotonic:
+                if not future.done():
+                    future.set_result(None)
+            elif not future.done():
+                remaining.append((deadline, future))
+        self._waiters = remaining
+
+    async def sleep(self, seconds: float) -> None:
+        if seconds <= 0:
+            await asyncio.sleep(0)
+            return
+        future = asyncio.get_running_loop().create_future()
+        item = (self._monotonic + seconds, future)
+        self._waiters.append(item)
+        try:
+            await future
+        finally:
+            if item in self._waiters:
+                self._waiters.remove(item)

aiogram_idle/compat.py

@@ -0,0 +1,72 @@
+"""Task-preserving timeout scope, including Python 3.10."""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import AsyncGenerator, Callable
+from contextlib import asynccontextmanager
+from typing import cast
+
+
+@asynccontextmanager
+async def bounded(seconds: float) -> AsyncGenerator[None, None]:
+    task = asyncio.current_task()
+    if task is None:
+        raise RuntimeError("Timeout scope requires an asyncio task")
+    cancelling = cast(Callable[[], int] | None, getattr(task, "cancelling", None))
+    uncancel = cast(Callable[[], int] | None, getattr(task, "uncancel", None))
+    baseline = cancelling() if cancelling is not None else 0
+    expired = False
+    consumed = False
+    marker = object()
+    legacy_marker = False
+    legacy_previous: object = None
+
+    def expire() -> None:
+        nonlocal expired, legacy_marker, legacy_previous
+        expired = True
+        if cancelling is None:
+            legacy_previous = getattr(task, "_cancel_message", None)
+        task.cancel(marker)
+        if cancelling is None and hasattr(task, "_cancel_message"):
+            # CPython 3.10 has no cancellation counter. Pin its message so even
+            # an external cancel(None) racing this cancellation remains distinct.
+            # Other Task implementations fall back to the delivered marker.
+            try:
+                setattr(task, "_cancel_message", marker)  # noqa: B010 -- guarded 3.10-only attribute
+            except (AttributeError, TypeError):
+                pass
+            else:
+                legacy_marker = True
+
+    def consume() -> int:
+        nonlocal consumed
+        if uncancel is not None and not consumed:
+            consumed = True
+            return uncancel()
+        return cancelling() if cancelling is not None else 0
+
+    handle = asyncio.get_running_loop().call_later(seconds, expire)
+    try:
+        yield
+    except asyncio.CancelledError as exc:
+        if expired:
+            remaining = consume()
+            owned = (
+                remaining <= baseline
+                if cancelling is not None
+                else exc.args == (marker,)
+                and (not legacy_marker or getattr(task, "_cancel_message", None) is marker)
+            )
+            if owned:
+                raise asyncio.TimeoutError from exc
+        raise
+    finally:
+        handle.cancel()
+        if expired:
+            if legacy_marker and getattr(task, "_cancel_message", None) is marker:
+                # Restore an outer timeout marker, never an external cancellation.
+                setattr(task, "_cancel_message", legacy_previous)  # noqa: B010
+            # A body that suppresses CancelledError still must relinquish exactly
+            # this timeout's request; external cancellation requests are retained.
+            consume()

aiogram_idle/config.py

@@ -0,0 +1,71 @@
+"""Validated library settings; importing the package never reads the environment."""
+
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass, fields
+from enum import Enum
+from typing import cast
+
+from .errors import ConfigurationError
+
+
+class AmbiguousSendPolicy(str, Enum):
+    SUPPRESS = "suppress"
+    RETRY = "retry"
+
+
+@dataclass(frozen=True)
+class IdleConfig:
+    enabled: bool = False
+    poll_seconds: float = 10
+    concurrency: int = 8
+    claim_limit: int = 8
+    lease_seconds: float = 60
+    renew_seconds: float = 15
+    operation_timeout_seconds: float = 45
+    lock_wait_seconds: float = 5
+    shutdown_seconds: float = 10
+    retry_max_attempts: int = 5
+    retry_max_age_seconds: float = 300
+    recovery_retention_seconds: float = 3600
+    ambiguous_send: AmbiguousSendPolicy = AmbiguousSendPolicy.SUPPRESS
+    max_conversations: int = 10_000
+    max_receipts_per_conversation: int = 256
+    max_tokens_per_conversation: int = 16
+    max_params_bytes: int = 16_384
+    max_components_bytes: int = 8_388_608
+
+    def __post_init__(self) -> None:
+        if not isinstance(cast(object, self.enabled), bool):
+            raise ConfigurationError("enabled must be a boolean")
+        integer_fields = {
+            "concurrency",
+            "claim_limit",
+            "retry_max_attempts",
+            "max_conversations",
+            "max_receipts_per_conversation",
+            "max_tokens_per_conversation",
+            "max_params_bytes",
+            "max_components_bytes",
+        }
+        for field in fields(self):
+            value = getattr(self, field.name)
+            if field.name in {"enabled", "ambiguous_send"}:
+                continue
+            if not isinstance(value, (int, float)) or isinstance(value, bool):
+                raise ConfigurationError(f"{field.name} must be numeric")
+            if not math.isfinite(value) or value <= 0:
+                raise ConfigurationError(f"{field.name} must be positive and finite")
+            if field.name in integer_fields and not isinstance(value, int):
+                raise ConfigurationError(f"{field.name} must be an integer")
+        if self.max_components_bytes > 8_388_608:
+            raise ConfigurationError("max_components_bytes exceeds the supported 8 MiB bound")
+        if self.claim_limit > self.concurrency:
+            raise ConfigurationError("claim_limit exceeds worker concurrency")
+        if self.renew_seconds * 2 >= self.lease_seconds:
+            raise ConfigurationError("renew interval must be below half the lease")
+        if self.lock_wait_seconds >= self.lease_seconds:
+            raise ConfigurationError("lock wait must be shorter than lease")
+        if not isinstance(cast(object, self.ambiguous_send), AmbiguousSendPolicy):
+            raise ConfigurationError("unknown ambiguous-send policy")

aiogram_idle/controls.py

@@ -0,0 +1,167 @@
+"""All Telegram control styles enter the same authorized runtime pipeline."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import ClassVar, Literal, Protocol
+
+from aiogram import Bot
+from aiogram.exceptions import TelegramAPIError
+from aiogram.filters import Command
+from aiogram.types import CallbackQuery, Message
+
+from .models import IdleConversationKey
+from .presentation import PromptReceipt, PromptTexts
+
+
+@dataclass(frozen=True)
+class ControlContext:
+    key: IdleConversationKey
+    actor_id: int
+    transport: str = "commands"
+    prompt_id: str | None = None
+    token: str | None = None
+    message_id: int | None = None
+    operation_id: str = ""
+
+
+@dataclass(frozen=True)
+class ControlResult:
+    accepted: bool
+    outcome: str
+    message: str = ""
+
+
+@dataclass(frozen=True)
+class ReplyPromptControls:
+    mode: ClassVar[str] = "reply"
+    continue_label: str = "Continue"
+    cancel_label: str = "Cancel"
+
+    def match(self, text: str) -> Literal["continue", "cancel"] | None:
+        if self.continue_label == self.cancel_label:
+            raise ValueError("Reply prompt labels must differ")
+        if text == self.continue_label:
+            return "continue"
+        if text == self.cancel_label:
+            return "cancel"
+        return None
+
+
+@dataclass(frozen=True)
+class InlinePromptControls:
+    mode: ClassVar[str] = "inline"
+
+    def match(self, data: str) -> tuple[Literal["continue", "cancel"], str] | None:
+        parts = data.split(":", 2)
+        if len(parts) != 3 or parts[0] != "idle" or not parts[2]:
+            return None
+        if parts[1] == "c":
+            return "continue", parts[2]
+        if parts[1] == "x":
+            return "cancel", parts[2]
+        return None
+
+
+@dataclass(frozen=True)
+class CommandPromptControls:
+    mode: ClassVar[str] = "commands"
+
+    async def match(self, message: Message, bot: Bot) -> Literal["continue", "cancel"] | None:
+        if await Command("continue")(message, bot):
+            return "continue"
+        if await Command("cancel")(message, bot):
+            return "cancel"
+        return None
+
+
+class ControlRuntime(Protocol):
+    async def current_prompt(self, key: IdleConversationKey) -> PromptReceipt | None: ...
+    async def continue_current(self, context: ControlContext) -> ControlResult: ...
+    async def cancel_current(self, context: ControlContext) -> ControlResult: ...
+
+
+async def handle_control(
+    runtime: ControlRuntime,
+    event: Message | CallbackQuery,
+    key: IdleConversationKey,
+    *,
+    bot: Bot,
+    texts: PromptTexts,
+    update_id: int,
+) -> bool:
+    """Return True only when this update belongs to idle controls.
+
+    A bare /cancel without a prompt falls through to the application's cancel
+    handler. Ordinary text is reserved only while the active reply tray asks it.
+    """
+    prompt = await runtime.current_prompt(key)
+    if isinstance(event, CallbackQuery):
+        data = event.data or ""
+        if not data.startswith("idle:"):
+            return False
+        parsed = InlinePromptControls().match(data)
+        if parsed is None:
+            await _ack(bot, event.id, texts.stale)
+            return True
+        action, token = parsed
+        context = ControlContext(
+            key=key,
+            actor_id=event.from_user.id,
+            transport="inline",
+            prompt_id=prompt.prompt_id if prompt else None,
+            token=token,
+            message_id=event.message.message_id if event.message else None,
+            operation_id=f"update:{update_id}:idle:{action}",
+        )
+        # Stop Telegram's spinner before a slow application adapter executes.
+        known = prompt is not None and token in {prompt.continue_token, prompt.cancel_token}
+        await _ack(bot, event.id, "" if known else texts.stale)
+        await _dispatch(runtime, action, context)
+        # A rejected token proves neither ownership nor obsolescence of its
+        # message. Preserve untracked or partially rendered component keyboards.
+        return True
+    action = await CommandPromptControls().match(event, bot)
+    if action == "cancel" and prompt is None:
+        return False
+    if action == "continue" and prompt is None:
+        await bot.send_message(event.chat.id, texts.stale, parse_mode=None)
+        return True
+    if action is None and prompt is not None and prompt.controls in {"reply", "hybrid"}:
+        action = ReplyPromptControls(texts.continue_label, texts.cancel_label).match(
+            event.text or ""
+        )
+        transport = "reply"
+    else:
+        transport = "commands"
+    if action is None:
+        return False
+    context = ControlContext(
+        key=key,
+        actor_id=event.from_user.id if event.from_user else 0,
+        transport=transport,
+        prompt_id=prompt.prompt_id if prompt else None,
+        message_id=event.message_id,
+        operation_id=f"update:{update_id}:idle:{action}",
+    )
+    result = await _dispatch(runtime, action, context)
+    if not result.accepted:
+        await bot.send_message(event.chat.id, result.message or texts.stale, parse_mode=None)
+    return True
+
+
+async def _dispatch(
+    runtime: ControlRuntime,
+    action: str,
+    context: ControlContext,
+) -> ControlResult:
+    if action == "continue":
+        return await runtime.continue_current(context)
+    return await runtime.cancel_current(context)
+
+
+async def _ack(bot: Bot, callback_id: str, text: str) -> None:
+    try:
+        await bot.answer_callback_query(callback_id, text=text)
+    except TelegramAPIError:
+        pass  # Expired acknowledgement cannot undo an already committed answer.