Skip to content

Application-owned sessions, isolation and drafts

Idle does not require navigation. The public FlowAdapter describes resumability, resume, abandon and tray restoration; the application continues to own business drafts, authentication and FSM data. Use the external session example for an executable ordinary-handler or FSM integration:

python -m pip install 'aiogram-idle[redis]==0.2.0'
python examples/external_sessions.py --help
# From a checkout, with BOT_TOKEN set in the environment:
python examples/external_sessions.py --controls inline
python examples/external_sessions.py --fsm --controls hybrid --timezone Europe/Berlin

The example uses in-process application sessions and memory storage deliberately. It is not a persistent authentication service. No token is read and no logging is configured on import. All four prompt control styles are supported, and --help does not need a token. The example's 30-second policy is explicitly enabled; library idle creation remains disabled by default.

Read-only session authority

Supply an object implementing SessionAuthority.current(CoordinationKey) to IdleRuntime(session_authority=...). Return an immutable ExternalSession or None when the application has no authorized session. The contract is exported by both Idle and aiogram-coordination:

from aiogram_coordination import CoordinationKey, ExternalSession


class ExistingSessions:
    def __init__(self, store):
        self.store = store

    async def current(self, key: CoordinationKey) -> ExternalSession | None:
        current = await self.store.read_current_session(key)
        if current is None:
            return None
        return ExternalSession(
            session_id=current.id,
            revision=current.revision,
            absolute_expires_at=current.absolute_expiry_ms,
            idle_expires_at=current.idle_expiry_ms,
        )

store is the application's existing service; adapt its public fields explicitly. Both expiries are UTC epoch milliseconds, not seconds or naive datetimes. The effective deadline is the earlier expiry. IDs must not be reused, and absolute expiry cannot change under the same ID. Revision is an opaque nonempty string. An unavailable service must raise, never return None. Idle wraps lookup failure as SessionAuthorityUnavailable, preserving recovery evidence and retrying later without treating the failure as logout or running abandonment.

Before selecting external mode, explicitly activate storage format 2 as described in Redis storage. Idle projects the external ID onto its own internal generation, with the original absolute expiry. It does not create, extend, replace or clear the application's session and does not clear FSM data on expiry. Authority is rechecked before activity acceptance, controls and external effects. A replaced/expired session cannot resume an older flow. Unresolved old effects remain retained and may require reconciliation before a new flow is admitted.

Explicit successful activity

Register a descriptor once rather than constructing activity snapshots in every handler:

from aiogram_idle import ActivityRegistration

editing = ActivityRegistration("draft.editing", policy_id="draft", adapter_key="application")
# Inside an installed, protected handler after application validation:
activity = await idle_context.activate(editing, operation_id="stable-application-operation")
# After a later successful edit:
activity = await idle_context.touch(
    expected=activity.guard, operation_id="stable-successful-edit-operation"
)

Pass the previous guard when replacing an existing activity. Use stable operation IDs for retries; the same ID must not describe different caller intent. A received update, failed validation or rejected application write must not count as activity. Library-owned mode still requires an explicitly opened session before activation. In external mode, open_session and replace_session reject the operation.

Share the real FSM lock

Construct the Dispatcher with an explicit wrapper. The installer never swaps its isolation silently:

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

application_lock = SimpleEventIsolation()
dispatcher = Dispatcher(events_isolation=TrackedEventIsolation(application_lock))
runtime.install(dispatcher)

For cross-process FSM locking, reuse the application Redis client and key builder with the renewable reference provider:

from aiogram import Dispatcher
from aiogram_coordination import RenewableRedisEventIsolation, TrackedEventIsolation


def dispatcher_for_application(redis, application_storage, application_key_builder):
    application_lock = RenewableRedisEventIsolation(
        redis=redis, key_builder=application_key_builder
    )
    return Dispatcher(
        storage=application_storage,
        events_isolation=TrackedEventIsolation(application_lock),
    )

The supplied storage may remain the application's encrypted FSM implementation. Its keys must preserve bot/chat/actor/field identity. Supported idle identity is still actor-owned private chats with FSMStrategy.USER_IN_CHAT; this feature does not silently add group, topic or business-message support.

A custom isolation implementation needs a public IsolationProvider that references that exact isolation and returns a key-bound LeaseHandle with valid ownership, an assertion and loss notification. Opaque fixed-TTL Redis locks are not assumed to renew. The reference provider is an explicit application choice, not an introspective wrapper around private aiogram Redis lock internals.

Handlers borrow proven ownership; workers acquire the same application lock. The order is application isolation, then Idle's own storage coordination. Redis commits retain their separate Lua ownership fence. Do not reacquire the application lock recursively, bypass coordination after a Redis failure or swallow lease-loss cancellation and continue business writes. Application session writes and business FSM mutations must participate in this same boundary. A separate database is not made transactional with Telegram or Redis by the wrapper.

Timezones, events and shutdown

TelegramPromptPresenter(quiet_hours=resolver) accepts a per-conversation async resolver (key, at_seconds) -> bool. QuietHours(timezone, start, end) is a reusable IANA-zone implementation. Applications choose the timezone explicitly; there is no guessed tenant timezone. UTC instants convert through zoneinfo, so repeated local times in an autumn fold share the same quiet classification; nonexistent spring-forward times have no corresponding instant. Midnight-spanning intervals are supported. Quiet hours change sound delivery, not authentication or deadlines.

on_event receives immutable IdleEvent(event_id, operation_id, outcome, key, activity_key, at, prompt_id=None) after commit; at is UTC epoch seconds. IdleOutcome enumerates shown, continued, cancelled, timed_out, restored, delivery_unknown, failed, and session_expired. Unknown adapter effects and quarantine remain inspectable phases; their observational outcome is failed. Events are best-effort observations, without a durable analytics outbox.

Use coarse_event_sink to map observational outcomes to application enums without forwarding actor, node, activity or prompt identifiers. Internal diagnostic events retain their identifiers for recovery. Sink failures cannot replay committed delivery or business effects. Never send message text or credentials to analytics.

Managed installation stops the runtime before aiogram closes its FSM resources. For an application-owned shutdown controller: stop new webhook/polling admission, await runtime.stop(), drain protected handler work, close the backend, then close FSM storage/isolation and application-owned Redis and Bot clients. Default shutdown_seconds is 10 seconds. Unfinished effects retain their actual pending or unknown evidence; a shutdown timeout does not mark them successful.

Unknown sends are suppressed by default. That avoids blind duplicate prompts but does not guarantee eventual delivery. Explicit retry of ambiguous sends may cause duplicates; reconcile using receipts and application idempotency evidence.