trueppm-api 0.4.0b2__py3-none-any.whl

trueppm_api/apps/webhooks/views.py

@@ -0,0 +1,383 @@
+"""Views for webhook management API."""
+
+from __future__ import annotations
+
+import logging
+
+import redis as redis_lib
+from django.db import transaction
+from django.db.models import QuerySet
+from drf_spectacular.utils import (
+    OpenApiResponse,
+    extend_schema,
+    extend_schema_view,
+    inline_serializer,
+)
+from kombu.exceptions import (  # type: ignore[import-untyped]
+    OperationalError as KombuOperationalError,
+)
+from rest_framework import serializers, status
+from rest_framework.decorators import action
+from rest_framework.mixins import (
+    CreateModelMixin,
+    DestroyModelMixin,
+    ListModelMixin,
+    RetrieveModelMixin,
+    UpdateModelMixin,
+)
+from rest_framework.pagination import CursorPagination
+from rest_framework.permissions import BasePermission, IsAuthenticated
+from rest_framework.request import Request
+from rest_framework.response import Response
+from rest_framework.serializers import BaseSerializer
+from rest_framework.viewsets import GenericViewSet
+
+from trueppm_api.apps.access.permissions import (
+    IsProgramAdmin,
+    IsProgramMember,
+    IsProjectAdmin,
+    IsProjectMember,
+    IsProjectNotArchived,
+)
+from trueppm_api.apps.idempotency.mixins import IdempotencyMixin
+from trueppm_api.apps.projects.models import Program, Project
+from trueppm_api.apps.webhooks.dispatch import build_delivery_body
+from trueppm_api.apps.webhooks.models import (
+    PING_EVENT_TYPE,
+    Webhook,
+    WebhookDelivery,
+    _next_delivery_sequence,
+)
+from trueppm_api.apps.webhooks.serializers import (
+    WebhookCreateResponseSerializer,
+    WebhookDeliverySerializer,
+    WebhookSerializer,
+)
+from trueppm_api.apps.webhooks.tasks import deliver_webhook
+
+logger = logging.getLogger(__name__)
+
+_BROKER_ERRORS = (KombuOperationalError, ConnectionError, redis_lib.ConnectionError)
+
+
+class WebhookDeliveryCursorPagination(CursorPagination):
+    """Depth-independent pagination for a webhook's delivery log (#1317).
+
+    The delivery history grows without bound — one row per event fired — and the
+    previous hard ``[:50]`` slice could only ever surface the newest 50 with no
+    way to page back. A created_at cursor is stable under the concurrent inserts
+    the dispatcher produces. Mirrors AuditEventCursorPagination.
+    """
+
+    ordering = "-created_at"
+    page_size = 50
+    page_size_query_param = "page_size"
+    max_page_size = 200
+
+
+# The real 200 body of a webhook's delivery log. Declared once and shared by the
+# project- and program-scoped viewsets so both publish the identical component
+# (two `inline_serializer` calls with the same name would be a duplicate-component
+# hazard). This action paginates with a CURSOR while its viewset's own
+# pagination_class is page-number, and drf-spectacular's auto-wrap reads the class
+# attribute — so a `many=True` response was wrapped in the page-number envelope and
+# published `count` as *required* for a body that never carries one. Same defect
+# class as #2583's named instances: a client typing `count` as non-optional breaks
+# on first call. Declare the envelope rather than lean on a heuristic that cannot
+# see which paginator actually runs.
+WEBHOOK_DELIVERY_PAGE = inline_serializer(
+    name="WebhookDeliveryCursorPage",
+    fields={
+        "next": serializers.URLField(allow_null=True),
+        "previous": serializers.URLField(allow_null=True),
+        "results": WebhookDeliverySerializer(many=True),
+    },
+)
+
+
+# The 201 body carries the one-time `secret`; the shared Webhook schema does not
+# declare it (the field is write_only, which is right for every read). Declared per
+#: Both causes of the 403 the project-scoped create now answers. Declared as one string
+#: because the two are indistinguishable on the wire — same status, bare ``detail`` — so
+#: a client branches on the message either way, and publishing only one of them would
+#: tell an integrator the other cannot happen.
+#:
+#: Used ONLY where `ProgramWebhookViewSet` overrides the declaration with its own. A
+#: declaration on an inherited action that the subclass does not re-declare publishes on
+#: BOTH paths — which also collides their pinned operationIds — so `update`,
+#: `partial_update` and `destroy` are deliberately left undeclared here rather than
+#: gaining a project-flavored 403 on the program routes. They are part of the wider
+#: undeclared-403-on-DELETE gap recorded in the MR for #3414.
+_ARCHIVED_OR_NOT_ADMIN = (
+    "Caller is not a project Admin, or the project is archived (#3414) — archived "
+    "plans are read-only, so a webhook cannot be added, edited, deleted or "
+    "test-fired on one. Reading the webhook and its deliveries still works."
+)
+
+
+# viewset because one shared declaration would publish the same operationId on both
+# the project- and program-scoped paths — a duplicate-operationId collision. Ids are
+# pinned for the same reason as `deliveries`: operationId is the *method name* in a
+# generated client, so fixing a response shape must not rename every caller's method
+# (#2583).
+@extend_schema_view(
+    create=extend_schema(
+        summary="Register a webhook",
+        responses={
+            201: WebhookCreateResponseSerializer,
+            403: OpenApiResponse(description=_ARCHIVED_OR_NOT_ADMIN),
+        },
+        operation_id="v1_projects_webhooks_create",
+    ),
+)
+class WebhookViewSet(
+    IdempotencyMixin,
+    CreateModelMixin,
+    RetrieveModelMixin,
+    UpdateModelMixin,
+    DestroyModelMixin,
+    ListModelMixin,
+    GenericViewSet[Webhook],
+):
+    """CRUD for outbound webhooks scoped to a project.
+
+    List/retrieve: requires Viewer+ (IsProjectMember).
+    Create/update/delete: requires Admin+ (IsProjectAdmin).
+    """
+
+    serializer_class = WebhookSerializer
+
+    # Exempt from the generic Idempotency-Key path (ADR-0170): the create response
+    # carries the one-time plaintext signing secret, which must never be persisted
+    # in the idempotency store for replay. Mirrors ProjectApiTokenViewSet, and it is
+    # the same reasoning #2885 encrypts the column for — storing the plaintext in
+    # IdempotencyKey.response_body (a plain JSONField, retained for
+    # IDEMPOTENCY_RETENTION_HOURS) would move the secret to another table rather than
+    # remove it, and would re-serve it on replay, contradicting the documented
+    # "returned exactly once" guarantee.
+    idempotency_exempt = True
+
+    def get_permissions(self) -> list[BasePermission]:
+        # `deliveries` exposes the full event payload (task notes, comment
+        # snippets, assignee emails) of every event ever sent (#903). That is
+        # information disclosure beyond plain project membership, so it is
+        # Admin-only — consistent with webhook create/update/delete/test, which
+        # are already Admin-gated (only an Admin could have created the webhook).
+        if self.action == "deliveries":
+            # A read. Archived projects stay readable, so no lifecycle gate here.
+            return [IsAuthenticated(), IsProjectAdmin()]
+        if self.action in ("create", "update", "partial_update", "destroy", "test_ping"):
+            # IsProjectNotArchived fires in `has_permission` on these routes because the
+            # URL names `project_pk` — the kwarg `_project_pk_from_view` reads (#3414).
+            # `destroy` is gated like the rest since the archive bypass was scoped to
+            # ProjectViewSet; before that, the router-minted action name alone was
+            # enough to skip the check on every project-scoped viewset.
+            return [IsAuthenticated(), IsProjectAdmin(), IsProjectNotArchived()]
+        return [IsAuthenticated(), IsProjectMember()]
+
+    def get_queryset(self) -> QuerySet[Webhook]:
+        project_pk = self.kwargs["project_pk"]
+        return (
+            Webhook.objects.filter(project_id=project_pk)
+            .select_related("project", "created_by")
+            .order_by("-created_at")
+        )
+
+    def perform_create(self, serializer: BaseSerializer[Webhook]) -> None:
+        project_pk = self.kwargs["project_pk"]
+        try:
+            project = Project.objects.get(pk=project_pk, is_deleted=False)
+        except Project.DoesNotExist:
+            from rest_framework.exceptions import NotFound
+
+            raise NotFound("Project not found.") from None
+
+        # Check object-level permission.
+        self.check_object_permissions(self.request, project)
+
+        serializer.save(project=project, created_by=self.request.user)
+
+    def perform_update(self, serializer: BaseSerializer[Webhook]) -> None:
+        serializer.save()
+
+    def get_object(self) -> Webhook:
+        obj: Webhook = super().get_object()
+        # Object-level permission check against the webhook's scope object —
+        # the Project for project-scoped webhooks, the Program for program-scoped
+        # ones (ADR-0076). The active permission classes (Is{Project,Program}*)
+        # match because get_permissions is scope-specific per subclass.
+        self.check_object_permissions(self.request, self._scope_object(obj))
+        return obj
+
+    def _scope_object(self, webhook: Webhook) -> Project | Program:
+        """Return the Project or Program a webhook is scoped to (XOR)."""
+        scope = webhook.program if webhook.program_id else webhook.project
+        # The webhook_scope_xor DB constraint guarantees exactly one is set, so
+        # scope is never None here — assert narrows the type for mypy.
+        assert scope is not None
+        return scope
+
+    @extend_schema(
+        summary="Send a test webhook ping",
+        responses={
+            202: inline_serializer(
+                name="WebhookTestPingResponse",
+                fields={"delivery_id": serializers.CharField()},
+            ),
+            403: OpenApiResponse(
+                description=(
+                    "Caller lacks Admin on the webhook's scope. On a PROJECT webhook the "
+                    "same status is also how an archived project refuses (#3414); the "
+                    "program-scoped route has no archived state. Declared once because "
+                    "this handler is shared by both viewsets."
+                )
+            ),
+        },
+    )
+    @action(detail=True, methods=["post"], url_path="test")
+    def test_ping(self, request: Request, **kwargs: object) -> Response:
+        """Send a test ping to the webhook URL.
+
+        The ping takes exactly the same path as a real delivery: it renders through
+        the subscription's registered format, is signed identically, and consumes a
+        sequence number with a matching ``_meta.sequence``. A test therefore fails
+        wherever a real delivery would, and never shows up as a gap in the
+        consumer's sequence counter.
+
+        Returns 202 with the ``delivery_id``. That acknowledges the *enqueue*, not
+        the receiver's answer — read the ``deliveries`` action back for that row's
+        terminal ``status`` and ``response_status`` to learn what the receiver said.
+        """
+        # Building the ping inline (rather than through the provider) was how a
+        # slack-format webhook — the UI default — got sent a body Slack rejects with
+        # 400 invalid_payload while the API reported success on the 202 (#2884).
+        webhook = self.get_object()
+        sequence = _next_delivery_sequence(webhook.pk)
+        body = build_delivery_body(
+            webhook,
+            PING_EVENT_TYPE,
+            {"event": PING_EVENT_TYPE, "webhook_id": str(webhook.pk)},
+            sequence,
+        )
+        delivery = WebhookDelivery.objects.create(
+            webhook=webhook,
+            event_type=PING_EVENT_TYPE,
+            payload=body,
+            sequence_number=sequence,
+        )
+        # Defer dispatch until the delivery row is committed so the task never
+        # races against an uncommitted row.  If the broker is down the delay()
+        # call is a no-op — the delivery row stays PENDING and drain_webhook_queue
+        # picks it up within _DRAIN_ORPHAN_MINUTES.
+        delivery_id = str(delivery.pk)
+
+        def _enqueue_ping() -> None:
+            try:
+                deliver_webhook.delay(delivery_id)
+            except _BROKER_ERRORS:
+                logger.warning(
+                    "test_ping: broker unavailable — delivery %s will be drained",
+                    delivery_id,
+                )
+
+        transaction.on_commit(_enqueue_ping)
+        return Response(
+            {"delivery_id": delivery_id},
+            status=status.HTTP_202_ACCEPTED,
+        )
+
+    @extend_schema(
+        summary="List recent webhook deliveries",
+        responses={200: WEBHOOK_DELIVERY_PAGE},
+        # Pinned because declaring the envelope changes what drf-spectacular
+        # thinks this operation is. It derives the operationId's `_list`/
+        # `_retrieve` suffix from whether the 200 is a ``many=True`` serializer,
+        # so switching to an object envelope silently renamed
+        # ``…_deliveries_list`` to ``…_deliveries_retrieve`` — and operationId is
+        # the *method name* in a generated client. Fixing a broken response type
+        # by breaking every caller's method name would trade one #2583 for
+        # another, so the shipped id is held fixed.
+        operation_id="v1_projects_webhooks_deliveries_list",
+    )
+    @action(detail=True, methods=["get"], url_path="deliveries")
+    def deliveries(self, request: Request, **kwargs: object) -> Response:
+        """List deliveries for this webhook, newest first (cursor-paginated, #1317).
+
+        A bare ``GET`` returns the most recent page; follow ``next`` to page
+        back through history. Instantiates the cursor paginator directly rather
+        than going through ``self.paginator`` (the viewset default is page-number
+        for the webhook CRUD list — the delivery log wants a cursor).
+        """
+        webhook = self.get_object()
+        qs = WebhookDelivery.objects.filter(webhook=webhook)
+        paginator = WebhookDeliveryCursorPagination()
+        page = paginator.paginate_queryset(qs, request, view=self)
+        serializer = WebhookDeliverySerializer(page, many=True)
+        return paginator.get_paginated_response(serializer.data)
+
+
+@extend_schema_view(
+    # Annotates the INHERITED action rather than redefining it. A single pinned
+    # operation_id on the base class would publish the same id on both the
+    # project- and program-scoped paths — a duplicate-operationId collision — so
+    # each concrete viewset needs its own. `extend_schema_view` does that without
+    # a subclass override, which would duplicate the handler for no runtime
+    # reason. See WebhookViewSet.deliveries for why the envelope must be explicit
+    # and why the id is pinned at all (#2583).
+    deliveries=extend_schema(
+        summary="List recent webhook deliveries",
+        responses={200: WEBHOOK_DELIVERY_PAGE},
+        operation_id="v1_programs_webhooks_deliveries_list",
+    ),
+    create=extend_schema(
+        summary="Register a webhook",
+        responses={201: WebhookCreateResponseSerializer},
+        operation_id="v1_programs_webhooks_create",
+    ),
+)
+class ProgramWebhookViewSet(WebhookViewSet):
+    """CRUD for outbound webhooks scoped to a program (ADR-0076).
+
+    A program-scoped webhook fires for events on any project within the program.
+    Inherits the test/deliveries actions and the rendering/dispatch substrate
+    from WebhookViewSet; only the scope resolution and RBAC ladder change:
+    list/retrieve require Program Viewer+ (IsProgramMember), mutations require
+    Program Admin+ (IsProgramAdmin).
+    """
+
+    def get_permissions(self) -> list[BasePermission]:
+        # `deliveries` exposes the full event payload (task notes, comment
+        # snippets, assignee emails) of every event ever sent (#903). That is
+        # information disclosure beyond plain project membership, so it is
+        # Admin-only — consistent with webhook create/update/delete/test, which
+        # are already Admin-gated (only an Admin could have created the webhook).
+        if self.action in (
+            "create",
+            "update",
+            "partial_update",
+            "destroy",
+            "test_ping",
+            "deliveries",
+        ):
+            return [IsAuthenticated(), IsProgramAdmin()]
+        return [IsAuthenticated(), IsProgramMember()]
+
+    def get_queryset(self) -> QuerySet[Webhook]:
+        program_pk = self.kwargs["program_pk"]
+        return (
+            Webhook.objects.filter(program_id=program_pk)
+            .select_related("program", "created_by")
+            .order_by("-created_at")
+        )
+
+    def perform_create(self, serializer: BaseSerializer[Webhook]) -> None:
+        program_pk = self.kwargs["program_pk"]
+        try:
+            program = Program.objects.get(pk=program_pk, is_deleted=False)
+        except Program.DoesNotExist:
+            from rest_framework.exceptions import NotFound
+
+            raise NotFound("Program not found.") from None
+
+        self.check_object_permissions(self.request, program)
+        serializer.save(program=program, created_by=self.request.user)

trueppm_api/apps/workflow_engine/apps.py

@@ -0,0 +1,23 @@
+"""App config for the workflow execution engine (ADR-0080).
+
+Holds the persistence layer (models, migrations, beat drain) for the default
+workflow backend. The public import surface workflow authors target lives at
+``trueppm_api.workflows`` (interface, services, backends, registry); this app
+is a backend implementation detail those consumers never import directly, which
+is what preserves backend-neutrality (ADR-0080 §E).
+
+Named ``workflow_engine`` (not ``workflows``) so the app label does not collide
+with the ``trueppm_api.workflows`` public package — that collision confused tools
+that map app label → module (the mypy django-stubs plugin stopped recognizing
+these as models), and is avoided by naming the engine's persistence app and the
+public API package distinctly.
+"""
+
+from __future__ import annotations
+
+from django.apps import AppConfig
+
+
+class WorkflowEngineConfig(AppConfig):
+    default_auto_field = "django.db.models.BigAutoField"
+    name = "trueppm_api.apps.workflow_engine"

trueppm_api/apps/workflow_engine/migrations/0001_initial.py

@@ -0,0 +1,230 @@
+# Generated by Django 6.0.3 on 2026-05-24 11:50
+
+import uuid
+
+import django.db.models.deletion
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+    initial = True
+
+    dependencies = []
+
+    operations = [
+        migrations.CreateModel(
+            name="WorkflowInstance",
+            fields=[
+                (
+                    "id",
+                    models.UUIDField(
+                        default=uuid.uuid4, editable=False, primary_key=True, serialize=False
+                    ),
+                ),
+                ("name", models.CharField(db_index=True, max_length=255)),
+                (
+                    "status",
+                    models.CharField(
+                        choices=[
+                            ("pending", "Pending"),
+                            ("running", "Running"),
+                            ("sleeping", "Sleeping"),
+                            ("completed", "Completed"),
+                            ("failed", "Failed"),
+                            ("canceled", "Canceled"),
+                        ],
+                        default="pending",
+                        max_length=16,
+                    ),
+                ),
+                ("input", models.JSONField(default=dict)),
+                ("result", models.JSONField(blank=True, null=True)),
+                ("error", models.TextField(blank=True, default="")),
+                ("idempotency_key", models.CharField(max_length=64)),
+                ("cancel_reason", models.CharField(blank=True, default="", max_length=255)),
+                ("created_at", models.DateTimeField(auto_now_add=True)),
+                ("updated_at", models.DateTimeField(auto_now=True)),
+                ("completed_at", models.DateTimeField(blank=True, null=True)),
+            ],
+            options={
+                "indexes": [
+                    models.Index(fields=["status", "created_at"], name="workflow_status_idx"),
+                    models.Index(fields=["completed_at"], name="workflow_completed_idx"),
+                ],
+                "constraints": [
+                    models.UniqueConstraint(
+                        fields=("idempotency_key",), name="workflow_idempotency_key_uniq"
+                    )
+                ],
+            },
+        ),
+        migrations.CreateModel(
+            name="WorkflowHistoryEvent",
+            fields=[
+                (
+                    "id",
+                    models.UUIDField(
+                        default=uuid.uuid4, editable=False, primary_key=True, serialize=False
+                    ),
+                ),
+                ("seq", models.BigIntegerField()),
+                ("event_type", models.CharField(max_length=32)),
+                ("payload", models.JSONField(default=dict)),
+                ("created_at", models.DateTimeField(auto_now_add=True)),
+                (
+                    "workflow",
+                    models.ForeignKey(
+                        on_delete=django.db.models.deletion.CASCADE,
+                        related_name="history",
+                        to="workflow_engine.workflowinstance",
+                    ),
+                ),
+            ],
+            options={
+                "ordering": ["workflow_id", "seq"],
+                "indexes": [
+                    models.Index(fields=["workflow", "seq"], name="workflow_history_lookup_idx"),
+                    models.Index(fields=["created_at"], name="workflow_history_retention_idx"),
+                ],
+                "constraints": [
+                    models.UniqueConstraint(
+                        fields=("workflow", "seq"), name="workflow_history_seq_uniq"
+                    )
+                ],
+            },
+        ),
+        migrations.CreateModel(
+            name="WorkflowActivityExecution",
+            fields=[
+                (
+                    "id",
+                    models.UUIDField(
+                        default=uuid.uuid4, editable=False, primary_key=True, serialize=False
+                    ),
+                ),
+                ("activity_name", models.CharField(max_length=255)),
+                ("input_hash", models.CharField(max_length=64)),
+                ("result", models.JSONField(blank=True, null=True)),
+                ("created_at", models.DateTimeField(auto_now_add=True)),
+                (
+                    "workflow",
+                    models.ForeignKey(
+                        on_delete=django.db.models.deletion.CASCADE,
+                        related_name="activity_executions",
+                        to="workflow_engine.workflowinstance",
+                    ),
+                ),
+            ],
+            options={
+                "constraints": [
+                    models.UniqueConstraint(
+                        fields=("workflow", "activity_name", "input_hash"),
+                        name="workflow_activity_oaoo_uniq",
+                    )
+                ],
+            },
+        ),
+        migrations.CreateModel(
+            name="WorkflowOutboxRow",
+            fields=[
+                (
+                    "id",
+                    models.UUIDField(
+                        default=uuid.uuid4, editable=False, primary_key=True, serialize=False
+                    ),
+                ),
+                ("step_name", models.CharField(max_length=255)),
+                ("step_input", models.JSONField(default=dict)),
+                (
+                    "status",
+                    models.CharField(
+                        choices=[
+                            ("pending", "Pending"),
+                            ("dispatched", "Dispatched"),
+                            ("done", "Done"),
+                            ("dead", "Dead"),
+                        ],
+                        default="pending",
+                        max_length=16,
+                    ),
+                ),
+                ("attempt_count", models.PositiveIntegerField(default=0)),
+                ("celery_task_id", models.CharField(blank=True, default="", max_length=255)),
+                ("created_at", models.DateTimeField(auto_now_add=True)),
+                ("dispatched_at", models.DateTimeField(blank=True, null=True)),
+                (
+                    "workflow",
+                    models.ForeignKey(
+                        on_delete=django.db.models.deletion.CASCADE,
+                        related_name="outbox_rows",
+                        to="workflow_engine.workflowinstance",
+                    ),
+                ),
+            ],
+            options={
+                "ordering": ["created_at"],
+                "indexes": [
+                    models.Index(fields=["status", "created_at"], name="workflow_outbox_drain_idx")
+                ],
+            },
+        ),
+        migrations.CreateModel(
+            name="WorkflowSignal",
+            fields=[
+                (
+                    "id",
+                    models.UUIDField(
+                        default=uuid.uuid4, editable=False, primary_key=True, serialize=False
+                    ),
+                ),
+                ("signal_name", models.CharField(max_length=255)),
+                ("payload", models.JSONField(default=dict)),
+                ("consumed", models.BooleanField(default=False)),
+                ("created_at", models.DateTimeField(auto_now_add=True)),
+                (
+                    "workflow",
+                    models.ForeignKey(
+                        on_delete=django.db.models.deletion.CASCADE,
+                        related_name="signals",
+                        to="workflow_engine.workflowinstance",
+                    ),
+                ),
+            ],
+            options={
+                "ordering": ["created_at"],
+                "indexes": [
+                    models.Index(
+                        fields=["workflow", "consumed", "created_at"],
+                        name="workflow_signal_inbox_idx",
+                    )
+                ],
+            },
+        ),
+        migrations.CreateModel(
+            name="WorkflowTimer",
+            fields=[
+                (
+                    "id",
+                    models.UUIDField(
+                        default=uuid.uuid4, editable=False, primary_key=True, serialize=False
+                    ),
+                ),
+                ("fire_at", models.DateTimeField()),
+                ("fired", models.BooleanField(default=False)),
+                ("created_at", models.DateTimeField(auto_now_add=True)),
+                (
+                    "workflow",
+                    models.ForeignKey(
+                        on_delete=django.db.models.deletion.CASCADE,
+                        related_name="timers",
+                        to="workflow_engine.workflowinstance",
+                    ),
+                ),
+            ],
+            options={
+                "indexes": [
+                    models.Index(fields=["fired", "fire_at"], name="workflow_timer_due_idx")
+                ],
+            },
+        ),
+    ]