From e685e6f93d838746276a9d33d0dc04a710396163 Mon Sep 17 00:00:00 2001 From: Vishal Rana Date: Sat, 17 Oct 2026 14:04:27 -0700 Subject: [PATCH] refactor(api): serve alerts and their summary under the alerting domain One feature used two path domains: fired alerts at /api/alerts and /api/alerts/summary, rules at /api/alerting/rules. Alerts and the summary now live beside the rules, so every alerting route shares one domain and no sibling resource sits where an alert ID would belong. - GET /api/alerting/alerts lists fired alerts. - GET /api/alerting/summary returns the summary view. - The old /api/alerts routes are removed, with no aliases. Responses are unchanged. Authorization classification, tests, the route reference and the alerts guide move with the routes. Claude-Session: https://claude.ai/code/session_018HfyEXHyGD1utmKF4CQtyQ --- cmd/fanout-docgen/routes.go | 2 +- internal/api/alerts.go | 4 +- internal/api/alerts_test.go | 69 +++++++++++++++++++ internal/api/auth_middleware.go | 2 +- internal/api/auth_test.go | 12 ++-- .../src/content/docs/guides/set-up-alerts.mdx | 6 +- .../content/docs/reference/http-routes.mdx | 6 +- 7 files changed, 87 insertions(+), 14 deletions(-) create mode 100644 internal/api/alerts_test.go diff --git a/cmd/fanout-docgen/routes.go b/cmd/fanout-docgen/routes.go index 8181912a7..87ab13b52 100644 --- a/cmd/fanout-docgen/routes.go +++ b/cmd/fanout-docgen/routes.go @@ -277,7 +277,7 @@ func renderRoutes(routes []api.RouteDoc) []byte { b.WriteString("The supported programmatic interface is **MCP**, at `/mcp` — see\n") b.WriteString("[MCP tools](/reference/mcp-tools). The stable non-MCP surfaces are OTLP\n") b.WriteString("ingest, and the operational endpoints in [endpoints](/reference/endpoints).\n\n") - b.WriteString("Alert rules (`/api/alerting/rules`, `/api/alerts`) currently have no browser\n") + b.WriteString("Alert rules (`/api/alerting/rules`, `/api/alerting/alerts`) currently have no browser\n") b.WriteString("page. Ingest-token rotation uses `POST /api/settings/ingest/token/rotate`\n") b.WriteString("and is also available to administrators on **Connect telemetry**.\n") b.WriteString(":::\n\n") diff --git a/internal/api/alerts.go b/internal/api/alerts.go index cdc7bb4c3..df942debe 100644 --- a/internal/api/alerts.go +++ b/internal/api/alerts.go @@ -16,8 +16,8 @@ func RegisterAlertRoutes(e *echo.Echo, store *alert.Store, engine *alert.Engine) read := RequireCapability(ReadTelemetry) manage := RequireCapability(ManageAlerts) - e.GET("/api/alerts", h.ListAlerts, read) - e.GET("/api/alerts/summary", h.AlertSummary, read) + e.GET("/api/alerting/alerts", h.ListAlerts, read) + e.GET("/api/alerting/summary", h.AlertSummary, read) e.GET("/api/alerting/rules", h.ListRules, read) e.POST("/api/alerting/rules", h.CreateRule, manage) e.PUT("/api/alerting/rules/:id", h.UpdateRule, manage) diff --git a/internal/api/alerts_test.go b/internal/api/alerts_test.go new file mode 100644 index 000000000..e613dbff8 --- /dev/null +++ b/internal/api/alerts_test.go @@ -0,0 +1,69 @@ +package api + +import ( + "net/http" + "net/http/httptest" + "strings" + "testing" + + "github.com/labstack/echo/v5" + + "github.com/labstack/fanout/internal/auth" +) + +func TestAlertingReadRoutesRequireAuthenticationAndPreserveBodies(t *testing.T) { + s := newTestAuthServer(t) + RegisterAlertRoutes(s.e, nil, nil) + viewer, err := s.users.CreateWithAudit("alert-reader@example.com", "", "viewer", auth.AuditEvent{EventType: "user.created", Outcome: "success"}) + if err != nil { + t.Fatal(err) + } + cookie := s.login(t, viewer) + for _, tc := range []struct{ path, body string }{ + {"/api/alerting/alerts", "[]"}, + {"/api/alerting/summary", `{"firing":0,"pending":0,"resolved":0}`}, + {"/api/alerting/rules", "[]"}, + } { + t.Run(tc.path, func(t *testing.T) { + anonymous := httptest.NewRecorder() + s.e.ServeHTTP(anonymous, httptest.NewRequest(http.MethodGet, tc.path, nil)) + if anonymous.Code != http.StatusUnauthorized { + t.Fatalf("anonymous read = %d, want 401: %s", anonymous.Code, anonymous.Body.String()) + } + authenticated := httptest.NewRecorder() + s.e.ServeHTTP(authenticated, sessionRequest(http.MethodGet, tc.path, nil, cookie)) + if authenticated.Code != http.StatusOK || strings.TrimSpace(authenticated.Body.String()) != tc.body { + t.Fatalf("viewer read = %d %s, want 200 %s", authenticated.Code, authenticated.Body.String(), tc.body) + } + }) + } +} + +func TestRetiredAlertRoutesReturn404WithSPACatchAll(t *testing.T) { + s := newTestAuthServer(t) + RegisterAlertRoutes(s.e, nil, nil) + s.e.GET("/*", func(c *echo.Context) error { return c.String(http.StatusOK, "SPA") }) + viewer, err := s.users.CreateWithAudit("retired-alert-reader@example.com", "", "viewer", auth.AuditEvent{EventType: "user.created", Outcome: "success"}) + if err != nil { + t.Fatal(err) + } + cookie := s.login(t, viewer) + retiredPath := "/api/" + "alerts" + for _, path := range []string{retiredPath, retiredPath + "/summary"} { + for _, session := range []struct { + name string + cookie *http.Cookie + }{ + {"anonymous", nil}, + {"authenticated", cookie}, + } { + t.Run(session.name+" "+path, func(t *testing.T) { + rec := httptest.NewRecorder() + s.e.ServeHTTP(rec, sessionRequest(http.MethodGet, path, nil, session.cookie)) + if rec.Code != http.StatusNotFound { + t.Fatalf("retired route = %d, want 404: %s", rec.Code, rec.Body.String()) + } + }) + } + } +} diff --git a/internal/api/auth_middleware.go b/internal/api/auth_middleware.go index 9b6b95882..4cdf125d1 100644 --- a/internal/api/auth_middleware.go +++ b/internal/api/auth_middleware.go @@ -294,7 +294,7 @@ func classifyRoute(method, path string) (routePolicy, bool) { return routePolicy{kind: routePolicyCapability, capability: ReadTelemetry}, read case path == "/api/intelligence": return routePolicy{kind: routePolicyCapability, capability: ReadTelemetry}, read - case path == "/api/alerts" || path == "/api/alerts/summary" || path == "/api/alerting/rules": + case path == "/api/alerting/alerts" || path == "/api/alerting/summary" || path == "/api/alerting/rules": if read { return routePolicy{kind: routePolicyCapability, capability: ReadTelemetry}, true } diff --git a/internal/api/auth_test.go b/internal/api/auth_test.go index 6403c17de..9b1810a09 100644 --- a/internal/api/auth_test.go +++ b/internal/api/auth_test.go @@ -166,7 +166,11 @@ func TestRoutePolicyClassification(t *testing.T) { {http.MethodGet, "/api/traces/abc", routePolicyCapability, ReadTelemetry}, {http.MethodHead, "/api/traces/abc", routePolicyCapability, ReadTelemetry}, {http.MethodGet, "/api/intelligence", routePolicyCapability, ReadTelemetry}, - {http.MethodGet, "/api/alerts", routePolicyCapability, ReadTelemetry}, + {http.MethodGet, "/api/alerting/alerts", routePolicyCapability, ReadTelemetry}, + {http.MethodHead, "/api/alerting/alerts", routePolicyCapability, ReadTelemetry}, + {http.MethodGet, "/api/alerting/summary", routePolicyCapability, ReadTelemetry}, + {http.MethodHead, "/api/alerting/summary", routePolicyCapability, ReadTelemetry}, + {http.MethodGet, "/api/alerting/rules", routePolicyCapability, ReadTelemetry}, {http.MethodPost, "/api/alerting/rules", routePolicyCapability, ManageAlerts}, {http.MethodPut, "/api/alerting/rules/rule-1", routePolicyCapability, ManageAlerts}, {http.MethodGet, "/api/dashboards/dashboard-1", routePolicyCapability, ManageOwnDashboards}, @@ -252,11 +256,11 @@ func TestMetricsRequiresValidScraperToken(t *testing.T) { func TestKnownRouteWrongMethodReturns405(t *testing.T) { s := newTestAuthServer(t) - s.e.GET("/api/alerts", func(c *echo.Context) error { return c.NoContent(http.StatusNoContent) }) + s.e.GET("/api/alerting/alerts", func(c *echo.Context) error { return c.NoContent(http.StatusNoContent) }) rec := httptest.NewRecorder() - s.e.ServeHTTP(rec, httptest.NewRequest(http.MethodPost, "/api/alerts", nil)) + s.e.ServeHTTP(rec, httptest.NewRequest(http.MethodPost, "/api/alerting/alerts", nil)) if rec.Code != http.StatusMethodNotAllowed { - t.Fatalf("POST /api/alerts = %d, want 405", rec.Code) + t.Fatalf("POST /api/alerting/alerts = %d, want 405", rec.Code) } } diff --git a/site/src/content/docs/guides/set-up-alerts.mdx b/site/src/content/docs/guides/set-up-alerts.mdx index d212f2e18..5020d848a 100644 --- a/site/src/content/docs/guides/set-up-alerts.mdx +++ b/site/src/content/docs/guides/set-up-alerts.mdx @@ -17,8 +17,8 @@ Rules are managed over HTTP. There is no browser page for them yet — see | Endpoint | Does | |---|---| -| `GET /api/alerts` | Current alert state | -| `GET /api/alerts/summary` | Counts by state | +| `GET /api/alerting/alerts` | Current alert state | +| `GET /api/alerting/summary` | Counts by state | | `GET /api/alerting/rules` | List rules | | `POST /api/alerting/rules` | Create and compile a rule | | `PUT /api/alerting/rules/:id` | Replace a rule; recompile it when enabled | @@ -82,7 +82,7 @@ An alert moves through three states: what stops a metric hovering at the threshold from delivering repeatedly. Each alert records its last delivery status and timestamp, so a webhook endpoint -that started rejecting is visible in `GET /api/alerts` rather than silent. +that started rejecting is visible in `GET /api/alerting/alerts` rather than silent. :::caution[The namespace field on a rule is not applied] A rule carries a `namespace` selector and it is stored, but evaluation reads diff --git a/site/src/content/docs/reference/http-routes.mdx b/site/src/content/docs/reference/http-routes.mdx index 1a9f1162e..2c68cc366 100644 --- a/site/src/content/docs/reference/http-routes.mdx +++ b/site/src/content/docs/reference/http-routes.mdx @@ -49,7 +49,7 @@ The supported programmatic interface is **MCP**, at `/mcp` — see [MCP tools](/reference/mcp-tools). The stable non-MCP surfaces are OTLP ingest, and the operational endpoints in [endpoints](/reference/endpoints). -Alert rules (`/api/alerting/rules`, `/api/alerts`) currently have no browser +Alert rules (`/api/alerting/rules`, `/api/alerting/alerts`) currently have no browser page. Ingest-token rotation uses `POST /api/settings/ingest/token/rotate` and is also available to administrators on **Connect telemetry**. ::: @@ -108,13 +108,13 @@ Capabilities map to roles in [roles](/reference/roles). | `DELETE` | `/api/agent/threads/:id` | `agent:run` | | `GET` | `/api/agent/threads/:id` | `agent:run` | | `PATCH` | `/api/agent/threads/:id` | `agent:run` | +| `GET` | `/api/alerting/alerts` | `telemetry:read` | | `GET` | `/api/alerting/rules` | `telemetry:read` | | `POST` | `/api/alerting/rules` | `alerts:manage` | | `DELETE` | `/api/alerting/rules/:id` | `alerts:manage` | | `PUT` | `/api/alerting/rules/:id` | `alerts:manage` | | `POST` | `/api/alerting/rules/:id/test` | `alerts:manage` | -| `GET` | `/api/alerts` | `telemetry:read` | -| `GET` | `/api/alerts/summary` | `telemetry:read` | +| `GET` | `/api/alerting/summary` | `telemetry:read` | | `POST` | `/api/annotations` | `telemetry:read` | | `POST` | `/api/auth/code/send` | none | | `POST` | `/api/auth/code/verify` | none |