Add Floating IP scanning and a durable address registry with configurable history depth

Adds POST /api/v1/admin/ips/scan (plus an optional periodic ticker) to discover free Floating IPs in the OpenStack project and feed them straight into the check queue. More importantly, decouples check/event history from ip_queue's lifecycle: a new ip_registry table (migration 0007) gives every address ever submitted a durable identity, so deleting it from the queue no longer destroys its history — it's still reachable via the new GET /api/v1/admin/registry[/{ip}] endpoints and the dashboard's /registry pages, with retention depth configurable in check cycles per address (history_retention_cycles, 0 = unlimited). Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-09-23 09:52:01 +03:00
1 parent 78b20fa5be
commit 582b44f314
@@ -32,6 +32,27 @@ type clearQueueResponse struct {
 	Deleted []string `json:"deleted"`
 }

+type scanIPsResponse struct {
+	ScannedFree       int      `json:"scanned_free"`
+	Added             []string `json:"added"`
+	Requeued          []string `json:"requeued"`
+	Reordered         []string `json:"reordered"`
+	SkippedInProgress []string `json:"skipped_in_progress"`
+}
+
+// registryDTO is one row of the durable per-address registry — see
+// db.RegistrySummary.
+type registryDTO struct {
+	IPAddress     string     `json:"ip_address"`
+	FirstSeenAt   time.Time  `json:"first_seen_at"`
+	LastSeenAt    time.Time  `json:"last_seen_at"`
+	TotalCycles   int        `json:"total_cycles"`
+	LastResult    string     `json:"last_result"`
+	LastCheckedAt *time.Time `json:"last_checked_at"`
+	InQueue       bool       `json:"in_queue"`
+	CurrentState  string     `json:"current_state"`
+}
+
 type validatorDTO struct {
 	ValidatorID     string     `json:"validator_id"`
 	Hostname        string     `json:"hostname"`
@@ -85,7 +106,8 @@ type putCheckTypeRequest struct {
 // request body for /api/v1/admin/config/orchestrator — a single-field DTO,
 // same shape both ways, like putSiteRequest/siteDTO.
 type orchestratorSettingsDTO struct {
-	FIPSettleSeconds int `json:"fip_settle_seconds"`
+	FIPSettleSeconds       int `json:"fip_settle_seconds"`
+	HistoryRetentionCycles int `json:"history_retention_cycles"`
 }

 // inboundChecksDTO doubles as both the GET response and the PUT request
@@ -99,6 +99,26 @@ func (s *Server) handleAdminSubmitIPs(w http.ResponseWriter, r *http.Request) {
 	})
 }

+// handleAdminScanFloatingIPs lists every floating IP in the configured
+// OpenStack project, filters to the free (unassociated) pool, and submits
+// that address list to the check queue — see orchestrator.ScanFloatingIPs.
+// Takes no body; POST is used (rather than GET) because it mutates the
+// queue, matching handleAdminSubmitIPs.
+func (s *Server) handleAdminScanFloatingIPs(w http.ResponseWriter, r *http.Request) {
+	result, scannedFree, err := s.Orch.ScanFloatingIPs(r.Context())
+	if err != nil {
+		writeError(w, http.StatusBadGateway, err.Error())
+		return
+	}
+	writeJSON(w, http.StatusOK, scanIPsResponse{
+		ScannedFree:       scannedFree,
+		Added:             emptyIfNil(result.Added),
+		Requeued:          emptyIfNil(result.Requeued),
+		Reordered:         emptyIfNil(result.Reordered),
+		SkippedInProgress: emptyIfNil(result.SkippedInProgress),
+	})
+}
+
 // handleAdminCancelIP force-stops a check in progress (or still-queued) for
 // the given address. Requires the orchestrator, since a floating IP may
 // need to be disassociated in OpenStack.
@@ -200,7 +200,10 @@ func (s *Server) handleConfigGetOrchestratorSettings(w http.ResponseWriter, r *h
 		writeDBError(w, err)
 		return
 	}
-	writeJSON(w, http.StatusOK, orchestratorSettingsDTO{FIPSettleSeconds: settings.FIPSettleSeconds})
+	writeJSON(w, http.StatusOK, orchestratorSettingsDTO{
+		FIPSettleSeconds:       settings.FIPSettleSeconds,
+		HistoryRetentionCycles: settings.HistoryRetentionCycles,
+	})
 }

 // handleConfigPutOrchestratorSettings goes through the orchestrator (not a
@@ -217,7 +220,14 @@ func (s *Server) handleConfigPutOrchestratorSettings(w http.ResponseWriter, r *h
 		writeDBError(w, err)
 		return
 	}
-	writeJSON(w, http.StatusOK, orchestratorSettingsDTO{FIPSettleSeconds: req.FIPSettleSeconds})
+	if err := s.DB.SetHistoryRetentionCycles(r.Context(), req.HistoryRetentionCycles); err != nil {
+		writeDBError(w, err)
+		return
+	}
+	writeJSON(w, http.StatusOK, orchestratorSettingsDTO{
+		FIPSettleSeconds:       req.FIPSettleSeconds,
+		HistoryRetentionCycles: req.HistoryRetentionCycles,
+	})
 }

 // --- prober inbound checks ---
@@ -0,0 +1,59 @@
+package httpapi
+
+import (
+	"net/http"
+
+	"cloudipvalidator/internal/db"
+)
+
+// handleAdminRegistry lists every address ever submitted to the check
+// queue, each with a summary of its accumulated check history — the
+// durable record that survives an address being deleted from ip_queue and
+// later re-added. See migrations/0007_ip_registry.sql.
+func (s *Server) handleAdminRegistry(w http.ResponseWriter, r *http.Request) {
+	items, err := s.DB.ListRegistry(r.Context())
+	if err != nil {
+		writeError(w, http.StatusInternalServerError, err.Error())
+		return
+	}
+	out := make([]registryDTO, len(items))
+	for i, it := range items {
+		out[i] = registrySummaryToDTO(it)
+	}
+	writeJSON(w, http.StatusOK, out)
+}
+
+// handleAdminRegistryHistory returns one address's registry record plus its
+// full retained check history (across every cycle still kept — see
+// db.PruneRegistryHistory / settings.history_retention_cycles), newest
+// cycle first.
+func (s *Server) handleAdminRegistryHistory(w http.ResponseWriter, r *http.Request) {
+	address := r.PathValue("ip")
+	summary, err := s.DB.GetRegistryByAddress(r.Context(), address)
+	if err != nil {
+		writeDBError(w, err)
+		return
+	}
+	checks, err := s.DB.ListChecksForRegistry(r.Context(), summary.ID, nil)
+	if err != nil {
+		writeError(w, http.StatusInternalServerError, err.Error())
+		return
+	}
+	writeJSON(w, http.StatusOK, struct {
+		Registry registryDTO `json:"registry"`
+		Checks   []db.Check  `json:"checks"`
+	}{registrySummaryToDTO(*summary), checks})
+}
+
+func registrySummaryToDTO(s db.RegistrySummary) registryDTO {
+	return registryDTO{
+		IPAddress:     s.IPAddress,
+		FirstSeenAt:   s.FirstSeenAt,
+		LastSeenAt:    s.LastSeenAt,
+		TotalCycles:   s.TotalCycles,
+		LastResult:    s.LastResult,
+		LastCheckedAt: s.LastCheckedAt,
+		InQueue:       s.InQueue,
+		CurrentState:  s.CurrentState,
+	}
+}
@@ -0,0 +1,150 @@
+package httpapi
+
+import (
+	"context"
+	"encoding/json"
+	"net/http"
+	"testing"
+	"time"
+
+	"cloudipvalidator/internal/db"
+)
+
+// TestScanFloatingIPsEndpoint proves POST /api/v1/admin/ips/scan only
+// queues floating IPs that are currently unassociated in OpenStack.
+func TestScanFloatingIPsEndpoint(t *testing.T) {
+	fc, _, _, mock := newConfigTestHarness(t)
+	mock.Seed("fip-free", "5.5.5.5", "svc-project")
+	mock.SeedWithPort("fip-occupied", "6.6.6.6", "svc-project", "some-port")
+
+	resp, body := fc.do(http.MethodPost, "/api/v1/admin/ips/scan", nil)
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("scan: status=%d body=%s", resp.StatusCode, body)
+	}
+	var scanResp scanIPsResponse
+	if err := json.Unmarshal(body, &scanResp); err != nil {
+		t.Fatalf("unmarshal scan response: %v", err)
+	}
+	if scanResp.ScannedFree != 1 {
+		t.Fatalf("expected 1 free fip scanned, got %+v", scanResp)
+	}
+	if len(scanResp.Added) != 1 || scanResp.Added[0] != "5.5.5.5" {
+		t.Fatalf("expected only 5.5.5.5 added, got %+v", scanResp)
+	}
+
+	_, body = fc.do(http.MethodGet, "/api/v1/admin/ips", nil)
+	var ips []db.IPQueueItem
+	if err := json.Unmarshal(body, &ips); err != nil {
+		t.Fatalf("unmarshal ips: %v", err)
+	}
+	if len(ips) != 1 || ips[0].IPAddress != "5.5.5.5" {
+		t.Fatalf("expected only the free address queued, got %+v", ips)
+	}
+}
+
+// TestRegistryHistoryOutlivesIPDeletion proves that after an address
+// completes a full check cycle and is then deleted from the queue, its
+// history is still reachable via the registry endpoints (though the plain
+// /ips/{ip} endpoint now 404s), and that resubmitting the same address adds
+// a second, distinct cycle to the same registry entry.
+func TestRegistryHistoryOutlivesIPDeletion(t *testing.T) {
+	fc, d, orch, mock := newConfigTestHarness(t)
+	ctx := context.Background()
+	mock.Seed("fip-1", "9.9.9.9", "svc-project")
+
+	fc.do(http.MethodPost, "/api/v1/admin/config/validators", createValidatorRequest{ValidatorID: "validator-1", OSPortID: "port-1"})
+	fc.do(http.MethodPut, "/api/v1/admin/config/targets/web", putTargetGroupRequest{Targets: []string{"https://example.test"}})
+	fc.do(http.MethodPut, "/api/v1/admin/config/check-types/https", putCheckTypeRequest{Enabled: true, Targets: []string{"web"}})
+	fc.do(http.MethodPost, "/api/v1/agents/register", registerAgentRequest{ValidatorID: "validator-1"})
+
+	runOneCycle := func() {
+		orch.Tick(ctx)
+		_, body := fc.do(http.MethodGet, "/api/v1/agents/validator-1/assignment", nil)
+		var assignment assignmentResponse
+		if err := json.Unmarshal(body, &assignment); err != nil {
+			t.Fatalf("unmarshal assignment: %v", err)
+		}
+		fc.do(http.MethodPost, "/api/v1/agents/validator-1/self-check", selfCheckRequest{
+			IPID: assignment.IPID, DetectedEgress: "9.9.9.9", Success: true,
+		})
+		fc.do(http.MethodPost, "/api/v1/agents/validator-1/results", agentResultsRequest{
+			Results: []checkResultDTO{{
+				IPID: assignment.IPID, CheckType: "https", Target: "https://example.test",
+				Success: true, CheckedAt: time.Now().Format(time.RFC3339Nano),
+			}},
+		})
+		fc.do(http.MethodPost, "/api/v1/agents/validator-1/complete", agentCompleteRequest{IPID: assignment.IPID})
+		orch.Tick(ctx)
+	}
+
+	fc.do(http.MethodPost, "/api/v1/admin/ips", submitIPsRequest{Addresses: []string{"9.9.9.9"}})
+	runOneCycle()
+
+	item, err := d.GetIPByAddress(ctx, "9.9.9.9")
+	if err != nil {
+		t.Fatalf("get ip: %v", err)
+	}
+	if item.State != db.IPDone {
+		t.Fatalf("expected done after first cycle, got %s", item.State)
+	}
+
+	resp, _ := fc.do(http.MethodDelete, "/api/v1/admin/ips/9.9.9.9", nil)
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("delete ip: status=%d", resp.StatusCode)
+	}
+
+	resp, _ = fc.do(http.MethodGet, "/api/v1/admin/ips/9.9.9.9", nil)
+	if resp.StatusCode != http.StatusNotFound {
+		t.Fatalf("expected 404 for deleted address on /ips, got %d", resp.StatusCode)
+	}
+
+	resp, body := fc.do(http.MethodGet, "/api/v1/admin/registry/9.9.9.9", nil)
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("registry history: status=%d body=%s", resp.StatusCode, body)
+	}
+	var hist struct {
+		Registry registryDTO `json:"registry"`
+		Checks   []db.Check  `json:"checks"`
+	}
+	if err := json.Unmarshal(body, &hist); err != nil {
+		t.Fatalf("unmarshal registry history: %v", err)
+	}
+	if hist.Registry.TotalCycles != 1 {
+		t.Fatalf("expected 1 retained cycle, got %+v", hist.Registry)
+	}
+	if len(hist.Checks) == 0 {
+		t.Fatalf("expected retained check history, got none")
+	}
+	if hist.Registry.InQueue {
+		t.Fatalf("expected registry entry to report not-in-queue after delete, got %+v", hist.Registry)
+	}
+
+	// Resubmitting starts a second, distinct cycle on the same registry
+	// entry rather than colliding with the first.
+	mock.Seed("fip-1", "9.9.9.9", "svc-project")
+	fc.do(http.MethodPost, "/api/v1/admin/ips", submitIPsRequest{Addresses: []string{"9.9.9.9"}})
+	runOneCycle()
+
+	resp, body = fc.do(http.MethodGet, "/api/v1/admin/registry/9.9.9.9", nil)
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("registry history (2nd): status=%d body=%s", resp.StatusCode, body)
+	}
+	if err := json.Unmarshal(body, &hist); err != nil {
+		t.Fatalf("unmarshal registry history (2nd): %v", err)
+	}
+	if hist.Registry.TotalCycles != 2 {
+		t.Fatalf("expected 2 retained cycles after resubmission, got %+v", hist.Registry)
+	}
+	if !hist.Registry.InQueue {
+		t.Fatalf("expected registry entry to report in-queue again, got %+v", hist.Registry)
+	}
+
+	_, body = fc.do(http.MethodGet, "/api/v1/admin/registry", nil)
+	var all []registryDTO
+	if err := json.Unmarshal(body, &all); err != nil {
+		t.Fatalf("unmarshal registry list: %v", err)
+	}
+	if len(all) != 1 || all[0].IPAddress != "9.9.9.9" {
+		t.Fatalf("expected a single registry entry for the address, got %+v", all)
+	}
+}
@@ -21,6 +21,7 @@ func (s *Server) routes(mux *http.ServeMux) {
 	mux.HandleFunc("GET /api/v1/admin/status", s.handleAdminStatus)
 	mux.HandleFunc("GET /api/v1/admin/ips", s.handleAdminIPs)
 	mux.HandleFunc("POST /api/v1/admin/ips", s.handleAdminSubmitIPs)
+	mux.HandleFunc("POST /api/v1/admin/ips/scan", s.handleAdminScanFloatingIPs)
 	mux.HandleFunc("GET /api/v1/admin/ips/{ip}", s.handleAdminIPDetail)
 	mux.HandleFunc("POST /api/v1/admin/ips/{ip}/cancel", s.handleAdminCancelIP)
 	mux.HandleFunc("DELETE /api/v1/admin/ips/{ip}", s.handleAdminDeleteIP)
@@ -28,6 +29,9 @@ func (s *Server) routes(mux *http.ServeMux) {
 	mux.HandleFunc("POST /api/v1/admin/ips/clear", s.handleAdminClearQueue)
 	mux.HandleFunc("GET /api/v1/admin/validators", s.handleAdminValidators)

+	mux.HandleFunc("GET /api/v1/admin/registry", s.handleAdminRegistry)
+	mux.HandleFunc("GET /api/v1/admin/registry/{ip}", s.handleAdminRegistryHistory)
+
 	mux.HandleFunc("GET /api/v1/admin/config/validators", s.handleConfigListValidators)
 	mux.HandleFunc("POST /api/v1/admin/config/validators", s.handleConfigCreateValidator)
 	mux.HandleFunc("PUT /api/v1/admin/config/validators/{id}", s.handleConfigUpdateValidator)