notify: added more documentation + examples

machines/gerd/services/notify/app.py

@@ -32,6 +32,7 @@ CONFIG_PORT = int(getenv("PORT", 8080))
 
 CONFIG_DATABASE_PATH = getenv("DATABASE_PATH", "notifications.db")
 
+CONFIG_MATRIX_BOT_NAME = getenv("MATRIX_BOT_NAME", "unset")
 CONFIG_MATRIX_BOT_TOKEN = getenv("MATRIX_BOT_TOKEN")
 CONFIG_MATRIX_HOST = getenv("MATRIX_HOST")
 
@@ -41,33 +42,44 @@ CONFIG_MAIL_USERNAME = getenv("MAIL_USERNAME")
 CONFIG_MAIL_PASSWORD = getenv("MAIL_PASSWORD")
 CONFIG_MAIL_DOMAIN = getenv("MAIL_DOMAIN")
 CONFIG_MAIL_HOST = getenv("MAIL_HOST")
-CONFIG_MAIL_PORT = int(getenv("MAIL_PORT"))
+CONFIG_MAIL_PORT = int(getenv("MAIL_PORT", "465"))
 CONFIG_MAIL_MODE = getenv("MAIL_MODE", "ssl")
 
+script_example = rf"""#!/usr/bin/env bash
+#!/usr/bin/env nix-shell
+#!nix-shell --pure -i python3 -p "python3.withPackages (ps: with ps; [ requests ])"
+import requests
+import argparse
+import sys
+import os
 
-script_example = r"""#!/usr/bin/env bash
+parser = argparse.ArgumentParser(formatter_class=argparse.ArgumentDefaultsHelpFormatter)
-BODY="$1"
+parser.add_argument("--title", default="", help="Subject/title of the notification")
-TITLE=${2:-Notification}
+parser.add_argument("--body", default="", help="`-` for stdin")
-JQ_EXPR=${3:-.}
+parser.add_argument("--jq", default=".", help="Jq filter to use")
-TYPE=${4:-matrix}
+parser.add_argument("--type", default="matrix", help="mail or matrix")
-TOKEN="$(cat ~/.config/notify/token)"
+parser.add_argument("--token", help="token to use")
-# TOKEN="$(cat /run/agenix/notify-token)"
+parser.add_argument("--token-file", help="file to read token from")
-URL="||URL||/notify"
+parser.add_argument("--url", default="{CONFIG_URL}/notify", help="Notify endpoint")
+args = parser.parse_args()
 
-# get stdin if needed
+token: str = args.token
-if [ "$BODY" = "-" ]; then
+if args.token_file:
-    BODY="$(cat -)"
+    token = open(args.token_file, "r").read().strip()
-fi
+if not token:
+    exit("No token or tokenfile specified, or empty")
 
-# make request
+data = args.body
-curl -H "Authorization: Bearer $TOKEN" "$URL" \
+if data == "-" and not sys.stdin.isatty():
-    --get \
+    data = "\n".join(sys.stdin.readlines())
-    --data-urlencode "title=$TITLE" \
+
-    --data-urlencode "body=$BODY" \
+req = requests.post(args.url, headers={{"Authorization": f"Bearer {{token}}"}}, data=data)
-    --data-urlencode "jq=$JQ_EXPR" \
+print(req.text)
-    --data-urlencode "type=$TYPE" 
+"""
-""".replace(
+
-    "||URL||", "https://notify.fricloud.dk"
+script_example_with_token = script_example.replace(
+    '--token"',
+    '--token", default="||TOKEN||"',
 )
 
 
@@ -149,9 +161,66 @@ def index():
           <input type="submit" class="btn btn-primary" name="action" value="Generate Token">
         </form>
     <hr>
-    <pre><code>
+    <p>
-{script_example}
+      This notification service has support for both matrix and email.
-    </code></pre>
+      Matrix notifications will be sent from {CONFIG_MATRIX_BOT_NAME}, be sure to invite them to the room/space if it is private.
+      If using email, they will only be sent to your member email, and can't be sent anywhere else.
+      You'll receive them from {CONFIG_MAIL_USERNAME}@{CONFIG_MAIL_DOMAIN}.
+    </p>
+    <hr>
+    <table class="table">
+      <thead>
+        <tr>
+          <th scope="col">Param</th>
+          <th scope="col">Description</th>
+          <th scope="col">Default</th>
+          <th scope="col">Example</th>
+        </tr>
+      </thead>
+      <tbody>
+        <tr>
+          <th scope="row">title</th>
+          <td>Title of notification</td>
+          <td>Notification</td>
+          <td>Compilation Finished!</td>
+        </tr>
+        <tr>
+          <th scope="row">body</th>
+          <td>Body of notification</td>
+          <td>empty</td>
+          <td>Compilation result: success (default is nothing)</td>
+        </tr>
+        <tr>
+          <th scope="row">type</th>
+          <td>type of notification</td>
+          <td>matrix</td>
+          <td>matrix</td>
+        </tr>
+        <tr>
+          <th scope="row">room_id</th>
+          <td>Matrix room ID</td>
+          <td>default room</td>
+          <td>!yREJWHUMJhGROiHbtu:fricloud.dk or #na-offtopic:rend.al</td>
+        </tr>
+      </tbody>
+    </table>
+    <hr>
+    curl
+    <pre class="border"><code>curl "{CONFIG_URL}/notify" -H "Authorization: Bearer {token}"</code></pre>
+    curl w/ specific body/title
+    <pre class="border"><code>curl "{CONFIG_URL}/notify?title=MyTitle&body=MyBody" -H "Authorization: Bearer {token}"</code></pre>
+    Python
+    <pre class="border"><code>{script_example}</code></pre>
+    Python w/ <b>hardcoded token (DO NOT SHARE)</b>
+    <pre class="border"><code>{script_example_with_token}</code></pre>
+
+    Nix Python Script <b>HARDCODED TOKEN (DO NOT SHARE)</b>
+<pre class="border"><code>pkgs.writers.writePython3Bin "notify" {{
+    libraries = with pkgs.python3Packages; [ requests ];
+    doCheck = false;
+  }} ''{script_example_with_token}'';
+</code></pre>
+
     <!--
         <p class="fs-5">You've successfully loaded up the Bootstrap starter example. It includes <a href="https://getbootstrap.com/">Bootstrap 5</a> via the <a href="https://www.jsdelivr.com/package/npm/bootstrap">jsDelivr CDN</a> and includes an additional CSS and JS file for your own code.</p>
         <p>Feel free to download or copy-and-paste any parts of this example.</p>
@@ -165,8 +234,9 @@ def index():
     </div>
 </body>
 </html>
-    """
+    """.replace(
-
+        r"||TOKEN||", token
+    )
     return tmpl
 
 

machines/gerd/services/notify/default.nix

@@ -20,6 +20,7 @@ in {
       NOTIFIER_DATABASE_PATH = "${stateDir}/notify.db";
 
       # NOTIFIER_MATRIX_BOT_TOKEN = "";
+      NOTIFIER_MATRIX_BOT_NAME = "@${ldap_user}:${config.mine.shared.settings.domain}";
       NOTIFIER_MATRIX_HOST = config.mine.shared.settings.matrix-synapse.domain;
 
       NOTIFIER_PROXY_AUTH_USERNAME_HEADER = config.mine.shared.lib.authelia.protectedHeaders.username;