feat(api): add /v1/stats/nodes endpoint for traffic breakdown by server

Author: AppsGanin

docs/api.md

@@ -216,11 +216,24 @@ The join token is embedded once and expires in 24h; `/regen-join` issues a new o
 
 ```
 GET $BASE/v1/stats/series?user_id=5&from=2026-01-01&to=2026-01-31   → daily traffic points
+GET $BASE/v1/stats/nodes?user_id=5&from=2026-01-01&to=2026-01-31    → traffic split by server
 GET $BASE/v1/stats/users?from=2026-01-01&to=2026-01-31              → per-user totals
 ```
 
-`user_id` is optional on `series` (omit for a panel-wide series). `from`/`to` are
-`YYYY-MM-DD` (in the panel's configured timezone).
+`user_id` is optional on `series` and `nodes` (omit for a panel-wide figure).
+`from`/`to` are `YYYY-MM-DD` (in the panel's configured timezone).
+
+`nodes` breaks the same traffic down by the server that carried it, busiest first —
+`series` tells you how much, this tells you where. `node_id` is `0` for the panel's
+own server; names are resolved for you, including servers deleted since (their
+traffic rows outlive them).
+
+```json
+{ "data": [
+  { "node_id": 2, "name": "NL", "up": 46059475, "down": 1488367869 },
+  { "node_id": 0, "name": "Этот сервер", "up": 52711616, "down": 3901246326 }
+] }
+```
 
 ### Monitoring
 

internal/server/api_v1.go

@@ -69,9 +69,16 @@ type (
 // the two docs routes take precedence over the authenticated catch-all.
 func (rt *Router) apiHandler() http.Handler {
 	mux := http.NewServeMux()
-	mux.HandleFunc("GET /v1/openapi.json", rt.apiOpenAPI)
-	mux.HandleFunc("GET /v1/docs", rt.apiDocs)
-	mux.HandleFunc("GET /v1/healthz", rt.apiHealthz)
+	// Recorded like the authenticated routes below, so the OpenAPI coverage test sees
+	// the whole /v1 surface and not just the part behind apiAuth.
+	for pattern, h := range map[string]http.HandlerFunc{
+		"GET /v1/openapi.json": rt.apiOpenAPI,
+		"GET /v1/docs":         rt.apiDocs,
+		"GET /v1/healthz":      rt.apiHealthz,
+	} {
+		rt.apiRoutes = append(rt.apiRoutes, pattern)
+		mux.HandleFunc(pattern, h)
+	}
 	mux.Handle("/", rt.apiAuth(rt.apiMux()))
 	return mux
 }
@@ -103,8 +110,16 @@ func (rt *Router) apiHealthz(w http.ResponseWriter, _ *http.Request) {
 // caller (apiAuth), so every route here already has a valid key.
 func (rt *Router) apiMux() http.Handler {
 	mux := http.NewServeMux()
+	// Every /v1 registration goes through hf so the route table is recorded as it is
+	// built: TestAPISpecCoversEveryRoute reads it back and fails when an endpoint
+	// ships without an OpenAPI entry. GET /v1/health had drifted that way — reachable,
+	// documented in docs/api.md, absent from the generated spec.
+	hf := func(pattern string, h http.HandlerFunc) {
+		rt.apiRoutes = append(rt.apiRoutes, pattern)
+		mux.HandleFunc(pattern, h)
+	}
 	id := func(pattern string, h func(http.ResponseWriter, *http.Request, int64)) {
-		mux.HandleFunc(pattern, func(w http.ResponseWriter, r *http.Request) {
+		hf(pattern, func(w http.ResponseWriter, r *http.Request) {
 			v, err := strconv.ParseInt(r.PathValue("id"), 10, 64)
 			if err != nil {
 				writeAPIErr(w, http.StatusBadRequest, "bad_request", "invalid id")
@@ -114,11 +129,11 @@ func (rt *Router) apiMux() http.Handler {
 		})
 	}
 
-	mux.HandleFunc("GET /v1/health", rt.apiHealth)
+	hf("GET /v1/health", rt.apiHealth)
 
-	mux.HandleFunc("GET /v1/users", rt.apiListUsers)
-	mux.HandleFunc("POST /v1/users", rt.apiCreateUser)
-	mux.HandleFunc("POST /v1/users/bulk", rt.apiBulkUsers)
+	hf("GET /v1/users", rt.apiListUsers)
+	hf("POST /v1/users", rt.apiCreateUser)
+	hf("POST /v1/users/bulk", rt.apiBulkUsers)
 	id("GET /v1/users/{id}", rt.apiGetUser)
 	id("PATCH /v1/users/{id}", rt.apiPatchUser)
 	id("DELETE /v1/users/{id}", rt.apiDeleteUser)
@@ -128,21 +143,22 @@ func (rt *Router) apiMux() http.Handler {
 	id("POST /v1/users/{id}/plan", rt.apiApplyPlan)
 	id("GET /v1/users/{id}/connections", rt.apiUserConnections)
 
-	mux.HandleFunc("GET /v1/billing/providers", rt.apiListProviders)
-	mux.HandleFunc("GET /v1/billing/plans", rt.apiListPlans)
-	mux.HandleFunc("POST /v1/billing/plans", rt.apiSavePlan)
+	hf("GET /v1/billing/providers", rt.apiListProviders)
+	hf("GET /v1/billing/plans", rt.apiListPlans)
+	hf("POST /v1/billing/plans", rt.apiSavePlan)
 	id("DELETE /v1/billing/plans/{id}", rt.apiDeletePlan)
-	mux.HandleFunc("GET /v1/billing/orders", rt.apiListOrders)
-	mux.HandleFunc("POST /v1/billing/orders", rt.apiCreateOrder)
+	hf("GET /v1/billing/orders", rt.apiListOrders)
+	hf("POST /v1/billing/orders", rt.apiCreateOrder)
 	id("POST /v1/billing/orders/{id}/confirm", rt.apiConfirmOrder)
 	id("POST /v1/billing/orders/{id}/cancel", rt.apiCancelOrder)
 
-	mux.HandleFunc("GET /v1/stats/series", rt.apiStatsSeries)
-	mux.HandleFunc("GET /v1/stats/users", rt.apiStatsUsers)
+	hf("GET /v1/stats/series", rt.apiStatsSeries)
+	hf("GET /v1/stats/nodes", rt.apiStatsNodes)
+	hf("GET /v1/stats/users", rt.apiStatsUsers)
 
-	mux.HandleFunc("GET /v1/summary", rt.apiSummary)
-	mux.HandleFunc("GET /v1/system", rt.apiSystem)
-	mux.HandleFunc("GET /v1/health/report", rt.apiHealthReport)
+	hf("GET /v1/summary", rt.apiSummary)
+	hf("GET /v1/system", rt.apiSystem)
+	hf("GET /v1/health/report", rt.apiHealthReport)
 
 	// Node mutations over the external API must land in the admin audit trail too —
 	// the panel's audited-middleware wraps only the panel mux, not this one. idFn adds
@@ -158,10 +174,10 @@ func (rt *Router) apiMux() http.Handler {
 		}
 	}
 	nodeAudit := func(pattern, section string, h http.HandlerFunc) {
-		mux.HandleFunc(pattern, rt.apiAudited(section, h))
+		hf(pattern, rt.apiAudited(section, h))
 	}
 
-	mux.HandleFunc("GET /v1/nodes", rt.apiListNodes)
+	hf("GET /v1/nodes", rt.apiListNodes)
 	nodeAudit("POST /v1/nodes", "API · нода добавлена", rt.apiCreateNode)
 	id("GET /v1/nodes/{id}", rt.apiGetNode)
 	nodeAudit("PATCH /v1/nodes/{id}", "API · нода изменена", idFn(rt.apiPatchNode))
@@ -173,7 +189,7 @@ func (rt *Router) apiMux() http.Handler {
 
 	// Any unmatched /v1 path (or a wrong method) returns a JSON 404 in-envelope
 	// rather than the default plain-text one.
-	mux.HandleFunc("/", func(w http.ResponseWriter, _ *http.Request) {
+	hf("/", func(w http.ResponseWriter, _ *http.Request) {
 		writeAPIErr(w, http.StatusNotFound, "not_found", "no such endpoint")
 	})
 	return mux
@@ -312,7 +328,7 @@ func (rt *Router) apiUserView(w http.ResponseWriter, u model.User) {
 // ---- handlers ----
 
 func (rt *Router) apiHealth(w http.ResponseWriter, _ *http.Request) {
-	writeAPIData(w, http.StatusOK, map[string]any{"status": "ok"})
+	writeAPIData(w, http.StatusOK, oaHealthResp{Status: "ok"})
 }
 
 // apiListUsers lists users with optional filtering (?status, ?search) and
@@ -684,6 +700,32 @@ func (rt *Router) apiStatsSeries(w http.ResponseWriter, r *http.Request) {
 	writeAPIData(w, http.StatusOK, series)
 }
 
+// apiStatsNodes is the /v1 twin of the panel's per-server split: which server
+// carried the period's traffic. Offered here because a caller building their own
+// reporting on top of /v1/stats/series would otherwise have no way to break the same
+// numbers down by server.
+func (rt *Router) apiStatsNodes(w http.ResponseWriter, r *http.Request) {
+	q := r.URL.Query()
+	var userID int64
+	if s := q.Get("user_id"); s != "" {
+		v, err := strconv.ParseInt(s, 10, 64)
+		if err != nil || v < 0 {
+			writeAPIErr(w, http.StatusBadRequest, "bad_request", "invalid user_id")
+			return
+		}
+		userID = v
+	}
+	rows, err := rt.mgr.NodeTrafficBreakdown(userID, q.Get("from"), q.Get("to"))
+	if err != nil {
+		writeAPIManagerErr(w, err)
+		return
+	}
+	if rows == nil {
+		rows = []core.NodeTraffic{}
+	}
+	writeAPIData(w, http.StatusOK, rows)
+}
+
 func (rt *Router) apiStatsUsers(w http.ResponseWriter, r *http.Request) {
 	q := r.URL.Query()
 	totals, err := rt.mgr.StatsByUser(q.Get("from"), q.Get("to"))

internal/server/openapi.go

@@ -39,6 +39,13 @@ type oaRoute struct {
 	noAuth                     bool // key-free route; overrides the document-wide bearerAuth
 }
 
+// oaHealthResp is what GET /v1/health answers. Named rather than an inline map so
+// the generated spec reflects its real shape — the same reason request bodies are
+// named types here.
+type oaHealthResp struct {
+	Status string `json:"status"` // "ok"
+}
+
 // oaOrderResp / oaAffectedResp document the two non-model JSON responses so the
 // spec types them precisely (they mirror the maps the handlers write).
 type oaOrderResp struct {
@@ -113,13 +120,22 @@ func apiSpecRoutes() []oaRoute {
 				{name: "to", typ: "string", desc: "YYYY-MM-DD"},
 			},
 			resp: t(model.DailyPoint{}), list: true},
+		{method: "GET", path: "/v1/stats/nodes", tag: "Stats", summary: "Traffic split by server",
+			query: []oaParam{
+				{name: "user_id", typ: "integer", desc: "restrict to one user (omit for panel-wide)"},
+				{name: "from", typ: "string", desc: "YYYY-MM-DD"},
+				{name: "to", typ: "string", desc: "YYYY-MM-DD"},
+			},
+			resp: t(core.NodeTraffic{}), list: true},
 		{method: "GET", path: "/v1/stats/users", tag: "Stats", summary: "Per-user traffic totals",
 			query: []oaParam{
 				{name: "from", typ: "string", desc: "YYYY-MM-DD"},
 				{name: "to", typ: "string", desc: "YYYY-MM-DD"},
 			},
 			resp: t(model.UserTotal{}), list: true},
 
+		{method: "GET", path: "/v1/health", tag: "Monitoring", summary: "API reachability check",
+			resp: t(oaHealthResp{})},
 		{method: "GET", path: "/v1/summary", tag: "Monitoring", summary: "Panel summary",
 			resp: t(core.Summary{})},
 		{method: "GET", path: "/v1/system", tag: "Monitoring", summary: "Live system metrics",

internal/server/openapi_coverage_test.go

@@ -0,0 +1,77 @@
+package server
+
+import (
+	"strings"
+	"testing"
+)
+
+// specDocRoutes are the two endpoints deliberately absent from the spec: they ARE
+// the spec and the viewer for it, and describing them inside themselves adds
+// nothing a reader can act on.
+var specDocRoutes = map[string]bool{
+	"GET /v1/openapi.json": true,
+	"GET /v1/docs":         true,
+	// The catch-all that turns an unmatched /v1 path into a JSON 404. Not an
+	// operation, so there is nothing for the spec to describe.
+	"/": true,
+}
+
+// TestAPISpecCoversEveryRoute keeps the published contract honest.
+//
+// The spec is hand-declared in openapi.go while routes are registered in
+// api_v1.go, so nothing but this test stops the two drifting: an endpoint can ship,
+// work, and be missing from the spec with no error anywhere. That is exactly what
+// had happened to GET /v1/health — reachable, described in docs/api.md, invisible
+// to every client generated from the spec.
+func TestAPISpecCoversEveryRoute(t *testing.T) {
+	rt := &Router{}
+	rt.apiHandler() // registration is what fills rt.apiRoutes
+
+	if len(rt.apiRoutes) == 0 {
+		t.Fatal("no /v1 routes recorded — the registration helper stopped tracking them")
+	}
+
+	declared := map[string]bool{}
+	for _, r := range apiSpecRoutes() {
+		declared[r.method+" "+r.path] = true
+	}
+
+	for _, pattern := range rt.apiRoutes {
+		if specDocRoutes[pattern] {
+			continue
+		}
+		if !declared[pattern] {
+			t.Errorf("%s is served but has no OpenAPI entry — clients generated from "+
+				"the spec cannot see it; add it to apiSpecRoutes() in openapi.go", pattern)
+		}
+	}
+}
+
+// TestSpecDeclaresNothingImaginary is the other direction: a spec entry for a route
+// that does not exist sends callers at a 404.
+func TestSpecDeclaresNothingImaginary(t *testing.T) {
+	rt := &Router{}
+	rt.apiHandler()
+
+	served := map[string]bool{}
+	for _, p := range rt.apiRoutes {
+		served[p] = true
+	}
+
+	for _, r := range apiSpecRoutes() {
+		pattern := r.method + " " + r.path
+		if !served[pattern] {
+			t.Errorf("the spec declares %s, but nothing serves it", pattern)
+		}
+	}
+}
+
+// TestSpecPathsAreVersioned guards a smaller foot-gun: a path written without the
+// /v1 prefix would generate a spec clients cannot call.
+func TestSpecPathsAreVersioned(t *testing.T) {
+	for _, r := range apiSpecRoutes() {
+		if !strings.HasPrefix(r.path, "/v1/") {
+			t.Errorf("spec path %q is not under /v1/", r.path)
+		}
+	}
+}

internal/server/server.go

@@ -46,6 +46,7 @@ type Router struct {
 	streams    *streamGate    // caps concurrent SSE streams
 	status     *statusFeed    // one dashboard-payload timer shared by every viewer
 	routes     []string       // panel route patterns, in registration order (audit exhaustiveness test)
+	apiRoutes  []string       // /v1 route patterns (OpenAPI coverage test)
 
 	mu        sync.RWMutex
 	secret    string