codex-bot 0.1.0__py3-none-any.whl

codex_bot/engine/discovery/service.py

@@ -0,0 +1,258 @@
+"""
+FeatureDiscoveryService — Auto-discovery and registration of features.
+
+Supports two modes of operation:
+1. **Auto-discovery** — scans modules from a list of feature_paths via importlib.
+2. **Explicit registration** — the developer passes objects directly (fallback for
+   environments without dynamic imports: PyInstaller, strict mypy, etc.).
+
+Both modes can be combined in a single application.
+"""
+
+import importlib
+import logging
+from types import ModuleType
+from typing import Any, cast
+
+from aiogram import Router
+
+from ...fsm.garbage_collector import GarbageStateRegistry
+from ...redis.dispatcher import BotRedisDispatcher
+from ...redis.router import RedisRouter
+
+log = logging.getLogger(__name__)
+
+
+class FeatureDiscoveryService:
+    """
+    Service for discovering and registering feature configurations.
+
+    Two modes:
+
+    **Mode 1: Auto-discovery** (similar to Django's INSTALLED_APPS):
+    ```python
+    discovery = FeatureDiscoveryService(
+        module_prefix="src.telegram_bot",
+        installed_features=["features.telegram.commands", "features.telegram.booking"],
+        installed_redis_features=["features.redis.notifications"],
+        redis_dispatcher=bot_redis_dispatcher,
+    )
+    discovery.discover_all()
+    orchestrators = discovery.create_feature_orchestrators(container)
+    ```
+
+    **Mode 2: Explicit registration** (fallback):
+    ```python
+    discovery = FeatureDiscoveryService()
+    discovery.register_router(commands_router)
+    discovery.register_orchestrator("booking", BookingOrchestrator(container))
+    discovery.register_garbage_states(BookingStates)
+    ```
+
+    Args:
+        module_prefix: Module path prefix for auto-discovery.
+                       Example: "src.telegram_bot".
+        installed_features: List of Telegram feature paths (with Aiogram routers).
+        installed_redis_features: List of Redis feature paths (with RedisRouter).
+        redis_dispatcher: Dispatcher for registering Redis handlers.
+    """
+
+    def __init__(
+        self,
+        module_prefix: str = "",
+        installed_features: list[str] | None = None,
+        installed_redis_features: list[str] | None = None,
+        redis_dispatcher: BotRedisDispatcher | None = None,
+    ) -> None:
+        self._prefix = module_prefix
+        self._features = installed_features or []
+        self._redis_features = installed_redis_features or []
+        self._redis_dispatcher = redis_dispatcher
+
+        # Explicitly registered objects (Mode 2)
+        self._explicit_routers: list[Router] = []
+        self._explicit_orchestrators: dict[str, Any] = {}
+
+    # =========================================================================
+    # Mode 1: Auto-discovery
+    # =========================================================================
+
+    def discover_all(self) -> None:
+        """
+        Starts auto-discovery of all registered features.
+
+        For Telegram features: loads menu config, garbage states, Aiogram routers.
+        For Redis features: loads RedisRouter and connects it to the dispatcher.
+        """
+        for feature_path in self._features:
+            self._discover_menu(feature_path)
+            self._discover_garbage_states(feature_path)
+
+        for feature_path in self._redis_features:
+            self._discover_redis_handlers(feature_path)
+            self._discover_garbage_states(feature_path)
+
+    def create_feature_orchestrators(self, container: Any) -> dict[str, Any]:
+        """
+        Creates orchestrators for all features via their factory functions.
+
+        Looks for the `create_orchestrator(container)` function in the `feature_setting.py`
+        of each feature. The key prefix for Redis features is "redis_".
+
+        Args:
+            container: Project's DI container.
+
+        Returns:
+            Dictionary {feature_key: orchestrator_instance}.
+        """
+        orchestrators = dict(self._explicit_orchestrators)
+        configs = [(self._features, ""), (self._redis_features, "redis_")]
+
+        for feature_list, prefix in configs:
+            for feature_path in feature_list:
+                module = self._load_feature_module(feature_path)
+                if not module:
+                    continue
+                factory = getattr(module, "create_orchestrator", None)
+                if not factory:
+                    continue
+                base_name = feature_path.split(".")[-1]
+                key = f"{prefix}{base_name}"
+                orchestrators[key] = factory(container)
+                log.info(f"FeatureDiscovery | orchestrator loaded key='{key}'")
+
+        return orchestrators
+
+    def collect_aiogram_routers(self) -> list[Router]:
+        """
+        Collects Aiogram Routers from all Telegram features.
+
+        Returns:
+            List of Routers to be included in the main router.
+        """
+        routers = list(self._explicit_routers)
+
+        for feature_path in self._features:
+            module_path = f"{self._prefix}.{feature_path}.handlers" if self._prefix else f"{feature_path}.handlers"
+            try:
+                module = importlib.import_module(module_path)
+                router = getattr(module, "router", None)
+                if router and isinstance(router, Router):
+                    routers.append(router)
+                    log.info(f"FeatureDiscovery | router loaded feature='{feature_path}'")
+            except ImportError as e:
+                if getattr(e, "name", None) == module_path:
+                    log.debug(f"FeatureDiscovery | no handlers file feature='{feature_path}'")
+                else:
+                    log.critical(f"FeatureDiscovery | Broken import inside '{feature_path}': {e}")
+                    raise
+
+        return routers
+
+    def get_menu_buttons(self, is_admin: bool | None = None) -> dict[str, dict[str, Any]]:
+        """
+        Returns menu button configurations for all Telegram features.
+
+        Args:
+            is_admin: None — all buttons, True — only admin, False — only user.
+
+        Returns:
+            Dictionary {feature_key: menu_config_dict}.
+        """
+        buttons: dict[str, dict[str, Any]] = {}
+        for feature_path in self._features:
+            btn = self._discover_menu(feature_path)
+            if btn:
+                if is_admin is not None and btn.get("is_admin", False) != is_admin:
+                    continue
+                key = btn.get("key", feature_path)
+                buttons[key] = btn
+        return buttons
+
+    # =========================================================================
+    # Mode 2: Explicit registration (fallback)
+    # =========================================================================
+
+    def register_router(self, router: Router) -> None:
+        """
+        Explicitly registers an Aiogram Router (without auto-discovery).
+
+        Args:
+            router: Instance of aiogram.Router.
+        """
+        self._explicit_routers.append(router)
+
+    def register_orchestrator(self, key: str, orchestrator: Any) -> None:
+        """
+        Explicitly registers a feature orchestrator.
+
+        Args:
+            key: Feature key (e.g., "booking", "redis_notifications").
+            orchestrator: Orchestrator instance.
+        """
+        self._explicit_orchestrators[key] = orchestrator
+
+    def register_garbage_states(self, states: Any) -> None:
+        """
+        Explicitly registers states as garbage (Garbage Collector).
+
+        Args:
+            states: State, StatesGroup, string, or a list of them.
+        """
+        GarbageStateRegistry.register(states)
+
+    # =========================================================================
+    # Private auto-discovery methods
+    # =========================================================================
+
+    def _load_feature_module(self, feature_path: str) -> ModuleType | None:
+        candidates = []
+        if self._prefix:
+            candidates.append(f"{self._prefix}.{feature_path}.feature_setting")
+            candidates.append(f"{self._prefix}.{feature_path}")
+        candidates.append(f"{feature_path}.feature_setting")
+        candidates.append(feature_path)
+
+        for path in candidates:
+            try:
+                return importlib.import_module(path)
+            except ImportError:
+                continue
+        return None
+
+    def _discover_menu(self, feature_path: str) -> dict[str, Any] | None:
+        module = self._load_feature_module(feature_path)
+        if module:
+            config = getattr(module, "MENU_CONFIG", None)
+            if config and isinstance(config, dict):
+                return cast(dict[str, Any] | None, config)
+        return None
+
+    def _discover_garbage_states(self, feature_path: str) -> None:
+        module = self._load_feature_module(feature_path)
+        if not module:
+            return
+        garbage = getattr(module, "GARBAGE_STATES", None)
+        if garbage:
+            GarbageStateRegistry.register(garbage)
+            return
+        if getattr(module, "GARBAGE_COLLECT", False):
+            states = getattr(module, "STATES", None)
+            if states:
+                GarbageStateRegistry.register(states)
+
+    def _discover_redis_handlers(self, feature_path: str) -> None:
+        if not self._redis_dispatcher:
+            return
+        module_path = f"{self._prefix}.{feature_path}.handlers" if self._prefix else f"{feature_path}.handlers"
+        try:
+            module = importlib.import_module(module_path)
+            redis_router = getattr(module, "redis_router", None)
+            if redis_router and isinstance(redis_router, RedisRouter):
+                self._redis_dispatcher.include_router(redis_router)
+        except ImportError as e:
+            if getattr(e, "name", None) == module_path:
+                log.debug(f"FeatureDiscovery | no redis handlers file feature='{module_path}'")
+            else:
+                log.critical(f"FeatureDiscovery | Broken import inside '{module_path}': {e}")
+                raise

codex_bot/engine/factory/__init__.py

@@ -0,0 +1,7 @@
+"""
+codex_bot.engine.factory — BotBuilder for creating Bot + Dispatcher.
+"""
+
+from codex_bot.engine.factory.bot_builder import BotBuilder
+
+__all__ = ["BotBuilder"]

codex_bot/engine/factory/bot_builder.py

@@ -0,0 +1,111 @@
+"""
+BotBuilder — Builder pattern for creating Bot + Dispatcher.
+
+Allows explicit control over the order of middleware connection.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from aiogram import Bot, Dispatcher
+from aiogram.client.default import DefaultBotProperties
+from aiogram.fsm.storage.base import BaseStorage
+from aiogram.fsm.storage.memory import MemoryStorage
+
+log = logging.getLogger(__name__)
+
+
+class BotBuilder:
+    """Builder for Bot + Dispatcher with explicit middleware management.
+
+    Allows injecting custom middleware at arbitrary points,
+    unlike the functional approach with a fixed order.
+
+    Args:
+        bot_token: Telegram bot token.
+        parse_mode: Message parsing mode (default is ``"HTML"``).
+        fsm_storage: FSM storage. ``None`` → ``MemoryStorage``.
+        dispatcher_kwargs: Additional kwargs for ``Dispatcher``.
+
+    Raises:
+        ValueError: If ``bot_token`` is empty.
+
+    Example:
+        ```python
+        from codex_bot.engine.factory import BotBuilder
+        from codex_bot.engine.middlewares import UserValidationMiddleware, ThrottlingMiddleware
+
+        builder = BotBuilder(bot_token=settings.bot_token, fsm_storage=RedisStorage(redis))
+        builder.add_middleware(UserValidationMiddleware())
+        builder.add_middleware(ThrottlingMiddleware(redis=redis_client))
+        builder.add_middleware(MyAnalyticsMiddleware())
+        bot, dp = builder.build()
+        ```
+    """
+
+    def __init__(
+        self,
+        bot_token: str,
+        parse_mode: str = "HTML",
+        fsm_storage: BaseStorage | None = None,
+        dispatcher_kwargs: dict[str, Any] | None = None,
+    ) -> None:
+        if not bot_token:
+            raise ValueError("bot_token must not be empty")
+
+        self._bot_token = bot_token
+        self._parse_mode = parse_mode
+        self._fsm_storage: BaseStorage = fsm_storage or MemoryStorage()
+        self._dispatcher_kwargs: dict[str, Any] = dispatcher_kwargs or {}
+        self._middlewares: list[Any] = []
+
+    def add_middleware(self, middleware: Any) -> BotBuilder:
+        """Adds middleware to the connection queue.
+
+        Middleware are connected in the order they are added.
+
+        Args:
+            middleware: Middleware instance to connect to ``dp.update``.
+
+        Returns:
+            ``self`` for chaining.
+
+        Example:
+            ```python
+            builder.add_middleware(UserValidationMiddleware())
+                   .add_middleware(ThrottlingMiddleware(redis))
+            ```
+        """
+        self._middlewares.append(middleware)
+        return self
+
+    def build(self) -> tuple[Bot, Dispatcher]:
+        """Assembles Bot and Dispatcher.
+
+        Creates a ``Bot`` with the specified parameters and a ``Dispatcher`` with FSM storage.
+        Connects all middleware via ``dp.update.middleware``.
+
+        Returns:
+            Tuple ``(bot, dispatcher)``.
+
+        Example:
+            ```python
+            bot, dp = builder.build()
+            await dp.start_polling(bot)
+            ```
+        """
+        bot = Bot(
+            token=self._bot_token,
+            default=DefaultBotProperties(parse_mode=self._parse_mode),
+        )
+
+        dp = Dispatcher(storage=self._fsm_storage, **self._dispatcher_kwargs)
+
+        for middleware in self._middlewares:
+            dp.update.middleware(middleware)
+            log.debug(f"BotBuilder | Middleware registered: {middleware.__class__.__name__}")
+
+        log.info(f"BotBuilder | Built bot with {len(self._middlewares)} middleware(s)")
+        return bot, dp

codex_bot/engine/http/__init__.py

@@ -0,0 +1,10 @@
+"""
+codex_bot.engine.http — Base async HTTP client.
+"""
+
+from codex_bot.engine.http.api_client import ApiClientError, BaseApiClient
+
+__all__ = [
+    "BaseApiClient",
+    "ApiClientError",
+]

codex_bot/engine/http/api_client.py

@@ -0,0 +1,123 @@
+"""
+BaseApiClient — Long-lived async HTTP client on top of httpx.
+
+The client is created ONCE (in the DI container at startup) and reuses
+ the TCP connection pool throughout the application's lifetime. This eliminates
+ the overhead of TLS handshakes for each request.
+
+Inherit to create clients for specific backend APIs.
+"""
+
+import logging
+from typing import Any
+
+log = logging.getLogger(__name__)
+
+try:
+    import httpx
+except ImportError as e:
+    raise ImportError("BaseApiClient requires 'httpx'. Install it: pip install codex-bot[http]") from e
+
+
+class ApiClientError(Exception):
+    """Base HTTP client error."""
+
+
+class BaseApiClient:
+    """
+    Base async HTTP client with a long-lived connection pool.
+
+    Created once in the DI container, not per-request.
+    Reuses TCP connections via httpx connection pooling.
+    Call ``close()`` when stopping the bot for proper termination.
+
+    Args:
+        base_url: Base API URL (e.g., ``"https://api.example.com"``).
+        api_key: API key for the ``X-API-Key`` header. ``None`` — no authentication.
+        timeout: Total request timeout in seconds (``connect`` is always 5 sec).
+
+    Example:
+        ```python
+        class BookingApiClient(BaseApiClient):
+            async def get_slots(self, date: str) -> list[dict]:
+                return await self._request("GET", "/slots", params={"date": date})
+
+        # In the DI container — once:
+        client = BookingApiClient(base_url="https://api.example.com", api_key="secret")
+
+        # When stopping the bot:
+        await client.close()
+        ```
+    """
+
+    def __init__(
+        self,
+        base_url: str,
+        api_key: str | None = None,
+        timeout: float = 10.0,
+    ) -> None:
+        headers: dict[str, str] = {
+            "Content-Type": "application/json",
+            "Accept": "application/json",
+        }
+        if api_key:
+            headers["X-API-Key"] = api_key
+
+        # Long-lived client — created once, lives for the entire bot duration
+        self.client = httpx.AsyncClient(
+            base_url=base_url.rstrip("/"),
+            headers=headers,
+            timeout=httpx.Timeout(timeout, connect=5.0),
+        )
+
+    async def close(self) -> None:
+        """Closes the connection pool. Call when stopping the bot.
+
+        Example:
+            ```python
+            # In on_shutdown hook:
+            await api_client.close()
+            ```
+        """
+        await self.client.aclose()
+
+    async def _request(
+        self,
+        method: str,
+        endpoint: str,
+        json: dict[str, Any] | None = None,
+        params: dict[str, Any] | None = None,
+    ) -> Any:
+        """Performs an HTTP request via the long-lived client.
+
+        Args:
+            method: HTTP method (``"GET"``, ``"POST"``, ``"PUT"``, ``"DELETE"``).
+            endpoint: Endpoint path (e.g., ``"/api/v1/slots"``).
+            json: Request body in JSON format.
+            params: Query parameters.
+
+        Returns:
+            Parsed JSON response or ``None`` for 204 No Content.
+
+        Raises:
+            ApiClientError: For HTTP errors or connection issues.
+        """
+        url = endpoint.lstrip("/")
+
+        try:
+            log.debug(f"API {method} /{url} | params={params}")
+            response = await self.client.request(method=method, url=url, json=json, params=params)
+            response.raise_for_status()
+
+            # 204 No Content and empty responses (DELETE, some POST)
+            if response.status_code == 204 or not response.content:
+                return None
+
+            return response.json()
+
+        except httpx.HTTPStatusError as e:
+            log.error(f"API HTTP error {e.response.status_code}: {e.response.text}")
+            raise ApiClientError(f"HTTP {e.response.status_code}") from e
+        except httpx.RequestError as e:
+            log.error(f"API connection error: {e}")
+            raise ApiClientError(f"Connection error: {e}") from e

codex_bot/engine/i18n/__init__.py

@@ -0,0 +1,7 @@
+"""
+codex_bot.engine.i18n — Compilation of Fluent (.ftl) locales.
+"""
+
+from codex_bot.engine.i18n.locales_compiler import compile_locales
+
+__all__ = ["compile_locales"]

codex_bot/engine/i18n/locales_compiler.py

@@ -0,0 +1,83 @@
+"""
+LocalesCompiler — Compilation of Fluent (.ftl) locales into a single tmp directory.
+
+Collects all .ftl files from language subfolders and merges them
+into one messages.ftl per language for passing to FluentRuntimeCore.
+
+Each project gets an isolated tmp folder based on the hash of the
+absolute path to the locales — multiple bots on one server
+do not overwrite each other's files.
+"""
+
+import hashlib
+import logging
+import pathlib
+import shutil
+import tempfile
+
+log = logging.getLogger(__name__)
+
+
+def compile_locales(base_path: pathlib.Path) -> str:
+    """Compiles .ftl files from language subfolders into an isolated tmp directory.
+
+    Collects all ``*.ftl`` files from ``{base_path}/{lang}/*.ftl``
+    into ``/tmp/bot_locales_{hash}/{lang}/messages.ftl``.
+    The resulting path is passed to ``FluentRuntimeCore``.
+
+    The folder is isolated by the hash of the absolute path: multiple bots or
+    parallel tests on the same server do not interfere with each other.
+
+    Args:
+        base_path: Path to the directory with language subfolders.
+
+    Returns:
+        Path template ``"/tmp/bot_locales_{hash}/{locale}"`` for ``FluentRuntimeCore``.
+
+    Raises:
+        OSError: If the tmp directory cannot be created or files cannot be written.
+
+    Example:
+        ```python
+        from codex_bot.engine.i18n import compile_locales
+
+        locales_path = compile_locales(Path("resources/locales"))
+        core = FluentRuntimeCore(path=locales_path)
+        ```
+    """
+    # Short hash of the absolute path — unique per project, stable between restarts
+    # usedforsecurity=False tells Bandit/linters that this is not a cryptographic hash.
+    path_hash = hashlib.md5(str(base_path.absolute()).encode(), usedforsecurity=False).hexdigest()[:8]
+    tmp_dir = pathlib.Path(tempfile.gettempdir()) / f"bot_locales_{path_hash}"
+
+    if tmp_dir.exists():
+        try:
+            shutil.rmtree(tmp_dir)
+        except OSError as e:
+            log.warning(f"LocalesCompiler | Failed to clean tmp_dir (maybe in use): {e}")
+
+    tmp_dir.mkdir(parents=True, exist_ok=True)
+
+    if not base_path.exists():
+        log.warning(f"LocalesCompiler | Source path not found: {base_path}")
+        return str(tmp_dir / "{locale}")
+
+    for lang_dir in base_path.iterdir():
+        if not lang_dir.is_dir():
+            continue
+
+        lang = lang_dir.name
+        compiled_content: list[str] = []
+
+        for ftl_file in sorted(lang_dir.glob("*.ftl")):
+            content = ftl_file.read_text(encoding="utf-8")
+            compiled_content.append(f"### Source: {ftl_file.name} ###\n{content}\n")
+
+        if compiled_content:
+            lang_tmp_dir = tmp_dir / lang
+            lang_tmp_dir.mkdir(exist_ok=True)
+            output_file = lang_tmp_dir / "messages.ftl"
+            output_file.write_text("\n".join(compiled_content), encoding="utf-8")
+            log.debug(f"LocalesCompiler | Compiled {lang} ({len(compiled_content)} files) → {output_file}")
+
+    return str(tmp_dir / "{locale}")

codex_bot/engine/middlewares/__init__.py

@@ -0,0 +1,24 @@
+"""
+codex_bot.engine.middlewares — Ready-to-use middleware for Aiogram.
+
+All middleware are "dumb" bridges between aiogram and the DI container.
+No business logic — only infrastructure.
+
+Connection (recommended order):
+    1. UserValidationMiddleware  — checks for user presence
+    2. ThrottlingMiddleware      — rate limiting (atomic SET NX)
+    3. ContainerMiddleware       — DI container injection
+"""
+
+from codex_bot.engine.middlewares.container import ContainerMiddleware
+from codex_bot.engine.middlewares.throttling import ThrottlingMiddleware
+from codex_bot.engine.middlewares.user_validation import UserValidationMiddleware
+
+__all__ = [
+    "UserValidationMiddleware",
+    "ThrottlingMiddleware",
+    "ContainerMiddleware",
+]
+
+# FSMContextI18nManager is exported separately — requires aiogram-i18n[optional]
+# from codex_bot.engine.middlewares.i18n import FSMContextI18nManager

codex_bot/engine/middlewares/container.py

@@ -0,0 +1,46 @@
+"""
+ContainerMiddleware — DI container injection into handlers.
+
+Adds `data["container"]` so that handlers don't import the container
+directly — they receive it from the event context.
+"""
+
+from collections.abc import Awaitable, Callable
+from typing import Any
+
+from aiogram import BaseMiddleware
+from aiogram.types import TelegramObject
+
+
+class ContainerMiddleware(BaseMiddleware):
+    """
+    Middleware for injecting a DI container into handlers.
+
+    Passes any container object via `data["container"]`.
+    Does not know about the specific container type — works with any object.
+
+    Args:
+        container: Project's DI container (any object).
+
+    Example:
+        ```python
+        container = BotContainer(settings=settings, redis=redis)
+        dp.update.middleware(ContainerMiddleware(container=container))
+
+        # In a handler:
+        async def my_handler(callback: CallbackQuery, container: BotContainer):
+            result = await container.booking_service.get_slots()
+        ```
+    """
+
+    def __init__(self, container: Any) -> None:
+        self.container = container
+
+    async def __call__(
+        self,
+        handler: Callable[[TelegramObject, dict[str, Any]], Awaitable[Any]],
+        event: TelegramObject,
+        data: dict[str, Any],
+    ) -> Any:
+        data["container"] = self.container
+        return await handler(event, data)