codex-bot 0.1.0__py3-none-any.whl

codex_bot/engine/middlewares/i18n.py

@@ -0,0 +1,90 @@
+"""
+FSMContextI18nManager — Locale manager via FSM storage.
+
+Integrates with aiogram-i18n. Stores the user's selected language
+in FSM (Redis) instead of a database, requiring no additional queries.
+"""
+
+from typing import Any
+
+from aiogram.fsm.context import FSMContext
+from aiogram.types import User
+
+from ...fsm.state_helper import StateHelper
+
+try:
+    from aiogram_i18n.managers import BaseManager
+except ImportError as e:
+    raise ImportError("FSMContextI18nManager requires 'aiogram-i18n'. Install it: pip install codex-bot[i18n]") from e
+
+
+class FSMContextI18nManager(BaseManager):
+    """
+    Language manager via FSM storage (Redis).
+
+    Locale determination priority:
+    1. FSM storage (key "locale") — user explicitly selected a language.
+    2. Telegram language_code — if it's in the allowed_locales list.
+    3. default_locale — fallback.
+
+    Args:
+        allowed_locales: List of allowed language codes (e.g., ["ru", "en", "de"]).
+        default_locale: Default language if nothing matches.
+
+    Example:
+        ```python
+        from aiogram_i18n import I18nMiddleware
+        from aiogram_i18n.cores import FluentRuntimeCore
+
+        i18n = I18nMiddleware(
+            core=FluentRuntimeCore(path="locales/{locale}"),
+            manager=FSMContextI18nManager(allowed_locales=["ru", "en"], default_locale="en"),
+            default_locale="en",
+        )
+        i18n.setup(dp)
+        ```
+    """
+
+    def __init__(
+        self,
+        allowed_locales: list[str] | None = None,
+        default_locale: str = "en",
+    ) -> None:
+        self.allowed_locales: list[str] = allowed_locales or []
+        self.default_locale: str = default_locale
+
+    async def get_locale(self, event_from_user: User | None = None, **kwargs: Any) -> str:
+        """
+        Determines the user's current locale.
+
+        Args:
+            event_from_user: Telegram user.
+            **kwargs: aiogram-i18n context (includes "state").
+
+        Returns:
+            String locale code (e.g., "ru").
+        """
+        state: FSMContext | None = kwargs.get("state")
+        if state:
+            locale = await StateHelper.get_value(state, "locale")
+            if isinstance(locale, str):
+                return locale
+
+        if event_from_user:
+            lang = event_from_user.language_code
+            if lang and (not self.allowed_locales or lang in self.allowed_locales):
+                return lang
+
+        return str(self.default_locale)
+
+    async def set_locale(self, locale: str, **kwargs: Any) -> None:
+        """
+        Saves the selected locale to FSM.
+
+        Args:
+            locale: Language code to save.
+            **kwargs: Context (includes "state").
+        """
+        state: FSMContext | None = kwargs.get("state")
+        if state:
+            await StateHelper.update_value(state, "locale", locale)

codex_bot/engine/middlewares/throttling.py

@@ -0,0 +1,69 @@
+"""
+ThrottlingMiddleware — Spam protection via atomic Redis rate limiting.
+
+Uses the atomic SET NX (Set if Not eXists) operation instead of
+two separate EXISTS + SET, which eliminates race conditions during
+concurrent requests and halves the load on Redis.
+"""
+
+import logging
+from collections.abc import Awaitable, Callable
+from typing import Any
+
+from aiogram import BaseMiddleware
+from aiogram.types import CallbackQuery, TelegramObject
+
+log = logging.getLogger(__name__)
+
+
+class ThrottlingMiddleware(BaseMiddleware):
+    """
+    Rate limiting middleware via atomic Redis SET NX.
+
+    One network request instead of two (EXISTS + SET).
+    Atomicity eliminates race conditions during parallel updates.
+
+    Args:
+        redis: Async Redis client (``redis.asyncio.Redis``).
+        rate_limit: Minimum interval between requests in seconds.
+                    Supports fractional values (e.g., ``0.5``).
+
+    Example:
+        ```python
+        from redis.asyncio import Redis
+        from codex_bot.engine.middlewares import ThrottlingMiddleware
+
+        redis = Redis.from_url("redis://localhost")
+        builder.add_middleware(ThrottlingMiddleware(redis=redis, rate_limit=0.5))
+        ```
+    """
+
+    def __init__(self, redis: Any, rate_limit: float = 1.0) -> None:
+        self.redis = redis
+        self.rate_limit = rate_limit
+
+    async def __call__(
+        self,
+        handler: Callable[[TelegramObject, dict[str, Any]], Awaitable[Any]],
+        event: TelegramObject,
+        data: dict[str, Any],
+    ) -> Any:
+        user_id: int | None = event.from_user.id if hasattr(event, "from_user") and event.from_user else None
+
+        if not user_id:
+            return await handler(event, data)
+
+        key = f"throttle:{user_id}"
+
+        # Atomic operation: creates a key with TTL only if it didn't exist.
+        # Returns True on creation, None if the key already existed.
+        # px = milliseconds, supports fractional rate_limit (0.5 → 500 ms)
+        is_new = await self.redis.set(key, "1", px=int(self.rate_limit * 1000), nx=True)
+
+        if not is_new:
+            log.warning(f"Throttling | user={user_id} blocked")
+            if isinstance(event, CallbackQuery):
+                await event.answer("⏳ Not so fast!", show_alert=False)
+            return None
+
+        return await handler(event, data)

codex_bot/engine/middlewares/user_validation.py

@@ -0,0 +1,49 @@
+"""
+UserValidationMiddleware — User presence check in an event.
+
+Blocks processing of events without from_user (protection against system events,
+channels without a subscriber, bots). Adds user to data for handlers.
+"""
+
+import logging
+from collections.abc import Awaitable, Callable
+from typing import Any
+
+from aiogram import BaseMiddleware
+from aiogram.types import CallbackQuery, Message, TelegramObject
+
+log = logging.getLogger(__name__)
+
+
+class UserValidationMiddleware(BaseMiddleware):
+    """
+    User validation middleware in an incoming event.
+
+    For Message and CallbackQuery:
+    - Blocks events without from_user (returns None).
+    - Adds `data["user"]` — an aiogram User object — for handlers.
+
+    For other event types (Update, etc.) — passes without checking,
+    allowing the bot to send messages to channels.
+
+    Example:
+        ```python
+        dp.message.middleware(UserValidationMiddleware())
+        dp.callback_query.middleware(UserValidationMiddleware())
+        ```
+    """
+
+    async def __call__(
+        self,
+        handler: Callable[[TelegramObject, dict[str, Any]], Awaitable[Any]],
+        event: TelegramObject,
+        data: dict[str, Any],
+    ) -> Any:
+        if isinstance(event, Message | CallbackQuery):
+            user = event.from_user
+            if not user:
+                log.warning(f"UserValidation | no from_user event_type={type(event).__name__}")
+                return None
+            data["user"] = user
+
+        return await handler(event, data)

codex_bot/engine/router_builder/__init__.py

@@ -0,0 +1,10 @@
+"""
+codex_bot.engine.router_builder — Parametric assembly of the main router.
+"""
+
+from codex_bot.engine.router_builder.router_builder import build_main_router, collect_feature_routers
+
+__all__ = [
+    "collect_feature_routers",
+    "build_main_router",
+]

codex_bot/engine/router_builder/router_builder.py

@@ -0,0 +1,133 @@
+"""
+RouterBuilder — Parametric assembly of the main Aiogram router.
+
+Replaces hardcoded core/routers.py with explicit parameters
+module_prefix and installed_features.
+
+Fail Fast Principle: if a feature is declared in installed_features and its handlers.py
+contains an error — the startup fails immediately, rather than silently ignoring the problem.
+"""
+
+from __future__ import annotations
+
+import importlib
+import logging
+
+from aiogram import Router
+
+log = logging.getLogger(__name__)
+
+
+def collect_feature_routers(
+    installed_features: list[str],
+    module_prefix: str = "",
+    handler_module: str = "handlers",
+) -> list[Router]:
+    """Collects Aiogram routers from feature modules.
+
+    For each feature in ``installed_features``, it attempts to import
+    ``{module_prefix}.{feature_path}.{handler_module}``
+    and extract the ``router`` attribute from it.
+
+    **Fail Fast:** ``ImportError`` (no handlers file) — silent skip.
+    Any other error (syntax, runtime) — exception propagates up, the bot does not start.
+
+    Args:
+        installed_features: List of paths to features
+            (e.g., ``["features.telegram.booking", "features.telegram.profile"]``).
+        module_prefix: Module prefix
+            (e.g., ``"myproject"`` → ``"myproject.features.telegram.booking.handlers"``).
+            Empty string — ``feature_path`` is used directly.
+        handler_module: Name of the module with the router (default is ``"handlers"``).
+
+    Returns:
+        List of found ``Router`` objects.
+
+    Raises:
+        Exception: Any module loading error except ``ImportError`` (no file).
+
+    Example:
+        ```python
+        routers = collect_feature_routers(
+            installed_features=["features.telegram.booking", "features.telegram.profile"],
+            module_prefix="myproject",
+        )
+        ```
+    """
+    routers: list[Router] = []
+
+    for feature_path in installed_features:
+        module_path = (
+            f"{module_prefix}.{feature_path}.{handler_module}" if module_prefix else f"{feature_path}.{handler_module}"
+        )
+
+        try:
+            module = importlib.import_module(module_path)
+            feature_router = getattr(module, "router", None)
+            if feature_router and isinstance(feature_router, Router):
+                routers.append(feature_router)
+                log.info(f"RouterBuilder | feature='{feature_path}' status=loaded")
+            else:
+                log.debug(f"RouterBuilder | feature='{feature_path}' status=no_router_attr")
+        except ImportError as e:
+            if getattr(e, "name", None) == module_path:
+                # No handlers.py file — feature without UI, this is normal
+                log.debug(f"RouterBuilder | feature='{feature_path}' status=no_handlers_file")
+            else:
+                # handlers.py exists, but there's a broken import inside — fail
+                log.critical(f"RouterBuilder | Broken import inside '{feature_path}': {e}")
+                raise
+        # SyntaxError, NameError, etc. — not caught, the application fails immediately
+
+    return routers
+
+
+def build_main_router(
+    installed_features: list[str],
+    module_prefix: str = "",
+    handler_module: str = "handlers",
+    extra_routers: list[Router] | None = None,
+    router_name: str = "main_router",
+) -> Router:
+    """Assembles the main application router.
+
+    Creates a ``Router(name=router_name)``, includes routers from all features
+    and additional routers (e.g., ``common_fsm_router``).
+
+    Args:
+        installed_features: List of paths to features.
+        module_prefix: Module prefix (see ``collect_feature_routers``).
+        handler_module: Name of the module with the router (default is ``"handlers"``).
+        extra_routers: Additional routers included after features
+            (e.g., ``[common_fsm_router]``).
+        router_name: Name of the main router.
+
+    Returns:
+        The assembled ``Router``.
+
+    Example:
+        ```python
+        from codex_bot.engine.router_builder import build_main_router
+        from codex_bot.fsm import common_fsm_router
+
+        main_router = build_main_router(
+            installed_features=settings.INSTALLED_FEATURES,
+            module_prefix="myproject",
+            extra_routers=[common_fsm_router],
+        )
+        dp.include_router(main_router)
+        ```
+    """
+    main_router = Router(name=router_name)
+    feature_routers = collect_feature_routers(
+        installed_features=installed_features,
+        module_prefix=module_prefix,
+        handler_module=handler_module,
+    )
+
+    all_routers: list[Router] = feature_routers + (extra_routers or [])
+    if all_routers:
+        main_router.include_routers(*all_routers)
+
+    log.info(f"RouterBuilder | UI features loaded={len(feature_routers)} extra={len(extra_routers or [])}")
+    return main_router

codex_bot/fsm/__init__.py

@@ -0,0 +1,16 @@
+"""
+codex_bot.fsm — FSM manager, garbage collector, and common handlers.
+"""
+
+from .common_fsm_handlers import common_fsm_router
+from .garbage_collector import GarbageStateRegistry, IsGarbageStateFilter
+from .state_helper import StateHelper
+from .state_manager import BaseStateManager
+
+__all__ = [
+    "BaseStateManager",
+    "StateHelper",
+    "GarbageStateRegistry",
+    "IsGarbageStateFilter",
+    "common_fsm_router",
+]

codex_bot/fsm/common_fsm_handlers.py

@@ -0,0 +1,46 @@
+"""
+common_fsm_router — Common FSM handlers for the entire bot.
+
+Connected to the main router via build_main_router() or manually:
+    dp.include_router(common_fsm_router)
+
+Current set of handlers:
+    - Garbage Collector: deletes text messages in "garbage" states.
+"""
+
+import logging
+
+from aiogram import F, Router
+from aiogram.exceptions import TelegramAPIError
+from aiogram.fsm.context import FSMContext
+from aiogram.types import Message
+
+from .garbage_collector import IsGarbageStateFilter
+
+log = logging.getLogger(__name__)
+
+common_fsm_router = Router(name="codex_bot:common_fsm_router")
+
+
+@common_fsm_router.message(F.text, IsGarbageStateFilter())
+async def delete_garbage_text(message: Message, state: FSMContext) -> None:
+    """
+    Deletes unwanted text messages in "garbage" states.
+
+    Triggers only if the user's current FSM state is registered
+    in GarbageStateRegistry. States are added dynamically as features load.
+
+    Args:
+        message: Incoming text message.
+        state: User's FSM context.
+    """
+    user_id = message.from_user.id if message.from_user else "N/A"
+    current_state = await state.get_state()
+    log.info(f"GarbageCollector | user={user_id} state={current_state}")
+
+    try:
+        await message.delete()
+        text_preview = (message.text or "")[:20]
+        log.debug(f"GarbageCollector | status=deleted user={user_id} text='{text_preview}'")
+    except TelegramAPIError as e:
+        log.warning(f"GarbageCollector | status=delete_failed user={user_id} error='{e}'")

codex_bot/fsm/garbage_collector.py

@@ -0,0 +1,141 @@
+"""
+GarbageStateRegistry and IsGarbageStateFilter — Automatic deletion
+of text messages in states where only button clicks are expected.
+
+The registry is filled dynamically when features are loaded via
+FeatureDiscoveryService or directly via GarbageStateRegistry.register().
+This allows any feature to declare its states as "garbage" without
+touching the global configuration.
+
+Example:
+    ```python
+    # In feature_setting.py of a feature:
+    from aiogram.fsm.state import State, StatesGroup
+
+    class BookingStates(StatesGroup):
+        select_date = State()
+        select_time = State()
+
+    # Register the entire group as garbage:
+    GarbageStateRegistry.register(BookingStates)
+
+    # Or a single state:
+    GarbageStateRegistry.register(BookingStates.select_date)
+    ```
+"""
+
+from typing import Any
+
+from aiogram.filters import Filter
+from aiogram.fsm.context import FSMContext
+from aiogram.fsm.state import State, StatesGroup
+from aiogram.types import Message
+
+
+class GarbageStateRegistry:
+    """
+    Registry of FSM states where text messages are considered garbage.
+
+    Global registry: states are registered once at startup,
+    the filter checks the user's current state with each message.
+
+    Supports registration of:
+    - a single `State` object
+    - an entire `StatesGroup` (all states in the group)
+    - a string (state name)
+    - a list / tuple / set of the above types
+
+    Example:
+        ```python
+        GarbageStateRegistry.register(MyFeatureStates)          # entire group
+        GarbageStateRegistry.register(MyFeatureStates.waiting)  # single state
+        GarbageStateRegistry.register(["Feature1:main", "Feature2:step1"])
+        ```
+    """
+
+    _states: set[str] = set()
+
+    @classmethod
+    def register(
+        cls,
+        state: State | StatesGroup | type[StatesGroup] | str | list[Any] | tuple[Any, ...] | set[Any],
+    ) -> None:
+        """
+        Registers state(s) as garbage.
+
+        Args:
+            state: State, StatesGroup, string, or an iterable of them.
+        """
+        if isinstance(state, list | tuple | set):
+            for s in state:
+                cls.register(s)
+            return
+
+        # StatesGroup class (not instance) — take all its states
+        if isinstance(state, type) and issubclass(state, StatesGroup):
+            for s in state.__all_states__:
+                cls.register(s)
+            return
+
+        # StatesGroup instance — take __all_states__ (Aiogram 3)
+        if hasattr(state, "__all_states__"):
+            for s in state.__all_states__:
+                cls.register(s)
+            return
+
+        # State object or string
+        state_name = state.state if isinstance(state, State) else str(state)
+        if state_name:
+            cls._states.add(state_name)
+
+    @classmethod
+    def is_garbage(cls, state_name: str | None) -> bool:
+        """
+        Checks if a state is registered as garbage.
+
+        Args:
+            state_name: String name of the current FSM state.
+
+        Returns:
+            True if the state is registered as garbage.
+        """
+        if state_name is None:
+            return False
+        return state_name in cls._states
+
+    @classmethod
+    def registered_states(cls) -> frozenset[str]:
+        """
+        Returns all registered garbage states (read-only).
+
+        Returns:
+            Frozenset of string state names.
+        """
+        return frozenset(cls._states)
+
+
+class IsGarbageStateFilter(Filter):
+    """
+    Aiogram filter: True if the user's current FSM state is garbage.
+
+    Used in common_fsm_router for automatic deletion of unwanted text messages.
+
+    Example:
+        ```python
+        @router.message(F.text, IsGarbageStateFilter())
+        async def delete_garbage(message: Message, state: FSMContext):
+            await message.delete()
+        ```
+    """
+
+    async def __call__(self, message: Message, state: FSMContext) -> bool:
+        """
+        Args:
+            message: Incoming message.
+            state: User's FSM context.
+
+        Returns:
+            True if the current state is registered as garbage.
+        """
+        current_state = await state.get_state()
+        return GarbageStateRegistry.is_garbage(current_state)

codex_bot/fsm/state_helper.py

@@ -0,0 +1,72 @@
+"""
+StateHelper — Universal utilities for safe FSMContext data manipulation.
+
+Provides atomic-like operations for getting, updating, and removing keys
+from aiogram FSM storage, preventing "zombie dictionaries" in Redis.
+"""
+
+from typing import Any
+
+from aiogram.fsm.context import FSMContext
+
+
+class StateHelper:
+    """
+    Helper for safe operations with FSMContext data.
+
+    Encapsulates the logic of reading and writing to FSM storage
+    to ensure consistency across different modules (StateManager, I18n, etc.).
+    """
+
+    @staticmethod
+    async def get_value(state: FSMContext, key: str, default: Any = None) -> Any:
+        """
+        Safely retrieves a value from FSM storage.
+
+        Args:
+            state: FSM context.
+            key: Storage key.
+            default: Default value if key is missing.
+
+        Returns:
+            Stored value or default.
+        """
+        data = await state.get_data()
+        return data.get(key, default)
+
+    @staticmethod
+    async def update_value(state: FSMContext, key: str, value: Any) -> None:
+        """
+        Updates a value in FSM storage or removes the key if value is empty.
+
+        If the value is None, an empty dict, or an empty list, the key is
+        completely removed from the storage to avoid "zombie" entries in Redis.
+
+        Args:
+            state: FSM context.
+            key: Storage key.
+            value: Value to store.
+        """
+        data = await state.get_data()
+
+        # Check for "empty" values to trigger deletion
+        is_empty = value is None or (isinstance(value, dict | list) and not value)
+
+        if is_empty:
+            if key in data:
+                del data[key]
+                await state.set_data(data)
+        else:
+            data[key] = value
+            await state.set_data(data)
+
+    @staticmethod
+    async def clear_key(state: FSMContext, key: str) -> None:
+        """
+        Completely removes a key from FSM storage.
+
+        Args:
+            state: FSM context.
+            key: Key to remove.
+        """
+        await StateHelper.update_value(state, key, None)