WIP: add admin monitor snapshot endpoint for Admin UI

.env.example

@@ -125,6 +125,10 @@ MINT_RPC_SERVER_KEY="./server_private.pem"
 MINT_RPC_SERVER_CERT="./server_cert.pem"
 MINT_RPC_SERVER_CA="./ca_cert.pem"
 
+# Optional API key for admin-only monitoring endpoint GET /v1/admin/monitor
+# If not set, endpoint is disabled.
+# MINT_ADMIN_API_KEY="change-me"
+
 # Limits
 # Max mint balance in satoshis
 # MINT_MAX_BALANCE=1000000

README.md

@@ -271,3 +271,13 @@ poetry run pytest tests
 # Contributing
 
 Developers are invited to contribute to Nutshell. Please see the [contribution guide](CONTRIBUTING.md).
+
+## Experimental admin monitor endpoint
+
+Nutshell now exposes an optional admin-only monitoring endpoint:
+
+- `GET /v1/admin/monitor`
+- authentication: `X-Admin-Key` header
+- enable by setting `MINT_ADMIN_API_KEY` in your environment
+
+If `MINT_ADMIN_API_KEY` is not set, the endpoint is disabled.

cashu/core/models.py

@@ -384,3 +384,32 @@ class PostAuthBlindMintRequest(BaseModel):
 
 class PostAuthBlindMintResponse(BaseModel):
     signatures: List[BlindedSignature] = []
+
+
+# ------- API: ADMIN -------
+class AdminDbCounts(BaseModel):
+    promises: int
+    proofs_used: int
+    proofs_pending: int
+    mint_quotes: int
+    melt_quotes: int
+
+
+class AdminRequestVolume(BaseModel):
+    mint_quotes_last_24h: int
+    melt_quotes_last_24h: int
+
+
+class AdminHostMetrics(BaseModel):
+    disk_total_bytes: int
+    disk_free_bytes: int
+    cpu_load_1m: Optional[float] = None
+    cpu_load_5m: Optional[float] = None
+    cpu_load_15m: Optional[float] = None
+    process_cpu_seconds: float
+
+
+class AdminMonitorResponse(BaseModel):
+    db: AdminDbCounts
+    requests: AdminRequestVolume
+    host: AdminHostMetrics

cashu/core/settings.py

@@ -179,6 +179,13 @@ class MintLimits(MintSettings):
         title="Websocket read timeout",
         description="Timeout for reading from a websocket.",
     )
+    mint_admin_api_key: Optional[str] = Field(
+        default=None,
+        description=(
+            "Optional API key to enable admin-only HTTP monitoring endpoints. "
+            "If unset, admin endpoints are disabled."
+        ),
+    )
 
 
 class FakeWalletSettings(MintSettings):

cashu/mint/admin.py

@@ -0,0 +1,73 @@
+import os
+import shutil
+import time
+from hmac import compare_digest
+from typing import Any, Dict
+
+from fastapi import Header
+
+from ..core.errors import CashuError
+from ..core.settings import settings
+from .startup import ledger
+
+
+class MintAdminAuthError(CashuError):
+    code = 20001
+
+
+def _row_count_query(table: str) -> str:
+    return f"SELECT COUNT(*) as c FROM {ledger.db.table_with_schema(table)}"
+
+
+async def get_admin_monitor_snapshot() -> Dict[str, Any]:
+    since_24h = ledger.db.timestamp_from_seconds(time.time() - 24 * 60 * 60)
+
+    promises = await ledger.db.fetchone(_row_count_query("promises"))
+    proofs_used = await ledger.db.fetchone(_row_count_query("proofs_used"))
+    proofs_pending = await ledger.db.fetchone(_row_count_query("proofs_pending"))
+    mint_quotes = await ledger.db.fetchone(_row_count_query("mint_quotes"))
+    melt_quotes = await ledger.db.fetchone(_row_count_query("melt_quotes"))
+
+    mint_quotes_last_24h = await ledger.db.fetchone(
+        f"SELECT COUNT(*) as c FROM {ledger.db.table_with_schema('mint_quotes')} WHERE created_time >= :since",
+        {"since": since_24h},
+    )
+    melt_quotes_last_24h = await ledger.db.fetchone(
+        f"SELECT COUNT(*) as c FROM {ledger.db.table_with_schema('melt_quotes')} WHERE created_time >= :since",
+        {"since": since_24h},
+    )
+
+    disk = shutil.disk_usage(settings.cashu_dir)
+    load_1m = load_5m = load_15m = None
+    if hasattr(os, "getloadavg"):
+        load_1m, load_5m, load_15m = os.getloadavg()
+
+    return {
+        "db": {
+            "promises": int(promises["c"]),
+            "proofs_used": int(proofs_used["c"]),
+            "proofs_pending": int(proofs_pending["c"]),
+            "mint_quotes": int(mint_quotes["c"]),
+            "melt_quotes": int(melt_quotes["c"]),
+        },
+        "requests": {
+            "mint_quotes_last_24h": int(mint_quotes_last_24h["c"]),
+            "melt_quotes_last_24h": int(melt_quotes_last_24h["c"]),
+        },
+        "host": {
+            "disk_total_bytes": disk.total,
+            "disk_free_bytes": disk.free,
+            "cpu_load_1m": load_1m,
+            "cpu_load_5m": load_5m,
+            "cpu_load_15m": load_15m,
+            "process_cpu_seconds": time.process_time(),
+        },
+    }
+
+
+def require_admin_key(x_admin_key: str | None = Header(default=None)) -> None:
+    configured_key = settings.mint_admin_api_key
+    if not configured_key:
+        raise MintAdminAuthError("admin endpoint disabled")
+    if not x_admin_key or not compare_digest(x_admin_key, configured_key):
+        raise MintAdminAuthError("invalid admin api key")

cashu/mint/router.py

@@ -1,11 +1,12 @@
 import asyncio
 import time
 
-from fastapi import APIRouter, Request, WebSocket, WebSocketDisconnect
+from fastapi import APIRouter, Depends, Request, WebSocket, WebSocketDisconnect
 from loguru import logger
 
 from ..core.errors import KeysetNotFoundError
 from ..core.models import (
+    AdminMonitorResponse,
     GetInfoResponse,
     KeysetsResponse,
     KeysetsResponseKeyset,
@@ -27,6 +28,7 @@
 )
 from ..core.settings import settings
 from ..mint.startup import ledger
+from .admin import get_admin_monitor_snapshot, require_admin_key
 from .cache import RedisCache
 from .limit import limit_websocket, limiter
 
@@ -60,6 +62,17 @@ async def info() -> GetInfoResponse:
     )
 
 
+@router.get(
+    "/v1/admin/monitor",
+    name="Admin monitor snapshot",
+    summary="Admin-only monitoring snapshot for mint and host metrics.",
+    response_model=AdminMonitorResponse,
+)
+async def admin_monitor(_: None = Depends(require_admin_key)) -> AdminMonitorResponse:
+    logger.trace("> GET /v1/admin/monitor")
+    return AdminMonitorResponse.model_validate(await get_admin_monitor_snapshot())
+
+
 @router.get(
     "/v1/keys",
     name="Mint public keys",

tests/mint/test_admin_monitor.py

@@ -0,0 +1,72 @@
+from types import SimpleNamespace
+
+import pytest
+
+from cashu.mint import admin
+
+
+class DummyDB:
+    def table_with_schema(self, table: str) -> str:
+        return table
+
+    def timestamp_from_seconds(self, seconds):
+        return int(seconds)
+
+    async def fetchone(self, query, values=None):
+        if "FROM promises" in query:
+            return {"c": 10}
+        if "FROM proofs_used" in query:
+            return {"c": 11}
+        if "FROM proofs_pending" in query:
+            return {"c": 12}
+        if "FROM mint_quotes" in query and "created_time" not in query:
+            return {"c": 13}
+        if "FROM melt_quotes" in query and "created_time" not in query:
+            return {"c": 14}
+        if "FROM mint_quotes" in query and "created_time" in query:
+            assert values and "since" in values
+            return {"c": 2}
+        if "FROM melt_quotes" in query and "created_time" in query:
+            assert values and "since" in values
+            return {"c": 3}
+        raise AssertionError(f"unexpected query: {query}")
+
+
+@pytest.mark.asyncio
+async def test_get_admin_monitor_snapshot(monkeypatch):
+    monkeypatch.setattr(admin, "ledger", SimpleNamespace(db=DummyDB()))
+    monkeypatch.setattr(admin.settings, "cashu_dir", "/tmp")
+
+    snapshot = await admin.get_admin_monitor_snapshot()
+
+    assert snapshot["db"] == {
+        "promises": 10,
+        "proofs_used": 11,
+        "proofs_pending": 12,
+        "mint_quotes": 13,
+        "melt_quotes": 14,
+    }
+    assert snapshot["requests"] == {
+        "mint_quotes_last_24h": 2,
+        "melt_quotes_last_24h": 3,
+    }
+    assert "disk_total_bytes" in snapshot["host"]
+    assert "process_cpu_seconds" in snapshot["host"]
+
+
+def test_require_admin_key_accepts_valid_key(monkeypatch):
+    monkeypatch.setattr(admin.settings, "mint_admin_api_key", "secret")
+    admin.require_admin_key("secret")
+
+
+@pytest.mark.parametrize("provided", [None, "wrong"])
+def test_require_admin_key_rejects_invalid_key(monkeypatch, provided):
+    monkeypatch.setattr(admin.settings, "mint_admin_api_key", "secret")
+    with pytest.raises(admin.MintAdminAuthError):
+        admin.require_admin_key(provided)
+
+
+def test_require_admin_key_rejects_when_disabled(monkeypatch):
+    monkeypatch.setattr(admin.settings, "mint_admin_api_key", None)
+    with pytest.raises(admin.MintAdminAuthError):
+        admin.require_admin_key("anything")