aiogram-sentinel 0.1.0

Edge hygiene library for aiogram v3 with middlewares, router, and storage backends

aiogram-sentinel

Drop-in middlewares for aiogram v3 with batteries included - Protect your Telegram bots from spam, abuse, and unwanted behavior with powerful middleware and storage backends.

✨ Features

• Auth bootstrap with pluggable resolver → expose data["user_context"] without locking you to a DB.
• Blocking: deny early if user is blocked; auto-sync block/unblock via my_chat_member, with on_block / on_unblock hooks.
• Debouncing: suppress duplicate messages/callbacks within a window.
• Throttling: per-user/handler scopes; notifier hook for UX.
• Backends: memory (single worker) or redis (multi-worker), with configurable redis_prefix.
• Setup helper: Sentinel.setup(dp, cfg) wires recommended order and membership router.
• 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_sentinel import Sentinel, SentinelConfig

# 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
)

# Setup with one call - wires all middleware in recommended order
sentinel = Sentinel(config=config)
dp.message.middleware(sentinel.middleware)

# Your handlers now have access to user context
@dp.message()
async def handle_message(message, data):
    user_context = data["user_context"]  # Available after auth middleware
    await message.answer(f"Hello {user_context['username']}!")

# Start your bot
await dp.start_polling(bot)

📚 Documentation

• Quickstart - Get started in 5 minutes
• Configuration - Complete configuration guide
• API Reference - Full API documentation
• Tutorials - Step-by-step guides
• Performance - Benchmarks and optimization
• Migration Guides - Upgrade instructions
• Roadmap - Future plans and features
• Examples - Complete working examples

🤝 Contributing

See CONTRIBUTING.md for development guidelines and setup instructions.

🔒 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