maxapi

Inner middleware accumulates down the router hierarchy. When a handler is executed, its middleware chain (mw_chain) is composed of:

1. Global inner_middlewares from the Dispatcher.
2. inner_middlewares from all parent Routers in the hierarchy.
3. inner_middlewares from the specific Router containing the handler.
4. The handler's own local middlewares.

Example Hierarchy: If a parent router has DbTransactionMiddleware and a child router has ChildAuditMiddleware, a handler inside child will execute both in that order before calling the handler itself.

parent = Router(router_id="parent")
parent.register_inner_middleware(DbTransactionMiddleware())

child = Router(router_id="child")
child.register_inner_middleware(ChildAuditMiddleware())

parent.include_routers(child)
# Handlers in 'child' will run: [DbTransactionMiddleware, ChildAuditMiddleware] + local_middlewares

You can organize bot logic using Router objects and manage user flow using MemoryContext with StatesGroup.

• Routers: Use Router() to create modular handlers that can be included in a main Dispatcher via dp.include_routers(router).
• States: Define a class inheriting from StatesGroup with State() members to represent different steps in a conversation.
• Context: Use MemoryContext to persist data (update_data, get_data) and manage the current state (set_state, get_state, clear).
• Filtering: Use the F magic filter to trigger handlers based on specific conditions, such as F.callback.payload == '...' or combining a message filter with a specific state (e.g., @dp.message_created(F.message.body.text, Form.name)).

from maxapi import Bot, Dispatcher, F
from maxapi.context import MemoryContext, State, StatesGroup
from maxapi.types import MessageCreated, CallbackButton
from maxapi.utils.inline_keyboard import InlineKeyboardBuilder
from maxapi import Router

# 1. Define States
class Form(StatesGroup):
    name = State()
    age = State()

router = Router()

# 2. Use Router and Context to manage state transitions
@router.message_callback(F.callback.payload == "btn_1")
async def handle_btn_1(event: MessageCallback, context: MemoryContext):
    await context.set_state(Form.name)
    await event.message.answer("Отправьте свое имя:")

# 3. Handle input within a specific state
@router.message_created(F.message.body.text, Form.name)
async def handle_name_input(event: MessageCreated, context: MemoryContext):
    await context.update_data(name=event.message.body.text)
    await event.message.answer(f"Hello, {event.message.body.text}!")

The F object (MagicFilter) provides a powerful way to filter incoming messages based on their content and attributes. Supported operations include:

• Equality: F.message.body.text == "value"
• String methods: .lower().contains("substring")
• Regex: .regexp(r"pattern")
• Length checks: .len() > 20
• Existence: F.message.body.attachments (checks if attachments exist)
• Empty checks: .len() > 0

@dp.message_created(F.message.body.text == "привет")
async def on_hello(event: MessageCreated):
    await event.message.answer("Привет!")

@dp.message_created(F.message.body.text.lower().contains("помощь"))
async def on_help(event: MessageCreated):
    await event.message.answer("Чем могу помочь?")

@dp.message_created(F.message.body.text.regexp(r"^\d{4}$"))
async def on_code(event: MessageCreated):
    await event.message.answer("Принят 4-значный код")

@dp.message_created(F.message.body.attachments)
async def on_attachment(event: MessageCreated):
    await event.message.answer("Получено вложение")

@dp.message_created(F.message.body.text.len() > 20)
async def on_long_text(event: MessageCreated):
    await event.message.answer("Слишком длинное сообщение")

The Dispatcher and Router distinguish between two types of middleware based on when they are executed in the event lifecycle:

1. Outer Middleware (register_outer_middleware(mw)): Called before any filters or state checks for a specific handler are evaluated. It triggers for every event that reaches the dispatcher/router, even if the handler is eventually skipped. Use this for logging, tracing, or generating request IDs.
2. Inner Middleware (register_inner_middleware(mw)): Called only after a specific handler has passed all its filters and state requirements. It is guaranteed that the handler will be executed. Use this for database transactions, timing handler execution, or acquiring distributed locks.

Note: The methods dp.middleware(), router.middleware(), dp.outer_middleware(), and router.outer_middleware() are deprecated. Always use register_outer_middleware() and register_inner_middleware() instead.

# Registering on a Dispatcher
dp.register_outer_middleware(LoggingMiddleware())  # Every update
dp.register_inner_middleware(DbTransactionMiddleware())  # Only under handler

# Registering on a Router
router.register_outer_middleware(AuditMiddleware())
router.register_inner_middleware(LockMiddleware())

The maxapi framework distinguishes between two types of middleware to optimize performance and control execution flow:

Outer Middleware

• When it runs: Executes for every incoming event/update, even if no handler is matched or if filters (like IsAdmin) reject the request.
• Best use cases:
  • Tracing and Request IDs (RequestIdMiddleware).
  • Global logging of all incoming updates (LoggingMiddleware).
  • Security auditing (e.g., logging attempts to access admin routes before authorization checks occur).
• Registration: Use register_outer_middleware().

Inner Middleware

• When it runs: Executes only if a handler is actually matched and is about to be executed.
• Best use cases:
  • Database transactions (DbTransactionMiddleware) that should only start when a write/read is certain.
  • Performance metrics (HandlerLatencyMetricMiddleware) that only care about handler execution time.
  • Resource locks (BroadcastLockMiddleware) that should only be held during the actual operation to avoid unnecessary overhead.
• Registration: Use register_inner_middleware().

# Global Outer: runs for everything
dp.register_outer_middleware(LoggingMiddleware())

# Global Inner: runs only if a handler is found
dp.register_inner_middleware(DbTransactionMiddleware())

# Router Outer: runs for any event targeting this router
admin_router.register_outer_middleware(AdminAccessLogMiddleware())

# Router Inner: runs only when an admin handler is called
admin_router.register_inner_middleware(BroadcastLockMiddleware())