Skip to content

aiogram-sentinel

Source development and releases are maintained in the aiogram-kit monorepo. See the workspace contributing guide; package examples live under packages/aiogram-sentinel/.

Rate limiting and debouncing for aiogram 3. Sentinel protects handlers on its router and descendant routers while retaining application authorization middleware.

Install

pip install aiogram-sentinel
# Optional shared Redis storage:
pip install 'aiogram-sentinel[redis]'

Protect an application router

from aiogram import Dispatcher, Router
from aiogram_sentinel import ActionPolicy, Sentinel, SentinelConfig, ThrottleCfg

app = Router()
features = Router()
app.include_router(features)
# Register application handlers on features or app, then during async startup:
dp = Dispatcher()
router, infra = await Sentinel.setup(
    dp,
    SentinelConfig(
        bucket_mode="action_kind",
        action_policies={
            "message": ActionPolicy(throttle=ThrottleCfg(rate=5, per=10)),
            "command": ActionPolicy(throttle=ThrottleCfg(rate=3, per=10)),
            "callback_query": ActionPolicy(throttle=ThrottleCfg(rate=20, per=10)),
        },
    ),
    router=app,
)

These rates are examples, not new defaults. bucket_mode="shared" remains the default, with the existing limit of 5 events per 10 seconds and 2-second debounce. A command is a message with an initial Telegram bot_command entity. Command, message and callback namespaces are distinct only when explicitly requested.

Attachment matters: middleware on a sibling router does not wrap another router's handlers. Pass the application's ancestor router to setup, or register handlers on the returned router. Startup warns once when its protected subtree has no message/callback handlers. Do not attach the router to the Dispatcher before calling setup.

Named handler policies and legacy decorators now resolve the registered aiogram callback, including on aiogram 3.31. See configuration for precedence and explicit /start or callback-prefix exemptions. Exemptions bypass only Sentinel spam protections, never application guards.

Infrastructure failures

ErrorConfig(reraise_exceptions=(TimeoutError,)) propagates matching exceptions unchanged instead of sending friendly feedback. Add redis.exceptions.RedisError when using Redis, and aiogram_sentinel.exceptions.BackendOperationError for failures wrapped by Sentinel storage. This alone does not select an HTTP status: Dispatcher error handlers must re-raise, and a foreground webhook adapter must map the failure to 503. Background acknowledgement cannot be changed retroactively.

See the application integration guide for existing-client ownership, middleware/error ordering and the webhook recipe.

Compatibility and verification

Component Supported/tested contract
Python 3.10–3.13 in required CI
aiogram >=3.0,<4; minimum 3.0 and current 3.x tested
redis-py Optional >=5.0.8,<8; minimum/current endpoints tested
Redis server 7 and 8 tested; older servers are not qualified
Memory storage Single process/event loop; sliding-window rate limiter
Redis storage Shared clients; fixed-window counter with atomic expiry

Redis rate limiting requires EVAL, INCR, TTL, EXPIRE, GET; debounce requires SET with NX/EX. The middleware's retry-after lookup also uses TTL. No INFO, ROLE or CONFIG privileges are required by Sentinel. Availability, eviction and persistence remain deployment responsibilities; Sentinel does not provide Idle/Nav scheduling or durable business-effect recovery.

The library never configures logging globally. Examples enable scoped debug output and use recording Telegram sessions in tests; no real messages are sent by tests.

Native companion: publication withheld

The source includes optional engine="rust" memory infrastructure, but the native companion remains withheld for 1.3.1: serial qualification of the 1.3.0 kernels measured 11.65% and 7.63% CPU reductions in the selected workloads, below the required 20%. Latency measurements were unstable, so no tail-latency gain is claimed. Python remains the default and the optimized base package can ship independently. There is no native release or [native] extra; the core remains available from source. See the host-specific benchmark decision and engine selection and semantics.