Show effective tunnel status

Author: ibnbd

.env.example

@@ -49,6 +49,8 @@ MAILCUE_CORS_ORIGINS=[]
 # tunnel overlay, its compose file configures the validation relay automatically.
 MAILCUE_VALIDATION_SMTP_PROBE_ENABLED=true
 MAILCUE_VALIDATION_SMTP_TIMEOUT_SECONDS=8
+# Optional sidecar status endpoint used by Settings > Tunnels.
+MAILCUE_TUNNEL_METRICS_URL=http://mailcue-sidecar:9325
 # Hard end-to-end budget; keep below the SDK's default 30-second timeout.
 MAILCUE_VALIDATION_TOTAL_TIMEOUT_SECONDS=25
 MAILCUE_VALIDATION_PROBE_RELAY_HOST=

backend/app/config.py

@@ -125,6 +125,7 @@ class Settings(BaseSettings):
 
     # ── Tunnels (optional outbound relay through remote VPS edges) ─
     tunnels_config_path: str = "/etc/mailcue-sidecar/tunnels.json"
+    tunnel_metrics_url: str = "http://mailcue-sidecar:9325"
 
     @field_validator("mode", mode="before")
     @classmethod

backend/app/tunnels/router.py

@@ -12,6 +12,7 @@
 from app.database import get_db
 from app.dependencies import require_admin, require_scope
 from app.tunnels.schemas import (
+    EffectiveTunnelStatusResponse,
     TunnelClientIdentityRequest,
     TunnelClientIdentityResponse,
     TunnelCreate,
@@ -23,6 +24,7 @@
 from app.tunnels.service import (
     create_tunnel,
     delete_tunnel,
+    effective_tunnel_status,
     get_or_init_client_identity,
     get_tunnel,
     health_check,
@@ -98,6 +100,24 @@ async def reload_tunnels_config(
 # ── Tunnel CRUD ──────────────────────────────────────────────────
 
 
+@router.get(
+    "/status",
+    response_model=EffectiveTunnelStatusResponse,
+    dependencies=[Depends(require_scope(scopes.TUNNEL_READ))],
+)
+async def get_effective_tunnel_status(
+    _admin: User = Depends(require_admin),
+    db: AsyncSession = Depends(get_db),
+) -> EffectiveTunnelStatusResponse:
+    """Return file-managed tunnels plus live sidecar health. **Admin only.**"""
+    reachable, detail, tunnels = await effective_tunnel_status(db)
+    return EffectiveTunnelStatusResponse(
+        sidecar_reachable=reachable,
+        status_detail=detail,
+        tunnels=tunnels,
+    )
+
+
 @router.get(
     "",
     response_model=list[TunnelResponse],

backend/app/tunnels/schemas.py

@@ -122,6 +122,33 @@ class TunnelResponse(BaseModel):
     model_config = ConfigDict(from_attributes=True)
 
 
+class EffectiveTunnelStatus(BaseModel):
+    """Effective sidecar tunnel, including file-managed configurations."""
+
+    id: str
+    name: str
+    endpoint_host: str
+    endpoint_port: int
+    enabled: bool
+    weight: int
+    source: str
+    managed: bool
+    healthy: bool | None = None
+    idle_connections: int | None = None
+    inflight: int | None = None
+    requests_ok: int | None = None
+    requests_err: int | None = None
+    last_success: datetime | None = None
+
+
+class EffectiveTunnelStatusResponse(BaseModel):
+    """Sidecar reachability and its effective tunnel configuration."""
+
+    sidecar_reachable: bool
+    status_detail: str | None = None
+    tunnels: list[EffectiveTunnelStatus]
+
+
 class TunnelClientIdentityRequest(BaseModel):
     """Request body for upserting the client identity public key."""
 

backend/app/tunnels/service.py

@@ -10,25 +10,32 @@
 import json
 import logging
 import os
+import re
 import uuid
 from datetime import UTC, datetime
 from pathlib import Path
 from typing import Any
 
+import httpx
 from sqlalchemy import select
 from sqlalchemy.ext.asyncio import AsyncSession
 
 from app.config import settings
 from app.exceptions import ConflictError, NotFoundError, ValidationError
 from app.tunnels.models import Tunnel, TunnelClientIdentity
-from app.tunnels.schemas import TunnelCreate, TunnelUpdate
+from app.tunnels.schemas import EffectiveTunnelStatus, TunnelCreate, TunnelUpdate
 
 logger = logging.getLogger("mailcue.tunnels")
 
 _SIDECAR_KEY_PATH = "/var/lib/mailcue-sidecar/client.key"
 _TUNNELS_JSON_VERSION = 1
 _DEFAULT_SELECTION = "round_robin"
 _HEALTH_CHECK_TIMEOUT_SECONDS = 5.0
+_SIDECAR_STATUS_TIMEOUT_SECONDS = 3.0
+_PROM_LINE_RE = re.compile(
+    r"^mailcue_tunnel_(?P<metric>up|requests_total|last_success_seconds|inflight|idle_connections)"
+    r"\{(?P<labels>[^}]*)\}\s+(?P<value>[0-9.eE+-]+)$"
+)
 
 
 # ── CRUD ──────────────────────────────────────────────────────────
@@ -41,6 +48,133 @@ async def list_tunnels(db: AsyncSession) -> list[Tunnel]:
     return list(result.scalars().all())
 
 
+def _read_effective_tunnel_entries(path: str | Path) -> tuple[list[dict[str, Any]], str | None]:
+    """Read the sidecar's effective config without exposing public keys."""
+    try:
+        data = json.loads(Path(path).read_text(encoding="utf-8"))
+    except FileNotFoundError:
+        return [], f"Tunnel configuration is not mounted at {path}"
+    except PermissionError:
+        return [], f"Tunnel configuration is not readable at {path}"
+    except (OSError, json.JSONDecodeError) as exc:
+        return [], f"Could not read tunnel configuration: {exc}"
+    entries = data.get("tunnels") if isinstance(data, dict) else None
+    if not isinstance(entries, list):
+        return [], "Tunnel configuration does not contain a tunnels list"
+    return [entry for entry in entries if isinstance(entry, dict)], None
+
+
+def _parse_prometheus_labels(raw: str) -> dict[str, str]:
+    labels: dict[str, str] = {}
+    for match in re.finditer(r'(\w+)="((?:\\.|[^"])*)"', raw):
+        labels[match.group(1)] = match.group(2).replace(r"\"", '"').replace("\\\\", "\\")
+    return labels
+
+
+def _parse_sidecar_metrics(body: str) -> dict[str, dict[str, float]]:
+    """Parse the small, fixed Prometheus surface emitted by the sidecar."""
+    result: dict[str, dict[str, float]] = {}
+    for line in body.splitlines():
+        match = _PROM_LINE_RE.fullmatch(line.strip())
+        if match is None:
+            continue
+        labels = _parse_prometheus_labels(match.group("labels"))
+        tunnel_id = labels.get("tunnel")
+        if not tunnel_id:
+            continue
+        metric = match.group("metric")
+        if metric == "requests_total":
+            outcome = labels.get("outcome")
+            if outcome not in {"ok", "err"}:
+                continue
+            metric = f"requests_{outcome}"
+        result.setdefault(tunnel_id, {})[metric] = float(match.group("value"))
+    return result
+
+
+async def _fetch_sidecar_metrics() -> tuple[bool, str | None, dict[str, dict[str, float]]]:
+    url = settings.tunnel_metrics_url.rstrip("/") + "/metrics"
+    try:
+        async with httpx.AsyncClient(timeout=_SIDECAR_STATUS_TIMEOUT_SECONDS) as client:
+            response = await client.get(url)
+            response.raise_for_status()
+    except httpx.HTTPError as exc:
+        return False, f"Could not reach sidecar metrics at {url}: {exc}", {}
+    return True, None, _parse_sidecar_metrics(response.text)
+
+
+async def effective_tunnel_status(
+    db: AsyncSession,
+) -> tuple[bool, str | None, list[EffectiveTunnelStatus]]:
+    """Return the sidecar's effective file config enriched with live health."""
+    database_tunnels = await list_tunnels(db)
+    database_by_id = {tunnel.id: tunnel for tunnel in database_tunnels}
+    file_entries, config_error = await asyncio.to_thread(
+        _read_effective_tunnel_entries, settings.tunnels_config_path
+    )
+    sidecar_reachable, metrics_error, metrics = await _fetch_sidecar_metrics()
+
+    statuses: list[EffectiveTunnelStatus] = []
+    seen: set[str] = set()
+    for entry in file_entries:
+        tunnel_id = str(entry.get("id", "")).strip()
+        name = str(entry.get("name", tunnel_id)).strip()
+        host = str(entry.get("host", "")).strip()
+        if not tunnel_id or not name or not host:
+            continue
+        try:
+            port = int(entry.get("port", 7843))
+            weight = int(entry.get("weight", 1))
+        except (TypeError, ValueError):
+            continue
+        stat = metrics.get(tunnel_id, {})
+        last_success_value = int(stat.get("last_success_seconds", 0))
+        statuses.append(
+            EffectiveTunnelStatus(
+                id=tunnel_id,
+                name=name,
+                endpoint_host=host,
+                endpoint_port=port,
+                enabled=bool(entry.get("enabled", True)),
+                weight=weight,
+                source="database" if tunnel_id in database_by_id else "config_file",
+                managed=tunnel_id in database_by_id,
+                healthy=bool(stat.get("up")) if tunnel_id in metrics else None,
+                idle_connections=int(stat["idle_connections"])
+                if "idle_connections" in stat
+                else None,
+                inflight=int(stat["inflight"]) if "inflight" in stat else None,
+                requests_ok=int(stat["requests_ok"]) if "requests_ok" in stat else None,
+                requests_err=int(stat["requests_err"]) if "requests_err" in stat else None,
+                last_success=datetime.fromtimestamp(last_success_value, UTC)
+                if last_success_value > 0
+                else None,
+            )
+        )
+        seen.add(tunnel_id)
+
+    # A database row may not have reached the sidecar file yet. Surface it as
+    # managed but not loaded instead of silently dropping it from the UI.
+    for tunnel in database_tunnels:
+        if tunnel.id in seen:
+            continue
+        statuses.append(
+            EffectiveTunnelStatus(
+                id=tunnel.id,
+                name=tunnel.name,
+                endpoint_host=tunnel.endpoint_host,
+                endpoint_port=tunnel.endpoint_port,
+                enabled=tunnel.enabled,
+                weight=tunnel.weight,
+                source="database",
+                managed=True,
+            )
+        )
+
+    status_detail = config_error or metrics_error
+    return sidecar_reachable, status_detail, sorted(statuses, key=lambda item: item.name)
+
+
 async def get_tunnel(tunnel_id: str, db: AsyncSession) -> Tunnel:
     """Fetch a single tunnel by ID or raise :class:`NotFoundError`."""
     tunnel = await db.get(Tunnel, tunnel_id)

backend/tests/test_tunnels.py

@@ -23,11 +23,34 @@
 from httpx import ASGITransport, AsyncClient
 from sqlalchemy.ext.asyncio import AsyncSession
 
+from app.tunnels.service import _parse_sidecar_metrics
+
 # 32 bytes of zeros encoded as base64 -- shape-valid X25519 public key.
 _VALID_PUBKEY_B64: str = base64.b64encode(b"\x00" * 32).decode()
 _VALID_PUBKEY_B64_ALT: str = base64.b64encode(b"\x01" * 32).decode()
 
 
+def test_parse_sidecar_metrics_groups_health_and_outcomes() -> None:
+    metrics = _parse_sidecar_metrics(
+        "\n".join(
+            [
+                'mailcue_tunnel_up{tunnel="edge-1"} 1',
+                'mailcue_tunnel_requests_total{tunnel="edge-1",outcome="ok"} 7',
+                'mailcue_tunnel_requests_total{tunnel="edge-1",outcome="err"} 2',
+                'mailcue_tunnel_idle_connections{tunnel="edge-1"} 3',
+            ]
+        )
+    )
+    assert metrics == {
+        "edge-1": {
+            "up": 1.0,
+            "requests_ok": 7.0,
+            "requests_err": 2.0,
+            "idle_connections": 3.0,
+        }
+    }
+
+
 def _override_settings_path(monkeypatch: pytest.MonkeyPatch, target: Path) -> None:
     """Point ``settings.tunnels_config_path`` at *target* for the duration of the test."""
     from app.config import settings
@@ -99,6 +122,68 @@ async def test_create_tunnel_rejects_invalid_name(
 # ── CRUD round-trip + tunnels.json shape ─────────────────────────
 
 
+async def test_effective_status_surfaces_file_managed_tunnels_and_metrics(
+    client: AsyncClient,
+    monkeypatch: pytest.MonkeyPatch,
+    tmp_path: Path,
+) -> None:
+    """The UI must show working sidecar tunnels even when the DB is empty."""
+    json_path = tmp_path / "tunnels.json"
+    _override_settings_path(monkeypatch, json_path)
+    json_path.write_text(
+        json.dumps(
+            {
+                "version": 1,
+                "tunnels": [
+                    {
+                        "id": "relay-us",
+                        "name": "US relay",
+                        "host": "relay-us.example.com",
+                        "port": 7843,
+                        "edge_pubkey": _VALID_PUBKEY_B64,
+                        "enabled": True,
+                        "weight": 2,
+                    }
+                ],
+            }
+        )
+    )
+
+    async def _fake_metrics() -> tuple[bool, str | None, dict[str, dict[str, float]]]:
+        return (
+            True,
+            None,
+            {
+                "relay-us": {
+                    "up": 1,
+                    "idle_connections": 3,
+                    "inflight": 1,
+                    "requests_ok": 12,
+                    "requests_err": 2,
+                    "last_success_seconds": 1_785_369_600,
+                }
+            },
+        )
+
+    monkeypatch.setattr("app.tunnels.service._fetch_sidecar_metrics", _fake_metrics)
+    response = await client.get("/api/v1/tunnels/status")
+    assert response.status_code == 200, response.text
+    body = response.json()
+    assert body["sidecar_reachable"] is True
+    assert len(body["tunnels"]) == 1
+    tunnel = body["tunnels"][0]
+    assert tunnel["id"] == "relay-us"
+    assert tunnel["endpoint_host"] == "relay-us.example.com"
+    assert tunnel["source"] == "config_file"
+    assert tunnel["managed"] is False
+    assert tunnel["healthy"] is True
+    assert tunnel["idle_connections"] == 3
+    assert tunnel["requests_ok"] == 12
+    # Public keys from tunnels.json must never be returned by the status API.
+    assert "edge_pubkey" not in tunnel
+    assert "server_pubkey" not in tunnel
+
+
 async def test_full_crud_and_tunnels_json(
     client: AsyncClient,
     monkeypatch: pytest.MonkeyPatch,