feat(stats): add bounded path and hash-width analytics (#159)

internal/api/handlers/paths.go

@@ -0,0 +1,68 @@
+// Copyright 2026 Beacon Contributors
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
+package handlers
+
+import (
+	"context"
+	"errors"
+	"log/slog"
+	"net/http"
+	"time"
+
+	"github.com/MeshCore-Beacon/beacon-server/internal/api"
+)
+
+// getPathStats godoc
+//
+// @Summary Received path-entry and hash-width distributions
+// @Description Counts stored receptions in [since, until), at most 30 days. Hash widths count only validated nonempty ordinary header paths (1/2/3 bytes). Empty paths do not vote for a width. TRACE header paths contain signal readings and are separate. Missing payload type or inconsistent/unsupported path metadata is unclassified. The four categories partition total receptions. Flood paths accumulate entries; direct paths contain remaining entries, so counts do not measure distance or a complete traversed route. Both boundaries round down to UTC hours and the response reports that effective window. Reads use materialized snapshots refreshed by background.view_refresh; the current partial hour is excluded and missing hours are omitted.
+// @Tags Stats
+// @Produce json
+// @Param since query int true "Inclusive start, epoch milliseconds (0 through 253402300799999)"
+// @Param until query int true "Exclusive end, epoch milliseconds; at most 30 days after since"
+// @Param iatas query string false "Comma-separated reception IATA codes"
+// @Param regionId query int false "Region ID, expands to member IATAs"
+// @Param region query string false "Region slug, expands to member IATAs"
+// @Success 200 {object} api.PathStats
+// @Failure 400 {object} handlers.APIError
+// @Failure 500 {object} handlers.APIError
+// @Failure 503 {object} handlers.APIError
+// @Router /stats/paths [get]
+func getPathStats(reader api.Reader) http.HandlerFunc {
+	return func(w http.ResponseWriter, r *http.Request) {
+		q := r.URL.Query()
+		since, until, err := parseStatsWindow(r)
+		if err != nil {
+			respondError(w, http.StatusBadRequest, err.Error())
+			return
+		}
+		ctx, cancel := context.WithTimeout(r.Context(), 15*time.Second)
+		defer cancel()
+		iatas := parseIATAs(r)
+		if q.Get("regionId") != "" || q.Get("region") != "" {
+			regionIATAs, err := resolveRegionIATAs(ctx, q.Get("regionId"), q.Get("region"), reader)
+			if err != nil {
+				respondError(w, http.StatusBadRequest, "region not found")
+				return
+			}
+			iatas = append(iatas, regionIATAs...)
+			if len(iatas) == 0 {
+				iatas = []string{""}
+			}
+		}
+		stats, err := reader.GetPathStats(ctx, since, until, iatas)
+		switch {
+		case errors.Is(err, context.DeadlineExceeded) || errors.Is(ctx.Err(), context.DeadlineExceeded):
+			respondError(w, http.StatusServiceUnavailable, "path query timed out; try a shorter time period")
+		case err != nil:
+			if r.Context().Err() != nil {
+				return
+			}
+			slog.Error("path stats failed", "error", err)
+			respondError(w, http.StatusInternalServerError, "internal server error")
+		default:
+			respond(w, http.StatusOK, stats)
+		}
+	}
+}

internal/api/handlers/paths_test.go

@@ -0,0 +1,93 @@
+// Copyright 2026 Beacon Contributors
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
+package handlers
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"net/http/httptest"
+	"reflect"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/MeshCore-Beacon/beacon-server/internal/api"
+)
+
+type pathReader struct {
+	stubReader
+	read func(context.Context, time.Time, time.Time, []string) (*api.PathStats, error)
+}
+
+func (s pathReader) GetPathStats(ctx context.Context, since, until time.Time, iatas []string) (*api.PathStats, error) {
+	return s.read(ctx, since, until, iatas)
+}
+
+func TestPathsRejectInvalidWindow(t *testing.T) {
+	for _, query := range []string{"", "since=0", "since=x&until=1", "since=-1&until=1", "since=1&until=1", "since=2&until=1", "since=0&until=2592000001", "since=0&since=0&until=1", "since=0&until=1&until=2", "since=253402300799998&until=253402300800000"} {
+		w := httptest.NewRecorder()
+		StatsRouter(nil).ServeHTTP(w, httptest.NewRequest("GET", "/paths?"+query, nil))
+		if w.Code != 400 {
+			t.Fatalf("query %q: %d %s", query, w.Code, w.Body.String())
+		}
+	}
+}
+
+func TestPathsFiltersErrorsAndCancellation(t *testing.T) {
+	for _, tc := range []struct {
+		name, query string
+		iatas       []string
+		err         error
+		status      int
+	}{
+		{"global", "", nil, nil, 200}, {"IATAs", "&iatas=yvr,yyj", []string{"YVR", "YYJ"}, nil, 200},
+		{"region", "&region=west", []string{"YVR"}, nil, 200}, {"empty region", "&region=empty", []string{""}, nil, 200},
+		{"missing region", "&region=missing", nil, nil, 400}, {"timeout", "", nil, context.DeadlineExceeded, 503},
+		{"database error", "", nil, errors.New("private detail"), 500},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			reader := pathReader{stubReader: stubReader{getRegionBySlug: func(_ context.Context, slug string) (*api.Region, error) {
+				if slug == "empty" {
+					return &api.Region{}, nil
+				}
+				if slug == "missing" {
+					return nil, errors.New("not found")
+				}
+				return &api.Region{IATAs: []string{"YVR"}}, nil
+			}}, read: func(ctx context.Context, since, until time.Time, iatas []string) (*api.PathStats, error) {
+				if d, ok := ctx.Deadline(); !ok || time.Until(d) > 15*time.Second {
+					t.Fatal("query has no bounded deadline")
+				}
+				if since.UnixMilli() != 0 || until.UnixMilli() != 2592000000 || !reflect.DeepEqual(iatas, tc.iatas) {
+					t.Fatalf("unexpected arguments: %v %v %v", since, until, iatas)
+				}
+				return &api.PathStats{Until: until.UnixMilli(), Receptions: 4, Hashed: 1, Empty: 1, Trace: 1, Unclassified: 1}, tc.err
+			}}
+			w := httptest.NewRecorder()
+			StatsRouter(reader).ServeHTTP(w, httptest.NewRequest("GET", "/paths?since=0&until=2592000000"+tc.query, nil))
+			if w.Code != tc.status || strings.Contains(w.Body.String(), "private detail") {
+				t.Fatalf("%d %s", w.Code, w.Body.String())
+			}
+			if tc.status == 200 {
+				var got api.PathStats
+				if err := json.Unmarshal(w.Body.Bytes(), &got); err != nil || got.Receptions != 4 || got.Trace != 1 {
+					t.Fatalf("response: %+v %v", got, err)
+				}
+			}
+		})
+	}
+	ctx, cancel := context.WithCancel(context.Background())
+	cancel()
+	called := false
+	r := pathReader{read: func(ctx context.Context, _ time.Time, _ time.Time, _ []string) (*api.PathStats, error) {
+		called = true
+		return nil, ctx.Err()
+	}}
+	w := httptest.NewRecorder()
+	StatsRouter(r).ServeHTTP(w, httptest.NewRequest("GET", "/paths?since=0&until=1", nil).WithContext(ctx))
+	if !called || w.Body.Len() != 0 {
+		t.Fatal("cancellation did not reach reader")
+	}
+}

internal/api/handlers/stats.go

@@ -31,6 +31,7 @@ func StatsRouter(reader api.Reader) http.Handler {
 	r.Get("/overview", getStatsOverview(reader))
 	r.Get("/observations", getStatsObservations(reader))
 	r.Get("/signal", getSignalStats(reader))
+	r.Get("/paths", getPathStats(reader))
 	r.Get("/observer-comparison", getObserverComparison(reader))
 	r.Get("/payload-breakdown", getStatsPayloadBreakdown(reader))
 	r.Get("/top-nodes", getStatsTopNodes(reader))

internal/api/handlers/stub_reader_test.go

@@ -70,6 +70,10 @@ func (s stubReader) GetSignalStats(context.Context, time.Time, time.Time, []stri
 	return nil, nil
 }
 
+func (s stubReader) GetPathStats(context.Context, time.Time, time.Time, []string) (*api.PathStats, error) {
+	return nil, nil
+}
+
 func (s stubReader) GetObserverComparison(ctx context.Context, a, b uuid.UUID, since, until time.Time, iatas []string) (*api.ObserverComparison, error) {
 	if s.getObserverComparison != nil {
 		return s.getObserverComparison(ctx, a, b, since, until, iatas)

internal/api/paths.go

@@ -0,0 +1,46 @@
+// Copyright 2026 Beacon Contributors
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
+package api
+
+// PathStats counts stored receptions in [Since, Until), not unique packets or nodes.
+// Hashed + Empty + Trace + Unclassified partitions Receptions. Empty paths never
+// vote for a hash width. TRACE header paths contain signal readings, not hashes.
+// Since and Until are the effective UTC-hour boundaries of the materialized snapshot.
+type PathStats struct {
+	Since        int64           `json:"since"`
+	Until        int64           `json:"until"`
+	Receptions   int64           `json:"receptions"`
+	Hashed       int64           `json:"hashed"`
+	Empty        int64           `json:"empty"`
+	Trace        int64           `json:"trace"`
+	Unclassified int64           `json:"unclassified"`
+	HashWidths   []PathHashWidth `json:"hashWidths"`
+	PathLengths  []PathLengthBin `json:"pathLengths"`
+	Hourly       []PathHour      `json:"hourly"`
+}
+
+type PathHashWidth struct {
+	Bytes      int32 `json:"bytes"`
+	Receptions int64 `json:"receptions"`
+}
+
+// PathLengthBin counts entries in validated ordinary header paths, including empty.
+// Flood paths accumulate entries; direct paths contain remaining route entries.
+// These counts cannot establish distance or a complete end-to-end hop count.
+type PathLengthBin struct {
+	Entries    int32 `json:"entries"`
+	Receptions int64 `json:"receptions"`
+}
+
+// PathHour is a UTC hour clipped to the requested window. Missing hours are omitted.
+type PathHour struct {
+	Hour         int64 `json:"hour"`
+	Receptions   int64 `json:"receptions"`
+	OneByte      int64 `json:"oneByte"`
+	TwoByte      int64 `json:"twoByte"`
+	ThreeByte    int64 `json:"threeByte"`
+	Empty        int64 `json:"empty"`
+	Trace        int64 `json:"trace"`
+	Unclassified int64 `json:"unclassified"`
+}

internal/api/reader.go

@@ -164,6 +164,9 @@ type Reader interface {
 	// GetSignalStats aggregates retained reception readings in [since, until).
 	GetSignalStats(ctx context.Context, since, until time.Time, iatas []string) (*SignalStats, error)
 
+	// GetPathStats counts received path entries and validated ordinary hash widths.
+	GetPathStats(ctx context.Context, since, until time.Time, iatas []string) (*PathStats, error)
+
 	// GetStatsPayloadBreakdown returns observation counts grouped by payload type.
 	// Pass nil for iatas to return stats across all IATAs.
 	// since defines the start of the window; pass zero time for default (last 24h).