Skip to content

aiogram-coordination

Source development and releases are maintained in the aiogram-kit monorepo. See the workspace contributing guide; package examples live under packages/aiogram-coordination/.

Shared task-scoped ownership for aiogram applications and independent libraries. The package has no dependency on aiogram-idle, aiogram-nav or aiogram-kit.

Alpha version: 0.1.1. Requires Python 3.10+ and aiogram 3.22–3.x.

pip install aiogram-coordination==0.1.1
# Optional renewable Redis coordination:
pip install 'aiogram-coordination[redis]==0.1.1'

Memory coordination

from aiogram_coordination import CoordinationKey, MemoryCoordinator

coordinator = MemoryCoordinator()
key = CoordinationKey("bot", bot_id=123, chat_id=42, user_id=42)


async def protected_operation():
    async with coordinator.hold(key):
        scope = coordinator.scope_token(key)
        assert scope is not None
        # Invoke application code only while this task owns the scope.

Memory scopes serialize one process and one event loop. A child task does not inherit reentrant ownership. Identical structural conversation keys from independent libraries normalize to one full identity; arbitrary generic Hashable keys remain supported by the memory coordinator.

Existing application FSM isolation

Wrap isolation explicitly when constructing the Dispatcher, not after startup:

from aiogram import Dispatcher
from aiogram.fsm.storage.memory import SimpleEventIsolation
from aiogram_coordination import TrackedEventIsolation

application_isolation = SimpleEventIsolation()
tracked = TrackedEventIsolation(application_isolation)
dispatcher = Dispatcher(events_isolation=tracked)

A custom application isolation requires an explicit IsolationProvider tied to the exact same instance. It must return a key-bound, live LeaseHandle and signal loss. Unknown opaque locks, disabled isolation and unsupported proof are rejected. Custom isolation includes the contract and Redis reference.

Redis reference

from aiogram_coordination import RenewableRedisEventIsolation, TrackedEventIsolation

# application_redis is an existing redis.asyncio client owned by your app.
application_isolation = RenewableRedisEventIsolation(redis=application_redis)
tracked = TrackedEventIsolation(application_isolation)

This explicit renewable provider exposes ownership; it does not pretend to renew an opaque aiogram RedisEventIsolation lock. It reuses the caller's Redis client and public aiogram key builder. Client closure remains application-owned.

Use RedisCoordinator(redis=application_redis, prefix="application") for fenced conversation storage coordination. Its default lease/renew/wait/poll/I/O limits are 30/10/30/0.05/5 seconds. Lost leases revoke effect authority and cancel owners. A Lua storage transaction must check the returned fence token and positive PTTL; a local ownership check cannot make an external API transactional.

External sessions

SessionAuthority.current(key) returns an immutable ExternalSession or None. It reads only; it never creates, extends or clears application sessions. Outages raise SessionAuthorityUnavailable and are distinct from missing authorization. Session rules separate immutable absolute lifetime from a sliding application inactivity deadline.

Compatibility and verification

Component Supported / CI targets
Python 3.10–3.14
aiogram 3.22 minimum and latest resolvable 3.x
Redis client 5.0.8 minimum and latest below 8, optional
Redis server 7+ single writable primary; CI uses real Redis 7 and 8
Base install Neither Redis nor Idle/Nav/Kit is required

CI exercises installed wheels/sdists, task isolation, real Redis renewal/loss and process death. Verification evidence distinguishes executed checks from configured jobs. CONTRIBUTING.md documents commands, SECURITY.md reporting and release guidance the explicit tag-only publication procedure. Nothing configures logging globally on import. The CLI example enables only scoped development debug logging.

MIT licensed; see LICENSE.