trueppm-api 0.4.0b2__py3-none-any.whl

trueppm_api/apps/webhooks/dispatch.py

@@ -0,0 +1,144 @@
+"""Webhook dispatch helper — called from transaction.on_commit callbacks."""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+import redis as redis_lib
+from kombu.exceptions import (  # type: ignore[import-untyped]
+    OperationalError as KombuOperationalError,
+)
+
+logger = logging.getLogger(__name__)
+
+# Transient broker/connection errors that must not bubble out of dispatch —
+# the delivery row stays PENDING and drain_webhook_queue retries it.  Narrow
+# on purpose so serialization or programming bugs are not silently swallowed.
+_BROKER_ERRORS = (KombuOperationalError, ConnectionError, redis_lib.ConnectionError)
+
+
+def build_delivery_body(
+    webhook: Any,
+    event_type: str,
+    payload: dict[str, Any],
+    sequence: int,
+    project_id: str | None = None,
+) -> dict[str, Any]:
+    """Render ``payload`` for ``webhook``'s format and add the ``_meta`` envelope.
+
+    The single place a delivery body is constructed. It exists because the
+    "Send test" action used to build its ping inline as
+    ``{"event": "ping", "webhook_id": ...}`` — skipping the renderer entirely and
+    omitting ``_meta`` — while the real dispatch path did both (#2884). A
+    ``slack``-format subscription (the modal's default) therefore rejected the test
+    body with 400 ``invalid_payload``, so the admin's only diagnostic tool reported
+    success on a guaranteed failure, and the ping still consumed a sequence number
+    with no ``_meta.sequence`` to match, breaking the documented "always identical"
+    invariant and firing phantom gap alarms on every Test click.
+
+    Args:
+        webhook: The subscription being delivered to (supplies ``format``).
+        event_type: The event type, including the reserved ``ping``.
+        payload: The domain payload to render.
+        sequence: The already-allocated per-subscription sequence number. Passed in
+            rather than allocated here because ``render()`` runs before the delivery
+            row exists, and the stored row must equal the wire body (ADR-0083).
+        project_id: Project the event belongs to, when known. Falls back to the
+            webhook's own project so a program-scoped ping still carries a scope.
+
+    Returns:
+        The exact dict to persist as ``WebhookDelivery.payload`` and POST verbatim.
+    """
+    from trueppm_api.apps.integrations.registry import (
+        OUTGOING_CHANNEL_PROVIDERS,
+        OutgoingChannelEvent,
+    )
+
+    scope_id = project_id or (str(webhook.project_id) if webhook.project_id else "")
+    event = OutgoingChannelEvent(event_type=event_type, project_id=scope_id, payload=payload)
+    # An un-registered format (e.g. an Enterprise provider after a downgrade)
+    # degrades to the raw payload rather than 500ing — matches
+    # ProviderRegistry.get() returning None by design.
+    provider_cls = OUTGOING_CHANNEL_PROVIDERS.get(webhook.format)
+    rendered = provider_cls().render(event) if provider_cls is not None else payload
+    # ``_meta`` is a reserved top-level namespace (ADR-0089): the generic body is a
+    # flat domain dict, so a bare ``sequence`` key could collide with a future event
+    # field, and Slack ignores an unknown ``_meta`` key — one uniform rule covers
+    # every format. A fresh dict so the shared rendered/payload object is never
+    # mutated across the fan-out.
+    return {**rendered, "_meta": {"sequence": sequence}}
+
+
+def dispatch_webhooks(project_id: str, event_type: str, payload: dict[str, Any]) -> None:
+    """Query matching active webhooks and enqueue a delivery task for each.
+
+    This function MUST be called inside a ``transaction.on_commit`` callback
+    (same as ``broadcast_board_event``) so that delivery is never enqueued
+    for a rolled-back mutation.
+
+    Fans out to BOTH project-scoped webhooks (events on this project) and
+    program-scoped webhooks (events on any project within the program that
+    owns this project) per ADR-0076. The two queries are combined with a
+    single ``Q`` union so the database performs the OR in one round-trip.
+    """
+    from django.db.models import Q
+
+    from trueppm_api.apps.projects.models import Project
+    from trueppm_api.apps.webhooks.models import (
+        Webhook,
+        WebhookDelivery,
+        _next_delivery_sequence,
+    )
+    from trueppm_api.apps.webhooks.tasks import deliver_webhook
+
+    # Resolve the project's program (if any) so program-scoped webhooks fire
+    # for events on any of the program's projects. One extra SELECT for the
+    # program FK; cached by Django's queryset evaluation.
+    program_id = Project.objects.filter(pk=project_id).values_list("program_id", flat=True).first()
+
+    scope_filter = Q(project_id=project_id)
+    if program_id is not None:
+        scope_filter |= Q(program_id=program_id)
+
+    webhooks = Webhook.objects.filter(
+        scope_filter,
+        is_active=True,
+        events__contains=[event_type],
+    )
+
+    for webhook in webhooks:
+        # Render per-webhook: each subscription may have a different format
+        # (one project can have a Slack webhook and a generic JSON webhook on
+        # the same event). The rendered dict is frozen onto the delivery row,
+        # so deliver_webhook posts it verbatim and the row is the audit record
+        # of exactly what was sent.
+        #
+        # render() runs before the row exists, so we pre-allocate the sequence
+        # number (#664) and pass it to create() as both the body value and
+        # ``sequence_number`` — WebhookDelivery.save()'s lazy-allocation guard then
+        # no-ops, keeping this a single write where the stored row equals the wire
+        # body (ADR-0083 audit invariant).
+        sequence = _next_delivery_sequence(webhook.id)
+        body = build_delivery_body(webhook, event_type, payload, sequence, str(project_id))
+        delivery = WebhookDelivery.objects.create(
+            webhook=webhook,
+            event_type=event_type,
+            payload=body,
+            sequence_number=sequence,
+        )
+        try:
+            deliver_webhook.delay(str(delivery.pk))
+            logger.debug(
+                "dispatch_webhooks: enqueued delivery %s for webhook %s (%s)",
+                delivery.pk,
+                webhook.pk,
+                event_type,
+            )
+        except _BROKER_ERRORS:
+            # Broker unavailable — delivery row stays PENDING with attempt_count=0
+            # so drain_webhook_queue picks it up within _DRAIN_ORPHAN_MINUTES.
+            logger.warning(
+                "dispatch_webhooks: broker unavailable — delivery %s will be drained",
+                delivery.pk,
+            )

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

@@ -0,0 +1,146 @@
+"""Create Webhook and WebhookDelivery models."""
+
+from __future__ import annotations
+
+import uuid
+
+import django.contrib.postgres.fields
+import django.db.models.deletion
+from django.conf import settings
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+    initial = True
+
+    dependencies = [
+        ("projects", "0013_task_planned_start"),
+        migrations.swappable_dependency(settings.AUTH_USER_MODEL),
+    ]
+
+    operations = [
+        migrations.CreateModel(
+            name="Webhook",
+            fields=[
+                (
+                    "id",
+                    models.UUIDField(
+                        default=uuid.uuid4,
+                        editable=False,
+                        primary_key=True,
+                        serialize=False,
+                    ),
+                ),
+                ("url", models.URLField(max_length=2048)),
+                ("secret", models.CharField(max_length=255)),
+                (
+                    "events",
+                    django.contrib.postgres.fields.ArrayField(
+                        base_field=models.CharField(
+                            choices=[
+                                ("task.created", "Task Created"),
+                                ("task.updated", "Task Updated"),
+                                ("task.deleted", "Task Deleted"),
+                                ("dependency.created", "Dependency Created"),
+                                ("dependency.deleted", "Dependency Deleted"),
+                                ("schedule.recalculated", "Schedule Recalculated"),
+                                ("project.created", "Project Created"),
+                            ],
+                            max_length=30,
+                        ),
+                        size=None,
+                    ),
+                ),
+                ("is_active", models.BooleanField(default=True)),
+                ("created_at", models.DateTimeField(auto_now_add=True)),
+                (
+                    "created_by",
+                    models.ForeignKey(
+                        blank=True,
+                        null=True,
+                        on_delete=django.db.models.deletion.SET_NULL,
+                        to=settings.AUTH_USER_MODEL,
+                    ),
+                ),
+                (
+                    "project",
+                    models.ForeignKey(
+                        on_delete=django.db.models.deletion.CASCADE,
+                        related_name="webhooks",
+                        to="projects.project",
+                    ),
+                ),
+            ],
+            options={
+                "indexes": [
+                    models.Index(
+                        fields=["project", "is_active"],
+                        name="webhook_project_active_idx",
+                    ),
+                ],
+            },
+        ),
+        migrations.CreateModel(
+            name="WebhookDelivery",
+            fields=[
+                (
+                    "id",
+                    models.UUIDField(
+                        default=uuid.uuid4,
+                        editable=False,
+                        primary_key=True,
+                        serialize=False,
+                    ),
+                ),
+                (
+                    "event_type",
+                    models.CharField(
+                        choices=[
+                            ("task.created", "Task Created"),
+                            ("task.updated", "Task Updated"),
+                            ("task.deleted", "Task Deleted"),
+                            ("dependency.created", "Dependency Created"),
+                            ("dependency.deleted", "Dependency Deleted"),
+                            ("schedule.recalculated", "Schedule Recalculated"),
+                            ("project.created", "Project Created"),
+                        ],
+                        max_length=30,
+                    ),
+                ),
+                ("payload", models.JSONField()),
+                (
+                    "status",
+                    models.CharField(
+                        choices=[
+                            ("pending", "Pending"),
+                            ("success", "Success"),
+                            ("failed", "Failed"),
+                        ],
+                        default="pending",
+                        max_length=10,
+                    ),
+                ),
+                ("response_status", models.SmallIntegerField(blank=True, null=True)),
+                ("attempt_count", models.SmallIntegerField(default=0)),
+                ("created_at", models.DateTimeField(auto_now_add=True)),
+                ("completed_at", models.DateTimeField(blank=True, null=True)),
+                (
+                    "webhook",
+                    models.ForeignKey(
+                        on_delete=django.db.models.deletion.CASCADE,
+                        related_name="deliveries",
+                        to="webhooks.webhook",
+                    ),
+                ),
+            ],
+            options={
+                "ordering": ["-created_at"],
+                "indexes": [
+                    models.Index(
+                        fields=["webhook", "created_at"],
+                        name="delivery_webhook_created_idx",
+                    ),
+                ],
+            },
+        ),
+    ]

trueppm_api/apps/webhooks/migrations/0001_squashed_0007_sprint_lifecycle_events.py

@@ -0,0 +1,243 @@
+# Generated by Django 5.2.14 on 2026-06-23 21:38
+
+import uuid
+
+import django.contrib.postgres.fields
+import django.db.models.deletion
+from django.conf import settings
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+    replaces = [
+        ("webhooks", "0001_initial"),
+        ("webhooks", "0002_alter_webhook_events"),
+        ("webhooks", "0003_delivery_status_created_idx"),
+        ("webhooks", "0004_webhook_program_alter_webhook_project_and_more"),
+        ("webhooks", "0005_webhook_delivery_sequence_numbers"),
+        ("webhooks", "0006_webhook_format_alter_webhook_events_and_more"),
+        ("webhooks", "0007_sprint_lifecycle_events"),
+    ]
+
+    initial = True
+
+    dependencies = [
+        ("projects", "0013_task_planned_start"),
+        ("projects", "0039_apitoken_and_more"),
+        migrations.swappable_dependency(settings.AUTH_USER_MODEL),
+    ]
+
+    operations = [
+        migrations.CreateModel(
+            name="Webhook",
+            fields=[
+                (
+                    "id",
+                    models.UUIDField(
+                        default=uuid.uuid4, editable=False, primary_key=True, serialize=False
+                    ),
+                ),
+                ("url", models.URLField(max_length=2048)),
+                ("secret", models.CharField(max_length=255)),
+                (
+                    "events",
+                    django.contrib.postgres.fields.ArrayField(
+                        base_field=models.CharField(
+                            choices=[
+                                ("task.created", "Task Created"),
+                                ("task.updated", "Task Updated"),
+                                ("task.deleted", "Task Deleted"),
+                                ("dependency.created", "Dependency Created"),
+                                ("dependency.deleted", "Dependency Deleted"),
+                                ("schedule.recalculated", "Schedule Recalculated"),
+                                ("project.created", "Project Created"),
+                            ],
+                            max_length=30,
+                        ),
+                        help_text="List of event types this webhook subscribes to.",
+                        size=None,
+                    ),
+                ),
+                ("is_active", models.BooleanField(default=True)),
+                ("created_at", models.DateTimeField(auto_now_add=True)),
+                (
+                    "created_by",
+                    models.ForeignKey(
+                        blank=True,
+                        null=True,
+                        on_delete=django.db.models.deletion.SET_NULL,
+                        to=settings.AUTH_USER_MODEL,
+                    ),
+                ),
+                (
+                    "project",
+                    models.ForeignKey(
+                        blank=True,
+                        help_text="Set when the webhook fires for events on a single project. Exactly one of project/program is non-null (DB constraint).",
+                        null=True,
+                        on_delete=django.db.models.deletion.CASCADE,
+                        related_name="webhooks",
+                        to="projects.project",
+                    ),
+                ),
+                (
+                    "program",
+                    models.ForeignKey(
+                        blank=True,
+                        help_text="Set when the webhook fires for events on any project within this program. Exactly one of project/program is non-null (DB constraint).",
+                        null=True,
+                        on_delete=django.db.models.deletion.CASCADE,
+                        related_name="webhooks",
+                        to="projects.program",
+                    ),
+                ),
+            ],
+            options={
+                "indexes": [
+                    models.Index(fields=["project", "is_active"], name="webhook_project_active_idx")
+                ],
+            },
+        ),
+        migrations.CreateModel(
+            name="WebhookDelivery",
+            fields=[
+                (
+                    "id",
+                    models.UUIDField(
+                        default=uuid.uuid4, editable=False, primary_key=True, serialize=False
+                    ),
+                ),
+                (
+                    "event_type",
+                    models.CharField(
+                        choices=[
+                            ("task.created", "Task Created"),
+                            ("task.updated", "Task Updated"),
+                            ("task.deleted", "Task Deleted"),
+                            ("dependency.created", "Dependency Created"),
+                            ("dependency.deleted", "Dependency Deleted"),
+                            ("schedule.recalculated", "Schedule Recalculated"),
+                            ("project.created", "Project Created"),
+                        ],
+                        max_length=30,
+                    ),
+                ),
+                ("payload", models.JSONField()),
+                (
+                    "status",
+                    models.CharField(
+                        choices=[
+                            ("pending", "Pending"),
+                            ("success", "Success"),
+                            ("failed", "Failed"),
+                        ],
+                        default="pending",
+                        max_length=10,
+                    ),
+                ),
+                ("response_status", models.SmallIntegerField(blank=True, null=True)),
+                ("attempt_count", models.SmallIntegerField(default=0)),
+                ("created_at", models.DateTimeField(auto_now_add=True)),
+                ("completed_at", models.DateTimeField(blank=True, null=True)),
+                (
+                    "webhook",
+                    models.ForeignKey(
+                        on_delete=django.db.models.deletion.CASCADE,
+                        related_name="deliveries",
+                        to="webhooks.webhook",
+                    ),
+                ),
+            ],
+            options={
+                "ordering": ["-created_at"],
+                "indexes": [
+                    models.Index(
+                        fields=["webhook", "created_at"], name="delivery_webhook_created_idx"
+                    ),
+                    models.Index(
+                        fields=["status", "created_at"], name="delivery_status_created_idx"
+                    ),
+                ],
+            },
+        ),
+        migrations.AddIndex(
+            model_name="webhook",
+            index=models.Index(fields=["program", "is_active"], name="webhook_program_active_idx"),
+        ),
+        migrations.AddConstraint(
+            model_name="webhook",
+            constraint=models.CheckConstraint(
+                condition=models.Q(
+                    models.Q(("program__isnull", True), ("project__isnull", False)),
+                    models.Q(("program__isnull", False), ("project__isnull", True)),
+                    _connector="OR",
+                ),
+                name="webhook_scope_xor",
+            ),
+        ),
+        migrations.AddField(
+            model_name="webhookdelivery",
+            name="sequence_number",
+            field=models.BigIntegerField(default=0, editable=False),
+        ),
+        migrations.AddField(
+            model_name="webhook",
+            name="delivery_sequence",
+            field=models.BigIntegerField(default=0, editable=False),
+        ),
+        migrations.AddField(
+            model_name="webhook",
+            name="format",
+            field=models.CharField(default="generic", max_length=32),
+        ),
+        migrations.AlterField(
+            model_name="webhook",
+            name="events",
+            field=django.contrib.postgres.fields.ArrayField(
+                base_field=models.CharField(
+                    choices=[
+                        ("task.created", "Task Created"),
+                        ("task.updated", "Task Updated"),
+                        ("task.deleted", "Task Deleted"),
+                        ("dependency.created", "Dependency Created"),
+                        ("dependency.deleted", "Dependency Deleted"),
+                        ("schedule.recalculated", "Schedule Recalculated"),
+                        ("project.created", "Project Created"),
+                        ("task.assigned", "Task Assigned"),
+                        ("task.assignee_changed", "Task Assignee Changed"),
+                        ("task.mentioned", "Task Mentioned"),
+                        ("task.due_date_changed", "Task Due Date Changed"),
+                        ("sprint.activated", "Sprint Activated"),
+                        ("sprint.closed", "Sprint Closed"),
+                        ("sprint.scope_changed", "Sprint Scope Changed"),
+                    ],
+                    max_length=30,
+                ),
+                help_text="List of event types this webhook subscribes to.",
+                size=None,
+            ),
+        ),
+        migrations.AlterField(
+            model_name="webhookdelivery",
+            name="event_type",
+            field=models.CharField(
+                choices=[
+                    ("task.created", "Task Created"),
+                    ("task.updated", "Task Updated"),
+                    ("task.deleted", "Task Deleted"),
+                    ("dependency.created", "Dependency Created"),
+                    ("dependency.deleted", "Dependency Deleted"),
+                    ("schedule.recalculated", "Schedule Recalculated"),
+                    ("project.created", "Project Created"),
+                    ("task.assigned", "Task Assigned"),
+                    ("task.assignee_changed", "Task Assignee Changed"),
+                    ("task.mentioned", "Task Mentioned"),
+                    ("task.due_date_changed", "Task Due Date Changed"),
+                    ("sprint.activated", "Sprint Activated"),
+                    ("sprint.closed", "Sprint Closed"),
+                    ("sprint.scope_changed", "Sprint Scope Changed"),
+                ],
+                max_length=30,
+            ),
+        ),
+    ]

trueppm_api/apps/webhooks/migrations/0002_alter_webhook_events.py

@@ -0,0 +1,32 @@
+# Generated by Django 6.0.3 on 2026-04-11 23:42
+
+import django.contrib.postgres.fields
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+    dependencies = [
+        ("webhooks", "0001_initial"),
+    ]
+
+    operations = [
+        migrations.AlterField(
+            model_name="webhook",
+            name="events",
+            field=django.contrib.postgres.fields.ArrayField(
+                base_field=models.CharField(
+                    choices=[
+                        ("task.created", "Task Created"),
+                        ("task.updated", "Task Updated"),
+                        ("task.deleted", "Task Deleted"),
+                        ("dependency.created", "Dependency Created"),
+                        ("dependency.deleted", "Dependency Deleted"),
+                        ("schedule.recalculated", "Schedule Recalculated"),
+                        ("project.created", "Project Created"),
+                    ],
+                    max_length=30,
+                ),
+                help_text="List of event types this webhook subscribes to.",
+            ),
+        ),
+    ]

trueppm_api/apps/webhooks/migrations/0003_delivery_status_created_idx.py

@@ -0,0 +1,17 @@
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+    dependencies = [
+        ("webhooks", "0002_alter_webhook_events"),
+    ]
+
+    operations = [
+        migrations.AddIndex(
+            model_name="webhookdelivery",
+            index=models.Index(
+                fields=["status", "created_at"],
+                name="delivery_status_created_idx",
+            ),
+        ),
+    ]

trueppm_api/apps/webhooks/migrations/0004_webhook_program_alter_webhook_project_and_more.py

@@ -0,0 +1,64 @@
+# Generated by Django 6.0.3 on 2026-05-21 16:36
+
+import django.db.models.deletion
+from django.conf import settings
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+    dependencies = [
+        ("projects", "0039_apitoken_and_more"),
+        ("webhooks", "0003_delivery_status_created_idx"),
+        migrations.swappable_dependency(settings.AUTH_USER_MODEL),
+    ]
+
+    operations = [
+        migrations.AddField(
+            model_name="webhook",
+            name="program",
+            field=models.ForeignKey(
+                blank=True,
+                help_text=(
+                    "Set when the webhook fires for events on any project within "
+                    "this program. Exactly one of project/program is non-null (DB constraint)."
+                ),
+                null=True,
+                on_delete=django.db.models.deletion.CASCADE,
+                related_name="webhooks",
+                to="projects.program",
+            ),
+        ),
+        migrations.AlterField(
+            model_name="webhook",
+            name="project",
+            field=models.ForeignKey(
+                blank=True,
+                help_text=(
+                    "Set when the webhook fires for events on a single project. "
+                    "Exactly one of project/program is non-null (DB constraint)."
+                ),
+                null=True,
+                on_delete=django.db.models.deletion.CASCADE,
+                related_name="webhooks",
+                to="projects.project",
+            ),
+        ),
+        migrations.AddIndex(
+            model_name="webhook",
+            index=models.Index(fields=["program", "is_active"], name="webhook_program_active_idx"),
+        ),
+        # safe-constraint: `program` is added by this migration and `project` was NOT
+        # NULL until the AlterField above, so every pre-existing row is (project set,
+        # program null) — the constraint's first branch.
+        migrations.AddConstraint(
+            model_name="webhook",
+            constraint=models.CheckConstraint(
+                condition=models.Q(
+                    models.Q(("program__isnull", True), ("project__isnull", False)),
+                    models.Q(("program__isnull", False), ("project__isnull", True)),
+                    _connector="OR",
+                ),
+                name="webhook_scope_xor",
+            ),
+        ),
+    ]

trueppm_api/apps/webhooks/migrations/0005_webhook_delivery_sequence_numbers.py

@@ -0,0 +1,30 @@
+"""Per-subscription outgoing webhook sequence numbers (#664).
+
+Adds a monotonic ``delivery_sequence`` counter to ``Webhook`` and a
+``sequence_number`` to each ``WebhookDelivery``, then backfills existing rows so
+the counter is contiguous and continues correctly for new deliveries.
+"""
+
+from django.db import migrations, models
+
+from trueppm_api.apps.webhooks.backfill import backfill_sequence_numbers, reverse_backfill
+
+
+class Migration(migrations.Migration):
+    dependencies = [
+        ("webhooks", "0004_webhook_program_alter_webhook_project_and_more"),
+    ]
+
+    operations = [
+        migrations.AddField(
+            model_name="webhook",
+            name="delivery_sequence",
+            field=models.BigIntegerField(default=0, editable=False),
+        ),
+        migrations.AddField(
+            model_name="webhookdelivery",
+            name="sequence_number",
+            field=models.BigIntegerField(default=0, editable=False),
+        ),
+        migrations.RunPython(backfill_sequence_numbers, reverse_backfill, elidable=True),
+    ]