codex-bot 0.1.0__py3-none-any.whl

codex_bot/fsm/state_manager.py

@@ -0,0 +1,104 @@
+"""
+BaseStateManager — Isolated feature data storage within FSM.
+
+Each feature works with its own namespaced key in the FSM storage,
+eliminating conflicts between features of the same bot.
+"""
+
+from typing import Any, TypeVar
+
+from aiogram.fsm.context import FSMContext
+
+from .state_helper import StateHelper
+
+T = TypeVar("T")
+
+
+class BaseStateManager:
+    """
+    Base FSM state manager for a feature (draft).
+
+    Isolates specific feature data under the `draft:<feature_key>` key
+    within the user's general FSM storage. This prevents collisions
+    between different features operating in the same FSM session.
+
+    Args:
+        state: FSM context of the current user.
+        feature_key: Unique feature key (e.g., `"booking"`, `"profile"`).
+
+    Example:
+        ```python
+        manager = BaseStateManager(state, feature_key="booking")
+        await manager.update(date="2024-01-15", time="14:00")
+        payload = await manager.get_payload()
+        # {"date": "2024-01-15", "time": "14:00"}
+        await manager.clear()
+        ```
+    """
+
+    def __init__(self, state: FSMContext, feature_key: str) -> None:
+        self.state = state
+        self.storage_key = f"draft:{feature_key}"
+
+    async def get_payload(self) -> dict[str, Any]:
+        """
+        Returns all data of the feature draft.
+
+        Returns:
+            Dictionary with current data. Empty dictionary if no data exists.
+        """
+        result = await StateHelper.get_value(self.state, self.storage_key, {})
+        return dict(result) if isinstance(result, dict) else {}
+
+    async def update(self, **kwargs: Any) -> dict[str, Any]:
+        """
+        Updates the draft with the passed fields (partial update).
+
+        Args:
+            **kwargs: Fields to update.
+
+        Returns:
+            Updated dictionary with draft data.
+
+        Example:
+            ```python
+            await manager.update(name="Alice", age=30)
+            ```
+        """
+        current = await self.get_payload()
+        current.update(kwargs)
+        await StateHelper.update_value(self.state, self.storage_key, current)
+        return current
+
+    async def clear(self) -> None:
+        """Completely removes the draft key from FSM storage.
+
+        Unlike resetting to ``{key: {}}``, it completely removes the key,
+        leaving no empty "zombie dictionaries" in Redis.
+        Does not affect data of other features in the same FSM storage.
+        """
+        await StateHelper.clear_key(self.state, self.storage_key)
+
+    async def set_value(self, key: str, value: Any) -> None:
+        """
+        Sets one specific value.
+
+        Args:
+            key: Field key.
+            value: Value to save.
+        """
+        await self.update(**{key: value})
+
+    async def get_value(self, key: str, default: Any = None) -> Any:
+        """
+        Returns a specific value from the draft.
+
+        Args:
+            key: Field key.
+            default: Default value if the key is not found.
+
+        Returns:
+            Field value or default.
+        """
+        payload = await self.get_payload()
+        return payload.get(key, default)

codex_bot/helper/__init__.py

@@ -0,0 +1,7 @@
+"""
+codex_bot.helper — Utilities for extracting context from Telegram events.
+"""
+
+from codex_bot.helper.context_helper import ContextHelper
+
+__all__ = ["ContextHelper"]

codex_bot/helper/context_helper.py

@@ -0,0 +1,61 @@
+"""
+ContextHelper — Extraction of BaseBotContext from Telegram events.
+"""
+
+from aiogram.types import CallbackQuery, Message
+
+from codex_bot.base.context_dto import BaseBotContext
+
+
+class ContextHelper:
+    """
+    Helper for extracting BaseBotContext from Message or CallbackQuery.
+
+    Normalizes user_id: if from_user is missing (e.g., a post in a channel),
+    it uses chat_id as a fallback for session uniqueness.
+
+    Example:
+        ```python
+        ctx = ContextHelper.extract_base_context(callback)
+        director = Director(container=container, state=state,
+                            user_id=ctx.user_id, chat_id=ctx.chat_id)
+        ```
+    """
+
+    @staticmethod
+    def extract_base_context(event: Message | CallbackQuery) -> BaseBotContext:
+        """
+        Extracts base IDs from an event.
+
+        Args:
+            event: Message or CallbackQuery from the user.
+
+        Returns:
+            Immutable BaseBotContext with user_id, chat_id, message_id, thread_id.
+        """
+        user_id = event.from_user.id if event.from_user else 0
+        chat_id = user_id
+        message_id: int | None = None
+        thread_id: int | None = None
+
+        if isinstance(event, CallbackQuery):
+            if isinstance(event.message, Message):
+                chat_id = event.message.chat.id
+                message_id = event.message.message_id
+                thread_id = event.message.message_thread_id
+            if user_id == 0:
+                user_id = chat_id
+
+        elif isinstance(event, Message):
+            chat_id = event.chat.id
+            message_id = event.message_id
+            thread_id = event.message_thread_id
+            if user_id == 0:
+                user_id = chat_id
+
+        return BaseBotContext(
+            user_id=user_id,
+            chat_id=chat_id,
+            message_id=message_id,
+            message_thread_id=thread_id,
+        )

codex_bot/redis/__init__.py

@@ -0,0 +1,15 @@
+"""
+codex_bot.redis — Redis Stream router, dispatcher, and processor.
+"""
+
+from codex_bot.redis.dispatcher import BotRedisDispatcher, RetrySchedulerProtocol
+from codex_bot.redis.router import RedisRouter
+from codex_bot.redis.stream_processor import RedisStreamProcessor, StreamStorageProtocol
+
+__all__ = [
+    "RedisRouter",
+    "BotRedisDispatcher",
+    "RetrySchedulerProtocol",
+    "RedisStreamProcessor",
+    "StreamStorageProtocol",
+]

codex_bot/redis/dispatcher.py

@@ -0,0 +1,169 @@
+"""
+BotRedisDispatcher — Dispatcher for messages from Redis Stream.
+
+Works on the principle of aiogram.Dispatcher, but for Redis Stream:
+registers handlers via decorators or include_router(),
+dispatches incoming messages by type.
+"""
+
+import logging
+from collections.abc import Callable
+from typing import Any
+
+from .router import FilterFunc, HandlerFunc, RedisRouter
+
+log = logging.getLogger(__name__)
+
+
+class RetrySchedulerProtocol:
+    """
+    Protocol for a retry scheduler (ARQ or similar).
+
+    Implement and pass to BotRedisDispatcher for automatic
+    rescheduling of failed messages to a retry queue.
+    """
+
+    async def schedule_retry(self, stream_name: str, payload: dict[str, Any], delay: int = 60) -> None:
+        """
+        Schedules message reprocessing.
+
+        Args:
+            stream_name: Redis Stream name.
+            payload: Message data for reprocessing.
+            delay: Delay in seconds before retry.
+        """
+        ...
+
+
+class BotRedisDispatcher:
+    """
+    Redis Stream message dispatcher for a Telegram bot.
+
+    Allows registering handlers via decorators (@dispatcher.on_message)
+    or via routers (include_router). When processing a message:
+
+    1. Determines the type by the ``"type"`` field in the payload.
+    2. Finds suitable handlers (considering filters).
+    3. On handler error — if a ``retry_scheduler`` exists, passes the
+       task to it and returns control (Stream ACK will occur in the processor).
+       If there is no scheduler or it fails — re-raises the exception (no ACK).
+
+    Args:
+        retry_scheduler: Optional retry scheduler (ARQ, etc.).
+
+    Example:
+        ```python
+        dispatcher = BotRedisDispatcher()
+
+        @dispatcher.on_message("booking.confirmed")
+        async def on_booking(payload: dict, container) -> None:
+            await container.notification_service.send(payload["user_id"])
+
+        # Connecting a router from a feature:
+        dispatcher.include_router(notifications_redis_router)
+
+        # Setting dependencies before start:
+        dispatcher.setup(container=container)
+        await dispatcher.process_message({"type": "booking.confirmed", ...})
+        ```
+    """
+
+    def __init__(self, retry_scheduler: RetrySchedulerProtocol | None = None) -> None:
+        self._container: Any = None
+        self._retry_scheduler = retry_scheduler
+        self._handlers: dict[str, list[tuple[HandlerFunc, FilterFunc | None]]] = {}
+        log.info("BotRedisDispatcher | initialized")
+
+    def setup(self, container: Any) -> None:
+        """
+        Sets the DI container before processing begins.
+
+        If a handler needs a Bot to send messages — it retrieves it
+        directly from ``container.bot``.
+
+        Args:
+            container: Project's DI container.
+        """
+        self._container = container
+
+    def include_router(self, router: RedisRouter) -> None:
+        """
+        Connects a RedisRouter with its handlers.
+
+        Args:
+            router: Router from a feature.
+        """
+        for message_type, handlers in router.handlers.items():
+            if message_type not in self._handlers:
+                self._handlers[message_type] = []
+            self._handlers[message_type].extend(handlers)
+        log.info(f"BotRedisDispatcher | included router types={list(router.handlers.keys())}")
+
+    def on_message(
+        self,
+        message_type: str,
+        filter_func: "FilterFunc | None" = None,
+    ) -> Callable[[HandlerFunc], HandlerFunc]:
+        """
+        Decorator for registering a handler directly in the dispatcher.
+
+        Args:
+            message_type: Redis Stream message type.
+            filter_func: Optional payload -> bool filter.
+
+        Returns:
+            Decorator.
+        """
+
+        def decorator(handler: HandlerFunc) -> HandlerFunc:
+            if message_type not in self._handlers:
+                self._handlers[message_type] = []
+            self._handlers[message_type].append((handler, filter_func))
+            return handler
+
+        return decorator
+
+    async def process_message(self, message_data: dict[str, Any]) -> None:
+        """
+        Dispatches an incoming Redis Stream message.
+
+        Args:
+            message_data: Message payload. Required field: ``"type"``.
+        """
+        if not self._container:
+            log.error("BotRedisDispatcher | container not set — call setup() first")
+            return
+
+        msg_type = message_data.get("type")
+        if not msg_type:
+            log.warning(f"BotRedisDispatcher | message without 'type' field: {message_data}")
+            return
+
+        handlers = self._handlers.get(msg_type, [])
+        if not handlers:
+            log.debug(f"BotRedisDispatcher | no handlers for type='{msg_type}'")
+            return
+
+        for handler, filter_func in handlers:
+            try:
+                if filter_func is None or filter_func(message_data):
+                    log.debug(f"BotRedisDispatcher | calling {handler.__name__} for type='{msg_type}'")
+                    await handler(message_data, self._container)
+            except Exception as e:
+                log.error(f"BotRedisDispatcher | handler {handler.__name__} failed: {e}")
+
+                if self._retry_scheduler:
+                    try:
+                        await self._retry_scheduler.schedule_retry(
+                            stream_name="bot_events",
+                            payload=message_data,
+                            delay=60,
+                        )
+                        log.info(f"BotRedisDispatcher | retry scheduled for type='{msg_type}'")
+                        # Responsibility passed to scheduler — ACK will occur in processor
+                        return
+                    except Exception as retry_err:
+                        log.error(f"BotRedisDispatcher | retry scheduling failed: {retry_err}")
+
+                # No scheduler or it failed — re-raise, no ACK (PEL)
+                raise

codex_bot/redis/router.py

@@ -0,0 +1,71 @@
+"""
+RedisRouter — Router for grouping Redis Stream handlers.
+
+Analogous to aiogram.Router, but for messages from Redis Stream.
+Allows organizing handlers modularly by feature.
+"""
+
+from collections.abc import Callable
+from typing import Any
+
+# Types for readability
+HandlerFunc = Callable[[dict[str, Any], Any], Any]
+FilterFunc = Callable[[dict[str, Any]], bool]
+
+
+class RedisRouter:
+    """
+    Router for grouping Redis Stream handlers by message type.
+
+    Used in feature_setting.py of Redis features. After creation,
+    it is connected to BotRedisDispatcher via include_router().
+
+    Example:
+        ```python
+        redis_router = RedisRouter()
+
+        @redis_router.message("notification.created")
+        async def handle_notification(payload: dict, container) -> None:
+            user_id = payload["user_id"]
+            ...
+
+        # With a filter:
+        @redis_router.message("notification.created", filter_func=lambda p: p.get("urgent"))
+        async def handle_urgent(payload: dict, container) -> None:
+            ...
+        ```
+    """
+
+    def __init__(self) -> None:
+        # {message_type: [(handler, filter_func), ...]}
+        self._handlers: dict[str, list[tuple[HandlerFunc, FilterFunc | None]]] = {}
+
+    def message(
+        self,
+        message_type: str,
+        filter_func: FilterFunc | None = None,
+    ) -> Callable[[HandlerFunc], HandlerFunc]:
+        """
+        Decorator for registering a handler for a Redis Stream message type.
+
+        Args:
+            message_type: String message type (e.g., "booking.confirmed").
+            filter_func: Optional filter — callable(payload) -> bool.
+                         The handler is called only if the filter returns True.
+
+        Returns:
+            Decorator returning the original handler unchanged.
+        """
+
+        def decorator(handler: HandlerFunc) -> HandlerFunc:
+            if message_type not in self._handlers:
+                self._handlers[message_type] = []
+            self._handlers[message_type].append((handler, filter_func))
+            return handler
+
+        return decorator
+
+    @property
+    def handlers(self) -> dict[str, list[tuple[HandlerFunc, FilterFunc | None]]]:
+        """Registered handlers (read-only view)."""
+        return self._handlers

codex_bot/redis/stream_processor.py

@@ -0,0 +1,210 @@
+"""
+RedisStreamProcessor — Redis Stream polling loop (Consumer Group).
+
+Reads messages from Redis Stream via a Consumer Group, passes them
+to a callback function (usually BotRedisDispatcher.process_message),
+and acknowledges successful processing via ACK.
+"""
+
+import asyncio
+import contextlib
+import logging
+from collections.abc import Awaitable, Callable
+from typing import Any, Protocol, runtime_checkable
+
+log = logging.getLogger(__name__)
+
+
+@runtime_checkable
+class StreamStorageProtocol(Protocol):
+    """
+    Redis Stream adapter protocol for RedisStreamProcessor.
+
+    Implement in the project on top of redis-py or any other client.
+
+    Example:
+        ```python
+        class RedisStreamAdapter:
+            def __init__(self, redis: Redis): self.redis = redis
+
+            async def create_group(self, stream: str, group: str) -> None:
+                with contextlib.suppress(ResponseError):
+                    await self.redis.xgroup_create(stream, group, id="0", mkstream=True)
+
+            async def read_events(self, stream_name, group_name, consumer_name, count):
+                result = await self.redis.xreadgroup(
+                    group_name, consumer_name, {stream_name: ">"}, count=count, block=0
+                )
+                if not result:
+                    return []
+                return [(msg_id, data) for _, messages in result for msg_id, data in messages]
+
+            async def ack_event(self, stream_name, group_name, message_id) -> None:
+                await self.redis.xack(stream_name, group_name, message_id)
+        ```
+    """
+
+    async def create_group(self, stream_name: str, group_name: str) -> None:
+        """Creates a Consumer Group (idempotently)."""
+        ...
+
+    async def read_events(
+        self,
+        stream_name: str,
+        group_name: str,
+        consumer_name: str,
+        count: int,
+    ) -> list[tuple[str, dict[str, Any]]]:
+        """
+        Reads a batch of unread messages from the group.
+
+        Returns:
+            List of pairs (message_id, data_dict).
+        """
+        ...
+
+    async def ack_event(self, stream_name: str, group_name: str, message_id: str) -> None:
+        """Acknowledges message processing (XACK)."""
+        ...
+
+
+MessageCallback = Callable[[dict[str, Any]], Awaitable[None]]
+
+
+class RedisStreamProcessor:
+    """
+    Redis Stream processor: reads messages and passes them to a callback.
+
+    Starts a background asyncio task (_consume_loop) that continuously
+    reads messages from Redis Stream via a Consumer Group.
+    On errors — recreates the group (e.g., after a Redis restart).
+
+    Args:
+        storage: Stream adapter (StreamStorageProtocol).
+        stream_name: Redis Stream name (e.g., "bot_events").
+        consumer_group_name: Consumer Group name.
+        consumer_name: Unique consumer name (e.g., "bot-worker-1").
+        batch_count: Number of messages per reading cycle.
+        poll_interval: Wait interval (sec) if there are no messages.
+
+    Example:
+        ```python
+        processor = RedisStreamProcessor(
+            storage=redis_stream_adapter,
+            stream_name="bot_events",
+            consumer_group_name="bot_group",
+            consumer_name="bot-1",
+        )
+        processor.set_message_callback(dispatcher.process_message)
+        await processor.start_listening()
+        ```
+    """
+
+    def __init__(
+        self,
+        storage: StreamStorageProtocol,
+        stream_name: str,
+        consumer_group_name: str,
+        consumer_name: str,
+        batch_count: int = 10,
+        poll_interval: float = 1.0,
+    ) -> None:
+        self.storage = storage
+        self.stream_name = stream_name
+        self.group_name = consumer_group_name
+        self.consumer_name = consumer_name
+        self.batch_count = batch_count
+        self.poll_interval = poll_interval
+
+        self.is_running = False
+        self._callback: MessageCallback | None = None
+        self._task: asyncio.Task[None] | None = None
+
+    def set_message_callback(self, callback: MessageCallback) -> None:
+        """
+        Sets the callback for processing each message.
+
+        Args:
+            callback: Async callable(payload: dict) -> None.
+        """
+        self._callback = callback
+
+    async def start_listening(self) -> None:
+        """
+        Starts the background Stream reading loop.
+
+        Creates a Consumer Group (up to 5 attempts), then starts _consume_loop
+        as an asyncio Task.
+        """
+        if self.is_running:
+            log.warning("RedisStreamProcessor | already running")
+            return
+
+        for attempt in range(1, 6):
+            try:
+                await self.storage.create_group(self.stream_name, self.group_name)
+                break
+            except Exception as e:
+                log.warning(f"RedisStreamProcessor | create_group attempt {attempt}/5: {e}")
+                if attempt < 5:
+                    await asyncio.sleep(3)
+                else:
+                    log.error("RedisStreamProcessor | failed to create group, giving up")
+                    return
+
+        self.is_running = True
+        self._task = asyncio.create_task(self._consume_loop())
+        log.info(
+            f"RedisStreamProcessor | listening stream='{self.stream_name}' "
+            f"group='{self.group_name}' consumer='{self.consumer_name}'"
+        )
+
+    async def stop_listening(self) -> None:
+        """Stops the reading loop and correctly cancels the asyncio Task."""
+        self.is_running = False
+        if self._task and not self._task.done():
+            self._task.cancel()
+            with contextlib.suppress(asyncio.CancelledError):
+                await self._task
+        log.info("RedisStreamProcessor | stopped")
+
+    async def _consume_loop(self) -> None:
+        try:
+            while self.is_running:
+                try:
+                    messages = await self.storage.read_events(
+                        stream_name=self.stream_name,
+                        group_name=self.group_name,
+                        consumer_name=self.consumer_name,
+                        count=self.batch_count,
+                    )
+
+                    if not messages:
+                        await asyncio.sleep(self.poll_interval)
+                        continue
+
+                    for message_id, data in messages:
+                        await self._process_single(message_id, data)
+
+                except asyncio.CancelledError:
+                    raise  # propagate immediately, do not catch in general except
+                except Exception as e:
+                    log.error(f"RedisStreamProcessor | consume loop error: {e}")
+                    if "NOGROUP" in str(e):
+                        log.warning("RedisStreamProcessor | consumer group missing, recreating...")
+                        try:
+                            await self.storage.create_group(self.stream_name, self.group_name)
+                        except Exception as create_err:
+                            log.error(f"RedisStreamProcessor | recreate failed: {create_err}")
+                    await asyncio.sleep(5)
+        except asyncio.CancelledError:
+            log.info("RedisStreamProcessor | consume loop cancelled")
+            raise  # asyncio requires propagating CancelledError
+
+    async def _process_single(self, message_id: str, data: dict[str, Any]) -> None:
+        try:
+            if self._callback:
+                await self._callback(data)
+            await self.storage.ack_event(self.stream_name, self.group_name, message_id)
+        except Exception as e:
+            log.error(f"RedisStreamProcessor | failed to process message {message_id}: {e}")

codex_bot/sender/__init__.py

@@ -0,0 +1,15 @@
+"""
+codex_bot.sender — ViewSender, SenderManager, and UI coordinate storage protocols.
+"""
+
+from codex_bot.sender.protocols import SenderStateStorageProtocol
+from codex_bot.sender.sender_keys import SenderKeys
+from codex_bot.sender.sender_manager import SenderManager
+from codex_bot.sender.view_sender import ViewSender
+
+__all__ = [
+    "SenderStateStorageProtocol",
+    "SenderKeys",
+    "SenderManager",
+    "ViewSender",
+]