aiogram-coordination 0.1.0__py3-none-any.whl

aiogram_coordination/__init__.py

@@ -0,0 +1,47 @@
+"""Shared task-scoped coordination without Idle/Nav dependencies."""
+
+from .errors import (
+    ConfigurationError,
+    CoordinationError,
+    OwnershipLost,
+    PersistenceUnavailable,
+    SessionAuthorityUnavailable,
+)
+from .identity import CoordinationKey, coordination_key
+from .isolation import AiogramMemoryCoordinator, TrackedEventIsolation
+from .memory import MemoryCoordinator
+from .protocols import (
+    BorrowedFsmCoordinator,
+    Coordinator,
+    FencedCoordinator,
+    IsolationProvider,
+    LeaseHandle,
+)
+from .redis import RedisCoordinator
+from .redis_isolation import RedisIsolationProvider, RenewableRedisEventIsolation
+from .sessions import ExternalSession, SessionAuthority, validate_session_transition
+from .version import __version__ as __version__
+
+__all__ = [
+    "BorrowedFsmCoordinator",
+    "AiogramMemoryCoordinator",
+    "TrackedEventIsolation",
+    "RenewableRedisEventIsolation",
+    "RedisIsolationProvider",
+    "CoordinationKey",
+    "coordination_key",
+    "Coordinator",
+    "FencedCoordinator",
+    "MemoryCoordinator",
+    "RedisCoordinator",
+    "IsolationProvider",
+    "LeaseHandle",
+    "ExternalSession",
+    "SessionAuthority",
+    "validate_session_transition",
+    "ConfigurationError",
+    "CoordinationError",
+    "OwnershipLost",
+    "PersistenceUnavailable",
+    "SessionAuthorityUnavailable",
+]

aiogram_coordination/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_coordination/errors.py

@@ -0,0 +1,21 @@
+"""Public coordination and authority failures; no credentials in messages."""
+
+
+class CoordinationError(Exception):
+    """Base shared coordination failure."""
+
+
+class ConfigurationError(CoordinationError, ValueError):
+    """The requested setup cannot prove safe coordination."""
+
+
+class OwnershipLost(CoordinationError):
+    """The protected scope no longer owns its lock or lease."""
+
+
+class PersistenceUnavailable(CoordinationError):
+    """The lock's authoritative storage is unavailable."""
+
+
+class SessionAuthorityUnavailable(CoordinationError):
+    """Session lookup failed; this is not an unauthorized-session result."""

aiogram_coordination/identity.py

@@ -0,0 +1,66 @@
+"""Lossless full-identity keys shared without importing consuming libraries."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Protocol, cast
+
+from .errors import ConfigurationError
+
+
+@dataclass(frozen=True)
+class CoordinationKey:
+    namespace: str
+    bot_id: int
+    chat_id: int
+    user_id: int
+    tenant_id: str | None = None
+
+    def __post_init__(self) -> None:
+        if (
+            not isinstance(cast(object, self.namespace), str)
+            or not self.namespace
+            or len(self.namespace) > 128
+        ):
+            raise ConfigurationError("Namespace must contain 1 to 128 characters")
+        for name in ("bot_id", "chat_id", "user_id"):
+            value = getattr(self, name)
+            if type(value) is not int or value <= 0:
+                raise ConfigurationError(f"{name} must be a positive integer")
+        if self.tenant_id is not None and (
+            not isinstance(cast(object, self.tenant_id), str)
+            or not self.tenant_id
+            or len(self.tenant_id) > 128
+        ):
+            raise ConfigurationError("Tenant must be nonempty text when supplied")
+
+
+class _Identity(Protocol):
+    namespace: str
+    bot_id: int
+    chat_id: int
+    user_id: int
+    tenant_id: str | None
+
+
+def coordination_key(key: object) -> CoordinationKey:
+    """Accept validated structural library keys without collapsing any identity."""
+    if isinstance(key, CoordinationKey):
+        return key
+    for field in ("thread_id", "message_thread_id", "business_connection_id", "destiny"):
+        value = getattr(key, field, None)
+        if value is not None and not (field == "destiny" and value == "default"):
+            raise ConfigurationError(
+                "Additional FSM identity requires an explicit lossless mapping"
+            )
+    structural = cast(_Identity, key)
+    try:
+        return CoordinationKey(
+            namespace=structural.namespace,
+            bot_id=structural.bot_id,
+            chat_id=structural.chat_id,
+            user_id=structural.user_id,
+            tenant_id=structural.tenant_id,
+        )
+    except (AttributeError, TypeError) as error:
+        raise ConfigurationError("Expected a lossless full conversation identity") from error

aiogram_coordination/isolation.py

@@ -0,0 +1,331 @@
+"""Explicit, verifiable application-owned FSM isolation integration."""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import AsyncGenerator, Callable, Hashable
+from contextlib import AbstractAsyncContextManager, asynccontextmanager
+from contextvars import ContextVar
+from dataclasses import dataclass
+from typing import cast
+
+from aiogram.fsm.storage.base import BaseEventIsolation, StorageKey
+from aiogram.fsm.storage.memory import SimpleEventIsolation
+
+from .errors import ConfigurationError, OwnershipLost
+from .identity import coordination_key
+from .memory import MemoryCoordinator
+from .protocols import IsolationProvider, LeaseHandle
+
+
+@dataclass
+class _MemoryLease:
+    key: StorageKey
+    lost: asyncio.Event
+
+    @property
+    def valid(self) -> bool:
+        return not self.lost.is_set()
+
+    def assert_owned(self) -> None:
+        if not self.valid:
+            raise OwnershipLost("FSM isolation ownership ended")
+
+    async def wait_lost(self) -> None:
+        await self.lost.wait()
+
+
+class _SimpleProvider:
+    def __init__(self, isolation: SimpleEventIsolation) -> None:
+        self.isolation = isolation
+
+    @asynccontextmanager
+    async def acquire(self, key: StorageKey) -> AsyncGenerator[LeaseHandle, None]:
+        async with self.isolation.lock(key=key):
+            lease = _MemoryLease(key, asyncio.Event())
+            try:
+                yield lease
+            finally:
+                lease.lost.set()
+
+
+@dataclass
+class _Held:
+    key: StorageKey
+    task: asyncio.Task[object]
+    lease: LeaseHandle
+    revoked: bool = False
+
+    @property
+    def valid(self) -> bool:
+        return not self.revoked and self.lease.valid
+
+    def assert_owned(self) -> None:
+        if not self.valid:
+            raise OwnershipLost("Captured FSM scope was revoked")
+
+    async def wait_lost(self) -> None:
+        if not self.valid:
+            return
+        await self.lease.wait_lost()
+
+
+class TrackedEventIsolation(BaseEventIsolation):
+    """Wrap application isolation at Dispatcher construction, never at install.
+
+    Only SimpleEventIsolation has a safe implicit provider. A custom provider
+    must explicitly reference the same underlying isolation and return a live,
+    key-bound lease; opaque fixed-TTL locks are never assumed to renew.
+    """
+
+    def __init__(
+        self,
+        isolation: BaseEventIsolation,
+        *,
+        provider: IsolationProvider | None = None,
+        close_delegate: bool = False,
+    ) -> None:
+        if not isinstance(cast(object, isolation), BaseEventIsolation):
+            raise ConfigurationError("Expected an application BaseEventIsolation")
+        if provider is None:
+            if type(isolation) is SimpleEventIsolation:
+                provider = _SimpleProvider(isolation)
+            elif isinstance(isolation, RenewableRedisEventIsolation):
+                provider = isolation
+            else:
+                raise ConfigurationError("Custom isolation requires an explicit lease provider")
+        if (
+            not isinstance(cast(object, provider), IsolationProvider)
+            or provider.isolation is not isolation
+        ):
+            raise ConfigurationError("Lease provider must describe the exact application isolation")
+        if type(close_delegate) is not bool:
+            raise ConfigurationError("close_delegate must be boolean")
+        self.isolation = isolation
+        self.provider = provider
+        self.close_delegate = close_delegate
+        self._owned: ContextVar[tuple[_Held, ...]] = ContextVar(
+            f"tracked_fsm_{id(self)}", default=()
+        )
+        self._pending = 0
+        self._closed = False
+
+    @property
+    def active_scopes(self) -> int:
+        return self._pending
+
+    def _held(self, key: StorageKey) -> _Held | None:
+        task = asyncio.current_task()
+        return next(
+            (held for held in reversed(self._owned.get()) if held.key == key and held.task is task),
+            None,
+        )
+
+    def owns(self, key: StorageKey) -> bool:
+        held = self._held(key)
+        return held is not None and not held.revoked and held.lease.valid
+
+    def proof(self, key: StorageKey) -> LeaseHandle:
+        held = self._held(key)
+        if held is None:
+            raise OwnershipLost("FSM scope is not owned by this task")
+        held.assert_owned()
+        return held
+
+    @asynccontextmanager
+    async def borrowed(self, key: StorageKey) -> AsyncGenerator[None, None]:
+        held = self._held(key)
+        if held is None or held.revoked:
+            raise OwnershipLost("FSM lock is not owned by this task")
+        held.lease.assert_owned()
+        yield
+        if held.revoked or not held.lease.valid:
+            raise OwnershipLost("Borrowed FSM scope was revoked")
+
+    @asynccontextmanager
+    async def _acquire(self, key: StorageKey) -> AsyncGenerator[LeaseHandle, None]:
+        self._pending += 1
+        try:
+            async with self.provider.acquire(key) as lease:
+                if self._closed:
+                    raise ConfigurationError("FSM isolation closed during acquisition")
+                yield lease
+        finally:
+            # Includes waiting, protected work AND provider.__aexit__ release.
+            self._pending -= 1
+
+    @asynccontextmanager
+    async def lock(self, key: StorageKey) -> AsyncGenerator[None, None]:
+        if self._closed or not isinstance(cast(object, key), StorageKey):
+            raise ConfigurationError("Isolation is closed or the FSM key is invalid")
+        if self._held(key) is not None:
+            async with self.borrowed(key):
+                yield
+            return
+        task = asyncio.current_task()
+        if task is None:
+            raise ConfigurationError("FSM coordination requires a task")
+        async with self._acquire(key) as lease:
+            if not isinstance(cast(object, lease), LeaseHandle) or lease.key != key:
+                raise ConfigurationError("Isolation provider returned an invalid lease identity")
+            lease.assert_owned()
+            held = _Held(key, task, lease)
+            token = self._owned.set((*self._owned.get(), held))
+            marker = object()
+            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
+            requested = consumed = legacy_marker = False
+            legacy_previous: object = None
+
+            async def watch() -> None:
+                nonlocal requested, legacy_marker, legacy_previous
+                try:
+                    await lease.wait_lost()
+                except asyncio.CancelledError:
+                    raise
+                except Exception:
+                    # An inability to monitor ownership must revoke permission.
+                    pass
+                held.revoked = True
+                if cancelling is None:
+                    legacy_previous = getattr(task, "_cancel_message", None)
+                requested = task.cancel(marker)
+                if requested and cancelling is None and hasattr(task, "_cancel_message"):
+                    try:
+                        setattr(task, "_cancel_message", marker)  # noqa: B010 -- CPython 3.10
+                    except (AttributeError, TypeError):
+                        pass
+                    else:
+                        legacy_marker = True
+
+            def consume() -> int:
+                nonlocal consumed
+                if requested and not consumed and uncancel is not None:
+                    consumed = True
+                    return uncancel()
+                return cancelling() if cancelling is not None else 0
+
+            watcher = asyncio.create_task(watch())
+            try:
+                yield
+                if held.revoked or not lease.valid:
+                    raise OwnershipLost("FSM isolation lease lost")
+            except asyncio.CancelledError as error:
+                remaining = consume()
+                if requested and (
+                    remaining <= baseline
+                    if cancelling is not None
+                    else error.args == (marker,)
+                    and (not legacy_marker or getattr(task, "_cancel_message", None) is marker)
+                ):
+                    raise OwnershipLost("FSM isolation lease lost") from error
+                raise
+            finally:
+                held.revoked = True
+                self._owned.reset(token)
+                if legacy_marker and getattr(task, "_cancel_message", None) is marker:
+                    setattr(task, "_cancel_message", legacy_previous)  # noqa: B010
+                watcher.cancel()
+                await asyncio.gather(watcher, return_exceptions=True)
+                consume()
+
+    async def close(self) -> None:
+        if self.active_scopes:
+            raise ConfigurationError("Drain FSM scopes before closing isolation")
+        self._closed = True
+        if self.close_delegate:
+            await self.isolation.close()
+
+
+class AiogramMemoryCoordinator(MemoryCoordinator):
+    """Borrow a proven FSM scope; workers acquire the same normalized lock."""
+
+    configuration_error = ConfigurationError
+    ownership_lost_error = OwnershipLost
+
+    def __init__(self, isolation: object) -> None:
+        if type(isolation) is not SimpleEventIsolation and not isinstance(
+            isolation, TrackedEventIsolation
+        ):
+            raise self.configuration_error("Expected verified Simple or TrackedEventIsolation")
+        super().__init__()
+        self.isolation = isolation
+        self._fsm_proofs: dict[object, LeaseHandle] = {}
+
+    @property
+    def active_scopes(self) -> int:
+        fsm_active = (
+            self.isolation.active_scopes if isinstance(self.isolation, TrackedEventIsolation) else 0
+        )
+        return max(super().active_scopes, fsm_active)
+
+    @property
+    def fsm_isolation(self) -> BaseEventIsolation:
+        return self.isolation
+
+    def configure_fsm_isolation(self, isolation: BaseEventIsolation) -> None:
+        if isolation is not self.isolation:
+            raise self.configuration_error("FSM bridge cannot replace its configured isolation")
+
+    def borrowed_fsm(self, key: Hashable) -> AbstractAsyncContextManager[None]:
+        return self.borrowed(key)
+
+    def scope_active(self, token: object) -> bool:
+        proof = self._fsm_proofs.get(token)
+        if proof is not None and not proof.valid:
+            self._live_scopes.discard(token)
+        return super().scope_active(token)
+
+    @asynccontextmanager
+    async def borrowed(self, key: Hashable) -> AsyncGenerator[None, None]:
+        key = self.normalize_key(key)
+        normalized = coordination_key(key)
+        fsm_key = StorageKey(
+            bot_id=normalized.bot_id, chat_id=normalized.chat_id, user_id=normalized.user_id
+        )
+        if self.owns(key):
+            yield
+            return
+        if isinstance(self.isolation, TrackedEventIsolation):
+            proof = self.isolation.proof(fsm_key)
+            async with self.isolation.borrowed(fsm_key), self._scope(key):
+                scope = self.scope_token(key)
+                if scope is None:
+                    raise self.ownership_lost_error("No borrowed FSM scope was established")
+                self._fsm_proofs[scope] = proof
+                try:
+                    yield
+                finally:
+                    self._fsm_proofs.pop(scope, None)
+        else:
+            # Legacy installer verifies this branch executes inside aiogram FSM.
+            async with self._scope(key):
+                yield
+
+    @asynccontextmanager
+    async def hold(self, key: Hashable) -> AsyncGenerator[None, None]:
+        key = self.normalize_key(key)
+        self._check_reentry(key)
+        if self.owns(key):
+            yield
+            return
+        normalized = coordination_key(key)
+        fsm_key = StorageKey(
+            bot_id=normalized.bot_id, chat_id=normalized.chat_id, user_id=normalized.user_id
+        )
+        self._pending_scopes += 1
+        acquired = False
+        try:
+            async with self.isolation.lock(key=fsm_key):
+                self._pending_scopes -= 1
+                acquired = True
+                async with self.borrowed(key):
+                    yield
+        finally:
+            if not acquired:
+                self._pending_scopes -= 1
+
+
+# Imported last to keep Redis coordination independent of this adapter module.
+from .redis_isolation import RenewableRedisEventIsolation  # noqa: E402

aiogram_coordination/memory.py

@@ -0,0 +1,127 @@
+"""Single-process, task-scoped conversation coordination."""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import AsyncGenerator, Hashable
+from contextlib import asynccontextmanager
+from contextvars import ContextVar
+from dataclasses import dataclass
+
+from .errors import OwnershipLost
+from .identity import coordination_key
+
+
+@dataclass
+class _LockEntry:
+    lock: asyncio.Lock
+    users: int = 0
+
+
+class MemoryCoordinator:
+    """Serialize a whole handler and worker for each conversation.
+
+    Ownership is checked against the actual asyncio Task. Context copied into a
+    child task never grants that task permission to bypass the lock.
+    """
+
+    ownership_lost_error = OwnershipLost
+
+    def __init__(self) -> None:
+        self._locks: dict[Hashable, _LockEntry] = {}
+        self._owned: ContextVar[tuple[tuple[Hashable, asyncio.Task[object]], ...]] = ContextVar(
+            f"coord_owned_{id(self)}", default=()
+        )
+
+        self._scope_tokens: ContextVar[
+            tuple[tuple[Hashable, asyncio.Task[object], object], ...]
+        ] = ContextVar(f"coord_scope_tokens_{id(self)}", default=())
+        self._live_scopes: set[object] = set()
+        self._scope_keys: dict[object, Hashable] = {}
+        self._pending_scopes = 0
+
+    def normalize_key(self, key: Hashable) -> Hashable:
+        if all(
+            hasattr(key, field)
+            for field in ("namespace", "tenant_id", "bot_id", "chat_id", "user_id")
+        ):
+            return coordination_key(key)
+        return key
+
+    @property
+    def active_scopes(self) -> int:
+        return len(self._scope_keys) + self._pending_scopes
+
+    def scope_token(self, key: Hashable) -> object | None:
+        key = self.normalize_key(key)
+        task = asyncio.current_task()
+        for held, owner, token in reversed(self._scope_tokens.get()):
+            if held == key and owner is task and self.scope_active(token):
+                return token
+        return None
+
+    def scope_active(self, token: object) -> bool:
+        return token in self._live_scopes
+
+    def scope_matches(self, key: Hashable, token: object) -> bool:
+        """Validate a delegated capability without granting task lock ownership."""
+        return self._scope_keys.get(token) == self.normalize_key(key) and self.scope_active(token)
+
+    @asynccontextmanager
+    async def _scope(self, key: Hashable) -> AsyncGenerator[None, None]:
+        key = self.normalize_key(key)
+        task = asyncio.current_task()
+        if task is None:
+            raise RuntimeError("Conversation coordination requires an asyncio task")
+        scope = object()
+        self._live_scopes.add(scope)
+        self._scope_keys[scope] = key
+        ownership = self._owned.set((*self._owned.get(), (key, task)))
+        tokens = self._scope_tokens.set((*self._scope_tokens.get(), (key, task, scope)))
+        try:
+            yield
+        finally:
+            self._live_scopes.discard(scope)
+            self._scope_keys.pop(scope, None)
+            self._scope_tokens.reset(tokens)
+            self._owned.reset(ownership)
+
+    def owns(self, key: Hashable) -> bool:
+        return self.scope_token(key) is not None
+
+    def _check_reentry(self, key: Hashable) -> None:
+        key = self.normalize_key(key)
+        task = asyncio.current_task()
+        if not self.owns(key) and any(
+            held == key and owner is task for held, owner, _ in self._scope_tokens.get()
+        ):
+            raise self.ownership_lost_error("A revoked scope cannot acquire fresh ownership")
+
+    @asynccontextmanager
+    async def hold(self, key: Hashable) -> AsyncGenerator[None, None]:
+        key = self.normalize_key(key)
+        self._check_reentry(key)
+        if self.owns(key):
+            yield
+            return
+        entry = self._locks.setdefault(key, _LockEntry(asyncio.Lock()))
+        entry.users += 1
+        self._pending_scopes += 1
+        acquired = False
+        try:
+            async with entry.lock:
+                self._pending_scopes -= 1
+                acquired = True
+                async with self._scope(key):
+                    yield
+        finally:
+            if not acquired:
+                self._pending_scopes -= 1
+            entry.users -= 1
+            if entry.users == 0:
+                self._locks.pop(key, None)
+
+    @property
+    def lock_count(self) -> int:
+        """Number of active or contended locks, useful for health checks."""
+        return len(self._locks)