flyteplugins-linear 2.7.0__py3-none-any.whl

flyteplugins/linear/__init__.py

@@ -0,0 +1,32 @@
+"""Linear webhooks for Flyte.
+
+Hand a `LinearProvider()` to a `WebhookAppEnvironment` and register handlers with the
+typed constants in `events`. Calling the Linear API is not this plugin's job —
+Linear's API is a single GraphQL endpoint, so use `gql` from your tasks. See
+`examples/external_saas_integrations`.
+"""
+
+import hashlib
+import hmac
+
+from . import events
+from ._provider import LinearProvider, parse, verify
+
+__all__ = ["SAMPLE_DELIVERY", "LinearProvider", "events", "parse", "verify"]
+
+
+def _sample_headers(body: bytes, secret: str) -> dict[str, str]:
+    return {"X-Linear-Signature": hmac.new(secret.encode(), body, hashlib.sha256).hexdigest()}
+
+
+#: A real `Issue.create` delivery, trimmed to the fields the parser reads.
+SAMPLE_DELIVERY = (
+    _sample_headers,
+    (
+        b'{"action": "create", "type": "Issue", "webhookId": "wh-000",'
+        b' "createdAt": "2024-01-01T00:00:00.000Z",'
+        b' "data": {"id": "00000000-0000-0000-0000-000000000000", "title": "A bug",'
+        b' "teamId": "team-000", "updatedAt": "2024-01-01T00:00:00.000Z",'
+        b' "url": "https://linear.app/acme/issue/ENG-1"}}'
+    ),
+)

flyteplugins/linear/_provider.py

@@ -0,0 +1,92 @@
+"""Linear webhook verification and payload normalization."""
+
+from __future__ import annotations
+
+from typing import Any, ClassVar, Mapping
+
+from flyte.extras.webhooks import (
+    Provider,
+    WebhookEvent,
+    constant_time_equals,
+    hex_hmac_sha256,
+    json_body,
+    lower_headers,
+)
+
+
+def verify(body: bytes, headers: Mapping[str, str], secret: str) -> bool:
+    """Verify the `X-Linear-Signature` HMAC over the raw body."""
+    signature = lower_headers(headers).get("x-linear-signature")
+    if not signature:
+        return False
+    return constant_time_equals(hex_hmac_sha256(secret, body), signature.strip())
+
+
+def _team_id(data: dict[str, Any]) -> str | None:
+    """Find the team id, which Comment and Reaction payloads nest on the issue.
+
+    Without these fallbacks a `scopes` allowlist drops every non-Issue event as
+    unattributable.
+    """
+    issue = data.get("issue") or {}
+    for candidate in (
+        data.get("teamId"),
+        (data.get("team") or {}).get("id"),
+        issue.get("teamId"),
+        (issue.get("team") or {}).get("id"),
+    ):
+        if candidate:
+            return str(candidate)
+    return None
+
+
+def parse(headers: Mapping[str, str], body: bytes) -> WebhookEvent:
+    """Normalize a Linear delivery into a `WebhookEvent`."""
+    payload = json_body(body)
+    data = payload.get("data") or {}
+    return WebhookEvent(
+        provider="linear",
+        event_type=payload.get("type", "Unknown"),
+        action=payload.get("action", "unknown"),
+        delivery_id=str(payload.get("webhookId") or ""),
+        resource_id=data.get("id"),
+        # `updatedAt` is on the entity; `createdAt` is the delivery time and the
+        # only timestamp on payloads whose entity carries none.
+        occurred_at=data.get("updatedAt") or payload.get("createdAt"),
+        scope=_team_id(data),
+        title=data.get("title"),
+        url=data.get("url") or payload.get("url"),
+        actor=(data.get("creator") or {}).get("name"),
+        payload=payload,
+    )
+
+
+class LinearProvider(Provider):
+    """Linear's webhook provider, with its defaults pre-wired.
+
+    ```python
+    from flyte.extras.webhooks import WebhookAppEnvironment
+    from flyteplugins.linear import LinearProvider
+
+    app_env = WebhookAppEnvironment(name="webhooks", providers=[LinearProvider()])
+    ```
+
+    `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] = "LINEAR_WEBHOOK_SECRET"
+
+    def __init__(self, *, secret_env: str | None = None) -> None:
+        super().__init__(
+            name="linear",
+            secret_env=secret_env or self.default_secret_env,
+            verify=verify,
+            parse=parse,
+            setup_hint="Linear Settings -> API -> Webhooks",
+        )

flyteplugins/linear/events.py

@@ -0,0 +1,79 @@
+"""Linear webhook events, spelled as the `Type.action` pattern Linear sends."""
+
+from __future__ import annotations
+
+from flyte.extras.webhooks import EventType
+
+__all__ = ["Attachment", "Comment", "Cycle", "Issue", "IssueLabel", "Project", "ProjectUpdate", "Reaction"]
+
+
+class Issue(EventType):
+    """`Issue` entity events."""
+
+    ANY = "Issue"
+    CREATE = "Issue.create"
+    UPDATE = "Issue.update"
+    REMOVE = "Issue.remove"
+
+
+class Comment(EventType):
+    """`Comment` entity events."""
+
+    ANY = "Comment"
+    CREATE = "Comment.create"
+    UPDATE = "Comment.update"
+    REMOVE = "Comment.remove"
+
+
+class IssueLabel(EventType):
+    """`IssueLabel` entity events."""
+
+    ANY = "IssueLabel"
+    CREATE = "IssueLabel.create"
+    UPDATE = "IssueLabel.update"
+    REMOVE = "IssueLabel.remove"
+
+
+class Project(EventType):
+    """`Project` entity events."""
+
+    ANY = "Project"
+    CREATE = "Project.create"
+    UPDATE = "Project.update"
+    REMOVE = "Project.remove"
+
+
+class ProjectUpdate(EventType):
+    """`ProjectUpdate` entity events — project status posts."""
+
+    ANY = "ProjectUpdate"
+    CREATE = "ProjectUpdate.create"
+    UPDATE = "ProjectUpdate.update"
+    REMOVE = "ProjectUpdate.remove"
+
+
+class Cycle(EventType):
+    """`Cycle` entity events."""
+
+    ANY = "Cycle"
+    CREATE = "Cycle.create"
+    UPDATE = "Cycle.update"
+    REMOVE = "Cycle.remove"
+
+
+class Reaction(EventType):
+    """`Reaction` entity events."""
+
+    ANY = "Reaction"
+    CREATE = "Reaction.create"
+    UPDATE = "Reaction.update"
+    REMOVE = "Reaction.remove"
+
+
+class Attachment(EventType):
+    """`Attachment` entity events."""
+
+    ANY = "Attachment"
+    CREATE = "Attachment.create"
+    UPDATE = "Attachment.update"
+    REMOVE = "Attachment.remove"

flyteplugins_linear-2.7.0.dist-info/METADATA

@@ -0,0 +1,91 @@
+Metadata-Version: 2.4
+Name: flyteplugins-linear
+Version: 2.7.0
+Summary: Receive Linear 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-linear
+
+Receive Linear webhooks in Flyte.
+
+```bash
+pip install "flyteplugins-linear[app]"
+```
+
+## Using it
+
+Hand a `LinearProvider()` 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.linear import LinearProvider, events
+
+# LinearProvider.default_secret_env is mounted for you.
+app_env = WebhookAppEnvironment(name="linear-webhooks", providers=[LinearProvider()])
+
+
+@app_env.on_event(events.Issue.CREATE)
+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 Linear times deliveries out in seconds.
+
+One app can serve several products at once — hand it one provider per product.
+
+## Try it
+
+`examples/linear_webhooks.py` runs two ways. The first needs no Linear account:
+
+```bash
+python examples/linear_webhooks.py --local   # replay a real sample delivery in-process
+python examples/linear_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 LINEAR_WEBHOOK_SECRET --value <secret>
+   ```
+2. Point Linear at `<app-url>/webhook/linear`, from
+   Linear Settings → API → Webhooks (it shows the signing secret on creation).
+
+**Verification:** HMAC-SHA256 over the raw body (`X-Linear-Signature`).
+
+Comment and reaction payloads carry the team id only on the nested issue; the parser follows it, so a `scopes` allowlist can still attribute them.
+
+## 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 Linear API. Use `gql` — Linear ships no Python SDK, and its API is a single GraphQL endpoint 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_linear-2.7.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+flyteplugins/linear/__init__.py,sha256=LMVeCvdZ6fOVr0280-oTk7lUFVI--j0UZqxh3el4tKM,1138
+flyteplugins/linear/_provider.py,sha256=1aTTdtYIEh4568QZ0pSwAEvhaUd5mCS-S2-1ak8Wm68,3035
+flyteplugins/linear/events.py,sha256=qAFB8qlkA7BOgDbAX9Y_GwA-8OoiOEK6vCAymemb98k,1741
+flyteplugins_linear-2.7.0.dist-info/METADATA,sha256=FQd7eDb9bYcv9uVDEZGItEwdoPpFr_FFjQcofFVLu6M,3081
+flyteplugins_linear-2.7.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+flyteplugins_linear-2.7.0.dist-info/top_level.txt,sha256=cgd779rPu9EsvdtuYgUxNHHgElaQvPn74KhB5XSeMBE,13
+flyteplugins_linear-2.7.0.dist-info/RECORD,,

flyteplugins_linear-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_linear-2.7.0.dist-info/top_level.txt

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