Optional aiogram-nav integration¶
aiogram_idle.integrations.nav projects navigation onto the idle backend. The two
standalone libraries still work independently. Importing aiogram_idle, including
its Redis backend, does not import or install aiogram-nav. Navigation itself has
no idle dependency.
Install the integration in a bot environment:
python -m pip install 'aiogram-idle[nav]==0.3.0'
# Select both optional integrations when using Redis:
python -m pip install 'aiogram-idle[nav,redis]==0.3.0'
The nav extra resolves aiogram-nav>=0.3.0,<0.4 from PyPI. Base and Redis-only
installations remain independent of aiogram-nav.
For source development, install the published optional dependencies and run the combined example from the idle checkout:
uv sync --frozen --extra nav --extra redis
uv run --no-sync python examples/navigation.py --style hybrid
Set BOT_TOKEN for the example. Set NAV_REDIS_URL to use Redis for both integrated navigation and the example's application FSM store. Without it, storage is memory and single-process. CLI help does not require either variable. All four styles are available: reply, inline, commands and hybrid. Debug logging is configured by the example, never globally by the library.
Construction and installation¶
from aiogram_idle.integrations.nav import NavigationIntegration, NodePolicies
from aiogram_nav import Navigation
integration = NavigationIntegration(
idle=idle,
registry=registry,
policies=NodePolicies(
default="none",
overrides={"editor": "draft"},
activities={"editor.rating": "editor", "editor.typing": "editor"},
),
adapters={"editor": application_flow_adapter},
)
navigation = Navigation(
registry=registry,
repository=integration.navigation_repository,
presenter=screen_presenter,
)
integration.install(dispatcher, navigation=navigation)
The referenced policy IDs must exist in idle.policies; none is an example
exempt-policy ID, not a reserved value. Policy overrides inherit through registry
parents. Activity grouping is an explicit exact-node mapping; dotted name prefixes
never imply membership. By default every node is its own activity.
Use only integration.install, before business Routers and before starting
workers. Do not first call navigation.install or idle.install; those create
standalone middleware with separate ownership assumptions. Duplicate installation,
multiple integration writers, incompatible registries, live coordinator changes,
unsupported isolation and lossy identity mapping are rejected. For headless
navigation/worker use, call integration.bind(navigation) instead and manage
idle.start() / idle.stop() yourself. Workers drain before shared FSM shutdown when the integration owns lifecycle. With application-owned shutdown, stop idle before closing shared stores.
lifecycle=False disables dispatcher
startup/shutdown hooks for tests or an application-owned lifecycle.
Application adapters supply eligibility (inspect) and idempotent business
cancellation (abandon). They do not own integrated screen reconstruction:
Continue re-renders the current node and restore renders its registry Cancel
destination. The integration records those effects and stages their navigation
result under the existing idle operation. The application cancellation hook gets a nested durable stage; its own replay_safe opt-in controls whether an unknown business effect may repeat. Application hooks must use the supplied
effect recorder or durable idempotency/version checks for their business writes.
One authoritative record¶
The idle backend owns the session, activity, idle state, deadlines and operation
receipts. Navigation owns a versioned opaque aiogram_nav component containing its
snapshot, prepared actions, stage receipts and callback tokens. Core idle treats
that payload as JSON; only the optional adapter interprets it.
Every navigation mutation executes the normal navigation reducer, then commits its component through an idle-owned conditional transaction. A completed accepted navigation action updates its displayed location, activity and due scheduling in that same transaction. No post-commit callback supplies the atomic guarantee. Memory uses the existing backend lock; Redis uses the authoritative envelope CAS and scheduling script. Network calls run outside backend locks.
Session IDs map to the same authoritative generation. Navigation expiry never exceeds that session’s absolute expiry and may be shorter; reconstruction never extends authentication. Navigation timestamps use integer milliseconds; idle uses seconds, with conversion only at this boundary. Both displayed activity revisions share one acceptance counter. Moving to a new activity group creates a fresh activity ID; refresh/parameter changes within the same group preserve it and accept activity once. Background rendering changes the view without advancing accepted activity or extending its deadline. Exempt nodes retain navigation but disarm ordinary idle prompts.
Standalone enter, touch, clear and session replacement cannot overwrite an
integration-owned activity. Business handlers use a mapped guard:
record = await idle.inspect(integration.navigation_repository.mapping.to_idle(nav_key))
await integration.touch(
nav_key, expected=record.activity.guard, operation_id="update:42:accepted-text"
)
Call this only after application processing succeeds. When a reply/hybrid prompt
has replaced the tray, touch also reserves a deterministic background render in
the same atomic transaction. It restores the application keyboard without
accepting activity twice; a crash leaves recoverable pending UI work. Duplicate
touch retries return the original activity receipt and do not render again. Use a distinct stable
operation ID for each logical action. restart_activity accepts the same guard
and explicitly starts a fresh activity generation within the current group.
An FSM write or external database update is not made atomic with idle by this
transaction. Use a durable producer outbox or an application transaction adapter
when that additional guarantee is required.
Coordination and input precedence¶
One idle conversation coordinator covers handlers, navigation actions and workers. The projection maps the complete namespace/tenant/bot/chat/actor identity into its lock domain. Identity mappings must preserve every supported field and round-trip. Built-in support is for actor-owned private chats; default FSM mapping cannot represent tenant-specific state and rejects that setup.
The combined middleware runs after the FSM middleware, verifies its storage and
key mapping, borrows the actual held SimpleEventIsolation lock, then acquires the
shared distributed lock when applicable. Workers acquire locks in the same order.
Disabled FSM isolation still receives full-handler coordination. Use
FSMStrategy.USER_IN_CHAT, and DefaultKeyBuilder(with_bot_id=True) for a shared
Redis FSM store. Merely choosing Redis for navigation does not make a memory FSM
store shared across processes.
Active idle controls precede navigation bindings, then business input. Bare /cancel falls through to the application when there is no idle prompt. Reply text and commands have current-prompt provenance only; inline controls retain their actor/session/activity/prompt or view ownership. Rejected callbacks acknowledge without stripping keyboards whose ownership is unproven.
Recovery and limits¶
Navigation prepare retains the old committed screen but suppresses idle prompts about it while rendering is unresolved. Generic recovery scheduling retains the pending component. A worker reuses confirmed rendering receipts; unknown sends, expired authorization or denied reconstruction park the component rather than resending automatically. Inspection retains the reason. Explicit recovery or a new safe refresh can resolve the retained navigation operation; do not delete its receipts to regain capacity.
Continue, timeout and Cancel reserve one idle operation. Their rendering uses that
operation's effect recorder and captured job claim. The navigation component and
idle lifecycle finish together. A crashed poller cannot discard its only recovery
job, and navigation checkpoints cannot replace a live worker's claim generation.
Temporary reply-keyboard provenance is invalidated when an idle prompt overlays
it. The canonical text presenter reinstalls the declared application keyboard,
or sends explicit removal if the reconstructed screen omits a keyboard. Custom
presenters receive RenderRequest.dependencies["aiogram_idle.reply_overlay"]
and must reconstruct or remove that temporary tray. Restoration requests also
carry aiogram_idle.silent_restore; the canonical text presenter sends them
silently, and custom presenters must honor that flag.
After commit, tracked obsolete inline controls are cleaned only under a live
coordination guard. Cleanup failures do not repeat business cancellation or sends.
Components and effect receipts have an absolute 8 MiB limit; max_components_bytes
can lower component admission. The complete persisted envelope is bounded at
32 MiB. The idle receipt budget is shared by preparation, effect checkpoints and completion,
not just completed screens. Configure it for the expected number of staged writes.
Receipt/history/control limits also apply; admission may reject before a
count limit if its byte bound is reached. Unresolved evidence is retained rather
than evicted. Redis requires a supported writable primary with noeviction; its
persistence and failover durability remain deployment responsibilities. Leases
cannot retract an in-flight Telegram request or fence arbitrary business stores.
Verification¶
The combined matrix is separate from standalone checks. coverage-nav.toml and
pyright-nav.json include the optional modules; default standalone checks omit
them and remain runnable without the peer package.
uv sync --frozen --extra nav --extra redis
AIOGRAM_IDLE_REDIS_URL=redis://localhost:6379/0 AIOGRAM_IDLE_REQUIRE_REDIS=1 \
uv run --no-sync pytest --cov=aiogram_idle --cov-config=coverage-nav.toml
uv run --no-sync pyright --project pyright-nav.json
Source checkouts resolve published peers; an adjacent repository is not required. See installation for explicit joint-development overrides.
An automatic, separate integration CI job installs published navigation through
the nav extra, runs the optional strict type profile and exercises
navigation/component tests with real Redis. Standalone jobs do not install
navigation. The manual optional-integration workflow uses the same published
dependencies and checks the broader Python 3.10–3.14 and Redis 8 matrix.
Configured jobs do not imply remote execution or package publication; consult
dated verification evidence for what was actually run.