omdnotificationforwarder 4.0__tar.gz → 4.2__tar.gz

{omdnotificationforwarder-4.0 → omdnotificationforwarder-4.2}/.gitignore

@@ -4,3 +4,5 @@ dist
 sdist
 *.egg
 examples/
+.opencode/
+notificationforwarder/tests/var/

{omdnotificationforwarder-4.0 → omdnotificationforwarder-4.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: omdnotificationforwarder
-Version: 4.0
+Version: 4.2
 Summary: A framework for notification scripts for OMD
 Project-URL: Homepage, https://github.com/lausser/noteventificationforhandlerwarder
 Project-URL: Bug Tracker, https://github.com/lausser/noteventificationforhandlerwarder/issues
@@ -11,6 +11,8 @@ Classifier: Programming Language :: Python :: 3
 Requires-Python: >=3.6.1
 Requires-Dist: coshsh
 Requires-Dist: jinja2
+Provides-Extra: nostr
+Requires-Dist: pynostr; extra == 'nostr'
 Provides-Extra: test
 Requires-Dist: flake8; extra == 'test'
 Requires-Dist: pytest; extra == 'test'
@@ -38,6 +40,8 @@ Let me list some of the formatter/forwarder combinations which are usually found
 |json          |Splunk HEC |
 |json          |RabbitMQ |
 
+|markdown-like Nostr note|Nostr relays |
+
 Of course json is not json, the attributes and values are different depending on the recipient.
 
 
@@ -260,6 +264,34 @@ There is also a SyslogFormatter, which creates the log line as:
 
 If you want a different format, then copy *lib/python/notificationforwarder/syslog/formatter.py* to *local/lib/python/notificationforwarder/syslog/formatter.py* and modify it like you want. Or, with *--formatter*, you can use whatever formatter is suitable, as long as it's payload attribute consists of a line of text.
 
+### Nostr
+
+The Nostr plugin pair publishes an encrypted direct message with labeled lines and default monitoring tags so the alert appears in chat-oriented clients.
+
+Install the optional Nostr support with `pip install notificationforwarder[nostr]`.
+
+|parameter|description|default|
+|---------|-----------|-------|
+|relays|comma-separated relay URLs|`wss://relay.damus.io`|
+|nsec|bech32 private key for signing|required|
+|tags|extra Nostr tags to include|`monitoring` plus host/service/state tags|
+
+Example:
+
+```bash
+$USER1$/notificationforwarder \
+    --forwarder nostr \
+    --forwarderopt relays='wss://relay.damus.io,wss://nostr-pub.wellorder.net' \
+    --forwarderopt nsec='$NSEC$' \
+    --formatter nostr \
+    --eventopt HOSTNAME='$HOSTNAME$' \
+    --eventopt SERVICEDESC='$SERVICEDESC$' \
+    --eventopt SERVICESTATE='$SERVICESTATE$' \
+    --eventopt SERVICEOUTPUT='$SERVICEOUTPUT$'
+```
+
+The recipient `p` tag can be provided through the `tags` forwarder option or custom formatter output. The message content is encrypted before relay publication, so it shows up as a DM in clients that support NIP-04 direct messages.
+
 ## Loggers
 
 The framework uses a modular logging architecture similar to formatters, forwarders, and reporters. By default, notificationforwarder uses **text format logging** - you don't need to do anything, logging works exactly as it did before. The traditional text format is backward compatible with all existing installations.
@@ -349,6 +381,62 @@ class MyloggerLogger(NotificationLogger):
         pass
 ```
 
+## Runtime Architecture
+
+The runtime keeps the historical CLI and plugin model, but the core flow is now split into clearer responsibilities instead of concentrating everything in one large class.
+
+- `baseclass.new(...)`: compatibility entrypoint that creates a configured forwarder instance.
+- `runtime_config.py`: normalizes runtime options, default values, log naming, and spool-related paths.
+- `component_loader.py`: resolves and loads forwarders, formatters, reporters, and loggers using the established naming rules.
+- `runtime_flow.py`: enriches raw events and applies the common forwarding/reporting result flow.
+- `spool.py`: owns sqlite spool persistence, replay batches, and flush-lock retry behavior.
+
+### Forwarding Flow
+
+The runtime flow is:
+
+1. Normalize runtime configuration and initialize logging.
+2. Load the forwarder implementation.
+3. Enrich the raw event with OMD/site metadata.
+4. Load the formatter and build a `FormattedEvent`.
+5. Attempt delivery.
+6. If delivery fails, spool the raw event for retry unless it is a heartbeat.
+7. If a reporter is configured, attach forwarding context and call the reporter.
+
+### Extension Contracts
+
+Custom extensions still follow the existing filesystem and naming conventions:
+
+- Forwarder: `notificationforwarder/<name>/forwarder.py` with class `<Name>Forwarder`
+- Formatter: `notificationforwarder/<name>/formatter.py` with class `<Name>Formatter`
+- Reporter: `notificationforwarder/<name>/reporter.py` with class `<Name>Reporter`
+- Logger: `notificationforwarder/<name>/logger.py` with class `<Name>Logger`
+
+If you pass a dotted class path instead of a simple name, the runtime uses it as an explicit module/class reference. Otherwise it derives the class name by capitalizing the plugin name and appending the expected suffix.
+
+### Runtime Guarantees
+
+- Text logging remains the default and fallback logger.
+- Unknown logger implementations fall back to the text logger and emit a warning.
+- Failed deliveries are spooled in sqlite when possible.
+- Spooled events are retried on later executions before the new event is sent, as long as they have not expired.
+- Expired spool entries are dropped during flush and logged as outdated events.
+- Concurrent flush attempts for the same forwarder are suppressed with a lock file.
+
+## Contributor Verification
+
+When changing runtime code, run the relevant tests at minimum:
+
+```bash
+pytest tests/test_runtime_foundation.py tests/test_delivery_resilience.py tests/test_classes.py
+```
+
+For broader confidence, run the full suite:
+
+```bash
+pytest
+```
+
 ## Reporters
 
 Like *forwarder* and *formatter*, a *reporter* is an instance of a *NotificationReporter* class defined in a file named *reporter.py*. There is one class coming with notificationforwarder, the *NaemonlogReporter*. It's purpose it to write a message to the Naemon logfile. When notificationforwarder is run as a standalone script (and not triggered as a notificationhandler by Naemon), the *NaemonlogReporter* can nevertheless leave a line in the Naemon log.
@@ -375,5 +463,3 @@ define command{
                     >> $USER4$/var/log/notificationforwarder_errors.log 2>&1
 }
 ```
-
-

{omdnotificationforwarder-4.0 → omdnotificationforwarder-4.2}/README.md

@@ -18,6 +18,8 @@ Let me list some of the formatter/forwarder combinations which are usually found
 |json          |Splunk HEC |
 |json          |RabbitMQ |
 
+|markdown-like Nostr note|Nostr relays |
+
 Of course json is not json, the attributes and values are different depending on the recipient.
 
 
@@ -240,6 +242,34 @@ There is also a SyslogFormatter, which creates the log line as:
 
 If you want a different format, then copy *lib/python/notificationforwarder/syslog/formatter.py* to *local/lib/python/notificationforwarder/syslog/formatter.py* and modify it like you want. Or, with *--formatter*, you can use whatever formatter is suitable, as long as it's payload attribute consists of a line of text.
 
+### Nostr
+
+The Nostr plugin pair publishes an encrypted direct message with labeled lines and default monitoring tags so the alert appears in chat-oriented clients.
+
+Install the optional Nostr support with `pip install notificationforwarder[nostr]`.
+
+|parameter|description|default|
+|---------|-----------|-------|
+|relays|comma-separated relay URLs|`wss://relay.damus.io`|
+|nsec|bech32 private key for signing|required|
+|tags|extra Nostr tags to include|`monitoring` plus host/service/state tags|
+
+Example:
+
+```bash
+$USER1$/notificationforwarder \
+    --forwarder nostr \
+    --forwarderopt relays='wss://relay.damus.io,wss://nostr-pub.wellorder.net' \
+    --forwarderopt nsec='$NSEC$' \
+    --formatter nostr \
+    --eventopt HOSTNAME='$HOSTNAME$' \
+    --eventopt SERVICEDESC='$SERVICEDESC$' \
+    --eventopt SERVICESTATE='$SERVICESTATE$' \
+    --eventopt SERVICEOUTPUT='$SERVICEOUTPUT$'
+```
+
+The recipient `p` tag can be provided through the `tags` forwarder option or custom formatter output. The message content is encrypted before relay publication, so it shows up as a DM in clients that support NIP-04 direct messages.
+
 ## Loggers
 
 The framework uses a modular logging architecture similar to formatters, forwarders, and reporters. By default, notificationforwarder uses **text format logging** - you don't need to do anything, logging works exactly as it did before. The traditional text format is backward compatible with all existing installations.
@@ -329,6 +359,62 @@ class MyloggerLogger(NotificationLogger):
         pass
 ```
 
+## Runtime Architecture
+
+The runtime keeps the historical CLI and plugin model, but the core flow is now split into clearer responsibilities instead of concentrating everything in one large class.
+
+- `baseclass.new(...)`: compatibility entrypoint that creates a configured forwarder instance.
+- `runtime_config.py`: normalizes runtime options, default values, log naming, and spool-related paths.
+- `component_loader.py`: resolves and loads forwarders, formatters, reporters, and loggers using the established naming rules.
+- `runtime_flow.py`: enriches raw events and applies the common forwarding/reporting result flow.
+- `spool.py`: owns sqlite spool persistence, replay batches, and flush-lock retry behavior.
+
+### Forwarding Flow
+
+The runtime flow is:
+
+1. Normalize runtime configuration and initialize logging.
+2. Load the forwarder implementation.
+3. Enrich the raw event with OMD/site metadata.
+4. Load the formatter and build a `FormattedEvent`.
+5. Attempt delivery.
+6. If delivery fails, spool the raw event for retry unless it is a heartbeat.
+7. If a reporter is configured, attach forwarding context and call the reporter.
+
+### Extension Contracts
+
+Custom extensions still follow the existing filesystem and naming conventions:
+
+- Forwarder: `notificationforwarder/<name>/forwarder.py` with class `<Name>Forwarder`
+- Formatter: `notificationforwarder/<name>/formatter.py` with class `<Name>Formatter`
+- Reporter: `notificationforwarder/<name>/reporter.py` with class `<Name>Reporter`
+- Logger: `notificationforwarder/<name>/logger.py` with class `<Name>Logger`
+
+If you pass a dotted class path instead of a simple name, the runtime uses it as an explicit module/class reference. Otherwise it derives the class name by capitalizing the plugin name and appending the expected suffix.
+
+### Runtime Guarantees
+
+- Text logging remains the default and fallback logger.
+- Unknown logger implementations fall back to the text logger and emit a warning.
+- Failed deliveries are spooled in sqlite when possible.
+- Spooled events are retried on later executions before the new event is sent, as long as they have not expired.
+- Expired spool entries are dropped during flush and logged as outdated events.
+- Concurrent flush attempts for the same forwarder are suppressed with a lock file.
+
+## Contributor Verification
+
+When changing runtime code, run the relevant tests at minimum:
+
+```bash
+pytest tests/test_runtime_foundation.py tests/test_delivery_resilience.py tests/test_classes.py
+```
+
+For broader confidence, run the full suite:
+
+```bash
+pytest
+```
+
 ## Reporters
 
 Like *forwarder* and *formatter*, a *reporter* is an instance of a *NotificationReporter* class defined in a file named *reporter.py*. There is one class coming with notificationforwarder, the *NaemonlogReporter*. It's purpose it to write a message to the Naemon logfile. When notificationforwarder is run as a standalone script (and not triggered as a notificationhandler by Naemon), the *NaemonlogReporter* can nevertheless leave a line in the Naemon log.
@@ -355,5 +441,3 @@ define command{
                     >> $USER4$/var/log/notificationforwarder_errors.log 2>&1
 }
 ```
-
-

{omdnotificationforwarder-4.0 → omdnotificationforwarder-4.2}/bin/notificationforwarder

@@ -78,7 +78,7 @@ Example for an HTTP-based reporter:
                       help='Logger type: text (default) or json, or custom logger module',
                       default='text')
     parser.add_argument('--version', action='version',
-                      version=f'%(prog)s 4.0')
+                      version=f'%(prog)s 4.2')
 
     args = parser.parse_args()
     if not hasattr(args, 'formatter'):

{omdnotificationforwarder-4.0 → omdnotificationforwarder-4.2}/pyproject.toml

@@ -21,7 +21,7 @@ packages = ["src/notificationforwarder"]
 
 [project]
 name = "omdnotificationforwarder"
-version = "4.0"
+version = "4.2"
 authors = [
   { name="Gerhard Lausser", email="lausser@yahoo.com" },
 ]
@@ -39,6 +39,9 @@ dependencies = [
 ]
 
 [project.optional-dependencies]
+nostr = [
+    "pynostr",
+]
 test = [
     "requests",
     "flake8",