python-trueconf-bot 1.3.0__py3-none-any.whl → 1.4.0__py3-none-any.whl

{python_trueconf_bot-1.3.0.dist-info → python_trueconf_bot-1.4.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-trueconf-bot
-Version: 1.3.0
+Version: 1.4.0
 Summary: Lightweight and powerful framework for the TrueConf Server Chatbot API
 Author-email: TrueConf LLC <info@trueconf.com>, Anton Baadzhi <baadzhianton@gmail.com>
 License-Expression: BSD-3-Clause-Clear

{python_trueconf_bot-1.3.0.dist-info → python_trueconf_bot-1.4.0.dist-info}/RECORD

@@ -1,16 +1,17 @@
-python_trueconf_bot-1.3.0.dist-info/licenses/LICENSE,sha256=ftDuEzhr-yY_dsfpEQ2SKAP_dEAO-iPt96MBZq_K48o,1684
-trueconf/__init__.py,sha256=JRFC0ca_JhwlDuzcnZ1r9bflnAmQyMYhJr_hBRYcdpw,394
-trueconf/_version.py,sha256=kjMXs_RelAfH3nsfXcggy4eqwR8yDdd160wJ9EHB63g,520
+python_trueconf_bot-1.4.0.dist-info/licenses/LICENSE,sha256=ftDuEzhr-yY_dsfpEQ2SKAP_dEAO-iPt96MBZq_K48o,1684
+trueconf/__init__.py,sha256=Ka9VLhsdu-jZPndOQI1QpUXWldpu8xTC2BfgW51Px5U,481
+trueconf/_version.py,sha256=u2oUj6dCZIqQ271Pm6INHvXKeiux4BSapl6g0c_tllg,520
 trueconf/exceptions.py,sha256=JlnOybf6XBVKGYPPN3STlruupdfQXrLdeZ_FbtUuMIs,7653
 trueconf/loggers.py,sha256=4dnq14qFo6fJ8SKZJCRZd0iJDYRqmcuX-ccv5FezxlQ,594
+trueconf/middleware.py,sha256=7yaS4UjZSrPb-lv5STmX8qGg1OamYbO5Nd5-IjPtbU4,2281
 trueconf/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 trueconf/client/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-trueconf/client/bot.py,sha256=CCtWyKrmxQxETBSD31sd4r6I5_L4eWHgh4sNXfNYBUI,78540
+trueconf/client/bot.py,sha256=vfIPb5ok5RUuVqvhoQzf5v0P_9Zz72sF_DiqJcl20wI,78735
 trueconf/client/context_controller.py,sha256=_aItNHblyFbEqRsnbOM3ESgPqg2Pkji7xidTx0gb6zk,660
 trueconf/client/session.py,sha256=CvHjxQXbkUyyS1r7YCFVL8al37zOYtnhw5ACNLJJDOc,1751
 trueconf/dispatcher/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-trueconf/dispatcher/dispatcher.py,sha256=3l0CVXWj5pPIzN2jd4O6aClZ4LS0Gm0E55sM8P_WMOs,2114
-trueconf/dispatcher/router.py,sha256=Oqwfq854565a0kVSsa_0QkdTIR3g0T8YzSkqnAae-oQ,15843
+trueconf/dispatcher/dispatcher.py,sha256=v2TRq90NZ5j85gJAANfVp1HPFB6Pt_AueFQCbmRCCt4,5802
+trueconf/dispatcher/router.py,sha256=WFduzQCUVuCDtGA-4RxNcEipZt73y7_4n9iy11YO8KE,20642
 trueconf/enums/__init__.py,sha256=YxjyW5UbyBAB8NWYqpxeSpuC6b_D7tghq0S4XWCySms,645
 trueconf/enums/aouth_error.py,sha256=Ru5oZxam-2SnhSPZyapH79IlNrU_3t1l6RxsUJ4f5b8,462
 trueconf/enums/chat_participant_role.py,sha256=2W-1nQdpvOWd8hDDgksPtykKdzewj6nwXWrvvHrQxGU,434
@@ -28,6 +29,17 @@ trueconf/filters/command.py,sha256=UWGn0yyFA5we2pRnL0BeUiJBjvN5slu_5GderrmQl8I,3
 trueconf/filters/instance_of.py,sha256=O5s2AfoGvsXdsZLdk0OnAqUss-PeUQG7-giDpiJle6s,287
 trueconf/filters/message.py,sha256=-4mSEokWo_Bqnk2K7ci3dI1niJw3X9CVFHo5xo1Qtis,480
 trueconf/filters/method.py,sha256=v2cB3N8fzKWqz1AGJaUjsswen8d58pafOt4eB0qJtgM,367
+trueconf/fsm/__init__.py,sha256=ewkpwMGTf0tFRXOFGrSCEZpyh5j0EXMNfbGZ5yHEK-w,554
+trueconf/fsm/context.py,sha256=Eo__H5RJi7S3l1KQBggc1evg8dPFqkTZ0LSWfmy91x8,1726
+trueconf/fsm/filters.py,sha256=v8RC_uSHL9N_xyu5_qSLbMN_aGIlk8W9dh_oYVk0Lps,939
+trueconf/fsm/key_builder.py,sha256=7LVrpgWxS8_5uuCW_XSep72aZJ4cB-wsZCOSBe9bcTs,1228
+trueconf/fsm/manager.py,sha256=ybcdv3id4lz4cCj85ZokpLmuZIJwJ70oRpntO0-6P20,1199
+trueconf/fsm/middleware.py,sha256=F5MMVg5CbsFqpegr6_hpgvZ0xU8oxLQ0QM1FdPiAHkc,663
+trueconf/fsm/state.py,sha256=MmF6QMekC-3alOBU0pByA7wZ_h3_SOuut_-X74-8pyc,4538
+trueconf/fsm/strategy.py,sha256=m5--QhJf_NSq8rTN4xkxp2Zx76w5D8Jb8PIkGXvVjac,951
+trueconf/fsm/storage/__init__.py,sha256=cDVH7QNbdIvUFDsEg0RIyxfvmYo_haALvqsBY8apFoM,148
+trueconf/fsm/storage/base.py,sha256=f5vhdNt7mSXrXkqOTKCtj3CpJ24VqryWVKzLoOKuz5c,984
+trueconf/fsm/storage/memory.py,sha256=Etib3uqMXfuD6hrsYZCxSp0awsM61c2NqjzWl5sFpmg,1781
 trueconf/methods/__init__.py,sha256=fapNvuoZ16q6YUaJJjRWljoSXAOmyqq3PyUK8yyCh9Q,1911
 trueconf/methods/add_participant_to_chat.py,sha256=uT-NBkHXFDfmHbi3f_hc3HJtS_jRS69yBuIQ87HczVQ,677
 trueconf/methods/auth.py,sha256=ZEYoJpEKqUybDyqW8YJMPxA8QK2cAYXhipYr8V3nbj0,783
@@ -143,7 +155,7 @@ trueconf/utils/split_text.py,sha256=0HTVv63kLo2gx1r-ImM47ejTR4X_uDkNr5QMxvWdTBo,
 trueconf/utils/formatting/__init__.py,sha256=Ii9rEamQdy8R0pVbmDf3xbdB4TtmgYyu2-RWRTCXukw,261
 trueconf/utils/formatting/decorations.py,sha256=iQzCdFBELn16llCgTTPk43K5-BzY6BGPc1M3V2Q0tPQ,2175
 trueconf/utils/formatting/text.py,sha256=pOW07TIV5vfvtWmGa2i2l_Q0UjFM6QMuowmsAjE9nyo,6867
-python_trueconf_bot-1.3.0.dist-info/METADATA,sha256=N8b9bbvbyice_Egb7QWBYOmi_e_fgrkJGdCQli0A8rY,5700
-python_trueconf_bot-1.3.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
-python_trueconf_bot-1.3.0.dist-info/top_level.txt,sha256=GjgYdn_osTUuU-H8f59VhIS7MY44xLV7-D7veywJaeY,9
-python_trueconf_bot-1.3.0.dist-info/RECORD,,
+python_trueconf_bot-1.4.0.dist-info/METADATA,sha256=Zp74Ghw3JmfBFYW7OPok0WFUAOi5GFLt64RmNDk76js,5700
+python_trueconf_bot-1.4.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+python_trueconf_bot-1.4.0.dist-info/top_level.txt,sha256=GjgYdn_osTUuU-H8f59VhIS7MY44xLV7-D7veywJaeY,9
+python_trueconf_bot-1.4.0.dist-info/RECORD,,

trueconf/__init__.py

@@ -1,6 +1,7 @@
 from trueconf.client.bot import Bot
 from trueconf.dispatcher.dispatcher import Dispatcher
 from trueconf.dispatcher.router import Router
+from trueconf.middleware import BaseMiddleware, SkipSelfMessages
 from magic_filter import F
 from trueconf.types.message import Message
 from trueconf.types import requests
@@ -11,6 +12,7 @@ __all__ = (
     "Bot",
     "Dispatcher",
     "Router",
+    "BaseMiddleware",
     "F",
     "Message",
     "requests",

trueconf/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '1.3.0'
-__version_tuple__ = version_tuple = (1, 3, 0)
+__version__ = version = '1.4.0'
+__version_tuple__ = version_tuple = (1, 4, 0)
 
 __commit_id__ = commit_id = None

trueconf/client/bot.py

@@ -125,6 +125,7 @@ class Bot:
             dispatcher: Dispatcher | None = None,
             receive_unread_messages: bool = False,
             receive_system_messages: bool = False,
+            skip_self_messages: bool = True,
             verify_ssl: SSLVerify = True,
             web_port: int | None = None,
             https: bool = True,
@@ -147,6 +148,8 @@ class Bot:
             receive_unread_messages (bool, optional): Whether to receive unread messages on connection. Defaults to False.
             receive_system_messages (bool, optional): Whether to receive system messages, such as user additions
                 to the chat or chat title changes. Defaults to False.
+            skip_self_messages (bool, optional): If True, the bot will ignore messages sent by itself.
+                This prevents echo loops when multiple bot sessions are running. Defaults to True.
             verify_ssl (bool | str | ssl.SSLContext, optional): SSL verification mode. If True, verifies
                 the server certificate using the system trust store when available. If False, disables
                 certificate verification. If a string is provided, it must be a path to a CA bundle file.
@@ -200,10 +203,14 @@ class Bot:
         self._me_id: str
         self._on_health_check = on_health_check
 
+        if skip_self_messages:
+            from trueconf.middleware import SkipSelfMessages
+            self.dp.outer_middleware(SkipSelfMessages())
+
         loggers.chatbot.info(
             f"Bot initialized: server={server}:{self.port}, protocol={self._protocol}, "
             f"verify_ssl={_describe_ssl_context(self.ssl_context)}, ws_max_retries={ws_max_retries}, ws_max_delay={ws_max_delay}, "
-            f"receive_unread={receive_unread_messages}"
+            f"receive_unread={receive_unread_messages}, skip_self={skip_self_messages}"
         )
 
     async def __call__(self, method: TrueConfMethod[T]) -> T:
@@ -322,6 +329,7 @@ class Bot:
             dispatcher: Dispatcher | None = None,
             receive_unread_messages: bool = False,
             receive_system_messages: bool = False,
+            skip_self_messages: bool = True,
             verify_ssl: SSLVerify = True,
             web_port: int | None = None,
             https: bool = True,
@@ -345,19 +353,16 @@ class Bot:
             receive_unread_messages (bool, optional): Whether to receive unread messages on connection. Defaults to False.
             receive_system_messages (bool, optional): Whether to receive system messages, such as user additions
                 to the chat or chat title changes. Defaults to False.
-            verify_ssl (bool | str | ssl.SSLContext, optional): SSL verification mode. If True, verifies
-                the server certificate using the system trust store when available. If False, disables
-                certificate verification. If a string is provided, it must be a path to a CA bundle file.
-                A custom ssl.SSLContext can also be passed. Defaults to True.
+            skip_self_messages (bool, optional): If True, the bot will ignore messages sent by itself.
+                Defaults to True.
+            verify_ssl (bool | str | ssl.SSLContext, optional): SSL verification mode. Defaults to True.
             web_port (int, optional): WebSocket connection port. Defaults to 443.
             https (bool, optional): Whether to use HTTPS protocol. Defaults to True.
             ws_max_retries (int, optional): Max connection attempts on network/IP errors before giving up. Defaults to 5.
             ws_max_delay (int, optional): Maximum delay between reconnection attempts (in seconds). Defaults to 60.
             debug (bool, optional): Enables debug mode. Defaults to False.
             on_health_check (HealthCheckCallback | None, optional): Async callback called when the bot
-                connection health changes. The callback receives a dictionary with the current status,
-                WebSocket state, authorization state, server, port, protocol, timestamp, and optional
-                error details. Defaults to None.
+                connection health changes. Defaults to None.
 
         Returns:
             Bot: An authorized bot instance.
@@ -379,7 +384,8 @@ class Bot:
             https=https,
             dispatcher=dispatcher,
             receive_unread_messages=receive_unread_messages,
-            receive_system_messages = receive_system_messages,
+            receive_system_messages=receive_system_messages,
+            skip_self_messages=skip_self_messages,
             verify_ssl=ssl_context,
             ws_max_delay=ws_max_delay,
             ws_max_retries=ws_max_retries,
@@ -758,7 +764,7 @@ class Bot:
         if hasattr(payload, "bind"):
             payload.bind(self)
 
-        await self.dp._feed_update(data)
+        await self.dp._feed_update(data, {"bot": self})
 
     async def __on_raw_message(self, raw: str):
         try:

trueconf/dispatcher/dispatcher.py

@@ -1,63 +1,149 @@
 from __future__ import annotations
-from typing import List
+from typing import TYPE_CHECKING, Any, Awaitable, Callable, Dict, List
 from trueconf.filters.base import Event
 from trueconf.dispatcher.router import Router
 
+MiddlewareHandler = Callable[[Event, Dict[str, Any]], Awaitable[None]]
 
-class Dispatcher:
-    """
-        Central event dispatcher for processing and routing incoming events.
+if TYPE_CHECKING:
+    from trueconf.fsm.key_builder import KeyBuilder
+    from trueconf.fsm.manager import FSMManager
+    from trueconf.fsm.storage.base import BaseStorage
+    from trueconf.fsm.strategy import FSMStrategy
 
-        The `Dispatcher` aggregates one or more `Router` instances and feeds each
-        incoming event through them. The routers are traversed recursively via their
-        `subrouters` (using `_iter_all()`), and each event is passed to `_feed()` of
-        each router in order until it is handled.
 
-        Typical usage includes registering routers with handlers and then calling
-        `feed_update()` with incoming events.
+class Dispatcher(Router):
+    """Central dispatcher for routing incoming events.
 
-        Examples:
-            >>> dispatcher = Dispatcher()
-            >>> dispatcher.include_router(my_router)
+    The dispatcher is the root router of an application. It receives incoming
+    events, applies its own outer middleware chain, and then passes each event
+    to the included root routers in order. Processing stops when a router handles
+    the event, unless that router allows propagation to its child routers.
 
-        Attributes:
-            routers (List[Router]): List of root routers included in the dispatcher.
+    `Dispatcher` inherits from `Router`, so it supports the same handler,
+    middleware, and subrouter registration APIs.
 
-        """
+    Example:
+        ```python
+        dispatcher = Dispatcher()
+        dispatcher.include_router(router)
+        ```
+
+    FSM example:
+        ```python
+        from trueconf.fsm.storage.memory import MemoryStorage
+
+        storage = MemoryStorage()
+        dp = Dispatcher(storage=storage)
+        ```
+
+    Args:
+        storage: Storage backend used to create an FSM manager. Cannot be used
+            together with `fsm_manager`.
+        fsm_manager: Existing FSM manager instance. Cannot be used together
+            with `storage`.
+        key_builder: Key builder used when creating an FSM manager from
+            `storage`. Ignored when `fsm_manager` is passed.
+        strategy: FSM strategy used when creating an FSM manager from `storage`.
+            Ignored when `fsm_manager` is passed.
 
-    def __init__(self):
-        """Initializes an empty dispatcher with no routers."""
+    Attributes:
+        routers: Root routers included in the dispatcher.
+        fsm: FSM manager configured for the dispatcher, or `None` if FSM support
+            has not been enabled.
+    """
+
+    def __init__(
+        self,
+        *,
+        storage: BaseStorage | None = None,
+        fsm_manager: FSMManager | None = None,
+        key_builder: KeyBuilder | None = None,
+        strategy: FSMStrategy | None = None,
+    ):
+        super().__init__(name="dispatcher")
         self.routers: List[Router] = []
+        self.fsm: FSMManager | None = None
 
-    def include_router(self, router: Router):
-        """
-            Includes a router to be used by the dispatcher.
+        if fsm_manager is not None and storage is not None:
+            raise ValueError("Pass either fsm_manager or storage, not both")
+
+        if fsm_manager is not None:
+            self.setup_fsm(fsm_manager=fsm_manager)
+        elif storage is not None:
+            self.setup_fsm(storage=storage, key_builder=key_builder, strategy=strategy)
 
-            Args:
-                router (Router): A `Router` instance to include.
+    def setup_fsm(
+        self,
+        *,
+        fsm_manager: FSMManager | None = None,
+        storage: BaseStorage | None = None,
+        key_builder: KeyBuilder | None = None,
+        strategy: FSMStrategy | None = None,
+    ) -> FSMManager:
+        from trueconf.fsm.key_builder import DefaultKeyBuilder
+        from trueconf.fsm.manager import FSMManager
+        from trueconf.fsm.middleware import FSMMiddleware
+        from trueconf.fsm.storage.memory import MemoryStorage
+        from trueconf.fsm.strategy import FSMStrategy
+
+        if self.fsm is not None:
+            raise RuntimeError(
+                "FSM is already configured for this Dispatcher. "
+                "Call setup_fsm() only once, or create a new Dispatcher."
+            )
+
+        if fsm_manager is None:
+            fsm_manager = FSMManager(
+                storage=storage or MemoryStorage(),
+                key_builder=key_builder or DefaultKeyBuilder(),
+                strategy=strategy or FSMStrategy.USER_IN_CHAT,
+            )
+
+        self.fsm = fsm_manager
+        self._outer_middlewares.insert(0, FSMMiddleware(fsm_manager))
+        return fsm_manager
+
+    def include_router(self, router: "Router") -> None:
+        """Include a root router in the dispatcher.
+
+        The dispatcher's own middleware is applied in ``_feed_update`` before
+        the event reaches child routers. Therefore we do NOT set ``_parent`` —
+        child routers should not inherit the dispatcher's middleware through
+        the ancestor chain.
         """
         self.routers.append(router)
 
-    async def _feed_update(self, event: Event):
+    async def _feed_update(self, event: Event, data: Dict[str, Any]) -> None:
         """
-            Feeds an event to all routers and subrouters in order,
+            Feeds an event to all child routers in order,
             stopping at the first one that handles it.
 
-            Args:
-                event (Event): The event to be processed.
+            The event first passes through the dispatcher's own middleware chain
+            (outer middlewares from dispatcher ancestors → dispatcher), then is
+            fed to each child router.
 
-            Returns:
-                None
+        Args:
+            event (Event): The event to be processed.
+            data (Dict[str, Any]): Context data passed through the middleware pipeline.
         """
 
-        async def progress_router(router, count = 0):
-            handled = await router._feed(event)
-            if count < 0 or count >= len(router._subrouters):
-                return
-            if (not handled) or (handled and router.allow_child_on_event):
-                subrouter = router._subrouters[count]
-                return await progress_router(subrouter, count=len(router._subrouters) - 1)
-            return
-
-        for router in self.routers:
-            await progress_router(router)
+        async def _feed_children(evt: Event, ctx: Dict[str, Any]) -> None:
+            async def progress_router(router: Router, count: int = 0) -> None:
+                handled = await router._feed(evt, ctx)
+                if count < 0 or count >= len(router._subrouters):
+                    return
+                if (not handled) or (handled and router.allow_child_on_event):
+                    subrouter = router._subrouters[count]
+                    await progress_router(subrouter, count=len(router._subrouters) - 1)
+
+            for router in self.routers:
+                await progress_router(router)
+
+        # Build outer middleware chain: dispatcher outer_mw → feed_children
+        chain: MiddlewareHandler = _feed_children
+        for mw in reversed(self._collect_middlewares("_outer_middlewares")):
+            nxt = chain
+            chain = Router._wrap_middleware(mw, nxt)
+
+        await chain(event, data)

trueconf/dispatcher/router.py

@@ -2,7 +2,7 @@ from __future__ import annotations
 import asyncio
 import logging
 import inspect
-from typing import Callable, Awaitable, List, Tuple, Any, Union
+from typing import TYPE_CHECKING, Callable, Awaitable, Dict, List, Tuple, Any, Union
 from magic_filter import MagicFilter
 from trueconf.filters.base import Event
 from trueconf.filters.base import Filter
@@ -25,6 +25,9 @@ from trueconf.types.requests.removed_chat_participant import RemovedChatParticip
 from trueconf.types.requests.removed_message import RemovedMessage
 from trueconf.types.requests.uploading_progress import UploadingProgress
 
+if TYPE_CHECKING:
+    from trueconf.middleware import BaseMiddleware
+
 logger = logging.getLogger("chat_bot")
 
 Handler = Callable[..., Awaitable[None]]
@@ -62,12 +65,19 @@ class Router:
         If you have multiple routers, use `.include_router()` to add them to a parent router.
         """
 
-    def __init__(self, name: str | None = None, allow_child_on_event: bool = False):
-
+    def __init__(
+        self,
+        name: str | None = None,
+        allow_child_on_event: bool = False,
+        _parent: "Router | None" = None,
+    ):
         self.name = name or hex(id(self))
         self.allow_child_on_event = allow_child_on_event
+        self._parent: Router | None = _parent
         self._handlers: List[Tuple[Tuple[FilterLike, ...], Handler]] = []
         self._subrouters: List["Router"] = []
+        self._outer_middlewares: List["BaseMiddleware"] = []
+        self._inner_middlewares: List["BaseMiddleware"] = []
 
     def _iter_all(self) -> List["Router"]:
         """Return a list of this router and all nested subrouters recursively."""
@@ -76,8 +86,42 @@ class Router:
             out.extend(child._iter_all())
         return out
 
+    def _ancestors_with_self(self) -> List["Router"]:
+        """Return routers from root ancestor down to self."""
+        chain: list[Router] = []
+        current: Router | None = self
+        while current is not None:
+            chain.append(current)
+            current = current._parent
+        chain.reverse()
+        return chain
+
+    def _collect_middlewares(
+        self, attr: str
+    ) -> List["BaseMiddleware"]:
+        """Collect middlewares from ancestors → self."""
+        result: list[BaseMiddleware] = []
+        for router in self._ancestors_with_self():
+            result.extend(getattr(router, attr, []))
+        return result
+
+    def outer_middleware(self, middleware: "BaseMiddleware") -> None:
+        """Register outer middleware (runs before filter/handler matching)."""
+        self._outer_middlewares.append(middleware)
+
+    def inner_middleware(self, middleware: "BaseMiddleware") -> None:
+        """Register inner middleware (runs after filter match, before handler)."""
+        self._inner_middlewares.append(middleware)
+
     def _register(self, filters: Tuple[FilterLike, ...]):
         """Internal decorator for registering handlers with filters."""
+        # Sugar: State instances are auto-wrapped with StateFilter
+        from trueconf.fsm.filters import StateFilter
+        from trueconf.fsm.state import State
+        filters = tuple(
+            StateFilter(f) if isinstance(f, State) else f
+            for f in filters
+        )
 
         def decorator(func: Handler):
             async def async_wrapper(evt: Event, **kwargs: Any):
@@ -91,41 +135,96 @@ class Router:
 
         return decorator
 
-    async def _feed(self, event: Event) -> bool:
-        """Feed an incoming event to the router and invoke the first matching handler."""
-        logger.info(f"📥 Incoming event: {event}")
-        for flts, handler in self._handlers:
+    async def _feed(self, event: Event, data: Dict[str, Any]) -> bool:
+        """Feed an incoming event to the router and invoke the first matching handler.
 
-            if not flts:
-                self._spawn(handler, event, "<none>")
-                return True
+        Pipeline:
+            outer_middleware → filter match → inner_middleware → handler
 
-            matched = True
-            for f in flts:
-                try:
-                    if not await self._apply_filter(f, event):
-                        matched = False
-                        break
-                except Exception as e:
-                    logger.exception(f"Filter {type(f).__name__} error: {e}")
-                    matched = False
-                    break
+        Returns:
+            True  — event was handled or blocked by outer middleware.
+            False — no handler matched and outer middleware did not block;
+                    the dispatcher may try the next router.
+        """
+        logger.info("📥 Incoming event: %s", event)
 
-            if matched:
-                filters_str = ", ".join(
-                    getattr(f, "__name__", type(f).__name__) if callable(f) else type(f).__name__
-                    for f in flts
-                )
+        outer_passed = False
+        handler_found = False
 
+        async def _core(evt: Event, ctx: Dict[str, Any]) -> None:
+            nonlocal outer_passed, handler_found
+            outer_passed = True
+
+            # --- filter search ---
+            for flts, handler in self._handlers:
+                if not flts:
+                    handler_found = True
+                    self._spawn(handler, evt, "<none>")
+                    return
+
+                matched = True
                 kwargs: dict[str, Any] = {}
                 for f in flts:
-                    result = await self._apply_filter(f, event)
+                    try:
+                        result = await self._apply_filter(f, evt, ctx)
+                    except Exception as e:
+                        logger.exception("Filter %s error: %s", type(f).__name__, e)
+                        matched = False
+                        break
+
+                    if not result:
+                        matched = False
+                        break
+
                     if isinstance(result, dict):
                         kwargs.update(result)
 
-                self._spawn(handler, event, filters_str, **kwargs)
-                return True
-        return False
+                if matched:
+                    handler_found = True
+                    filters_str = ", ".join(
+                        getattr(f, "__name__", type(f).__name__) if callable(f) else type(f).__name__
+                        for f in flts
+                    )
+
+                    # Merge data dict (bot, state, etc.) with filter-returned kwargs
+                    all_kwargs: dict[str, Any] = {**ctx, **kwargs}
+
+                    # --- build inner chain: inner_mw → handler ---
+                    async def _inner_base(ievt: Event, ictx: Dict[str, Any]) -> None:
+                        self._spawn(handler, ievt, filters_str, **all_kwargs)
+
+                    inner_chain: Callable[[Event, Dict[str, Any]], Awaitable[None]] = _inner_base
+                    for mw in reversed(self._collect_middlewares("_inner_middlewares")):
+                        nxt = inner_chain
+                        inner_chain = self._wrap_middleware(mw, nxt)
+
+                    await inner_chain(evt, ctx)
+                    return
+
+        # --- wrap with outer middlewares ---
+        chain: Callable[[Event, Dict[str, Any]], Awaitable[None]] = _core
+        for mw in reversed(self._collect_middlewares("_outer_middlewares")):
+            nxt = chain
+            chain = self._wrap_middleware(mw, nxt)
+
+        await chain(event, data)
+
+        if not outer_passed:
+            # Outer middleware blocked — event consumed
+            return True
+        if not handler_found:
+            # No handler matched — try next router
+            return False
+        return True
+
+    @staticmethod
+    def _wrap_middleware(
+        mw: "BaseMiddleware",
+        nxt: Callable[[Event, Dict[str, Any]], Awaitable[None]],
+    ) -> Callable[[Event, Dict[str, Any]], Awaitable[None]]:
+        async def wrapped(evt: Event, ctx: Dict[str, Any]) -> None:
+            await mw(nxt, evt, ctx)
+        return wrapped
 
     def _spawn(self, handler: Handler, event: Event, filters_str: str, **kwargs: dict[str, Any]):
         """Internal method to spawn a task for executing the matched handler."""
@@ -140,24 +239,42 @@ class Router:
 
         asyncio.create_task(_run())
 
-    async def _apply_filter(self, f: Filter | Any, event: Event) -> bool:
-        """Evaluate a filter (sync or async) against the event."""
+    async def _apply_filter(self, f: Filter | Any, event: Event, data: dict[str, Any] | None = None) -> bool:
+        """Evaluate a filter against the event, passing matching kwargs from data."""
+        data = data or {}
+
         if isinstance(f, MagicFilter):
             try:
                 return bool(f.resolve(event))
             except Exception:
                 return False
 
+        # Resolve which kwargs from data the filter accepts
+        kwargs: dict[str, Any] = {}
+        has_var_kwargs = False
         try:
-            res = f(event)
-        except Exception:
-            return False
+            sig = inspect.signature(f)
+            for name, param in sig.parameters.items():
+                if param.kind == inspect.Parameter.VAR_KEYWORD:
+                    has_var_kwargs = True
+                    continue
+                if name in data and param.kind in (
+                    inspect.Parameter.POSITIONAL_OR_KEYWORD,
+                    inspect.Parameter.KEYWORD_ONLY,
+                ):
+                    kwargs[name] = data[name]
+        except (ValueError, TypeError):
+            pass
+
+        # If filter accepts **kwargs, pass all remaining data
+        if has_var_kwargs:
+            kwargs.update({k: v for k, v in data.items() if k not in kwargs})
+
+        # Regular filters: let exceptions propagate (config errors must be explicit)
+        res = f(event, **kwargs) if kwargs else f(event)
 
         if inspect.isawaitable(res):
-            try:
-                res = await res
-            except Exception:
-                return False
+            res = await res
 
         if isinstance(res, (bool, dict)):
             return res
@@ -165,6 +282,7 @@ class Router:
 
     def include_router(self, router: "Router") -> None:
         """Include a child router for hierarchical event routing."""
+        router._parent = self
         self._subrouters.append(router)
 
     def event(self, method: str, *filters: FilterLike):

trueconf/fsm/__init__.py

@@ -0,0 +1,20 @@
+from trueconf.fsm.context import FSMContext
+from trueconf.fsm.filters import StateFilter
+from trueconf.fsm.key_builder import DefaultKeyBuilder, KeyBuilder, StorageKey
+from trueconf.fsm.manager import FSMManager
+from trueconf.fsm.state import State, StatesGroup, any_state, default_state
+from trueconf.fsm.strategy import FSMStrategy
+
+__all__ = (
+    "FSMContext",
+    "FSMManager",
+    "FSMStrategy",
+    "State",
+    "StateFilter",
+    "StatesGroup",
+    "StorageKey",
+    "KeyBuilder",
+    "DefaultKeyBuilder",
+    "any_state",
+    "default_state",
+)

trueconf/fsm/context.py

@@ -0,0 +1,57 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any, overload
+
+from trueconf.fsm.key_builder import StorageKey
+from trueconf.fsm.state import State
+from trueconf.fsm.storage.base import BaseStorage
+
+
+class FSMContext:
+    def __init__(self, storage: BaseStorage, key: StorageKey) -> None:
+        self._storage = storage
+        self._key = key
+
+    @property
+    def key(self) -> StorageKey:
+        return self._key
+
+    @property
+    def storage(self) -> BaseStorage:
+        return self._storage
+
+    async def get_state(self) -> str | None:
+        return await self._storage.get_state(self._key)
+
+    async def set_state(self, state: State | str | None) -> None:
+        value = str(state) if isinstance(state, State) else state
+        await self._storage.set_state(self._key, value)
+
+    async def get_data(self) -> dict[str, Any]:
+        return await self._storage.get_data(self._key)
+
+    async def set_data(self, data: Mapping[str, Any]) -> None:
+        await self._storage.set_data(self._key, dict(data))
+
+    @overload
+    async def get_value(self, key: str) -> Any | None: ...
+
+    @overload
+    async def get_value(self, key: str, default: Any) -> Any: ...
+
+    async def get_value(self, key: str, default: Any | None = None) -> Any | None:
+        return await self._storage.get_value(self._key, key, default)
+
+    async def update_data(
+        self,
+        data: Mapping[str, Any] | None = None,
+        **kwargs: Any,
+    ) -> dict[str, Any]:
+        if data:
+            kwargs.update(data)
+        return await self._storage.update_data(self._key, kwargs)
+
+    async def clear(self) -> None:
+        await self.set_state(None)
+        await self.set_data({})

trueconf/fsm/filters.py

@@ -0,0 +1,31 @@
+from __future__ import annotations
+
+from typing import Any
+
+from trueconf.fsm.context import FSMContext
+from trueconf.fsm.state import State
+
+
+class StateFilter:
+    def __init__(self, *states: State | str | None) -> None:
+        self._states: set[str | None] = {
+            str(s) if isinstance(s, State) else s for s in states
+        }
+        self._wildcard = "*" in self._states
+
+    async def __call__(
+        self,
+        event: Any,
+        *,
+        state: FSMContext | None = None,
+    ) -> bool:
+        if state is None:
+            raise RuntimeError(
+                "StateFilter requires FSMContext in data['state'], but it was not found. "
+                "Make sure FSMMiddleware is registered as outer middleware "
+                "before any StateFilter is evaluated."
+            )
+        if self._wildcard:
+            return True
+        current = await state.get_state()
+        return current in self._states

trueconf/fsm/key_builder.py

@@ -0,0 +1,39 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Protocol, runtime_checkable
+
+
+@dataclass(frozen=True, slots=True)
+class StorageKey:
+    bot_id: str | None
+    chat_id: str
+    user_id: str
+    destiny: str = "default"
+
+
+@runtime_checkable
+class KeyBuilder(Protocol):
+    def build(self, bot: Any, event: Any) -> StorageKey: ...
+
+
+class DefaultKeyBuilder:
+    def build(self, bot: Any, event: Any) -> StorageKey:
+        bot_id = getattr(bot, "me_id", None) or getattr(bot, "id", None)
+
+        chat_id = (
+            getattr(event, "chat_id", None)
+            or getattr(getattr(event, "chat", None), "id", None)
+        )
+
+        user = getattr(event, "from_user", None) or getattr(event, "author", None)
+        user_id = getattr(user, "id", None) if user else None
+
+        if chat_id is None or user_id is None:
+            raise RuntimeError(
+                f"Cannot build FSM StorageKey: event of type {type(event).__name__} "
+                f"has no chat_id ({chat_id}) or user_id ({user_id}). "
+                f"Provide a custom KeyBuilder to Dispatcher.setup_fsm()."
+            )
+
+        return StorageKey(bot_id=bot_id, chat_id=str(chat_id), user_id=str(user_id))

trueconf/fsm/manager.py

@@ -0,0 +1,36 @@
+from __future__ import annotations
+
+from typing import Any
+
+from trueconf.fsm.context import FSMContext
+from trueconf.fsm.key_builder import DefaultKeyBuilder, KeyBuilder, StorageKey
+from trueconf.fsm.storage.base import BaseStorage
+from trueconf.fsm.storage.memory import MemoryStorage
+from trueconf.fsm.strategy import FSMStrategy, apply_strategy
+
+
+class FSMManager:
+    def __init__(
+        self,
+        storage: BaseStorage | None = None,
+        key_builder: KeyBuilder | None = None,
+        strategy: FSMStrategy = FSMStrategy.USER_IN_CHAT,
+    ) -> None:
+        self.storage: BaseStorage = storage or MemoryStorage()
+        self.key_builder: KeyBuilder = key_builder or DefaultKeyBuilder()
+        self.strategy = strategy
+
+    def get_context(self, bot: Any, event: Any) -> FSMContext:
+        key = self.key_builder.build(bot, event)
+        chat_id, user_id = apply_strategy(
+            self.strategy,
+            key.chat_id,
+            key.user_id,
+        )
+        adjusted_key = StorageKey(
+            bot_id=key.bot_id,
+            chat_id=chat_id,
+            user_id=user_id,
+            destiny=key.destiny,
+        )
+        return FSMContext(self.storage, adjusted_key)

trueconf/fsm/middleware.py

@@ -0,0 +1,24 @@
+from __future__ import annotations
+
+from typing import Any
+
+from trueconf.fsm.manager import FSMManager
+from trueconf.middleware import BaseMiddleware
+
+
+class FSMMiddleware(BaseMiddleware):
+    def __init__(self, fsm_manager: FSMManager) -> None:
+        self._manager = fsm_manager
+
+    async def __call__(
+        self,
+        handler: Any,
+        event: Any,
+        data: dict[str, Any],
+    ) -> None:
+        bot = data.get("bot")
+        if bot is not None:
+            context = self._manager.get_context(bot, event)
+            data["state"] = context
+            data["raw_state"] = await context.get_state()
+        return await handler(event, data)

trueconf/fsm/state.py

@@ -0,0 +1,135 @@
+from __future__ import annotations
+
+import inspect
+from typing import Any
+
+
+class State:
+    def __init__(self, state: str | None = None) -> None:
+        self._custom_state = state
+        self._name: str | None = None
+        self._group: type[StatesGroup] | None = None
+
+    def bind(self, group: type[StatesGroup], name: str) -> None:
+        if self._group is not None or self._name is not None:
+            raise RuntimeError(
+                f"State '{self._name}' is already bound to {self._group}. "
+                f"Cannot rebind to {group.__name__}:{name}."
+            )
+        self._group = group
+        self._name = name
+
+    def __str__(self) -> str:
+        if self._custom_state is not None:
+            return self._custom_state
+        if self._group is None or self._name is None:
+            raise RuntimeError(
+                "State is not bound to a StatesGroup. "
+                "Use State inside a StatesGroup class definition, "
+                "or pass a custom string: State('my:state')."
+            )
+        return f"{self._group.__full_group_name__}:{self._name}"
+
+    def __repr__(self) -> str:
+        return f"State({str(self)!r})"
+
+    def __eq__(self, other: object) -> bool:
+        if isinstance(other, State):
+            return str(self) == str(other)
+        if isinstance(other, str):
+            return str(self) == other
+        return NotImplemented
+
+    def __hash__(self) -> int:
+        return hash(str(self))
+
+
+class _StatesGroupMeta(type):
+    __parent__: type[StatesGroup] | None
+    __childs__: tuple[type[StatesGroup], ...]
+    __states__: tuple[State, ...]
+    __all_states__: tuple[State, ...]
+    __all_childs__: tuple[type[StatesGroup], ...]
+
+    def __new__(
+        mcs,
+        name: str,
+        bases: tuple[type, ...],
+        namespace: dict[str, Any],
+    ) -> _StatesGroupMeta:
+        cls = super().__new__(mcs, name, bases, namespace)
+
+        states: list[State] = []
+        childs: list[type[StatesGroup]] = []
+
+        for key, value in namespace.items():
+            if isinstance(value, State):
+                value.bind(cls, key)
+                states.append(value)
+            elif (
+                inspect.isclass(value)
+                and issubclass(value, StatesGroup)
+                and value is not StatesGroup
+            ):
+                child = cls._prepare_child(value)
+                childs.append(child)
+
+        cls.__parent__ = None  # type: ignore[attr-defined]
+        cls.__childs__ = tuple(childs)  # type: ignore[attr-defined]
+        cls.__states__ = tuple(states)  # type: ignore[attr-defined]
+        cls.__all_childs__ = cls._get_all_childs()  # type: ignore[attr-defined]
+        cls.__all_states__ = cls._get_all_states()  # type: ignore[attr-defined]
+
+        return cls
+
+    @property
+    def __full_group_name__(cls) -> str:  # type: ignore[override]
+        if cls.__parent__ is not None:
+            return f"{cls.__parent__.__full_group_name__}.{cls.__name__}"
+        return cls.__name__
+
+    def _prepare_child(cls, child: type[StatesGroup]) -> type[StatesGroup]:
+        child.__parent__ = cls  # type: ignore[assignment]
+        return child
+
+    def _get_all_childs(cls) -> tuple[type[StatesGroup], ...]:
+        result: list[type[StatesGroup]] = list(cls.__childs__)
+        for child in cls.__childs__:
+            result.extend(child.__childs__)
+        return tuple(result)
+
+    def _get_all_states(cls) -> tuple[State, ...]:
+        result: list[State] = list(cls.__states__)
+        for child in cls.__childs__:
+            result.extend(child.__all_states__)
+        return tuple(result)
+
+    def __contains__(cls, item: Any) -> bool:
+        if isinstance(item, str):
+            return item in tuple(str(s) for s in cls.__all_states__)
+        if isinstance(item, State):
+            return item in cls.__all_states__
+        if isinstance(item, _StatesGroupMeta):
+            return item in cls.__all_childs__
+        return False
+
+    def __iter__(cls) -> Any:
+        return iter(cls.__all_states__)
+
+
+class StatesGroup(metaclass=_StatesGroupMeta):
+    __parent__: type[StatesGroup] | None = None
+    __childs__: tuple[type[StatesGroup], ...] = ()
+    __states__: tuple[State, ...] = ()
+    __all_states__: tuple[State, ...] = ()
+    __all_childs__: tuple[type[StatesGroup], ...] = ()
+
+    @classmethod
+    def get_root(cls) -> type[StatesGroup]:
+        if cls.__parent__ is None:
+            return cls
+        return cls.__parent__.get_root()
+
+
+any_state = State(state="*")
+default_state = State()

trueconf/fsm/storage/__init__.py

@@ -0,0 +1,4 @@
+from trueconf.fsm.storage.base import BaseStorage
+from trueconf.fsm.storage.memory import MemoryStorage
+
+__all__ = ("BaseStorage", "MemoryStorage")

trueconf/fsm/storage/base.py

@@ -0,0 +1,36 @@
+from abc import ABC, abstractmethod
+from typing import Any
+
+from trueconf.fsm.key_builder import StorageKey
+
+
+class BaseStorage(ABC):
+    @abstractmethod
+    async def get_state(self, key: StorageKey) -> str | None: ...
+
+    @abstractmethod
+    async def set_state(self, key: StorageKey, state: str | None) -> None: ...
+
+    @abstractmethod
+    async def get_data(self, key: StorageKey) -> dict[str, Any]: ...
+
+    @abstractmethod
+    async def set_data(self, key: StorageKey, data: dict[str, Any]) -> None: ...
+
+    @abstractmethod
+    async def update_data(self, key: StorageKey, updates: dict[str, Any]) -> dict[str, Any]: ...
+
+    @abstractmethod
+    async def clear(self, key: StorageKey) -> None: ...
+
+    async def get_value(
+        self,
+        key: StorageKey,
+        dict_key: str,
+        default: Any | None = None,
+    ) -> Any | None:
+        data = await self.get_data(key)
+        return data.get(dict_key, default)
+
+    async def close(self) -> None:
+        pass

trueconf/fsm/storage/memory.py

@@ -0,0 +1,57 @@
+from __future__ import annotations
+
+from copy import copy
+from dataclasses import dataclass, field
+from typing import Any
+
+from trueconf.fsm.key_builder import StorageKey
+from trueconf.fsm.storage.base import BaseStorage
+
+
+@dataclass
+class _Record:
+    state: str | None = None
+    data: dict[str, Any] = field(default_factory=dict)
+
+
+class MemoryStorage(BaseStorage):
+    def __init__(self) -> None:
+        self._records: dict[StorageKey, _Record] = {}
+
+    def _get_or_create(self, key: StorageKey) -> _Record:
+        if key not in self._records:
+            self._records[key] = _Record()
+        return self._records[key]
+
+    async def get_state(self, key: StorageKey) -> str | None:
+        record = self._records.get(key)
+        return record.state if record else None
+
+    async def set_state(self, key: StorageKey, state: str | None) -> None:
+        self._get_or_create(key).state = state
+
+    async def get_data(self, key: StorageKey) -> dict[str, Any]:
+        record = self._records.get(key)
+        return record.data.copy() if record else {}
+
+    async def set_data(self, key: StorageKey, data: dict[str, Any]) -> None:
+        self._get_or_create(key).data = data.copy()
+
+    async def update_data(self, key: StorageKey, updates: dict[str, Any]) -> dict[str, Any]:
+        record = self._get_or_create(key)
+        record.data.update(updates)
+        return record.data.copy()
+
+    async def clear(self, key: StorageKey) -> None:
+        self._records.pop(key, None)
+
+    async def get_value(
+        self,
+        key: StorageKey,
+        dict_key: str,
+        default: Any | None = None,
+    ) -> Any | None:
+        record = self._records.get(key)
+        if record is None:
+            return default
+        return copy(record.data.get(dict_key, default))

trueconf/fsm/strategy.py

@@ -0,0 +1,36 @@
+from __future__ import annotations
+
+from enum import Enum, auto
+
+
+class FSMStrategy(Enum):
+    """FSM strategy for storage key generation.
+
+    Determines how chat_id and user_id are combined to form the storage key.
+    """
+
+    USER_IN_CHAT = auto()
+    """State is stored per user per chat. Default behavior."""
+
+    CHAT = auto()
+    """State is stored per chat (all users in a chat share the same state)."""
+
+    GLOBAL_USER = auto()
+    """State is stored per user globally (across all chats)."""
+
+
+def apply_strategy(
+    strategy: FSMStrategy,
+    chat_id: str,
+    user_id: str,
+) -> tuple[str, str]:
+    """Apply FSM strategy to chat_id and user_id.
+
+    Returns (effective_chat_id, effective_user_id) for StorageKey construction.
+    """
+    if strategy == FSMStrategy.CHAT:
+        return chat_id, chat_id
+    if strategy == FSMStrategy.GLOBAL_USER:
+        return user_id, user_id
+    # USER_IN_CHAT (default)
+    return chat_id, user_id

trueconf/middleware.py

@@ -0,0 +1,78 @@
+from __future__ import annotations
+import logging
+from typing import TYPE_CHECKING, Any, Awaitable, Callable, Dict
+
+from trueconf.filters.base import Event
+
+if TYPE_CHECKING:
+    pass
+
+logger = logging.getLogger("chat_bot")
+
+MiddlewareHandler = Callable[[Event, Dict[str, Any]], Awaitable[None]]
+
+
+class BaseMiddleware:
+    """
+    Base middleware class for event processing pipeline.
+
+    Middleware wraps event handlers and can intercept, modify, or block events
+    before they reach the actual handler. To block an event, simply do not call
+    ``await handler(event, data)``.
+
+    Example:
+        >>> class LoggingMiddleware(BaseMiddleware):
+        ...     async def __call__(self, handler, event, data):
+        ...         logger.info(f"Event: {event}")
+        ...         await handler(event, data)
+        ...         logger.info("Done")
+
+        >>> router.outer_middleware(LoggingMiddleware())
+    """
+
+    async def __call__(
+        self,
+        handler: MiddlewareHandler,
+        event: Event,
+        data: Dict[str, Any],
+    ) -> None:
+        await handler(event, data)
+
+
+class SkipSelfMessages(BaseMiddleware):
+    """
+    Middleware that drops messages sent by the bot itself.
+
+    Prevents the bot from reacting to its own messages when multiple bot sessions
+    are running. If the event is a ``Message`` and its ``author.id`` matches
+    ``bot.me_id``, the event is silently dropped.
+
+    Registration:
+        Automatically registered when ``Bot(skip_self_messages=True)`` (default).
+        Alternatively:
+        >>> from trueconf.middleware import SkipSelfMessages
+        >>> dp.outer_middleware(SkipSelfMessages())
+    """
+
+    async def __call__(
+        self,
+        handler: MiddlewareHandler,
+        event: Event,
+        data: Dict[str, Any],
+    ) -> None:
+        bot = data.get("bot")
+        if bot is None:
+            await handler(event, data)
+            return
+
+        from trueconf.types.message import Message
+
+        if isinstance(event, Message) and event.author.id == bot.me_id:
+            logger.debug(
+                "[SkipSelfMessages] dropped message %s from bot self (author=%s)",
+                event.message_id,
+                event.author.id,
+            )
+            return
+
+        await handler(event, data)