django-qstash 0.0.1__py3-none-any.whl → 0.0.3__py3-none-any.whl

django_qstash/__init__.py

@@ -1,4 +1,6 @@
-__version__ = "0.1.0"
+from __future__ import annotations
+
+__version__ = "0.0.3"
 
 from .tasks import shared_task
 

django_qstash/exceptions.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+
+class WebhookError(Exception):
+    """Base exception for webhook handling errors."""
+
+    pass
+
+
+class SignatureError(WebhookError):
+    """Invalid or missing signature."""
+
+    pass
+
+
+class PayloadError(WebhookError):
+    """Invalid payload structure or content."""
+
+    pass
+
+
+class TaskError(WebhookError):
+    """Error in task execution."""
+
+    pass

django_qstash/handlers.py

@@ -0,0 +1,143 @@
+from __future__ import annotations
+
+import json
+import logging
+from dataclasses import dataclass
+from typing import Any
+
+from django.conf import settings
+from django.http import HttpRequest
+from qstash import Receiver
+
+from . import utils
+from .exceptions import PayloadError
+from .exceptions import SignatureError
+from .exceptions import TaskError
+from .results.services import store_task_result
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class TaskPayload:
+    function: str
+    module: str
+    args: list
+    kwargs: dict
+    task_name: str
+    function_path: str
+
+    @classmethod
+    def from_dict(cls, data: dict) -> TaskPayload:
+        """Create TaskPayload from dictionary."""
+        is_valid, error = utils.validate_task_payload(data)
+        if not is_valid:
+            raise PayloadError(error)
+
+        function_path = f"{data['module']}.{data['function']}"
+        return cls(
+            function=data["function"],
+            module=data["module"],
+            args=data["args"],
+            kwargs=data["kwargs"],
+            task_name=data.get("task_name", function_path),
+            function_path=function_path,
+        )
+
+
+class QStashWebhook:
+    def __init__(self):
+        self.receiver = Receiver(
+            current_signing_key=settings.QSTASH_CURRENT_SIGNING_KEY,
+            next_signing_key=settings.QSTASH_NEXT_SIGNING_KEY,
+        )
+        self.force_https = getattr(settings, "DJANGO_QSTASH_FORCE_HTTPS", True)
+
+    def verify_signature(self, body: str, signature: str, url: str) -> None:
+        """Verify QStash signature."""
+        if not signature:
+            raise SignatureError("Missing Upstash-Signature header")
+
+        if self.force_https and not url.startswith("https://"):
+            url = url.replace("http://", "https://")
+
+        try:
+            self.receiver.verify(body=body, signature=signature, url=url)
+        except Exception as e:
+            raise SignatureError(f"Invalid signature: {e}")
+
+    def parse_payload(self, body: str) -> TaskPayload:
+        """Parse and validate webhook payload."""
+        try:
+            data = json.loads(body)
+            return TaskPayload.from_dict(data)
+        except json.JSONDecodeError as e:
+            raise PayloadError(f"Invalid JSON payload: {e}")
+
+    def execute_task(self, payload: TaskPayload) -> Any:
+        """Import and execute the task function."""
+        try:
+            task_func = utils.import_string(payload.function_path)
+        except ImportError as e:
+            raise TaskError(f"Could not import task function: {e}")
+
+        try:
+            if callable(task_func) and hasattr(task_func, "actual_func"):
+                return task_func.actual_func(*payload.args, **payload.kwargs)
+            return task_func(*payload.args, **payload.kwargs)
+        except Exception as e:
+            raise TaskError(f"Task execution failed: {e}")
+
+    def handle_request(self, request: HttpRequest) -> tuple[dict, int]:
+        """Process webhook request and return response data and status code."""
+        payload = None  # Initialize payload as None
+        try:
+            body = request.body.decode()
+            self.verify_signature(
+                body=body,
+                signature=request.headers.get("Upstash-Signature"),
+                url=request.build_absolute_uri(),
+            )
+
+            payload = self.parse_payload(body)
+            result = self.execute_task(payload)
+
+            store_task_result(
+                task_id=request.headers.get("Upstash-Message-Id"),
+                task_name=payload.task_name,
+                status="SUCCESS",
+                result=result,
+                args=payload.args,
+                kwargs=payload.kwargs,
+            )
+
+            return {
+                "status": "success",
+                "task_name": payload.task_name,
+                "result": result if result is not None else "null",
+            }, 200
+
+        except (SignatureError, PayloadError) as e:
+            logger.exception("Authentication error: %s", str(e))
+            return {
+                "status": "error",
+                "error_type": e.__class__.__name__,
+                "error": str(e),
+                "task_name": getattr(payload, "task_name", None),
+            }, 400
+        except TaskError as e:
+            logger.exception("Task execution error: %s", str(e))
+            return {
+                "status": "error",
+                "error_type": e.__class__.__name__,
+                "error": str(e),
+                "task_name": payload.task_name if payload else None,
+            }, 500
+        except Exception as e:
+            logger.exception("Unexpected error in webhook handler: %s", str(e))
+            return {
+                "status": "error",
+                "error_type": "InternalServerError",
+                "error": "An unexpected error occurred",
+                "task_name": getattr(payload, "task_name", None),
+            }, 500

django_qstash/management/commands/clear_stale_results.py

@@ -0,0 +1,61 @@
+from __future__ import annotations
+
+from datetime import timedelta
+
+from django.apps import apps
+from django.conf import settings
+from django.core.management.base import BaseCommand
+from django.utils import timezone
+
+DJANGO_QSTASH_RESULT_TTL = getattr(settings, "DJANGO_QSTASH_RESULT_TTL", 604800)
+
+
+class Command(BaseCommand):
+    help = f"""Clears stale task results older than\n
+    {DJANGO_QSTASH_RESULT_TTL} seconds (settings.DJANGO_QSTASH_RESULT_TTL)"""
+
+    def add_arguments(self, parser):
+        parser.add_argument(
+            "--no-input",
+            action="store_true",
+            help="Do not ask for confirmation",
+        )
+        parser.add_argument(
+            "--since",
+            type=int,
+            help="The number of seconds ago to clear results for",
+        )
+
+    def handle(self, *args, **options):
+        no_input = options["no_input"]
+        since = options.get("since") or DJANGO_QSTASH_RESULT_TTL
+        cutoff_date = timezone.now() - timedelta(seconds=since)
+        try:
+            TaskResult = apps.get_model("django_qstash_results", "TaskResult")
+        except LookupError:
+            self.stdout.write(
+                self.style.ERROR(
+                    "Django QStash Results not installed.\nAdd `django_qstash.results` to INSTALLED_APPS and run migrations."
+                )
+            )
+            return
+        to_delete = TaskResult.objects.filter(date_done__lt=cutoff_date)
+
+        if not to_delete.exists():
+            self.stdout.write("No stale Django QStash task results found")
+            return
+
+        # use input to confirm  deletion
+        self.stdout.write(
+            f"Deleting {to_delete.count()} task results older than {cutoff_date} ({DJANGO_QSTASH_RESULT_TTL} seconds)"
+        )
+        if not no_input:
+            if input("Are you sure? (y/n): ") != "y":
+                self.stdout.write("Skipping deletion")
+                return
+
+        deleted_count, _ = to_delete.delete()
+
+        self.stdout.write(
+            self.style.SUCCESS(f"Successfully deleted {deleted_count} stale results.")
+        )

django_qstash/results/admin.py

@@ -0,0 +1,21 @@
+from __future__ import annotations
+
+from django.contrib import admin
+
+from .models import TaskResult
+
+
+@admin.register(TaskResult)
+class TaskResultAdmin(admin.ModelAdmin):
+    readonly_fields = [
+        "task_name",
+        "status",
+        "date_done",
+        "result",
+        "traceback",
+        "args",
+        "kwargs",
+        "task_id",
+        "date_created",
+    ]
+    list_display = ["task_name", "status", "date_done"]

django_qstash/results/apps.py

@@ -0,0 +1,10 @@
+from __future__ import annotations
+
+from django.apps import AppConfig
+
+
+class ResultsConfig(AppConfig):
+    name = "django_qstash.results"
+    label = "django_qstash_results"
+    verbose_name = "django_qstash_results"
+    default_auto_field = "django.db.models.BigAutoField"

django_qstash/results/migrations/0001_initial.py

@@ -0,0 +1,62 @@
+# Generated by Django 5.1.4 on 2024-12-30 23:31
+
+from __future__ import annotations
+
+import uuid
+
+import django.utils.timezone
+from django.db import migrations
+from django.db import models
+
+
+class Migration(migrations.Migration):
+    initial = True
+
+    dependencies = []
+
+    operations = [
+        migrations.CreateModel(
+            name="TaskResult",
+            fields=[
+                (
+                    "id",
+                    models.UUIDField(
+                        default=uuid.uuid1,
+                        editable=False,
+                        primary_key=True,
+                        serialize=False,
+                        unique=True,
+                    ),
+                ),
+                (
+                    "task_id",
+                    models.CharField(db_index=True, max_length=255, unique=True),
+                ),
+                ("task_name", models.CharField(max_length=255)),
+                (
+                    "status",
+                    models.CharField(
+                        choices=[
+                            ("PENDING", "Pending"),
+                            ("SUCCESS", "Success"),
+                            ("FAILURE", "Failure"),
+                        ],
+                        default="PENDING",
+                        max_length=50,
+                    ),
+                ),
+                (
+                    "date_created",
+                    models.DateTimeField(default=django.utils.timezone.now),
+                ),
+                ("date_done", models.DateTimeField(null=True)),
+                ("result", models.JSONField(null=True)),
+                ("traceback", models.TextField(null=True)),
+                ("args", models.JSONField(null=True)),
+                ("kwargs", models.JSONField(null=True)),
+            ],
+            options={
+                "ordering": ["-date_done"],
+            },
+        ),
+    ]

django_qstash/results/models.py

@@ -0,0 +1,36 @@
+from __future__ import annotations
+
+import uuid
+
+from django.db import models
+from django.utils import timezone
+
+
+class TaskResult(models.Model):
+    id = models.UUIDField(
+        primary_key=True, default=uuid.uuid1, editable=False, unique=True
+    )
+    task_id = models.CharField(max_length=255, unique=True, db_index=True)
+    task_name = models.CharField(max_length=255)
+    status = models.CharField(
+        max_length=50,
+        choices=[
+            ("PENDING", "Pending"),
+            ("SUCCESS", "Success"),
+            ("FAILURE", "Failure"),
+        ],
+        default="PENDING",
+    )
+    date_created = models.DateTimeField(default=timezone.now)
+    date_done = models.DateTimeField(null=True)
+    result = models.JSONField(null=True)
+    traceback = models.TextField(null=True)
+    args = models.JSONField(null=True)
+    kwargs = models.JSONField(null=True)
+
+    class Meta:
+        app_label = "django_qstash_results"
+        ordering = ["-date_done"]
+
+    def __str__(self):
+        return f"{self.task_name} ({self.task_id})"

django_qstash/results/services.py

@@ -0,0 +1,33 @@
+from __future__ import annotations
+
+import logging
+
+from django.apps import apps
+from django.utils import timezone
+
+logger = logging.getLogger(__name__)
+
+
+def store_task_result(
+    task_id, task_name, status, result=None, traceback=None, args=None, kwargs=None
+):
+    """Helper function to store task results if the results app is installed"""
+    try:
+        TaskResult = apps.get_model("django_qstash_results", "TaskResult")
+        task_result = TaskResult.objects.create(
+            task_id=task_id,
+            task_name=task_name,
+            status=status,
+            date_done=timezone.now(),
+            result=result,
+            traceback=traceback,
+            args=args,
+            kwargs=kwargs,
+        )
+        return task_result
+    except LookupError:
+        # Model isn't installed, skip storage
+        logger.debug(
+            "Django QStash Results not installed. Add `django_qstash.results` to INSTALLED_APPS and run migrations."
+        )
+        return None

django_qstash/views.py

@@ -1,124 +1,21 @@
+from __future__ import annotations
+
 import json
-import logging
 
-from django.conf import settings
-from django.http import (
-    HttpRequest,
-    HttpResponse,
-    HttpResponseBadRequest,
-    HttpResponseForbidden,
-)
+from django.http import HttpRequest
+from django.http import HttpResponse
 from django.views.decorators.csrf import csrf_exempt
 from django.views.decorators.http import require_http_methods
-from qstash import Receiver
-
-from . import utils
-
-DJANGO_QSTASH_FORCE_HTTPS = getattr(settings, "DJANGO_QSTASH_FORCE_HTTPS", True)
-
-logger = logging.getLogger(__name__)
 
-
-# Initialize the QStash receiver
-receiver = Receiver(
-    current_signing_key=settings.QSTASH_CURRENT_SIGNING_KEY,
-    next_signing_key=settings.QSTASH_NEXT_SIGNING_KEY,
-)
+from .handlers import QStashWebhook
 
 
 @csrf_exempt
 @require_http_methods(["POST"])
 def qstash_webhook_view(request: HttpRequest) -> HttpResponse:
-    """
-    Webhook handler for QStash callbacks.
-
-    Expects a POST request with:
-    - Upstash-Signature header for verification
-    - JSON body containing task information:
-        {
-            "function": "full.path.to.function",
-            "module": "module.path",
-            "args": [...],
-            "kwargs": {...},
-            "task_name": "optional_task_name",
-            "options": {...}
-        }
-    """
-    try:
-        # Get the signature from headers
-        signature = request.headers.get("Upstash-Signature")
-        if not signature:
-            return HttpResponseForbidden("Missing Upstash-Signature header")
-
-        # Verify the signature using the QStash SDK
-        url = request.build_absolute_uri()
-        if DJANGO_QSTASH_FORCE_HTTPS and not url.startswith("https://"):
-            url = url.replace("http://", "https://")
-        try:
-            receiver.verify(
-                body=request.body.decode(),
-                signature=signature,
-                url=url,
-            )
-        except Exception as e:
-            logger.error(f"Signature verification failed: {e}")
-            return HttpResponseForbidden("Invalid signature")
-
-        # Parse the payload
-        try:
-            payload = json.loads(request.body.decode())
-        except json.JSONDecodeError as e:
-            logger.error(f"Failed to parse JSON payload: {e}")
-            return HttpResponseBadRequest("Invalid JSON payload")
-
-        # Validate payload structure
-        is_valid, error_message = utils.validate_task_payload(payload)
-        if not is_valid:
-            logger.error(f"Invalid payload structure: {error_message}")
-            return HttpResponseBadRequest(error_message)
-
-        # Import the function
-        try:
-            function_path = f"{payload['module']}.{payload['function']}"
-            task_func = utils.import_string(function_path)
-        except ImportError as e:
-            logger.error(f"Failed to import task function: {e}")
-            return HttpResponseBadRequest(f"Could not import task function: {e}")
-
-        # Execute the task
-        try:
-            if hasattr(task_func, "__call__") and hasattr(task_func, "actual_func"):
-                # If it's a wrapped function, call the actual function directly
-                result = task_func.actual_func(*payload["args"], **payload["kwargs"])
-            else:
-                result = task_func(*payload["args"], **payload["kwargs"])
-
-            # Prepare the response
-            response_data = {
-                "status": "success",
-                "task_name": payload.get("task_name", function_path),
-                "result": result if result is not None else "null",
-            }
-
-            return HttpResponse(
-                json.dumps(response_data), content_type="application/json"
-            )
-
-        except Exception as e:
-            logger.exception(f"Task execution failed: {e}")
-            error_response = {
-                "status": "error",
-                "task_name": payload.get("task_name", function_path),
-                "error": str(e),
-            }
-            return HttpResponse(
-                json.dumps(error_response), status=500, content_type="application/json"
-            )
-
-    except Exception as e:
-        logger.exception(f"Unexpected error in webhook handler: {e}")
-        return HttpResponse(
-            json.dumps({"status": "error", "error": "Internal server error"}),
-            status=500,
-            content_type="application/json",
-        )
+    """Handle QStash webhook requests."""
+    webhook = QStashWebhook()
+    response_data, status_code = webhook.handle_request(request)
+    return HttpResponse(
+        json.dumps(response_data), status=status_code, content_type="application/json"
+    )

{django_qstash-0.0.1.dist-info → django_qstash-0.0.3.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: django-qstash
-Version: 0.0.1
+Version: 0.0.3
 Summary: A drop-in replacement for Celery's shared_task with Upstash QStash.
 Author-email: Justin Mitchel <justin@codingforentrepreneurs.com>
 Project-URL: Changelog, https://github.com/jmitchel3/django-qstash
@@ -27,6 +27,8 @@ Requires-Dist: django>=4.2
 Requires-Dist: qstash>=2
 Requires-Dist: requests>=2.30
 
+> :warning: **BETA Software**: Working on being production-ready soon.
+
 # Django QStash `pip install django-qstash`
 
 A drop-in replacement for Celery's shared_task leveraging Upstash QStash for a truly serverless Django application to run background tasks asynchronously from the request/response cycle.
@@ -49,6 +51,7 @@ Depends on:
 # from celery import shared_task
 from django_qstash import shared_task
 
+
 @shared_task
 def math_add_task(a, b, save_to_file=False):
     logger.info(f"Adding {a} and {b}")
@@ -73,23 +76,24 @@ math_add_task.delay(12, 454, save_to_file=True)
 
 
 ```python
-QSTASH_TOKEN="your_token"
-QSTASH_CURRENT_SIGNING_KEY="your_current_signing_key"
-QSTASH_NEXT_SIGNING_KEY="your_next_signing_key"
+QSTASH_TOKEN = "your_token"
+QSTASH_CURRENT_SIGNING_KEY = "your_current_signing_key"
+QSTASH_NEXT_SIGNING_KEY = "your_next_signing_key"
 
 # required for django-qstash
-DJANGO_QSTASH_DOMAIN="https://example.com"
-DJANGO_QSTASH_WEBHOOK_PATH="/qstash/webhook/"
+DJANGO_QSTASH_DOMAIN = "https://example.com"
+DJANGO_QSTASH_WEBHOOK_PATH = "/qstash/webhook/"
 ```
 
 
+`DJANGO_QSTASH_DOMAIN`: Must be a valid and publicly accessible domain. For example `https://djangoqstash.com`
 
-`DJANGO_QSTASH_DOMAIN`: Must be a valid and publicly accessible domain. For example `https://djangoqstash.net`
+In development mode, we recommend using a tunnel like [Cloudflare Tunnels](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/) with a domain name you control. You can also consider [ngrok](https://ngrok.com/).
 
-In development mode, we recommend using a tunnel like [Cloudflare Tunnels](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/) with a domain name you control. You can also consider [ngrok](https://ngrok.com/). 
 
+`DJANGO_QSTASH_WEBHOOK_PATH` (default:`/qstash/webhook/`): The path where QStash will send webhooks to your Django application.
 
-`DJANGO_QSTASH_WEBHOOK_PATH`: The path where QStash will send webhooks to your Django application. Defaults to `/qstash/webhook/`
 
+`DJANGO_QSTASH_FORCE_HTTPS` (default:`True`): Whether to force HTTPS for the webhook.
 
-`DJANGO_QSTASH_FORCE_HTTPS`: Whether to force HTTPS for the webhook. Defaults to `True`.
+`DJANGO_QSTASH_RESULT_TTL` (default:`604800`): A number of seconds after which task result data can be safely deleted. Defaults to 604800 seconds (7 days or 7 * 24 * 60 * 60).

django_qstash-0.0.3.dist-info/RECORD

@@ -0,0 +1,19 @@
+django_qstash/__init__.py,sha256=KLUoDDQqN2L9ikWuv1pbu1hY2VEXh93Kzn09C6TbmLI,117
+django_qstash/exceptions.py,sha256=pH6kKRJFIVFkDHUJQ9yRWmtGdBBSXpNAwMSFuNzMgPw,392
+django_qstash/handlers.py,sha256=mmm8TJOqV3j1rQXooNOa128gtmALXFNCAaDZ5xwIcuw,4950
+django_qstash/tasks.py,sha256=X2gFILRvUF2GFuwyAUT43Zvw7OsdFci7870VhRNQ5-M,4929
+django_qstash/utils.py,sha256=wrTU30cobO2di18BNEFtKD4ih2euf7eQNpg6p6TkQ1Y,1185
+django_qstash/views.py,sha256=H32f_jGnlwOTO0YG9znNo2b-GRYZ8TM-Wt0T62SGdXM,639
+django_qstash/management/commands/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+django_qstash/management/commands/clear_stale_results.py,sha256=stHCnvC1ER_rZXKUK-YVUgazC2q04eGIHjo_BrPSDEI,2096
+django_qstash/results/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+django_qstash/results/admin.py,sha256=q9fn3lfn0gviMfiimYij0wBCYww7FxyrOfGPr1NvntA,434
+django_qstash/results/apps.py,sha256=4me4cg5yeoeSJTphkHYzGMJUfGucT47FNIUMYu5gmIo,275
+django_qstash/results/models.py,sha256=aEiAhGJOuLRtjibUw6xdQqUt3eYKLqY2as4I4QSrF5U,1047
+django_qstash/results/services.py,sha256=HvNp5D1tQ__nz4LVUTAGxuyLl_dnlBps4pJ6E9HD2kA,991
+django_qstash/results/migrations/0001_initial.py,sha256=A90SKgWmBf4SIJYG1Jh6-b_81Ia1zIzGj3Bfl1O4-kg,1902
+django_qstash/results/migrations/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+django_qstash-0.0.3.dist-info/METADATA,sha256=t_nf7LAsZI-R5PEyKI2yPxxsRobQ6QoI33e_9div-kE,3332
+django_qstash-0.0.3.dist-info/WHEEL,sha256=PZUExdf71Ui_so67QXpySuHtCi3-J3wvF4ORK6k_S8U,91
+django_qstash-0.0.3.dist-info/top_level.txt,sha256=AlV3WSK1A0ZvKuCLsINtIJhJW8zo7SEB-D3_RAjZ0hI,14
+django_qstash-0.0.3.dist-info/RECORD,,

django_qstash-0.0.1.dist-info/RECORD

@@ -1,8 +0,0 @@
-django_qstash/__init__.py,sha256=HvBJshBllZs_V6B2p1DtRYkcU1CiDglPlk43V8MYleI,81
-django_qstash/tasks.py,sha256=X2gFILRvUF2GFuwyAUT43Zvw7OsdFci7870VhRNQ5-M,4929
-django_qstash/utils.py,sha256=wrTU30cobO2di18BNEFtKD4ih2euf7eQNpg6p6TkQ1Y,1185
-django_qstash/views.py,sha256=ucxKQdBoz9Db_1wpuE3U0BBC4nPqtFv05Kb0wggrpOg,4270
-django_qstash-0.0.1.dist-info/METADATA,sha256=QZayHLC5YDuYHMFtMbmBdx8ZTllFhnXk8F2xAxGWcpI,3079
-django_qstash-0.0.1.dist-info/WHEEL,sha256=PZUExdf71Ui_so67QXpySuHtCi3-J3wvF4ORK6k_S8U,91
-django_qstash-0.0.1.dist-info/top_level.txt,sha256=AlV3WSK1A0ZvKuCLsINtIJhJW8zo7SEB-D3_RAjZ0hI,14
-django_qstash-0.0.1.dist-info/RECORD,,