Rubka | مستندات میدلورها (Middleware)

میدلورها (Middleware)

سیستم میدلور قدرتمند در کتابخانه روبکا — پردازش لایه‌ای پیام‌ها، اعتبارسنجی، لاگینگ و مدیریت خطاها

Middleware v2.0

میدلور چیست؟

میدلورها توابعی هستند که قبل، بعد یا هنگام خطا در پردازش پیام‌ها اجرا می‌شوند. از میدلورها برای:

اولویت‌بندی (MiddlewarePriority)
MiddlewarePriority
Enum برای تعیین اولویت اجرای میدلورها
HIGHEST = 0 HIGH = 1 NORMAL = 2 LOW = 3 LOWEST = 4

میدلورها بر اساس اولویت (عدد کمتر = اولویت بالاتر) مرتب می‌شوند.

from rubka.middleware import MiddlewarePriority

@bot.before_middleware(priority=MiddlewarePriority.HIGHEST)
async def first_middleware(bot, message, context):
    print("اولین میدلور اجرا می‌شود")
    return True
میدلور اصلی (@bot.middleware)
@bot.middleware()
میدلور اصلی که handler بعدی را دریافت می‌کند و می‌تواند قبل و بعد از اجرا کد اجرا کند
نامنوعتوضیحات
priorityMiddlewarePriorityاولویت میدلور (پیشفرض NORMAL)
namestr | Noneنام دلخواه برای میدلور
پارامترنوعتوضیحات
botRobotنمونه ربات
messageMessageپیام دریافتی
next_handlerCallableتابع بعدی در زنجیره
metadatadictداده‌های جانبی
@bot.middleware(priority=MiddlewarePriority.HIGH)
async def log_middleware(bot, message, next_handler, metadata):
    print("بل از اجرا")
    result = await next_handler(bot, message)
    print("بعد از اجرا")
    return result
میدلور قبل از اجرا (@bot.before_middleware)
@bot.before_middleware()
میدلوری که قبل از اجرای هندلر اصلی اجرا می‌شود
priorityMiddlewarePriorityاولویت میدلور (پیشفرض NORMAL)
پارامترنوعتوضیحات
botRobotنمونه ربات
messageMessageپیام دریافتی
contextdictداده‌های جانبی
@bot.before_middleware(priority=MiddlewarePriority.HIGHEST)
async def check_user(bot, message, context):
    if message.sender_id not in allowed_users:
        await message.reply("شما دسترسی ندارید!")
        return False  # جلوگیری از ادامه پردازش
    return True  # ادامه پردازش
میدلور بعد از اجرا (@bot.after_middleware)
@bot.after_middleware()
میدلوری که بعد از اجرای هندلر اصلی اجرا می‌شود
priorityMiddlewarePriorityاولویت میدلور (پیشفرض NORMAL)
پارامترنوعتوضیحات
botRobotنمونه ربات
messageMessageپیام دریافتی
resultAnyنتیجه اجرای هندلر
contextdictداده‌های جانبی
@bot.after_middleware()
async def send_log(bot, message, result, context):
    print(f"پیام {message.message_id} پردازش شد")
    # می‌توانید result را تغییر دهید
    return result
میدلور خطا (@bot.error_middleware)
@bot.error_middleware()
میدلوری که در صورت بروز خطا در پردازش پیام اجرا می‌شود
priorityMiddlewarePriorityاولویت میدلور (پیشفرض NORMAL)
پارامترنوعتوضیحات
botRobotنمونه ربات
messageMessageپیام دریافتی
errorExceptionخطای رخ داده
contextdictداده‌های جانبی
@bot.error_middleware()
async def handle_error(bot, message, error, context):
    print(f"❌ خطا: {error}")
    await message.reply("متأسفانه خطایی رخ داد!")
    return True  # خطا مدیریت شد
کلاس MiddlewareManager
MiddlewareManager
مدیریت و هماهنگی اجرای میدلورها
متدتوضیحات
add_middleware(func, priority, name)افزودن میدلور اصلی
add_before_middleware(func, priority)افزودن میدلور قبل
add_after_middleware(func, priority)افزودن میدلور بعد
add_error_middleware(func, priority)افزودن میدلور خطا
run_middlewares(bot, message, handler, context)اجرای زنجیره میدلورها
from rubka.middleware import MiddlewareManager, MiddlewarePriority

manager = MiddlewareManager()

# افزودن میدلور
manager.add_middleware(log_middleware, MiddlewarePriority.NORMAL)

# اجرا
result = await manager.run_middlewares(bot, message, handler, {})
مثال کامل کاربردی
مثال کامل میدلورها
نمایش کامل استفاده از میدلورها در یک ربات
from rubka import Robot
from rubka.context import Message
from rubka.middleware import MiddlewarePriority

bot = Robot(token="YOUR_TOKEN")

# قبل از همه میدلورها
@bot.before_middleware(priority=MiddlewarePriority.HIGHEST)
async def before_all(bot, message, context):
    print("⚡ قبل از همه چیز")
    return True

# میدلور اصلی برای لاگینگ
@bot.middleware()
async def log_middleware(bot, message, next_handler, metadata):
    print("1️⃣ قبل از اجرا")
    result = await next_handler(bot, message)
    print("3️⃣ بعد از اجرا")
    return result

# بعد از میدلورها
@bot.after_middleware()
async def after_all(bot, message, result, context):
    if hasattr(message, 'reply'):
        await message.reply("پیام از after_middleware ارسال شد!")
    return result

# هندلر اصلی
@bot.on_message(commands=["start"])
async def start(bot: Robot, message: Message):
    print("داخل دستور start")
    await message.reply("سلام!")

bot.run()

ترتیب اجرا:

1️⃣ before_middleware → 2️⃣ middleware → 3️⃣ handler اصلی → 4️⃣ after_middleware

اگر before_middleware مقدار False برگرداند، زنجیره قطع می‌شود و handler اجرا نمی‌شود.

کاربردهای میدلور
سناریوهای کاربردی
موارد استفاده رایج از میدلورها
# محدودیت نرخ ارسال (Rate Limiting)
@bot.before_middleware()
async def rate_limit(bot, message, context):
    if is_rate_limited(message.sender_id):
        await message.reply("⏳ لطفاً کمی صبر کنید!")
        return False
    return True

#⃣ بررسی عضویت در کانال
@bot.before_middleware()
async def check_membership(bot, message, context):
    is_member = await bot.check_join("channel_id", message.chat_id)
    if not is_member:
        await message.reply("لطفاً ابتدا در کانال عضو شوید!")
        return False
    return True

# اندازه‌گیری زمان پاسخ
@bot.middleware()
async def measure_time(bot, message, next_handler, metadata):
    start = time.time()
    result = await next_handler(bot, message)
    duration = time.time() - start
    print(f"⏱️ زمان پاسخ: {duration:.2f} ثانیه")
    return result

#ذخیره خودکار پیام‌ها در دیتابیس
@bot.after_middleware()
async def save_to_db(bot, message, result, context):
    await bot.save_message(message)
    return result