Implement decentralized event handlers

Co-Authored-By: khaleel@reflex.dev <khaleel.aladhami@gmail.com>

Author: devin-ai-integration[bot]

reflex/event.py

@@ -55,6 +55,30 @@
 )
 from reflex.vars.object import ObjectVar
 
+_global_event_handlers: dict[str, EventHandler] = {}
+
+
+def register_event_handler(name: str, handler: EventHandler) -> None:
+    """Register a decentralized event handler.
+
+    Args:
+        name: The name of the event handler.
+        handler: The event handler.
+    """
+    _global_event_handlers[name] = handler
+
+
+def get_event_handler(name: str) -> EventHandler | None:
+    """Get a decentralized event handler by name.
+
+    Args:
+        name: The name of the event handler.
+
+    Returns:
+        The event handler, or None if not found.
+    """
+    return _global_event_handlers.get(name)
+
 
 @dataclasses.dataclass(
     init=True,
@@ -178,7 +202,7 @@ class EventHandler(EventActionsMixin):
 
     # The full name of the state class this event handler is attached to.
     # Empty string means this event handler is a server side event.
-    state_full_name: str = dataclasses.field(default="")
+    state_full_name: str | None = dataclasses.field(default="")
 
     @classmethod
     def __class_getitem__(cls, args_spec: str) -> Annotated:
@@ -261,6 +285,13 @@ def __call__(self, *args: Any, **kwargs: Any) -> EventSpec:
                 ) from e
         payload = tuple(zip(fn_args, values, strict=False))
 
+        # Check if this is a decentralized event handler
+        if self.state_full_name is None:
+            from reflex.utils import format
+
+            name = format.to_snake_case(self.fn.__qualname__)
+            register_event_handler(name, self)
+
         # Return the event spec.
         return EventSpec(
             handler=self, args=payload, event_actions=self.event_actions.copy()
@@ -1492,6 +1523,9 @@ def check_fn_match_arg_spec(
     Raises:
         EventFnArgMismatchError: Raised if the number of mandatory arguments do not match
     """
+    if is_decentralized_event_handler(user_func):
+        return
+
     user_args = list(inspect.signature(user_func).parameters)
     # Drop the first argument if it's a bound method
     if inspect.ismethod(user_func) and user_func.__self__ is not None:
@@ -1518,6 +1552,61 @@ def check_fn_match_arg_spec(
         )
 
 
+DECENTRALIZED_EVENT_MARKER = "_rx_decentralized_event"
+
+
+def is_decentralized_event_handler(fn: Callable) -> bool:
+    """Check if a function is a decentralized event handler.
+
+    Args:
+        fn: The function to check.
+
+    Returns:
+        Whether the function is a decentralized event handler.
+    """
+    # Check if the function has been decorated with @rx.event
+    if not hasattr(fn, "__qualname__"):
+        return False
+
+    # Check if the function has the decentralized event marker
+    return hasattr(fn, DECENTRALIZED_EVENT_MARKER)
+
+
+def wrap_decentralized_handler(fn: Callable) -> Callable:
+    """Wrap a decentralized event handler to be used with component events.
+
+    This creates a wrapper that doesn't require the state parameter when called
+    from a component event, but will pass the state when the event is processed.
+
+    Args:
+        fn: The decentralized event handler to wrap.
+
+    Returns:
+        A wrapped function that can be used with component events.
+    """
+
+    # Create a wrapper function that doesn't require the state parameter
+    def wrapper(*args, **kwargs):
+        # Get or create the event handler
+        from reflex.utils import format
+
+        name = format.to_snake_case(fn.__qualname__)
+        handler = _global_event_handlers.get(name)
+        if handler is None:
+            handler = EventHandler(fn=fn, state_full_name=None)
+            register_event_handler(name, handler)
+
+        # Create an event spec with no arguments - the state will be provided
+        return EventSpec(handler=handler, args=())
+
+    wrapper.__name__ = fn.__name__
+    wrapper.__qualname__ = fn.__qualname__
+    wrapper.__doc__ = fn.__doc__
+    wrapper.__module__ = fn.__module__
+
+    return wrapper
+
+
 def call_event_fn(
     fn: Callable,
     arg_spec: ArgsSpec | Sequence[ArgsSpec],
@@ -1543,6 +1632,11 @@ def call_event_fn(
     from reflex.event import EventHandler, EventSpec
     from reflex.utils.exceptions import EventHandlerValueError
 
+    # Check if this is a decentralized event handler
+    if is_decentralized_event_handler(fn):
+        wrapped_fn = wrap_decentralized_handler(fn)
+        return call_event_fn(wrapped_fn, arg_spec, key=key)
+
     # Check that fn signature matches arg_spec
     check_fn_match_arg_spec(fn, arg_spec, key=key)
 
@@ -2066,7 +2160,19 @@ def wrapper(
                 setattr(func, BACKGROUND_TASK_MARKER, True)
             if getattr(func, "__name__", "").startswith("_"):
                 raise ValueError("Event handlers cannot be private.")
-            return func  # pyright: ignore [reportReturnType]
+
+            # Check if this is a method (defined in a class) or a standalone function
+            if hasattr(func, "__qualname__") and "." in func.__qualname__:
+                return func  # pyright: ignore [reportReturnType]
+            else:
+                # This is a decentralized event handler
+                handler = EventHandler(fn=func, state_full_name=None)
+                if background:
+                    setattr(handler, BACKGROUND_TASK_MARKER, True)
+                # Mark the function as a decentralized event handler
+                setattr(func, DECENTRALIZED_EVENT_MARKER, True)
+                # Return the original function so it can be called normally
+                return func  # pyright: ignore [reportReturnType]
 
         if func is not None:
             return wrapper(func)

reflex/state.py

@@ -1586,15 +1586,30 @@ def _get_event_handler(
         Args:
             event: The event to get the handler for.
 
-
         Returns:
             The event handler.
 
         Raises:
             ValueError: If the event handler or substate is not found.
+            EventHandlerValueError: If the event handler is not found.
         """
         # Get the event handler.
         path = event.name.split(".")
+
+        if "." not in event.name:
+            from reflex.event import get_event_handler
+            from reflex.utils.exceptions import EventHandlerValueError
+
+            handler = get_event_handler(event.name)
+            if handler is None:
+                raise EventHandlerValueError(f"Event handler {event.name} not found.")
+
+            # For background tasks, proxy the state
+            if handler.is_background:
+                return StateProxy(self), handler
+
+            return self, handler
+
         path, name = path[:-1], path[-1]
         substate = self.get_substate(path)
         if not substate:
@@ -1753,7 +1768,10 @@ async def _process_event(
         from reflex.utils import telemetry
 
         # Get the function to process the event.
-        fn = functools.partial(handler.fn, state)
+        if handler.state_full_name is None:
+            fn = handler.fn
+        else:
+            fn = functools.partial(handler.fn, state)
 
         try:
             type_hints = typing.get_type_hints(handler.fn)

reflex/utils/format.py

@@ -483,6 +483,11 @@ def format_event_handler(handler: EventHandler) -> str:
     Returns:
         The formatted function.
     """
+    if handler.state_full_name is None:
+        from reflex.utils import format
+
+        return format.to_snake_case(handler.fn.__qualname__)
+
     state, name = get_event_handler_parts(handler)
     if state == "":
         return name

tests/integration/test_decentralized_event_handlers.py

@@ -0,0 +1,110 @@
+"""Test decentralized event handlers functionality."""
+
+import pytest
+from selenium.webdriver.common.by import By
+
+from reflex.testing import AppHarness, WebDriver
+
+
+def DecentralizedEventHandlers():
+    """Test that decentralized event handlers work as expected."""
+    import reflex as rx
+
+    class TestState(rx.State):
+        count: int = 0
+
+        @rx.event
+        def increment(self):
+            """Increment the counter."""
+            self.count += 1
+
+    @rx.event
+    def on_load(state: TestState):
+        """Event handler for loading the state.
+
+        Args:
+            state: The state to modify.
+        """
+        state.count = 10
+
+    @rx.event
+    def reset_count(state: TestState):
+        """Event handler for resetting the count.
+
+        Args:
+            state: The state to modify.
+        """
+        state.count = 0
+
+    def index():
+        return rx.vstack(
+            rx.heading(TestState.count, id="counter"),
+            rx.button("Increment", on_click=TestState.increment, id="increment"),
+            rx.button("Reset", on_click=reset_count, id="reset"),
+            rx.text("Loaded", on_mount=on_load, id="loaded"),
+        )
+
+    app = rx.App()
+    app.add_page(index)
+
+
+@pytest.fixture(scope="module")
+def decentralized_handlers(
+    tmp_path_factory,
+):
+    """Start DecentralizedEventHandlers app at tmp_path via AppHarness.
+
+    Args:
+        tmp_path_factory: pytest tmp_path_factory fixture
+
+    Yields:
+        running AppHarness instance
+    """
+    with AppHarness.create(
+        root=tmp_path_factory.mktemp("decentralized_handlers"),
+        app_source=DecentralizedEventHandlers,
+    ) as harness:
+        yield harness
+
+
+@pytest.fixture
+def driver(decentralized_handlers: AppHarness):
+    """Get an instance of the browser open to the app.
+
+    Args:
+        decentralized_handlers: harness for DecentralizedEventHandlers app
+
+    Yields:
+        WebDriver instance.
+    """
+    assert decentralized_handlers.app_instance is not None, "app is not running"
+    driver = decentralized_handlers.frontend()
+    try:
+        yield driver
+    finally:
+        driver.quit()
+
+
+def test_decentralized_event_handlers(
+    decentralized_handlers: AppHarness,
+    driver: WebDriver,
+):
+    """Test that decentralized event handlers work as expected.
+
+    Args:
+        decentralized_handlers: harness for DecentralizedEventHandlers app
+        driver: WebDriver instance
+    """
+    assert decentralized_handlers.app_instance is not None
+
+    counter = driver.find_element(By.ID, "counter")
+    increment_button = driver.find_element(By.ID, "increment")
+    reset_button = driver.find_element(By.ID, "reset")
+
+    assert decentralized_handlers._poll_for(lambda: counter.text == "10", timeout=5)
+
+    increment_button.click()
+    assert decentralized_handlers._poll_for(lambda: counter.text == "11", timeout=5)
+
+    reset_button.click()
+    assert decentralized_handlers._poll_for(lambda: counter.text == "0", timeout=5)