feat: add agent management

backend/app/agent_registry/__init__.py

@@ -0,0 +1 @@
+"""Read-only Agent registry projection."""

backend/app/agent_registry/dependencies.py

@@ -0,0 +1,8 @@
+"""Dependencies for the Agent registry read model."""
+
+from app.agent_registry.repository import AgentRegistryRepository
+from app.agent_registry.service import AgentRegistryService
+
+
+def get_agent_registry_service() -> AgentRegistryService:
+    return AgentRegistryService(AgentRegistryRepository())

backend/app/agent_registry/models.py

@@ -0,0 +1,62 @@
+"""Typed read models for Agent Management."""
+
+from datetime import datetime
+from typing import Literal
+from uuid import UUID
+
+from pydantic import BaseModel, Field
+
+
+CredentialState = Literal["legacy", "active", "revoked"]
+RoutingState = Literal["assigned", "unassigned", "disabled"]
+
+
+class AgentRegistrySite(BaseModel):
+    id: UUID
+    name: str
+
+
+class AgentRegistryZone(BaseModel):
+    id: UUID
+    site_id: UUID
+    site_name: str
+    name: str
+    description: str | None = None
+    is_enabled: bool
+    assigned_agent_id: str | None = None
+    networks: list[str] = Field(default_factory=list)
+
+
+class AgentRegistryAgent(BaseModel):
+    agent_id: str
+    display_name: str | None = None
+
+    site_id: UUID | None = None
+    site_name: str
+
+    agent_zone_id: UUID | None = None
+    agent_zone_name: str | None = None
+    agent_zone_enabled: bool | None = None
+
+    hostname: str | None = None
+    version: str | None = None
+    ip_address: str | None = None
+    last_checkin_at: datetime
+
+    credential_state: CredentialState
+    credential_created_at: datetime | None = None
+    credential_revoked_at: datetime | None = None
+
+    routing_state: RoutingState
+
+
+class AgentRegistryData(BaseModel):
+    agents: list[AgentRegistryAgent] = Field(default_factory=list)
+    sites: list[AgentRegistrySite] = Field(default_factory=list)
+    zones: list[AgentRegistryZone] = Field(default_factory=list)
+
+
+class AgentRegistryResponse(BaseModel):
+    data: AgentRegistryData
+    meta: dict[str, object] = Field(default_factory=dict)
+    error: None = None

backend/app/agent_registry/repository.py

@@ -0,0 +1,127 @@
+"""PostgreSQL reads for the durable Agent registry."""
+
+import psycopg
+from psycopg.rows import dict_row
+
+from app.config import settings
+
+
+def default_connection_factory():
+    return psycopg.connect(
+        host=settings.postgres_host,
+        port=settings.postgres_port,
+        dbname=settings.postgres_db,
+        user=settings.postgres_user,
+        password=settings.postgres_password,
+        row_factory=dict_row,
+    )
+
+
+class AgentRegistryRepository:
+    def __init__(self, connection_factory=default_connection_factory):
+        self.connection_factory = connection_factory
+
+    def list_registry(self) -> dict[str, list[dict]]:
+        connection = self.connection_factory()
+
+        try:
+            with connection.cursor() as cur:
+                cur.execute(
+                    """
+                    SELECT
+                        site.id,
+                        site.name
+                    FROM sites AS site
+                    WHERE EXISTS (
+                        SELECT 1
+                        FROM agent_zones AS zone
+                        WHERE zone.site_id = site.id
+                    )
+                    ORDER BY lower(site.name), site.id
+                    """
+                )
+                sites = cur.fetchall()
+
+                cur.execute(
+                    """
+                    SELECT
+                        zone.id,
+                        zone.site_id,
+                        site.name AS site_name,
+                        zone.name,
+                        zone.description,
+                        zone.is_enabled,
+                        assigned.agent_id AS assigned_agent_id,
+                        COALESCE(
+                            array_agg(
+                                network.network::text
+                                ORDER BY network.network::text
+                            ) FILTER (WHERE network.id IS NOT NULL),
+                            ARRAY[]::text[]
+                        ) AS networks
+                    FROM agent_zones AS zone
+                    JOIN sites AS site
+                      ON site.id = zone.site_id
+                    LEFT JOIN minerops_site_agents AS assigned
+                      ON assigned.agent_zone_id = zone.id
+                    LEFT JOIN agent_zone_network_ranges AS network
+                      ON network.agent_zone_id = zone.id
+                    GROUP BY
+                        zone.id,
+                        zone.site_id,
+                        site.name,
+                        zone.name,
+                        zone.description,
+                        zone.is_enabled,
+                        assigned.agent_id
+                    ORDER BY
+                        lower(site.name),
+                        lower(zone.name),
+                        zone.id
+                    """
+                )
+                zones = cur.fetchall()
+
+                cur.execute(
+                    """
+                    SELECT
+                        agent.agent_id,
+                        agent.display_name,
+                        agent.site_id,
+                        COALESCE(site.name, agent.site_name) AS site_name,
+                        agent.agent_zone_id,
+                        zone.name AS agent_zone_name,
+                        zone.is_enabled AS agent_zone_enabled,
+                        agent.hostname,
+                        agent.version,
+                        agent.ip_address,
+                        agent.last_checkin_at,
+                        agent.credential_created_at,
+                        agent.credential_revoked_at,
+                        CASE
+                            WHEN agent.credential_revoked_at IS NOT NULL
+                                THEN 'revoked'
+                            WHEN agent.agent_secret_hash IS NOT NULL
+                                THEN 'active'
+                            ELSE 'legacy'
+                        END AS credential_state
+                    FROM minerops_site_agents AS agent
+                    LEFT JOIN sites AS site
+                      ON site.id = agent.site_id
+                    LEFT JOIN agent_zones AS zone
+                      ON zone.id = agent.agent_zone_id
+                    ORDER BY
+                        lower(COALESCE(site.name, agent.site_name)),
+                        lower(COALESCE(agent.display_name, agent.agent_id)),
+                        agent.agent_id
+                    """
+                )
+                agents = cur.fetchall()
+
+            return {
+                "sites": sites,
+                "zones": zones,
+                "agents": agents,
+            }
+        finally:
+            connection.close()

backend/app/agent_registry/router.py

@@ -0,0 +1,48 @@
+"""Read-only Agent Management API."""
+
+from typing import Annotated
+
+from fastapi import APIRouter, Depends, Response
+
+from app.agent_registry.dependencies import get_agent_registry_service
+from app.agent_registry.models import AgentRegistryResponse
+from app.agent_registry.service import AgentRegistryService
+from app.identity import require_permission
+
+
+router = APIRouter(tags=["agents"])
+
+RegistryService = Annotated[
+    AgentRegistryService,
+    Depends(get_agent_registry_service),
+]
+
+AgentViewer = Annotated[
+    dict,
+    Depends(require_permission("agents.view")),
+]
+
+
+@router.get(
+    "/api/agents",
+    response_model=AgentRegistryResponse,
+)
+def list_agents(
+    response: Response,
+    current_user: AgentViewer,
+    service: RegistryService,
+) -> AgentRegistryResponse:
+    del current_user
+
+    response.headers["Cache-Control"] = "no-store"
+
+    data = service.list_registry()
+
+    return AgentRegistryResponse(
+        data=data,
+        meta={
+            "agent_count": len(data.agents),
+            "site_count": len(data.sites),
+            "zone_count": len(data.zones),
+        },
+    )

backend/app/agent_registry/service.py

@@ -0,0 +1,52 @@
+"""Application service for the Agent Management read model."""
+
+from app.agent_registry.models import (
+    AgentRegistryAgent,
+    AgentRegistryData,
+    AgentRegistrySite,
+    AgentRegistryZone,
+)
+
+
+class AgentRegistryService:
+    def __init__(self, repository):
+        self.repository = repository
+
+    def list_registry(self) -> AgentRegistryData:
+        rows = self.repository.list_registry()
+
+        sites = [
+            AgentRegistrySite(**row)
+            for row in rows["sites"]
+        ]
+
+        zones = [
+            AgentRegistryZone(**row)
+            for row in rows["zones"]
+        ]
+
+        agents: list[AgentRegistryAgent] = []
+
+        for row in rows["agents"]:
+            zone_id = row.get("agent_zone_id")
+            zone_enabled = row.get("agent_zone_enabled")
+
+            if zone_id is None:
+                routing_state = "unassigned"
+            elif zone_enabled is False:
+                routing_state = "disabled"
+            else:
+                routing_state = "assigned"
+
+            agents.append(
+                AgentRegistryAgent(
+                    **row,
+                    routing_state=routing_state,
+                )
+            )
+
+        return AgentRegistryData(
+            agents=agents,
+            sites=sites,
+            zones=zones,
+        )