Skip to content

Redis concurrency and recovery audit

This historical follow-up review checks the standalone Redis implementation against the reviewed storage, recovery and FSM contracts. It preceded the separately implemented optional navigation integration; these Redis fixes introduced no navigation dependency into the standalone runtime.

Corrected gaps

Finding Correction
A namespace marker or established configuration could disappear between a Python check and a script Lua reads and mutations now validate namespace history and the configuration witness atomically; losing established state never bootstraps new defaults
Replicas could disagree about retention and storage limits An immutable namespace profile binds retention, conversation/receipt/token capacities and parameter limits; incompatible clients fail initialization
Awaited child tasks could checkpoint effects without the parent Redis lock fence Effect checkpoints carry the captured coordination scope; backends validate the live, conversation-bound capability and Redis commits compare the actual lock token
A revoked handler could acquire a fresh scope and continue An open revoked scope rejects reentry and unfenced commits
Workers omitted the local FSM lock used by incoming handlers Workers acquire the same verified SimpleEventIsolation instance before Redis; middleware borrows its already-held FSM lock without recursive acquisition
Redis FSM keys could alias different bots Redis FSM key builders must distinguish bot, chat, user and state/data fields; use DefaultKeyBuilder(with_bot_id=True)
FSM configuration could change after installation Middleware checks isolation, normalized identity and actual FSM middleware placement before borrowing
Missing jobs and orphan due entries could block queue progress Bounded polling repairs missing jobs and conditionally removes obsolete due entries; reconciliation parks corrupt records and continues healthy work
Corruption could arrive between job validation and claiming CLAIM compares the exact validated job snapshot before mutation
Unknown business effects could lose their ledger through ordinary input EFFECT_UNKNOWN and QUARANTINED operations block business-handler admission and public activity replacement until explicitly resolved
Storage delays could consume the remaining grace budget before sending Eligibility is checked again immediately before outer/custom and recorded Telegram question stages
A foreign ActionReceipt could finish the current operation Nonempty receipt operation IDs must match the reserved operation
An old heartbeat could extend ownership after a newer heartbeat Ordered renewal timestamps prevent A/B/replay-A from extending the lease again
Quarantine could park a repaired replacement snapshot Classification and CAS now refer to the same captured bytes; unsupported/binary evidence is retained
NOSCRIPT retries could misclassify a subsequent script error Reload is bounded; Redis response-error subclasses consistently halt the affected scope as BackendInconsistent
Expired positive evidence could be reported as proof of absence Expired receipts return unknown_history rather than not_found_within_retention
Caught timeouts or lease revocations could leave cancellation bookkeeping behind Timeout and coordinator scopes remove only their own cancellation request and preserve external cancellation

Operational contracts

Configure storage limits identically across replicas. Runtime polling/concurrency knobs and enablement are not part of the immutable storage profile. Existing namespaces using an older unversioned layout are rejected rather than silently rewritten. Migration requires explicit evidence-preserving administrative work; changing prefixes is not a substitute for resolving old effects.

For Redis FSM storage:

from aiogram.fsm.storage.redis import DefaultKeyBuilder, RedisStorage

storage = RedisStorage(
    redis=redis_client,
    key_builder=DefaultKeyBuilder(prefix="my-bot:fsm", with_bot_id=True),
)

Disabled FSM event isolation remains supported because idle supplies renewable distributed coordination for the full handler. When SimpleEventIsolation is enabled, installation binds its exact instance to workers. Configure it before installation and do not replace it afterward. Custom FSM isolation still requires a supported adapter and is rejected by the current integration.

Coordinator.scope_matches(key, scope) validates a live capability's conversation binding. Backend implementers must support the optional transition(..., coordination_scope=...) argument used by delegated effect checkpoints. A captured scope authorizes the guarded checkpoint; it does not transfer handler lock ownership or make detached tasks safe.

Unknown business outcomes require an operator/application recovery decision based on external evidence. Under the shared coordinator, trusted recovery code can use a guarded backend transition to record that decision. Ordinary clear/enter/touch must not erase the ledger. DELIVERY_UNKNOWN retains its separate documented supersession behavior. No automatic replay of uncertain business actions was added.

Verification and boundaries

See verification results for the current test count, coverage, compatibility and artifact checks. New real-Redis tests interpose between reads, validation and commits rather than relying only on timing races. They cover namespace/configuration loss, profile mismatches, changed claim candidates, revoked scopes, delegated checkpoints, FSM wait ordering, queue repair, quarantine and renewal replay. Memory regressions cover the shared recovery contracts.

Redis infrastructure rollback/failover qualification, Redis Cluster, external session stores and durable analytics remain deferred. Navigation adapters were deferred at this audit and are now implemented separately; see navigation.md. In-flight Telegram or application requests cannot be retracted by a lease; application writes still need business-generation checks and idempotency.