Analytics: compare two finished runs

New page /analytics/compare and API GET /admin/analytics/compare (+ /lists/{group}):
the administrator picks an old (A) and a new (B) run; the report shows the new
addresses (only in B), the ones that left (only in A) and the common ones whose
membership in the seven indicators (pass, partial, fail, egress https any/all,
ingress ssh any/all) differs, with a "what changed" summary per address; the
dynamics of each indicator (delta = new - left + entered - exited) and a verdict
transition matrix. Every number opens a list with CSV. Cancelled addresses are not
part of a run. The list dialog moved to a shared analytics-dialog.js and template;
/analytics got a "compare with another run" button.

Docs, plan and summary in docs/changes/.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

internal/httpapi/handlers_analytics.go

@@ -72,15 +72,21 @@ func (s *Server) handleAnalyticsRuns(w http.ResponseWriter, r *http.Request) {
 	writeJSON(w, http.StatusOK, out)
 }
 
-// analysisFor returns the analysis of a finalized run, from the cache when the
-// run's data has not changed since it was computed. It writes the error
-// response itself and returns nil when it cannot.
+// analysisFor returns the analysis of the run named by the {id} of the path;
+// see analysisByID.
 func (s *Server) analysisFor(w http.ResponseWriter, r *http.Request) *analytics.Analysis {
 	id, err := strconv.ParseInt(r.PathValue("id"), 10, 64)
 	if err != nil || id <= 0 {
 		writeError(w, http.StatusBadRequest, "invalid run id")
 		return nil
 	}
+	return s.analysisByID(w, r, id)
+}
+
+// analysisByID returns the analysis of a finalized run, from the cache when
+// the run's data has not changed since it was computed. It writes the error
+// response itself and returns nil when it cannot.
+func (s *Server) analysisByID(w http.ResponseWriter, r *http.Request, id int64) *analytics.Analysis {
 	ctx := r.Context()
 	run, err := s.DB.GetRun(ctx, id)
 	if err != nil {
@@ -152,12 +158,6 @@ func (s *Server) handleAnalyticsList(w http.ResponseWriter, r *http.Request) {
 		writeJSON(w, http.StatusOK, list)
 		return
 	}
-	var buf bytes.Buffer
-	buf.WriteString("\xef\xbb\xbf") // UTF-8 BOM, so Excel opens the file as UTF-8
-	cw := csv.NewWriter(&buf)
-	cw.UseCRLF = true
-	_ = cw.Write(list.Columns)
-	_ = cw.WriteAll(list.Rows)
 	name := kind
 	if kind == analytics.ListError {
 		if slug := strings.Trim(nonSlug.ReplaceAllString(strings.ToLower(class), "-"), "-"); slug != "" {
@@ -166,12 +166,91 @@ func (s *Server) handleAnalyticsList(w http.ResponseWriter, r *http.Request) {
 			name += "-class"
 		}
 	}
+	writeCSV(w, list.Columns, list.Rows, fmt.Sprintf("%s_run%s.csv", name, r.PathValue("id")))
+}
+
+// writeCSV sends a table as a downloadable CSV file.
+func writeCSV(w http.ResponseWriter, columns []string, rows [][]string, filename string) {
+	var buf bytes.Buffer
+	buf.WriteString("\xef\xbb\xbf") // UTF-8 BOM, so Excel opens the file as UTF-8
+	cw := csv.NewWriter(&buf)
+	cw.UseCRLF = true
+	_ = cw.Write(columns)
+	_ = cw.WriteAll(rows)
 	w.Header().Set("Content-Type", "text/csv; charset=utf-8")
-	w.Header().Set("Content-Disposition", fmt.Sprintf(`attachment; filename="%s_run%s.csv"`, name, r.PathValue("id")))
+	w.Header().Set("Content-Disposition", fmt.Sprintf(`attachment; filename="%s"`, filename))
 	w.WriteHeader(http.StatusOK)
 	_, _ = w.Write(buf.Bytes())
 }
 
+// compareFor loads the two runs named by ?base=A&target=B (the older and the
+// newer one) and compares them. It writes the error response itself and
+// returns nil when it cannot: 400 for a missing or malformed id or the same
+// run twice, 404 for an unknown run, 409 for one that is still open.
+func (s *Server) compareFor(w http.ResponseWriter, r *http.Request) (c *analytics.Comparison, base, target int64) {
+	ids := [2]int64{}
+	for i, name := range []string{"base", "target"} {
+		id, err := strconv.ParseInt(r.URL.Query().Get(name), 10, 64)
+		if err != nil || id <= 0 {
+			writeError(w, http.StatusBadRequest, "invalid or missing "+name+" run id")
+			return nil, 0, 0
+		}
+		ids[i] = id
+	}
+	if ids[0] == ids[1] {
+		writeError(w, http.StatusBadRequest, "base and target must be different runs")
+		return nil, 0, 0
+	}
+	a := s.analysisByID(w, r, ids[0])
+	if a == nil {
+		return nil, 0, 0
+	}
+	b := s.analysisByID(w, r, ids[1])
+	if b == nil {
+		return nil, 0, 0
+	}
+	return analytics.Compare(a, b), ids[0], ids[1]
+}
+
+// handleAnalyticsCompare serves the comparison of two finished runs:
+// ?base=A (older) &target=B (newer).
+func (s *Server) handleAnalyticsCompare(w http.ResponseWriter, r *http.Request) {
+	if c, _, _ := s.compareFor(w, r); c != nil {
+		writeJSON(w, http.StatusOK, c)
+	}
+}
+
+// handleAnalyticsCompareList serves the address table of one group of the
+// comparison (new|left|common|changed|same|entered|exited), narrowed by
+// ?indicator=... and ?from=...&to=... (verdicts), as JSON or, with
+// ?format=csv, as a downloadable CSV file.
+func (s *Server) handleAnalyticsCompareList(w http.ResponseWriter, r *http.Request) {
+	c, base, target := s.compareFor(w, r)
+	if c == nil {
+		return
+	}
+	q := r.URL.Query()
+	group := r.PathValue("group")
+	f := analytics.CompareFilter{Indicator: q.Get("indicator"), From: q.Get("from"), To: q.Get("to")}
+	list, err := c.List(group, f)
+	if err != nil {
+		writeError(w, http.StatusNotFound, err.Error())
+		return
+	}
+	if q.Get("format") != "csv" {
+		writeJSON(w, http.StatusOK, list)
+		return
+	}
+	name := "compare_" + group
+	if f.Indicator != "" {
+		name += "_" + f.Indicator
+	}
+	if f.From != "" {
+		name += "_" + f.From + "-" + f.To
+	}
+	writeCSV(w, list.Columns, list.Rows, fmt.Sprintf("%s_run%d-%d.csv", name, base, target))
+}
+
 func (s *Server) handleConfigGetSubnets(w http.ResponseWriter, r *http.Request) {
 	list, err := s.DB.ListSubnets(r.Context())
 	if err != nil {