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_error:    Whether raise PathNotExistError 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_error: true
 
 """
 
@@ -32,20 +35,29 @@
 import dpath
 
 
+class PathNotExistError(Exception):
+    pass
+
+
 def main(
     event: dict[str, Any],
     host_path: str | None = None,
     host_separator: str | None = None,
     path_separator: str = ".",
+    *,
+    raise_error: bool = False,
 ) -> dict[str, Any]:
     """Extract hosts from event data and insert into meta dict."""
     if not host_path:
         return event
 
     try:
         hosts = dpath.get(event, host_path, path_separator)
-    except KeyError:
+    except KeyError as error:
         # does not contain host
+        if raise_error:
+            msg = f"Event {event} does not contain {host_path}"
+            raise PathNotExistError(msg) from error
         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,7 @@
 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 PathNotExistError
 
 EVENT_DATA_1 = [
     (
@@ -66,3 +67,16 @@ 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"
+    assert hosts_main(event, host_path=host_path) == event
+
+
+def test_host_path_not_exist_exception():
+    event = {"app": {"target": 5000}}
+    host_path = "app.bad"
+    with pytest.raises(PathNotExistError):
+        hosts_main(event, host_path=host_path, raise_error=True)