[ntfy] Add dedicated service plugin ntfy

Author: amotl

CHANGES.rst

@@ -14,6 +14,7 @@ in progress
 - [file] Allow writing of binary content. Thanks, @sevmonster.
 - [ux] Rename subcommand ``mqttwarn make-samplefuncs`` to ``mqttwarn make-udf``,
   and adjust naming.
+- [ntfy] Add dedicated service plugin ``ntfy``
 
 
 2023-04-11 0.33.0

README.rst

@@ -183,18 +183,22 @@ you an idea how to pass relevant information on the command line using JSON::
     # Launch "pushover" service plugin
     mqttwarn --plugin=pushover --options='{"title": "About", "message": "Hello world", "addrs": ["userkey", "token"], "priority": 6}'
 
-    # Launch "ssh" service plugin from the command line
+    # Launch "ntfy" service plugin
+    mqttwarn --plugin=ntfy --options='{"addrs": {"url": "http://localhost:5555/testdrive"}, "title": "Example notification", "message": "Hello world"}' --data='{"tags": "foo,bar,äöü", "priority": "high"}'
+
+    # Launch "ntfy" service plugin, and add remote attachment
+    mqttwarn --plugin=ntfy --options='{"addrs": {"url": "http://localhost:5555/testdrive"}, "title": "Example notification", "message": "Hello world"}' --data='{"attach": "https://unsplash.com/photos/spdQ1dVuIHw/download?w=320", "filename": "goat.jpg"}'
+
+    # Launch "ntfy" service plugin, and add attachment from local filesystem
+    mqttwarn --plugin=ntfy --options='{"addrs": {"url": "http://localhost:5555/testdrive", "attachment": "goat.jpg"}, "title": "Example notification", "message": "Hello world"}'
+
+    # Launch "ssh" service plugin
     mqttwarn --plugin=ssh --config='{"host": "ssh.example.org", "port": 22, "user": "foo", "password": "bar"}' --options='{"addrs": ["command with substitution %s"], "payload": "{\"args\": \"192.168.0.1\"}"}'
 
-    # Launch "cloudflare_zone" service plugin from "mqttwarn-contrib", passing "--config" parameters via command line
+    # Launch "cloudflare_zone" service plugin from "mqttwarn-contrib"
     pip install mqttwarn-contrib
     mqttwarn --plugin=mqttwarn_contrib.services.cloudflare_zone --config='{"auth-email": "foo", "auth-key": "bar"}' --options='{"addrs": ["0815", "www.example.org", ""], "message": "192.168.0.1"}'
 
-    # Submit notification to "ntfy", using Apprise service plugin.
-    mqttwarn --plugin=apprise \
-        --config='{"baseuri": "ntfy://user:password@ntfy.example.org/topic1/topic2"}' \
-        --options='{"addrs": [], "title": "Example notification", "message": "Hello world"}'
-
 
 Also, the ``--config-file`` parameter can be used to optionally specify the
 path to a configuration file.

docs/notifier-catalog.md

@@ -223,22 +223,22 @@ template arguments. mqttwarn supports propagating them from either the
 ``baseuri`` configuration setting, or from its data dictionary to the Apprise
 plugin invocation.
 
-So, for example, you can propagate parameters to the [Apprise Ntfy plugin]
-by either pre-setting them as URL query parameters, like 
+So, for example, you can propagate parameters to the [Apprise JSON HTTP POST
+Notifications plugin] by either pre-setting them as URL query parameters, like
 ```
-ntfy://user:password@ntfy.example.org/topic1/topic2?email=test@example.org
+json://localhost/?:sound=oceanwave
 ```
 or by submitting them within a JSON-formatted MQTT message, like
 ```json
-{"priority": "high", "tags": "foo,bar", "click": "https://httpbin.org/headers"}
+{":sound": "oceanwave", "tags": "foo,bar", "click": "https://httpbin.org/headers"}
 ```
 
 
 [Apprise]: https://github.com/caronc/apprise
 [Apprise documentation]: https://github.com/caronc/apprise/wiki
 [Apprise URL Basics]: https://github.com/caronc/apprise/wiki/URLBasics
 [Apprise Notification Services]: https://github.com/caronc/apprise/wiki#notification-services
-[Apprise Ntfy plugin]: https://github.com/caronc/apprise/wiki/Notify_ntfy
+[Apprise JSON HTTP POST Notifications plugin]: https://github.com/caronc/apprise/wiki/Notify_Custom_JSON
 
 
 ### `apprise_single`
@@ -256,7 +256,7 @@ Apprise to E-Mail, an HTTP endpoint, and a Discord channel.
 
 ```ini
 [defaults]
-launch    = apprise-mail, apprise-json, apprise-discord, apprise-ntfy
+launch    = apprise-mail, apprise-json, apprise-discord
 
 [config:apprise-mail]
 ; Dispatch message as e-mail.
@@ -283,16 +283,9 @@ baseuri  = 'json://localhost:1234/mqtthook'
 module   = 'apprise_single'
 baseuri  = 'discord://4174216298/JHMHI8qBe7bk2ZwO5U711o3dV_js'
 
-[config:apprise-ntfy]
-; Dispatch message to ntfy.
-; https://github.com/caronc/apprise/wiki/URLBasics
-; https://github.com/caronc/apprise/wiki/Notify_ntfy
-module   = 'apprise_single'
-baseuri  = 'ntfy://user:password@ntfy.example.org/topic1/topic2'
-
 [apprise-single-test]
 topic    = apprise/single/#
-targets  = apprise-mail:demo, apprise-json, apprise-discord, apprise-ntfy
+targets  = apprise-mail:demo, apprise-json, apprise-discord
 format   = Alarm from {device}: {payload}
 title    = Alarm from {device}
 ```
@@ -325,7 +318,6 @@ module   = 'apprise_multi'
 targets = {
    'demo-http'        : [ { 'baseuri':  'json://localhost:1234/mqtthook' }, { 'baseuri':  'json://daq.example.org:5555/foobar' } ],
    'demo-discord'     : [ { 'baseuri':  'discord://4174216298/JHMHI8qBe7bk2ZwO5U711o3dV_js' } ],
-   'demo-ntfy'        : [ { 'baseuri':  'ntfy://user:password@ntfy.example.org/topic1/topic2' } ],
    'demo-mailto'      : [ {
           'baseuri':  'mailtos://smtp_username:smtp_password@mail.example.org',
           'recipients': ['foo@example.org', 'bar@example.org'],
@@ -336,7 +328,7 @@ targets = {
 
 [apprise-multi-test]
 topic    = apprise/multi/#
-targets  = apprise-multi:demo-http, apprise-multi:demo-discord, apprise-multi:demo-mailto, apprise-multi:demo-ntfy
+targets  = apprise-multi:demo-http, apprise-multi:demo-discord, apprise-multi:demo-mailto
 format   = Alarm from {device}: {payload}
 title    = Alarm from {device}
 ```
@@ -1746,10 +1738,151 @@ Requires:
 
 ### `ntfy`
 
-Support for [ntfy] is provided through Apprise, see [apprise_single](#apprise_single)
-and [apprise_multi](#apprise_multi).
+> [ntfy] (pronounce: _notify_) is a simple HTTP-based [pub-sub] notification service.
+> It allows you to send notifications to your phone or desktop via scripts from
+> any computer, entirely without signup, cost or setup.
+> [ntfy is also open source](https://github.com/binwiederhier/ntfy), if you want to
+> run an instance on your own premises.
+
+ntfy uses topics to address communication channels. This topic is part of the
+HTTP API URL.
+
+To use the hosted variant on `ntfy.sh`, just provide an URL including the topic.
+```ini
+[config:ntfy]
+targets  = {
+    'test': 'https://ntfy.sh/testdrive',
+    }
+```
+
+When running your own instance, you would use a custom URL here.
+```ini
+[config:ntfy]
+targets  = {
+    'test': 'http://username:password@localhost:5555/testdrive',
+    }
+```
+
+In order to specify more options, please wrap your ntfy URL into a dictionary
+under the `url` key. This way, additional options can be added.
+```ini
+[config:ntfy]
+targets  = {
+    'test': {
+        'url': 'https://ntfy.sh/testdrive',
+        },
+    }
+```
+
+:::{important}
+[ntfy publishing options] outlines different ways to marshal data to the ntfy
+HTTP API. mqttwarn is using HTTP headers for serializing values, because the
+HTTP body will already be used for the attachment file. Because of this, you
+are not able to use UTF-8 characters within your message text, they will be
+replaced by placeholder characters like `?`.
+:::
+
+{#ntfy-remote-attachments}
+#### Remote attachments
+In order to submit notifications with an attachment file at a remote location,
+use the `attach` field. Optionally, the `filename` field can be used to assign
+a different name to the file.
+```ini
+[config:ntfy]
+targets  = {
+    'test': {
+        'url': 'https://ntfy.sh/testdrive',
+        'attach': 'https://unsplash.com/photos/spdQ1dVuIHw/download?w=320',
+        'filename': 'goat.jpg',
+        },
+    }
+```
+
+{#ntfy-local-attachments}
+#### Local attachments
+By using the `attachment` option, you can add an attachment to your message, local
+to the machine mqttwarn is running on. The file will be uploaded when submitting
+the notification, and ntfy will serve it for clients so that you don't have to. In
+order to address the file, you can provide a path template, where the transformation
+data will also get interpolated into.
+```ini
+[config:ntfy]
+targets  = {
+    'test': {
+        'url': 'https://ntfy.sh/testdrive',
+        'attachment': '/tmp/ntfy-attachment-{slot}-{label}.png',
+        }
+    }
+```
+:::{important}
+In order to allow users to **upload** and attach files to notifications, you will
+need to enable the corresponding ntfy feature by simply configuring an attachment
+cache directory and a base URL (`attachment-cache-dir`, `base-url`), see
+[ntfy stored attachments].
+:::
+:::{note}
+When mqttwarn processes a message, and accessing the file raises an error, it gets
+handled gracefully. In this way, notifications will be triggered even when attaching
+the file fails for whatever reasons.
+:::
+
+#### Publishing options
+You can use all the available [ntfy publishing options], by using the corresponding
+option names listed within `NTFY_FIELD_NAMES`, which are: `message`, `title`, `tags`, 
+`priority`, `actions`, `click`, `attach`, `filename`, `delay`, and `email`. 
+
+You can obtain ntfy option fields from _three_ contexts in total, as implemented
+by the `obtain_ntfy_fields` function. Effectively, that means that you can place
+them either within the `targets` address descriptor, within the configuration
+section, or submit them using a JSON MQTT message and a corresponding decoder
+function into the transformation data dictionary.
+
+For example, you can always send a `priority` field using MQTT/JSON, or use one of
+those configuration snippets, which are equivalent.
+```ini
+[config:ntfy]
+targets  = {
+    'test': {
+        'url': 'https://ntfy.sh/testdrive',
+        'priority': 'high',
+        }
+    }
+```
+```ini
+[config:ntfy]
+targets  = {
+    'test': {
+        'url': 'https://ntfy.sh/testdrive',
+        }
+    }
+priority = high
+```
+
+The highest precedence takes data coming in from the transformation data dictionary,
+followed by option fields coming in from the per-recipient `targets` address descriptor,
+followed by option fields defined on the `[config:ntfy]` configuration section.
+
+#### Examples
+
+1. This is another way to write the "[remote attachments](#ntfy-remote-attachments)"
+   example, where all ntfy options are located on the configuration section, so they
+   will apply for all configured target addresses.
+   ```ini
+   [config:ntfy]
+   targets  = {'test': 'https://ntfy.sh/testdrive'}
+   attach   = https://unsplash.com/photos/spdQ1dVuIHw/download?w=320
+   filename = goat.jpg
+   ```
+
+2. The tutorial [](#processing-frigate-events) explains how to configure mqttwarn to
+   notify the user with events emitted by Frigate, a network video recorder (NVR)
+   with realtime local object detection for IP cameras.
+
 
 [ntfy]: https://ntfy.sh/
+[ntfy publishing options]: https://docs.ntfy.sh/publish/
+[ntfy stored attachments]: https://docs.ntfy.sh/config/#attachments
+[pub-sub]: https://en.wikipedia.org/wiki/Publish%E2%80%93subscribe_pattern
 
 
 ### `desktopnotify`

mqttwarn/commands.py

@@ -26,7 +26,7 @@ def run():
     Usage:
       {program} [make-config]
       {program} [make-udf]
-      {program} [--config=] [--config-file=] [--plugin=] [--options=]
+      {program} [--config=] [--config-file=] [--plugin=] [--options=] [--data=]
       {program} --version
       {program} (-h | --help)
 
@@ -39,8 +39,8 @@ def run():
       [--plugin=]               The plugin name to load. This can either be a
                                 full qualified Python package/module name or a
                                 path to a Python file.
-      [--options=]              Configuration options to propagate to the plugin
-                                entrypoint.
+      [--options=]              Configuration options to propagate to the plugin entrypoint.
+      [--data=]                 Data to propagate to the plugin entrypoint.
 
     Bootstrapping options:
       make-config               Dump configuration file blueprint to STDOUT,
@@ -76,22 +76,23 @@ def run():
 
         # Decode arguments
         arg_plugin = options["--plugin"]
-        arg_options = json.loads(options["--options"])
+        arg_options = options["--options"] and json.loads(options["--options"]) or {}
+        arg_data = options["--data"] and json.loads(options["--data"]) or {}
         arg_config = None
         if "--config" in options and options["--config"] is not None:
             arg_config = json.loads(options["--config"])
 
         # Launch service plugin in standalone mode
         launch_plugin_standalone(
-            arg_plugin, arg_options, configfile=options.get("--config-file"), config_more=arg_config
+            arg_plugin, arg_options, arg_data, configfile=options.get("--config-file"), config_more=arg_config
         )
 
     # Run mqttwarn in service mode when no command line arguments are given
     else:
         run_mqttwarn()
 
 
-def launch_plugin_standalone(plugin, options, configfile=None, config_more=None):
+def launch_plugin_standalone(plugin, options, data, configfile=None, config_more=None):
 
     # Optionally load configuration file
     does_not_exist = False
@@ -120,7 +121,7 @@ def launch_plugin_standalone(plugin, options, configfile=None, config_more=None)
     logger.info('Running service plugin "{}" with options "{}"'.format(plugin, options))
 
     # Launch service plugin
-    run_plugin(config=config, name=plugin, options=options)
+    run_plugin(config=config, name=plugin, options=options, data=data)
 
 
 def run_mqttwarn():

mqttwarn/core.py

@@ -784,7 +784,7 @@ def bootstrap(config=None, scriptname=None):
         SCRIPTNAME = scriptname
 
 
-def run_plugin(config=None, name=None, options=None):
+def run_plugin(config=None, name=None, options=None, data=None):
     """
     Run service plugins directly without the
     dispatching and transformation machinery.
@@ -817,7 +817,7 @@ def run_plugin(config=None, name=None, options=None):
     item.config = config.config("config:" + name)
     item.service = srv
     item.target = "mqttwarn"
-    item.data = {}  # FIXME
+    item.data = data or {}
 
     # Launch plugin
     module = service_plugins[name]["module"]

mqttwarn/model.py

@@ -40,7 +40,7 @@ def enum(self):
 # Covering old- and new-style configuration layouts. `addrs` has
 # originally been a list of strings, has been expanded to be a
 # list of dictionaries (Apprise), and to be a dictionary (Pushsafer).
-addrs_type = Union[List[Union[str, Dict[str, str]]], Dict[str, str]]
+addrs_type = Union[List[Union[str, Dict[str, str]]], Dict[str, str], str]
 
 
 @dataclass
@@ -52,6 +52,7 @@ class ProcessorItem:
     service: Optional[str] = None
     target: Optional[str] = None
     config: Dict = field(default_factory=dict)
+    # TODO: `addrs` can also be a string or dictionary now.
     addrs: addrs_type = field(default_factory=list)  # type: ignore[assignment]
     priority: Optional[int] = None
     topic: Optional[str] = None

mqttwarn/services/apprise_multi.py

@@ -42,7 +42,7 @@ def plugin(srv, item):
             # Collect URL parameters.
             params = OrderedDict()
 
-            # Obtain and apply all possible Ntfy parameters from data dictionary.
+            # Obtain and apply all possible Apprise parameters from data dictionary.
             params.update(obtain_apprise_arguments(item, APPRISE_ALL_ARGUMENT_NAMES))
 
             # Apply addressee information.

mqttwarn/services/apprise_single.py

@@ -43,7 +43,7 @@ def plugin(srv, item):
         # Collect URL parameters.
         params = OrderedDict()
 
-        # Obtain and apply all possible Ntfy parameters from data dictionary.
+        # Obtain and apply all possible Apprise parameters from data dictionary.
         params.update(obtain_apprise_arguments(item, APPRISE_ALL_ARGUMENT_NAMES))
 
         # Apply addressee information.

mqttwarn/services/apprise_util.py

@@ -30,8 +30,6 @@ def get_all_template_argument_names():
 def obtain_apprise_arguments(item: ProcessorItem, arg_names: list) -> dict:
     """
     Obtain eventual Apprise parameters from data dictionary.
-
-    https://github.com/caronc/apprise/wiki/Notify_ntfy#parameter-breakdown
     """
     params = dict()
     for arg_name in arg_names: