Redis navigation storage¶
The optional Redis backend persists the same navigation snapshots, prepared operations, stage receipts and actor/session/view-bound controls as memory storage. It is independent of aiogram-idle. No idle worker or navigation-to-idle adapter is installed.
pip install 'aiogram-nav[redis]==0.3.0'
from aiogram_nav import Navigation
from aiogram_nav.storage.redis import RedisNavigationRepository
repository = await RedisNavigationRepository.from_url(redis_url, prefix="my-bot:navigation")
navigation = Navigation(registry=registry, repository=repository, presenter=presenter)
# Install before business routers. Close only after handlers/workers drain.
navigation.install(dispatcher)
# ... application lifetime ...
await repository.close()
Alternatively supply redis=client and call await repository.initialize().
Supplied clients remain caller-owned. from_url owns and closes its client.
Use a stable prefix for replicas sharing state and a separate prefix for unrelated
applications. Identity includes namespace, bot, private conversation, actor and
tenant; a shared prefix alone does not establish compatible application ownership.
Server and configuration¶
Redis 7 or newer, a writable standalone primary, scripting and noeviction are
required. Cluster is rejected. Startup verifies these requirements and persists a
storage configuration profile. Replicas must agree on all storage limits and
lifetimes; startup never overwrites an established profile. The root node is an
application registry setting and is excluded from the storage profile.
Redis client support is redis>=5.0.8,<8. Operations have bounded I/O timeouts.
No failure selects a local-memory fallback.
Redis TIME supplies authoritative milliseconds. Local monotonic interpolation is only for runtime checks between server operations. Atomic commits recheck expiry and any coordination fence. Clock jumps are logged without exposing keys, URLs, tokens or draft text.
The namespace stores a profile, an establishment witness, a retained-conversation index and one versioned JSON envelope per conversation. Each mutation loads the authoritative envelope, applies the shared memory contract as a temporary reducer, then performs an atomic compare-and-swap. There is no persistent local mirror. Concurrent CAS retries are bounded; stale caller versions remain conflicts. Opaque receipts are checked before stale-version rejection. Record size is bounded in addition to configured receipt, token, history and conversation limits.
Ownership and FSM¶
A renewable Redis conversation lease serializes complete protected handlers and navigation workers across replicas. Writes validate the lease token in the same script as state mutation. Lease loss revokes the task capability and cancels its owner. Copied child-task context never becomes independent lock ownership.
With SimpleEventIsolation, the dispatcher borrows its actual held FSM lock and
then acquires Redis. Background navigation acquires the same locks in the same
order. Disabled FSM isolation uses Redis for the entire handler. Unsupported
custom isolation is rejected. Use FSMStrategy.USER_IN_CHAT; for Redis FSM storage
use DefaultKeyBuilder(with_bot_id=True). Every replica must use the same shared
FSM storage. A local memory FSM store remains local even when navigation is Redis.
The runnable examples/redis_demo.py uses a shared Redis FSM store.
A lease cannot retract an already-sent Telegram request or fence an unrelated business database. Business writes still need their own durable version checks and operation IDs. Navigation does not clear application FSM data.
Recovery and operational limits¶
A confirmed partial render survives process exit. Retrying the original operation
reuses confirmed stage receipts and performs only definitely unsent or explicitly
safe work. An interrupted started send is uncertain; automatic resend stays
suppressed. A completed operation can be recovered without repeating delivery.
A lost commit response raises CommitUnknown: inspect/retry the same operation
ID before choosing a new action. Never infer that an absent receipt after Redis
data loss proves that Telegram did not receive a request.
Scripts use EVALSHA with bounded NOSCRIPT reload. Other transport failures are
uncertain execution; script errors are BackendInconsistent. Missing witnesses,
index inconsistencies, malformed schemas and incompatible profiles fail closed.
Do not delete or rebuild these keys while traffic runs. Corruption requires
operator investigation and explicit restoration from a consistent backup; there
is no automatic administrative index rebuild or rollback detector.
await repository.sweep(limit=100) walks the retained index in bounded pages and
reclaims expired terminal evidence. Unresolved operations are retained and may
exhaust capacity; inspect and resolve them instead of deleting evidence to admit
new work. Call sweep periodically if inactive conversations should be reclaimed
before the next capacity-triggered bounded sweep. There is no scheduling poller
in navigation.
Persistence, backups, replication and failover durability are deployment choices. The package cannot recover receipts discarded by Redis rollback or total data loss. Tests exercise real servers and process death, not infrastructure failover.
The Redis audit records follow-up fixes to cleanup ownership, sweep validation, strict FSM borrowing and persisted receipt validation. Rejected callbacks are acknowledgement-only; they do not prove ownership of the message containing them.
Staged storage format activation (0.1 → 0.2)¶
New repositories write the existing format 1 by default. Version 0.2 reads formats 1 and 2, but external application-session bindings require explicit format 2. A deployment upgrade does not automatically enable new persistence behavior.
Drain all 0.1 writers and protected handlers, take a Redis backup, and assess the existing namespace using its exact configured prefix and storage configuration:
report = await repository.activate_storage_format(operation_id="upgrade-020")
# Read-only assessment: report.before, after, conversations, pending, applied.
Or use the repository tool; provide credentials through the environment:
export AIOGRAM_NAV_REDIS_URL=redis://localhost:6379/0
uv run --no-sync python tools/migrate_storage.py --prefix my-navigation
uv run --no-sync python tools/migrate_storage.py --prefix my-navigation \
--apply --old-workers-drained --operation-id upgrade-020
A pristine dry run does not bootstrap keys. Applying requires an explicit operator drain assertion and zero active local coordination scopes. The CLI uses default storage settings and strict deployment probes; deployments with customized settings or managed-service attestation should use the API on their configured repository. The API call is:
report = await repository.activate_storage_format(
expected=1,
target=2,
operation_id="upgrade-020",
old_workers_drained=True,
dry_run=False,
)
Activation atomically rotates the namespace profile/history witness and records a stable operation receipt. An initialized old writer then fails its existing Lua history check; an old startup fails the profile check. A lost activation response can be retried with the same operation ID. Other operation IDs cannot silently replace the activation decision.
Existing records, session IDs, prompt/control tokens, partial renders and operation receipts are not rewritten or discarded by activation. New writes migrate an individual envelope under the normal guarded transaction. Unresolved effects are retained and are never replayed by migration. New readers accept retained format-1 records while writing format 2. Missing or corrupt format metadata fails closed.
Before activation, binary rollback is possible while format 1 remains in use. After activation, old binaries cannot share the namespace. Use a compatible forward fix, or a coordinated backup restore after all writers stop. Restoring a backup cannot undo Telegram sends or application database effects; review retained uncertainty before restarting any delivery.
Managed Redis with denied introspection¶
Strict startup probes INFO server, ROLE, INFO cluster and
CONFIG GET maxmemory-policy. Supported storage is Redis 7+, a writable single
primary, non-cluster, with noeviction. Runtime ACLs also need GET, SET, DEL,
EXISTS, TYPE, TIME, PTTL, PEXPIRE, SADD, SREM, SCARD, SISMEMBER,
SSCAN, EVALSHA and SCRIPT LOAD, restricted to the chosen namespace. The Lua
scripts call the corresponding allowed data commands. Tests may use administrative
commands to create isolated ACL users; those are not runtime requirements.
If managed Redis denies introspection with NOPERM, supply facts independently
verified by the operator:
from aiogram_nav.storage.deployment import RedisDeploymentAttestation
from aiogram_nav.storage.redis import RedisNavigationRepository
repository = RedisNavigationRepository(
redis=application_redis,
prefix="my-navigation",
deployment=RedisDeploymentAttestation(
server_major=7,
writable_primary=True,
cluster_enabled=False,
maxmemory_policy="noeviction",
operator_reference="reviewed-redis-change-123",
),
)
Attestation substitutes only the specific facts whose probe is denied. Observed
unsafe configuration, malformed responses, connection errors and timeouts still
fail startup. The library logs command names when attestation is used, not
credentials or the operator reference. There is no warning-only unsafe mode and
no memory fallback. Caller-supplied Redis clients remain caller-owned; from_url
creates a client closed by repository shutdown.
Redis persistence, replication and failover configuration remain deployment-owned. A successful commit is not a guarantee against infrastructure data loss; retained history detects missing state rather than silently reconstructing it around uncertain Telegram effects.