formatters: add github

.pre-commit-config.yaml

@@ -23,7 +23,7 @@ repos:
     hooks:
     -   id: pydocstyle
         args:
-        - --ignore=D200,D212
+        - --ignore=D200,D203,D212
 -   repo: https://github.com/PyCQA/flake8
     rev: 3.9.2
     hooks:

CHANGELOG.md

@@ -6,10 +6,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
-- add grafana formatter
+- add github & grafana formatters
 - add formatted_body to bypass markdown with direct
   [matrix-custom-HTML](https://matrix.org/docs/spec/client_server/r0.6.1#m-room-message-msgtypes)
 - allow "key" to be passed as a parameter
+- allow to use a sha256 HMAC hex digest with the key instead of the raw key
 - allow "room_id" to be passed as a parameter or with the data
 - rename "text" to "body".
 - Publish releases also on github from github actions

matrix_webhook/formatters.py

@@ -13,3 +13,20 @@ def grafana(data, headers):
             text = text + "* " + match["metric"] + ": " + str(match["value"]) + "\n"
     data["body"] = text
     return data
+
+
+def github(data, headers):
+    """Pretty-print a github notification."""
+    # TODO: Write nice useful formatters. This is only an example.
+    if headers["X-GitHub-Event"] == "push":
+        pusher, ref, a, b, c = [
+            data[k] for k in ["pusher", "ref", "after", "before", "compare"]
+        ]
+        pusher = f"[{pusher['name']}](https://github.com/{pusher['name']})"
+        data["body"] = f"@{pusher} pushed on {ref}: [{b} → {a}]({c}):\n\n"
+        for commit in data["commits"]:
+            data["body"] += f"- [{commit['message']}]({commit['url']})\n"
+    else:
+        data["body"] = "notification from github"
+    data["digest"] = headers["X-Hub-Signature-256"].replace("sha256=", "")
+    return data

matrix_webhook/handler.py

@@ -3,6 +3,7 @@
 import json
 import logging
 from http import HTTPStatus
+from hmac import HMAC
 
 from markdown import markdown
 
@@ -18,10 +19,10 @@ async def matrix_webhook(request):
     This one handles a POST, checks its content, and forwards it to the matrix room.
     """
     LOGGER.debug(f"Handling {request=}")
-    data = await request.read()
+    data_b = await request.read()
 
     try:
-        data = json.loads(data.decode())
+        data = json.loads(data_b.decode())
     except json.decoder.JSONDecodeError:
         return utils.create_json_response(HTTPStatus.BAD_REQUEST, "Invalid JSON")
 
@@ -48,6 +49,16 @@ async def matrix_webhook(request):
     if "room_id" not in data:
         data["room_id"] = request.path.lstrip("/")
 
+    # If we get a good SHA-256 HMAC digest,
+    # we can consider that the sender has the right API key
+    if "digest" in data:
+        if data["digest"] == HMAC(conf.API_KEY.encode(), data_b, "sha256").hexdigest():
+            data["key"] = conf.API_KEY
+        else:  # but if there is a wrong digest, an informative error should be provided
+            return utils.create_json_response(
+                HTTPStatus.UNAUTHORIZED, "Invalid SHA-256 HMAC digest"
+            )
+
     missing = []
     for key in ["body", "key", "room_id"]:
         if key not in data or not data[key]:

tests/example_grafana.json

@@ -0,0 +1,22 @@
+{
+  "dashboardId":1,
+  "evalMatches":[
+    {
+      "value":1,
+      "metric":"Count",
+      "tags":{}
+    }
+  ],
+  "imageUrl":"https://grafana.com/assets/img/blog/mixed_styles.png",
+  "message":"Notification Message",
+  "orgId":1,
+  "panelId":2,
+  "ruleId":1,
+  "ruleName":"Panel Title alert",
+  "ruleUrl":"http://localhost:3000/d/hZ7BuVbWz/test-dashboard?fullscreen\u0026edit\u0026tab=alert\u0026panelId=2\u0026orgId=1",
+  "state":"alerting",
+  "tags":{
+    "tag name":"tag value"
+  },
+  "title":"[Alerting] Panel Title alert"
+}

tests/test_github.py

@@ -0,0 +1,71 @@
+"""Test module for grafana formatter."""
+
+import unittest
+
+import httpx
+import nio
+
+from .start import BOT_URL, FULL_ID, MATRIX_ID, MATRIX_PW, MATRIX_URL
+
+SHA256 = "fd7522672889385736be8ffc86d1f8de2e15668864f49af729b5c63e5e0698c4"
+EXAMPLE_GITHUB_REQUEST_HEADERS = {
+    # 'Request URL': 'https://bot.saurel.me/room?formatter=github',
+    # 'Request method': 'POST',
+    "Accept": "*/*",
+    "content-type": "application/json",
+    "User-Agent": "GitHub-Hookshot/8d33975",
+    "X-GitHub-Delivery": "636b9b1c-0761-11ec-8a8a-5e435c5ac4f4",
+    "X-GitHub-Event": "push",
+    "X-GitHub-Hook-ID": "311845633",
+    "X-GitHub-Hook-Installation-Target-ID": "171114171",
+    "X-GitHub-Hook-Installation-Target-Type": "repository",
+    "X-Hub-Signature": "sha1=ea68fdfcb2f328aaa8f50d176f355e5d4fc95d94",
+    "X-Hub-Signature-256": f"sha256={SHA256}",
+}
+
+
+class GithubFormatterTest(unittest.IsolatedAsyncioTestCase):
+    """Github formatter test class."""
+
+    async def test_github_body(self):
+        """Send a markdown message, and check the result."""
+        messages = []
+        client = nio.AsyncClient(MATRIX_URL, MATRIX_ID)
+
+        await client.login(MATRIX_PW)
+        room = await client.room_create()
+
+        with open("tests/example_github_push.json", "rb") as f:
+            example_github_push = f.read().strip()
+
+        self.assertEqual(
+            httpx.post(
+                f"{BOT_URL}/{room.room_id}",
+                params={
+                    "formatter": "github",
+                },
+                content=example_github_push,
+                headers=EXAMPLE_GITHUB_REQUEST_HEADERS,
+            ).json(),
+            {"status": 200, "ret": "OK"},
+        )
+
+        sync = await client.sync()
+        messages = await client.room_messages(room.room_id, sync.next_batch)
+        await client.close()
+
+        before = "ac7d1d9647008145e9d0cf65d24744d0db4862b8"
+        after = "4bcdb25c809391baaabc264d9309059f9f48ead2"
+        GH = "https://github.com"
+        expected = f'<p>@<a href="{GH}/nim65s">nim65s</a> pushed on refs/heads/devel: '
+        expected += f'<a href="{GH}/nim65s/matrix-webhook/compare/ac7d1d964700...'
+        expected += f'4bcdb25c8093">{before} → {after}</a>:</p>\n<ul>\n<li>'
+        expected += f'<a href="{GH}/nim65s/matrix-webhook/commit/{after}">'
+        expected += "formatters: also get headers</a></li>\n</ul>"
+
+        message = messages.chunk[0]
+        self.assertEqual(message.sender, FULL_ID)
+        self.assertEqual(
+            message.formatted_body,
+            expected,
+        )

tests/test_grafana.py

@@ -1,4 +1,8 @@
-"""Test module for grafana formatter."""
+"""
+Test module for grafana formatter.
+
+ref https://grafana.com/docs/grafana/latest/alerting/old-alerting/notifications/#webhook
+"""
 
 import unittest
 
@@ -7,32 +11,6 @@ import nio
 
 from .start import BOT_URL, FULL_ID, KEY, MATRIX_ID, MATRIX_PW, MATRIX_URL
 
-# ref https://grafana.com/docs/grafana/latest/alerting/old-alerting/notifications/#webhook
-EXAMPLE_GRAFANA_REQUEST = """
-{
-  "dashboardId":1,
-  "evalMatches":[
-    {
-      "value":1,
-      "metric":"Count",
-      "tags":{}
-    }
-  ],
-  "imageUrl":"https://grafana.com/assets/img/blog/mixed_styles.png",
-  "message":"Notification Message",
-  "orgId":1,
-  "panelId":2,
-  "ruleId":1,
-  "ruleName":"Panel Title alert",
-  "ruleUrl":"http://localhost:3000/d/hZ7BuVbWz/test-dashboard?fullscreen\u0026edit\u0026tab=alert\u0026panelId=2\u0026orgId=1",
-  "state":"alerting",
-  "tags":{
-    "tag name":"tag value"
-  },
-  "title":"[Alerting] Panel Title alert"
-}
-"""
-
 
 class GrafanaFormatterTest(unittest.IsolatedAsyncioTestCase):
     """Grafana formatter test class."""
@@ -45,11 +23,13 @@ class GrafanaFormatterTest(unittest.IsolatedAsyncioTestCase):
         await client.login(MATRIX_PW)
         room = await client.room_create()
 
+        with open("tests/example_grafana.json") as f:
+            example_grafana_request = f.read()
         self.assertEqual(
             httpx.post(
                 f"{BOT_URL}/{room.room_id}",
                 params={"formatter": "grafana", "key": KEY},
-                content=EXAMPLE_GRAFANA_REQUEST,
+                content=example_grafana_request,
             ).json(),
             {"status": 200, "ret": "OK"},
         )

tests/tests.py

@@ -86,7 +86,7 @@ class BotTest(unittest.IsolatedAsyncioTestCase):
         self.assertEqual(message.formatted_body, "<h1>Hello</h1>")
 
     async def test_room_id_parameter(self):
-        """Send a markdown message in a room given as parameter, and check the result."""
+        """Send a markdown message in a room given as parameter."""
         body = "# Hello"
         messages = []
         client = nio.AsyncClient(MATRIX_URL, MATRIX_ID)