feat: [AAP-38755] add documentation for pg_listener, range, tick, url…

…_check and webhook plugins

.config/dictionary.txt

@@ -31,6 +31,7 @@ conftest
 conninfo
 containerd
 darglint
+dbname
 deadsnakes
 digestmod
 docsite

extensions/eda/plugins/event_source/pg_listener.py

@@ -63,6 +63,68 @@
 import xxhash
 from psycopg import AsyncConnection, OperationalError
 
+DOCUMENTATION = r"""
+---
+short_description: Read events from pg_pub_sub.
+description:
+  - An ansible-rulebook event source plugin for reading events from pg_pub_sub.
+options:
+  dsn:
+    description:
+      - The connection string/dsn for Postgres as supported by psycopg/libpq.
+        Refer to https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNSTRING-KEYWORD-VALUE.
+        Either dsn or postgres_params is required.
+    type: str
+  postgres_params:
+    description:
+      - The parameters for the pg connection as they are supported by psycopg/libpq.
+        Refer to https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-PARAMKEYWORDS
+        If the param is already in the dsn, it will be overridden by the value in postgres_params.
+        Either dsn or postgres_params is required.
+    type: dict
+  channels:
+    description:
+      - The list of channels to listen
+    type: list
+    elements: str
+    required: true
+notes:
+  - Chunking - this is just informational, a user doesn't have to do anything
+    special to enable chunking. The sender which is the pg_notify
+    action from ansible rulebook will decide if chunking needs to
+    happen based on the size of the payload.
+  - If the messages are over 7KB the sender will chunk the messages
+    into separate payloads with each payload having having the following
+    keys
+    * _message_chunked_uuid   The unique message uuid
+    * _message_chunk_count    The number of chunks for the message
+    * _message_chunk_sequence The sequence of the current chunk
+    * _chunk                  The actual chunk
+    * _message_length         The total length of the message
+    * _message_xx_hash        A hash for the entire message
+  - The pg_listener source will assemble the chunks and once all the
+    chunks have been received it will deliver the entire payload to the
+    rulebook engine. Before the payload is delivered we validated that the entire
+    message has been received by validating its computed hash.
+"""
+
+EXAMPLES = r"""
+- ansible.eda.pg_listener:
+    dsn: "host=localhost port=5432 dbname=mydb"
+    channels:
+      - my_events
+      - my_alerts
+
+- ansible.eda.pg_listener:
+    postgres_params:
+      host: localhost
+      port: 5432
+      dbname: mydb
+    channels:
+      - my_events
+      - my_alerts
+"""
+
 LOGGER = logging.getLogger(__name__)
 
 MESSAGE_CHUNKED_UUID = "_message_chunked_uuid"

extensions/eda/plugins/event_source/range.py

@@ -1,21 +1,23 @@
-"""range.py.
-
-An ansible-rulebook event source plugin for generating events with an
-increasing index i.
-
-Arguments:
----------
-    limit: The upper limit of the range of the index.
-
-Example:
--------
-    - ansible.eda.range:
-        limit: 5
+import asyncio
+from typing import Any
 
+DOCUMENTATION = r"""
+---
+short_description: Generate events with an increasing index i.
+description:
+  - An ansible-rulebook event source plugin for generating events with an increasing index i.
+options:
+  limit:
+    description:
+      - The upper limit of the range of the index.
+    type: int
+    default: 0
 """
 
-import asyncio
-from typing import Any
+EXAMPLES = r"""
+- ansible.eda.range:
+    limit: 5
+"""
 
 
 async def main(queue: asyncio.Queue[Any], args: dict[str, Any]) -> None:

extensions/eda/plugins/event_source/tick.py

@@ -1,23 +1,25 @@
-"""tick.py.
-
-An ansible-rulebook event source plugin for generating events with an increasing index
-i that never ends.
-
-Arguments:
----------
-    delay: time between ticks
-
-Example:
--------
-    - ansible.eda.tick:
-        delay: 5
-
-"""
-
 import asyncio
 import itertools
 from typing import Any
 
+DOCUMENTATION = r"""
+---
+short_description: Generate events with an increasing index i that never ends.
+description:
+  - An ansible-rulebook event source plugin for generating events with an increasing index i that never ends.
+options:
+  delay:
+    description:
+      - The delay (in seconds) between ticks.
+    type: int
+    default: 1
+"""
+
+EXAMPLES = r"""
+- ansible.eda.tick:
+    delay: 5
+"""
+
 
 async def main(queue: asyncio.Queue[Any], args: dict[str, Any]) -> None:
     """Generate events with an increasing index i and a time between ticks."""

extensions/eda/plugins/event_source/url_check.py

@@ -1,29 +1,39 @@
-"""url_check.py.
-
-An ansible-rulebook event source plugin that polls a set of URLs and sends
-events with their status.
-
-Arguments:
----------
-    urls - a list of urls to poll
-    delay - the number of seconds to wait between polling
-    verify_ssl - verify SSL certificate
-
-Example:
--------
-    - name: check web server
-      ansible.eda.url_check:
-        urls:
-          - http://44.201.5.56:8000/docs
-        delay: 10
-
-"""
-
 import asyncio
 from typing import Any
 
 import aiohttp
 
+DOCUMENTATION = r"""
+---
+short_description: Poll a set of URLs and sends events with their status.
+description:
+  - An ansible-rulebook event source plugin that polls a set of URLs and sends events with their status.
+options:
+  urls:
+    description:
+      - A list of urls to poll.
+    type: list
+    elements: str
+    required: true
+  delay:
+    description:
+      - The delay (in seconds) between polling.
+    type: int
+    default: 1
+  verify_ssl:
+    description:
+      - Verify SSL certificate.
+    type: bool
+    default: true
+"""
+
+EXAMPLES = r"""
+- ansible.eda.url_check:
+    urls:
+      - http://44.201.5.56:8000/docs
+    delay: 10
+"""
+
 OK = 200
 
 

extensions/eda/plugins/event_source/webhook.py

@@ -1,39 +1,3 @@
-"""webhook.py.
-
-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)
-    port:     The TCP port to listen to.  Defaults to 5000
-    token:    The optional authentication token expected from client
-    certfile: The optional path to a certificate file to enable TLS support
-    keyfile:  The optional path to a key file to be used together with certfile
-    password: The optional password to be used when loading the certificate chain
-    cafile:   The optional path to a file containing CA certificates used to validate
-              clients' certificates
-    capath:   The optional path to a directory containing CA certificates
-              Provide either cafile or capath to enable mTLS support
-    hmac_secret: The optional HMAC secret used to verify the payload from the client
-    hmac_algo: The optional HMAC algorithm used to calculate the payload hash.
-               See your python's hashlib.algorithms_available set for available options.
-               Defaults to sha256
-    hmac_header: The optional HMAC header sent by the client with the payload signature.
-                 Defaults to x-hub-signature-256
-    hmac_format: The optional HMAC signature format format.
-                 Supported formats: hex, base64
-                 Defaults to hex
-
-"""
-
 from __future__ import annotations
 
 import asyncio
@@ -48,6 +12,88 @@
 
 from aiohttp import web
 
+
+DOCUMENTATION = r"""
+---
+short_description: Receive events via a webhook.
+description:
+  - 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.
+options:
+  host:
+    description:
+      - The hostname to listen to.
+    type: str
+    default: "0.0.0.0"
+  port:
+    description:
+      - The TCP port to listen to..
+    type: str
+    required: true
+  token:
+    description:
+      - The optional authentication token expected from client.
+    type: str
+  certfile:
+    description:
+      - The optional path to a certificate file to enable TLS support.
+    type: str
+  keyfile:
+    description:
+      - The optional path to a key file to be used together with certfile.
+    type: str
+  password:
+    description:
+      - The optional password to be used when loading the certificate chain.
+    type: str
+  cafile:
+    description:
+      - The optional path to a file containing CA certificates used to validate clients' certificates.
+    type: str
+  capath:
+    description:
+      - The optional path to a directory containing CA certificates.
+      - Provide either cafile or capath to enable mTLS support.
+    type: str
+  hmac_secret:
+    description:
+      - The optional HMAC secret used to verify the payload from the client.
+    type: str
+  hmac_algo:
+    description:
+      - The optional HMAC algorithm used to calculate the payload hash.
+      - See your python's hashlib.algorithms_available set for available options.
+    type: str
+    default: "sha256"
+  hmac_header:
+    description:
+      - The optional HMAC header sent by the client with the payload signature.
+    type: str
+    default: "x-hub-signature-256"
+  hmac_format:
+    description:
+      -The optional HMAC signature format format.
+    type: str
+    default: "hex"
+    choices: ["hex", "base64"]
+"""
+
+EXAMPLES = r"""
+- ansible.eda.webhook:
+    port: 6666
+    host: 0.0.0.0
+    hmac_secret: "secret"
+    hmac_algo: "sha256"
+    hmac_header: "x-hub-signature-256"
+    hmac_format: "base64"
+"""
+
 if typing.TYPE_CHECKING:
     from collections.abc import Callable