trueppm-api 0.4.0b2__py3-none-any.whl

trueppm_api/apps/integrations/serializers.py

@@ -0,0 +1,453 @@
+"""DRF serializers for the ``/me/credentials/`` viewset (ADR-0049 §3).
+
+Three serializers, all built around the rule that the encrypted PAT
+ciphertext is **never** rendered back to the client — not even to the
+authenticated owner. The list response is intentionally a derived view
+("does a row exist? when was it last used? when does it expire?"); read
+of the underlying secret only happens server-side when the git-aware
+tasks refresh endpoint (#637) needs it.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+from urllib.parse import urlparse
+
+from django.core.exceptions import ValidationError as DjangoValidationError
+from django.core.validators import URLValidator
+from rest_framework import serializers
+
+from .models import IntegrationCredential, TaskLink
+from .registry import TASK_LINK_PROVIDERS
+
+
+class CredentialSummarySerializer(serializers.Serializer[Any]):
+    """One row per provider in the list response.
+
+    Surfaces:
+    - ``provider`` (machine key) and ``name`` (human label) for the UI header
+    - ``exists`` — drives the Connected / Not connected pill
+    - ``base_url`` for self-hosted users
+    - ``created_at`` / ``updated_at`` / ``last_used_at`` for the audit trail
+    - ``expires_at`` for the "expires in X days" hint
+    - ``requires_credential`` so the UI can hide the Connect button for the
+      ``generic`` provider when no PAT is needed
+
+    Notably absent: any field derived from ``secret_ciphertext``.
+    """
+
+    provider = serializers.CharField()
+    name = serializers.CharField()
+    exists = serializers.BooleanField()
+    base_url = serializers.CharField(allow_blank=True, required=False)
+    created_at = serializers.DateTimeField(allow_null=True)
+    updated_at = serializers.DateTimeField(allow_null=True)
+    last_used_at = serializers.DateTimeField(allow_null=True)
+    expires_at = serializers.DateTimeField(allow_null=True)
+    requires_credential = serializers.BooleanField()
+
+
+class CredentialUpsertSerializer(serializers.Serializer[Any]):
+    """Payload for ``POST /me/credentials/{provider}/`` (connect or rotate).
+
+    Validation rules:
+    - ``secret`` is required and non-empty (the encryption helper refuses
+      empty plaintext anyway; rejecting here gives a clean 400).
+    - ``secret`` is write-only — never echoed back.
+    - ``base_url`` is optional. When present it must be an ``http://`` or
+      ``https://`` URL; ``file://`` / ``javascript:`` / ``gopher://`` /
+      similar schemes are rejected here. This serializer is the cheap first
+      line of defense; the resolver-level SSRF guard (block RFC1918, link-local,
+      cloud metadata at connect time) lands with #677's PAT verification in
+      ``integrations.http`` and is reused by #637's git-link refresh.
+    - ``expires_at`` is optional and informational only.
+    """
+
+    secret = serializers.CharField(
+        write_only=True, min_length=1, max_length=4096, trim_whitespace=False
+    )
+    base_url = serializers.CharField(required=False, allow_blank=True, max_length=512)
+    expires_at = serializers.DateTimeField(required=False, allow_null=True)
+
+    def validate_secret(self, value: str) -> str:
+        # trim_whitespace=False above lets us catch the all-whitespace case
+        # explicitly so the error message is clear.
+        if not value.strip():
+            raise serializers.ValidationError("Secret must not be blank.")
+        return value
+
+    def validate_base_url(self, value: str) -> str:
+        if not value:
+            return value
+        if "://" not in value:
+            raise serializers.ValidationError(
+                "Host URL must include a scheme (https://example.com)."
+            )
+        parsed = urlparse(value)
+        if parsed.scheme.lower() not in ("http", "https"):
+            raise serializers.ValidationError(
+                f"Host URL scheme {parsed.scheme.lower()!r} is not allowed. Use http or https."
+            )
+        # A host URL is a base — a path (self-hosted GitLab relative root, e.g.
+        # https://example.com/gitlab) is fine, but a query string or fragment is
+        # never meaningful and would corrupt the constructed ``…/api/v4/user``
+        # verify URL (e.g. https://host#frag/api/v4/user). Reject them here.
+        if parsed.query or parsed.fragment:
+            raise serializers.ValidationError(
+                "Host URL must not contain a query string or fragment."
+            )
+        return value
+
+
+class CredentialVerificationErrorSerializer(serializers.Serializer[Any]):
+    """422 body when live PAT verification fails (#677).
+
+    Documents the shape the Connected Accounts page reads on a rejected
+    connect/rotate: a human ``detail``, the stable ``code``
+    ``provider_verification_failed``, and a machine-readable ``reason`` the
+    client can branch on (``invalid_token``, ``provider_unreachable``,
+    ``provider_timeout``, ``blocked_host``).
+    """
+
+    detail = serializers.CharField()
+    code = serializers.CharField()
+    reason = serializers.CharField(allow_null=True)
+
+
+class TaskLinkSerializer(serializers.ModelSerializer[TaskLink]):
+    """A git/PM link on a task (ADR-0049 §3, #637; redesign #970).
+
+    Client-writable: ``url``, ``custom_title``, ``labels``, ``display_order``.
+    ``provider`` is resolved server-side from the URL + the user's connected
+    hosts, and ``status``/``title``/``fetched_at`` are populated by the refresh
+    endpoint — never trusted from the client. ``server_version`` is exposed so
+    offline clients can reconcile against the sync delta.
+    """
+
+    # Declared as a plain CharField (not the auto ModelSerializer URLField) so a
+    # bare host like "github.com/acme/api" survives field validation and reaches
+    # ``validate_url``, which prepends the scheme before validating (#970). A
+    # strict URLField would 400 it before normalization could run.
+    url = serializers.CharField(max_length=2048, trim_whitespace=True)
+    # Optional free-text tags; entries are trimmed/de-duped/capped in
+    # ``validate_labels``. ``allow_blank`` on the child so a stray "" is dropped
+    # rather than 400-ing the whole request.
+    labels = serializers.ListField(
+        child=serializers.CharField(max_length=40, allow_blank=True),
+        required=False,
+    )
+
+    class Meta:
+        model = TaskLink
+        fields = [
+            "id",
+            "url",
+            "provider",
+            "title",
+            "custom_title",
+            "labels",
+            "status",
+            "fetched_at",
+            # Cloud-file preview cache (#571, ADR-0163) — server-owned, populated
+            # by a file provider's OpenGraph unfurl on refresh; read-only.
+            "description",
+            "thumbnail_url",
+            "preview_type",
+            "display_order",
+            "server_version",
+        ]
+        read_only_fields = [
+            "id",
+            "provider",
+            "title",
+            "status",
+            "fetched_at",
+            "description",
+            "thumbnail_url",
+            "preview_type",
+            "server_version",
+        ]
+
+    def validate_url(self, value: str) -> str:
+        """Normalize a scheme-less URL to ``https://`` then validate (#970).
+
+        Users routinely paste a bare ``github.com/acme/api/pull/5`` — prepend
+        ``https://`` rather than reject it. Anything with an explicit scheme is
+        left as-is so a deliberate ``ftp://`` / ``javascript:`` is still caught
+        by the http(s)-only ``URLValidator``. The resolver-level SSRF guard runs
+        separately at refresh time when the URL is actually fetched.
+        """
+        raw = (value or "").strip()
+        if not raw:
+            raise serializers.ValidationError("Enter a URL.")
+        if "://" not in raw:
+            raw = "https://" + raw.lstrip("/")
+        try:
+            URLValidator(schemes=["http", "https"])(raw)
+        except DjangoValidationError:
+            raise serializers.ValidationError("Enter a valid http(s) web address.") from None
+        return raw
+
+    def validate_labels(self, value: list[str]) -> list[str]:
+        """Trim, drop blanks, de-dupe (case-insensitive), and cap at 12 (#970)."""
+        cleaned: list[str] = []
+        seen: set[str] = set()
+        for raw in value:
+            label = (raw or "").strip()
+            if not label:
+                continue
+            key = label.casefold()
+            if key in seen:
+                continue
+            seen.add(key)
+            cleaned.append(label)
+        if len(cleaned) > 12:
+            raise serializers.ValidationError("A link can have at most 12 labels.")
+        return cleaned
+
+    def validate_custom_title(self, value: str) -> str:
+        return (value or "").strip()
+
+
+class TaskLinkCredentialRequiredSerializer(serializers.Serializer[Any]):
+    """422 body when refresh needs a PAT the caller hasn't connected (#637).
+
+    Lets the task-detail UI swap the status badge for a "Connect {provider}"
+    affordance pointing at ``/me/settings/connected-accounts`` instead of
+    leaving the link stuck at ``unknown``.
+    """
+
+    detail = serializers.CharField()
+    code = serializers.CharField()
+    provider = serializers.CharField()
+    requires_credential = serializers.BooleanField()
+
+
+def serialize_credential_summaries(
+    user: Any,
+    queryset: list[IntegrationCredential],
+) -> list[dict[str, Any]]:
+    """Build the list-response payload for ``GET /me/credentials/``.
+
+    Iterates the registered providers (so the response always includes one
+    entry per provider, whether the user has a row or not) and joins the
+    user's existing rows by ``provider`` key. This is the shape the
+    Connected Accounts page consumes — it never has to reason about
+    "missing rows" vs "no providers registered."
+    """
+    rows_by_provider: dict[str, IntegrationCredential] = {row.provider: row for row in queryset}
+    out: list[dict[str, Any]] = []
+    for key in TASK_LINK_PROVIDERS:
+        handler = TASK_LINK_PROVIDERS.get(key)
+        if handler is None:  # pragma: no cover — keys() iterates known
+            continue
+        # Skip providers that never store a credential (cloud-file preview
+        # providers, #571) — the Connected Accounts page is a PAT manager, and
+        # an account with nothing to connect would only confuse.
+        if not getattr(handler, "connectable", True):
+            continue
+        row = rows_by_provider.get(key)
+        out.append(
+            {
+                "provider": key,
+                "name": getattr(handler, "label", key),
+                "exists": row is not None,
+                "base_url": row.base_url if row else "",
+                "created_at": row.created_at if row else None,
+                "updated_at": row.updated_at if row else None,
+                "last_used_at": row.last_used_at if row else None,
+                "expires_at": row.expires_at if row else None,
+                "requires_credential": getattr(handler, "requires_credential", True),
+            }
+        )
+    return out
+
+
+#: Outcomes a **verified** delivery can produce (#2882). Published as an ``enum`` on
+#: ``GitAutomationConfig.last_delivery_outcome`` so an SDK consumer can discover the
+#: vocabulary the web client renders as user-facing copy. Kept as a module constant,
+#: not re-typed inline, because the receiver and the schema must not drift.
+GIT_DELIVERY_OUTCOMES = (
+    "malformed_payload",
+    "ignored",
+    "draft",
+    "duplicate",
+    "no_url",
+    "no_link",
+    "noop_forward_only",
+    "opened_review",
+    "merged_complete",
+)
+
+#: Outcomes a **refused** (pre-verification) delivery can produce. ``no_automation``
+#: is absent on purpose: that refusal has no ``BoardAutomation`` row to write to, so
+#: it can only ever reach the receiver log — publishing it as a readable value would
+#: be advertising a field state that cannot occur.
+GIT_REFUSAL_OUTCOMES = (
+    "automation_disabled",
+    "no_secret",
+    "unknown_provider",
+    "secret_unreadable",
+    "bad_signature",
+    "project_archived",
+)
+
+
+class GitAutomationConfigSerializer(serializers.Serializer[Any]):
+    """Read view of a project's Git-event card automation (#329, ADR-0158).
+
+    Never renders the secret — only whether one is set. ``webhook_url`` is the
+    per-project endpoint the admin pastes into GitHub/GitLab; the secret travels
+    in the provider's signature header, never in the URL.
+    """
+
+    enabled = serializers.BooleanField()
+    secret_set = serializers.BooleanField()
+    webhook_url = serializers.CharField()
+    configured_by = serializers.UUIDField(allow_null=True)
+    secret_set_at = serializers.DateTimeField(allow_null=True)
+    updated_at = serializers.DateTimeField(allow_null=True)
+    # Delivery diagnostics (#2882). Before these, a webhook that failed or matched
+    # nothing was invisible on every surface an operator can reach: the receiver
+    # logged nothing, every non-auth outcome was a 200 so the provider showed a green
+    # check, and the settings card had no error state at all. These are what the
+    # "Last delivery" and "Last refused delivery" rows on that card read.
+    #
+    # ``ChoiceField``, not ``CharField``, and not for validation — these are
+    # read-only outputs. It is so the vocabulary reaches ``openapi.json`` as an
+    # ``enum``. The same MR gives the receiver's own ``reason`` a documented enum, and
+    # publishing its superset as a bare ``string`` here would leave an SDK consumer no
+    # way to discover the values, while the web client maps every one of them to
+    # user-facing copy. A token the server can emit and a client cannot look up is the
+    # declared-vs-actual gap this issue is about.
+    last_delivery_at = serializers.DateTimeField(allow_null=True)
+    last_delivery_outcome = serializers.ChoiceField(
+        choices=GIT_DELIVERY_OUTCOMES,
+        allow_blank=True,
+        help_text=(
+            "Outcome of the last delivery whose signature VERIFIED. Empty until one "
+            "arrives. Trustworthy: the caller proved it holds the project's secret."
+        ),
+    )
+    last_delivery_provider = serializers.CharField(allow_blank=True)
+    # Deliberately separate from the fields above — see BoardAutomation. A refusal is
+    # recorded before verification, so an unauthenticated caller holding the project
+    # UUID can write here at will; keeping it out of ``last_delivery_*`` is what stops
+    # that caller erasing a genuine outcome or provoking a needless secret rotation.
+    last_refusal_at = serializers.DateTimeField(allow_null=True)
+    last_refusal_outcome = serializers.ChoiceField(
+        choices=GIT_REFUSAL_OUTCOMES,
+        allow_blank=True,
+        help_text=(
+            "Why the last REFUSED delivery was refused. The caller saw only an opaque "
+            "404. Diagnostic, not evidence: the endpoint is public, so this may record "
+            "unauthenticated traffic rather than your provider."
+        ),
+    )
+    last_refusal_provider = serializers.CharField(allow_blank=True)
+
+
+class GitAutomationUpdateSerializer(serializers.Serializer[Any]):
+    """Write payload for toggling Git-event automation (project-admin only)."""
+
+    enabled = serializers.BooleanField()
+
+
+class GitAutomationSecretSerializer(serializers.Serializer[Any]):
+    """One-time rotate-secret response (``201``) for ``.../rotate-secret/``.
+
+    Declared so the published schema stops describing this endpoint as
+    "200: No response body" — it returns **201** with a plaintext secret that is
+    never retrievable again, which is precisely the shape an integrator has to know
+    in advance (#2882).
+    """
+
+    secret = serializers.CharField()
+    webhook_url = serializers.CharField()
+    secret_set_at = serializers.DateTimeField(allow_null=True)
+
+
+#: Raw OpenAPI schema for the inbound receiver's **request** body (#3364).
+#:
+#: The receiver published no ``requestBody`` at all (``request=None``), which told a
+#: generated client the endpoint accepts nothing — while the handler reads
+#: ``request.data`` and refuses a non-object with a 400. There is no serializer to
+#: name here and there should not be: the body is the *provider's* pull/merge-request
+#: event, whose shape GitHub and GitLab own and change without asking us. Declaring a
+#: fixed schema would publish a contract we do not control and cannot keep true.
+#:
+#: So this declares exactly what the receiver actually requires — a JSON **object**,
+#: any keys — and says in prose where the real shape is defined. ``parse_envelope``
+#: reads a handful of provider-specific keys out of it and ignores the rest, which is
+#: why "an object" is not a cop-out but the honest ceiling on what we can promise.
+GIT_WEBHOOK_PAYLOAD_SCHEMA: dict[str, Any] = {
+    "type": "object",
+    "additionalProperties": True,
+    "description": (
+        "The provider's own webhook event payload, forwarded verbatim — GitHub's "
+        "`pull_request` event or GitLab's `merge_request` event. Its shape is defined "
+        "by the provider, not by TruePPM, so it is typed here only as far as this "
+        "receiver actually constrains it: a JSON object. A non-object body is refused "
+        "with a 400 once the signature has verified. The signature is computed over "
+        "these exact bytes, so the body must be sent unmodified."
+    ),
+}
+
+
+#: Raw OpenAPI schema for the inbound receiver's ``200`` body (#2882).
+#:
+#: The published schema declared all four Git endpoints as "200: No response body",
+#: while the receiver actually returns four distinct shapes and a ``reason`` enum that
+#: was discoverable only by reading Python. Expressed as a raw schema rather than a
+#: ``Serializer`` for one blunt reason: the body carries a ``from`` key, and ``from``
+#: is a Python keyword, so it cannot be a serializer class attribute. Renaming the
+#: wire field to suit the tooling would be the tail wagging the dog.
+GIT_WEBHOOK_RESULT_SCHEMA: dict[str, Any] = {
+    "type": "object",
+    "properties": {
+        "matched": {
+            "type": "boolean",
+            "description": "A task in this project is linked to the PR/MR in the payload.",
+        },
+        "moved": {"type": "boolean", "description": "The linked card's status changed."},
+        "task": {
+            "type": "string",
+            "format": "uuid",
+            "nullable": True,
+            "description": "The matched task, when there was one.",
+        },
+        "from": {"type": "string", "nullable": True, "description": "Board status before."},
+        "to": {"type": "string", "nullable": True, "description": "Board status after."},
+        "ignored": {
+            "type": "string",
+            "description": (
+                "The provider's own event name, present when the event is not one this "
+                "receiver acts on."
+            ),
+        },
+        "reason": {
+            "type": "string",
+            "enum": [
+                "draft",
+                "duplicate",
+                "no_url",
+                "no_link",
+                "noop_forward_only",
+                "opened_review",
+                "merged_complete",
+            ],
+            "description": (
+                "draft: a draft/WIP pull/merge request opened — deliberately does not "
+                "promote the card, the promotion happens when it is marked ready for "
+                "review. duplicate: a provider redelivery of an event already "
+                "processed. no_url: the payload carried no pull/merge request URL. "
+                "no_link: no task in this project has a link pointing at this PR/MR, so "
+                "there is no card to move — this is the most common reason a correctly "
+                "configured webhook moves nothing. noop_forward_only: the card is "
+                "already at or past the target status. opened_review / merged_complete: "
+                "a card moved."
+            ),
+        },
+    },
+    "required": ["matched", "moved"],
+}

trueppm_api/apps/integrations/services.py

@@ -0,0 +1,171 @@
+"""Service layer for user-scoped external task sync (ADR-0097 §4).
+
+``enqueue_external_sync`` is the single entry point that queues a read-only pull
+of one ``(user, source)`` connection. It follows the canonical transactional
+outbox shape (ADR-0017/0019): write an ``ExternalSyncRequest`` row inside a
+transaction, then a best-effort ``transaction.on_commit`` dispatch of the
+``external_sync`` Celery task. If the broker is down the row stays ``PENDING``
+and the 300 s ``drain-external-sync`` Beat task recovers it.
+
+Never call ``external_sync.delay()`` directly from a view — the outbox row is
+what makes the pull survive a broker outage (ADR-0097 §Durable Execution #4).
+"""
+
+from __future__ import annotations
+
+import logging
+import uuid
+
+from django.db import IntegrityError, transaction
+from django.utils import timezone
+
+from .external_sources import EXTERNAL_TASK_SOURCES
+from .models import (
+    ExternalSyncRequest,
+    ExternalSyncRequestReason,
+    ExternalSyncRequestStatus,
+)
+
+logger = logging.getLogger(__name__)
+
+# Minimum spacing between *manual* refreshes of one connection (ADR-0097
+# §Resolution #5 "per-user cooldown ≥60 s"). The partial-unique constraint
+# already coalesces a burst onto one in-flight pull; this outer bound also
+# rate-limits back-to-back refreshes *after* a pull completes, so a user
+# hammering the button cannot walk Jira's rate budget. The opt-in poll and the
+# on-open refresh are exempt — they are already low-frequency by construction.
+MANUAL_SYNC_COOLDOWN_SECONDS = 60
+
+
+class SyncCooldownActive(Exception):
+    """A manual refresh was requested inside the per-connection cooldown window.
+
+    Carries ``retry_after`` (seconds) so the view can answer ``429`` with a
+    ``Retry-After`` header rather than silently swallowing the request.
+    """
+
+    def __init__(self, retry_after: int) -> None:
+        self.retry_after = retry_after
+        super().__init__(f"Sync cooldown active — retry in {retry_after}s")
+
+
+def enqueue_external_sync(
+    user_id: int,
+    source: str,
+    *,
+    reason: ExternalSyncRequestReason = ExternalSyncRequestReason.MANUAL,
+) -> ExternalSyncRequest | None:
+    """Queue a read-only pull of one external-source connection (outbox + dispatch).
+
+    Idempotent: if a ``PENDING`` row already exists for ``(user, source)`` it is
+    adopted (coalescing a burst of triggers onto one pull) rather than stacking a
+    second Jira fetch — mirrors ``scheduling.enqueue_recalculate``.
+
+    Args:
+        user_id: Owner of the connection (rows are strictly per-user).
+        source: An ``EXTERNAL_TASK_SOURCES`` key (e.g. ``"jira"``).
+        reason: Why the pull was queued — forensics only.
+
+    Returns:
+        The queued (or adopted) ``ExternalSyncRequest``, or ``None`` if a race
+        transitioned the pending row out from under the adopt path.
+
+    Raises:
+        ValueError: ``source`` is not a registered external task source.
+        SyncCooldownActive: ``reason`` is ``MANUAL`` and the last request for this
+            connection is inside :data:`MANUAL_SYNC_COOLDOWN_SECONDS`.
+    """
+    if EXTERNAL_TASK_SOURCES.get(source) is None:
+        raise ValueError(f"Unknown external task source {source!r}.")
+
+    now = timezone.now()
+
+    # Manual-refresh cooldown (ADR-0097 §Resolution #5). Measured from the most
+    # recent request's ``requested_at`` regardless of its terminal state, so a
+    # completed pull still blocks an immediate re-trigger. Poll / on-open reasons
+    # skip this — they are already spaced by their Beat cadence.
+    if reason == ExternalSyncRequestReason.MANUAL:
+        last = (
+            ExternalSyncRequest.objects.filter(user_id=user_id, source=source)
+            .order_by("-requested_at")
+            .first()
+        )
+        if last is not None:
+            elapsed = (now - last.requested_at).total_seconds()
+            if elapsed < MANUAL_SYNC_COOLDOWN_SECONDS:
+                raise SyncCooldownActive(
+                    retry_after=max(1, int(MANUAL_SYNC_COOLDOWN_SECONDS - elapsed))
+                )
+
+    req: ExternalSyncRequest
+    try:
+        with transaction.atomic():
+            req = ExternalSyncRequest.objects.create(user_id=user_id, source=source, reason=reason)
+    except IntegrityError:
+        # A PENDING row already exists (partial-unique constraint). Adopt it — it
+        # may be stranded (its own dispatch failed on a broker blip) and every
+        # subsequent trigger would otherwise pile up behind it. Re-dispatching now
+        # collapses them into one pull with the latest Jira data.
+        existing = ExternalSyncRequest.objects.filter(
+            user_id=user_id,
+            source=source,
+            status=ExternalSyncRequestStatus.PENDING,
+        ).first()
+        if existing is None:
+            # Race: the row left PENDING between the insert and this lookup — the
+            # other writer already dispatched it, so there is nothing to do.
+            return None
+        req = existing
+
+        # An adopted row may be a rate-limited pull sitting out the clock the
+        # source itself gave us (``_requeue_rate_limited`` puts it back in PENDING
+        # with ``next_attempt_at``). Dispatching it now would re-hit the source
+        # inside its own ``Retry-After`` and earn another 429 — the ADR-0097 §4
+        # "backoff that respects Retry-After" promise, broken by the trigger rather
+        # than by the backoff.
+        #
+        # This became routine with the background-poll opt-in (#3104): the poll
+        # ticks every 15 minutes and ``_RATE_LIMIT_MAX_BACKOFF`` is also 15
+        # minutes, so an always-on connection reliably ticks inside an active
+        # backoff window with nobody touching the UI. ``drain_external_sync``
+        # already honors the same clock and re-dispatches on its own 300 s cadence,
+        # so leaving the row alone loses nothing — the pull still happens, just
+        # when the source said it could.
+        if req.next_attempt_at is not None and req.next_attempt_at > now:
+            return req
+
+    _dispatch_on_commit(req.id)
+    return req
+
+
+def _dispatch_on_commit(request_id: uuid.UUID) -> None:
+    """Register a best-effort ``external_sync`` dispatch for after commit.
+
+    The dispatch is deferred to ``transaction.on_commit`` so the outbox row is
+    durably committed before the worker reads it. A broker error is swallowed —
+    the row stays ``PENDING`` and ``drain_external_sync`` re-dispatches it.
+    """
+
+    def _dispatch() -> None:
+        from .tasks import external_sync
+
+        try:
+            result = external_sync.delay(str(request_id))
+        except Exception:
+            logger.exception(
+                "enqueue_external_sync: immediate dispatch failed for request %s "
+                "— drain_external_sync will retry",
+                request_id,
+            )
+            return
+        # Flip to DISPATCHED only if still PENDING, so a concurrent drain that
+        # already dispatched this row is not clobbered.
+        ExternalSyncRequest.objects.filter(
+            id=request_id, status=ExternalSyncRequestStatus.PENDING
+        ).update(
+            status=ExternalSyncRequestStatus.DISPATCHED,
+            celery_task_id=result.id,
+            dispatched_at=timezone.now(),
+        )
+
+    transaction.on_commit(_dispatch)