Cross-process communication via use_channel_layer hook (#221)

This PR develops a `use_channel_layer` hook which provides simplified Django channel layers support.

Author: Archmonger

CHANGELOG.md

@@ -34,7 +34,9 @@ Using the following categories, list your changes in this order:
 
 ## [Unreleased]
 
--   Nothing (yet)!
+### Added
+
+-   Built-in cross-process communication mechanism via the `reactpy_django.hooks.use_channel_layer` hook.
 
 ## [3.7.0] - 2024-01-30
 

docs/examples/python/use-channel-layer-group.py

@@ -0,0 +1,40 @@
+from reactpy import component, hooks, html
+from reactpy_django.hooks import use_channel_layer
+
+
+@component
+def my_sender_component():
+    sender = use_channel_layer("my-channel-name", group=True)
+
+    async def submit_event(event):
+        if event["key"] == "Enter":
+            await sender({"text": event["target"]["value"]})
+
+    return html.div(
+        "Message Sender: ",
+        html.input({"type": "text", "onKeyDown": submit_event}),
+    )
+
+
+@component
+def my_receiver_component_1():
+    message, set_message = hooks.use_state("")
+
+    async def receive_event(message):
+        set_message(message["text"])
+
+    use_channel_layer("my-channel-name", receiver=receive_event, group=True)
+
+    return html.div(f"Message Receiver 1: {message}")
+
+
+@component
+def my_receiver_component_2():
+    message, set_message = hooks.use_state("")
+
+    async def receive_event(message):
+        set_message(message["text"])
+
+    use_channel_layer("my-channel-name", receiver=receive_event, group=True)
+
+    return html.div(f"Message Receiver 2: {message}")

docs/examples/python/use-channel-layer-signal-receiver.py

@@ -0,0 +1,14 @@
+from reactpy import component, hooks, html
+from reactpy_django.hooks import use_channel_layer
+
+
+@component
+def my_receiver_component():
+    message, set_message = hooks.use_state("")
+
+    async def receive_event(message):
+        set_message(message["text"])
+
+    use_channel_layer("my-channel-name", receiver=receive_event)
+
+    return html.div(f"Message Receiver: {message}")

docs/examples/python/use-channel-layer-signal-sender.py

@@ -0,0 +1,20 @@
+from asgiref.sync import async_to_sync
+from channels.layers import get_channel_layer
+from django.db.models import Model
+from django.db.models.signals import pre_save
+from django.dispatch import receiver
+
+
+class ExampleModel(Model):
+    ...
+
+
+@receiver(pre_save, sender=ExampleModel)
+def my_sender_signal(sender, instance, **kwargs):
+    layer = get_channel_layer()
+
+    # Example of sending a message to a channel
+    async_to_sync(layer.send)("my-channel-name", {"text": "Hello World!"})
+
+    # Example of sending a message to a group channel
+    async_to_sync(layer.group_send)("my-channel-name", {"text": "Hello World!"})

docs/examples/python/use-channel-layer.py

@@ -0,0 +1,28 @@
+from reactpy import component, hooks, html
+from reactpy_django.hooks import use_channel_layer
+
+
+@component
+def my_sender_component():
+    sender = use_channel_layer("my-channel-name")
+
+    async def submit_event(event):
+        if event["key"] == "Enter":
+            await sender({"text": event["target"]["value"]})
+
+    return html.div(
+        "Message Sender: ",
+        html.input({"type": "text", "onKeyDown": submit_event}),
+    )
+
+
+@component
+def my_receiver_component():
+    message, set_message = hooks.use_state("")
+
+    async def receive_event(message):
+        set_message(message["text"])
+
+    use_channel_layer("my-channel-name", receiver=receive_event)
+
+    return html.div(f"Message Receiver: {message}")

docs/src/about/changelog.md

@@ -3,6 +3,12 @@ hide:
     - toc
 ---
 
+<!--
+
+If you see this page, you probably meant to visit the other CHANGELOG.md (all caps).
+
+-->
+
 <p class="intro" markdown>
 
 {% include-markdown "../../../CHANGELOG.md" start="<!--attr-start-->" end="<!--attr-end-->" %}

docs/src/dictionary.txt

@@ -38,3 +38,4 @@ misconfiguration
 misconfigurations
 backhaul
 sublicense
+broadcasted

docs/src/reference/hooks.md

@@ -275,7 +275,11 @@ Mutation functions can be sync or async.
 
 ### Use User Data
 
-Store or retrieve data (`#!python dict`) specific to the connection's `#!python User`. This data is stored in the `#!python REACTPY_DATABASE`.
+Store or retrieve a `#!python dict` containing user data specific to the connection's `#!python User`.
+
+This hook is useful for storing user-specific data, such as preferences, settings, or any generic key-value pairs.
+
+User data saved with this hook is stored within the `#!python REACTPY_DATABASE`.
 
 === "components.py"
 
@@ -312,6 +316,103 @@ Store or retrieve data (`#!python dict`) specific to the connection's `#!python
 
 ---
 
+## Communication Hooks
+
+---
+
+### Use Channel Layer
+
+Subscribe to a [Django Channels layer](https://channels.readthedocs.io/en/latest/topics/channel_layers.html) to send/receive messages.
+
+Layers are a multiprocessing-safe communication system that allows you to send/receive messages between different parts of your application.
+
+This is often used to create chat systems, synchronize data between components, or signal re-renders from outside your components.
+
+=== "components.py"
+
+    ```python
+    {% include "../../examples/python/use-channel-layer.py" %}
+    ```
+
+??? example "See Interface"
+
+    <font size="4">**Parameters**</font>
+
+    | Name | Type | Description | Default |
+    | --- | --- | --- | --- |
+    | `#!python name` | `#!python str` | The name of the channel to subscribe to. | N/A |
+    | `#!python receiver` | `#!python AsyncMessageReceiver | None` | An async function that receives a `#!python message: dict` from the channel layer. If more than one receiver waits on the same channel, a random one will get the result (unless `#!python group=True` is defined). | `#!python None` |
+    | `#!python group` | `#!python bool` | If `#!python True`, a "group channel" will be used. Messages sent within a group are broadcasted to all receivers on that channel. | `#!python False` |
+    | `#!python layer` | `#!python str` | The channel layer to use. These layers must be defined in `#!python settings.py:CHANNEL_LAYERS`. | `#!python 'default'` |
+
+    <font size="4">**Returns**</font>
+
+    | Type | Description |
+    | --- | --- |
+    | `#!python AsyncMessageSender` | An async callable that can send a `#!python message: dict` |
+
+??? warning "Extra Django configuration required"
+
+    In order to use this hook, you will need to configure Django to enable channel layers.
+
+    The [Django Channels documentation](https://channels.readthedocs.io/en/latest/topics/channel_layers.html#configuration) has information on what steps you need to take.
+
+    In summary, you will need to:
+
+    1. Run the following command to install `channels-redis` in your Python environment.
+
+        ```bash linenums="0"
+        pip install channels-redis
+        ```
+
+    2. Configure your `settings.py` to use `RedisChannelLayer` as your layer backend.
+
+        ```python linenums="0"
+        CHANNEL_LAYERS = {
+            "default": {
+                "BACKEND": "channels_redis.core.RedisChannelLayer",
+                "CONFIG": {
+                    "hosts": [("127.0.0.1", 6379)],
+                },
+            },
+        }
+        ```
+
+??? question "How do I broadcast a message to multiple components?"
+
+    By default, if more than one receiver waits on the same channel, a random one will get the result.
+
+    However, by defining `#!python group=True` you can configure a "group channel", which will broadcast messages to all receivers.
+
+    In the example below, all messages sent by the `#!python sender` component will be received by all `#!python receiver` components that exist (across every active client browser).
+
+    === "components.py"
+
+        ```python
+        {% include "../../examples/python/use-channel-layer-group.py" %}
+        ```
+
+??? question "How do I signal a re-render from something that isn't a component?"
+
+    There are occasions where you may want to signal a re-render from something that isn't a component, such as a Django model signal.
+
+    In these cases, you can use the `#!python use_channel_layer` hook to receive a signal within your component, and then use the `#!python get_channel_layer().send(...)` to send the signal.
+
+    In the example below, the sender will send a signal every time `#!python ExampleModel` is saved. Then, when the receiver component gets this signal, it explicitly calls `#!python set_message(...)` to trigger a re-render.
+
+    === "components.py"
+
+        ```python
+        {% include "../../examples/python/use-channel-layer-signal-receiver.py" %}
+        ```
+    === "signals.py"
+
+        ```python
+        {% include "../../examples/python/use-channel-layer-signal-sender.py" %}
+        ```
+
+---
+
 ## Connection Hooks
 
 ---

docs/src/reference/router.md

@@ -2,7 +2,7 @@
 
 <p class="intro" markdown>
 
-A variant of [`reactpy-router`](https://github.com/reactive-python/reactpy-router) that utilizes Django conventions.
+A Single Page Application URL router, which is a variant of [`reactpy-router`](https://github.com/reactive-python/reactpy-router) that uses Django conventions.
 
 </p>
 

requirements/check-types.txt

@@ -1,2 +1,3 @@
 mypy
 django-stubs[compatible-mypy]
+channels-redis