Skip to content

Application-owned FSM isolation

Construct the application isolation, wrap it explicitly, then pass the wrapper to Dispatcher(events_isolation=...). Library installers must not replace the configured isolation after FSM middleware begins loading state.

TrackedEventIsolation verifies the exact application instance, full FSM StorageKey, current task and live lease. owns(key) is task-scoped. borrowed(key) refuses absent, expired, foreign or child-task ownership. Nested calls in the actual owning task do not recursively acquire the underlying lock.

Custom provider

Implement the public IsolationProvider protocol:

class ApplicationProvider:
    def __init__(self, application_isolation):
        self.isolation = application_isolation

    def acquire(self, key):
        # Return an async context manager that acquires THIS application's lock.
        # It yields a LeaseHandle and always releases its own ownership.
        return self.isolation.acquire_with_receipt(key)

The application-owned acquire_with_receipt is an example of an application API, not a method supplied by aiogram. A returned LeaseHandle exposes key, valid, assert_owned() and await wait_lost(). Its identity must equal the requested StorageKey. valid and assert_owned must account for actual ownership and expiry; wait_lost signals revocation, including inability to monitor the lock. The wrapper cancels the owner on loss and refuses success even if cancellation is suppressed. Applications must not suppress cancellation and continue writes.

Opaque BaseEventIsolation.lock() alone does not expose enough evidence for custom distributed leases and is rejected. Provider configuration and key builders must remain unchanged while in use. The library does not invent renewal for existing RedisEventIsolation locks whose tokens are hidden.

Redis reference provider

RenewableRedisEventIsolation(redis=existing_client, key_builder=builder) is a complete explicit application isolation provider. It uses token-checked renewal, a fixed maximum I/O budget and the public key builder's lock key. It does not wrap or invoke opaque locks, and it never closes the caller's client. Its default builder separates bot, business connection and destiny. A supplied builder must at least separate bot/chat/actor. The provider probes thread/business/destiny separation too. A supplied private-only builder remains usable for default FSM keys, but a requested unsupported dimension is rejected before any Redis command. Two distinct nondefault values are checked so presence-only encoders cannot silently alias all business sessions or destinies.

The actual full StorageKey remains part of scope identity. Conversation normalization never collapses thread, destiny or business fields of FSM locks.

Ordering, storage fencing and shutdown

Application coordinator bridges implement the public BorrowedFsmCoordinator capability so installers do not need concrete package-class checks. The bridge must borrow the live Tracked receipt and preserve scope validity; advertising method names or distributed=True alone does not prove safe ownership.

Acquire application FSM isolation first, then the library's storage coordinator. An incoming handler borrows its already-held FSM scope; a worker acquires that same lock before storage coordination. Storage mutations still require an atomic Redis fence check; sharing the FSM lock does not replace CAS or token validation.

Active-scope reporting includes queued acquisitions and release tails after effect authority is already revoked. Coordinators bound to a Tracked wrapper also count that wrapper's active application scopes, conservatively delaying drain until external FSM release finishes.

Stop accepting updates, stop workers, drain protected scopes, then close FSM storage and caller-owned Redis clients. TrackedEventIsolation.close() rejects active scopes and does not close the delegate by default. Set close_delegate=True only when that ownership is intentional. It never closes a client independently of the configured delegate. No cross-database transaction or exactly-once business effect is promised.