django-sockets 1.0.0__py3-none-any.whl

django_sockets/broadcaster.py

@@ -0,0 +1,99 @@
+import asyncio, logging
+
+from .pubsub import PubSubLayer
+from .utils import ensure_loop_running, get_config
+
+logger = logging.getLogger(__name__)
+
+
+class Broadcaster:
+    def __init__(self, *args, loop=None, config=None, **kwargs):
+        self.__loop__ = ensure_loop_running(loop)
+        self.pubsub_layer = self.__get_pubsub_layer__(config=config)
+        self.__usable__ = self.pubsub_layer is not None
+
+    # Sync Functions
+    def broadcast(self, channel: str, data: [dict | list]):
+        """
+        Broadcast data to a specific channel or all channels that this socket server is subscribed to.
+
+        Requires:
+
+        - channel: str = The channel to broadcast the data to
+        - data: [dict|list] = The data to broadcast to the channel
+            - Note: This data must be JSON serializable
+        """
+        asyncio.run_coroutine_threadsafe(
+            self.async_broadcast(channel, data), self.__loop__
+        )
+
+    def subscribe(self, channel: str):
+        """
+        Subscribe to a channel to receive data from broadcasts
+
+        Requires:
+
+        - channel: str = The channel to subscribe to
+        """
+        asyncio.run_coroutine_threadsafe(
+            self.async_subscribe(channel), self.__loop__
+        )
+
+    # Async Functions
+    async def async_broadcast(self, channel: str, data):
+        """
+        Broadcast data to a channel where all relevant clients will receive the data
+        and send it to the client
+
+        Requires:
+
+        - channel: str = The channel to broadcast the data to
+        - data: [dict|list] = The data to broadcast to the channel
+            - Note: This data must be JSON serializable
+        """
+        self.__warn_on_not_usable__()
+        await self.pubsub_layer.send(str(channel), data)
+
+    async def async_subscribe(self, channel: str):
+        """
+        Subscribe to a channel to receive data from broadcasts
+
+        Requires:
+
+        - channel: str = The channel to subscribe to
+        """
+        self.__warn_on_not_usable__()
+        await self.pubsub_layer.subscribe(str(channel))
+
+    async def async_receive_broadcast(self):
+        """
+        Receive a broadcast from a channel that this socket server is subscribed to
+
+        Returns:
+
+        - channel: str = The channel that the data was broadcasted to
+        - data: [dict|list] = The data that was broadcasted to the channel
+            - Note: This data must be JSON serializable
+        """
+        data = await self.pubsub_layer.receive()
+        return data["channel"], data["data"]
+
+    # Internal Methods
+    def __get_pubsub_layer__(self, config=None):
+        """
+        A method to get the PubSubLayer given the settings.DJANGO_SOCKETS_CONFIG
+        """
+        config = get_config(config)
+        if "hosts" in config:
+            return PubSubLayer(**config)
+        return None
+
+    def __warn_on_not_usable__(self):
+        """
+        Warn the user if the broadcaster is not usable
+        """
+        if not self.__usable__:
+            logger.log(
+                logging.ERROR,
+                "No hosts provided in settings.DJANGO_SOCKETS_CONFIG. Broadcasting / Subscribing is not possible.",
+            )

django_sockets/middleware.py

@@ -0,0 +1,56 @@
+from .utils import database_sync_to_async
+
+def get_anonymous_user_obj():
+    try:
+        return AnonymousUser()
+    except:
+        pass
+    try:
+        from django.contrib.auth.models import AnonymousUser
+        return AnonymousUser()
+    except:
+        pass
+    return None
+    
+def get_drf_token_obj():
+    try:
+        return Token
+    except:
+        pass
+    try:
+        from rest_framework.authtoken.models import Token
+        return Token
+    except:
+        pass
+    return None
+
+@database_sync_to_async
+def get_drf_user(user_token):
+    if user_token is not None:
+        try:
+            token = get_drf_token_obj().objects.get(key=user_token)
+            return token.user
+        except:
+            pass
+    return get_anonymous_user_obj()
+
+
+def get_query_arg(query_string, arg, default=None):
+    try:
+        return (
+            dict((x.split("=") for x in query_string.decode().split("&")))
+        ).get(arg, default)
+    except:
+        return None
+
+
+class DRFTokenAuthMiddleware:
+    def __init__(self, app):
+        self.app = app
+
+    async def __call__(self, scope, receive, send):
+        scope = dict(scope)
+        scope["user"] = await get_drf_user(
+            get_query_arg(scope["query_string"], "user_token")
+        )
+        return await self.app(scope, receive, send)

django_sockets/pubsub.py

@@ -0,0 +1,315 @@
+import asyncio, logging, binascii, msgpack, logging, uuid
+from redis.asyncio import Redis, ConnectionPool, sentinel
+
+logger = logging.getLogger(__name__)
+
+
+class PubSubLayer:
+    """
+    A meta PubSub Layer that uses Redis's pub/sub functionality and allows multiple subscriptions to
+    different channels that may or may not be on different cache shards.
+
+    This layer is designed to be used with asyncio and is not necessarily thread-safe.
+    """
+
+    def __init__(
+        self,
+        hosts=None,
+    ):
+        """
+        Initialize the PubSub Layer
+
+        Requires:
+        - hosts: A list of dictionaries
+            - Note: This uses a redis connection pool or a sentinel connection pool to connect to the Redis server.
+            - Each dictionary should contain the following key value pairs (depending on the connection pool type):
+                - ConnectionPool:
+                    - address: The address of the Redis server
+                        - EG: 'redis://0.0.0.0:6379'
+                        - Note: This can be used alone or in conjunction with other connection pool keys
+                    - host: The host of the Redis server
+                        - Note: This must be used with the port key and can be used in conjunction with the other connection pool keys
+                    - port: The port of the Redis server
+                        - Note: This must be used with the host key and can be used in conjunction with the other connection pool keys
+                    - Other keys listed in the redis-py ConnectionPool documentation
+                - SentinelConnectionPool:
+                    - master_name: The name of the master in a Redis Sentinel setup
+                    - sentinels: A list of sentinel addresses
+                    - sentinel_kwargs: A dictionary of keyword arguments to pass to the sentinel connect
+                    - Other keys listed in the redis-py SentinelConnectionPool documentation
+        """
+        self.queue = asyncio.Queue()
+        self.subscriptions = dict()
+        if not isinstance(hosts, list):
+            raise ValueError("Hosts must be a list of dictionaries")
+        if len(hosts) == 0:
+            raise ValueError("Hosts must contain at least one dictionary")
+        self.shards = [ShardConnection(host, self) for host in hosts]
+
+    # PubSub methods
+    async def subscribe(self, channel: str):
+        """
+        Subscribe to a channel
+        """
+        shard = self.__get_shard__(channel)
+        if channel not in self.subscriptions:
+            self.subscriptions[channel] = shard
+        await shard.subscribe(channel)
+
+    async def unsubscribe(self, channel: str):
+        """
+        Unsubscribe from a channel
+        """
+        if channel in self.subscriptions:
+            shard = self.subscriptions.pop(channel)
+            await shard.unsubscribe(channel)
+
+    async def send(self, channel: str, data):
+        """
+        Send data to a channel
+        """
+        shard = self.__get_shard__(channel)
+        await shard.publish(channel, data)
+
+    async def receive(self) -> dict | None:
+        """
+        Get the next item from the queue. This will hang until an item is available.
+
+        If the queue has been closed, cleanup and raise an exception to exit the calling task.
+
+        Format:
+        {
+            'channel': str,
+            'data': Any
+        }
+        """
+        try:
+            return await self.queue.get()
+        except (asyncio.CancelledError, asyncio.TimeoutError, GeneratorExit):
+            # Cleanup / unsubscribe on interruptions / exits / timeouts
+            await self.flush()
+            # Raise an exception to exit the calling task
+            raise asyncio.CancelledError
+
+    async def flush(self):
+        """
+        Flush the layer and close all connections.
+        """
+        for shard in set(self.subscriptions.values()):
+            try:
+                await shard.flush()
+            except asyncio.CancelledError:
+                raise asyncio.CancelledError
+            except BaseException as e:
+                logger.exception(
+                    f"Exception while flushing shard connection: {e}"
+                )
+        self.subscriptions = dict()
+
+    # Utility Methods
+    def __get_shard__(self, channel):
+        """
+        Return the shard that is used for this channel.
+
+        This is done by assigning a shard index location based on the CRC32 of the channel name.
+        """
+        if len(self.shards) == 1:
+            shard_index = 0
+        else:
+            hash_val = binascii.crc32(channel.encode("utf8")) & 0xFFF
+            shard_index = int(hash_val / (4096 / float(len(self.shards))))
+        return self.shards[shard_index]
+
+
+class ShardConnection:
+    def __init__(self, host, pubsub_layer_obj, prefix="pubsub"):
+        self.connection_pool = self.__get_connection_pool__(host)
+        self.pubsub_layer_obj = pubsub_layer_obj
+        self.lock = asyncio.Lock()
+        self.connection = None
+        self.pubsub = None
+        self.receiver_task = None
+        self.subscriptions = set()
+        self.prefix = prefix
+
+    # PubSub methods
+    async def subscribe(self, channel):
+        channel = self.__get_channel_name__(channel)
+        async with self.lock:
+            if channel in self.subscriptions:
+                return
+            await self.__ensure_connection__()
+            await self.pubsub.subscribe(channel)
+            self.subscriptions.add(channel)
+        # Drop out of the lock to start the receiver task which requires the lock to be released
+        await self.ensure_receiver_task()
+
+    async def unsubscribe(self, channel):
+        channel = self.__get_channel_name__(channel)
+        async with self.lock:
+            if channel not in self.subscriptions:
+                return
+            await self.__ensure_connection__()
+            await self.pubsub.unsubscribe(channel)
+            self.subscriptions.remove(channel)
+        if len(self.subscriptions) == 0:
+            await self.flush()
+
+    async def publish(self, channel, message):
+        channel = self.__get_channel_name__(channel)
+        async with self.lock:
+            await self.__ensure_connection__()
+            message = self.__serialize__(message)
+            # if the message is larger than 1MB, then save it as a uuid in the same cache and send the uuid
+            # This helps bypass the 32 MB limit on pubsub queue size for most cache servers
+            # Ensure that this objeect times out after 60s to keep the cache clean
+            if len(message) > 1024 * 1024:
+                msg_loc_key = f"{self.prefix}.{str(uuid.uuid4())}"
+                await self.connection.set(msg_loc_key, message, ex=60)
+                message = self.__serialize__(f"msg:{msg_loc_key}")
+            await self.connection.publish(channel, message)
+
+    async def ensure_receiver_task(self):
+        async with self.lock:
+            if self.receiver_task is None:
+                self.receiver_task = asyncio.create_task(
+                    self.__receiver_task__()
+                )
+                # This is needed to continue the main coroutine execution after create_task
+                await asyncio.sleep(0)
+
+    async def flush(self):
+        # Flushing is not locked since it can be called from inside the lock
+        if self.receiver_task:
+            self.receiver_task.cancel()
+            try:
+                await self.receiver_task
+            except asyncio.CancelledError:
+                pass
+            self.receiver_task = None
+        if self.pubsub:
+            await self.pubsub.close()
+            self.pubsub = None
+        if self.connection:
+            await self.connection.close()
+            self.connection = None
+
+    # Tasks
+    async def __receiver_task__(self):
+        """
+        Start a task to receive messages from the pubsub and put them in the queue
+
+        This task will run until all subscriptions are removed.
+
+        It will loop continuously as awaiting the pubsub.get_message will not hang the event loop.
+        """
+        # print("RECEIVER TASK STARTING")
+        while len(self.subscriptions) > 0:
+            try:
+                # Make sure pubsub is active and subscribed otherwise wait for subscription to be established
+                if self.pubsub and self.pubsub.subscribed:
+                    # Get messages from the pubsub
+                    message = await self.pubsub.get_message(
+                        ignore_subscribe_messages=True
+                    )
+                    # If message is not None, put it in the channel queue
+                    if message:
+                        message_data = self.__deserialize__(message["data"])
+                        # If the message was too large, then get that message from the cache
+                        if isinstance(message_data, str):
+                            if message_data.startswith("msg:"):
+                                msg_loc_key = message_data[4:]
+                                message_data = self.__deserialize__(
+                                    await self.connection.get(msg_loc_key)
+                                )
+                        self.pubsub_layer_obj.queue.put_nowait(
+                            {
+                                "channel": self.__get_channel_from_name__(
+                                    message["channel"].decode()
+                                ),
+                                "data": message_data,
+                            }
+                        )
+                # Wait for a short time to prevent busy waiting
+                # This also serves to wait for the pubsub layer to be subscribed to the channel
+                await asyncio.sleep(0.1)
+            # Exit on cancellation, timeout, or generator exit (for cleanup afer connection is closed)
+            except (
+                asyncio.CancelledError,
+                asyncio.TimeoutError,
+                GeneratorExit,
+            ):
+                # print("RECEIVER TASK KILLED")
+                raise asyncio.CancelledError
+            except:
+                logger.exception(
+                    "Exception while receiving message from pubsub"
+                )
+        await self.flush()
+
+    # Utility Methods
+    async def __ensure_connection__(self):
+        """
+        Ensure that the connection to the cache is established.
+
+        Note: This should only be called within a lock.
+        """
+        if not self.connection:
+            self.connection = Redis(connection_pool=self.connection_pool)
+            # If the connection failed, then raise an exception
+            try:
+                is_connected = await self.connection.ping()
+            except:
+                is_connected = False
+            if not is_connected:
+                logger.log(
+                    logging.ERROR,
+                    "Could not connect to the cache server. Please check your config and make sure that the cache server is running.",
+                )
+                raise ConnectionError("Could not connect to the cache server.")
+            self.pubsub = self.connection.pubsub()
+
+    def __get_channel_name__(self, channel):
+        """
+        Get the channel name with the prefix.
+        """
+        return f"{self.prefix}.{channel}"
+
+    def __get_channel_from_name__(self, channel_name):
+        """
+        Get the channel name without the prefix.
+        """
+        return channel_name[len(self.prefix) + 1 :]
+
+    def __serialize__(self, message):
+        """
+        Serialize a message into bytes.
+        """
+        return msgpack.packb(message)
+
+    def __deserialize__(self, message):
+        """
+        Deserialize a message from bytes.
+        """
+        return msgpack.unpackb(message, strict_map_key=False)
+
+    @staticmethod
+    def __get_connection_pool__(host: dict):
+        """
+        Get a connection pool from a host dictionary
+        """
+        host = host.copy()
+        if "address" in host:
+            address = host.pop("address")
+            return ConnectionPool.from_url(address, **host)
+
+        master_name = host.pop("master_name", None)
+        if master_name is not None:
+            sentinels = host.pop("sentinels")
+            sentinel_kwargs = host.pop("sentinel_kwargs", None)
+            return sentinel.SentinelConnectionPool(
+                master_name,
+                sentinel.Sentinel(sentinels, sentinel_kwargs=sentinel_kwargs),
+                **host,
+            )
+        return ConnectionPool(**host)

django_sockets/sockets.py

@@ -0,0 +1,206 @@
+import json, asyncio, logging
+from .broadcaster import Broadcaster
+from .utils import run_in_thread
+
+logger = logging.getLogger(__name__)
+
+
+class BaseSocketServer(Broadcaster):
+    def __init__(self, scope, receive, send, config=None):
+        """
+        Initialize the socket server
+
+        Required:
+
+        - scope: dict = The scope of the websocket connection
+        - receive: method = The `get` method for an asyncio.Queue() object that will be used to receive data from the websocket client
+        - send: async callable = The function that should send the data to the websocket client
+            - Note: This function takes in a dictionary with the following keys:
+                - type: str = The type of message to send (always 'websocket.send')
+                - text: str = The data to send to the client (the json serialized version of the data sent / broadcasted)
+
+        Optional:
+
+        - config: dict = The configuration for the socket server
+            - hosts: list = A list of dictionaries that contain the host information for the socket server
+                - See: django_sockets.pubsub.PubSubLayer docs for more more comprehensive docs on the config parameter
+            - Default:
+                - If provided in django settings: settings.DJANGO_SOCKETS_CONFIG
+                - Else: {'hosts': [{'address': 'redis://0.0.0.0:6379'}]}
+        """
+        self.scope = scope
+        self.__receive__ = receive
+        self.__send__ = send
+        self.is_alive = True
+        super().__init__(config=config)
+
+    # Sync Functions
+    def send(self, data: [dict | list | str | float | int]):
+        """
+        Send data to the websocket client.
+        - Note: This only sends data to the client from which the calling function was called
+        - Note: To send data to all clients that are subscribed to a channel, use the broadcast method
+                which is inherited from the Broadcaster class
+
+        Requires:
+
+        - data: [dict|list|str|float|int] = The data to send to the client
+            - Note: This data must be JSON serializable
+        """
+        self.run_async(self.async_send(data))
+
+    def run_async(self, func):
+        """
+        Run an async function in the current object's event loop
+        """
+        asyncio.run_coroutine_threadsafe(func, self.__loop__)
+
+    # Async Functions
+    async def async_send(self, data: [dict | list | str | float | int]):
+        """
+        Send data to the websocket client.
+        - Note: To send data to all clients that are subscribed to a channel, use the broadcast method
+                which is inherited from the Broadcaster class
+
+        Requires:
+
+        - data: [dict|list|str|float|int] = The data to send to the client
+            - Note: This data must be JSON serializable
+        """
+        if self.__send__ is None:
+            logger.log(
+                logging.ERROR,
+                "The send and async_send functions are not available because the send parameter was not provided when the socket server was initialized. To silence this warning, you can provide a function that simulates some sending behavior.",
+            )
+        else:
+            try:
+                json_data = json.dumps(data)
+            except:
+                raise ValueError("Data must be JSON serializable")
+            await self.__send__({"type": "websocket.send", "text": json_data})
+
+    async def async_handle_received_broadcast(
+        self, channel: str, data: [dict | list | str | float | int]
+    ):
+        """
+        Handle a received broadcast from a subscribed channel
+
+        This method is provided so that it can be overwritten by the user if they want to handle
+        received broadcasts from subscriptions in a specific way.
+
+        By default, this method will send the data to the client using the async_send method
+
+        In general, this method should only be called by the __broadcast_listener_task__ method
+
+        Requires:
+
+        - channel: str = The channel that the data was broadcasted to
+        - data: [dict|list|str|float|int] = The data that was broadcasted
+            - Note: This data must be JSON serializable
+        """
+        await self.async_send(data)
+
+    # Tasks
+    async def __ws_listener_task__(self):
+        """
+        Listen for incoming WS data and handle it accordingly
+        """
+        if self.__receive__ is None:
+            logger.log(
+                logging.ERROR,
+                "The websocket listener task is not available because the receive parameter was not provided when the socket server was initialized. To silence this warning, you can provide an asyncio.Queue() receive parameter and put items in it to simulate received ws messages.",
+            )
+        else:
+            while self.is_alive:
+                data = await self.__receive__()
+                if data["type"] == "websocket.receive":
+                    try:
+                        data_text = json.loads(data["text"])
+                        run_in_thread(self.receive, data_text)
+                    except:
+                        logger.exception("Invalid JSON data received")
+                elif data["type"] == "websocket.disconnect":
+                    self.__kill__()
+                elif data["type"] == "websocket.connect":
+                    await self.__send__({"type": "websocket.accept"})
+                    self.connect()
+                else:
+                    raise ValueError(f"Invalid WS data type: {data['type']}")
+
+    async def __broadcast_listener_task__(self):
+        """
+        Handle all messages that were broadcast to subscribed channels
+        """
+        # Only handle broadcasts if the broadcaster is usable
+        if self.__usable__:
+            while self.is_alive:
+                try:
+                    channel, data = await self.async_receive_broadcast()
+                    await self.async_handle_received_broadcast(channel, data)
+                # Cleanup on exit
+                except asyncio.CancelledError:
+                    raise asyncio.CancelledError
+                except Exception as e:
+                    raise e
+
+    # Lifecycle Methods
+    def __kill__(self):
+        """
+        Kill the socket server and stop all tasks
+        """
+        self.is_alive = False
+
+    async def async_start_listeners(self):
+        try:
+            # Create Tasks for the listener and queue processor
+            ws_listener_task = asyncio.create_task(self.__ws_listener_task__())
+            broadcast_listener_task = asyncio.create_task(
+                self.__broadcast_listener_task__()
+            )
+            # wait until the socket server is killed or the tasks are cancelled
+            while self.is_alive:
+                await asyncio.sleep(0.2)
+        # Catch exits handled by Daphne and allow the tasks to be cancelled
+        except asyncio.CancelledError:
+            pass
+        # Ensure all tasks are cancelled
+        ws_listener_task.cancel()
+        broadcast_listener_task.cancel()
+        # Allow the cancelation to run in the background
+        # The next line allows the async function to return
+        # and the above tasks to be cancelled in the background
+        await asyncio.sleep(0)
+
+    def start_listeners(self):
+        """
+        Start the listeners for the socket server
+        """
+        self.run_async(self.async_start_listeners())
+
+    # Utility Methods
+    @classmethod
+    async def as_asgi(cls, scope, receive, send):
+        """
+        An ASGI application runner function that can be called by Daphne.
+
+        This creates a new socket server instance and starts the listeners in the background.
+        """
+        # Wrap in a try / except block to catch unclean exits handled by Daphne
+        socket_server = cls(scope, receive, send)
+        await socket_server.async_start_listeners()
+
+    # Placeholder Methods
+    def receive(self, data):
+        """
+        Placeholder method for the receive method that must be overwritten by the user
+
+        This is the method that will be called when data is received from the ws client.
+        """
+        raise NotImplementedError(
+            "The receive method must be implemented by the user"
+        )
+
+    def connect(self):
+        """
+        Placeholder method for the connect method that can be overwritten by the user.
+        """

django_sockets/utils.py

@@ -0,0 +1,215 @@
+from django.db import close_old_connections
+from django.core.exceptions import ImproperlyConfigured
+from django.urls.exceptions import Resolver404
+from django.urls.resolvers import RegexPattern, RoutePattern, URLResolver
+
+import asyncio, logging, threading
+from asgiref.sync import SyncToAsync
+
+logger = logging.getLogger(__name__)
+
+def get_django_settings():
+    """
+    Get the Django settings
+    """
+    try:
+        return settings
+    except:
+        pass
+    try:
+        from django.conf import settings
+        if settings.configured:
+            return settings
+    except:
+        pass
+    return None
+
+
+def get_config(config=None):
+    """
+    Get the configuration for the socket server
+    """
+    # If the config is passed, return it.
+    if config is not None:
+        return config
+    # If the config is not passed, try to get it from the Django settings
+    django_settings = get_django_settings()
+    if hasattr(django_settings, "DJANGO_SOCKETS_CONFIG"):
+        return django_settings.DJANGO_SOCKETS_CONFIG
+    # If nothing has been returned yet, return a default configuration
+    return {"hosts": [{"address": "redis://0.0.0.0:6379"}]}
+
+
+def run_in_thread(command, *args, **kwargs):
+    """
+    Takes in a synchronous command along with args and kwargs and runs it in a background
+    thread that is not tied to the websocket connection.
+
+    This will be terminated when the larger daphne server is terminated
+    """
+    thread = threading.Thread(
+        target=command, args=args, kwargs=kwargs, daemon=True
+    )
+    thread.start()
+    return thread
+
+
+def start_event_loop_thread(loop):
+    """
+    Starts the event loop in a new thread
+    """
+    asyncio.set_event_loop(loop)
+    loop.run_forever()
+
+
+def ensure_loop_running(loop=None):
+    """
+    Starts the event loop in a new thread and returns the thread
+    """
+    loop = loop if loop is not None else asyncio.get_event_loop()
+    if not loop.is_running():
+        try:
+            thread = run_in_thread(start_event_loop_thread, loop)
+        except:
+            logger.log(logging.ERROR, "Event Loop already running")
+    return loop
+
+
+# The following code is copied directly from Django Channels (channels/db.py)
+# Begin Code Copy:
+################################################################################
+
+
+class DatabaseSyncToAsync(SyncToAsync):
+    """
+    SyncToAsync version that cleans up old database connections when it exits.
+    """
+
+    def thread_handler(self, loop, *args, **kwargs):
+        close_old_connections()
+        try:
+            return super().thread_handler(loop, *args, **kwargs)
+        finally:
+            close_old_connections()
+
+
+# The class is TitleCased, but we want to encourage use as a callable/decorator
+database_sync_to_async = DatabaseSyncToAsync
+################################################################################
+# End Code Copy:
+
+
+# The following code is copied directly from Django Channels (channels/routing.py)
+# Begin Code Copy:
+################################################################################
+class ProtocolTypeRouter:
+    """
+    Takes a mapping of protocol type names to other Application instances,
+    and dispatches to the right one based on protocol name (or raises an error)
+    """
+
+    def __init__(self, application_mapping):
+        self.application_mapping = application_mapping
+
+    async def __call__(self, scope, receive, send):
+        if scope["type"] in self.application_mapping:
+            application = self.application_mapping[scope["type"]]
+            return await application(scope, receive, send)
+        else:
+            raise ValueError(
+                "No application configured for scope type %r" % scope["type"]
+            )
+
+
+class URLRouter:
+    """
+    Routes to different applications/consumers based on the URL path.
+
+    Works with anything that has a ``path`` key, but intended for WebSocket
+    and HTTP. Uses Django's django.urls objects for resolution -
+    path() or re_path().
+    """
+
+    #: This router wants to do routing based on scope[path] or
+    #: scope[path_remaining]. ``path()`` entries in URLRouter should not be
+    #: treated as endpoints (ended with ``$``), but similar to ``include()``.
+    _path_routing = True
+
+    def __init__(self, routes):
+        self.routes = routes
+
+        for route in self.routes:
+            # The inner ASGI app wants to do additional routing, route
+            # must not be an endpoint
+            if getattr(route.callback, "_path_routing", False) is True:
+                pattern = route.pattern
+                if isinstance(pattern, RegexPattern):
+                    arg = pattern._regex
+                elif isinstance(pattern, RoutePattern):
+                    arg = pattern._route
+                else:
+                    raise ValueError(
+                        f"Unsupported pattern type: {type(pattern)}"
+                    )
+                route.pattern = pattern.__class__(
+                    arg, pattern.name, is_endpoint=False
+                )
+
+            if not route.callback and isinstance(route, URLResolver):
+                raise ImproperlyConfigured(
+                    "%s: include() is not supported in URLRouter. Use nested"
+                    " URLRouter instances instead." % (route,)
+                )
+
+    async def __call__(self, scope, receive, send):
+        # Get the path
+        path = scope.get("path_remaining", scope.get("path", None))
+        if path is None:
+            raise ValueError(
+                "No 'path' key in connection scope, cannot route URLs"
+            )
+
+        if "path_remaining" not in scope:
+            # We are the outermost URLRouter, so handle root_path if present.
+            root_path = scope.get("root_path", "")
+            if root_path and not path.startswith(root_path):
+                # If root_path is present, path must start with it.
+                raise ValueError("No route found for path %r." % path)
+            path = path[len(root_path) :]
+
+        # Remove leading / to match Django's handling
+        path = path.lstrip("/")
+        # Run through the routes we have until one matches
+        for route in self.routes:
+            try:
+                match = route.pattern.match(path)
+                if match:
+                    new_path, args, kwargs = match
+                    # Add defaults to kwargs from the URL pattern.
+                    kwargs.update(route.default_args)
+                    # Add args or kwargs into the scope
+                    outer = scope.get("url_route", {})
+                    application = route.callback
+                    return await application(
+                        dict(
+                            scope,
+                            path_remaining=new_path,
+                            url_route={
+                                "args": outer.get("args", ()) + args,
+                                "kwargs": {**outer.get("kwargs", {}), **kwargs},
+                            },
+                        ),
+                        receive,
+                        send,
+                    )
+            except Resolver404:
+                pass
+        else:
+            if "path_remaining" in scope:
+                raise Resolver404("No route found for path %r." % path)
+            # We are the outermost URLRouter
+            raise ValueError("No route found for path %r." % path)
+
+
+################################################################################
+# End Code Copy:

django_sockets-1.0.0.dist-info/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Connor Makowski
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

django_sockets-1.0.0.dist-info/METADATA

@@ -0,0 +1,191 @@
+Metadata-Version: 2.1
+Name: django_sockets
+Version: 1.0.0
+Summary: Simplified Django websocket processes designed to work with cloud caches
+Author-email: Connor Makowski <conmak@mit.edu>
+Project-URL: Homepage, https://github.com/connor-makowski/django_sockets
+Project-URL: Bug Tracker, https://github.com/connor-makowski/django_sockets/issues
+Project-URL: Documentation, https://connor-makowski.github.io/django_sockets/django_sockets.html
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: django >=5.0.0
+Requires-Dist: asgiref >=3.0.0
+Requires-Dist: redis >=5.0.0
+Requires-Dist: msgpack >=1.0.0
+
+# Django Sockets
+[![PyPI version](https://badge.fury.io/py/django_sockets.svg)](https://badge.fury.io/py/django_sockets)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Simplified Django websocket processes designed to work with cloud caches (valkey|redis on single|distributed|serverless)
+
+# Setup
+
+### General
+
+Make sure you have Python 3.10.x (or higher) installed on your system. You can download it [here](https://www.python.org/downloads/).
+
+### Installation
+
+```
+pip install django_sockets
+```
+
+### Other Requirements
+
+- Make sure a cache (valkey or redis) is setup and accessible from your server.
+
+    - To run one locally (using docker) for testing, you can use the following command:
+
+        ```bash
+        docker run -d -p 6379:6379 --name django_sockets_cache valkey/valkey:7
+        ```
+
+    - To run the container after it has been created, you can use the following command:
+
+        ```bash
+        docker start django_sockets_cache
+        ```
+
+    - To kill the container later, you can use the following command:
+
+        ```bash
+        docker kill django_sockets_cache
+        ```
+
+# Usage
+
+Low level docs: https://connor-makowski.github.io/django_sockets/django_sockets.html
+
+## Implement in a Django Project
+
+### TODO
+
+## Examples Without Django
+
+### Example Subscribing & Broadcasting
+```py
+from django_sockets.sockets import BaseSocketServer
+import asyncio, time
+
+DJANGO_SOCKETS_CONFIG = {
+    "hosts": [
+        {"address": f"redis://0.0.0.0:6379"}
+    ],
+}
+
+# Override the send method to print the data being sent
+# instead of sending it over a non existent websocket connection
+async def send(ws_data):
+    print("WS SENDING:", ws_data)
+
+
+# Create a receive queue to simulate receiving messages from a websocket client
+base_receive = asyncio.Queue()
+# Create a base socket server with a scope of {}
+base_socket_server = BaseSocketServer(scope={}, receive=base_receive.get, send=send, config=DJANGO_SOCKETS_CONFIG)
+# Start the listeners for the base socket server
+base_socket_server.start_listeners()
+# Subscribe to the test_channel
+base_socket_server.subscribe("test_channel")
+# Broadcast a message to the test_channel
+base_socket_server.broadcast("test_channel", "test message")
+# Give the async functions a small amount of time to complete
+time.sleep(.5)
+
+
+#=> Output:
+#=> WS SENDING: {'type': 'websocket.send', 'text': '"test message"'}
+```
+
+### Example Handle Websocket Messages
+```py
+from django_sockets.sockets import BaseSocketServer
+import asyncio, time
+
+DJANGO_SOCKETS_CONFIG = {
+    "hosts": [
+        {"address": f"redis://0.0.0.0:6379"}
+    ],
+}
+
+class CustomSocketServer(BaseSocketServer):
+    def receive(self, data):
+        """
+        When a data message is received from a websocket client:
+            - Print the data
+            - Broadcast the data to a channel (the same channel that the socket server is subscribed to)
+
+        Normally you would want to override the receive method to do any server side processing of the data that is received
+        then broadcast any changes back to relevant channels.
+        """
+        print("WS RECEIVED: ", data)
+        print(f"BROADCASTING TO '{self.scope['username']}'")
+        self.broadcast(self.scope['username'], data)
+
+    def connect(self):
+        """
+        When the websocket connects, subscribe to the channel of the user.
+
+        This is an important method to override if you want to subscribe to a channel when a user frist connects.
+
+        Otherwise, you can always subscribe to a channel based on the data that is received in the receive method.
+        """
+        print(f"CONNECTED")
+        print(f"SUSCRIBING TO '{self.scope['username']}'")
+        self.subscribe(self.scope['username'])
+
+# Override the send method to print the data being sent
+async def send(data):
+    """
+    Normally you would not override the send method, but since we are not actually sending data over a websocket connection
+    we are just going to print the data that would be sent.
+
+    This is useful for testing the socket server without having to actually send data over a websocket connection
+
+    Note: This only sends the first 64 characters of the data
+    """
+    print("WS SENDING:", str(data)[:64])
+
+# Create a receive queue to simulate receiving messages from a websocket client
+custom_receive = asyncio.Queue()
+# Create a custom socket server defined above with a scope of {'username':'adam'}, the custom_receive queue, and the send method defined above
+custom_socket_server = CustomSocketServer(scope={'username':'adam'}, receive=custom_receive.get, send=send)
+# Start the listeners for the custom socket server
+#    - Websocket Listener - Listens for websocket messages
+#    - Broadcast Listener - Listens for messages that were broadcasted to a channel that the socket server is subscribed to
+custom_socket_server.start_listeners()
+# Give the async functions a small amount of time to complete
+time.sleep(.1)
+# Simulate a WS connection request
+custom_receive.put_nowait({'type': 'websocket.connect'})
+# Give the async functions a small amount of time to complete
+time.sleep(.1)
+# Simulate a message being received from a WS client
+# This will call the receive method which is defined above
+custom_receive.put_nowait({'type': 'websocket.receive', 'text': '{"data": "test"}'})
+# Give the async functions a small amount of time to complete
+time.sleep(.1)
+# Simulate a WS disconnect request
+custom_receive.put_nowait({'type': 'websocket.disconnect'})
+# Give the async functions a small amount of time to complete
+time.sleep(.1)
+# Simulate a message being received from a WS client after the connection has been closed
+# This will not do anything since the connection has been closed and the listeners have been killed
+custom_receive.put_nowait({'type': 'websocket.receive', 'text': '{"data_after_close": "test"}'})
+# Give the async functions a small amount of time to complete
+time.sleep(.1)
+
+#=> Output:
+#=> WS SENDING: {'type': 'websocket.accept'}
+#=> CONNECTED
+#=> SUSCRIBING TO 'adam'
+#=> WS RECEIVED:  {'data': 'test'}
+#=> BROADCASTING TO 'adam'
+#=> WS SENDING: {'type': 'websocket.send', 'text': '{"data": "test"}'}
+
+```

django_sockets-1.0.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+django_sockets/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+django_sockets/broadcaster.py,sha256=rX7bGA1-TS1mCt2R0Nv66Ts7XKXvalV8kl2ula8fWQ4,3182
+django_sockets/middleware.py,sha256=2tOP0XoIEZ3towGxTzCK_5HW1oej4rmFdf5DJF99xLY,1309
+django_sockets/pubsub.py,sha256=mf_v7w8efnRxYQhFn7Df6w1jJllLZ7S_m30fRzIJzJg,12548
+django_sockets/sockets.py,sha256=D9GLivaSybjyPbsp9y0Mi7AWGbLsUMvKOtT4jK825vk,8367
+django_sockets/utils.py,sha256=mySD-fOwDuCUGmSZ19yhe6eGp9QhNbZCvDceBk9h7DY,7503
+django_sockets-1.0.0.dist-info/LICENSE,sha256=lWsmWo1t9v94zSBfnvvyFFVyAKworr9FQWvXDmk-Peo,1072
+django_sockets-1.0.0.dist-info/METADATA,sha256=k8E06XeHvS95NwqkdfjY9_6mdhsvKSw2N3HwyODMlss,6995
+django_sockets-1.0.0.dist-info/WHEEL,sha256=P9jw-gEje8ByB7_hXoICnHtVCrEwMQh-630tKvQWehc,91
+django_sockets-1.0.0.dist-info/top_level.txt,sha256=V4H73fZaPpKLIl3GqUGNQ-QW0lqv7B8NamEOJPh-ZCg,15
+django_sockets-1.0.0.dist-info/RECORD,,

django_sockets-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (75.3.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

django_sockets-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+django_sockets