feat: add --workspace-status-json to boardwalkd to generate JSON status for all workspaces (#229)

* feat: add --workspace-status-json for unauthenticated global ws status

Adds a boardwalkd flag `--workspace-status-json` to enable the route
/api/workspaces/status to provide a JSON object containing the status
for all known workspaces.

This can, for example, feed into a secondary monitoring system, allowing
the status of Boardwalk to be centrally monitored by a NOC team, for
example.

Co-authored-by: lo <lorelei@backblaze.com>

Author: asullivan-blze

.gitignore

@@ -1,6 +1,7 @@
 __pycache__/
 .pytest_cache/
 .ruff_cache/
+.ansible/
 .boardwalk/
 .boardwalkd/
 .DS_store

Makefile

@@ -37,12 +37,14 @@ develop-server: develop
 ifdef BOARDWALKD_SLACK_WEBHOOK_URL
 	poetry run boardwalkd serve \
 		--develop \
+		--workspace-status-json \
 		--host-header-pattern="(localhost|127\.0\.0\.1)" \
 		--port=8888 \
 		--url='http://localhost:8888'
 else
 	poetry run boardwalkd serve \
 		--develop \
+		--workspace-status-json \
 		--host-header-pattern="(localhost|127\.0\.0\.1)" \
 		--port=8888 \
 		--url='http://localhost:8888'

pyproject.toml

@@ -6,7 +6,7 @@ build-backend = "poetry.core.masonry.api"
 name = "boardwalk"
 description = "Boardwalk is a linear Ansible workflow engine"
 readme = "README.md"
-version = "0.8.27"
+version = "0.8.28"
 requires-python = ">=3.11,<4"
 authors = [
     {name="Mat Hornbeek", email="84995001+m4wh6k@users.noreply.github.com"},

src/boardwalkd/cli.py

@@ -170,6 +170,13 @@ def cli():
     type=str,
     required=True,
 )
+@click.option(
+    "--workspace-status-json/--no-workspace-status-json",
+    help=("Exposed an unauthenticated JSON object of the status of all workspaces at /api/workspaces/status"),
+    type=bool,
+    default=False,
+    show_envvar=True,
+)
 def serve(
     auth_expire_days: float,
     auth_method: str,
@@ -186,6 +193,7 @@ def serve(
     tls_key: str | None,
     tls_port: int | None,
     url: str,
+    workspace_status_json: bool,
 ):
     """Runs the server"""
     # Validate host_header_pattern
@@ -242,6 +250,7 @@ def serve(
             tls_key_path=tls_key,
             tls_port_number=tls_port,
             url=url,
+            workspace_status_json=workspace_status_json,
         )
     )
 

src/boardwalkd/server.py

@@ -36,6 +36,7 @@
 from boardwalkd.broadcast import handle_slack_broadcast
 from boardwalkd.protocol import ApiLoginMessage, WorkspaceDetails, WorkspaceEvent
 from boardwalkd.state import User, WorkspaceState, load_state, valid_user_roles
+from boardwalkd.utils import is_workspace_active
 
 module_dir = Path(__file__).resolve().parent
 state = load_state()
@@ -518,10 +519,10 @@ def check_xsrf_cookie(self):
         pass
 
     def get_current_user(self) -> bytes | None:
-        """Decodes the API token to return the current logged in user"""
+        """Decodes the API token to return the current logged in user."""
         return self.get_secure_cookie(
             "boardwalk_api_token",
-            value=self.request.headers["boardwalk-api-token"],
+            value=self.request.headers.get("boardwalk-api-token"),
             max_age_days=self.settings["auth_expire_days"],
             min_version=2,
         )
@@ -613,6 +614,32 @@ def get(self):
         return self.send_error(403)
 
 
+class WorkspacesStatusApiHandler(APIBaseHandler):
+    """Returns an unauthenticated, read-only summary of all workspaces for monitoring integrations"""
+
+    # nosemgrep: test.boardwalk.python.security.handler-method-missing-authentication
+    def get(self):
+        result = []
+        for name, ws in state.workspaces.items():
+            entry: dict[str, Any] = {
+                "name": name,
+                "semaphores": ws.semaphores.model_dump(),
+            }
+            if ws.details:
+                entry["details"] = {
+                    "workflow": ws.details.workflow,
+                    "worker": f"{ws.details.worker_username}@{ws.details.worker_hostname}",
+                    "worker_connected": is_workspace_active(workspace_name=name),
+                    "host_pattern": ws.details.host_pattern,
+                    "limit_pattern": "<unknown>" if ws.details.worker_limit == "" else ws.details.worker_limit,
+                    "command": ws.details.worker_command,
+                }
+            if ws.last_seen:
+                entry["last_seen"] = ws.last_seen.isoformat()
+            result.append(entry)
+        self.write({"workspaces": result})
+
+
 class WorkspaceCatchApiHandler(APIBaseHandler):
     """Handles setting a catch on a workspace"""
 
@@ -817,6 +844,7 @@ def make_app(
     slack_error_webhook_url: str,
     slack_webhook_url: str,
     url: str,
+    workspace_status_json: bool,
 ) -> tornado.web.Application:
     """Builds the tornado application object"""
     handlers: list[tornado.web.OutputTransform] = []
@@ -836,6 +864,7 @@ def make_app(
             "server_version": ui_method_server_version,
             "sort_events_by_date": ui_method_sort_events_by_date,
         },
+        "workspace_status_json": workspace_status_json,
         "url": urlparse(url),
         "websocket_ping_interval": 10,
         "xsrf_cookies": True,
@@ -901,6 +930,10 @@ def make_app(
                 r"/api/auth/login/socket",
                 AuthLoginApiWebsocketHandler,
             ),
+            (
+                r"/api/workspaces/status",
+                WorkspacesStatusApiHandler,
+            ),
             (
                 r"/api/workspace/(\w+)/details",
                 WorkspaceDetailsApiHandler,
@@ -955,6 +988,7 @@ async def run(
     slack_webhook_url: str,
     slack_slash_command_prefix: str,
     url: str,
+    workspace_status_json: bool,
 ):
     """Starts the tornado server and IO loop"""
     global state
@@ -969,6 +1003,7 @@ async def run(
         slack_error_webhook_url=slack_error_webhook_url,
         slack_webhook_url=slack_webhook_url,
         url=url,
+        workspace_status_json=workspace_status_json,
     )
 
     if port_number is not None:

src/boardwalkd/slack.py

@@ -39,44 +39,11 @@
 from boardwalkd.protocol import WorkspaceEvent
 from boardwalkd.server import SERVER_URL, SLACK_SLASH_COMMAND_PREFIX, SLACK_TOKENS, internal_workspace_event
 from boardwalkd.server import state as STATE
+from boardwalkd.utils import count_of_workspaces_caught, list_active_workspaces, list_inactive_workspaces
 
 app = AsyncApp(token=SLACK_TOKENS.get("bot"))
 
 
-# Possibly move this elsewhere if these functions are useful in other locations?
-def _count_of_workspaces_caught() -> int:
-    """
-    Returns the number of workspaces which are caught
-    """
-    return len([k for k, v in STATE.workspaces.items() if v.semaphores.caught])
-
-
-def _list_active_workspaces(last_seen_seconds: int = 10, _sorted: bool = True) -> list[str]:
-    """
-    Returns a sorted list[str] of currently active workspaces. Takes
-    `last_seen_seconds`, which corresponds to how long ago the worker connected
-    to the workspace was last seen. Defaults to 10.
-    """
-    workspaces: list[str] = []
-    for name, workspace in STATE.workspaces.items():
-        if (datetime.now(UTC) - workspace.last_seen.replace(tzinfo=UTC)).total_seconds() < last_seen_seconds:  # type: ignore
-            workspaces.append(name)
-    if _sorted:
-        return sorted(workspaces)
-    else:
-        return workspaces
-
-
-def _list_inactive_workspaces(last_seen_seconds: int = 10) -> list[str]:
-    """
-    Returns a sorted list[str] of inactive workspaces. Takes
-    `last_seen_seconds`, which corresponds to the time at which the last
-    connected worker was seen before the workspace is considered inactive.
-    Defaults to 10.
-    """
-    return sorted([name for name in STATE.workspaces.keys() if name not in _list_active_workspaces(last_seen_seconds)])
-
-
 @app.command(f"/{SLACK_SLASH_COMMAND_PREFIX}-version")
 async def hello_command(ack: AsyncAck, body: dict[str, Any], client: AsyncWebClient) -> None:
     await ack()
@@ -273,7 +240,7 @@ async def command_list_active_workspaces(ack: AsyncAck, body: dict[str, Any], cl
     message_blocks = [
         SectionBlock(text=MarkdownTextObject(text="The following workspaces have an active worker connected:"))
     ]
-    active_workspaces = _list_active_workspaces()
+    active_workspaces = list_active_workspaces()
 
     if len(active_workspaces) > 0:
         message_blocks.append(SectionBlock(text=MarkdownTextObject(text=", ".join(active_workspaces))))
@@ -341,8 +308,8 @@ async def app_home_opened(ack: AsyncAck, client: AsyncWebClient, logger: Logger,
         SectionBlock(
             text=" ".join(  # semgrep avoidance https://sg.run/Kl07 -- string-concat-in-list
                 [
-                    f"There are {len(STATE.workspaces)} workspaces in total, of which {_count_of_workspaces_caught()} are",
-                    f"caught, with {len(_list_active_workspaces())} active CLI workers.",
+                    f"There are {len(STATE.workspaces)} workspaces in total, of which {count_of_workspaces_caught()} are",
+                    f"caught, with {len(list_active_workspaces())} active CLI workers.",
                 ]
             )
         ),
@@ -351,7 +318,7 @@ async def app_home_opened(ack: AsyncAck, client: AsyncWebClient, logger: Logger,
 
     _active: list[str] = []
     _inactive: list[str] = []
-    for _list, _workspaces in [(_active, _list_active_workspaces()), (_inactive, _list_inactive_workspaces())]:
+    for _list, _workspaces in [(_active, list_active_workspaces()), (_inactive, list_inactive_workspaces())]:
         for _workspace in _workspaces:
             _list.append(
                 f"{'🕵️‍♀️' if STATE.workspaces[_workspace].details.worker_command == 'check' else '👟'}"

src/boardwalkd/utils.py

@@ -0,0 +1,46 @@
+from datetime import UTC, datetime
+
+from boardwalkd import server
+
+
+def list_active_workspaces(last_seen_seconds: int = 10, _sorted: bool = True) -> list[str]:
+    """
+    Returns a sorted list[str] of currently active workspaces. Takes
+    `last_seen_seconds`, which corresponds to how long ago the worker connected
+    to the workspace was last seen. Defaults to 10.
+    """
+    workspaces: list[str] = []
+    for name, workspace in server.state.workspaces.items():
+        if (datetime.now(UTC) - workspace.last_seen.replace(tzinfo=UTC)).total_seconds() < last_seen_seconds:  # type: ignore
+            workspaces.append(name)
+    if _sorted:
+        return sorted(workspaces)
+    else:
+        return workspaces
+
+
+def is_workspace_active(workspace_name: str, last_seen_seconds: int = 10) -> bool:
+    """Returns Boolean True if the provided workspace name is active, based on the configured `last_seen_seconds` value."""
+    if ws := server.state.workspaces.get(workspace_name):
+        if (datetime.now(UTC) - ws.last_seen.replace(tzinfo=UTC)).total_seconds() < last_seen_seconds:  # type: ignore
+            return True
+    return False
+
+
+def list_inactive_workspaces(last_seen_seconds: int = 10) -> list[str]:
+    """
+    Returns a sorted list[str] of inactive workspaces. Takes
+    `last_seen_seconds`, which corresponds to the time at which the last
+    connected worker was seen before the workspace is considered inactive.
+    Defaults to 10.
+    """
+    return sorted(
+        [name for name in server.state.workspaces.keys() if name not in list_active_workspaces(last_seen_seconds)]
+    )
+
+
+def count_of_workspaces_caught() -> int:
+    """
+    Returns the number of workspaces which are caught
+    """
+    return len([k for k, v in server.state.workspaces.items() if v.semaphores.caught])