WIP broken Quart/Slack implementation

docs/source/configuration.rst

@@ -3,7 +3,7 @@
 Configuration
 =============
 
-TBD.
+Configuration of the machine-access-control (MAC) server is accomplished by some JSON configuration files and optional environment variables, as detailed below.
 
 .. _configuration.users-json:
 
@@ -27,6 +27,36 @@ The schema of this file is as follows:
 
 .. jsonschema:: dm_mac.models.machine.CONFIG_SCHEMA
 
+.. _configuration.env-vars:
+
+Environment Variables
+---------------------
+
+.. list-table:: Environment Variables
+   :header-rows: 1
+
+   * - Variable
+     - Required?
+     - Description
+   * - ``USERS_CONFIG``
+     - no
+     - path to users configuration file; default ``./users.json``
+   * - ``MACHINES_CONFIG``
+     - no
+     - path to machines configuration file; default ``./machines.json``
+   * - ``MACHINE_STATE_DIR``
+     - no
+     - path to machine state directory; default ``./machine_state``
+   * - ``SLACK_BOT_TOKEN``
+     - no
+     - If using the Slack integration, the Bot User OAuth Token for your installation of the app.
+   * - ``SLACK_APP_TOKEN``
+     - no
+     - If using the Slack integration, the Socket OAuth Token for your installation of the app.
+   * - ``SLACK_SIGNING_SECRET``
+     - no
+     - If using the Slack integration, the Signing Secret for your installation of the app.
+
 .. _configuration.machine-state-dir:
 
 Machine State Directory

docs/source/index.rst

@@ -10,6 +10,7 @@
    Introduction <introduction>
    Installation <installation>
    Configuration <configuration>
+   Slack Integration <slack>
    Hardware <hardware>
    Administration <admin>
    Contributing and Development <contributing>

docs/source/slack.rst

@@ -0,0 +1,40 @@
+.. _slack:
+
+Slack Integration
+=================
+
+machine-access-control (MAC) offers a Slack integration for logging and control.
+
+.. _slack.setup:
+
+Setup
+-----
+
+To set up the Slack integration:
+
+1. `Create a new Slack app <https://api.slack.com/apps?new_app=1&track=hello-world-bolt>`_
+
+   1. Create your new app "from scratch".
+   2. Set a meaningful name, such as ``machine-access-control`` and create the app in your Workspace.
+   3. In the left menu, navigate to ``OAuth & Permissions``.
+   4. In the "Scopes" pane, under "Bot Token Scopes", click "Add an OAuth Scope" and add scopes for ``app_mentions:read``, ``canvases:read``, ``canvases:write``, ``channels:read``, ``chat:write``, ``groups:read``, ``groups:write``, ``incoming-webhook``, ``users.profile:read``, and ``users:read``.
+
+2. In your workspace, create a new private channel for admins to interact with MAC in, and MAC to post status updates to.
+3. In the left menu, navigate to ``Install App``. Click on the button to install to your workspace. When prompted for a channel for the app to post in, select the private channel that you created in the previous step.
+4. On the next screen, ``Installed App Settings``, copy the ``Bot User OAuth Token`` and set this as the ``SLACK_BOT_TOKEN`` environment variable for the MAC server.
+5. Go back to the main settings for your app and navigate to ``Socket Mode`` under ``Settings`` on the left menu; toggle on ``Enable Socket Mode``. For ``Token Name``, enter ``socket-mode-token`` and click ``Generate``. Copy the generated token and set it as the ``SLACK_APP_TOKEN`` environment variable for the MAC server **TBD is this needed? document on config page.**
+6. Go back to the main settings for your app and navigate to ``Basic Information`` under ``Settings`` on the left menu; in the ``App Credentials`` pane click ``Show`` in the ``Signing Secret`` box and then copy that value; set it as the ``SLACK_SIGNING_SECRET`` environment variable for the MAC server.
+
+.. _slack.configuration:
+
+Configuration
+-------------
+
+TBD.
+
+.. _slack.usage:
+
+Usage
+-----
+
+TBD.

pyproject.toml

@@ -30,6 +30,7 @@ filelock = "^3.15.4"
 prometheus-client = "^0.20.0"
 quart = "^0.19.8"
 asyncio = "^3.4.3"
+slack-bolt = "^1.21.2"
 
 [tool.poetry.group.dev.dependencies]
 Pygments = ">=2.10.0"

src/dm_mac/slack_app.py

@@ -0,0 +1,25 @@
+"""Slack app."""
+
+import os
+from slack_bolt import App
+from slack_bolt.adapter.quart import AsyncQuartReceiver
+from quart import Quart
+import logging
+
+logger: logging.Logger = logging.getLogger(__name__)
+
+
+class SlackApp:
+    """MAC Slack App."""
+
+    def __init__(self, app: Quart) -> None:
+        receiver: AsyncQuartReceiver = AsyncQuartReceiver(app)
+        self.app: App = App(
+            token=os.environ("SLACK_APP_TOKEN"),
+            signing_secret=os.environ("SLACK_SIGNING_SECRET"),
+            receiver=receiver
+        )
+
+    @self.app.event("app_mention")
+    async def handle_app_mention(self, event, say):
+        logging.info("app mention event=%s say=%s", event, say)