PLG+DOCS: better scaffolding

Author: jokob-sk

docs/PLUGINS_DEV.md

@@ -235,7 +235,9 @@ Check your plugin against these repo-wide conventions before opening a PR (verif
 
 - **`RUN` defaults to `"disabled"`.** True for the large majority of plugins; only core maintenance plugins (`csv_backup`, `db_cleanup`, `maintenance`, `vendor_update`) default to `schedule`. A new optional plugin should load disabled until the user configures it.
 - **Pick `RUN_SCHD` from precedent, not an arbitrary value.** Check the closest existing plugin for its schedule (e.g. `pihole_api_scan` uses `*/5 * * * *`) rather than inventing a new cadence — consistency keeps first-time setup predictable across plugins.
-- **`RUN_TIMEOUT` is a subprocess kill-timer, not a per-request budget.** The core plugin runner (`server/plugin.py`) passes this same value as the hard timeout for the *entire* script (`subprocess` `timeout=`). If your script makes multiple sequential network calls (e.g. two upstream instances, or a per-device lookup in a loop), don't also reuse `RUN_TIMEOUT` as each individual call's timeout — one slow call can then consume the whole budget and get the process killed before it writes its result file, silently dropping the entire run.
+- **`RUN_TIMEOUT` is a subprocess kill-timer, not a per-request budget.** The core plugin runner (`server/plugin.py`) passes this same value as the hard timeout for the *entire* script (`subprocess` `timeout=`). If your script makes multiple sequential network calls (e.g. two upstream instances, or a per-device lookup in a loop), don't also reuse `RUN_TIMEOUT` as each individual call's timeout — one slow call can then consume the whole budget and get the process killed before it writes its result file, silently dropping the entire run. Two correct alternatives, depending on the shape of your loop:
+  - **Looping over a config-declared, known-length list** (e.g. a subnets or IPs setting) — mark that `params` entry with `"timeoutMultiplier": true` in `config.json`. The framework then multiplies the *outer* kill-timeout by that list's length before running your script, so each iteration can safely use the full `RUN_TIMEOUT` internally. See `arp_scan/config.json`'s `subnets` param for a working example.
+  - **Looping over a runtime-variable-length collection** (e.g. a notification queue, where length isn't known until the script runs) — `timeoutMultiplier` doesn't apply here since there's no config-declared count. Instead, divide the *inner* per-call timeout down using `plugin_helper.per_item_timeout(run_timeout, item_count)`, so N sequential calls can't collectively exceed the outer budget. See `server/plugins/_publisher_ntfy/ntfy.py`'s notification loop for a working example.
 - **Reuse existing core settings instead of duplicating them.** If NetAlertX already has a concept your plugin needs (e.g. `API_TOKEN` for its own GraphQL/API endpoint), read it with `get_setting_value("API_TOKEN")` rather than adding a plugin-specific `<PREFIX>_API_TOKEN` — see `server/plugins/sync/sync.py` for the pattern.
 - **Keep `description` strings short.** They render directly in the Settings UI. Put implementation rationale and design trade-offs in the plugin's README or code comments, not the UI-facing description.
 - **For "one or more instances of the same thing," use the nested array + popup-form settings pattern**, not a fixed hardcoded count (e.g. "primary"/"secondary"). See `rest_import` (`RSTIMPRT`)'s `imports` setting for a working example — it also gives each instance its own sub-settings (URL, credentials, per-instance flags) for free.

docs/PLUGINS_DEV_DATA_CONTRACT.md

@@ -85,6 +85,8 @@ The library automatically:
 | 11 | `helpVal3` | string | *conditional* | Helper value 3. If used, all help values must be supplied |
 | 12 | `helpVal4` | string | *conditional* | Helper value 4. If used, all help values must be supplied |
 
+> **Gotcha:** `plugin_helper.py`'s `Plugin_Object.__init__` applies `helpVal1-4 or ""` internally, collapsing any falsy value (`0`, `False`, `""`) to `""` - indistinguishable from "not supplied." `watchedValue1-4` are stored as-is with no such coercion. If a real `0` or `False` is a meaningful value you need to preserve (not just "absent"), put it in a `watchedValue*` column instead of a `helpVal*` one.
+
 ## Usage Guide
 
 ### Empty/Null Values

server/plugins/_publisher_ntfy/ntfy.py

@@ -13,7 +13,7 @@
 
 import conf  # noqa: E402 [flake8 lint suppression]
 from const import confFileName, logPath  # noqa: E402 [flake8 lint suppression]
-from plugin_helper import Plugin_Objects, handleEmpty  # noqa: E402 [flake8 lint suppression]
+from plugin_helper import Plugin_Objects, handleEmpty, per_item_timeout  # noqa: E402 [flake8 lint suppression]
 from utils.datetime_utils import timeNowUTC  # noqa: E402 [flake8 lint suppression]
 from logger import mylog, Logger  # noqa: E402 [flake8 lint suppression]
 from helper import get_setting_value  # noqa: E402 [flake8 lint suppression]
@@ -55,11 +55,18 @@ def main():
     # Retrieve new notifications
     new_notifications = notifications.getNew()
 
+    # RUN_TIMEOUT is enforced by the core plugin runner as this whole
+    # script's kill-timeout, not a safe per-request timeout - divide it
+    # across the queue so a burst of notifications can't let one slow send()
+    # call consume the whole budget and get the process killed mid-loop.
+    run_timeout = int(get_setting_value('NTFY_RUN_TIMEOUT') or 10)
+    per_call_timeout = per_item_timeout(run_timeout, len(new_notifications))
+
     # Process the new notifications (see the Notifications DB table for structure or check the /php/server/query_json.php?file=table_notifications.json endpoint)
     for notification in new_notifications:
 
         # Send notification
-        response_text, response_status_code = send(notification["HTML"], notification["Text"])
+        response_text, response_status_code = send(notification["HTML"], notification["Text"], per_call_timeout)
 
         # Log result
         plugin_objects.add_object(
@@ -131,11 +138,14 @@ def build_custom_headers(entries, reserved_headers):
 
 
 # -------------------------------------------------------------------------------
-def send(html, text):
+def send(html, text, timeout=None):
 
     response_text = ''
     response_status_code = ''
 
+    if timeout is None:
+        timeout = int(get_setting_value('NTFY_RUN_TIMEOUT') or 10)
+
     # settings
     token = get_setting_value('NTFY_TOKEN')
     user = get_setting_value('NTFY_USER')
@@ -178,7 +188,7 @@ def send(html, text):
             headers = headers,
             params  = url_query_string if url_query_string != '' else None,
             verify  = verify_ssl,
-            timeout = get_setting_value('NTFY_RUN_TIMEOUT')
+            timeout = timeout
         )
 
         response_status_code = response.status_code

server/plugins/_publisher_pushsafer/pushsafer.py

@@ -10,7 +10,7 @@
 
 import conf  # noqa: E402 [flake8 lint suppression]
 from const import confFileName, logPath  # noqa: E402 [flake8 lint suppression]
-from plugin_helper import Plugin_Objects, handleEmpty  # noqa: E402 [flake8 lint suppression]
+from plugin_helper import Plugin_Objects, handleEmpty, per_item_timeout  # noqa: E402 [flake8 lint suppression]
 from logger import mylog, Logger  # noqa: E402 [flake8 lint suppression]
 from helper import get_setting_value, hide_string  # noqa: E402 [flake8 lint suppression]
 from utils.datetime_utils import timeNowUTC  # noqa: E402 [flake8 lint suppression]
@@ -52,11 +52,18 @@ def main():
     # Retrieve new notifications
     new_notifications = notifications.getNew()
 
+    # RUN_TIMEOUT is enforced by the core plugin runner as this whole
+    # script's kill-timeout, not a safe per-request timeout - divide it
+    # across the queue so a burst of notifications can't let one slow send()
+    # call consume the whole budget and get the process killed mid-loop.
+    run_timeout = int(get_setting_value("PUSHSAFER_RUN_TIMEOUT") or 10)
+    per_call_timeout = per_item_timeout(run_timeout, len(new_notifications))
+
     # Process the new notifications (see the Notifications DB table for structure or check the /php/server/query_json.php?file=table_notifications.json endpoint)
     for notification in new_notifications:
 
         # Send notification
-        response_text, response_status_code = send(notification["Text"])
+        response_text, response_status_code = send(notification["Text"], per_call_timeout)
 
         # Log result
         plugin_objects.add_object(
@@ -74,13 +81,16 @@ def main():
 
 
 # -------------------------------------------------------------------------------
-def send(text):
+def send(text, timeout=None):
 
     response_text = ''
     response_status_code = ''
 
     token = get_setting_value('PUSHSAFER_TOKEN')
 
+    if timeout is None:
+        timeout = int(get_setting_value("PUSHSAFER_RUN_TIMEOUT") or 10)
+
     mylog('verbose', [f'[{pluginName}] PUSHSAFER_TOKEN: "{hide_string(token)}"'])
 
     try:
@@ -97,7 +107,7 @@ def send(text):
             "ut" : 'Open NetAlertX',
             "k" : token,
         }
-        response = requests.post(url, data=post_fields, timeout=get_setting_value("PUSHSAFER_RUN_TIMEOUT"))
+        response = requests.post(url, data=post_fields, timeout=timeout)
         response_status_code = response.status_code
 
         # Check if the request was successful (status code 200)

server/plugins/_publisher_telegram/tg.py

@@ -11,7 +11,7 @@
 
 import conf  # noqa: E402 [flake8 lint suppression]
 from const import confFileName, logPath  # noqa: E402 [flake8 lint suppression]
-from plugin_helper import Plugin_Objects  # noqa: E402 [flake8 lint suppression]
+from plugin_helper import Plugin_Objects, per_item_timeout  # noqa: E402 [flake8 lint suppression]
 from utils.datetime_utils import timeNowUTC  # noqa: E402 [flake8 lint suppression]
 from logger import mylog, Logger  # noqa: E402 [flake8 lint suppression]
 from helper import get_setting_value  # noqa: E402 [flake8 lint suppression]
@@ -53,10 +53,17 @@ def main():
     # Retrieve new notifications
     new_notifications = notifications.getNew()
 
+    # RUN_TIMEOUT is enforced by the core plugin runner as this whole
+    # script's kill-timeout, not a safe per-request timeout - divide it
+    # across the queue so a burst of notifications can't let one slow send()
+    # call consume the whole budget and get the process killed mid-loop.
+    run_timeout = int(get_setting_value('TELEGRAM_RUN_TIMEOUT'))
+    per_call_timeout = per_item_timeout(run_timeout, len(new_notifications))
+
     # Process the new notifications (see the Notifications DB table for structure or check the /php/server/query_json.php?file=table_notifications.json endpoint)
     for notification in new_notifications:
         # Send notification
-        result = send(notification["Text"])
+        result = send(notification["Text"], per_call_timeout)
 
         # Log result
         plugin_objects.add_object(
@@ -79,13 +86,14 @@ def check_config():
 
 
 # -------------------------------------------------------------------------------
-def send(text):
+def send(text, timeout=None):
     """
     Send a Telegram notification.
     """
     limit = get_setting_value('TELEGRAM_SIZE')
-    run_timeout = int(get_setting_value('TELEGRAM_RUN_TIMEOUT'))
-    curl_timeout = str(max(1, run_timeout - 1))
+    if timeout is None:
+        timeout = int(get_setting_value('TELEGRAM_RUN_TIMEOUT'))
+    curl_timeout = str(max(1, timeout - 1))
 
     # Ensure the final payload, including the truncation marker,
     # never exceeds TELEGRAM_SIZE.

server/plugins/adguard_export/script.py

@@ -374,7 +374,7 @@ def main():
     # Read settings
     # ------------------------------------------------------------------
     agrd_url        = get_setting_value("ADGUARDEXP_URL")       or "http://localhost:3000"
-    agrd_user       = get_setting_value("ADGUARDEXP_USER")      or ""
+    agrd_user       = get_setting_value("ADGUARDEXP_USER")      or "admin"
     agrd_pass       = get_setting_value("ADGUARDEXP_PASSWORD")  or ""
     verify_ssl_str      = get_setting_value("ADGUARDEXP_VERIFYSSL")       or "true"
     include_offline_str = get_setting_value("ADGUARDEXP_INCLUDE_OFFLINE") or "true"

server/plugins/adguard_import/adguard_import.py

@@ -66,7 +66,7 @@ def main():
     user = get_setting_value("ADGUARDIMP_USER")
     pw = get_setting_value("ADGUARDIMP_PASS")
     fake_mac_enabled = get_setting_value("ADGUARDIMP_FAKE_MAC")
-    timeout = int(get_setting_value("ADGUARDIMP_RUN_TIMEOUT") or 5)
+    timeout = int(get_setting_value("ADGUARDIMP_RUN_TIMEOUT") or 30)
 
     auth = (user, pw) if user or pw else None
 

server/plugins/nbtscan_scan/nbtscan.py

@@ -36,8 +36,11 @@
 def main():
     mylog('verbose', [f'[{pluginName}] In script'])
 
-    # timeout = get_setting_value('NBLOOKUP_RUN_TIMEOUT')
-    timeout = 20
+    # The "ips" param in config.json is marked timeoutMultiplier: true, so the
+    # framework already scales the outer subprocess kill-timeout by device
+    # count - use the real per-device budget here instead of a hardcoded
+    # value that could exceed what the multiplier actually grants.
+    timeout = int(get_setting_value('NBTSCAN_RUN_TIMEOUT') or 10)
 
     # Initialize the Plugin obj output file
     plugin_objects = Plugin_Objects(RESULT_FILE)

server/plugins/nmap_dev_scan/config.json

@@ -44,7 +44,8 @@
       "name": "subnets",
       "type": "setting",
       "value": "SCAN_SUBNETS",
-      "base64": true
+      "base64": true,
+      "timeoutMultiplier": true
     }
   ],
   "settings": [

server/plugins/plugin_helper.py

@@ -264,6 +264,28 @@ def normalize_mac(mac):
     return ':'.join(normalized_parts)
 
 
+# -------------------------------------------------------------------
+def per_item_timeout(run_timeout, item_count, floor=1):
+    """
+    Divide a RUN_TIMEOUT budget evenly across `item_count` sequential
+    operations (e.g. one HTTP call per queued notification) so no single
+    item can consume the whole script's kill-timeout - the core plugin
+    runner (server/plugin.py) enforces RUN_TIMEOUT as the entire
+    subprocess's hard timeout, not a per-call one.
+
+    Returns run_timeout unchanged when there's 0 or 1 items, so the common
+    single-item case sees no behavior change. For a config-declared,
+    known-length list (e.g. a subnets/IPs setting), prefer the config.json
+    "timeoutMultiplier" mechanism instead - it scales the outer timeout up
+    rather than dividing the inner one down. Use this helper for
+    runtime-variable-length loops (e.g. a notification queue) where
+    timeoutMultiplier doesn't apply.
+    """
+    if item_count <= 1:
+        return run_timeout
+    return max(floor, run_timeout // item_count)
+
+
 # -------------------------------------------------------------------
 class Plugin_Object:
     """