Proposal: Named parameters for target address descriptor configurations

[amotl]

Dear JP and Ben,

while modernizing mqttwarn on some aspects after taking over maintenance, I regularily touch the important detail about the configuration of the plugin service target address descriptors, originally designed to be a list, mostly. I believe it may be confusing for service plugins which would better need to obtain named parameters instead.

In order to improve this situation, I would like to make a general proposal. Please let me know if you have any objections.

With kind regards,
Andreas.

Status quo

For the SMTP service, this is just perfect.

[config:smtp]
targets = {
    'localj'     : [ 'jpm@localhost' ],
    'special'    : [ 'ben@gmail', 'suzie@example.net' ]
    }

At the Pushover configuration snippet, for example, it is tolerable.

[config:pushover]
targets = {
    'nagios'     : ['userkey1', 'appkey1', 'sound1'],
    'alerts'     : ['userkey2', 'appkey2'],
    'tracking'   : ['userkey1', 'appkey2', None, 'cellphone1,cellphone2'],
    'extraphone' : ['userkey2', 'appkey3']
    }

Problem

On the other hand, this style of configuration is clearly confusing with the Pushsafer plugin, where you would have to constantly maintain a mind map of parameter positions within the list, in order to reason about their meanings. This does not only happen to the user, but also to the maintainer of this plugin.

[config:pushsafer]
targets = {
    'nagios'     : ['privatekey', 'Device ID', 'Icon', 'Sound', 'Vibration', 'URL', 'Url Title', 'Time2Live', 'Priority', 'Retry', 'Expire', 'Answer'],
    'tracking'   : ['aliaskey1'],
    'extraphone' : ['aliaskey2', '', '', '', '', '', '', '60', '2', '60', '600', '0'],
    'warnme'     : ['aliaskey3', '', '', '', '', '', '', '60', '1', '', '', '1']
    }

Proposal

So, my proposal is to use dictionaries instead, where it makes sense to propagate named parameters to service plugins, similarly to how it has been implemented for the Apprise service plugin already, see GH-558 and GH-627.

Of course, backward compatibility should and will be maintained when applying this improvement to any of the existing service plugin configurations ¹.

Example for Apprise

[config:apprise]
; Dispatch message to multiple Apprise plugins.
module   = 'apprise_multi'
targets = {
   'demo-mailto'      : [ {
          'baseuri':  'mailtos://smtp_username:smtp_password@mail.example.org',
          'recipients': ['foo@example.org', 'bar@example.org'],
          'sender': 'monitoring@example.org',
          'sender_name': 'Example Monitoring',
          } ],
   }

Example for Pushsafer

[config:pushsafer]
; https://www.pushsafer.com/en/pushapi
; https://www.pushsafer.com/en/pushapi_ext
targets = {
    'basic': { 'private_key': '3SAz1a2iTYsh19eXIMiO' },
    'nagios': {
        'private_key': '3SAz1a2iTYsh19eXIMiO',
        'device': '52|65|78',
        'icon': 64,
        'sound': 2,
        'vibration': 2,
        'url': 'http://example.org',
        'url_title': 'Example Org',
        'time_to_live': 60,
        'priority': 2,
        'retry': 60,
        'expire': 600,
        'answer': 1,
        },
    'tracking': {
        'private_key': '3SAz1a2iTYsh19eXIMiO',
        'device': 'gs23',
        'icon': 18,
        },
    }

Footnotes

1. I am looking at Pushsafer here, see [Pushsafer] Improve configuration to use named parameters #629. ↩

[amotl]

Hi again,

Of course, backward compatibility should and will be maintained when applying this improvement to any of the existing service plugin configurations.

Let me reference both patches as examples which demonstrate the corresponding improvement for the Pushsafer service configuration, while retaining compatibility with the previous configuration layout.

With kind regards,
Andreas.

• [Pushsafer] Improve configuration to use named parameters #629
• [Pushsafer] Add configuration options "Confirm", "Answer Options", and "Force Answers" #630

[amotl]

Hi again,

at #632 (comment), we reported about improvements to the Frigate » Forward events and snapshots to ntfy integration tutorial.

This also utilizes the improved way of defining named parameters within target address descriptors. I think it works very well, and I haven't heard about any compatibility problems yet.

[config:ntfy]
targets = {
    'test': {
        'url': 'http://username:password@localhost:5555/frigate-testdrive',
        'file': '/tmp/mqttwarn-frigate-{camera}-{label}.png',
        'click': 'https://httpbin.org/anything?camera={event.camera}&label={event.label}&zone={event.entered_zones[0]}',
        # Wait for the file to arrive for three quarters of a second, and delete it after reading.
        '__settings__': {
            'file_retry_tries': 10,
            'file_retry_interval': 0.075,
            'file_unlink': True,
            }
        }
    }

With kind regards,
Andreas.

[amotl]

With GH-676, the Pushbullet service plugin now also uses the modernized variant, based on named parameters.

[config:pushbullet]
targets = {
    "warnme"   : {
        "access_token": "a6FJVAA0LVJKrT8k",
        "recipient": "test@example.org",
        "recipient_type": "email",
        },
    "alertme"   : {
        "access_token": "a6FJVAA0LVJKrT8k",
        "recipient": "ujpah72o0sjAoRtnM0jc",
        },
    }