cloudfall 0.2.0__py3-none-any.whl

cloudfall/dashboard.py

@@ -0,0 +1,407 @@
+"""Render a dependency-free static Cloudfall operations dashboard."""
+
+# ruff: noqa: E501
+
+from __future__ import annotations
+
+import hashlib
+import json
+from dataclasses import dataclass
+from html import escape
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+    from cloudfall.operations import (
+        DomainCheck,
+        DomainOperations,
+        FleetOperations,
+        MonitoredFilesystem,
+        OperationsTask,
+        ServerOperations,
+        SmartDeviceEvidence,
+    )
+
+_FILESYSTEM_WARNING_BASIS_POINTS = 8_500
+_FILESYSTEM_CRITICAL_BASIS_POINTS = 9_500
+_SMART_WARNING_PERCENT_USED = 90
+_REFRESH_MINIMUM_SECONDS = 1
+_REFRESH_MAXIMUM_SECONDS = 3_600
+
+
+@dataclass(frozen=True, slots=True)
+class RefreshInterval:
+    """How often live dashboard consumers re-derive and re-fetch evidence."""
+
+    seconds: int
+
+    def __post_init__(self) -> None:
+        """Reject intervals outside the supported live-refresh range."""
+        if not (
+            _REFRESH_MINIMUM_SECONDS <= self.seconds <= _REFRESH_MAXIMUM_SECONDS
+        ):
+            message = (
+                "refresh interval must be between "
+                f"{_REFRESH_MINIMUM_SECONDS} and {_REFRESH_MAXIMUM_SECONDS} "
+                f"seconds, got {self.seconds}"
+            )
+            raise ValueError(message)
+
+    @classmethod
+    def from_boundary(cls, value: object) -> RefreshInterval:
+        """Coerce a boundary value while keeping internal APIs strictly typed."""
+        if isinstance(value, RefreshInterval):
+            return value
+        if not isinstance(value, int) or isinstance(value, bool):
+            message = (
+                "refresh interval must be an integer number of seconds, "
+                f"got {type(value).__name__}"
+            )
+            raise TypeError(message)
+        return cls(value)
+
+    @property
+    def milliseconds(self) -> int:
+        """Return the interval for JavaScript timer consumption."""
+        return self.seconds * 1_000
+
+
+@dataclass(frozen=True, slots=True)
+class DashboardArtifacts:
+    """Files emitted by one dashboard build."""
+
+    index: Path
+    operations: Path
+
+    def as_dict(self) -> dict[str, str]:
+        """Serialize generated artifact paths."""
+        return {
+            "index": str(self.index),
+            "operations": str(self.operations),
+        }
+
+
+def build_dashboard(
+    operations: FleetOperations, output_directory: Path
+) -> DashboardArtifacts:
+    """Write static HTML and its machine-readable operations payload."""
+    output_directory.mkdir(parents=True, exist_ok=True)
+    index_path = output_directory / "index.html"
+    operations_path = output_directory / "operations.json"
+    _atomic_write(
+        operations_path,
+        f"{json.dumps(operations.as_dict(), indent=2, sort_keys=True)}\n",
+    )
+    _atomic_write(index_path, _render_html(operations))
+    return DashboardArtifacts(index=index_path, operations=operations_path)
+
+
+def _atomic_write(path: Path, content: str) -> None:
+    temporary = path.with_suffix(f"{path.suffix}.tmp")
+    temporary.write_text(content, encoding="utf-8")
+    temporary.replace(path)
+
+
+def operations_fingerprint(operations: FleetOperations) -> str:
+    """Hash evidence-derived content, ignoring the generation timestamp."""
+    payload = dict(operations.as_dict())
+    del payload["generatedAt"]
+    serialized = json.dumps(payload, sort_keys=True)
+    return hashlib.sha256(serialized.encode("utf-8")).hexdigest()
+
+
+def render_dashboard_html(
+    operations: FleetOperations, live: RefreshInterval | None = None
+) -> str:
+    """Render the dashboard page, optionally with self-updating live refresh."""
+    return _render_html(operations, live)
+
+
+_LIVE_SCRIPT_TEMPLATE = """<script>
+(() => {
+  const REFRESH_MS = __REFRESH_MS__;
+  const schedule = () => setTimeout(refresh, REFRESH_MS);
+  const setStatus = (text, stale) => {
+    const status = document.getElementById("live-status");
+    status.textContent = text;
+    status.classList.toggle("stale", stale);
+  };
+  const refresh = async () => {
+    try {
+      const response = await fetch(window.location.pathname, { cache: "no-store" });
+      if (!response.ok) {
+        throw new Error(`HTTP ${response.status}`);
+      }
+      const markup = await response.text();
+      const next = new DOMParser().parseFromString(markup, "text/html").querySelector("main");
+      if (next === null) {
+        throw new Error("refresh payload has no <main> element");
+      }
+      const current = document.querySelector("main");
+      if (next.dataset.fingerprint !== current.dataset.fingerprint) {
+        current.replaceWith(next);
+      }
+      setStatus(`live · checked ${new Date().toLocaleTimeString()}`, false);
+    } catch (error) {
+      setStatus(`refresh failed: ${error.message}`, true);
+    }
+    schedule();
+  };
+  schedule();
+})();
+</script>"""
+
+
+def _render_html(
+    operations: FleetOperations, live: RefreshInterval | None = None
+) -> str:
+    payload = operations.as_dict()
+    summary = payload["summary"]
+    if not isinstance(summary, dict):
+        message = "serialized operations summary is not an object"
+        raise TypeError(message)
+    tasks = summary["tasks"]
+    if not isinstance(tasks, dict):
+        message = "serialized operations task summary is not an object"
+        raise TypeError(message)
+    server_cards = "".join(_render_server(server) for server in operations.servers)
+    domain_cards = "".join(_render_domain(domain) for domain in operations.domains)
+    if not domain_cards:
+        domain_cards = '<p class="empty">No desired public domains.</p>'
+    task_rows = "".join(_render_task_row(task) for task in operations.tasks)
+    if not task_rows:
+        task_rows = (
+            '<tr><td colspan="5" class="empty">No open tasks from current '
+            "evidence.</td></tr>"
+        )
+    fingerprint = operations_fingerprint(operations)
+    live_status = (
+        f'<div class="muted" id="live-status">live · every {live.seconds}s</div>'
+        if live is not None
+        else ""
+    )
+    live_script = (
+        _LIVE_SCRIPT_TEMPLATE.replace("__REFRESH_MS__", str(live.milliseconds))
+        if live is not None
+        else ""
+    )
+    return f"""<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>Cloudfall Operations</title>
+  <style>
+    :root {{ color-scheme: dark; --bg: #0c1117; --panel: #151c24;
+      --line: #293442; --text: #e7edf5; --muted: #91a0b2;
+      --healthy: #48c78e; --warning: #ffbd59; --critical: #ff6577;
+      --unknown: #91a0b2; }}
+    * {{ box-sizing: border-box; }}
+    body {{ margin: 0; background: var(--bg); color: var(--text);
+      font: 15px/1.5 ui-sans-serif, system-ui, -apple-system, sans-serif; }}
+    main {{ width: min(1180px, calc(100% - 32px)); margin: 40px auto 64px; }}
+    header {{ display: flex; justify-content: space-between; gap: 24px;
+      align-items: end; margin-bottom: 28px; }}
+    h1, h2, h3, p {{ margin-top: 0; }} h1 {{ margin-bottom: 4px; }}
+    h2 {{ margin: 36px 0 14px; font-size: 19px; }}
+    .muted, code {{ color: var(--muted); }}
+    .badge {{ display: inline-flex; align-items: center; border: 1px solid;
+      border-radius: 999px; padding: 4px 9px; font-size: 12px;
+      font-weight: 700; letter-spacing: .04em; text-transform: uppercase; }}
+    .healthy {{ color: var(--healthy); }} .warning {{ color: var(--warning); }}
+    .critical {{ color: var(--critical); }} .unknown {{ color: var(--unknown); }}
+    .summary {{ display: grid; grid-template-columns: repeat(5, 1fr); gap: 12px; }}
+    .stat, .server, .domain, .table-wrap {{ background: var(--panel); border: 1px solid var(--line);
+      border-radius: 12px; }}
+    .stat {{ padding: 16px; }} .stat strong {{ display: block; font-size: 28px; }}
+    .stat span {{ color: var(--muted); font-size: 13px; }}
+    .servers {{ display: grid; grid-template-columns: repeat(auto-fit, minmax(360px, 1fr));
+      gap: 14px; }}
+    .domains {{ display: grid; grid-template-columns: repeat(auto-fit, minmax(430px, 1fr));
+      gap: 14px; }}
+    .server, .domain {{ padding: 18px; }} .server-head, .domain-head {{ display: flex;
+      justify-content: space-between; gap: 16px; }}
+    .server h3, .domain h3 {{ margin-bottom: 2px; }}
+    table {{ width: 100%; border-collapse: collapse; }}
+    th, td {{ text-align: left; padding: 11px 13px; border-bottom: 1px solid var(--line);
+      vertical-align: top; }}
+    tr:last-child td {{ border-bottom: 0; }} th {{ color: var(--muted);
+      font-size: 12px; letter-spacing: .04em; text-transform: uppercase; }}
+    .table-wrap {{ overflow-x: auto; }} .compact {{ margin-top: 14px; font-size: 13px; }}
+    .compact th, .compact td {{ padding: 7px 8px; }}
+    .usage {{ min-width: 110px; }} .bar {{ height: 6px; background: #27313d;
+      border-radius: 99px; overflow: hidden; margin-top: 5px; }}
+    .bar span {{ display: block; height: 100%; background: currentColor; }}
+    .task-title {{ font-weight: 650; }} .task-detail {{ color: var(--muted);
+      font-size: 13px; margin-top: 2px; }} .empty {{ color: var(--muted);
+      padding: 28px; text-align: center; }}
+    a {{ color: #7dc4ff; }} footer {{ margin-top: 20px; color: var(--muted);
+      font-size: 13px; }}
+    #live-status {{ margin-top: 4px; }} #live-status.stale {{ color: var(--critical); }}
+    @media (max-width: 720px) {{ header {{ display: block; }}
+      .summary {{ grid-template-columns: repeat(2, 1fr); }}
+      .servers, .domains {{ grid-template-columns: 1fr; }} main {{ margin-top: 24px; }} }}
+  </style>
+</head>
+<body>
+<main data-fingerprint="{fingerprint}">
+  <header>
+    <div><h1>Cloudfall Operations</h1><p class="muted">Evidence-backed fleet status</p></div>
+    <div><span class="badge {operations.health.value}">{operations.health.value}</span>
+      <div class="muted">Generated {escape(operations.generated_at.as_string())}</div>{live_status}</div>
+  </header>
+  <section class="summary" aria-label="Fleet summary">
+    <div class="stat"><strong>{len(operations.domains)}</strong><span>services</span></div>
+    <div class="stat"><strong>{len(operations.servers)}</strong><span>servers</span></div>
+    <div class="stat critical"><strong>{tasks["critical"]}</strong><span>critical tasks</span></div>
+    <div class="stat warning"><strong>{tasks["warning"]}</strong><span>warning tasks</span></div>
+    <div class="stat unknown"><strong>{tasks["unknown"]}</strong><span>unknown tasks</span></div>
+  </section>
+  <h2>Services</h2>
+  <section class="domains">{domain_cards}</section>
+  <h2>Servers</h2>
+  <section class="servers">{server_cards}</section>
+  <h2>Open tasks</h2>
+  <div class="table-wrap"><table>
+    <thead><tr><th>Severity</th><th>Server</th><th>Task</th><th>Kind</th><th>Evidence</th></tr></thead>
+    <tbody>{task_rows}</tbody>
+  </table></div>
+  <footer>Read-only projection. <a href="operations.json">View operations JSON</a>.</footer>
+</main>
+{live_script}
+</body>
+</html>
+"""
+
+
+def _render_domain(domain: DomainOperations) -> str:
+    observation = (
+        domain.observed_at.as_string()
+        if domain.observed_at is not None
+        else "No route observation"
+    )
+    deployed_at = (
+        domain.deployed_at.as_string()
+        if domain.deployed_at is not None
+        else "No deployment receipt"
+    )
+    return f"""<article class="domain">
+  <div class="domain-head"><div><h3>{escape(domain.primary_name)}</h3>
+    <div class="muted">{escape(domain.domain_id.value)} ·
+      {escape(domain.proxy_server_id.value)} → {escape(domain.origin_server_id.value)}</div></div>
+    <span class="badge {domain.health.value}">{domain.health.value}</span></div>
+  <table class="compact"><thead><tr><th>Lifecycle</th><th>Status</th><th>Evidence</th></tr></thead>
+    <tbody>
+      {_render_lifecycle_row("Planned", domain.planned.value, "Desired Domain exists")}
+      {_render_lifecycle_row("Ready", domain.ready_to_deploy.value, "Referenced servers are active")}
+      {_render_lifecycle_row("Deployed", domain.deployed.value, deployed_at)}
+      {_render_lifecycle_row("Configured", domain.configuration.value, domain.configuration_detail)}
+    </tbody></table>
+  <table class="compact"><thead><tr><th>Route check</th><th>Status</th><th>Evidence</th></tr></thead>
+    <tbody>
+      {_render_domain_check("DNS / edge", domain.dns)}
+      {_render_domain_check("TLS", domain.tls)}
+      {_render_domain_check("Origin", domain.origin)}
+      {_render_domain_check("Public", domain.public_route)}
+    </tbody></table>
+  <p class="muted" style="margin: 12px 0 0">{escape(observation)}</p>
+</article>"""
+
+
+def _render_lifecycle_row(label: str, status: str, detail: str) -> str:
+    css_class = (
+        "healthy"
+        if status in {"yes", "compliant"}
+        else "warning"
+        if status in {"no", "drifted"}
+        else "unknown"
+    )
+    return f"""<tr><td>{escape(label)}</td>
+  <td><span class="badge {css_class}">{escape(status)}</span></td>
+  <td class="muted">{escape(detail)}</td></tr>"""
+
+
+def _render_domain_check(label: str, check: DomainCheck) -> str:
+    css_class = (
+        "healthy"
+        if check.status.value == "healthy"
+        else "warning"
+        if check.status.value == "unhealthy"
+        else "unknown"
+    )
+    return f"""<tr><td>{escape(label)}</td>
+  <td><span class="badge {css_class}">{escape(check.status.value)}</span></td>
+  <td class="muted">{escape(check.detail)}</td></tr>"""
+
+
+def _render_server(server: ServerOperations) -> str:
+    observation = (
+        server.observed_at.as_string()
+        if server.observed_at is not None
+        else "No observation"
+    )
+    filesystems = "".join(
+        _render_filesystem(filesystem) for filesystem in server.filesystems
+    )
+    if not filesystems:
+        filesystems = '<tr><td colspan="3" class="muted">No filesystem data</td></tr>'
+    smart_rows = "".join(
+        _render_smart_device(device) for device in server.smart_devices
+    )
+    smart_section = (
+        f"""<table class="compact"><thead><tr><th>NVMe</th><th>SMART</th>
+    <th>Endurance</th><th>Temperature</th></tr></thead>
+    <tbody>{smart_rows}</tbody></table>"""
+        if smart_rows
+        else ""
+    )
+    return f"""<article class="server">
+  <div class="server-head"><div><h3>{escape(server.hostname)}</h3>
+    <div class="muted">{escape(server.server_id.value)} · {escape(observation)}</div></div>
+    <span class="badge {server.health.value}">{server.health.value}</span></div>
+  <table class="compact"><thead><tr><th>Mount</th><th>Type</th><th>Usage</th></tr></thead>
+    <tbody>{filesystems}</tbody></table>
+  {smart_section}
+  <p class="muted" style="margin: 12px 0 0">{len(server.tasks)} open tasks</p>
+</article>"""
+
+
+def _render_filesystem(filesystem: MonitoredFilesystem) -> str:
+    severity = (
+        "critical"
+        if filesystem.utilization.basis_points >= _FILESYSTEM_CRITICAL_BASIS_POINTS
+        else "warning"
+        if filesystem.utilization.basis_points >= _FILESYSTEM_WARNING_BASIS_POINTS
+        else "healthy"
+    )
+    percent = filesystem.utilization.percent
+    width = min(percent, 100.0)
+    return f"""<tr><td><code>{escape(filesystem.target.value)}</code></td>
+  <td>{escape(filesystem.filesystem.value)}</td>
+  <td class="usage {severity}">{percent:.1f}%<div class="bar">
+    <span style="width:{width:.1f}%"></span></div></td></tr>"""
+
+
+def _render_smart_device(device: SmartDeviceEvidence) -> str:
+    severity = (
+        "critical"
+        if device.is_degraded
+        else "warning"
+        if device.percentage_used >= _SMART_WARNING_PERCENT_USED
+        else "healthy"
+    )
+    return f"""<tr><td><code>{escape(device.path.value)}</code>
+    <div class="muted">{escape(device.model)}</div></td>
+  <td class="{severity}">{escape(device.overall_health.value)}</td>
+  <td class="{severity}">{device.percentage_used}% used ·
+    {device.available_spare_percent}% spare</td>
+  <td>{device.temperature_celsius}°C</td></tr>"""
+
+
+def _render_task_row(task: OperationsTask) -> str:
+    return f"""<tr><td><span class="badge {task.severity.value}">{task.severity.value}</span></td>
+  <td>{escape(task.server_id.value)}</td>
+  <td><div class="task-title">{escape(task.title)}</div>
+    <div class="task-detail">{escape(task.detail)}</div></td>
+  <td>{escape(task.kind.value)}</td><td><code>{escape(task.source)}</code></td></tr>"""

cloudfall/dashboard_server.py

@@ -0,0 +1,201 @@
+"""Serve a live-refreshing read-only operations dashboard over HTTP."""
+
+from __future__ import annotations
+
+import json
+import threading
+import time
+from dataclasses import dataclass, field
+from http import HTTPStatus
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from typing import TYPE_CHECKING
+
+from cloudfall.dashboard import RefreshInterval, render_dashboard_html
+from cloudfall.inventory import PlatformInventory
+from cloudfall.observation import load_observations
+from cloudfall.operations import UtcTimestamp, build_operations_view
+from cloudfall.service_evidence import (
+    DeploymentReceiptSet,
+    DomainObservationSet,
+    EvidenceTimestamp,
+    SocketDomainNetworkClient,
+    inspect_domains,
+    load_deployment_receipts,
+    load_domain_observations,
+)
+from cloudfall.validation import ConfigValidationError, validate_config
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+    from pathlib import Path
+
+    from cloudfall.operations import FleetOperations
+
+_PORT_MAXIMUM = 65_535
+
+
+@dataclass(frozen=True, slots=True)
+class ListenEndpoint:
+    """Network address the dashboard server binds to."""
+
+    host: str
+    port: int
+
+    def __post_init__(self) -> None:
+        """Reject empty hosts and out-of-range ports."""
+        if not self.host:
+            message = "listen host must not be empty"
+            raise ValueError(message)
+        if not 0 <= self.port <= _PORT_MAXIMUM:
+            message = f"listen port must be within 0..{_PORT_MAXIMUM}, got {self.port}"
+            raise ValueError(message)
+
+
+@dataclass(frozen=True, slots=True)
+class EvidenceSources:
+    """Filesystem locations the dashboard re-derives its view from."""
+
+    project_directory: Path
+    schema_directory: Path
+    observed_directory: Path
+    service_observed_directory: Path
+    deployments_directory: Path
+    inspect_services: bool = False
+
+    def operations_view(self) -> FleetOperations:
+        """Re-validate state and evidence, then build a fresh projection."""
+        state = validate_config(self.project_directory, self.schema_directory)
+        inventory = PlatformInventory.from_state(state)
+        if self.inspect_services:
+            inspect_domains(
+                inventory,
+                self.service_observed_directory,
+                SocketDomainNetworkClient(),
+                observed_at=EvidenceTimestamp.now(),
+            )
+        observations = load_observations(
+            self.observed_directory, self.schema_directory
+        )
+        deployment_receipts = (
+            load_deployment_receipts(
+                self.deployments_directory, self.schema_directory
+            )
+            if self.deployments_directory.is_dir()
+            else DeploymentReceiptSet.empty()
+        )
+        domain_observations = (
+            load_domain_observations(
+                self.service_observed_directory, self.schema_directory
+            )
+            if self.service_observed_directory.is_dir()
+            else DomainObservationSet.empty()
+        )
+        return build_operations_view(
+            inventory,
+            observations,
+            deployment_receipts,
+            domain_observations,
+            generated_at=UtcTimestamp.now(),
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class DashboardSnapshot:
+    """One rendered dashboard build held in memory by the server."""
+
+    html: str
+    operations_json: str
+    built_at: float
+
+
+@dataclass(slots=True)
+class SnapshotCache:
+    """Rebuild dashboard artifacts from evidence at most once per interval."""
+
+    sources: EvidenceSources
+    refresh: RefreshInterval
+    clock: Callable[[], float] = time.monotonic
+    _lock: threading.Lock = field(
+        default_factory=threading.Lock, init=False, repr=False
+    )
+    _snapshot: DashboardSnapshot | None = field(default=None, init=False, repr=False)
+
+    def current(self) -> DashboardSnapshot:
+        """Return the cached snapshot, rebuilding once it has expired."""
+        with self._lock:
+            now = self.clock()
+            snapshot = self._snapshot
+            if snapshot is None or now - snapshot.built_at >= self.refresh.seconds:
+                operations = self.sources.operations_view()
+                payload = json.dumps(
+                    operations.as_dict(), indent=2, sort_keys=True
+                )
+                snapshot = DashboardSnapshot(
+                    html=render_dashboard_html(operations, live=self.refresh),
+                    operations_json=f"{payload}\n",
+                    built_at=now,
+                )
+                self._snapshot = snapshot
+            return snapshot
+
+
+class DashboardHTTPServer(ThreadingHTTPServer):
+    """Threaded HTTP server carrying the shared snapshot cache."""
+
+    daemon_threads = True
+
+    def __init__(self, endpoint: ListenEndpoint, cache: SnapshotCache) -> None:
+        """Bind the endpoint and expose the cache to request handlers."""
+        self.cache = cache
+        super().__init__((endpoint.host, endpoint.port), _DashboardRequestHandler)
+
+
+class _DashboardRequestHandler(BaseHTTPRequestHandler):
+    """Serve the rendered dashboard page and its machine-readable payload."""
+
+    def do_GET(self) -> None:
+        """Route dashboard requests to the current evidence snapshot."""
+        if self.path not in {"/", "/index.html", "/operations.json"}:
+            body = json.dumps({"error": "not found", "path": self.path}, sort_keys=True)
+            self._respond(HTTPStatus.NOT_FOUND, "application/json", f"{body}\n")
+            return
+        try:
+            snapshot = self._cache().current()
+        except ConfigValidationError as error:
+            body = json.dumps(error.as_dict(), sort_keys=True)
+            self._respond(
+                HTTPStatus.INTERNAL_SERVER_ERROR, "application/json", f"{body}\n"
+            )
+            return
+        if self.path == "/operations.json":
+            self._respond(HTTPStatus.OK, "application/json", snapshot.operations_json)
+            return
+        self._respond(HTTPStatus.OK, "text/html; charset=utf-8", snapshot.html)
+
+    def _cache(self) -> SnapshotCache:
+        server = self.server
+        if not isinstance(server, DashboardHTTPServer):
+            message = f"handler bound to unexpected server: {type(server).__name__}"
+            raise TypeError(message)
+        return server.cache
+
+    def _respond(self, status: HTTPStatus, content_type: str, body: str) -> None:
+        encoded = body.encode("utf-8")
+        self.send_response(status)
+        self.send_header("Content-Type", content_type)
+        self.send_header("Content-Length", str(len(encoded)))
+        self.send_header("Cache-Control", "no-store")
+        self.end_headers()
+        self.wfile.write(encoded)
+
+
+def create_dashboard_server(
+    sources: EvidenceSources,
+    endpoint: ListenEndpoint,
+    refresh: RefreshInterval,
+    clock: Callable[[], float] = time.monotonic,
+) -> DashboardHTTPServer:
+    """Build one snapshot eagerly (fail fast), then bind the HTTP server."""
+    cache = SnapshotCache(sources=sources, refresh=refresh, clock=clock)
+    cache.current()
+    return DashboardHTTPServer(endpoint, cache)