Merge pull request #180 from AvaCodeSolutions/feat/159/deliver-contents-endpoint

payamnj · web-flow · commit b490d67f1a94 · 2026-01-29T16:00:40.000+04:00
feat: #159 Add api endpoit for deliver_contents
diff --git a/django_email_learning/decorators.py b/django_email_learning/decorators.py
@@ -2,6 +2,8 @@
 from django.http import JsonResponse
 from django_email_learning.models import OrganizationUser
 from django_email_learning.apps import PLATFORM_ADMIN_GROUP_NAME
+from django_email_learning.services.jwt_service import decode_jwt, InvalidTokenException
+from django_email_learning.models import ApiKey
 import typing
 
 
@@ -68,3 +70,54 @@ def _wrapped_view(request, *view_args, **view_kwargs) -> JsonResponse:  # type:
         return _wrapped_view
 
     return decorator
+
+
+def check_api_key() -> typing.Callable:
+    def decorator(view_func: typing.Callable) -> typing.Callable:
+        @wraps(view_func)
+        def _wrapped_view(request, *view_args, **view_kwargs) -> JsonResponse:  # type: ignore[no-untyped-def]
+            authorization_header = request.headers.get("Authorization")
+            if not authorization_header:
+                return JsonResponse(
+                    {"error": "Authorization header missing"}, status=401
+                )
+            authorization_header_parts = authorization_header.split(" ")
+            if (
+                len(authorization_header_parts) != 2
+                or authorization_header_parts[0] != "Bearer"
+            ):
+                return JsonResponse(
+                    {
+                        "error": "Invalid Authorization header format. Expected: Bearer <API_KEY>"
+                    },
+                    status=401,
+                )
+            api_key = authorization_header_parts[1]
+            try:
+                key_data = decode_jwt(api_key)
+                possible_keys = ApiKey.objects.filter(salt=key_data["salt"])
+                key_matched = False
+                for possible_key in possible_keys:
+                    key_value = possible_key.decrypt_password(possible_key.key)
+                    if key_value == key_data["key"]:
+                        key_matched = True
+                        break
+                if not key_matched:
+                    return JsonResponse({"error": "Invalid API key"}, status=401)
+            except InvalidTokenException:
+                return JsonResponse({"error": "Invalid Json Web Token"}, status=401)
+            except KeyError:
+                return JsonResponse(
+                    {"error": "Json Web Token missing required fields"}, status=401
+                )
+
+            try:
+                api_key = ApiKey.objects.get(salt=key_data["salt"])
+            except ApiKey.DoesNotExist:
+                return JsonResponse({"error": "Invalid API key"}, status=401)
+
+            return view_func(request, *view_args, **view_kwargs)
+
+        return _wrapped_view
+
+    return decorator
diff --git a/django_email_learning/jobs/api/__init__.py b/django_email_learning/jobs/api/__init__.py
diff --git a/django_email_learning/jobs/api/urls.py b/django_email_learning/jobs/api/urls.py
@@ -0,0 +1,10 @@
+from django.urls import path
+from django_email_learning.jobs.api.views import DeliverContentsJobView
+
+app_name = "django_email_learning"
+
+urlpatterns = [
+    path(
+        "deliver_contents/", DeliverContentsJobView.as_view(), name="deliver_contents"
+    ),
+]
diff --git a/django_email_learning/jobs/api/views.py b/django_email_learning/jobs/api/views.py
@@ -0,0 +1,13 @@
+from django.views import View
+from django_email_learning.decorators import check_api_key
+from django_email_learning.jobs.deliver_contents_job import DeliverContentsJob
+from django.utils.decorators import method_decorator
+from django.http import JsonResponse
+
+
+@method_decorator(check_api_key(), name="get")
+class DeliverContentsJobView(View):
+    def get(self, request, *args, **kwargs) -> JsonResponse:  # type: ignore[no-untyped-def]
+        job = DeliverContentsJob()
+        job.run()
+        return JsonResponse({"status": "DeliverContentsJob triggered"}, status=202)
diff --git a/django_email_learning/jobs/deliver_contents_job.py b/django_email_learning/jobs/deliver_contents_job.py
@@ -8,8 +8,10 @@
     SendQuizCommand,
     QuizNotFoundError,
 )
+from django_email_learning.models import JobExecution, JobName, JobStatus
 from django.utils.module_loading import import_string
 from django.conf import settings
+from django.utils import timezone
 import logging
 import datetime
 
@@ -22,11 +24,27 @@ def __init__(self) -> None:
         self.delivery_queue: DeliveryQueueProtocol = self.get_delivery_queue()
 
     def run(self) -> None:
+        if JobExecution.objects.filter(
+            job_name=JobName.DELIVER_CONTENTS.value,
+            status=JobStatus.RUNNING.value,
+        ).exists():
+            logger.warning(
+                "Another instance of DeliverContentsJob is already running. Exiting this run."
+            )
+            return
+        job_execution = JobExecution.objects.create(
+            job_name=JobName.DELIVER_CONTENTS.value,
+            status=JobStatus.RUNNING.value,
+            started_at=timezone.now(),
+        )
         should_check_next = True
         while should_check_next:
             delivery_schedule = self.delivery_queue.next_task()
             if delivery_schedule is None:
                 should_check_next = False
+                job_execution.status = JobStatus.COMPLETED.value
+                job_execution.finished_at = timezone.now()
+                job_execution.save()
             else:
                 self.process_delivery(delivery_schedule)
 
diff --git a/django_email_learning/migrations/0004_jobexecution_alter_apikey_salt_and_more.py b/django_email_learning/migrations/0004_jobexecution_alter_apikey_salt_and_more.py
@@ -0,0 +1,60 @@
+# Generated by Django 6.0.1 on 2026-01-29 07:56
+
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+    dependencies = [
+        ("django_email_learning", "0003_apikey_salt_imapconnection_salt"),
+    ]
+
+    operations = [
+        migrations.CreateModel(
+            name="JobExecution",
+            fields=[
+                (
+                    "id",
+                    models.BigAutoField(
+                        auto_created=True,
+                        primary_key=True,
+                        serialize=False,
+                        verbose_name="ID",
+                    ),
+                ),
+                (
+                    "job_name",
+                    models.CharField(
+                        choices=[("DELIVER_CONTENTS", "deliver_contents")],
+                        max_length=200,
+                    ),
+                ),
+                ("started_at", models.DateTimeField(auto_now_add=True)),
+                ("finished_at", models.DateTimeField(blank=True, null=True)),
+                (
+                    "status",
+                    models.CharField(
+                        choices=[("RUNNING", "running"), ("COMPLETED", "completed")],
+                        max_length=50,
+                    ),
+                ),
+            ],
+        ),
+        migrations.AlterField(
+            model_name="apikey",
+            name="salt",
+            field=models.CharField(
+                default="727829a83ebd47f8baf0c15400d16119",
+                editable=False,
+                max_length=32,
+            ),
+        ),
+        migrations.AlterField(
+            model_name="imapconnection",
+            name="salt",
+            field=models.CharField(
+                default="727829a83ebd47f8baf0c15400d16119",
+                editable=False,
+                max_length=32,
+            ),
+        ),
+    ]
diff --git a/django_email_learning/models.py b/django_email_learning/models.py
@@ -109,11 +109,12 @@ def __str__(self) -> str:
 class EncryptionMixin(models.Model):
     salt = models.CharField(max_length=32, editable=False, default=uuid.uuid4().hex)
 
-    def _fernet(self) -> Fernet:
+    @classmethod
+    def _fernet(cls, salt: str) -> Fernet:
         kdf = PBKDF2HMAC(
             algorithm=hashes.SHA256(),
             length=32,
-            salt=self.salt.encode(),
+            salt=salt.encode(),
             iterations=100000,
         )
         try:
@@ -125,12 +126,17 @@ def _fernet(self) -> Fernet:
         key = base64.urlsafe_b64encode(kdf.derive(secret.encode()))
         return Fernet(key)
 
+    @classmethod
+    def encrypted_value(cls, value: str, salt: str) -> str:
+        f = cls._fernet(salt)
+        return f.encrypt(value.encode()).decode()
+
     def _encrypt_password(self, password: str) -> str:
-        f = self._fernet()
+        f = self._fernet(self.salt)
         return f.encrypt(password.encode()).decode()
 
     def decrypt_password(self, encrypted_password: str) -> str:
-        f = self._fernet()
+        f = self._fernet(self.salt)
         return f.decrypt(encrypted_password.encode()).decode()
 
     class Meta:
@@ -698,3 +704,29 @@ def save(self, *args, **kwargs) -> None:  # type: ignore[no-untyped-def]
             self.key = self._encrypt_password(self.key)
         self.full_clean()
         super().save(*args, **kwargs)
+
+
+class JobName(StrEnum):
+    DELIVER_CONTENTS = "deliver_contents"
+
+
+class JobStatus(StrEnum):
+    RUNNING = "running"
+    COMPLETED = "completed"
+
+
+class JobExecution(models.Model):
+    job_name = models.CharField(
+        max_length=200, choices=[(job.name, job.value) for job in JobName]
+    )
+    started_at = models.DateTimeField(auto_now_add=True)
+    finished_at = models.DateTimeField(null=True, blank=True)
+    status = models.CharField(
+        max_length=50,
+        choices=[(status.name, status.value) for status in JobStatus],
+    )
+
+    def __str__(self) -> str:
+        return (
+            f"Job: {self.job_name} started at {self.started_at} - Status: {self.status}"
+        )
diff --git a/django_email_learning/personalised/api/urls.py b/django_email_learning/personalised/api/urls.py
@@ -1,7 +1,7 @@
 from django.urls import path
 from django_email_learning.personalised.api.views import QuizSubmissionView
 
-app_name = "email_learning"
+app_name = "django_email_learning"
 
 urlpatterns = [
     path("quiz/", QuizSubmissionView.as_view(), name="quiz_submission"),
diff --git a/django_email_learning/personalised/urls.py b/django_email_learning/personalised/urls.py
@@ -4,7 +4,7 @@
     VerifyEnrollmentView,
 )
 
-app_name = "email_learning"
+app_name = "django_email_learning"
 
 urlpatterns = [
     path("quiz/", QuizPublicView.as_view(), name="quiz_public_view"),
diff --git a/django_email_learning/platform/api/serializers.py b/django_email_learning/platform/api/serializers.py
@@ -24,6 +24,7 @@
     Enrollment,
     EnrollmentStatus,
 )
+from django_email_learning.services.jwt_service import generate_jwt
 import enum
 
 
@@ -35,10 +36,14 @@ class ApiKeyResponse(BaseModel):
 
     @staticmethod
     def from_django_model(api_key: ApiKey) -> "ApiKeyResponse":
+        decrypted_key = api_key.decrypt_password(api_key.key)
+        salt = api_key.salt
+        jwt_key = generate_jwt({"key": decrypted_key, "salt": salt}, exp=datetime.max)
+
         return ApiKeyResponse.model_validate(
             {
                 "id": api_key.id,  # type: ignore[attr-defined]
-                "key": api_key.decrypt_password(api_key.key),
+                "key": jwt_key,
                 "created_at": api_key.created_at,
                 "created_by": api_key.created_by.username
                 if api_key.created_by
diff --git a/django_email_learning/public/api/urls.py b/django_email_learning/public/api/urls.py
@@ -1,7 +1,7 @@
 from django.urls import path
 from django_email_learning.public.api.views import EnrollView
 
-app_name = "email_learning"
+app_name = "django_email_learning"
 
 urlpatterns = [
     path("enroll/", EnrollView.as_view(), name="enroll"),
diff --git a/django_email_learning/public/urls.py b/django_email_learning/public/urls.py
@@ -1,7 +1,7 @@
 from django.urls import path
 from django_email_learning.public.views import OrganizationView
 
-app_name = "email_learning"
+app_name = "django_email_learning"
 
 urlpatterns = [
     path(
diff --git a/django_email_learning/urls.py b/django_email_learning/urls.py
@@ -5,6 +5,7 @@
 from django_email_learning.personalised import urls as personalised_urls
 from django_email_learning.public.api import urls as public_api_urls
 from django_email_learning.public import urls as public_urls
+from django_email_learning.jobs.api import urls as jobs_api_urls
 
 app_name = "django_email_learning"
 
@@ -18,4 +19,5 @@
     path("platform/", include(platform_urls, namespace="platform")),
     path("public/", include(public_urls, namespace="public")),
     path("my/", include(personalised_urls, namespace="personalised")),
+    path("api/jobs/", include(jobs_api_urls, namespace="api_jobs")),
 ]
diff --git a/docs/source/_static/logo.png b/docs/source/_static/logo.png
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -23,4 +23,12 @@
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 
 html_theme = "alabaster"
+
+html_theme_options = {
+    "description": "A Django app for email-based learning management systems.",
+    "logo": "logo.png",
+    "github_user": "AvaCodeSolutions",
+    "github_repo": "django-email-learning",
+    "github_banner": True,
+}
 html_static_path = ["_static"]
diff --git a/docs/source/technical/management-commands.rst b/docs/source/technical/management-commands.rst
@@ -15,6 +15,13 @@ Usage
 
     python manage.py deliver_contents
 
+
+
+If you don't have the option to set a cron job or similar scheduling mechanism on the server, or you prefer to use a third-party service,
+you can trigger the command via the provided HTTP endpoint. ``/api/jobs/deliver-contents/``
+Ensure that you have the necessary authentication and permissions set up to access this endpoint securely. See :doc:`../platform/api_keys` for more details.
+
+
 Function
 ~~~~~~~~
 
@@ -29,10 +36,6 @@ Scheduling Requirement
 
 The ``deliver_contents`` command must be executed regularly to ensure timely content delivery. It should be scheduled to run automatically using a task scheduler.
 
-.. note::
-    The current version does not have an endpoint to trigger this command, so for this MVP version, you will need to set up a cron job or similar scheduling mechanism manually.
-    For future versions, we plan to introduce an HTTP endpoint to trigger this command. which can be used by webhooks or other services to initiate content delivery without relying solely on cron jobs.
-
 Execution Frequency
 -------------------
 
diff --git a/frontend/package-lock.json b/frontend/package-lock.json
diff --git a/pyproject.toml b/pyproject.toml
diff --git a/tests/jobs/api/__init__.py b/tests/jobs/api/__init__.py
diff --git a/tests/jobs/api/test_views/__init__.py b/tests/jobs/api/test_views/__init__.py
diff --git a/tests/jobs/api/test_views/test_deliver_contents_job_view.py b/tests/jobs/api/test_views/test_deliver_contents_job_view.py

Original file line number	Diff line number	Diff line change
`@@ -4,7 +4,7 @@`
`4`	`4`	`VerifyEnrollmentView,`
`5`	`5`	`)`
`6`	`6`
`7`		`-app_name = "email_learning"`
	`7`	`+app_name = "django_email_learning"`
`8`	`8`
`9`	`9`	`urlpatterns = [`
`10`	`10`	`path("quiz/", QuizPublicView.as_view(), name="quiz_public_view"),`