|
| 1 | +"""Support a product this family does not ship a plugin for. |
| 2 | +
|
| 3 | +A provider is small: say which environment variable holds its secret, how to |
| 4 | +verify a delivery, and how to turn a payload into a `WebhookEvent`. Core does |
| 5 | +the rest — the app, the dashboard, dispatch, the scope allowlist, and idempotent |
| 6 | +launching. |
| 7 | +
|
| 8 | +Run it without an account: |
| 9 | +
|
| 10 | + python custom_provider.py --local |
| 11 | +
|
| 12 | +That posts a signed sample delivery through the app in-process, so you see |
| 13 | +verification, normalization, and dispatch end to end. |
| 14 | +
|
| 15 | +Once it works, move it into its own `flyteplugins-webhooks-<product>` package |
| 16 | +beside the others and add the one-line conformance test: |
| 17 | +
|
| 18 | + from flyte.extras.webhooks.testing import assert_provider_conforms |
| 19 | + import flyteplugins.webhooks.acme as plugin |
| 20 | +
|
| 21 | + def test_conformance(): |
| 22 | + assert_provider_conforms(plugin) |
| 23 | +""" |
| 24 | + |
| 25 | +import hashlib |
| 26 | +import hmac |
| 27 | +import json |
| 28 | +import os |
| 29 | +import sys |
| 30 | +from typing import ClassVar, Mapping |
| 31 | + |
| 32 | +import flyte |
| 33 | +from flyte.extras.webhooks import ( |
| 34 | + EventType, |
| 35 | + Provider, |
| 36 | + WebhookAppEnvironment, |
| 37 | + WebhookEvent, |
| 38 | + constant_time_equals, |
| 39 | + hex_hmac_sha256, |
| 40 | + json_body, |
| 41 | + lower_headers, |
| 42 | +) |
| 43 | + |
| 44 | + |
| 45 | +class Ticket(EventType): |
| 46 | + """Acme's ticket events. `ANY` matches every action on the type.""" |
| 47 | + |
| 48 | + ANY = "ticket" |
| 49 | + OPENED = "ticket.opened" |
| 50 | + CLOSED = "ticket.closed" |
| 51 | + |
| 52 | + |
| 53 | +def verify(body: bytes, headers: Mapping[str, str], secret: str) -> bool: |
| 54 | + """Verify Acme's hex HMAC-SHA256 over the raw body. |
| 55 | +
|
| 56 | + Use `constant_time_equals` rather than `hmac.compare_digest` directly: the |
| 57 | + latter raises `TypeError` on `str` operands containing non-ASCII, and this |
| 58 | + header comes off the wire, so a crafted one would turn a clean 401 into a |
| 59 | + 500. |
| 60 | + """ |
| 61 | + signature = lower_headers(headers).get("x-acme-signature") |
| 62 | + if not signature: |
| 63 | + return False |
| 64 | + return constant_time_equals(hex_hmac_sha256(secret, body), signature.strip()) |
| 65 | + |
| 66 | + |
| 67 | +def parse(headers: Mapping[str, str], body: bytes) -> WebhookEvent: |
| 68 | + """Normalize an Acme delivery. |
| 69 | +
|
| 70 | + Fill in `resource_id` and `occurred_at` wherever the product gives them: |
| 71 | + together they are the dedupe key, and without a timestamp every later change |
| 72 | + to one resource collapses onto the first one's key and never launches. |
| 73 | + """ |
| 74 | + payload = json_body(body) |
| 75 | + ticket = payload.get("ticket") or {} |
| 76 | + return WebhookEvent( |
| 77 | + provider="acme", |
| 78 | + event_type="ticket", |
| 79 | + action=payload.get("action"), |
| 80 | + delivery_id=str(payload.get("delivery_id") or ""), |
| 81 | + resource_id=str(ticket.get("id")) if ticket.get("id") is not None else None, |
| 82 | + occurred_at=ticket.get("updated_at"), |
| 83 | + scope=ticket.get("project"), |
| 84 | + title=ticket.get("subject"), |
| 85 | + url=ticket.get("url"), |
| 86 | + payload=payload, |
| 87 | + ) |
| 88 | + |
| 89 | + |
| 90 | +class AcmeProvider(Provider): |
| 91 | + """Acme's webhook provider, with its defaults pre-wired. |
| 92 | +
|
| 93 | + Users then write `providers=[AcmeProvider()]`. The app mounts |
| 94 | + `default_secret_env` for them; `secret_env=` is there for anyone storing the |
| 95 | + secret under a different name. |
| 96 | + """ |
| 97 | + |
| 98 | + default_secret_env: ClassVar[str] = "ACME_WEBHOOK_SECRET" |
| 99 | + |
| 100 | + def __init__(self, *, secret_env: str | None = None) -> None: |
| 101 | + super().__init__( |
| 102 | + name="acme", |
| 103 | + secret_env=secret_env or self.default_secret_env, |
| 104 | + verify=verify, |
| 105 | + parse=parse, |
| 106 | + setup_hint="Acme Settings -> Webhooks", |
| 107 | + ) |
| 108 | + |
| 109 | + |
| 110 | +app_env = WebhookAppEnvironment( |
| 111 | + name="acme-webhooks", |
| 112 | + providers=[AcmeProvider()], |
| 113 | + image=flyte.Image.from_debian_base(python_version=(3, 12)).with_pip_packages("fastapi", "uvicorn"), |
| 114 | +) |
| 115 | + |
| 116 | + |
| 117 | +@app_env.on_event(Ticket.OPENED) |
| 118 | +async def on_ticket_opened(event): |
| 119 | + return {"saw": event.qualified_type, "resource": event.resource_id, "dedupe_key": event.dedupe_key()} |
| 120 | + |
| 121 | + |
| 122 | +#: A realistic delivery, the same thing a shipped plugin exports as SAMPLE_DELIVERY. |
| 123 | +SAMPLE_BODY = json.dumps( |
| 124 | + { |
| 125 | + "action": "opened", |
| 126 | + "delivery_id": "d-1", |
| 127 | + "ticket": { |
| 128 | + "id": 42, |
| 129 | + "subject": "Printer on fire", |
| 130 | + "project": "SUPPORT", |
| 131 | + "updated_at": "2024-01-01T00:00:00Z", |
| 132 | + "url": "https://acme.example/t/42", |
| 133 | + }, |
| 134 | + } |
| 135 | +).encode() |
| 136 | + |
| 137 | + |
| 138 | +def _try_locally() -> None: |
| 139 | + from fastapi.testclient import TestClient |
| 140 | + |
| 141 | + secret = os.environ.setdefault(AcmeProvider.default_secret_env, "local-trial-secret") |
| 142 | + headers = {"X-Acme-Signature": hmac.new(secret.encode(), SAMPLE_BODY, hashlib.sha256).hexdigest()} |
| 143 | + assert app_env.app is not None # built in __post_init__ |
| 144 | + client = TestClient(app_env.app) |
| 145 | + |
| 146 | + print("POST /webhook/acme (signed with a throwaway secret)") |
| 147 | + response = client.post("/webhook/acme", content=SAMPLE_BODY, headers=headers) |
| 148 | + print(f" {response.status_code} {response.json()}\n") |
| 149 | + |
| 150 | + print("an unsigned delivery is refused:") |
| 151 | + bad = client.post("/webhook/acme", content=SAMPLE_BODY, headers={}) |
| 152 | + print(f" {bad.status_code} {bad.json()}") |
| 153 | + |
| 154 | + |
| 155 | +if __name__ == "__main__": |
| 156 | + if "--local" in sys.argv: |
| 157 | + _try_locally() |
| 158 | + else: |
| 159 | + flyte.init_from_config() |
| 160 | + handle = flyte.serve(app_env) |
| 161 | + handle.activate(wait=True) |
| 162 | + print(f"Dashboard ready at {handle.endpoint}") |
0 commit comments