diff --git a/.config/dictionary.txt b/.config/dictionary.txt index 92c1acaf..2c9a45c4 100644 --- a/.config/dictionary.txt +++ b/.config/dictionary.txt @@ -31,6 +31,7 @@ conftest conninfo containerd darglint +dbname deadsnakes digestmod docsite diff --git a/extensions/eda/plugins/event_source/pg_listener.py b/extensions/eda/plugins/event_source/pg_listener.py index 9965e9fe..41fc0ab1 100644 --- a/extensions/eda/plugins/event_source/pg_listener.py +++ b/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" diff --git a/extensions/eda/plugins/event_source/range.py b/extensions/eda/plugins/event_source/range.py index f2619733..4afe7ea2 100644 --- a/extensions/eda/plugins/event_source/range.py +++ b/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: diff --git a/extensions/eda/plugins/event_source/tick.py b/extensions/eda/plugins/event_source/tick.py index 4a71f871..1b1cd580 100644 --- a/extensions/eda/plugins/event_source/tick.py +++ b/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.""" diff --git a/extensions/eda/plugins/event_source/url_check.py b/extensions/eda/plugins/event_source/url_check.py index fb3c3898..ae12d492 100644 --- a/extensions/eda/plugins/event_source/url_check.py +++ b/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 diff --git a/extensions/eda/plugins/event_source/webhook.py b/extensions/eda/plugins/event_source/webhook.py index 124b87aa..419fe535 100644 --- a/extensions/eda/plugins/event_source/webhook.py +++ b/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