Feature: extend health endpoint metadata

- derive service name from pyproject.toml
- add uptime starttime and uptime seconds
- add .data total size and first-level directory sizes
- add pytest coverage for the health response shape - 2026-03-15 23:53:00

Author: mgarcia01752

CODING_AGENTS.md

@@ -47,6 +47,7 @@ Before introducing new types, validators, formats, or storage conventions:
 - When adding new behavior, include tests covering the change.
 - New classes must have pytest coverage at a minimum for IPC and system calls.
 - Use `SystemCall` (`src/pypnm/lib/system_call/`) for subprocess/system calls; do not call `subprocess.run` directly in app code.
+- Avoid `try`/`except` inside hot loops; Ruff PERF rules flag this often. Move exception handling into a helper or restructure the loop before handing back commit/save commands.
 - Avoid broad refactors unless explicitly requested.
 - Any changes to `deploy/docker/config/system.json` must also be made in `demo/settings/system.json`.
 - Keep `deploy/docker/config/system.json.template` aligned with `deploy/docker/config/system.json`.
@@ -117,6 +118,7 @@ Before introducing new types, validators, formats, or storage conventions:
 - Testing expectations:
   - Run at least: `python3 -m compileall src`, `ruff check src`, `ruff format --check .`, `pytest -q`.
   - After any code change, run `ruff check src` and `pytest -q`. If only Markdown changes are made, run `mkdocs build -s` instead.
+  - Review new loops and exception paths for Ruff performance rules before finalizing; do not rely on the user to discover PERF issues during `git-save.sh`.
   - This is mandatory for every code update in this repo: do not finalize work without reporting `ruff check` and `pytest` results (or a clear blocker).
   - If an integration test is optional/gated (for example Postgres DSN), note skips explicitly in the summary.
 - Troubleshooting:

docs/kubernetes/kind-freelens.md

@@ -38,7 +38,37 @@ kubectl port-forward --namespace "${NAMESPACE}" deploy/pypnm-api 8000:8000
 curl -i http://127.0.0.1:8000/health
 ```
 
-If the returned `version` is older than expected, verify the tag used in the deploy command and confirm the namespace matches the running deployment.
+Example response:
+
+```json
+{
+  "status": "ok",
+  "service": {
+    "name": "pypnm-docsis",
+    "version": "1.4.2.0"
+  },
+  "uptime": {
+    "starttime": 1773640097,
+    "uptime": 1
+  },
+  "data": {
+    "path": ".data",
+    "size_bytes": 1761579619,
+    "directories": {
+      "json": 1728244816,
+      "xlsx": 0,
+      "pnm": 17349665,
+      "csv": 2819493,
+      "png": 2805111,
+      "db": 3388387,
+      "archive": 6968882,
+      "msg_rsp": 3265
+    }
+  }
+}
+```
+
+If the returned `service.version` is older than expected, verify the tag used in the deploy command and confirm the namespace matches the running deployment.
 
 ## Connect with FreeLens
 

src/pypnm/api/main.py

@@ -4,8 +4,10 @@
 from __future__ import annotations
 
 import pathlib
+import re
 import sys
 from collections.abc import Awaitable, Callable
+from time import monotonic, time
 
 from fastapi import FastAPI
 from fastapi.middleware.cors import CORSMiddleware
@@ -65,13 +67,82 @@
 )
 
 _hard_muted_routes: list[APIRoute] = []
+API_START_MONOTONIC: float = monotonic()
+API_START_EPOCH: int = int(time())
 
 
 def _route_tag_set(route: APIRoute) -> set[str]:
     tags = route.tags or []
     return {str(tag).strip().lower() for tag in tags if str(tag).strip() != ""}
 
 
+def _read_project_name() -> str:
+    """Read the project name from pyproject.toml, falling back to a stable default."""
+    pyproject_path = project_root.parent / "pyproject.toml"
+    if not pyproject_path.is_file():
+        return "pypnm-docsis"
+
+    pyproject_text = pyproject_path.read_text(encoding="utf-8")
+    project_match = re.search(r"^\[project\]\s*$", pyproject_text, re.MULTILINE)
+    if project_match is None:
+        return "pypnm-docsis"
+
+    tail_text = pyproject_text[project_match.end() :]
+    name_match = re.search(r'^\s*name\s*=\s*"([^"]+)"\s*$', tail_text, re.MULTILINE)
+    if name_match is None:
+        return "pypnm-docsis"
+
+    return name_match.group(1).strip()
+
+
+def _service_uptime_seconds() -> int:
+    """Return process uptime in whole seconds since API module initialization."""
+    elapsed_seconds = int(monotonic() - API_START_MONOTONIC)
+    return max(elapsed_seconds, 0)
+
+
+SERVICE_NAME: str = _read_project_name()
+
+
+def _data_root_path() -> pathlib.Path:
+    """Return the repository-local `.data` directory used for runtime artifacts."""
+    return pathlib.Path(".data")
+
+
+def _folder_size_bytes(folder_path: pathlib.Path) -> int:
+    """Return recursive folder size in bytes, ignoring inaccessible entries."""
+    if not folder_path.exists():
+        return 0
+
+    total_bytes = 0
+    for path in folder_path.rglob("*"):
+        total_bytes += _file_size_bytes(path)
+    return total_bytes
+
+
+def _file_size_bytes(path: pathlib.Path) -> int:
+    """Return file size in bytes, or zero for non-files and inaccessible paths."""
+    try:
+        if path.is_file():
+            return path.stat().st_size
+    except OSError:
+        return 0
+    return 0
+
+
+def _first_level_directory_sizes(folder_path: pathlib.Path) -> dict[str, int]:
+    """Return recursive sizes for each first-level directory under the given root."""
+    if not folder_path.exists():
+        return {}
+
+    sizes: dict[str, int] = {}
+    for child in folder_path.iterdir():
+        if not child.is_dir():
+            continue
+        sizes[child.name] = _folder_size_bytes(child)
+    return sizes
+
+
 def _apply_muted_tag_policy(app_instance: FastAPI) -> None:
     _hard_muted_routes.clear()
     muted_tags = read_env_csv_set(ENV_MUTE_TAGS)
@@ -90,9 +161,26 @@ def _apply_muted_tag_policy(app_instance: FastAPI) -> None:
 
 
 @app.get("/health", tags=["health"])
-def health() -> dict[str, str]:
+def health() -> dict[str, str | dict[str, int]]:
     """Lightweight health endpoint for probes."""
-    return {"status": "ok", "version": __version__}
+    uptime_seconds = _service_uptime_seconds()
+    data_root = _data_root_path()
+    return {
+        "status": "ok",
+        "service": {
+            "name": SERVICE_NAME,
+            "version": __version__,
+        },
+        "uptime": {
+            "starttime": API_START_EPOCH,
+            "uptime": uptime_seconds,
+        },
+        "data": {
+            "path": str(data_root),
+            "size_bytes": _folder_size_bytes(data_root),
+            "directories": _first_level_directory_sizes(data_root),
+        },
+    }
 
 app.add_middleware(GZipMiddleware, minimum_size=100_000)
 app.add_middleware(

tests/test_api_health.py

@@ -0,0 +1,41 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (c) 2026 Maurice Garcia
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from pypnm.api import main as api_main
+from pypnm.version import __version__
+
+
+def test_health_includes_uptime(monkeypatch) -> None:
+    monkeypatch.setattr(api_main, "API_START_MONOTONIC", 100.0)
+    monkeypatch.setattr(api_main, "API_START_EPOCH", 1_741_709_200)
+    monkeypatch.setattr(api_main, "SERVICE_NAME", "pypnm-docsis")
+    monkeypatch.setattr(api_main, "_data_root_path", lambda: Path(".data"))
+    monkeypatch.setattr(api_main, "_folder_size_bytes", lambda _: 4096)
+    monkeypatch.setattr(api_main, "_first_level_directory_sizes", lambda _: {"pnm": 1024, "json": 2048})
+    monkeypatch.setattr(api_main, "monotonic", lambda: 165.9)
+
+    response = api_main.health()
+
+    assert response == {
+        "status": "ok",
+        "service": {
+            "name": "pypnm-docsis",
+            "version": __version__,
+        },
+        "uptime": {
+            "starttime": 1_741_709_200,
+            "uptime": 65,
+        },
+        "data": {
+            "path": ".data",
+            "size_bytes": 4096,
+            "directories": {
+                "pnm": 1024,
+                "json": 2048,
+            },
+        },
+    }