Skip to main content

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 will not be published for 1.3.0: serial qualification 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.

Metadata

Release files for aiogram-sentinel 1.3.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for aiogram-sentinel 1.3.0
File Size Uploaded Provenance Actions
aiogram_sentinel-1.3.0.tar.gz 355.4 kB With provenance Details for aiogram_sentinel-1.3.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for aiogram-sentinel 1.3.0
File Interpreter ABI Platform Actions
aiogram_sentinel-1.3.0-py3-none-any.whl Python 3 none any Details for aiogram_sentinel-1.3.0-py3-none-any.whl

Total release size: 395.3 kB

Release files / aiogram_sentinel-1.3.0.tar.gz

Download URL aiogram_sentinel-1.3.0.tar.gz
Size 355.4 kB
Tags Source
SHA-256 checksum
How to use checksums
bf0525747279239a5810d717cdb40341d2fe5d2cba371214ee4a63b0afb6405c
BLAKE2b-256 checksum
How to use checksums
b6778f705f5bc507ed3f10116411e151606bdb3867f897a93670f35b0862df50
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 10, 2026.

Transparency log

Release files / aiogram_sentinel-1.3.0-py3-none-any.whl

Download URL aiogram_sentinel-1.3.0-py3-none-any.whl
Size 39.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
ec9c7422b23e480462e8c4f082056f445335c99d347ab56e15d17342bc2fd4f8
BLAKE2b-256 checksum
How to use checksums
29e45bc4340312a6d82852770d2301bf873b89a57ed2bd282f27b91e835bb4c7
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 10, 2026.

Transparency log

Security for aiogram-sentinel 1.3.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for aiogram_sentinel-1.3.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 10, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page