refactor: rename Metrics gear URL /history → /metrics + themed 404 (#97)

sarg3nt · web-flow · commit 669318f644ba · 2026-05-14T18:39:26.000-07:00
* refactor: rename Metrics gear URL /history → /metrics; clarify the term The Metrics gear was historically called "history" because the page shows time-series data. That name leaked into the URL (/history), the API endpoints (/api/{boxID}/history/*), the templ file (history.templ), the handler functions (HistoryPage, APIStatsHistoryHandler, …), and assorted comments / docs / README entries. With nginx / Apache / Caddy / Traefik detection now landing (issue #95) and "metric source" / "primary source" terminology in the new code, the dual naming has become genuinely confusing. This commit renames the metrics-gear identity end-to-end: - Page route: /history → /metrics (plugin.go SidebarItem.Path, base.templ path-prefix match + sidebar links, gears-page.js). - API routes: /api/{boxID}/history/stats → /api/{boxID}/metrics/stats /api/{boxID}/history/metrics → /api/{boxID}/metrics/system /api/{boxID}/history/backend/{name} → /api/{boxID}/metrics/backend/{name} (Last one coexists with /metrics/backend/{name}/details — the time-series endpoint vs the drill-down details endpoint added in #87.) - Handler functions: HistoryPage → MetricsPage APIStatsHistoryHandler → APIMetricsStatsHandler APIBackendHistoryHandler → APIMetricsBackendHandler APISystemMetricsHistoryHandler → APIMetricsSystemHandler - File: pages/history.templ → pages/metrics.templ (templ component History() → Metrics()) - JS callers: history.templ + details.templ + chart_partials.templ (8 fetch() URLs updated). - Docs: metrics gear README routes table + architecture diagram + development snippet; cmd/server/main.go route-group comment; pages.go migration-history comment; permissions.go field comment; docs/gears.md gear list. Intentionally **kept** as legitimate "history" concepts (per design discussion): - DB tables stats_history, system_metrics_history, backend_history — the rows ARE historical records. Renaming requires a migration with no user-visible benefit; the names accurately describe what they contain. The DB query methods that read them (GetStatsHistory, GetBackendHistory, GetSystemMetricsHistory) keep their names for the same reason. - Snapshot interval / retention config: HistoryIntervalSeconds, store_history, history_retention_days — these control how the historical record is kept. Same reasoning. - Local `history` variable names inside the renamed handler functions — they reflect what the DB methods return. - OS-update apt/zypper/dnf/pacman history — distinct concept. /api/v1/system/updates/history on the agent, /os-updates/history on the dashboard, parseAptHistoryLog, /var/log/apt/history.log, etc. All untouched. - HAProxy config change history — distinct concept. /{boxID}/haproxy/config/history, templates/pages/haproxy_config/change_history.templ, etc. Untouched. Agent module: no changes. The agent's "history" references are all OS-update package-manager history (apt/zypper/dnf/pacman/apk/yum), which is the legitimate concept. Tests + build green on both modules. * feat: themed static 404 page for unmatched routes Wires chi's NotFound to a self-contained handler so a typo'd URL (or a bookmark to the now-renamed /history) lands on a small Gearbox-themed page instead of the browser's default 404. Particularly relevant after the /history → /metrics rename in this PR — anyone with a bookmark to the old URL will hit this. Security posture: the handler is deliberately static end-to-end. - No templ rendering, no auth middleware, no DB / agent lookups. - HTML is a Go const so there's no filesystem or template lookup at request time. - Inline CSS only (no <link> tags) so the response works even if the static-asset bundle didn't load. - No request data echoed into the response (test enforces this) — guards against the page becoming a reflection vector. - `Cache-Control: no-store` so a 404 doesn't outlive a deploy that later adds the missing route. Tests: - TestNotFoundHandlerStatusAndBody: 404 status, HTML body, Cache- Control, expected copy. - TestNotFoundHandlerDoesNotEchoRequestData: URL/header/cookie probes don't appear in the response body — handler is fully static. - TestNotFoundHandlerStableAcrossMethods: GET/POST/PUT/DELETE/PATCH all return the same 404 page. Visual: matches the dashboard's blue accent (#2563eb), uses system fonts (no external font loading), `prefers-color-scheme`-aware so it renders in dark mode without JS. * docs: fix grammar in metrics README (Copilot review nit)
diff --git a/docs/gears.md b/docs/gears.md
@@ -138,7 +138,7 @@ Client gears run in the **gearbox** web application (the monitoring client) and
 - `traffic` - Traffic analysis and visualization page
 - `alerts` - Alert management page
 - `services` - Service status and control page
-- `metrics` - System metrics and history page
+- `metrics` - Time-series system + HAProxy metrics page (`/metrics`)
 
 ### Gear Scope: Box vs System
 
diff --git a/gearbox/cmd/server/main.go b/gearbox/cmd/server/main.go
@@ -452,6 +452,12 @@ func main() {
 	r.Use(gbmiddleware.SecurityHeaders)
 	// Inject asset configuration for templates (CDN vs local assets)
 	r.Use(gbmiddleware.InjectAssetConfig(cfg.UseLocalAssets))
+
+	// Themed 404 for unmatched routes. The handler is intentionally
+	// static (inline HTML, no auth/DB/templ) so a typo'd URL can't be a
+	// side channel for fingerprinting session state. See the handler's
+	// own godoc for the rationale.
+	r.NotFound(handler.NotFoundHandler)
 	// Note: Timeout middleware is applied per-route group below
 	// SSE endpoints need to bypass the timeout middleware
 
@@ -627,7 +633,7 @@ func main() {
 
 		// Gear-registered routes
 		// Gears handle: / (haproxy overview), /status-grid (haproxy), /logs (logs),
-		// /services (services), /history (metrics), /certificates (certificates),
+		// /services (services), /metrics (metrics gear), /certificates (certificates),
 		// /traffic (traffic), /alerts (alerts)
 		gearManager.RegisterRoutes(r)
 
@@ -676,10 +682,13 @@ func main() {
 			r.Get("/{boxID}/charts/error-rates", h.APIChartsErrorRatesHandler)
 			r.Get("/{boxID}/logs/{logName}", h.APILogsHandler)
 			r.Get("/{boxID}/log-sources", h.APILogSourcesHandler) // Get enabled log sources
-			// History API endpoints
-			r.Get("/{boxID}/history/stats", h.APIStatsHistoryHandler)
-			r.Get("/{boxID}/history/metrics", h.APISystemMetricsHistoryHandler)
-			r.Get("/{boxID}/history/backend/{backendName}", h.APIBackendHistoryHandler)
+			// Metrics gear — time-series endpoints (HAProxy stats,
+			// system metrics, per-backend stats). These power the
+			// charts on the /metrics page; the /metrics/* "v2"
+			// endpoints just below power the KPI band + insights.
+			r.Get("/{boxID}/metrics/stats", h.APIMetricsStatsHandler)
+			r.Get("/{boxID}/metrics/system", h.APIMetricsSystemHandler)
+			r.Get("/{boxID}/metrics/backend/{backendName}", h.APIMetricsBackendHandler)
 			r.Get("/{boxID}/incidents", h.APIIncidentsHandler)
 
 			// Metrics gear v2 — insights & drill-down endpoints
diff --git a/gearbox/internal/framework/handler/api_stats.go b/gearbox/internal/framework/handler/api_stats.go
@@ -102,8 +102,12 @@ func (h *Handler) APISystemMetricsHandler(w http.ResponseWriter, r *http.Request
 	h.writeJSON(w, response)
 }
 
-// APIStatsHistoryHandler returns historical stats data.
-func (h *Handler) APIStatsHistoryHandler(w http.ResponseWriter, r *http.Request) {
+// APIMetricsStatsHandler returns time-series HAProxy stats for the
+// Metrics page's per-backend chart. Served at /api/{boxID}/metrics/stats.
+// The underlying DB method is still named GetStatsHistory because the
+// data it returns IS historical records; the URL renamed for clarity
+// with issue #97.
+func (h *Handler) APIMetricsStatsHandler(w http.ResponseWriter, r *http.Request) {
 	boxID := chi.URLParam(r, "boxID")
 	if boxID == "" {
 		http.Error(w, "Server ID required", http.StatusBadRequest)
@@ -142,8 +146,12 @@ func (h *Handler) APIStatsHistoryHandler(w http.ResponseWriter, r *http.Request)
 	})
 }
 
-// APIBackendHistoryHandler returns historical data for a specific backend.
-func (h *Handler) APIBackendHistoryHandler(w http.ResponseWriter, r *http.Request) {
+// APIMetricsBackendHandler returns time-series stats for a specific
+// backend on the Metrics page. Served at
+// /api/{boxID}/metrics/backend/{backendName}. Coexists with the
+// /metrics/backend/{name}/details drill-down (which returns aggregate
+// insights rather than the time-series).
+func (h *Handler) APIMetricsBackendHandler(w http.ResponseWriter, r *http.Request) {
 	// Check if user has permission to view metrics
 	if !h.authManager.HasPermission(r, models.ComponentMetrics, models.PermissionView) {
 		http.Error(w, "Forbidden: insufficient permissions to view metrics", http.StatusForbidden)
@@ -191,8 +199,10 @@ func (h *Handler) APIBackendHistoryHandler(w http.ResponseWriter, r *http.Reques
 	})
 }
 
-// APISystemMetricsHistoryHandler returns historical system metrics.
-func (h *Handler) APISystemMetricsHistoryHandler(w http.ResponseWriter, r *http.Request) {
+// APIMetricsSystemHandler returns time-series host-level metrics for
+// the Metrics page (CPU, memory, disk, network). Served at
+// /api/{boxID}/metrics/system.
+func (h *Handler) APIMetricsSystemHandler(w http.ResponseWriter, r *http.Request) {
 	// Check if user has permission to view metrics
 	if !h.authManager.HasPermission(r, models.ComponentMetrics, models.PermissionView) {
 		http.Error(w, "Forbidden: insufficient permissions to view metrics", http.StatusForbidden)
diff --git a/gearbox/internal/framework/handler/not_found.go b/gearbox/internal/framework/handler/not_found.go
@@ -0,0 +1,110 @@
+package handler
+
+import "net/http"
+
+// NotFoundHandler serves a static, self-contained 404 page for any URL
+// that doesn't match a registered route. Wired in main.go via
+// chi's r.NotFound().
+//
+// Deliberately bypasses every dashboard concern beyond the HTTP
+// envelope: no templ rendering, no auth middleware, no DB / agent
+// lookups, no user-context injection. A page-not-found response for a
+// randomly-typed URL must not be a side channel for fingerprinting
+// session state or for accidentally exposing data that a logged-out
+// caller shouldn't see. The HTML is a const so there's no filesystem
+// or template lookup at request time either.
+//
+// Visually the page matches the dashboard's palette (blue accent,
+// system fonts, prefers-color-scheme-aware) and includes a single
+// link back to "/". All styles are inline so the response works even
+// if the static-asset bundle didn't load.
+func NotFoundHandler(w http.ResponseWriter, r *http.Request) {
+	w.Header().Set("Content-Type", "text/html; charset=utf-8")
+	// 404s shouldn't be cached — the next deploy might add the route.
+	w.Header().Set("Cache-Control", "no-store")
+	w.WriteHeader(http.StatusNotFound)
+	_, _ = w.Write([]byte(notFoundHTML))
+}
+
+// notFoundHTML is the entire 404 response body. Kept as a const so the
+// handler has no runtime template or filesystem dependency — security
+// posture comment on NotFoundHandler explains why this matters.
+const notFoundHTML = `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<title>404 — Page not found · Gearbox</title>
+<meta name="viewport" content="width=device-width,initial-scale=1">
+<meta name="robots" content="noindex">
+<style>
+:root { color-scheme: light dark; }
+* { box-sizing: border-box; }
+html, body { height: 100%; margin: 0; }
+body {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  font-family: ui-sans-serif, system-ui, -apple-system, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
+  background: #f8fafc;
+  color: #0f172a;
+  padding: 1.5rem;
+}
+@media (prefers-color-scheme: dark) {
+  body { background: #0f172a; color: #e2e8f0; }
+  .footer { color: #64748b; }
+}
+.card {
+  text-align: center;
+  max-width: 32rem;
+  padding: 2rem;
+}
+h1 {
+  font-size: 5rem;
+  font-weight: 700;
+  margin: 0 0 0.25rem;
+  letter-spacing: -0.025em;
+  color: #2563eb;
+  line-height: 1;
+}
+.lead {
+  font-size: 1.25rem;
+  font-weight: 600;
+  margin: 0 0 1rem;
+}
+p {
+  margin: 0.5rem 0;
+  line-height: 1.6;
+  opacity: 0.85;
+}
+a.home {
+  display: inline-block;
+  margin-top: 1.5rem;
+  padding: 0.625rem 1.25rem;
+  background: #2563eb;
+  color: #ffffff;
+  text-decoration: none;
+  border-radius: 0.5rem;
+  font-weight: 500;
+  font-size: 0.9375rem;
+  transition: background-color 120ms ease;
+}
+a.home:hover, a.home:focus { background: #1d4ed8; }
+.footer {
+  margin-top: 2rem;
+  font-size: 0.75rem;
+  color: #94a3b8;
+  letter-spacing: 0.04em;
+  text-transform: uppercase;
+}
+</style>
+</head>
+<body>
+  <main class="card">
+    <h1>404</h1>
+    <p class="lead">Page not found</p>
+    <p>The URL you requested isn't registered on this dashboard.</p>
+    <a class="home" href="/">Back to dashboard</a>
+    <p class="footer">Gearbox</p>
+  </main>
+</body>
+</html>`
diff --git a/gearbox/internal/framework/handler/not_found_test.go b/gearbox/internal/framework/handler/not_found_test.go
@@ -0,0 +1,65 @@
+package handler
+
+import (
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+)
+
+func TestNotFoundHandlerStatusAndBody(t *testing.T) {
+	req := httptest.NewRequest(http.MethodGet, "/anything-not-registered", nil)
+	w := httptest.NewRecorder()
+
+	NotFoundHandler(w, req)
+
+	if w.Code != http.StatusNotFound {
+		t.Errorf("status = %d, want 404", w.Code)
+	}
+	ct := w.Header().Get("Content-Type")
+	if !strings.HasPrefix(ct, "text/html") {
+		t.Errorf("Content-Type = %q, want HTML", ct)
+	}
+	if cc := w.Header().Get("Cache-Control"); cc != "no-store" {
+		t.Errorf("Cache-Control = %q, want no-store", cc)
+	}
+	body := w.Body.String()
+	for _, want := range []string{"<!doctype html>", "404", "Page not found", "Back to dashboard"} {
+		if !strings.Contains(body, want) {
+			t.Errorf("body should contain %q", want)
+		}
+	}
+}
+
+// TestNotFoundHandlerDoesNotEchoRequestData guards against accidentally
+// turning the 404 page into a reflection vector. The handler should
+// never embed any part of the request URL, headers, cookies, or body
+// into the response — the point of the static page is that a typo'd
+// URL produces a fully deterministic response.
+func TestNotFoundHandlerDoesNotEchoRequestData(t *testing.T) {
+	const probe = "GEARBOX-PROBE-MARKER-39df09a1"
+	req := httptest.NewRequest(http.MethodGet, "/"+probe, nil)
+	req.Header.Set("X-Probe", probe)
+	req.Header.Set("Cookie", "session="+probe)
+	req.Header.Set("Referer", "https://example.com/"+probe)
+	w := httptest.NewRecorder()
+
+	NotFoundHandler(w, req)
+
+	if strings.Contains(w.Body.String(), probe) {
+		t.Errorf("response body contains request-supplied marker %q — handler is reflecting request data", probe)
+	}
+}
+
+func TestNotFoundHandlerStableAcrossMethods(t *testing.T) {
+	for _, method := range []string{http.MethodGet, http.MethodPost, http.MethodPut, http.MethodDelete, http.MethodPatch} {
+		t.Run(method, func(t *testing.T) {
+			req := httptest.NewRequest(method, "/missing", nil)
+			w := httptest.NewRecorder()
+			NotFoundHandler(w, req)
+			if w.Code != http.StatusNotFound {
+				t.Errorf("%s: status = %d, want 404", method, w.Code)
+			}
+		})
+	}
+}
diff --git a/gearbox/internal/framework/handler/pages.go b/gearbox/internal/framework/handler/pages.go
@@ -15,7 +15,7 @@ import (
 // - OverviewPage -> plugins/haproxy
 // - StatusGridPage -> plugins/haproxy
 // - LogsPage -> plugins/logs
-// - HistoryPage -> plugins/metrics
+// - MetricsPage -> plugins/metrics
 // - ServicesPage -> plugins/services
 // - CertificatesPage -> plugins/certificates
 // - TrafficPage -> plugins/traffic
diff --git a/gearbox/internal/framework/models/permissions.go b/gearbox/internal/framework/models/permissions.go
@@ -335,7 +335,7 @@ func GetAvailablePermissionsForComponent(c Component) []Permission {
 		}
 	case ComponentMetrics:
 		return []Permission{
-			PermissionView,      // View metrics/history page and data
+			PermissionView,      // View the Metrics page and its data
 			PermissionConfigure, // Configure metrics storage settings
 		}
 	case ComponentGears:
diff --git a/gearbox/internal/framework/templates/layouts/base.templ b/gearbox/internal/framework/templates/layouts/base.templ
@@ -36,7 +36,7 @@ func gearLabelForPath(path string) string {
 		return ""
 	case path == "/haproxy" || strings.HasPrefix(path, "/haproxy/"):
 		return "HAProxy"
-	case path == "/history" || strings.HasPrefix(path, "/history/"):
+	case path == "/metrics" || strings.HasPrefix(path, "/metrics/"):
 		return "Metrics"
 	case path == "/logs" || strings.HasPrefix(path, "/logs/"):
 		return "Logs"
@@ -2175,7 +2175,7 @@ func integrationPath(name string) string {
 	case "haproxy":
 		return "/haproxy"
 	case "metrics":
-		return "/history"
+		return "/metrics"
 	case "logs":
 		return "/logs"
 	case "services":
@@ -2287,7 +2287,7 @@ templ OrderedIntegrationLinks(currentPath string) {
 			@SidebarLinkWithIntegration("/haproxy", "HAProxy", SidebarIconHAProxy(), currentPath, "haproxy")
 		}
 		if canViewIntegration(ctx, "metrics") {
-			@SidebarLinkWithIntegration("/history", "Metrics", SidebarIconMetrics(), currentPath, "metrics")
+			@SidebarLinkWithIntegration("/metrics", "Metrics", SidebarIconMetrics(), currentPath, "metrics")
 		}
 		if canViewIntegration(ctx, "logs") {
 			@SidebarLinkWithIntegration("/logs", "Logs", SidebarIconLogs(), currentPath, "logs")
@@ -2332,7 +2332,7 @@ templ renderIntegrationLink(name string, currentPath string) {
 		case "haproxy":
 			@SidebarLinkDraggable("/haproxy", "HAProxy", SidebarIconHAProxy(), currentPath, "haproxy")
 		case "metrics":
-			@SidebarLinkDraggable("/history", "Metrics", SidebarIconMetrics(), currentPath, "metrics")
+			@SidebarLinkDraggable("/metrics", "Metrics", SidebarIconMetrics(), currentPath, "metrics")
 		case "logs":
 			@SidebarLinkDraggable("/logs", "Logs", SidebarIconLogs(), currentPath, "logs")
 		case "services":
diff --git a/gearbox/internal/framework/templates/pages/details.templ b/gearbox/internal/framework/templates/pages/details.templ
@@ -714,7 +714,7 @@ templ BackendDetail(user *models.User, backendName string, stats *models.HAProxy
 					function loadBackendHistory() {
 						updateResolutionLabel();
 						var hours = document.getElementById('hours-select').value;
-						fetch('/api/' + backendServerID + '/history/backend/' + encodeURIComponent(backendNameVar) + '?hours=' + hours)
+						fetch('/api/' + backendServerID + '/metrics/backend/' + encodeURIComponent(backendNameVar) + '?hours=' + hours)
 							.then(function(response) { return response.json(); })
 							.then(function(result) {
 								cachedBackendData = result.data || [];
diff --git a/gearbox/internal/framework/templates/pages/metrics.templ b/gearbox/internal/framework/templates/pages/metrics.templ
@@ -4,8 +4,8 @@ import "github.com/sarg3nt/gearbox/internal/framework/models"
 import "github.com/sarg3nt/gearbox/internal/framework/templates/layouts"
 import "github.com/sarg3nt/gearbox/internal/framework/templates/components"
 
-templ History(user *models.User, servers []models.BoxConfig) {
-	@layouts.Base("Metrics", user, "/history") {
+templ Metrics(user *models.User, servers []models.BoxConfig) {
+	@layouts.Base("Metrics", user, "/metrics") {
 		<!-- Hidden container for page header content. Title + box selector
 		     live in the global header breadcrumb + chip. -->
 		<div id="page-header-source" class="hidden">
@@ -843,12 +843,12 @@ templ History(user *models.User, servers []models.BoxConfig) {
 			await applyCapabilities(serverID);
 
 			try {
-				// Fetch stats history
-				const statsResponse = await fetch(`/api/${serverID}/history/stats?hours=${hours}`);
+				// Fetch HAProxy stats time series
+				const statsResponse = await fetch(`/api/${serverID}/metrics/stats?hours=${hours}`);
 				const statsData = await statsResponse.json();
 
-				// Fetch system metrics history
-				const metricsResponse = await fetch(`/api/${serverID}/history/metrics?hours=${hours}`);
+				// Fetch system-metrics time series
+				const metricsResponse = await fetch(`/api/${serverID}/metrics/system?hours=${hours}`);
 				const metricsData = await metricsResponse.json();
 
 				// Cache the data for fullscreen toggle
diff --git a/gearbox/internal/gears/metrics/README.md b/gearbox/internal/gears/metrics/README.md
diff --git a/gearbox/internal/gears/metrics/chart_partials.templ b/gearbox/internal/gears/metrics/chart_partials.templ
diff --git a/gearbox/internal/gears/metrics/handlers.go b/gearbox/internal/gears/metrics/handlers.go
diff --git a/gearbox/internal/gears/metrics/plugin.go b/gearbox/internal/gears/metrics/plugin.go
diff --git a/gearbox/static/js/gears/gears-page.js b/gearbox/static/js/gears/gears-page.js

Original file line number	Diff line number	Diff line change
`@@ -335,7 +335,7 @@ func GetAvailablePermissionsForComponent(c Component) []Permission {`
`335`	`335`	`}`
`336`	`336`	`case ComponentMetrics:`
`337`	`337`	`return []Permission{`
`338`		`- PermissionView, // View metrics/history page and data`
	`338`	`+ PermissionView, // View the Metrics page and its data`
`339`	`339`	`PermissionConfigure, // Configure metrics storage settings`
`340`	`340`	`}`
`341`	`341`	`case ComponentGears:`