feat: add raise_exception option to insert_hosts_to_meta filter

extensions/eda/plugins/event_filter/insert_hosts_to_meta.py

@@ -14,6 +14,8 @@
                     string but contains multiple hosts, use this parameter to
                     delimits the hosts. Treat the vale as a single host if the
                     parameter is not present.
+    raise_exception: Whether raise PathNotExistException if host_path does not
+                     exist in the event. Default to false
 
 Example:
 -------
@@ -22,6 +24,7 @@
           host_path: "app.target"
           path_separator: "."
           host_separator: ";"
+          raise_exception: true
 
 """
 
@@ -32,11 +35,16 @@
 import dpath
 
 
+class PathNotExistException(Exception):
+    pass
+
+
 def main(
     event: dict[str, Any],
     host_path: str | None = None,
     host_separator: str | None = None,
     path_separator: str = ".",
+    raise_exception: bool = False,
 ) -> dict[str, Any]:
     """Extract hosts from event data and insert into meta dict."""
     if not host_path:
@@ -46,6 +54,9 @@ def main(
         hosts = dpath.get(event, host_path, path_separator)
     except KeyError:
         # does not contain host
+        if raise_exception:
+            msg = f"Event {event} does not contain {host_path}"
+            raise PathNotExistException(msg)
         return event
 
     if isinstance(hosts, str):

extensions/eda/plugins/event_source/webhook.py

@@ -3,6 +3,13 @@
 An ansible-rulebook event source module for receiving events via a webhook.
 The message must be a valid JSON object.
 
+The body received from the webhook post is placed under the key payload in
+the data pushed to the event queue. Do not expect the host(s) in the path
+"payload.meta.limit" will be automatically used to limit an ansible action
+running on these hosts. Use insert_hosts_to_meta filter instead. See
+https://ansible.readthedocs.io/projects/rulebook/en/latest/host_limit.html
+for more details.
+
 Arguments:
 ---------
     host:     The hostname to listen to. Defaults to 0.0.0.0 (all interfaces)

tests/unit/event_filter/test_insert_hosts_to_meta.py

@@ -1,6 +1,9 @@
 import pytest
 
-from extensions.eda.plugins.event_filter.insert_hosts_to_meta import main as hosts_main
+from extensions.eda.plugins.event_filter.insert_hosts_to_meta import (
+    PathNotExistException,
+    main as hosts_main,
+)
 
 EVENT_DATA_1 = [
     (
@@ -66,3 +69,18 @@ def test_find_hosts(data, args, expected_hosts):
 def test_fail_find_hosts(data, args):
     with pytest.raises(TypeError):
         hosts_main(data, **args)
+
+
+def test_host_path_not_exist():
+    event = {"app": {"target": 5000}}
+    host_path = "app.bad"
+    data = hosts_main(event, host_path=host_path)
+    assert data == event
+
+
+def test_host_path_not_exist_exception():
+    event = {"app": {"target": 5000}}
+    host_path = "app.bad"
+
+    with pytest.raises(PathNotExistException):
+        hosts_main(event, host_path=host_path, raise_exception=True)