django-pulse 1.0.0__py3-none-any.whl

django-pulse/__init__.py

@@ -0,0 +1 @@
+default_app_config = 'django_pulse.apps.DjangoPulseConfig'

django-pulse/apps.py

@@ -0,0 +1,8 @@
+from django.apps import AppConfig
+
+class DjangoPulseConfig(AppConfig):
+    default_auto_field = 'django.db.models.BigAutoField'
+    name = 'django_pulse'
+
+    def ready(self):
+        import django_pulse.signals

django-pulse/consumers.py

@@ -0,0 +1,155 @@
+import json
+from channels.generic.websocket import AsyncWebsocketConsumer
+from asgiref.sync import sync_to_async
+from django.apps import apps
+from django.db import transaction
+class SyncConsumer(AsyncWebsocketConsumer):
+
+    def get_model_by_name(self, table_name):
+        for config in apps.get_app_configs():
+            try:
+                return apps.get_model(config.label, table_name)
+            except LookupError:
+                continue
+        return None
+
+    async def connect(self):
+
+        self.user = self.scope["user"]
+        
+        if self.user.is_authenticated:
+            self.group_name = f"user_{self.user.id}_sync"
+            
+            # Unirse al grupo privado del usuario en Redis
+            await self.channel_layer.group_add(
+                self.group_name,
+                self.channel_name
+            )
+            await self.accept()
+        else:
+            await self.close()
+
+    async def disconnect(self, close_code):
+        if hasattr(self, 'group_name'):
+            await self.channel_layer.group_discard(
+                self.group_name,
+                self.channel_name
+            )
+
+    # Este método se activa cuando la Signal envía algo a Redis
+    async def sync_message(self, event):
+        # Enviar el paquete de datos al móvil
+
+        await self.send(text_data=json.dumps({
+            "type": "SYNC_UPDATE",
+            "data": event["payload"]
+        }))
+
+    async def receive(self, text_data):
+        data = json.loads(text_data)
+        msg_type = data.get('type')
+
+        if msg_type == 'SYNC_BATCH_UPLOAD':
+            await self.handle_batch_upload(data)
+        elif msg_type == 'SYNC_UPLOAD':
+            await self.handle_upload(data)
+        elif msg_type == 'SYNC_REQUEST_DELTA':
+            await self.handle_delta_request(data)
+
+    async def handle_delta_request(self, data):
+        table_name = data.get('table')
+        last_version = data.get('last_version', 0)
+        model = self.get_model_by_name(table_name)
+        
+        if model:
+            @sync_to_async
+            def get_updates():
+               # Filtramos por versión y opcionalmente por usuario
+                qs = model.objects.filter(version__gt=last_version)
+                if hasattr(model, 'user_id'):
+                    qs = qs.filter(user_id=self.user.id)
+                
+                return [
+                    {
+                        "model": table_name,
+                        "sync_id": str(obj.sync_id),
+                        "version": obj.version,
+                        "data": obj.to_dict() 
+                    } for obj in qs
+                ]
+            
+            changes = await get_updates()
+            for change in changes:
+                await self.send(text_data=json.dumps({
+                    "type": "SYNC_UPDATE",
+                    "data": change
+                }))
+
+    async def handle_upload(self, data):
+        table_name = data.get('table')
+        payload = data.get('payload')
+        model = self.get_model_by_name(table_name)
+        if not model: return
+
+        @sync_to_async
+        def process_individual():
+            sync_id = payload.get('sync_id')
+            client_version = payload.get('version', 0)
+            
+            current_obj = model.objects.filter(sync_id=sync_id).first()
+            if current_obj and client_version < current_obj.version:
+                return {"status": "CONFLICT", "sync_id": sync_id}
+
+            # manejo de errores (NACK)
+            try:
+                exclude = ['id', 'version', 'is_local_only']
+                clean_data = {k: v for k, v in payload.items() if k not in exclude}
+                if 'is_deleted' in clean_data:
+                    clean_data['is_deleted'] = bool(clean_data['is_deleted'])
+
+                model.objects.update_or_create(sync_id=sync_id, defaults=clean_data)
+                return {"status": "SUCCESS", "sync_id": sync_id}
+            except Exception as e:
+                return {"status": "ERROR", "sync_id": sync_id, "error": str(e)}
+
+        result = await process_individual()
+        await self.send(text_data=json.dumps({
+            "type": "SYNC_ACK_INDIVIDUAL",
+            "table": table_name,
+            **result
+        }))
+
+    async def handle_batch_upload(self, data):
+        table_name = data.get('table')
+        payloads = data.get('payloads', [])
+        model = self.get_model_by_name(table_name)
+        if not model: return
+
+        @sync_to_async
+        def process_atomic_batch():
+            results = {"synced_ids": [], "conflicts": [], "errors": []}
+            with transaction.atomic():
+                for item in payloads:
+                    s_id = item.get('sync_id')
+                    c_ver = item.get('version', 0)
+                    
+                    curr = model.objects.filter(sync_id=s_id).first()
+                    if curr and c_ver < curr.version:
+                        results["conflicts"].append(s_id)
+                        continue
+
+                    try:
+                        exclude = ['id', 'version', 'is_local_only']
+                        clean = {k: v for k, v in item.items() if k not in exclude}
+                        model.objects.update_or_create(sync_id=s_id, defaults=clean)
+                        results["synced_ids"].append(s_id)
+                    except Exception as e:
+                        results["errors"].append({"id": s_id, "msg": str(e)})
+            return results
+
+        res = await process_atomic_batch()
+        await self.send(text_data=json.dumps({
+            "type": "BATCH_ACK",
+            "table": table_name,
+            **res
+        }))

django-pulse/init.py

@@ -0,0 +1 @@
+default_app_config = 'django_pulse.apps.DjangoPulseConfig'

django-pulse/models.py

@@ -0,0 +1,97 @@
+from django.contrib.contenttypes.fields import GenericForeignKey
+from django.contrib.contenttypes.models import ContentType
+from django.db import models
+import uuid
+
+class GlobalSyncSequence(models.Model):
+    last_version = models.BigIntegerField(default=0)
+    
+    @classmethod
+    def get_next_version(cls):
+        # Usamos select_for_update para bloquear la fila y evitar que 
+        # dos procesos tomen el mismo número al mismo tiempo (Race Condition)
+        from django.db import transaction
+        with transaction.atomic():
+            seq, created = cls.objects.select_for_update().get_or_create(id=1)
+            seq.last_version += 1
+            seq.save()
+            return seq.last_version
+
+class SyncModel(models.Model):
+    # uid para evitar colisiones entre movil y servidor.
+    sync_id = models.UUIDField(default=uuid.uuid4, editable=False, unique=True)
+    version = models.BigIntegerField(default=0)
+    updated_at = models.DateTimeField(auto_now=True)
+    is_deleted = models.BooleanField(default=False) 
+    user_id = models.IntegerField(db_index=True, null=True, blank=True)
+
+    class Meta:
+        abstract = True
+
+    def get_sync_groups(self):
+        """
+        Lógica por defecto: 
+        1. Si el modelo tiene un campo 'user', enviar a ese usuario.
+        2. Si no, enviar al grupo 'global'.
+        """
+        if hasattr(self, 'user_id') and self.user_id:
+            return [f"user_{self.user_id}"]
+        return ["global"]
+
+    
+    def soft_delete(self):
+        self.is_deleted = True
+
+        next_v = GlobalSyncSequence.get_next_version()
+        self.version = next_v
+        self.save()
+
+    def to_dict(self):
+        from django.forms.models import model_to_dict
+        data = model_to_dict(self)
+        data['sync_id'] = str(self.sync_id)
+        if 'updated_at' in data:
+            data['updated_at'] = self.updated_at.isoformat()
+        return data
+
+    def serialize_model(self, obj):
+        if hasattr(obj, 'to_dict'):
+            return obj.to_dict()
+        from django.forms.models import model_to_dict
+        return model_to_dict(obj)
+
+    def __str__(self):
+        return f"{self.sync_id}"
+
+class SyncLog(models.Model):
+    # Apuntador genérico a cualquier objeto
+    content_type = models.ForeignKey(ContentType, on_delete=models.CASCADE)
+    object_id = models.UUIDField() 
+    content_object = GenericForeignKey('content_type', 'object_id')
+    
+    action = models.CharField(max_length=10, choices=[
+        ('CREATE', 'Create'),
+        ('UPDATE', 'Update'),
+        ('DELETE', 'Delete'),
+    ])
+    version = models.BigIntegerField()
+    timestamp = models.DateTimeField(auto_now_add=True)
+    
+    # Para la "Sincronización Selectiva" que hablamos
+    user_id = models.IntegerField(db_index=True)
+
+
+class Item(SyncModel):
+    name = models.CharField(max_length=255)
+    description = models.TextField(blank=True)
+    created_at = models.DateTimeField(auto_now_add=True)
+
+    class Meta:
+        ordering = ['-created_at']
+        indexes = [
+            models.Index(fields=['name']),
+        ]
+
+    def __str__(self):
+        return self.name
+

django-pulse/routing.py

@@ -0,0 +1,6 @@
+from django.urls import re_path
+from .consumers import SyncConsumer
+
+websocket_urlpatterns = [
+    re_path(r'ws/pulse/sync/$', SyncConsumer.as_asgi()),
+]

django-pulse/signals.py

@@ -0,0 +1,61 @@
+from django.db.models.signals import post_save, post_delete
+from django.dispatch import receiver
+from .models import SyncModel, GlobalSyncSequence, SyncLog
+from channels.layers import get_channel_layer
+from asgiref.sync import async_to_sync
+from django.forms.models import model_to_dict
+
+@receiver(post_save)
+def auto_track_sync_models(sender, instance, created, **kwargs):
+    if not isinstance(instance, SyncModel):
+        return
+
+    next_v = GlobalSyncSequence.get_next_version()
+    sender.objects.filter(pk=instance.pk).update(version=next_v)
+    instance.version = next_v # Actualiza el objeto en memoria antes de serializar
+
+    SyncLog.objects.create(
+        content_object=instance,
+        action='CREATE' if created else 'UPDATE',
+        version=next_v,
+        user_id=getattr(instance, 'user_id', None) # Intenta obtener user_id si existe
+    )
+
+    channel_layer = get_channel_layer()
+    
+    groups = instance.get_sync_groups()
+    for group in groups:
+        async_to_sync(channel_layer.group_send)(
+            f"{group}_sync",
+            {
+                "type": "sync.message",
+                "payload": {
+                    "model": sender.__name__.lower(),
+                    "sync_id": str(instance.sync_id),
+                    "version": next_v,
+                    "data": model_to_dict(instance)
+                }
+            }
+        )
+
+@receiver(post_delete)
+def handle_hard_delete(sender, instance, **kwargs):
+    if not isinstance(instance, SyncModel):
+        return
+
+    channel_layer = get_channel_layer()
+    
+    groups = instance.get_sync_groups()
+    
+    for group in groups:
+        async_to_sync(channel_layer.group_send)(
+            f"{group}_sync",
+            {
+                "type": "sync.message",
+                "payload": {
+                    "type": "HARD_DELETE",
+                    "model": sender.__name__.lower(),
+                    "sync_id": str(instance.sync_id),
+                }
+            }
+        )

django_pulse-1.0.0.dist-info/METADATA

@@ -0,0 +1,160 @@
+Metadata-Version: 2.4
+Name: django-pulse
+Version: 1.0.0
+Summary: Backend sync engine for pulse-rn
+Home-page: https://github.com/JesusM15/django-pulse
+Author: Jesus M.
+Classifier: Framework :: Django
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: django>=3.2
+Requires-Dist: channels>=3.0
+Requires-Dist: channels-redis>=3.0
+Requires-Dist: asgiref>=3.3
+Dynamic: author
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: license-file
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+# Django Pulse
+
+Backend engine for the `pulse-rn` React Native library.
+
+## Quick Start
+
+1. Install: `pip install django-pulse`
+2. Add to `INSTALLED_APPS`:
+   ```python
+   INSTALLED_APPS = [
+       ...,
+       'channels',
+       'django_pulse',
+   ]
+   ```
+
+## Model Inheritance
+
+To enable synchronization for your models, inherit from `SyncModel` instead of `models.Model`:
+
+```python
+from django_pulse.models import SyncModel
+from django.db import models
+
+class Task(SyncModel):
+    title = models.CharField(max_length=200)
+    description = models.TextField(blank=True)
+    completed = models.BooleanField(default=False)
+    user = models.ForeignKey(User, on_delete=models.CASCADE, null=True, blank=True)
+
+class Item(SyncModel):
+    name = models.CharField(max_length=255)
+    description = models.TextField(blank=True)
+    price = models.DecimalField(max_digits=10, decimal_places=2)
+```
+
+### SyncModel Features
+
+When you inherit from `SyncModel`, your models automatically get these fields:
+
+| Field | Type | Description |
+|--------|------|-------------|
+| `sync_id` | UUIDField | Unique identifier for synchronization |
+| `version` | PositiveIntegerField | Version number for conflict resolution |
+| `is_local_only` | BooleanField | Marks records pending sync |
+| `sync_error` | TextField | Stores sync error messages |
+| `created_at` | DateTimeField | Auto-created timestamp |
+| `updated_at` | DateTimeField | Auto-updated timestamp |
+
+### Automatic Synchronization
+
+All models inheriting from `SyncModel` will:
+
+- Automatically generate UUID `sync_id` on creation
+- Increment `version` on each update
+- Track synchronization status with `is_local_only`
+- Log synchronization errors in `sync_error`
+- Participate in real-time WebSocket updates
+
+### User-Specific Sync
+
+If your model has a `user` field (ForeignKey to User), synchronization will be scoped to that user:
+
+```python
+class Task(SyncModel):
+    title = models.CharField(max_length=200)
+    user = models.ForeignKey(User, on_delete=models.CASCADE)  # User-specific sync
+```
+
+Models without a `user` field will sync globally to all connected clients.
+
+## WebSocket Configuration
+
+Add the WebSocket routing to your `asgi.py`:
+
+```python
+from django_pulse.routing import websocket_urlpatterns
+
+application = ProtocolTypeRouter({
+    "http": get_asgi_application(),
+    "websocket": URLRouter(
+        websocket_urlpatterns
+    ),
+})
+```
+
+## Required Settings
+
+Ensure these settings are configured in your `settings.py`:
+
+```python
+# Channels configuration
+ASGI_APPLICATION = 'your_project.asgi.application'
+
+CHANNEL_LAYERS = {
+    'default': {
+        'BACKEND': 'channels_redis.core.RedisChannelLayer',
+        'CONFIG': {
+            'hosts': [('127.0.0.1', 6379)],
+        },
+    },
+}
+```
+
+## API Endpoints
+
+The library automatically creates these WebSocket endpoints:
+
+- `ws://localhost:8000/ws/pulse/sync/` - Main synchronization endpoint
+
+## Synchronization Flow
+
+1. **Client Connects**: WebSocket connection established
+2. **Delta Sync Request**: Client requests changes since last version
+3. **Batch Upload**: Client uploads pending local changes
+4. **Real-time Updates**: Server pushes changes to connected clients
+5. **Conflict Resolution**: Server resolves version conflicts
+
+## Example Usage
+
+```python
+# Create a synced task
+task = Task.objects.create(
+    title="Complete project",
+    description="Finish Django Pulse library",
+    user=request.user
+)
+
+# Update with automatic version increment
+task.title = "Updated project title"
+task.save()  # Automatically increments version
+
+# All changes are automatically synced to connected mobile clients

django_pulse-1.0.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+django-pulse/__init__.py,sha256=Nu0arJdJ2C7IbTAX6D0_A-AIv64MdgzjS3mjT5KS_xE,58
+django-pulse/apps.py,sha256=nM5HUN2yQQVO0foV2AfIr7sKpNBFF9HlWeJUD_tDNXc,218
+django-pulse/consumers.py,sha256=mID9x74rRLCV7tDhJxCZOMpCAcxclqhcUKutJYVFxdc,5821
+django-pulse/init.py,sha256=Nu0arJdJ2C7IbTAX6D0_A-AIv64MdgzjS3mjT5KS_xE,58
+django-pulse/models.py,sha256=T4VVo9qmP1_4rcf7K09HE4wA-6vNLGJI2ea5O7rPy9A,3223
+django-pulse/routing.py,sha256=FcDpU0c-vmhLF_IFfwtkGgD0v5VhnUCbgsyM_jMiZPw,158
+django-pulse/signals.py,sha256=RC9MQoK1VuJRs2w6woULNkiil4EJLqBrCw3hOWmN3Yc,2039
+django_pulse-1.0.0.dist-info/licenses/LICENSE,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+django_pulse-1.0.0.dist-info/METADATA,sha256=AfKwML_CWTshBFOfcBUd0Ei6CjTKnNrbRukz6eqVu1o,4535
+django_pulse-1.0.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+django_pulse-1.0.0.dist-info/top_level.txt,sha256=9lVNFVg9jMWxBHZa1eCGi5DQZCUQLNy4zAe_K9Pkoo0,13
+django_pulse-1.0.0.dist-info/RECORD,,

django_pulse-1.0.0.dist-info/WHEEL

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

django_pulse-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+django-pulse