flyteplugins-jira 2.7.0__py3-none-any.whl

flyteplugins/jira/__init__.py

@@ -0,0 +1,31 @@
+"""Jira webhooks for Flyte.
+
+Hand a `JiraProvider()` to a `WebhookAppEnvironment` and register handlers with the
+typed constants in `events`. Calling the Jira API is not this plugin's job — use
+the `jira` package from your tasks. See `examples/external_saas_integrations`.
+
+Note Jira does not sign its webhooks; see `_provider` for what this plugin does
+instead.
+"""
+
+from . import events
+from ._provider import JiraProvider, parse, verify
+
+__all__ = ["SAMPLE_DELIVERY", "JiraProvider", "events", "parse", "verify"]
+
+
+def _sample_headers(body: bytes, secret: str) -> dict[str, str]:
+    # No signature to compute: Jira sends a static shared token.
+    return {"X-Webhook-Token": secret}
+
+
+#: A real `jira:issue_created` delivery, trimmed to the fields the parser reads.
+SAMPLE_DELIVERY = (
+    _sample_headers,
+    (
+        b'{"webhookEvent": "jira:issue_created", "timestamp": 1700000000000,'
+        b' "user": {"displayName": "Bob"},'
+        b' "issue": {"key": "PROJ-1", "id": "10001",'
+        b' "fields": {"summary": "A bug", "project": {"key": "PROJ"}}}}'
+    ),
+)

flyteplugins/jira/_provider.py

@@ -0,0 +1,83 @@
+"""Jira webhook verification and payload normalization.
+
+Jira Cloud does **not** sign its webhooks. There is no HMAC to check, so this
+plugin authenticates with a shared token in `X-Webhook-Token` — which something
+in front of the app has to inject, because Jira itself cannot send custom
+headers. `JiraProvider` reports `signed=False` so the dashboard says so plainly rather than
+implying a guarantee that is not there.
+"""
+
+from __future__ import annotations
+
+from typing import ClassVar, Mapping
+
+from flyte.extras.webhooks import (
+    Provider,
+    WebhookEvent,
+    constant_time_equals,
+    json_body,
+    lower_headers,
+)
+
+
+def verify(body: bytes, headers: Mapping[str, str], secret: str) -> bool:
+    """Compare the `X-Webhook-Token` header against the shared token."""
+    token = lower_headers(headers).get("x-webhook-token")
+    if not token:
+        return False
+    return constant_time_equals(token.strip(), secret)
+
+
+def parse(headers: Mapping[str, str], body: bytes) -> WebhookEvent:
+    """Normalize a Jira delivery into a `WebhookEvent`."""
+    payload = json_body(body)
+    issue = payload.get("issue") or {}
+    fields = issue.get("fields") or {}
+    user = payload.get("user") or {}
+    return WebhookEvent(
+        provider="jira",
+        event_type=payload.get("webhookEvent", "unknown"),
+        delivery_id=str(payload.get("timestamp") or ""),
+        resource_id=issue.get("key"),
+        occurred_at=str(payload.get("timestamp")) if payload.get("timestamp") is not None else None,
+        scope=(fields.get("project") or {}).get("key"),
+        title=fields.get("summary"),
+        actor=user.get("displayName") or user.get("name"),
+        payload=payload,
+    )
+
+
+class JiraProvider(Provider):
+    """Jira's webhook provider, with its defaults pre-wired.
+
+    ```python
+    from flyte.extras.webhooks import WebhookAppEnvironment
+    from flyteplugins.jira import JiraProvider
+
+    app_env = WebhookAppEnvironment(name="webhooks", providers=[JiraProvider()])
+    ```
+
+    Jira does not sign its webhooks, so this provider authenticates with a
+    shared token instead and reports `signed=False` — which is what makes the
+    dashboard say so rather than implying a guarantee that is absent.
+
+    `WebhookAppEnvironment` mounts `default_secret_env` for you, so it does not
+    need naming again in `secrets=`.
+
+    Args:
+        secret_env: Environment variable holding the secret. Pass one only to
+            point this provider at a secret stored under a different name;
+            otherwise `default_secret_env` applies.
+    """
+
+    default_secret_env: ClassVar[str] = "JIRA_WEBHOOK_TOKEN"
+
+    def __init__(self, *, secret_env: str | None = None) -> None:
+        super().__init__(
+            name="jira",
+            secret_env=secret_env or self.default_secret_env,
+            verify=verify,
+            parse=parse,
+            signed=False,
+            setup_hint="Jira Settings -> System -> Webhooks (needs a proxy to inject X-Webhook-Token)",
+        )

flyteplugins/jira/events.py

@@ -0,0 +1,63 @@
+"""Jira webhook events, from the payload's `webhookEvent` field.
+
+Some names take a `jira:` prefix and some do not — that inconsistency is Jira's.
+These constants carry the exact wire values so you need not remember which.
+"""
+
+from __future__ import annotations
+
+from flyte.extras.webhooks import EventType
+
+__all__ = ["Comment", "Issue", "Project", "Sprint", "Version", "Worklog"]
+
+
+class Issue(EventType):
+    """Issue events. Note the `jira:` prefix, which comment events lack."""
+
+    CREATED = "jira:issue_created"
+    UPDATED = "jira:issue_updated"
+    DELETED = "jira:issue_deleted"
+
+
+class Comment(EventType):
+    """Comment events. These carry no `jira:` prefix."""
+
+    CREATED = "comment_created"
+    UPDATED = "comment_updated"
+    DELETED = "comment_deleted"
+
+
+class Worklog(EventType):
+    """Worklog events."""
+
+    CREATED = "worklog_created"
+    UPDATED = "worklog_updated"
+    DELETED = "worklog_deleted"
+
+
+class Project(EventType):
+    """Project events."""
+
+    CREATED = "project_created"
+    UPDATED = "project_updated"
+    DELETED = "project_deleted"
+
+
+class Version(EventType):
+    """Version (release) events."""
+
+    CREATED = "jira:version_created"
+    UPDATED = "jira:version_updated"
+    RELEASED = "jira:version_released"
+    UNRELEASED = "jira:version_unreleased"
+    DELETED = "jira:version_deleted"
+
+
+class Sprint(EventType):
+    """Sprint events (Jira Software)."""
+
+    CREATED = "sprint_created"
+    UPDATED = "sprint_updated"
+    STARTED = "sprint_started"
+    CLOSED = "sprint_closed"
+    DELETED = "sprint_deleted"

flyteplugins_jira-2.7.0.dist-info/METADATA

@@ -0,0 +1,91 @@
+Metadata-Version: 2.4
+Name: flyteplugins-jira
+Version: 2.7.0
+Summary: Receive Jira webhooks in Flyte.
+Author: Flyte Contributors
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: flyte
+Provides-Extra: app
+Requires-Dist: fastapi>=0.115; extra == "app"
+Requires-Dist: uvicorn>=0.30; extra == "app"
+
+# flyteplugins-jira
+
+Receive Jira webhooks in Flyte.
+
+```bash
+pip install "flyteplugins-jira[app]"
+```
+
+## Using it
+
+Hand a `JiraProvider()` to a `WebhookAppEnvironment` and register handlers with the
+typed constants in `events`:
+
+```python
+import flyte
+from flyte.extras.webhooks import WebhookAppEnvironment, run_once
+from flyteplugins.jira import JiraProvider, events
+
+# JiraProvider.default_secret_env is mounted for you.
+app_env = WebhookAppEnvironment(name="jira-webhooks", providers=[JiraProvider()])
+
+
+@app_env.on_event(events.Issue.CREATED)
+async def handle(event):
+    import flyte.remote as remote
+
+    task = remote.Task.get(name="my-env.my_task", auto_version="latest")
+    result = await run_once.aio(task, key=event.dedupe_key(), resource=event.resource_id)
+    if not result.created:
+        return {"skipped": result.run.name, "url": result.run.url}
+    return {"run": result.run.name}
+
+
+flyte.serve(app_env)
+```
+
+Handlers must `await run_once.aio(...)`. The blocking form stalls the
+app's event loop, and Jira times deliveries out in seconds.
+
+One app can serve several products at once — hand it one provider per product.
+
+## Try it
+
+`examples/jira_webhooks.py` runs two ways. The first needs no Jira account:
+
+```bash
+python examples/jira_webhooks.py --local   # replay a real sample delivery in-process
+python examples/jira_webhooks.py           # deploy the receiver to Flyte
+```
+
+`--local` posts this plugin's `SAMPLE_DELIVERY` through the app with FastAPI's
+test client, so you see a delivery verified, normalized, and dispatched — plus
+an unsigned one refused with a 401, and the same delivery replayed to show the
+dedupe key is stable.
+
+## Setup
+
+1. Store the secret and mount it on the app:
+   ```bash
+   flyte create secret JIRA_WEBHOOK_TOKEN --value <secret>
+   ```
+2. Point Jira at `<app-url>/webhook/jira`, from
+   Jira Settings → System → Webhooks.
+
+**Verification:** **None.** Jira Cloud does not sign its webhooks.
+
+Because there is no signature, this plugin authenticates with a shared token in `X-Webhook-Token` — which something in front of the app has to inject, since Jira cannot send custom headers. `JiraProvider` reports `signed=False`, so the dashboard says the product does not sign rather than implying a guarantee that is absent. A shared token also cannot detect body tampering, only that the sender knew the token.
+
+## Event constants
+
+`events` spells every event this plugin can dispatch, as `str` enums grouped by
+event type, so a typo fails at import rather than by silently never matching.
+Raw strings still work, for events the constants do not cover yet.
+
+## What this plugin does not do
+
+Call the Jira API. Use the `jira` package directly from your tasks — see
+`examples/external_saas_integrations`. This plugin owns only the part that is
+Flyte's: authenticating an inbound delivery and turning it into a run.

flyteplugins_jira-2.7.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+flyteplugins/jira/__init__.py,sha256=1BB7HbHLPOFNSOK3GcOe3V2XOQ4GRaYTRj_-lkjMBXo,1077
+flyteplugins/jira/_provider.py,sha256=3sLCzIZDrIP7Xfts1IKp7PwKVN7V3D3x-Ut5B_2TKmk,3002
+flyteplugins/jira/events.py,sha256=t5pJMq_0tVahp71i7qLK-CjHVNAWqM5NGhBJGqSoBzo,1557
+flyteplugins_jira-2.7.0.dist-info/METADATA,sha256=_SuYYTzQ34v2lG8gaUOXlx8cNF7ck1VmeYRhNGM6LwQ,3203
+flyteplugins_jira-2.7.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+flyteplugins_jira-2.7.0.dist-info/top_level.txt,sha256=cgd779rPu9EsvdtuYgUxNHHgElaQvPn74KhB5XSeMBE,13
+flyteplugins_jira-2.7.0.dist-info/RECORD,,

flyteplugins_jira-2.7.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

flyteplugins_jira-2.7.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+flyteplugins