aiogram-sentinel

Rate limiting and debouncing middleware for aiogram v3 - Protect your Telegram bots from spam and abuse with powerful middleware and storage backends.

✨ Features

• Rate Limiting: Per-user/handler scopes with sliding window algorithm
• Debouncing: Suppress duplicate messages/callbacks within a configurable window
• Storage Backends: Memory (single worker) or Redis (multi-worker) with configurable prefixes
• Decorators: @rate_limit and @debounce for easy handler configuration
• Hooks: Optional on_rate_limited callback for custom user feedback
• Setup Helper: Sentinel.setup(dp, cfg) wires middleware in recommended order
• Typed, async-first, production-ready.

📦 Installation

# Basic installation
pip install aiogram-sentinel

# With Redis support
pip install aiogram-sentinel[redis]

⚡ Quick Start

from aiogram import Bot, Dispatcher
from aiogram.types import Message
from aiogram_sentinel import Sentinel, SentinelConfig, rate_limit, debounce

# Create bot and dispatcher
bot = Bot(token="YOUR_BOT_TOKEN")
dp = Dispatcher()

# Configure aiogram-sentinel
config = SentinelConfig(
    throttling_default_max=10,  # 10 messages per window
    throttling_default_per_seconds=60,  # 60 second window
    debounce_default_window=2,  # 2 second debounce
)

# Setup with one call - wires all middleware in recommended order
router, infra = await Sentinel.setup(dp, config)

# Your handlers with protection
@router.message()
@rate_limit(5, 60)  # 5 messages per minute
@debounce(1.0)      # 1 second debounce
async def handle_message(message: Message):
    await message.answer(f"Hello! Your message: {message.text}")

# Start your bot
await dp.start_polling(bot)

📚 Documentation

👉 Full Documentation ← Start here!

• Quickstart - Get started in 5 minutes
• Configuration - Complete configuration guide
• API Reference - Full API documentation
• Tutorials - Step-by-step guides
• Performance - Benchmarks and optimization
• Examples - Complete working examples

🤝 Contributing

See CONTRIBUTING.md for development guidelines and setup instructions.

💬 Community & Support

• 💬 Discussions - Questions, ideas, and community chat
• 🐛 Issues - Bug reports and concrete feature requests
• 📖 Documentation - Complete guides and API reference

🎯 Where to Get Help

🔒 Security

For security issues, see SECURITY.md.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Built for aiogram v3 - Modern Telegram Bot API framework
• Inspired by the need for robust bot protection in production environments