Merge pull request #9 from GabrielSalla/enable-plugins

Create plugins feature

Author: GabrielSalla

README.md

@@ -25,6 +25,8 @@ Sentinela is also well-suited for monitoring state machines, where it is essenti
 # Documentation
 1. [Overview](./docs/overview.md)
 2. [Monitor](./docs/monitor.md)
+2. [Plugins](./docs/plugins.md)
+    1. [Slack](./docs/plugin_slack.md)
 3. [Querying data from databases](./docs/querying.md)
 4. [Registering a monitor](./docs/monitor_registering.md)
 5. [Usage](./docs/usage.md)

docs/monitor.md

@@ -28,9 +28,6 @@ To create a monitor, import specific dependencies from `monitor_utils`. Availabl
 - [`ValueRule`](#value-rule)
 - [`PriorityLevels`](#priority-levels)
 
-**Notifications**
-- [`SlackNotification`](#slack-notification)
-
 **Functions**
 - [`query`](#query)
 - [`read_file`](#read-file)
@@ -225,33 +222,7 @@ result = await asyncio.to_thread(blocking_function)
 # Notifications
 Notifications are optional and can be configured to send notifications to different targets without needing extensive settings for ech monitor. Configure notifications by creating the `notification_options` variable with a list of the desired notifications. Each notification has it's own settings and behaviors.
 
-Available notifications are:
-- `SlackNotification`: Sends notifications to a specified Slack channel.
-
-## Slack notification
-The **SlackNotification** class manages sending notifications for alerts to a specified Slack channel.
-
-Parameters:
-- `channel`: The Slack channel where notifications will be sent.
-- `title`: A title for the notification to help users to identify the problem.
-- `issues_fields`: A list of fields from the issue data to include in the notification.
-- `mention`: Slack user or group to mention if the alert reaches a specified priority. Provide the Slack identifier for a user (e.g., `U0011223344`) or a group (e.g., `G0011223344`). Set to `None` to avoid mentioning anyone. Defaults to `None`.
-- `min_priority_to_mention`: Minimum alert priority that triggers a mention. Mentions will occur if the alert is not acknowledged at the current priority level and it's is greater than or equal to this setting. Defaults to `moderate` (P3).
-
-The Slack message will show the alert and it's issues information. The notification will persist and will be updated until the alert is solved, even if it's priority falls to P5.
-
-The notification also includes buttons to interact with the alert, allowing it to be acknowledged, locked or solved. The latest is only included if the issues setting was set as **not solvable**.
-
-```python
-notification_options = [
-    SlackNotification(
-        channel="C0011223344",
-        title="Alert name",
-        issues_fields=["id", "name"],
-        mention="U0011223344",
-    )
-]
-```
+Notifications are provided as plugins. Check the [plugins documentation](./plugins.md) for more information.
 
 # Reactions
 Reactions are optional and can be configured reactions to specific events by creating a `reaction_options` variable with an instance of the `ReactionOptions` class, available in the `monitor_utils` module.

docs/plugin_slack.md

@@ -0,0 +1,76 @@
+# Slack Plugin
+The Slack plugin offers an interface to interact with Sentinela through Slack. It allows users to receive notifications from Sentinela in a Slack channel while also providing useful commands from notification buttons or Slack messages mentioning the Sentinela bot.
+
+## Slack commands
+Sentinela provides two main ways to interact through Slack:
+1. **Buttons** in notifications sent to a Slack channel.
+2. **Messages** mentioning the Sentinela Slack app directly.
+
+### Buttons in notifications
+Slack notifications can include buttons to interact with the notifications, depending on it's priority and status. Buttons are shown only for active notifications.
+
+Possible buttons:
+- **Ack**: Acknowledge the alert. Visible if the alert has not yet been acknowledged at the priority level.
+- **Lock**: Lock the alert. Visible if the alert is not already locked.
+- **Solve**: Solves the alert. Visible only if the monitor’s issue settings is set as **not solvable**.
+
+![Slack message with buttons](./images/slack_notification_message_with_buttons.png)
+
+### Messages mentioning Sentinela
+As a Slack app, Sentinela can also respond to direct commands sent in a message. To interact this way, mention the Sentinela app, followed by the desired action.
+
+Available commands:
+- `disable monitor {monitor_name}`: Disable the specified monitor.
+- `enable monitor {monitor_name}`: Enable the specified monitor.
+- `ack {alert_id}`: Acknowledge the specified alert.
+- `lock {alert_id}`: Lock the specified alert.
+- `solve {alert_id}`: Solve the specified alert.
+- `drop issue {issue_id}`: Drop the specified issue.
+- `resend notifications`: Delete and resend all active notifications for the current channel. Sometimes a Slack channel can have a lot of messages and a notification might get lost in the past. This command will resend the notification message so it'll be among the latest messages.
+
+Examples:
+- `@Sentinela disable monitor some_monitor`
+- `@Sentinela enable monitor some_monitor`
+- `@Sentinela ack 1234`
+- `@Sentinela lock 2345`
+- `@Sentinela solve 3456`
+- `@Sentinela drop issue 1212`
+- `@Sentinela resend notifications`
+
+> [!WARNING]
+> Ensure the message is using the correct `@` mention for the Sentinela Slack app in your workspace.
+
+## Actions
+Slack plugin implements a single action to handle the `resend notification` command.
+
+## Notifications
+```python
+from plugins.slack.notifications import SlackNotification
+```
+
+The **SlackNotification** class manages sending notifications for alerts to a specified Slack channel.
+
+Parameters:
+- `channel`: The Slack channel where notifications will be sent.
+- `title`: A title for the notification to help users to identify the problem.
+- `issues_fields`: A list of fields from the issue data to include in the notification.
+- `mention`: Slack user or group to mention if the alert reaches a specified priority. Provide the Slack identifier for a user (e.g., `U0011223344`) or a group (e.g., `G0011223344`). Set to `None` to avoid mentioning anyone. Defaults to `None`.
+- `min_priority_to_mention`: Minimum alert priority that triggers a mention. Mentions will occur if the alert is not acknowledged at the current priority level and it's is greater than or equal to this setting. Defaults to `moderate` (P3).
+
+The Slack message will show the alert and it's issues information. The notification will persist and will be updated until the alert is solved, even if it's priority falls to P5.
+
+The notification also includes buttons to interact with the alert, allowing it to be acknowledged, locked or solved. The latest is only included if the issues setting was set as **not solvable**.
+
+```python
+notification_options = [
+    SlackNotification(
+        channel="C0011223344",
+        title="Alert name",
+        issues_fields=["id", "name"],
+        mention="U0011223344",
+    )
+]
+```
+
+## Services
+The Slack plugin includes a service that connects to the Slack websocket API to receive mentions and button press events. Any event received will queue an action to be processed by Sentinela.

docs/plugins.md

@@ -0,0 +1,69 @@
+# Plugins
+Plugins are a way to add functionality to Sentinela without needing to edit the application code. Plugins can be added to the `src/plugins` directory and will be automatically loaded by Sentinela.
+
+Each plugin is a module that can implement it's own behaviors. Each plugin should follow the following basic structure:
+
+```
+src/plugins/my_plugin
+├── __init__.py
+├── actions
+│   └── __init__.py
+├── notifications
+│   └── __init__.py
+└── services
+    └── __init__.py
+```
+
+More files or functionalities can be included with the plugin as long as they are available in each internal `actions`, `notifications` or `services` module.
+
+**Each plugin should provide it's own documentation to guide users on how to use their functionalities.**
+
+## Actions
+Actions are used as custom behaviors to requests received by sentinela. If sentinela receives an action request named `plugin.my_plugin.some_action`, it'll look for the `some_action` function in the `actions` module of `my_plugin`.
+
+Actions must have the following signature:
+```python
+async def action_name(message_payload: dict[Any, Any]):
+```
+
+An example of the action call made by Sentinela is:
+```python
+await plugin.my_plugin.actions.action_name({"key": "value"})
+```
+
+## Notifications
+Notifications are used by monitors, usually to notify about an event. Each notification has it's own settings and behaviors.
+
+Notifications must inherit from the `src.notifications.base_notification.BaseNotification` class. The method `reactions_list` must return a list of reactions that will trigger an action. Each reaction is a tuple with the reaction name and a list of coroutines that must be called when the reaction is triggered.
+
+Example:
+```python
+def reactions_list(self) -> list[tuple[str, list[Coroutine | partial[Coroutine]]]]:
+    """Get a list of events that the notification will react to"""
+    return [
+        ("alert_acknowledged", [handle_event_acknowledged]),
+        ("alert_created", [handle_event_created]),
+        ("alert_solved", [handle_event_solved]),
+    ]
+```
+
+The reaction functions must follow the same structure presented in the [Monitor](./monitors.md) documentation.
+
+## Services
+Services are used when the plugin has some initialization or running service. An example of a running service is a websocket connection to an external provider.
+
+Each service in the services directory should have the `start` and `stop` async functions. The `start` function is called when Sentinela is starting and the `stop` function is called when Sentinela is finishing.
+
+The `start` function will receive, as parameters, the `controller_enabled` and `executor_enabled` booleans. These parameters are used to know if the controller and executor are running in the current process and can be used to control which functionalities might be enabled or provided in each scenario.
+
+The `start` and `stop` functions must have the following signatures:
+
+```python
+async def init(controller_enabled: bool, executor_enabled: bool): ...
+
+async def stop(): ...
+```
+
+## Built-in plugins
+Sentinela comes with some built-in plugins that can be used to extend the application's functionality.
+- [Slack](./plugin_slack.md)

docs/slack_commands.md

@@ -2,14 +2,8 @@
 import random
 from typing import TypedDict
 
-from monitor_utils import (
-    AlertOptions,
-    CountRule,
-    IssueOptions,
-    MonitorOptions,
-    PriorityLevels,
-    SlackNotification,
-)
+from monitor_utils import AlertOptions, CountRule, IssueOptions, MonitorOptions, PriorityLevels
+from plugins.slack import SlackNotification
 
 monitor_options = MonitorOptions(
     update_cron="* * * * *",

sample_monitors/test_monitor/test_monitor.py

@@ -11,8 +11,6 @@
 import utils.app as app
 from configs import configs
 from models import Monitor
-from services.slack import websocket as slack_websocket
-from utils.async_tools import do_concurrently
 from utils.exception_handling import catch_exceptions
 from utils.time import format_datetime_iso, is_triggered, now, time_since, time_until_next_trigger
 
@@ -58,13 +56,6 @@ async def diagnostics() -> tuple[dict[str, Any], list[str]]:
     return status, issues
 
 
-async def _init():
-    """Initialize the controller components"""
-    # Start the Slack websocket only at the controller
-    if configs.slack_websocket_enabled:
-        await slack_websocket.init()
-
-
 async def _queue_task(monitor: Monitor, tasks: list[str]):
     """Send a message to the queue with the monitor tasks that should be executed"""
     monitor.set_queued(True)
@@ -148,8 +139,6 @@ async def run():
 
     _logger.info("Controller running")
 
-    await _init()
-
     # Load configs
     controller_process_schedule = configs.controller_process_schedule
 
@@ -182,4 +171,3 @@ async def run():
 
     # Wait for Slack websocket and all tasks to finish
     _logger.info("Finishing")
-    await do_concurrently(slack_websocket.close(), *tasks)

src/components/controller/controller.py

@@ -4,12 +4,11 @@
 import traceback
 from typing import Any
 
+import plugins
 import registry as registry
 from base_exception import BaseSentinelaException
 from configs import configs
-from models import Alert, Issue, Notification, NotificationStatus
-from services.slack import clear_slack_notification
-from utils.async_tools import do_concurrently
+from models import Alert, Issue
 
 _logger = logging.getLogger("request_handler")
 
@@ -58,48 +57,45 @@ async def issue_drop(message_payload: dict[Any, Any]):
     await issue.drop()
 
 
-async def resend_slack_notifications(message_payload: dict[Any, Any]):
-    """Clear all the notifications for the channel and update all active alerts to queue events to
-    send the notifications again"""
-    # Get all active notifications for the channel
-    notifications = await Notification.get_all(
-        Notification.status == NotificationStatus.active,
-        Notification.target == "slack",
-        Notification.data["channel"].astext == message_payload["slack_channel"],
-    )
-
-    if len(notifications) == 0:
-        return
-
-    monitors_ids = {notification.monitor_id for notification in notifications}
-    for monitor_id in monitors_ids:
-        await registry.wait_monitor_loaded(monitor_id)
-
-    await do_concurrently(*[
-        clear_slack_notification(notification)
-        for notification in notifications
-    ])
-
-    alert_ids = list({notification.alert_id for notification in notifications})
-    alerts = await Alert.get_all(Alert.id.in_(alert_ids))
-    await do_concurrently(*[alert.update() for alert in alerts])
-
-
 actions = {
     "alert_acknowledge": alert_acknowledge,
     "alert_lock": alert_lock,
     "alert_solve": alert_solve,
     "issue_drop": issue_drop,
-    "resend_slack_notifications": resend_slack_notifications,
 }
 
 
+def get_action(action_name: str):
+    """Get the action function by its name, checking if it is a plugin action"""
+    if action_name.startswith("plugin."):
+        plugin_name, action_name = action_name.split(".")[1:3]
+
+        plugin = plugins.loaded_plugins.get(plugin_name)
+        if plugin is None:
+            _logger.warning(f"Plugin '{plugin_name}' unknown")
+            return None
+
+        plugin_actions = getattr(plugin, "actions", None)
+        if plugin_actions is None:
+            _logger.warning(f"Plugin '{plugin_name}' doesn't have actions")
+            return None
+
+        action = getattr(plugin_actions, action_name, None)
+        if action is None:
+            _logger.warning(f"Action '{plugin_name}.{action_name}' unknown")
+            return None
+
+        return action
+
+    return actions.get(action_name)
+
+
 async def run(message: dict[Any, Any]):
     """Process a received request"""
     message_payload = message["payload"]
     action_name = message_payload["action"]
 
-    action = actions.get(action_name)
+    action = get_action(action_name)
 
     if action is None:
         _logger.warning(f"Got request with unknown action '{json.dumps(message_payload)}'")

src/components/executor/request_handler.py

@@ -19,6 +19,7 @@
 
 _logger = logging.getLogger("monitor_loader")
 
+RELATIVE_PATH = "src"
 MONITORS_PATH = "_monitors"
 MONITORS_LOAD_PATH = "_monitors_load"
 COOL_DOWN_TIME = 2
@@ -281,5 +282,5 @@ async def wait_stop():
     global _task
     await _task
     _logger.info("Removing temporary monitors paths")
-    shutil.rmtree(MONITORS_LOAD_PATH, ignore_errors=True)
-    shutil.rmtree(MONITORS_PATH, ignore_errors=True)
+    shutil.rmtree(Path(RELATIVE_PATH) / MONITORS_LOAD_PATH, ignore_errors=True)
+    shutil.rmtree(Path(RELATIVE_PATH) / MONITORS_PATH, ignore_errors=True)