rxdjango 0.0.2__tar.gz

rxdjango-0.0.2/LICENSE.md

@@ -0,0 +1,20 @@
+Copyright (c) 2022 Control Devices, Inc
+
+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.

rxdjango-0.0.2/PKG-INFO

@@ -0,0 +1,14 @@
+Metadata-Version: 2.1
+Name: rxdjango
+Version: 0.0.2
+Home-page: https://github.com/CDIGlobalTrack/rxdjango
+Author: Luis Fagundes
+Author-email: lhfagundes@gmail.com
+License: LICENSE.md
+Requires-Python: >=3.10
+License-File: LICENSE.md
+Requires-Dist: Django>=4.2
+Requires-Dist: motor>=3.3
+Requires-Dist: channels>=4
+Requires-Dist: channels-redis>=4.1
+Requires-Dist: djangorestframework>=3

rxdjango-0.0.2/README.md

@@ -0,0 +1,96 @@
+RX-Django
+=========
+
+RX-Django is a layer over Django Channels aimed to make it as simple as possible to broadcast
+changes in Django models to browsers through websockets, with minimal latency.
+
+It's evolving in production for more than 2 years now and it's revised API has just been released
+in Python Nordeste 2023. There's no stable release yet.
+
+Quickstart
+==========
+
+Start by defining a StateChannel and define an "anchor", which is a serializer that will build
+the state that will be sent to user.
+
+```python
+# chat/channels.py
+from rxdjango.channels import StateChannel
+from chat.serializers import ChatRoomSerializer
+
+
+class ChatRoomChannel(StateChannel):
+
+    class Meta:
+        anchor = ChatRoomSerializer()
+
+    def has_permission(self, user, chat_room):
+        # check permission
+        return True
+
+```
+
+Then define paths for the channels in websocket_urlpatterns.
+[Django Channels documentation](https://channels.readthedocs.io/en/latest/tutorial/part_2.html)
+suggests you put this in app/routing.py.
+
+```python
+# chat/routing.py
+from chat.channels import ChatRoomChannel
+
+websocket_urlpatterns = [
+    path('ws/chat/<str:room_name>/', ChatRoomChannel.as_asgi()),
+]
+```
+
+This is all the code it takes in the app! From that, RX-Django will generate all the frontend
+code required to keep state in sync between backend and frontend. For that, we need to configure
+settings.py with some information about the frontend.
+
+```python
+# settings.py
+
+RX_FRONTEND_DIR = os.path.join(BASE_DIR, '../frontend/src/app/modules')
+RX_WEBSOCKET_URL = "import.meta.env.VITE_SOCKET_URL"
+```
+
+In the above example, we want our code to be generated at src/app/modules, and we take the websocket url from Vite.
+Also, there are some backend configuration required. Right now, we only support Redis and Mongo for caching.
+
+```python
+# settings.py
+MONGO_URL = "configure me"
+REDIS_URL = "configure me"
+# for now framework expects this to exist, and to be set to True during tests
+TESTING = False
+```
+
+And, of course, add `rxdjango` to your INSTALLED_APPS
+
+```python
+# settings.py
+INSTALLED_APPS = [
+    # ...
+    'rxdjango',
+]
+```
+
+Build all the frontend files:
+
+```bash
+python manage.py makefrontend
+```
+
+Check the files generated inside your modules app. Now, use the state
+from the backend with:
+
+```typescript
+import { ChatRoomChannel } from 'app/modules/chat.channels';
+import { useChannelState } from 'django-react';
+
+channel = new ChatRoomChannel(roomName, token);
+chatState = useChannelState(channel);
+```
+
+That's all it takes! Note that token is a rest_framework.authtoken token,
+the only authentication method supported for now.

rxdjango-0.0.2/rxdjango/apps.py

@@ -0,0 +1,30 @@
+import importlib
+from django.apps import apps, AppConfig
+
+
+class ReactFrameworkConfig(AppConfig):
+    default_auto_field = 'django.db.models.BigAutoField'
+    name = 'rxdjango'
+
+    def ready(self):
+        """Discover and register StateChannel subclasses within Django apps."""
+        from . import channels
+
+        for app_config in apps.get_app_configs():
+            try:
+                # Attempt to import the channels.py module from the app
+                channels_module = importlib.import_module(f"{app_config.name}.channels")
+
+                # Check for subclasses of StateChannel in the module
+                for attr_name in dir(channels_module):
+                    attr = getattr(channels_module, attr_name)
+                    # Register the subclass in the global dictionary
+                    if not isinstance(attr, type) or \
+                       not issubclass(attr, channels.StateChannel) or \
+                       attr.Meta.abstract:
+                        continue
+                    attr._signal_handler.setup(app_config)
+
+            except ImportError:
+                # channels.py not found in the app, so just continue
+                pass

rxdjango-0.0.2/rxdjango/channels.py

@@ -0,0 +1,128 @@
+import json
+from collections import deque, namedtuple
+import pymongo
+from django.utils import timezone
+from hashlib import md5
+from asgiref.sync import async_to_sync
+from django.conf import settings
+from django.db import models, connection, transaction, ProgrammingError
+from rest_framework import serializers
+from backend.celery import app
+
+from .consumers import StateConsumer
+from .transaction import get_transaction_id
+from .state_model import StateModel
+from .websocket_router import WebsocketRouter
+from .signal_handler import SignalHandler
+
+
+class StateChannelMeta(type):
+    """Metaclass for the StateChannel.
+
+    Builds the state model based on the provided fields and Meta class,
+    and assigns a WebsocketRouter and a SignalHandler to it.
+    """
+
+    def __new__(cls, name, bases, attrs):
+        """Create and return a new class instance."""
+
+        # Create the new class as usual.
+        new_class = super().__new__(cls, name, bases, attrs)
+
+        if new_class.__module__ == cls.__module__:
+            return new_class
+
+        # Set the name to be used for mongo collection names and redis keys.
+        new_class.name = '_'.join([
+            new_class.__module__.replace('.channels', '').replace('.', '_'),
+            new_class.__name__.lower()
+        ])
+
+        # Ensure the Meta class and anchor serializer are provided.
+        meta = attrs.get("Meta")
+        if not meta:
+            raise ProgrammingError(
+                f'{new_class.__name__} must define a Meta class'
+            )
+
+        meta.abstract = getattr(meta, 'abstract', False)
+        if meta.abstract:
+            return new_class
+
+        if not hasattr(meta, "anchor"):
+            raise ProgrammingError(
+                f'{new_class.__name__} must define a Meta class with an '
+                'anchor serializer'
+            )
+
+        anchor = meta.anchor
+
+        if not isinstance(anchor, serializers.ModelSerializer):
+            raise ProgrammingError(
+                f'{new_class.__name__}.Meta.anchor must be an instance of '
+                'serializers.ModelSerializer'
+            )
+
+        # Attach the state model, websocket router, and signal handler.
+        new_class._state_model = StateModel(anchor)
+        new_class._wsrouter = WebsocketRouter(new_class.name)
+        new_class._signal_handler = SignalHandler(new_class)
+
+        return new_class
+
+
+class StateChannel(metaclass=StateChannelMeta):
+
+    class Meta:
+        abstract = True
+
+    @classmethod
+    def as_asgi(cls):
+        Consumer = type(
+            f'{cls.__name__}Consumer',
+            (StateConsumer,),
+            dict(
+                state_channel_class=cls,
+                wsrouter=cls._wsrouter,
+            ),
+        )
+
+        return Consumer.as_asgi()
+
+    def __init__(self, user, **kwargs):
+        self.kwargs = kwargs
+        self.user = user
+        self.user_id = user.id
+        self.anchor_id = self.get_anchor_id(**kwargs)
+
+    def get_anchor_id(self, **kwargs):
+        """Subclass may implement get_anchor_id, based on url parameters,
+        otherwise the first parameter will be assumed to be it"""
+        return next(iter(kwargs.values()))
+
+    @staticmethod
+    def has_permission(user, **kwargs):
+        """Implement this method to check if user has permission on a channel"""
+        return True
+
+    async def on_connect(self, tstamp):
+        """Called after user has been authenticated.
+        tstamp is the tstamp sent on connection, if this is a reconnection"""
+        pass
+
+    async def on_disconnect(self):
+        """Called when user disconnects"""
+        pass
+
+    async def receive(self, data):
+        """Any data sent by user will get here"""
+        pass
+
+    @classmethod
+    def broadcast_instance(cls, anchor_id, instance, operation='update'):
+        cls._signal_handler.broadcast_instance(anchor_id, instance, operation)
+
+    @classmethod
+    def broadcast_notification(cls, anchor_id, notification, user_id=None):
+        notification['_instance_type'] = '_notification'
+        cls._wsrouter.sync_dispatch([notification], anchor_id, user_id)

rxdjango-0.0.2/rxdjango/consumers.py

@@ -0,0 +1,138 @@
+import json
+from datetime import datetime
+from pytz import utc
+from django.utils import timezone
+from django.db import models
+from django.db.models.query import QuerySet
+from asgiref.sync import sync_to_async, async_to_sync
+from channels.db import database_sync_to_async
+from channels.generic.websocket import AsyncWebsocketConsumer
+from rest_framework.authtoken.models import Token
+from .state_loader import StateLoader
+
+
+class StateConsumer(AsyncWebsocketConsumer):
+    """
+    WebSocket consumer that manages user authentication, session management,
+    and real-time data relay to clients. A subclass of StateConsumer will be
+    dinamically created by StateChannel.as_asgi().
+    """
+    def __init__(self, *args, **kwargs):
+
+        super().__init__(*args, **kwargs)
+
+        self.channel = None
+        self.user = None
+        self.token = None
+        self.anchor_id = None
+        self.wsrouter = None
+        self.tstamp = None
+        self.session = None
+
+    async def connect(self):
+        """Accept any connection and just wait for a token."""
+        await self.accept()
+
+    async def receive(self, text_data):
+        if self.user:
+            await self.receive_command(text_data)
+        else:
+            await self.receive_authentication(text_data)
+
+    async def receive_authentication(self, text_data):
+        # If user is not logged, we expect a text with
+        # token and maybe last_update
+        data = json.loads(text_data)
+        token = data.get('token', None)
+        last_update  = data.get('last_update', None)
+
+        user = await self.authenticate(token=token)
+        if user:
+            await self.start(user, last_update)
+        else:
+            await self.close()
+
+    async def start(self, user, tstamp):
+        kwargs = self.scope['url_route']['kwargs']
+        self.user = user
+        self.channel = self.state_channel_class(user, **kwargs)
+        self.user_id = self.user.id
+        self.anchor_id = self.channel.anchor_id
+        self.wsrouter = self.channel._wsrouter
+
+        await self.wsrouter.connect(
+            self.channel_layer,
+            self.channel_name,
+            self.anchor_id,
+            self.user_id,
+        )
+
+        async with StateLoader(self.channel) as loader:
+            await self.channel.on_connect(tstamp)
+
+            async for instances in loader.list_instances():
+                if instances:
+                    data = json.dumps(instances, default=str)
+                    await self.send(text_data=data)
+
+            self.tstamp = loader.tstamp
+            await self.send(text_data=self.end_of_data)
+
+    @property
+    def end_of_data(self):
+        return json.dumps([{
+            '_instance_type': '',
+            '_tstamp': self.tstamp,
+            '_operation': 'end_initial_state',
+            'id': 0,
+        }])
+
+    @database_sync_to_async
+    def serialized_data(self, Serializer, data):
+        return Serializer(data).data
+
+    async def disconnect(self, close_code=None):
+        if not self.channel:
+            return
+
+        await self.wsrouter.disconnect(
+            self.channel_layer,
+            self.channel_name,
+            self.anchor_id,
+            self.user_id,
+        )
+
+        await self.channel.on_disconnect()
+
+    @database_sync_to_async
+    def authenticate(self, token):
+        try:
+            token = Token.objects.get(key=token)
+        except Token.DoesNotExist:
+            #self.send('ERROR/Unauthorized')
+            return
+        self.token = token.key
+
+        kwargs = self.scope['url_route']['kwargs']
+        if not self.state_channel_class.has_permission(
+                token.user,
+                **kwargs,
+        ):
+            #self.send('ERROR/Forbidden')
+            return
+
+        #self.send('OK')
+
+        return token.user
+
+    async def relay(self, payload):
+        payload = payload['payload']
+        await self.send(text_data=json.dumps(payload, default=str))
+
+    async def receive_command(self, text_data):
+        # If user is logged, we expect a JSON command
+        try:
+            data = json.loads(text_data)
+        except json.JSONDecodeError:
+            await self.disconnect()
+        await self.channel.receive(data)

rxdjango-0.0.2/rxdjango/decorators.py

@@ -0,0 +1 @@
+from .related_properties import RelatedProperty as related_property

rxdjango-0.0.2/rxdjango/exceptions.py

@@ -0,0 +1,5 @@
+class UnknownProperty(Exception):
+    pass
+
+class AnchorDoesNotExist(Exception):
+    pass

rxdjango-0.0.2/rxdjango/management/commands/makefrontend.py

@@ -0,0 +1,33 @@
+from django.apps import apps
+from django.db import ProgrammingError
+from django.core.management.base import BaseCommand
+from django.conf import settings
+from rxdjango.ts.interfaces import create_app_interfaces
+from rxdjango.ts.channels import create_app_channels
+
+
+class Command(BaseCommand):
+    help = 'Generate typescript interfaces and classes'
+
+    def add_arguments(self, parser):
+        parser.add_argument('app', nargs='*', type=str)
+
+    def handle(self, *args, **options):
+        self._check()
+
+        all_apps = options['app']
+
+        if not all_apps:
+            models = apps.get_models()
+            all_apps = list(set([ x.__module__.split('.')[0] for x in models]))
+
+        for app in all_apps:
+            create_app_interfaces(app)
+            create_app_channels(app)
+
+    def _check(self):
+        if not getattr(settings, 'RX_FRONTEND_DIR', None):
+            raise ProgrammingError(
+                "settings.RX_FRONTEND_DIR is not set. Configure it with a folder "
+                "inside your react application."
+            )

rxdjango-0.0.2/rxdjango/mongo.py

@@ -0,0 +1,122 @@
+import json
+from datetime import datetime
+from copy import copy
+from decimal import Decimal
+import pymongo
+from motor import motor_asyncio
+from django.db import ProgrammingError
+from django.conf import settings
+from .redis import get_tstamp, sync_get_tstamp
+
+
+class MongoStateSession:
+
+    def __init__(self, channel):
+        self.channel = channel
+        self.anchor_id = channel.anchor_id
+        self.user_id = channel.user_id
+        self.state_model = channel._state_model
+        self._tstamp = None
+
+        client = motor_asyncio.AsyncIOMotorClient(settings.MONGO_URL)
+        db = client[settings.MONGO_STATE_DB]
+        self.collection = db[channel.__class__.__name__.lower()]
+
+    async def tstamp(self):
+        if self._tstamp:
+            return self._tstamp
+        self._tstamp = await get_tstamp()
+        return self._tstamp
+
+    async def list_instances(self, user_id):
+        for model in self.state_model.models():
+            instances = []
+            query = {
+                '_anchor_id': self.anchor_id,
+                '_user_key': {'$in': [None, user_id]},
+                '_instance_type': model.instance_type,
+            }
+
+            async for instance in self.collection.find(query):
+                del instance['_id']
+                del instance['_anchor_id']
+                instances.append(instance)
+
+            if instances:
+                yield instances
+                instances = []
+
+    async def write_instances(self, instances):
+        for instance in instances:
+            instance = _adapt(instance)
+            instance['_anchor_id'] = self.anchor_id
+            instance_type = instance['_instance_type']
+            if instance.get('id', None) is None:
+                raise ProgrammingError(f'Instance type {instance_type} has no "id"')
+            instance = _adapt(instance)
+            await self.collection.replace_one(
+                {
+                    '_anchor_id': self.anchor_id,
+                    '_instance_type': instance['_instance_type'],
+                    'id': instance['id'],
+                },
+                instance,
+                upsert=True,
+            )
+
+
+class MongoSignalWriter:
+    def __init__(self, channel_class):
+        client = pymongo.MongoClient(settings.MONGO_URL)
+        db = client[settings.MONGO_STATE_DB]
+        self.collection = db[channel_class.__name__.lower()]
+
+    def init_database(self):
+        # Make a new connection, because this needs to be sync
+        self.collection.drop()
+
+        self.collection.create_index(
+            [
+                ('_anchor_id', pymongo.ASCENDING),
+                ('_user_key', pymongo.ASCENDING),
+                ('_instance_type', pymongo.ASCENDING),
+                ('id', pymongo.ASCENDING),
+            ],
+            name='instance_pkey',
+        )
+
+        self.collection.create_index(
+            [
+                ('_anchor_id', pymongo.ASCENDING),
+                ('_tstamp', pymongo.DESCENDING),
+            ],
+            name='reconnection_index',
+        )
+
+    def write_instances(self, anchor_id, instances):
+        for instance in instances:
+            instance = _adapt(instance)
+            instance['_anchor_id'] = anchor_id
+            assert instance['_tstamp']
+            self.collection.replace_one(
+                {
+                    '_anchor_id': anchor_id,
+                    '_instance_type': instance['_instance_type'],
+                    'id': instance['id'],
+                },
+                instance,
+                upsert=True,
+            )
+            pass
+
+
+def _adapt(instance):
+    adapted = {}
+    for key, value in instance.items():
+        if isinstance(value, Decimal):
+            value = float(value)
+        elif isinstance(value, datetime):
+            value = value.isoformat()[:26] + 'Z'
+        adapted[key] = value
+
+    return adapted