omdnotificationforwarder 3.0__tar.gz → 4.1__tar.gz

{omdnotificationforwarder-3.0 → omdnotificationforwarder-4.1}/.gitignore

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

{omdnotificationforwarder-3.0 → omdnotificationforwarder-4.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: omdnotificationforwarder
-Version: 3.0
+Version: 4.1
 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
@@ -349,6 +349,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.
@@ -376,4 +432,3 @@ define command{
 }
 ```
 
-

{omdnotificationforwarder-3.0 → omdnotificationforwarder-4.1}/README.md

@@ -329,6 +329,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.
@@ -356,4 +412,3 @@ define command{
 }
 ```
 
-

{omdnotificationforwarder-3.0 → omdnotificationforwarder-4.1}/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 3.0')
+                      version=f'%(prog)s 4.1')
 
     args = parser.parse_args()
     if not hasattr(args, 'formatter'):

{omdnotificationforwarder-3.0 → omdnotificationforwarder-4.1}/pyproject.toml

@@ -21,7 +21,7 @@ packages = ["src/notificationforwarder"]
 
 [project]
 name = "omdnotificationforwarder"
-version = "3.0"
+version = "4.1"
 authors = [
   { name="Gerhard Lausser", email="lausser@yahoo.com" },
 ]