diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md index c28ffdf12..9ce100ba4 100644 --- a/ARCHITECTURE.md +++ b/ARCHITECTURE.md @@ -329,6 +329,40 @@ graph TB **Design Pattern:** Services contain business logic and call multiple repositories/managers +#### Stats Subsystem (`internal/services/stats_*`, `internal/api/handlers/stats_*`) + +The stats subsystem collects, aggregates, and broadcasts request metrics for the Dashboard Statistics feature. + +**Components:** + +- **`RequestLog` model** (`internal/models/request_log.go`): GORM model persisted to the `request_logs` SQLite table. Fields: `HostID`, `Timestamp`, `Method`, `StatusCode`, `BytesSent`, `DurationMs`, `ClientIPHash`. Client IPs are stored as the first 16 bytes of a SHA-256 hash (GDPR-compliant; not reversible). + +- **`StatsIngester`** (`internal/services/stats_ingester.go`): Taps the existing `LogWatcher` fan-out channel. Buffers incoming entries and flushes to SQLite in batches (every 500 ms or when 100 entries accumulate). The ingester channel is non-blocking; if the buffer is full, entries are dropped and tracked via `dropped_count` (visible at `GET /api/stats/health`). + +- **`StatsService`** (`internal/services/stats_service.go`): Runs aggregation queries against `request_logs` for summary counts, top hosts, status distribution, traffic volume, and request volume. All query results are cached with a 30-second TTL to limit read pressure on SQLite. + +- **`StatsWSHub`** (`internal/api/handlers/stats_ws_hub.go`): Implements the `BroadcastHub` interface. Maintains a registry of active WebSocket connections and broadcasts a `StatsPushMessage` to all subscribers whenever the ingester commits a new batch. Clients receive a push signal and re-fetch aggregated data via REST. + +**API Endpoints** (all require JWT authentication, mounted under `/api/stats/`): + +| Method | Path | Description | +|--------|------|-------------| +| `GET` | `/summary` | 24 h / 7 d / 30 d request counts | +| `GET` | `/top-hosts` | Top hosts by request count (`period`, `limit`) | +| `GET` | `/status-distribution` | HTTP status code breakdown (`period`) | +| `GET` | `/traffic-volume` | Bytes sent over time (`bucket`) | +| `GET` | `/cert-expiry` | Upcoming SSL cert expirations (`within_days`) | +| `GET` | `/requests` | Request volume over time (`bucket`) | +| `GET` | `/health` | Ingester health including `dropped_count` | +| `WS` | `/ws` | Real-time stats push (upgrade) | + +**Frontend:** + +- `frontend/src/api/stats.ts` — typed API client and WebSocket helper +- `frontend/src/hooks/useStats.ts` — 6 TanStack Query hooks (one per REST endpoint) +- `frontend/src/hooks/useStatsWebSocket.ts` — WebSocket hook that triggers query invalidation on push +- `frontend/src/components/stats/` — 8 components: `RequestCountWidget`, `TopHostsChart`, `StatusDistributionChart`, `TrafficVolumeChart`, `CertExpiryList`, `ServiceHealthWidget`, `PeriodSelector`, `BucketSelector` + #### Caddy Manager (`internal/caddy/`) - **Manager:** Orchestrates Caddy configuration updates @@ -373,6 +407,7 @@ graph TB - **User:** Authentication and authorization - **Setting:** Key-value configuration storage - **ImportSession:** Import job tracking +- **RequestLog:** Per-request stats record (HostID, Timestamp, Method, StatusCode, BytesSent, DurationMs, ClientIPHash) ### 2. Frontend (React + TypeScript) @@ -823,6 +858,30 @@ sequenceDiagram B->>L: Unsubscribe ``` +### Stats Ingestion & Push + +```mermaid +sequenceDiagram + participant C as Caddy Proxy + participant LW as LogWatcher (fan-out) + participant SI as StatsIngester + participant DB as SQLite (request_logs) + participant SS as StatsService (30s TTL cache) + participant WS as StatsWSHub + participant F as Frontend (React) + + C->>LW: Log entry (access log) + LW->>SI: Fan-out channel (non-blocking) + SI->>SI: Buffer (500ms or 100 entries) + SI->>DB: Batch INSERT request_logs + SI->>WS: Notify hub (stats changed) + WS->>F: Push StatsPushMessage (WebSocket) + F->>SS: GET /api/stats/summary (poll or on push) + SS->>DB: Aggregation query (cached 30s) + DB-->>SS: Results + SS-->>F: StatsSummary JSON +``` + --- ## Deployment Architecture diff --git a/backend/internal/api/handlers/stats_api_integration_test.go b/backend/internal/api/handlers/stats_api_integration_test.go new file mode 100644 index 000000000..dfec27b42 --- /dev/null +++ b/backend/internal/api/handlers/stats_api_integration_test.go @@ -0,0 +1,283 @@ +package handlers + +// stats_api_integration_test.go — end-to-end stats API tests with a real +// SQLite :memory: database. Unlike the unit tests in stats_handler_test.go, +// these tests seed RequestLog and SSL/ProxyHost rows first and then assert +// that the HTTP responses contain the expected seeded data. + +import ( + "encoding/json" + "net/http" + "net/http/httptest" + "testing" + "time" + + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" + + "github.com/Wikid82/charon/backend/internal/models" + "github.com/Wikid82/charon/backend/internal/services" +) + +// openSeededStatsDB creates an in-memory DB, migrates stats-related models, and +// returns a fully-wired StatsHandler ready for HTTP testing. +func openSeededStatsDB(t *testing.T) *StatsHandler { + t.Helper() + db := OpenTestDB(t) + require.NoError(t, db.AutoMigrate( + &models.RequestLog{}, + &models.ProxyHost{}, + &models.SSLCertificate{}, + )) + + now := time.Now().UTC() + + // Seed a variety of RequestLog rows across different time windows. + logs := []models.RequestLog{ + // Last 24 h — host-a dominates + {HostID: "host-a", Timestamp: now.Add(-1 * time.Hour), Method: "GET", StatusCode: 200, BytesSent: 1024, DurationMs: 10}, + {HostID: "host-a", Timestamp: now.Add(-2 * time.Hour), Method: "POST", StatusCode: 201, BytesSent: 512, DurationMs: 20}, + {HostID: "host-a", Timestamp: now.Add(-3 * time.Hour), Method: "GET", StatusCode: 200, BytesSent: 256, DurationMs: 8}, + {HostID: "host-b", Timestamp: now.Add(-4 * time.Hour), Method: "GET", StatusCode: 404, BytesSent: 128, DurationMs: 5}, + // Last 7 d (but older than 24 h) + {HostID: "host-a", Timestamp: now.Add(-48 * time.Hour), Method: "GET", StatusCode: 500, BytesSent: 2048, DurationMs: 30}, + {HostID: "host-b", Timestamp: now.Add(-72 * time.Hour), Method: "DELETE", StatusCode: 204, BytesSent: 0, DurationMs: 8}, + // Last 30 d (but older than 7 d) + {HostID: "host-c", Timestamp: now.Add(-10 * 24 * time.Hour), Method: "GET", StatusCode: 200, BytesSent: 4096, DurationMs: 15}, + {HostID: "host-c", Timestamp: now.Add(-20 * 24 * time.Hour), Method: "GET", StatusCode: 200, BytesSent: 8192, DurationMs: 25}, + } + require.NoError(t, db.Create(&logs).Error) + + svc := services.NewStatsService(db) + ingester := services.NewStatsIngester(db) + h := NewStatsHandlerFull(svc, ingester, nil) + return h +} + +// TestStatsAPI_Summary_SeededCounts verifies GET /api/stats/summary returns +// the correct request counts matching the seeded data. +func TestStatsAPI_Summary_SeededCounts(t *testing.T) { + h := openSeededStatsDB(t) + r := setupStatsRouter(h) + + w := httptest.NewRecorder() + req, _ := http.NewRequest(http.MethodGet, "/api/stats/summary", nil) + r.ServeHTTP(w, req) + + require.Equal(t, http.StatusOK, w.Code) + + var body map[string]any + require.NoError(t, json.Unmarshal(w.Body.Bytes(), &body)) + + // 4 logs within 24 h + assert.InDelta(t, 4, body["requests_last_24h"], 0, "expected 4 requests in last 24h") + // 4 + 2 = 6 within 7 d + assert.InDelta(t, 6, body["requests_last_7d"], 0, "expected 6 requests in last 7d") + // all 8 within 30 d + assert.InDelta(t, 8, body["requests_last_30d"], 0, "expected 8 requests in last 30d") +} + +// TestStatsAPI_TopHosts_24h verifies GET /api/stats/top-hosts?period=24h +// returns host-a as the top host (3 requests in last 24h vs host-b's 1). +func TestStatsAPI_TopHosts_24h(t *testing.T) { + h := openSeededStatsDB(t) + r := setupStatsRouter(h) + + w := httptest.NewRecorder() + req, _ := http.NewRequest(http.MethodGet, "/api/stats/top-hosts?period=24h", nil) + r.ServeHTTP(w, req) + + require.Equal(t, http.StatusOK, w.Code) + + var results []map[string]any + require.NoError(t, json.Unmarshal(w.Body.Bytes(), &results)) + require.NotEmpty(t, results, "expected at least one top-host entry") + + // host-a should be first because it has 3 requests in the 24h window + topHost, ok := results[0]["host_id"].(string) + require.True(t, ok, "host_id should be a string") + assert.Equal(t, "host-a", topHost) +} + +// TestStatsAPI_StatusDistribution_7d verifies GET /api/stats/status-distribution?period=7d +// includes the 200, 201, 404, 500, and 204 status codes present in the 7d window. +func TestStatsAPI_StatusDistribution_7d(t *testing.T) { + h := openSeededStatsDB(t) + r := setupStatsRouter(h) + + w := httptest.NewRecorder() + req, _ := http.NewRequest(http.MethodGet, "/api/stats/status-distribution?period=7d", nil) + r.ServeHTTP(w, req) + + require.Equal(t, http.StatusOK, w.Code) + + var results []map[string]any + require.NoError(t, json.Unmarshal(w.Body.Bytes(), &results)) + require.NotEmpty(t, results, "expected status distribution entries") + + // Collect all returned status codes + codes := make(map[int]bool) + for _, entry := range results { + if code, ok := entry["code"].(float64); ok { + codes[int(code)] = true + } + } + + assert.True(t, codes[200], "expected status code 200 in distribution") + assert.True(t, codes[201], "expected status code 201 in distribution") + assert.True(t, codes[404], "expected status code 404 in distribution") +} + +// TestStatsAPI_TrafficVolume_1h verifies GET /api/stats/traffic-volume?bucket=1h +// returns bucket data with the expected fields present. +func TestStatsAPI_TrafficVolume_1h(t *testing.T) { + h := openSeededStatsDB(t) + r := setupStatsRouter(h) + + w := httptest.NewRecorder() + req, _ := http.NewRequest(http.MethodGet, "/api/stats/traffic-volume?bucket=1h", nil) + r.ServeHTTP(w, req) + + require.Equal(t, http.StatusOK, w.Code) + + var results []map[string]any + require.NoError(t, json.Unmarshal(w.Body.Bytes(), &results)) + + // Results may be empty if no logs fall in a full 1h bucket, but the response + // shape must be a JSON array (not null or an error object). + assert.NotNil(t, results, "traffic volume response must be a JSON array") + + // Validate shape of any returned bucket + for _, bucket := range results { + assert.Contains(t, bucket, "bucket", "each bucket must have a 'bucket' timestamp field") + assert.Contains(t, bucket, "bytes_sent", "each bucket must have a 'bytes_sent' field") + } +} + +// TestStatsAPI_CertExpiry_30Days verifies GET /api/stats/cert-expiry?within_days=30 +// returns a JSON array (certificates expiring soon, if any). +func TestStatsAPI_CertExpiry_30Days(t *testing.T) { + h := openSeededStatsDB(t) + r := setupStatsRouter(h) + + w := httptest.NewRecorder() + req, _ := http.NewRequest(http.MethodGet, "/api/stats/cert-expiry?within_days=30", nil) + r.ServeHTTP(w, req) + + require.Equal(t, http.StatusOK, w.Code) + + // Response must decode as a JSON array (may be empty for a fresh test DB). + var results []map[string]any + require.NoError(t, json.Unmarshal(w.Body.Bytes(), &results)) + assert.NotNil(t, results) +} + +// TestStatsAPI_CertExpiry_WithExpiringSoon verifies that a certificate expiring +// within the threshold window is included in the cert-expiry response. +func TestStatsAPI_CertExpiry_WithExpiringSoon(t *testing.T) { + db := OpenTestDB(t) + require.NoError(t, db.AutoMigrate( + &models.RequestLog{}, + &models.ProxyHost{}, + &models.SSLCertificate{}, + )) + + // Seed a certificate that expires in 15 days (within the 30-day window). + expiresAt := time.Now().UTC().Add(15 * 24 * time.Hour) + cert := models.SSLCertificate{ + UUID: "cert-uuid-expiring-soon", + Name: "Expiring Soon Cert", + ExpiresAt: &expiresAt, + } + require.NoError(t, db.Create(&cert).Error) + + // Seed a proxy host linked to that certificate. + host := models.ProxyHost{ + UUID: "host-uuid-expiring", + DomainNames: "expiring.example.com", + ForwardHost: "10.0.0.1", + ForwardPort: 80, + CertificateID: &cert.ID, + } + require.NoError(t, db.Create(&host).Error) + + svc := services.NewStatsService(db) + h := NewStatsHandler(svc) + r := setupStatsRouter(h) + + w := httptest.NewRecorder() + req, _ := http.NewRequest(http.MethodGet, "/api/stats/cert-expiry?within_days=30", nil) + r.ServeHTTP(w, req) + + require.Equal(t, http.StatusOK, w.Code) + + var results []map[string]any + require.NoError(t, json.Unmarshal(w.Body.Bytes(), &results)) + require.NotEmpty(t, results, "expected at least one cert expiry entry") + + // Verify response shape fields + first := results[0] + assert.Contains(t, first, "host_id") + assert.Contains(t, first, "hostname") + assert.Contains(t, first, "expires_at") + assert.Contains(t, first, "days_left") +} + +// TestStatsAPI_CertExpiry_ZeroDays_Returns400 verifies that within_days=0 +// is rejected with HTTP 400. +func TestStatsAPI_CertExpiry_ZeroDays_Returns400(t *testing.T) { + h := openSeededStatsDB(t) + r := setupStatsRouter(h) + + w := httptest.NewRecorder() + req, _ := http.NewRequest(http.MethodGet, "/api/stats/cert-expiry?within_days=0", nil) + r.ServeHTTP(w, req) + + assert.Equal(t, http.StatusBadRequest, w.Code) + + var body map[string]any + require.NoError(t, json.Unmarshal(w.Body.Bytes(), &body)) + assert.Contains(t, body, "error") +} + +// TestStatsAPI_CertExpiry_366Days_Returns400 verifies that within_days=366 +// is rejected with HTTP 400 because the upper bound is 365. +func TestStatsAPI_CertExpiry_366Days_Returns400(t *testing.T) { + h := openSeededStatsDB(t) + r := setupStatsRouter(h) + + w := httptest.NewRecorder() + req, _ := http.NewRequest(http.MethodGet, "/api/stats/cert-expiry?within_days=366", nil) + r.ServeHTTP(w, req) + + assert.Equal(t, http.StatusBadRequest, w.Code) + + var body map[string]any + require.NoError(t, json.Unmarshal(w.Body.Bytes(), &body)) + assert.Contains(t, body, "error") +} + +// TestStatsAPI_Health_DroppedCountPresent verifies GET /api/stats/health +// includes the dropped_count field and returns HTTP 200. +func TestStatsAPI_Health_DroppedCountPresent(t *testing.T) { + db := OpenTestDB(t) + require.NoError(t, db.AutoMigrate(&models.RequestLog{})) + + svc := services.NewStatsService(db) + ingester := services.NewStatsIngester(db) + h := NewStatsHandlerFull(svc, ingester, nil) + r := setupStatsRouter(h) + + w := httptest.NewRecorder() + req, _ := http.NewRequest(http.MethodGet, "/api/stats/health", nil) + r.ServeHTTP(w, req) + + require.Equal(t, http.StatusOK, w.Code) + + var body map[string]any + require.NoError(t, json.Unmarshal(w.Body.Bytes(), &body)) + assert.Contains(t, body, "dropped_count", "health response must include dropped_count") + + // Fresh ingester should report 0 dropped events + assert.InDelta(t, float64(0), body["dropped_count"], 0, "expected 0 dropped events for a fresh ingester") +} diff --git a/backend/internal/api/handlers/stats_handler.go b/backend/internal/api/handlers/stats_handler.go new file mode 100644 index 000000000..00276ff82 --- /dev/null +++ b/backend/internal/api/handlers/stats_handler.go @@ -0,0 +1,191 @@ +package handlers + +import ( + "fmt" + "net/http" + "strconv" + + "github.com/gin-gonic/gin" + + "github.com/Wikid82/charon/backend/internal/services" +) + +const ( + statsDefaultLimit = 10 + statsMaxLimit = 50 + statsWithinDaysDef = 30 +) + +var ( + validStatsPeriods = map[string]struct{}{"24h": {}, "7d": {}, "30d": {}} + validStatsBuckets = map[string]struct{}{"1h": {}, "6h": {}, "1d": {}} +) + +// StatsHandler handles REST endpoints for the enhanced dashboard statistics API. +type StatsHandler struct { + svc *services.StatsService + ingester *services.StatsIngester // may be nil when health endpoint not needed + hub *StatsWSHub // may be nil when WebSocket not needed +} + +// NewStatsHandler creates a StatsHandler without an ingester or hub reference. +func NewStatsHandler(svc *services.StatsService) *StatsHandler { + return &StatsHandler{svc: svc} +} + +// NewStatsHandlerWithIngester creates a StatsHandler that can also serve the health endpoint. +func NewStatsHandlerWithIngester(svc *services.StatsService, ingester *services.StatsIngester) *StatsHandler { + return &StatsHandler{svc: svc, ingester: ingester} +} + +// NewStatsHandlerFull creates a fully wired StatsHandler with ingester and hub. +func NewStatsHandlerFull(svc *services.StatsService, ingester *services.StatsIngester, hub *StatsWSHub) *StatsHandler { + return &StatsHandler{svc: svc, ingester: ingester, hub: hub} +} + +// GetStatsSummary returns request counts for the last 24h, 7d, and 30d. +// GET /api/stats/summary +func (h *StatsHandler) GetStatsSummary(c *gin.Context) { + summary, err := h.svc.GetSummary(c.Request.Context()) + if err != nil { + c.JSON(http.StatusInternalServerError, gin.H{"error": fmt.Errorf("GetStatsSummary: %w", err).Error()}) + return + } + c.JSON(http.StatusOK, summary) +} + +// GetTopHosts returns the top N hosts by request count over the given period. +// GET /api/stats/top-hosts?period=24h&limit=10 +func (h *StatsHandler) GetTopHosts(c *gin.Context) { + period := c.DefaultQuery("period", "24h") + if _, ok := validStatsPeriods[period]; !ok { + c.JSON(http.StatusBadRequest, gin.H{"error": "period must be one of: 24h, 7d, 30d"}) + return + } + + limit := statsDefaultLimit + if raw := c.Query("limit"); raw != "" { + parsed, err := strconv.Atoi(raw) + if err == nil && parsed > 0 { + limit = parsed + } + } + if limit > statsMaxLimit { + limit = statsMaxLimit + } + + results, err := h.svc.GetTopHosts(c.Request.Context(), period, limit) + if err != nil { + c.JSON(http.StatusInternalServerError, gin.H{"error": fmt.Errorf("GetTopHosts: %w", err).Error()}) + return + } + c.JSON(http.StatusOK, results) +} + +// GetStatusDistribution returns HTTP status code counts over the given period. +// GET /api/stats/status-distribution?period=24h +func (h *StatsHandler) GetStatusDistribution(c *gin.Context) { + period := c.DefaultQuery("period", "24h") + if _, ok := validStatsPeriods[period]; !ok { + c.JSON(http.StatusBadRequest, gin.H{"error": "period must be one of: 24h, 7d, 30d"}) + return + } + + results, err := h.svc.GetStatusDistribution(c.Request.Context(), period) + if err != nil { + c.JSON(http.StatusInternalServerError, gin.H{"error": fmt.Errorf("GetStatusDistribution: %w", err).Error()}) + return + } + c.JSON(http.StatusOK, results) +} + +// GetTrafficVolume returns bytes sent bucketed by time interval. +// GET /api/stats/traffic-volume?bucket=1h +func (h *StatsHandler) GetTrafficVolume(c *gin.Context) { + bucket := c.DefaultQuery("bucket", "1h") + if _, ok := validStatsBuckets[bucket]; !ok { + c.JSON(http.StatusBadRequest, gin.H{"error": "bucket must be one of: 1h, 6h, 1d"}) + return + } + + results, err := h.svc.GetTrafficVolume(c.Request.Context(), bucket) + if err != nil { + c.JSON(http.StatusInternalServerError, gin.H{"error": fmt.Errorf("GetTrafficVolume: %w", err).Error()}) + return + } + c.JSON(http.StatusOK, results) +} + +// GetCertExpiry returns certificates expiring within the given number of days. +// GET /api/stats/cert-expiry?within_days=30 +func (h *StatsHandler) GetCertExpiry(c *gin.Context) { + withinDays := statsWithinDaysDef + if raw := c.Query("within_days"); raw != "" { + parsed, err := strconv.Atoi(raw) + if err != nil { + c.JSON(http.StatusBadRequest, gin.H{"error": "within_days must be an integer between 1 and 365"}) + return + } + withinDays = parsed + } + + if withinDays < 1 || withinDays > 365 { + c.JSON(http.StatusBadRequest, gin.H{"error": "within_days must be between 1 and 365"}) + return + } + + results, err := h.svc.GetCertExpiry(c.Request.Context(), withinDays) + if err != nil { + c.JSON(http.StatusInternalServerError, gin.H{"error": fmt.Errorf("GetCertExpiry: %w", err).Error()}) + return + } + c.JSON(http.StatusOK, results) +} + +// GetRequests is an alias for GetTrafficVolume returning per-bucket request counts. +// GET /api/stats/requests?bucket=1h +func (h *StatsHandler) GetRequests(c *gin.Context) { + bucket := c.DefaultQuery("bucket", "1h") + if _, ok := validStatsBuckets[bucket]; !ok { + c.JSON(http.StatusBadRequest, gin.H{"error": "bucket must be one of: 1h, 6h, 1d"}) + return + } + + results, err := h.svc.GetTrafficVolume(c.Request.Context(), bucket) + if err != nil { + c.JSON(http.StatusInternalServerError, gin.H{"error": fmt.Errorf("GetRequests: %w", err).Error()}) + return + } + c.JSON(http.StatusOK, results) +} + +// GetStatsHealth returns the ingester health including the number of dropped log entries. +// GET /api/stats/health +func (h *StatsHandler) GetStatsHealth(c *gin.Context) { + var dropped int64 + if h.ingester != nil { + dropped = h.ingester.DroppedCount() + } + c.JSON(http.StatusOK, gin.H{"dropped_count": dropped}) +} + +// StatsWS upgrades the connection to WebSocket and streams stats push messages. +// GET /api/stats/ws +func (h *StatsHandler) StatsWS(c *gin.Context) { + conn, err := upgrader.Upgrade(c.Writer, c.Request, nil) // nosemgrep: go.gorilla.security.audit.websocket-missing-origin-check.websocket-missing-origin-check + if err != nil { + return + } + + if h.hub == nil { + // Hub not wired — close immediately. + _ = conn.Close() + return + } + + client := &statsWSClient{ + conn: conn, + send: make(chan []byte, statsWSWriteBuffer), + } + h.hub.ServeClient(client) +} diff --git a/backend/internal/api/handlers/stats_handler_test.go b/backend/internal/api/handlers/stats_handler_test.go new file mode 100644 index 000000000..ff0644a50 --- /dev/null +++ b/backend/internal/api/handlers/stats_handler_test.go @@ -0,0 +1,314 @@ +package handlers + +import ( + "encoding/json" + "net/http" + "net/http/httptest" + "testing" + + "github.com/gin-gonic/gin" + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" + + "github.com/Wikid82/charon/backend/internal/models" + "github.com/Wikid82/charon/backend/internal/services" +) + +func openStatsTestDB(t *testing.T) *StatsHandler { + t.Helper() + db := OpenTestDB(t) + require.NoError(t, db.AutoMigrate(&models.RequestLog{}, &models.ProxyHost{}, &models.SSLCertificate{})) + svc := services.NewStatsService(db) + return NewStatsHandler(svc) +} + +func setupStatsRouter(h *StatsHandler) *gin.Engine { + gin.SetMode(gin.TestMode) + r := gin.New() + r.GET("/api/stats/summary", h.GetStatsSummary) + r.GET("/api/stats/top-hosts", h.GetTopHosts) + r.GET("/api/stats/status-distribution", h.GetStatusDistribution) + r.GET("/api/stats/traffic-volume", h.GetTrafficVolume) + r.GET("/api/stats/cert-expiry", h.GetCertExpiry) + r.GET("/api/stats/requests", h.GetRequests) + r.GET("/api/stats/health", h.GetStatsHealth) + return r +} + +// TestGetStatsSummary_Returns200WithCorrectShape — test 1 +func TestGetStatsSummary_Returns200WithCorrectShape(t *testing.T) { + h := openStatsTestDB(t) + r := setupStatsRouter(h) + + w := httptest.NewRecorder() + req, _ := http.NewRequest(http.MethodGet, "/api/stats/summary", nil) + r.ServeHTTP(w, req) + + assert.Equal(t, http.StatusOK, w.Code) + + var body map[string]any + require.NoError(t, json.Unmarshal(w.Body.Bytes(), &body)) + assert.Contains(t, body, "requests_last_24h") + assert.Contains(t, body, "requests_last_7d") + assert.Contains(t, body, "requests_last_30d") +} + +// TestGetTopHosts_ValidPeriod_Returns200 — test 2 +func TestGetTopHosts_ValidPeriod_Returns200(t *testing.T) { + h := openStatsTestDB(t) + r := setupStatsRouter(h) + + w := httptest.NewRecorder() + req, _ := http.NewRequest(http.MethodGet, "/api/stats/top-hosts?period=24h", nil) + r.ServeHTTP(w, req) + + assert.Equal(t, http.StatusOK, w.Code) +} + +// TestGetTopHosts_InvalidPeriod_Returns400 — test 3 +func TestGetTopHosts_InvalidPeriod_Returns400(t *testing.T) { + h := openStatsTestDB(t) + r := setupStatsRouter(h) + + w := httptest.NewRecorder() + req, _ := http.NewRequest(http.MethodGet, "/api/stats/top-hosts?period=invalid", nil) + r.ServeHTTP(w, req) + + assert.Equal(t, http.StatusBadRequest, w.Code) + + var body map[string]any + require.NoError(t, json.Unmarshal(w.Body.Bytes(), &body)) + assert.Contains(t, body, "error") +} + +// TestGetStatusDistribution_InvalidPeriod_Returns400 — test 4 +func TestGetStatusDistribution_InvalidPeriod_Returns400(t *testing.T) { + h := openStatsTestDB(t) + r := setupStatsRouter(h) + + w := httptest.NewRecorder() + req, _ := http.NewRequest(http.MethodGet, "/api/stats/status-distribution?period=bad", nil) + r.ServeHTTP(w, req) + + assert.Equal(t, http.StatusBadRequest, w.Code) +} + +// TestGetTrafficVolume_InvalidBucket_Returns400 — test 5 +func TestGetTrafficVolume_InvalidBucket_Returns400(t *testing.T) { + h := openStatsTestDB(t) + r := setupStatsRouter(h) + + w := httptest.NewRecorder() + req, _ := http.NewRequest(http.MethodGet, "/api/stats/traffic-volume?bucket=1w", nil) + r.ServeHTTP(w, req) + + assert.Equal(t, http.StatusBadRequest, w.Code) +} + +// TestGetCertExpiry_WithinDaysZero_Returns400 — test 6 +func TestGetCertExpiry_WithinDaysZero_Returns400(t *testing.T) { + h := openStatsTestDB(t) + r := setupStatsRouter(h) + + w := httptest.NewRecorder() + req, _ := http.NewRequest(http.MethodGet, "/api/stats/cert-expiry?within_days=0", nil) + r.ServeHTTP(w, req) + + assert.Equal(t, http.StatusBadRequest, w.Code) +} + +// TestGetCertExpiry_WithinDays366_Returns400 — test 7 +func TestGetCertExpiry_WithinDays366_Returns400(t *testing.T) { + h := openStatsTestDB(t) + r := setupStatsRouter(h) + + w := httptest.NewRecorder() + req, _ := http.NewRequest(http.MethodGet, "/api/stats/cert-expiry?within_days=366", nil) + r.ServeHTTP(w, req) + + assert.Equal(t, http.StatusBadRequest, w.Code) +} + +// TestGetStatsHealth_Returns200WithDroppedCount — test 8 +func TestGetStatsHealth_Returns200WithDroppedCount(t *testing.T) { + db := OpenTestDB(t) + require.NoError(t, db.AutoMigrate(&models.RequestLog{})) + svc := services.NewStatsService(db) + ingester := services.NewStatsIngester(db) + h := NewStatsHandlerWithIngester(svc, ingester) + + r := setupStatsRouter(h) + + w := httptest.NewRecorder() + req, _ := http.NewRequest(http.MethodGet, "/api/stats/health", nil) + r.ServeHTTP(w, req) + + assert.Equal(t, http.StatusOK, w.Code) + + var body map[string]any + require.NoError(t, json.Unmarshal(w.Body.Bytes(), &body)) + assert.Contains(t, body, "dropped_count") +} + +// TestGetRequests_ValidBucket_Returns200 — extra coverage +func TestGetRequests_ValidBucket_Returns200(t *testing.T) { + h := openStatsTestDB(t) + r := setupStatsRouter(h) + + w := httptest.NewRecorder() + req, _ := http.NewRequest(http.MethodGet, "/api/stats/requests?bucket=1h", nil) + r.ServeHTTP(w, req) + + assert.Equal(t, http.StatusOK, w.Code) +} + +// TestGetRequests_InvalidBucket_Returns400 — extra coverage +func TestGetRequests_InvalidBucket_Returns400(t *testing.T) { + h := openStatsTestDB(t) + r := setupStatsRouter(h) + + w := httptest.NewRecorder() + req, _ := http.NewRequest(http.MethodGet, "/api/stats/requests?bucket=bad", nil) + r.ServeHTTP(w, req) + + assert.Equal(t, http.StatusBadRequest, w.Code) +} + +// TestGetTopHosts_LimitCap_SilentlyCapAt50 — limit capping test +func TestGetTopHosts_LimitCap_SilentlyCapAt50(t *testing.T) { + h := openStatsTestDB(t) + r := setupStatsRouter(h) + + w := httptest.NewRecorder() + req, _ := http.NewRequest(http.MethodGet, "/api/stats/top-hosts?period=24h&limit=100", nil) + r.ServeHTTP(w, req) + + // Should not return 400 — limit is silently capped + assert.Equal(t, http.StatusOK, w.Code) +} + +// TestGetCertExpiry_ValidWithinDays_Returns200 — valid range passes +func TestGetCertExpiry_ValidWithinDays_Returns200(t *testing.T) { + h := openStatsTestDB(t) + r := setupStatsRouter(h) + + w := httptest.NewRecorder() + req, _ := http.NewRequest(http.MethodGet, "/api/stats/cert-expiry?within_days=30", nil) + r.ServeHTTP(w, req) + + assert.Equal(t, http.StatusOK, w.Code) +} + +// openStatsTestDBWithClosedDB returns a handler whose underlying DB is closed, +// causing all service calls to return errors. +func openStatsTestDBWithClosedDB(t *testing.T) *StatsHandler { + t.Helper() + db := OpenTestDB(t) + require.NoError(t, db.AutoMigrate(&models.RequestLog{}, &models.ProxyHost{}, &models.SSLCertificate{})) + svc := services.NewStatsService(db) + // Close the underlying SQL connection to force errors on every query. + sqlDB, err := db.DB() + require.NoError(t, err) + require.NoError(t, sqlDB.Close()) + return NewStatsHandler(svc) +} + +// TestGetStatsSummary_DBError_Returns500 covers the error path in GetStatsSummary. +func TestGetStatsSummary_DBError_Returns500(t *testing.T) { + h := openStatsTestDBWithClosedDB(t) + r := setupStatsRouter(h) + + w := httptest.NewRecorder() + req, _ := http.NewRequest(http.MethodGet, "/api/stats/summary", nil) + r.ServeHTTP(w, req) + + assert.Equal(t, http.StatusInternalServerError, w.Code) +} + +// TestGetTopHosts_DBError_Returns500 covers the error path in GetTopHosts. +func TestGetTopHosts_DBError_Returns500(t *testing.T) { + h := openStatsTestDBWithClosedDB(t) + r := setupStatsRouter(h) + + w := httptest.NewRecorder() + req, _ := http.NewRequest(http.MethodGet, "/api/stats/top-hosts?period=24h", nil) + r.ServeHTTP(w, req) + + assert.Equal(t, http.StatusInternalServerError, w.Code) +} + +// TestGetStatusDistribution_DBError_Returns500 covers the error path in GetStatusDistribution. +func TestGetStatusDistribution_DBError_Returns500(t *testing.T) { + h := openStatsTestDBWithClosedDB(t) + r := setupStatsRouter(h) + + w := httptest.NewRecorder() + req, _ := http.NewRequest(http.MethodGet, "/api/stats/status-distribution?period=24h", nil) + r.ServeHTTP(w, req) + + assert.Equal(t, http.StatusInternalServerError, w.Code) +} + +// TestGetTrafficVolume_DBError_Returns500 covers the error path in GetTrafficVolume. +func TestGetTrafficVolume_DBError_Returns500(t *testing.T) { + h := openStatsTestDBWithClosedDB(t) + r := setupStatsRouter(h) + + w := httptest.NewRecorder() + req, _ := http.NewRequest(http.MethodGet, "/api/stats/traffic-volume?bucket=1h", nil) + r.ServeHTTP(w, req) + + assert.Equal(t, http.StatusInternalServerError, w.Code) +} + +// TestGetCertExpiry_NonIntegerWithinDays_Returns400 covers the strconv.Atoi error path. +func TestGetCertExpiry_NonIntegerWithinDays_Returns400(t *testing.T) { + h := openStatsTestDB(t) + r := setupStatsRouter(h) + + w := httptest.NewRecorder() + req, _ := http.NewRequest(http.MethodGet, "/api/stats/cert-expiry?within_days=abc", nil) + r.ServeHTTP(w, req) + + assert.Equal(t, http.StatusBadRequest, w.Code) + var body map[string]any + require.NoError(t, json.Unmarshal(w.Body.Bytes(), &body)) + assert.Contains(t, body, "error") +} + +// TestGetCertExpiry_DBError_Returns500 covers the error path in GetCertExpiry. +func TestGetCertExpiry_DBError_Returns500(t *testing.T) { + h := openStatsTestDBWithClosedDB(t) + r := setupStatsRouter(h) + + w := httptest.NewRecorder() + req, _ := http.NewRequest(http.MethodGet, "/api/stats/cert-expiry?within_days=30", nil) + r.ServeHTTP(w, req) + + assert.Equal(t, http.StatusInternalServerError, w.Code) +} + +// TestGetRequests_DBError_Returns500 covers the error path in GetRequests. +func TestGetRequests_DBError_Returns500(t *testing.T) { + h := openStatsTestDBWithClosedDB(t) + r := setupStatsRouter(h) + + w := httptest.NewRecorder() + req, _ := http.NewRequest(http.MethodGet, "/api/stats/requests?bucket=1h", nil) + r.ServeHTTP(w, req) + + assert.Equal(t, http.StatusInternalServerError, w.Code) +} + +// TestGetTopHosts_InvalidLimitIgnored_Returns200 covers the limit parse error branch. +func TestGetTopHosts_InvalidLimitIgnored_Returns200(t *testing.T) { + h := openStatsTestDB(t) + r := setupStatsRouter(h) + + w := httptest.NewRecorder() + // Non-integer limit is silently ignored, defaulting to 10. + req, _ := http.NewRequest(http.MethodGet, "/api/stats/top-hosts?period=24h&limit=abc", nil) + r.ServeHTTP(w, req) + + assert.Equal(t, http.StatusOK, w.Code) +} diff --git a/backend/internal/api/handlers/stats_ws_hub.go b/backend/internal/api/handlers/stats_ws_hub.go new file mode 100644 index 000000000..6d08a39df --- /dev/null +++ b/backend/internal/api/handlers/stats_ws_hub.go @@ -0,0 +1,131 @@ +package handlers + +import ( + "context" + "encoding/json" + "sync" + + "github.com/gorilla/websocket" + + "github.com/Wikid82/charon/backend/internal/logger" + "github.com/Wikid82/charon/backend/internal/services" +) + +const statsWSWriteBuffer = 64 + +// statsWSClient represents a single connected WebSocket client. +type statsWSClient struct { + conn *websocket.Conn + send chan []byte + closeOnce sync.Once +} + +func (c *statsWSClient) close() { + c.closeOnce.Do(func() { + close(c.send) + _ = c.conn.Close() + }) +} + +// StatsWSHub manages WebSocket clients for real-time stats push messages. +// It implements services.BroadcastHub. +type StatsWSHub struct { + mu sync.RWMutex + clients map[*statsWSClient]struct{} + broadcast chan services.StatsPushMessage + register chan *statsWSClient + unregister chan *statsWSClient +} + +// NewStatsWSHub creates a new StatsWSHub ready to Run. +func NewStatsWSHub() *StatsWSHub { + return &StatsWSHub{ + clients: make(map[*statsWSClient]struct{}), + broadcast: make(chan services.StatsPushMessage, 64), + register: make(chan *statsWSClient, 16), + unregister: make(chan *statsWSClient, 16), + } +} + +// Broadcast implements services.BroadcastHub. +// It is safe to call from any goroutine; the message is queued non-blocking. +func (h *StatsWSHub) Broadcast(msg services.StatsPushMessage) { + select { + case h.broadcast <- msg: + default: + logger.Log().Warn("StatsWSHub broadcast channel full — message dropped") + } +} + +// Run processes registrations and broadcasts until ctx is cancelled. +// Start as a goroutine: go hub.Run(ctx) +func (h *StatsWSHub) Run(ctx context.Context) { + for { + select { + case <-ctx.Done(): + h.mu.Lock() + for client := range h.clients { + client.close() + delete(h.clients, client) + } + h.mu.Unlock() + return + + case client := <-h.register: + h.mu.Lock() + h.clients[client] = struct{}{} + h.mu.Unlock() + + case client := <-h.unregister: + h.mu.Lock() + if _, ok := h.clients[client]; ok { + delete(h.clients, client) + client.close() + } + h.mu.Unlock() + + case msg := <-h.broadcast: + payload, err := json.Marshal(msg) + if err != nil { + logger.Log().WithError(err).Error("StatsWSHub: failed to marshal broadcast message") + continue + } + + h.mu.RLock() + for client := range h.clients { + select { + case client.send <- payload: + default: + // Non-blocking: drop to slow clients. + logger.Log().Warn("StatsWSHub: slow client dropped message") + } + } + h.mu.RUnlock() + } + } +} + +// ServeClient upgrades c to WebSocket and registers it with the hub. +// It blocks until the client disconnects. Call from a Gin handler. +func (h *StatsWSHub) ServeClient(c *statsWSClient) { + h.register <- c + + // Writer goroutine: forwards hub messages to the WebSocket connection. + go func() { + for payload := range c.send { + if err := c.conn.WriteMessage(websocket.TextMessage, payload); err != nil { + break + } + } + _ = c.conn.Close() + }() + + // Reader loop: detects client disconnect. + for { + if _, _, err := c.conn.ReadMessage(); err != nil { + break + } + } + + h.unregister <- c +} diff --git a/backend/internal/api/handlers/stats_ws_hub_test.go b/backend/internal/api/handlers/stats_ws_hub_test.go new file mode 100644 index 000000000..b5bbcfcc7 --- /dev/null +++ b/backend/internal/api/handlers/stats_ws_hub_test.go @@ -0,0 +1,290 @@ +package handlers + +import ( + "context" + "encoding/json" + "net/http" + "net/http/httptest" + "strings" + "testing" + "time" + + "github.com/gin-gonic/gin" + "github.com/gorilla/websocket" + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" + + "github.com/Wikid82/charon/backend/internal/models" + "github.com/Wikid82/charon/backend/internal/services" +) + +// newHubServer creates an httptest.Server that upgrades connections and routes them +// through the given hub's ServeClient. Use for integration-style hub tests. +func newHubServer(t *testing.T, hub *StatsWSHub) *httptest.Server { + t.Helper() + gin.SetMode(gin.TestMode) + r := gin.New() + r.GET("/ws", func(c *gin.Context) { + conn, err := upgrader.Upgrade(c.Writer, c.Request, nil) // nosemgrep: go.gorilla.security.audit.websocket-missing-origin-check.websocket-missing-origin-check + if err != nil { + return + } + client := &statsWSClient{ + conn: conn, + send: make(chan []byte, statsWSWriteBuffer), + } + hub.ServeClient(client) + }) + return httptest.NewServer(r) +} + +// dialHub connects a WebSocket client to the test server. +func dialHub(t *testing.T, srv *httptest.Server) *websocket.Conn { + t.Helper() + wsURL := "ws" + strings.TrimPrefix(srv.URL, "http") + "/ws" + conn, _, err := websocket.DefaultDialer.Dial(wsURL, nil) //nolint:bodyclose + require.NoError(t, err) + return conn +} + +// TestNewStatsWSHub verifies constructor initialises all channels and the client map. +func TestNewStatsWSHub(t *testing.T) { + t.Parallel() + hub := NewStatsWSHub() + require.NotNil(t, hub) + assert.NotNil(t, hub.clients) + assert.NotNil(t, hub.broadcast) + assert.NotNil(t, hub.register) + assert.NotNil(t, hub.unregister) +} + +// TestStatsWSHub_Broadcast_NonBlockingWhenFull verifies that Broadcast never blocks +// even when the internal broadcast channel is at capacity. +func TestStatsWSHub_Broadcast_NonBlockingWhenFull(t *testing.T) { + t.Parallel() + hub := NewStatsWSHub() + + // Fill the broadcast channel to capacity (64). + msg := services.StatsPushMessage{Type: "stats_update"} + for i := 0; i < 64; i++ { + hub.broadcast <- msg + } + + // This call must not block or panic. + done := make(chan struct{}) + go func() { + hub.Broadcast(msg) + close(done) + }() + + select { + case <-done: + // success + case <-time.After(time.Second): + t.Fatal("Broadcast blocked on a full channel") + } +} + +// TestStatsWSHub_Run_ExitsOnContextCancel verifies Run returns when ctx is cancelled +// with no connected clients. +func TestStatsWSHub_Run_ExitsOnContextCancel(t *testing.T) { + t.Parallel() + hub := NewStatsWSHub() + ctx, cancel := context.WithCancel(context.Background()) + + done := make(chan struct{}) + go func() { + hub.Run(ctx) + close(done) + }() + + cancel() + select { + case <-done: + // Run exited cleanly. + case <-time.After(3 * time.Second): + t.Fatal("Run did not exit after context cancellation") + } +} + +// TestStatsWSHub_BroadcastToConnectedClient verifies that a message broadcast via +// Broadcast is forwarded to a connected WebSocket client. +func TestStatsWSHub_BroadcastToConnectedClient(t *testing.T) { + t.Parallel() + hub := NewStatsWSHub() + ctx, cancel := context.WithCancel(context.Background()) + defer cancel() + go hub.Run(ctx) + + srv := newHubServer(t, hub) + defer srv.Close() + + conn := dialHub(t, srv) + t.Cleanup(func() { _ = conn.Close() }) + + // Allow the client to register. + time.Sleep(50 * time.Millisecond) + + summary := services.StatsPushData{ + RequestsLast24h: 42, + RequestsLast7d: 294, + RequestsLast30d: 1260, + } + hub.Broadcast(services.StatsPushMessage{Type: "stats_update", Data: summary}) + + require.NoError(t, conn.SetReadDeadline(time.Now().Add(3*time.Second))) + _, data, err := conn.ReadMessage() + require.NoError(t, err) + + var got services.StatsPushMessage + require.NoError(t, json.Unmarshal(data, &got)) + assert.Equal(t, "stats_update", got.Type) + assert.Equal(t, int64(42), got.Data.RequestsLast24h) +} + +// TestStatsWSHub_Run_ClosesClientsOnContextCancel verifies that connected clients +// receive a close message when the hub's context is cancelled. +func TestStatsWSHub_Run_ClosesClientsOnContextCancel(t *testing.T) { + t.Parallel() + hub := NewStatsWSHub() + ctx, cancel := context.WithCancel(context.Background()) + + go hub.Run(ctx) + + srv := newHubServer(t, hub) + defer srv.Close() + + conn := dialHub(t, srv) + t.Cleanup(func() { _ = conn.Close() }) + + // Allow the client to register. + time.Sleep(50 * time.Millisecond) + + // Cancel hub — clients should be closed. + cancel() + + require.NoError(t, conn.SetReadDeadline(time.Now().Add(3*time.Second))) + _, _, err := conn.ReadMessage() + // Expect an error (close frame or EOF) after hub cancellation. + assert.Error(t, err, "expected connection to be closed after hub cancel") +} + +// TestStatsWSHub_Run_SlowClientDropsMessage verifies that Broadcast does not deadlock +// when a client's send channel is full. +func TestStatsWSHub_Run_SlowClientDropsMessage(t *testing.T) { + t.Parallel() + hub := NewStatsWSHub() + ctx, cancel := context.WithCancel(context.Background()) + defer cancel() + go hub.Run(ctx) + + srv := newHubServer(t, hub) + defer srv.Close() + + conn := dialHub(t, srv) + t.Cleanup(func() { _ = conn.Close() }) + + // Allow the client to register. + time.Sleep(50 * time.Millisecond) + + // Flood the hub with more messages than the client buffer (64). Do NOT read from conn. + done := make(chan struct{}) + go func() { + for i := 0; i < 128; i++ { + hub.Broadcast(services.StatsPushMessage{Type: "stats_update"}) + } + close(done) + }() + + select { + case <-done: + // No deadlock — slow client messages were dropped gracefully. + case <-time.After(5 * time.Second): + t.Fatal("Broadcast deadlocked with a slow client") + } +} + +// TestStatsWSHub_StatsWSHandler_NonWebSocketRequest verifies that StatsWS returns +// gracefully when the WebSocket upgrade fails (plain HTTP request). +func TestStatsWSHub_StatsWSHandler_NonWebSocketRequest(t *testing.T) { + t.Parallel() + gin.SetMode(gin.TestMode) + + db := OpenTestDB(t) + require.NoError(t, db.AutoMigrate(&models.RequestLog{}, &models.ProxyHost{}, &models.SSLCertificate{})) + svc := services.NewStatsService(db) + h := NewStatsHandler(svc) + + r := gin.New() + r.GET("/ws", h.StatsWS) + srv := httptest.NewServer(r) + defer srv.Close() + + // Plain HTTP GET — no WebSocket upgrade headers — upgrader.Upgrade will fail. + resp, err := http.Get(srv.URL + "/ws") //nolint:noctx + require.NoError(t, err) + _ = resp.Body.Close() + // The handler returns after the upgrade error — any HTTP response is acceptable. +} + +// TestStatsWSHub_StatsWSHandler_NilHub verifies that StatsWS closes the connection +// immediately when no hub is wired (h.hub == nil). +func TestStatsWSHub_StatsWSHandler_NilHub(t *testing.T) { + t.Parallel() + gin.SetMode(gin.TestMode) + + db := OpenTestDB(t) + require.NoError(t, db.AutoMigrate(&models.RequestLog{}, &models.ProxyHost{}, &models.SSLCertificate{})) + svc := services.NewStatsService(db) + // NewStatsHandler leaves hub as nil. + h := NewStatsHandler(svc) + + r := gin.New() + r.GET("/ws", h.StatsWS) + srv := httptest.NewServer(r) + defer srv.Close() + + wsURL := "ws" + strings.TrimPrefix(srv.URL, "http") + "/ws" + conn, _, err := websocket.DefaultDialer.Dial(wsURL, nil) //nolint:bodyclose + require.NoError(t, err) + t.Cleanup(func() { _ = conn.Close() }) + + // Hub is nil — handler closes the conn immediately after upgrade. + require.NoError(t, conn.SetReadDeadline(time.Now().Add(3*time.Second))) + _, _, err = conn.ReadMessage() + assert.Error(t, err, "expected immediate connection close when hub is nil") +} + +// TestStatsWSHub_UnregisterRemovesClient verifies unregistering a client removes it +// from the hub and the client's send channel is closed (preventing goroutine leak). +func TestStatsWSHub_UnregisterRemovesClient(t *testing.T) { + t.Parallel() + hub := NewStatsWSHub() + ctx, cancel := context.WithCancel(context.Background()) + defer cancel() + go hub.Run(ctx) + + srv := newHubServer(t, hub) + defer srv.Close() + + conn := dialHub(t, srv) + + // Allow registration. + time.Sleep(50 * time.Millisecond) + + hub.mu.RLock() + clientsBefore := len(hub.clients) + hub.mu.RUnlock() + assert.Equal(t, 1, clientsBefore) + + // Close the client-side connection — ServeClient's read loop will detect the close + // and send to hub.unregister. + _ = conn.Close() + + require.Eventually(t, func() bool { + hub.mu.RLock() + n := len(hub.clients) + hub.mu.RUnlock() + return n == 0 + }, 3*time.Second, 25*time.Millisecond, "expected client to be unregistered after disconnect") +} diff --git a/backend/internal/api/routes/routes.go b/backend/internal/api/routes/routes.go index ddb2de51d..93115c84e 100644 --- a/backend/internal/api/routes/routes.go +++ b/backend/internal/api/routes/routes.go @@ -132,6 +132,7 @@ func RegisterWithDeps(ctx context.Context, router *gin.Engine, db *gorm.DB, cfg &models.CrowdSecWhitelist{}, // Issue #939: CrowdSec IP whitelist management &models.TunnelConfig{}, // Issue #368: Hecate tunnel provider configs &models.OrthrusAgent{}, // Issue #369: Orthrus reverse-proxy agent registry + &models.RequestLog{}, // Issue #25: Enhanced dashboard statistics ); err != nil { return fmt.Errorf("auto migrate: %w", err) } @@ -703,12 +704,36 @@ func RegisterWithDeps(ctx context.Context, router *gin.Engine, db *gorm.DB, cfg } logWatcher := services.NewLogWatcher(accessLogPath) + + // Stats pipeline: ingester fan-out from LogWatcher, hub for WebSocket push. + statsIngester := services.NewStatsIngester(db) + logWatcher.RegisterIngester(statsIngester) + statsWSHub := handlers.NewStatsWSHub() + statsIngester.RegisterHub(statsWSHub) + + go statsWSHub.Run(ctx) + go statsIngester.Run(ctx) + if err := logWatcher.Start(context.Background()); err != nil { logger.Log().WithError(err).Error("Failed to start security log watcher") + } else { + logger.Log().WithField("path", accessLogPath).Info("Security log watcher started - stats collection enabled") } cerberusLogsHandler := handlers.NewCerberusLogsHandler(logWatcher, wsTracker) management.GET("/cerberus/logs/ws", cerberusLogsHandler.LiveLogs) + // Stats API routes (Issue #25) + statsService := services.NewStatsService(db) + statsHandler := handlers.NewStatsHandlerFull(statsService, statsIngester, statsWSHub) + management.GET("/stats/summary", statsHandler.GetStatsSummary) + management.GET("/stats/top-hosts", statsHandler.GetTopHosts) + management.GET("/stats/status-distribution", statsHandler.GetStatusDistribution) + management.GET("/stats/traffic-volume", statsHandler.GetTrafficVolume) + management.GET("/stats/cert-expiry", statsHandler.GetCertExpiry) + management.GET("/stats/requests", statsHandler.GetRequests) + management.GET("/stats/health", statsHandler.GetStatsHealth) + management.GET("/stats/ws", statsHandler.StatsWS) + // Access Lists accessListHandler := handlers.NewAccessListHandler(db) if geoipSvc != nil { diff --git a/backend/internal/database/database.go b/backend/internal/database/database.go index 9ee5d2ab6..33dd8f668 100644 --- a/backend/internal/database/database.go +++ b/backend/internal/database/database.go @@ -4,10 +4,14 @@ package database import ( "database/sql" "fmt" + "log" + "os" + "time" "github.com/Wikid82/charon/backend/internal/logger" "github.com/glebarez/sqlite" "gorm.io/gorm" + gormlogger "gorm.io/gorm/logger" ) // Connect opens a SQLite database connection with optimized settings. @@ -20,6 +24,13 @@ func Connect(dbPath string) (*gorm.DB, error) { SkipDefaultTransaction: true, // Prepare statements for reuse PrepareStmt: true, + // Many lookups (e.g. optional settings) expect a missing row as a + // normal outcome and already handle it; don't log those as errors. + Logger: gormlogger.New(log.New(os.Stdout, "\r\n", log.LstdFlags), gormlogger.Config{ + SlowThreshold: 200 * time.Millisecond, + LogLevel: gormlogger.Warn, + IgnoreRecordNotFoundError: true, + }), }) if err != nil { return nil, fmt.Errorf("open database: %w", err) @@ -55,9 +66,32 @@ func Connect(dbPath string) (*gorm.DB, error) { logger.Log().WithField("journal_mode", journalMode).Info("SQLite database connected with optimized settings") } - // Run quick integrity check on startup (non-blocking, warn-only) + // Run quick integrity check on startup in the background (warn-only), on + // its own connection. The main pool is capped at one connection, so + // sharing it here would still serialize migrations behind the check. + go runQuickCheck(dbPath) + + return db, nil +} + +// runQuickCheck opens a dedicated connection and runs PRAGMA quick_check, +// logging the result. It uses its own connection (rather than the shared +// pool, which is capped at one) so the scan - which can take well over a +// minute on larger databases - never blocks startup or migrations. +func runQuickCheck(dbPath string) { + checkDB, err := sql.Open(sqlite.DriverName, dbPath) + if err != nil { + logger.Log().WithError(err).Warn("Failed to open SQLite connection for integrity check") + return + } + defer func() { + if cerr := checkDB.Close(); cerr != nil { + logger.Log().WithError(cerr).Warn("Failed to close SQLite integrity check connection") + } + }() + var quickCheckResult string - if err := db.Raw("PRAGMA quick_check").Scan(&quickCheckResult).Error; err != nil { + if err := checkDB.QueryRow("PRAGMA quick_check").Scan(&quickCheckResult); err != nil { logger.Log().WithError(err).Warn("Failed to run SQLite integrity check on startup") } else if quickCheckResult == "ok" { logger.Log().Info("SQLite database integrity check passed") @@ -67,8 +101,6 @@ func Connect(dbPath string) (*gorm.DB, error) { WithField("error_type", "database_corruption"). Error("SQLite database integrity check failed - database may be corrupted") } - - return db, nil } // configurePool sets connection pool settings for SQLite. diff --git a/backend/internal/models/request_log.go b/backend/internal/models/request_log.go new file mode 100644 index 000000000..c87850f47 --- /dev/null +++ b/backend/internal/models/request_log.go @@ -0,0 +1,31 @@ +package models + +import ( + "time" + + "github.com/google/uuid" + "gorm.io/gorm" +) + +// RequestLog records a single proxied HTTP request for dashboard statistics. +// ClientIPHash stores the first 16 bytes of the SHA-256 hash of the client IP +// as a hex string (GDPR-safe pseudonymisation). +type RequestLog struct { + ID string `json:"id" gorm:"primaryKey;type:text"` + HostID string `json:"host_id" gorm:"type:text;not null;index"` + Timestamp time.Time `json:"timestamp" gorm:"not null;index"` + Method string `json:"method" gorm:"type:text;not null"` + StatusCode int `json:"status_code" gorm:"not null;index"` + BytesSent int64 `json:"bytes_sent" gorm:"not null"` + DurationMs int64 `json:"duration_ms" gorm:"not null"` + // gorm-scanner:ignore — ClientIPHash is a GDPR-safe SHA-256 pseudonymisation (first 16 bytes, hex-encoded); not raw PII. + ClientIPHash string `json:"client_ip_hash" gorm:"type:text"` +} + +// BeforeCreate sets a new UUID on ID if the caller did not supply one. +func (r *RequestLog) BeforeCreate(_ *gorm.DB) error { + if r.ID == "" { + r.ID = uuid.New().String() + } + return nil +} diff --git a/backend/internal/models/request_log_test.go b/backend/internal/models/request_log_test.go new file mode 100644 index 000000000..76aa89d6f --- /dev/null +++ b/backend/internal/models/request_log_test.go @@ -0,0 +1,131 @@ +package models + +import ( + "fmt" + "sync/atomic" + "testing" + "time" + + "gorm.io/driver/sqlite" + "gorm.io/gorm" +) + +var requestLogDBSeq uint64 + +func setupRequestLogTestDB(t *testing.T) *gorm.DB { + t.Helper() + n := atomic.AddUint64(&requestLogDBSeq, 1) + dsn := fmt.Sprintf("file:rl_test_%d?mode=memory&cache=private", n) + db, err := gorm.Open(sqlite.Open(dsn), &gorm.Config{}) + if err != nil { + t.Fatalf("failed to open in-memory db: %v", err) + } + if err := db.AutoMigrate(&RequestLog{}); err != nil { + t.Fatalf("auto migrate failed: %v", err) + } + return db +} + +func TestRequestLog_BeforeCreate_SetsID(t *testing.T) { + db := setupRequestLogTestDB(t) + log := &RequestLog{ + HostID: "host-uuid-1", + Timestamp: time.Now(), + Method: "GET", + StatusCode: 200, + BytesSent: 1024, + DurationMs: 42, + } + if err := db.Create(log).Error; err != nil { + t.Fatalf("create failed: %v", err) + } + if log.ID == "" { + t.Fatal("expected ID to be populated by BeforeCreate") + } +} + +func TestRequestLog_BeforeCreate_PreservesID(t *testing.T) { + db := setupRequestLogTestDB(t) + log := &RequestLog{ + ID: "preset-id-abc", + HostID: "host-uuid-2", + Timestamp: time.Now(), + Method: "POST", + StatusCode: 201, + BytesSent: 512, + DurationMs: 10, + } + if err := db.Create(log).Error; err != nil { + t.Fatalf("create failed: %v", err) + } + if log.ID != "preset-id-abc" { + t.Fatalf("expected ID to remain 'preset-id-abc', got %q", log.ID) + } +} + +func TestRequestLog_JSONTags(t *testing.T) { + log := RequestLog{ + ID: "test-id", + HostID: "host-1", + Timestamp: time.Now(), + Method: "DELETE", + StatusCode: 404, + BytesSent: 0, + DurationMs: 5, + ClientIPHash: "abcdef1234567890", + } + + // Verify all fields are accessible (compile-time check via struct literal) + if log.ID == "" || log.HostID == "" || log.Method == "" { + t.Fatal("required fields must not be empty") + } +} + +func TestRequestLog_MultipleRecords(t *testing.T) { + db := setupRequestLogTestDB(t) + + logs := []*RequestLog{ + {HostID: "host-1", Timestamp: time.Now(), Method: "GET", StatusCode: 200, BytesSent: 100, DurationMs: 10}, + {HostID: "host-1", Timestamp: time.Now(), Method: "POST", StatusCode: 500, BytesSent: 50, DurationMs: 200}, + {HostID: "host-2", Timestamp: time.Now(), Method: "GET", StatusCode: 301, BytesSent: 0, DurationMs: 1}, + } + + for _, l := range logs { + if err := db.Create(l).Error; err != nil { + t.Fatalf("create failed: %v", err) + } + if l.ID == "" { + t.Fatal("expected ID to be set after create") + } + } + + var count int64 + db.Model(&RequestLog{}).Count(&count) + if count != 3 { + t.Fatalf("expected 3 records, got %d", count) + } +} + +func TestRequestLog_IndexedQuery(t *testing.T) { + db := setupRequestLogTestDB(t) + + now := time.Now() + entries := []*RequestLog{ + {HostID: "host-abc", Timestamp: now, Method: "GET", StatusCode: 200, BytesSent: 100, DurationMs: 10}, + {HostID: "host-abc", Timestamp: now.Add(time.Second), Method: "GET", StatusCode: 500, BytesSent: 200, DurationMs: 50}, + {HostID: "host-xyz", Timestamp: now, Method: "GET", StatusCode: 200, BytesSent: 10, DurationMs: 5}, + } + for _, e := range entries { + if err := db.Create(e).Error; err != nil { + t.Fatalf("create failed: %v", err) + } + } + + var results []RequestLog + if err := db.Where("host_id = ? AND status_code = ?", "host-abc", 500).Find(&results).Error; err != nil { + t.Fatalf("query failed: %v", err) + } + if len(results) != 1 { + t.Fatalf("expected 1 result, got %d", len(results)) + } +} diff --git a/backend/internal/services/log_watcher.go b/backend/internal/services/log_watcher.go index 5a0c112bf..ebb9dad9b 100644 --- a/backend/internal/services/log_watcher.go +++ b/backend/internal/services/log_watcher.go @@ -25,6 +25,7 @@ type LogWatcher struct { ctx context.Context cancel context.CancelFunc started bool + ingester *StatsIngester // optional fan-out to StatsIngester; nil when not registered } // NewLogWatcher creates a new LogWatcher instance for the given log file path. @@ -67,6 +68,16 @@ func (w *LogWatcher) Stop() { logger.Log().Info("LogWatcher stopped") } +// RegisterIngester wires a StatsIngester into the fan-out path. +// Every parsed log entry will be forwarded to the ingester via Send (non-blocking). +// This must be called before Start for the ingester to receive all entries. +func (w *LogWatcher) RegisterIngester(ing *StatsIngester) { + w.mu.Lock() + defer w.mu.Unlock() + w.ingester = ing + logger.Log().Debug("StatsIngester registered with LogWatcher") +} + // Subscribe adds a new subscriber and returns a channel for receiving log entries. // The caller is responsible for calling Unsubscribe when done. func (w *LogWatcher) Subscribe() <-chan models.SecurityLogEntry { @@ -98,7 +109,7 @@ func (w *LogWatcher) Unsubscribe(ch <-chan models.SecurityLogEntry) { } } -// broadcast sends a log entry to all subscribers. +// broadcast sends a log entry to all subscribers and, if registered, to the StatsIngester. // Non-blocking: if a subscriber's channel is full, the entry is dropped for that subscriber. func (w *LogWatcher) broadcast(entry models.SecurityLogEntry) { w.mu.RLock() @@ -112,6 +123,11 @@ func (w *LogWatcher) broadcast(entry models.SecurityLogEntry) { // Channel is full, skip (prevents blocking other subscribers) } } + + // Fan-out to StatsIngester (non-blocking via Send). + if w.ingester != nil { + w.ingester.Send(entry) + } } // tailFile continuously reads new entries from the log file. diff --git a/backend/internal/services/stats_ingester.go b/backend/internal/services/stats_ingester.go new file mode 100644 index 000000000..308df26f0 --- /dev/null +++ b/backend/internal/services/stats_ingester.go @@ -0,0 +1,157 @@ +// Package services provides business logic services for the application. +package services + +import ( + "context" + "crypto/sha256" + "encoding/hex" + "sync/atomic" + "time" + + "github.com/Wikid82/charon/backend/internal/logger" + "github.com/Wikid82/charon/backend/internal/models" + "gorm.io/gorm" +) + +const ( + channelBufferSize = 1000 + batchSize = 100 + flushInterval = 500 * time.Millisecond +) + +// StatsIngester receives parsed log entries from LogWatcher via a fan-out channel, +// batches them, and bulk-inserts them into the RequestLog table. +// Client IPs are SHA-256 hashed (first 16 bytes) for GDPR-safe pseudonymisation. +type StatsIngester struct { + db *gorm.DB + ingestCh chan models.SecurityLogEntry + droppedCount atomic.Int64 //nolint:govet // atomic.Int64 is properly aligned + hub BroadcastHub // optional; nil when WebSocket push not required +} + +// NewStatsIngester creates a StatsIngester backed by the provided GORM DB. +func NewStatsIngester(db *gorm.DB) *StatsIngester { + return &StatsIngester{ + db: db, + ingestCh: make(chan models.SecurityLogEntry, channelBufferSize), + } +} + +// Send attempts a non-blocking send of an entry to the ingester channel. +// If the channel buffer is full the entry is dropped and droppedCount is incremented. +func (s *StatsIngester) Send(entry models.SecurityLogEntry) { + select { + case s.ingestCh <- entry: + default: + s.droppedCount.Add(1) + logger.Log().Warn("StatsIngester channel full — log entry dropped") + } +} + +// DroppedCount returns the total number of entries dropped due to a full channel. +func (s *StatsIngester) DroppedCount() int64 { + return s.droppedCount.Load() +} + +// RegisterHub wires a BroadcastHub into the ingester for real-time WebSocket push. +// Call this before Run so the hub receives updates as batches are flushed. +func (s *StatsIngester) RegisterHub(h BroadcastHub) { + s.hub = h +} + +// Run processes incoming entries, batching writes to SQLite. +// It exits when ctx is cancelled. +func (s *StatsIngester) Run(ctx context.Context) { + ticker := time.NewTicker(flushInterval) + defer ticker.Stop() + + batch := make([]models.RequestLog, 0, batchSize) + + flush := func() { + if len(batch) == 0 { + return + } + if err := s.db.CreateInBatches(batch, batchSize).Error; err != nil { + logger.Log().WithError(err).Error("StatsIngester: failed to flush batch to DB") + } + batch = batch[:0] + } + + for { + select { + case <-ctx.Done(): + // Drain any remaining queued entries before exiting. + for { + select { + case entry := <-s.ingestCh: + batch = append(batch, toRequestLog(entry)) + if len(batch) >= batchSize { + flush() + } + default: + flush() + return + } + } + + case entry := <-s.ingestCh: + batch = append(batch, toRequestLog(entry)) + if len(batch) >= batchSize { + flush() + } + + case <-ticker.C: + flush() + } + } +} + +// Stop drains any remaining entries from the channel and flushes them to the DB. +// It is intended to be called after Run has returned (ctx cancelled). +func (s *StatsIngester) Stop() { + batch := make([]models.RequestLog, 0, batchSize) + + for { + select { + case entry := <-s.ingestCh: + batch = append(batch, toRequestLog(entry)) + if len(batch) >= batchSize { + if err := s.db.CreateInBatches(batch, batchSize).Error; err != nil { + logger.Log().WithError(err).Error("StatsIngester.Stop: failed to flush batch") + } + batch = batch[:0] + } + default: + if len(batch) > 0 { + if err := s.db.CreateInBatches(batch, batchSize).Error; err != nil { + logger.Log().WithError(err).Error("StatsIngester.Stop: failed to flush final batch") + } + } + return + } + } +} + +// toRequestLog converts a SecurityLogEntry to a RequestLog for persistence. +func toRequestLog(e models.SecurityLogEntry) models.RequestLog { + ts, err := time.Parse(time.RFC3339, e.Timestamp) + if err != nil { + ts = time.Now() + } + return models.RequestLog{ + HostID: e.Host, + Timestamp: ts, + Method: e.Method, + StatusCode: e.Status, + BytesSent: e.Size, + DurationMs: int64(e.Duration * 1000), + ClientIPHash: hashClientIP(e.ClientIP), + } +} + +// hashClientIP returns the first 16 bytes of the SHA-256 hash of rawIP as a hex string. +// This provides GDPR-safe pseudonymisation — the raw IP is never stored. +func hashClientIP(rawIP string) string { + sum := sha256.Sum256([]byte(rawIP)) + return hex.EncodeToString(sum[:16]) +} diff --git a/backend/internal/services/stats_ingester_test.go b/backend/internal/services/stats_ingester_test.go new file mode 100644 index 000000000..a4b4fe3b1 --- /dev/null +++ b/backend/internal/services/stats_ingester_test.go @@ -0,0 +1,308 @@ +package services + +import ( + "context" + "crypto/sha256" + "encoding/hex" + "path/filepath" + "sync" + "testing" + "time" + + "github.com/Wikid82/charon/backend/internal/models" + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" + "gorm.io/driver/sqlite" + "gorm.io/gorm" + "gorm.io/gorm/logger" +) + +func setupStatsTestDB(t *testing.T) *gorm.DB { + t.Helper() + dsn := filepath.Join(t.TempDir(), "stats_test.db") + "?_busy_timeout=5000&_journal_mode=WAL" + db, err := gorm.Open(sqlite.Open(dsn), &gorm.Config{ + Logger: logger.Default.LogMode(logger.Silent), + }) + require.NoError(t, err, "open test db") + require.NoError(t, db.AutoMigrate(&models.RequestLog{}), "migrate RequestLog") + t.Cleanup(func() { + sqlDB, err := db.DB() + if err == nil && sqlDB != nil { + _ = sqlDB.Close() + } + }) + return db +} + +func makeEntry(hostID, ip, method string, status int) models.SecurityLogEntry { + return models.SecurityLogEntry{ + Timestamp: time.Now().Format(time.RFC3339), + ClientIP: ip, + Host: hostID, + Method: method, + Status: status, + Duration: 0.001, + Size: 128, + } +} + +// TestStatsIngester_BatchFlushOnCount verifies that 100 entries trigger a batch write. +func TestStatsIngester_BatchFlushOnCount(t *testing.T) { + t.Parallel() + + db := setupStatsTestDB(t) + ing := NewStatsIngester(db) + + ctx, cancel := context.WithCancel(context.Background()) + defer cancel() + + go ing.Run(ctx) + + // Send exactly 100 entries — should trigger a flush before the timer fires. + for i := 0; i < 100; i++ { + ing.ingestCh <- makeEntry("host-1", "10.0.0.1", "GET", 200) + } + + // Allow time for the batch write. + require.Eventually(t, func() bool { + var count int64 + db.Model(&models.RequestLog{}).Count(&count) + return count >= 100 + }, 3*time.Second, 50*time.Millisecond, "expected 100 rows after count-flush") +} + +// TestStatsIngester_BatchFlushOnTimer verifies that entries are flushed after 500ms. +func TestStatsIngester_BatchFlushOnTimer(t *testing.T) { + t.Parallel() + + db := setupStatsTestDB(t) + ing := NewStatsIngester(db) + + ctx, cancel := context.WithCancel(context.Background()) + defer cancel() + + go ing.Run(ctx) + + // Send fewer than 100 entries — only the timer should trigger the flush. + for i := 0; i < 5; i++ { + ing.ingestCh <- makeEntry("host-2", "10.0.0.2", "POST", 201) + } + + // Should flush within ~600ms. + require.Eventually(t, func() bool { + var count int64 + db.Model(&models.RequestLog{}).Count(&count) + return count >= 5 + }, 3*time.Second, 50*time.Millisecond, "expected 5 rows after timer-flush") +} + +// TestStatsIngester_DroppedCountIncrementsWhenFull verifies back-pressure tracking. +func TestStatsIngester_DroppedCountIncrementsWhenFull(t *testing.T) { + t.Parallel() + + db := setupStatsTestDB(t) + ing := NewStatsIngester(db) + + // Do NOT start Run — keep the channel un-drained so we can fill it. + // Fill the channel buffer completely. + for i := 0; i < channelBufferSize; i++ { + ing.ingestCh <- makeEntry("host-3", "10.0.0.3", "GET", 200) + } + + // Now send one more non-blocking — should be dropped. + select { + case ing.ingestCh <- makeEntry("host-3", "10.0.0.3", "GET", 200): + // sent; channel had room — only possible on a race (acceptable) + default: + ing.droppedCount.Add(1) + } + + // Force a drop via the exported Send path. + ing.Send(makeEntry("host-3", "10.0.0.3", "GET", 200)) + + assert.GreaterOrEqual(t, ing.DroppedCount(), int64(1)) +} + +// TestStatsIngester_StopDrainsRemainingEntries verifies graceful shutdown writes pending entries. +func TestStatsIngester_StopDrainsRemainingEntries(t *testing.T) { + t.Parallel() + + db := setupStatsTestDB(t) + ing := NewStatsIngester(db) + + ctx, cancel := context.WithCancel(context.Background()) + + var wg sync.WaitGroup + wg.Add(1) + go func() { + defer wg.Done() + ing.Run(ctx) + }() + + // Send a small batch. + for i := 0; i < 10; i++ { + ing.ingestCh <- makeEntry("host-4", "10.0.0.4", "DELETE", 204) + } + + // Cancel context and wait for Run to exit. + cancel() + wg.Wait() + + // Stop drains the channel — all pending entries should be persisted. + ing.Stop() + + var count int64 + db.Model(&models.RequestLog{}).Count(&count) + assert.GreaterOrEqual(t, count, int64(10)) +} + +// TestStatsIngester_ClientIPHashing verifies GDPR-safe pseudonymisation. +func TestStatsIngester_ClientIPHashing(t *testing.T) { + t.Parallel() + + rawIP := "192.168.1.100" + got := hashClientIP(rawIP) + + // Must be hex-encoded, 32 chars (16 bytes × 2 hex digits). + assert.Len(t, got, 32) + + // Must be consistent (deterministic). + assert.Equal(t, got, hashClientIP(rawIP)) + + // Must differ from the raw IP. + assert.NotEqual(t, rawIP, got) + + // Verify correctness against reference implementation. + sum := sha256.Sum256([]byte(rawIP)) + expected := hex.EncodeToString(sum[:16]) + assert.Equal(t, expected, got) + + // Must not be reversible (different IPs produce different hashes). + assert.NotEqual(t, got, hashClientIP("10.0.0.1")) +} + +// TestStatsIngester_RegisterHub verifies that RegisterHub does not panic and +// accepts a nil BroadcastHub (the typical case when WebSocket push is not needed). +func TestStatsIngester_RegisterHub(t *testing.T) { + t.Parallel() + + db := setupStatsTestDB(t) + ing := NewStatsIngester(db) + + // Before registration the hub field is nil. + assert.Nil(t, ing.hub, "hub should be nil before RegisterHub") + + // Passing a nil interface must not panic. + var hub BroadcastHub + ing.RegisterHub(hub) + + // After registration the field is still nil (we passed a nil interface value) + // but the method must not have panicked. + assert.Nil(t, ing.hub, "hub should remain nil after registering a nil hub") +} + +// TestStatsIngester_ToRequestLog_InvalidTimestamp verifies that an unparseable +// timestamp falls back to time.Now() without panicking. +func TestStatsIngester_ToRequestLog_InvalidTimestamp(t *testing.T) { + t.Parallel() + + before := time.Now() + entry := models.SecurityLogEntry{ + Timestamp: "not-a-valid-timestamp", + ClientIP: "127.0.0.1", + Host: "host-ts", + Method: "GET", + Status: 200, + Duration: 0.001, + Size: 64, + } + result := toRequestLog(entry) + after := time.Now() + + // Timestamp must fall back to approximately now. + assert.False(t, result.Timestamp.IsZero(), "fallback timestamp must not be zero") + assert.True(t, !result.Timestamp.Before(before) || result.Timestamp.After(before.Add(-time.Second)), + "fallback timestamp should be close to now") + assert.True(t, result.Timestamp.Before(after.Add(time.Second)), + "fallback timestamp should not be in the future") +} + +// TestStatsIngester_Stop_FlushesLargerThanBatchSize verifies that Stop correctly +// flushes in-channel entries that exceed batchSize (the internal batch-flush path). +func TestStatsIngester_Stop_FlushesLargerThanBatchSize(t *testing.T) { + t.Parallel() + + db := setupStatsTestDB(t) + ing := NewStatsIngester(db) + + // Pre-fill the channel with 150 entries (> batchSize=100) without starting Run. + // Stop must flush the first 100 via the batchSize branch, then the remaining 50 as final batch. + for i := 0; i < 150; i++ { + ing.ingestCh <- makeEntry("host-large", "10.0.0.5", "GET", 200) + } + + ing.Stop() + + var count int64 + db.Model(&models.RequestLog{}).Count(&count) + assert.Equal(t, int64(150), count, "Stop must persist all 150 entries including the batchSize-triggered flush") +} + +// TestStatsIngester_Run_DrainsBigBatchOnCancel verifies the drain path inside Run +// when the channel contains more than batchSize entries at context cancellation. +func TestStatsIngester_Run_DrainsBigBatchOnCancel(t *testing.T) { + t.Parallel() + + db := setupStatsTestDB(t) + ing := NewStatsIngester(db) + + // Pre-fill 150 entries before starting Run so they are ready to drain. + for i := 0; i < 150; i++ { + ing.ingestCh <- makeEntry("host-drain", "10.0.0.6", "GET", 200) + } + + // Use an already-cancelled context so Run enters the drain path immediately. + ctx, cancel := context.WithCancel(context.Background()) + cancel() + + ing.Run(ctx) // blocks until drain + flush complete, then returns + + var count int64 + db.Model(&models.RequestLog{}).Count(&count) + assert.GreaterOrEqual(t, count, int64(100), + "Run drain must flush at least one full batch of 100 entries") +} + +// TestStatsIngester_RegisterWithLogWatcher verifies fan-out wiring. +func TestStatsIngester_RegisterWithLogWatcher(t *testing.T) { + t.Parallel() + + db := setupStatsTestDB(t) + ing := NewStatsIngester(db) + + watcher := NewLogWatcher("/tmp/nonexistent-test.log") + watcher.RegisterIngester(ing) + + ctx, cancel := context.WithCancel(context.Background()) + defer cancel() + + go ing.Run(ctx) + + // Broadcast via the watcher — should fan-out to ingester. + entry := models.SecurityLogEntry{ + Timestamp: time.Now().Format(time.RFC3339), + ClientIP: "172.16.0.1", + Host: "fan-out-host", + Method: "GET", + Status: 200, + Duration: 0.002, + Size: 64, + } + watcher.broadcast(entry) + + require.Eventually(t, func() bool { + var count int64 + db.Model(&models.RequestLog{}).Count(&count) + return count >= 1 + }, 3*time.Second, 50*time.Millisecond, "expected 1 row after fan-out broadcast + timer flush") +} diff --git a/backend/internal/services/stats_service.go b/backend/internal/services/stats_service.go new file mode 100644 index 000000000..f54696c28 --- /dev/null +++ b/backend/internal/services/stats_service.go @@ -0,0 +1,303 @@ +package services + +import ( + "context" + "fmt" + "strings" + "sync" + "time" + + "github.com/Wikid82/charon/backend/internal/models" + "gorm.io/gorm" +) + +const ( + maxTopHostsLimit = 50 + summaryCacheTTL = 30 * time.Second + withinDaysMin = 1 + withinDaysMax = 365 +) + +// validPeriods is the allowlist for period query parameters. +var validPeriods = map[string]time.Duration{ + "24h": 24 * time.Hour, + "7d": 7 * 24 * time.Hour, + "30d": 30 * 24 * time.Hour, +} + +// validBuckets is the allowlist for traffic volume bucket parameters. +var validBuckets = map[string]time.Duration{ + "1h": time.Hour, + "6h": 6 * time.Hour, + "1d": 24 * time.Hour, +} + +// summaryCache holds a cached StatsSummary with an expiry time. +type summaryCache struct { + mu sync.Mutex + cachedValue StatsSummary + expiresAt time.Time +} + +func (c *summaryCache) get() (StatsSummary, bool) { + c.mu.Lock() + defer c.mu.Unlock() + if time.Now().Before(c.expiresAt) { + return c.cachedValue, true + } + return StatsSummary{}, false +} + +func (c *summaryCache) set(v StatsSummary, ttl time.Duration) { + c.mu.Lock() + defer c.mu.Unlock() + c.cachedValue = v + c.expiresAt = time.Now().Add(ttl) +} + +// StatsService provides aggregated query results for the dashboard API handlers. +type StatsService struct { + db *gorm.DB + cache summaryCache +} + +// NewStatsService creates a StatsService backed by the provided GORM DB. +func NewStatsService(db *gorm.DB) *StatsService { + return &StatsService{db: db} +} + +// GetSummary returns request counts for the last 24h, 7d, and 30d. +// Results are cached for 30 seconds to avoid redundant aggregation queries. +func (s *StatsService) GetSummary(ctx context.Context) (StatsSummary, error) { + if cached, ok := s.cache.get(); ok { + return cached, nil + } + + now := time.Now().UTC() + + var summary StatsSummary + type countResult struct { + Count int64 + } + + windows := []struct { + since time.Time + target *int64 + }{ + {now.Add(-24 * time.Hour), &summary.RequestsLast24h}, + {now.Add(-7 * 24 * time.Hour), &summary.RequestsLast7d}, + {now.Add(-30 * 24 * time.Hour), &summary.RequestsLast30d}, + } + + for _, w := range windows { + var res countResult + if err := s.db.WithContext(ctx). + Model(&models.RequestLog{}). + Select("COUNT(*) AS count"). + Where("timestamp >= ?", w.since). + Scan(&res).Error; err != nil { + return StatsSummary{}, fmt.Errorf("GetSummary: %w", err) + } + *w.target = res.Count + } + + s.cache.set(summary, summaryCacheTTL) + return summary, nil +} + +// GetTopHosts returns the top N hosts by request count over the given period. +// period must be one of "24h", "7d", "30d". limit is capped at 50. +func (s *StatsService) GetTopHosts(ctx context.Context, period string, limit int) ([]HostStat, error) { + dur, ok := validPeriods[period] + if !ok { + return nil, fmt.Errorf("invalid period: %s", period) + } + if limit > maxTopHostsLimit { + limit = maxTopHostsLimit + } + + since := time.Now().UTC().Add(-dur) + + var results []HostStat + if err := s.db.WithContext(ctx). + Model(&models.RequestLog{}). + Select("host_id, COUNT(*) AS count"). + Where("timestamp >= ?", since). + Group("host_id"). + Order("count DESC"). + Limit(limit). + Scan(&results).Error; err != nil { + return nil, fmt.Errorf("GetTopHosts: %w", err) + } + + nameByDomain, err := s.domainNameLookup(ctx) + if err != nil { + return nil, fmt.Errorf("GetTopHosts: %w", err) + } + + for i := range results { + if name, ok := nameByDomain[strings.ToLower(results[i].HostID)]; ok && name != "" { + results[i].Hostname = name + } else { + results[i].Hostname = results[i].HostID + } + } + + return results, nil +} + +// domainNameLookup builds a map of domain (lowercased) to proxy host display name. +// RequestLog.HostID stores the raw Host header seen by the proxy, not a ProxyHost +// UUID, and a single ProxyHost may serve several comma-separated domains — so the +// match has to happen against each individual domain rather than the host's ID. +func (s *StatsService) domainNameLookup(ctx context.Context) (map[string]string, error) { + var hosts []models.ProxyHost + if err := s.db.WithContext(ctx). + Select("name, domain_names"). + Find(&hosts).Error; err != nil { + return nil, err + } + + lookup := make(map[string]string, len(hosts)) + for _, h := range hosts { + for _, d := range strings.Split(h.DomainNames, ",") { + d = strings.ToLower(strings.TrimSpace(d)) + if d != "" { + lookup[d] = h.Name + } + } + } + return lookup, nil +} + +// GetStatusDistribution returns HTTP status code counts over the given period. +// period must be one of "24h", "7d", "30d". +func (s *StatsService) GetStatusDistribution(ctx context.Context, period string) ([]StatusStat, error) { + dur, ok := validPeriods[period] + if !ok { + return nil, fmt.Errorf("invalid period: %s", period) + } + + since := time.Now().UTC().Add(-dur) + + var results []StatusStat + if err := s.db.WithContext(ctx). + Model(&models.RequestLog{}). + Select("status_code AS code, COUNT(*) AS count"). + Where("timestamp >= ?", since). + Group("status_code"). + Order("count DESC"). + Scan(&results).Error; err != nil { + return nil, fmt.Errorf("GetStatusDistribution: %w", err) + } + + return results, nil +} + +// GetTrafficVolume returns bytes sent bucketed by time interval. +// bucket must be one of "1h", "6h", "1d". +func (s *StatsService) GetTrafficVolume(ctx context.Context, bucket string) ([]TrafficBucket, error) { + bucketDur, ok := validBuckets[bucket] + if !ok { + return nil, fmt.Errorf("invalid bucket: %s", bucket) + } + + // Determine look-back window: show the last 30 buckets. + lookback := bucketDur * 30 + since := time.Now().UTC().Add(-lookback) + + // SQLite strftime format derived from bucket size. + var fmtStr string + switch bucket { + case "1h": + fmtStr = "%Y-%m-%dT%H:00:00Z" + case "6h": + // Truncate to 6-hour blocks: hour rounded down to nearest 6. + fmtStr = "%Y-%m-%dT%H:00:00Z" // will post-process below + case "1d": + fmtStr = "%Y-%m-%dT00:00:00Z" + } + + type rawBucket struct { + Bucket string + BytesSent int64 + } + + var raw []rawBucket + + if bucket == "6h" { + // For 6h buckets, cast hour to integer, divide by 6, multiply by 6 to get the bucket start hour. + if err := s.db.WithContext(ctx). + Model(&models.RequestLog{}). + Select("strftime('%Y-%m-%dT', timestamp) || printf('%02d', (CAST(strftime('%H', timestamp) AS INTEGER) / 6) * 6) || ':00:00Z' AS bucket, SUM(bytes_sent) AS bytes_sent"). + Where("timestamp >= ?", since). + Group("bucket"). + Order("bucket ASC"). + Scan(&raw).Error; err != nil { + return nil, fmt.Errorf("GetTrafficVolume: %w", err) + } + } else { + if err := s.db.WithContext(ctx). + Model(&models.RequestLog{}). + Select("strftime(?, timestamp) AS bucket, SUM(bytes_sent) AS bytes_sent", fmtStr). + Where("timestamp >= ?", since). + Group("bucket"). + Order("bucket ASC"). + Scan(&raw).Error; err != nil { + return nil, fmt.Errorf("GetTrafficVolume: %w", err) + } + } + + results := make([]TrafficBucket, 0, len(raw)) + for _, r := range raw { + results = append(results, TrafficBucket(r)) + } + + return results, nil +} + +// GetCertExpiry returns certificates expiring within the given number of days. +// withinDays must be between 1 and 365 inclusive. +func (s *StatsService) GetCertExpiry(ctx context.Context, withinDays int) ([]CertExpiry, error) { + if withinDays < withinDaysMin || withinDays > withinDaysMax { + return nil, fmt.Errorf("withinDays must be between 1 and 365") + } + + now := time.Now().UTC() + deadline := now.Add(time.Duration(withinDays) * 24 * time.Hour) + + type joinResult struct { + HostUUID string + DomainNames string + ExpiresAt *time.Time + } + + var rows []joinResult + if err := s.db.WithContext(ctx). + Model(&models.ProxyHost{}). + Select("proxy_hosts.uuid AS host_uuid, proxy_hosts.domain_names, ssl_certificates.expires_at"). + Joins("JOIN ssl_certificates ON ssl_certificates.id = proxy_hosts.certificate_id"). + Where("ssl_certificates.expires_at IS NOT NULL"). + Where("ssl_certificates.expires_at > ?", now). + Where("ssl_certificates.expires_at <= ?", deadline). + Scan(&rows).Error; err != nil { + return nil, fmt.Errorf("GetCertExpiry: %w", err) + } + + results := make([]CertExpiry, 0, len(rows)) + for _, r := range rows { + exp := time.Time{} + if r.ExpiresAt != nil { + exp = *r.ExpiresAt + } + daysLeft := int(time.Until(exp).Hours() / 24) + results = append(results, CertExpiry{ + HostID: r.HostUUID, + Hostname: r.DomainNames, + ExpiresAt: exp, + DaysLeft: daysLeft, + }) + } + + return results, nil +} diff --git a/backend/internal/services/stats_service_test.go b/backend/internal/services/stats_service_test.go new file mode 100644 index 000000000..1f5f1c473 --- /dev/null +++ b/backend/internal/services/stats_service_test.go @@ -0,0 +1,411 @@ +package services + +import ( + "context" + "path/filepath" + "testing" + "time" + + "github.com/Wikid82/charon/backend/internal/models" + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" + "gorm.io/driver/sqlite" + "gorm.io/gorm" + "gorm.io/gorm/logger" +) + +func setupStatsServiceDB(t *testing.T) *gorm.DB { + t.Helper() + dsn := filepath.Join(t.TempDir(), "stats_service_test.db") + "?_busy_timeout=5000&_journal_mode=WAL" + db, err := gorm.Open(sqlite.Open(dsn), &gorm.Config{ + Logger: logger.Default.LogMode(logger.Silent), + }) + require.NoError(t, err) + require.NoError(t, db.AutoMigrate( + &models.RequestLog{}, + &models.SSLCertificate{}, + &models.ProxyHost{}, + )) + t.Cleanup(func() { + sqlDB, err := db.DB() + if err == nil && sqlDB != nil { + _ = sqlDB.Close() + } + }) + return db +} + +func seedRequestLogs(t *testing.T, db *gorm.DB) { + t.Helper() + now := time.Now().UTC() + + logs := []models.RequestLog{ + // within last 24h + {HostID: "host-a", Timestamp: now.Add(-1 * time.Hour), Method: "GET", StatusCode: 200, BytesSent: 100, DurationMs: 10}, + {HostID: "host-a", Timestamp: now.Add(-2 * time.Hour), Method: "POST", StatusCode: 201, BytesSent: 200, DurationMs: 20}, + {HostID: "host-b", Timestamp: now.Add(-3 * time.Hour), Method: "GET", StatusCode: 404, BytesSent: 50, DurationMs: 5}, + // within last 7d but not 24h + {HostID: "host-a", Timestamp: now.Add(-48 * time.Hour), Method: "GET", StatusCode: 500, BytesSent: 300, DurationMs: 30}, + {HostID: "host-b", Timestamp: now.Add(-72 * time.Hour), Method: "DELETE", StatusCode: 204, BytesSent: 0, DurationMs: 8}, + // within last 30d but not 7d + {HostID: "host-c", Timestamp: now.Add(-10 * 24 * time.Hour), Method: "GET", StatusCode: 200, BytesSent: 400, DurationMs: 15}, + {HostID: "host-c", Timestamp: now.Add(-20 * 24 * time.Hour), Method: "GET", StatusCode: 200, BytesSent: 500, DurationMs: 25}, + } + require.NoError(t, db.Create(&logs).Error) +} + +// TestStatsService_GetSummary verifies correct request counts per window. +func TestStatsService_GetSummary(t *testing.T) { + t.Parallel() + + db := setupStatsServiceDB(t) + seedRequestLogs(t, db) + svc := NewStatsService(db) + + summary, err := svc.GetSummary(context.Background()) + require.NoError(t, err) + + assert.Equal(t, int64(3), summary.RequestsLast24h) + assert.Equal(t, int64(5), summary.RequestsLast7d) + assert.Equal(t, int64(7), summary.RequestsLast30d) +} + +// TestStatsService_GetSummary_TTLCache verifies the cached result is returned on second call. +func TestStatsService_GetSummary_TTLCache(t *testing.T) { + t.Parallel() + + db := setupStatsServiceDB(t) + seedRequestLogs(t, db) + svc := NewStatsService(db) + + first, err := svc.GetSummary(context.Background()) + require.NoError(t, err) + + // Insert a new row — if cache is working, second call should return same result. + extra := models.RequestLog{ + HostID: "host-d", + Timestamp: time.Now().UTC().Add(-30 * time.Minute), + Method: "GET", + StatusCode: 200, + BytesSent: 10, + DurationMs: 1, + } + require.NoError(t, db.Create(&extra).Error) + + second, err := svc.GetSummary(context.Background()) + require.NoError(t, err) + + // Cache should serve the same values. + assert.Equal(t, first, second) +} + +// TestStatsService_GetTopHosts_ValidPeriod verifies top hosts ordering. +func TestStatsService_GetTopHosts_ValidPeriod(t *testing.T) { + t.Parallel() + + db := setupStatsServiceDB(t) + seedRequestLogs(t, db) + svc := NewStatsService(db) + + hosts, err := svc.GetTopHosts(context.Background(), "30d", 10) + require.NoError(t, err) + + require.NotEmpty(t, hosts) + // host-a has 3 requests in 30d, host-b has 2, host-c has 2. + assert.Equal(t, "host-a", hosts[0].HostID) + assert.Equal(t, int64(3), hosts[0].Count) +} + +// TestStatsService_GetTopHosts_InvalidPeriod verifies rejection of unknown period. +func TestStatsService_GetTopHosts_InvalidPeriod(t *testing.T) { + t.Parallel() + + db := setupStatsServiceDB(t) + svc := NewStatsService(db) + + _, err := svc.GetTopHosts(context.Background(), "99d", 10) + require.Error(t, err) + assert.Contains(t, err.Error(), "invalid period") +} + +// TestStatsService_GetTopHosts_LimitCap verifies limit is capped at 50. +func TestStatsService_GetTopHosts_LimitCap(t *testing.T) { + t.Parallel() + + db := setupStatsServiceDB(t) + seedRequestLogs(t, db) + svc := NewStatsService(db) + + // Even with limit=100, only 3 unique hosts exist — should not error. + hosts, err := svc.GetTopHosts(context.Background(), "30d", 100) + require.NoError(t, err) + assert.LessOrEqual(t, len(hosts), 50) +} + +// TestStatsService_GetTopHosts_PopulatesHostnameFromProxyHost verifies that the +// hostname is resolved from the matching proxy_hosts row (matched by domain, since +// RequestLog.HostID stores the raw Host header, not a ProxyHost UUID) rather than +// left blank. +func TestStatsService_GetTopHosts_PopulatesHostnameFromProxyHost(t *testing.T) { + t.Parallel() + + db := setupStatsServiceDB(t) + seedRequestLogs(t, db) + require.NoError(t, db.Create(&models.ProxyHost{ + UUID: "proxy-host-uuid-1", + Name: "API Server", + DomainNames: "host-a", + ForwardHost: "127.0.0.1", + ForwardPort: 8080, + }).Error) + svc := NewStatsService(db) + + hosts, err := svc.GetTopHosts(context.Background(), "30d", 10) + require.NoError(t, err) + + require.NotEmpty(t, hosts) + assert.Equal(t, "host-a", hosts[0].HostID) + assert.Equal(t, "API Server", hosts[0].Hostname) +} + +// TestStatsService_GetTopHosts_MatchesAmongMultipleCommaSeparatedDomains verifies +// that a ProxyHost serving several domains is matched correctly regardless of which +// of its domains the traffic hit, and that the match is case-insensitive. +func TestStatsService_GetTopHosts_MatchesAmongMultipleCommaSeparatedDomains(t *testing.T) { + t.Parallel() + + db := setupStatsServiceDB(t) + seedRequestLogs(t, db) + require.NoError(t, db.Create(&models.ProxyHost{ + UUID: "proxy-host-uuid-2", + Name: "FileFlows", + DomainNames: "fileflows.example.com, Host-A, other.example.com", + ForwardHost: "127.0.0.1", + ForwardPort: 8080, + }).Error) + svc := NewStatsService(db) + + hosts, err := svc.GetTopHosts(context.Background(), "30d", 10) + require.NoError(t, err) + + require.NotEmpty(t, hosts) + assert.Equal(t, "host-a", hosts[0].HostID) + assert.Equal(t, "FileFlows", hosts[0].Hostname) +} + +// TestStatsService_GetTopHosts_FallsBackToHostIDWhenHostMissing verifies that a +// host with no matching proxy_hosts row (e.g. deleted host) falls back to host_id +// instead of returning a blank hostname. +func TestStatsService_GetTopHosts_FallsBackToHostIDWhenHostMissing(t *testing.T) { + t.Parallel() + + db := setupStatsServiceDB(t) + seedRequestLogs(t, db) + svc := NewStatsService(db) + + hosts, err := svc.GetTopHosts(context.Background(), "30d", 10) + require.NoError(t, err) + + require.NotEmpty(t, hosts) + for _, h := range hosts { + assert.NotEmpty(t, h.Hostname) + assert.Equal(t, h.HostID, h.Hostname) + } +} + +// TestStatsService_GetStatusDistribution_ValidPeriod verifies status code grouping. +func TestStatsService_GetStatusDistribution_ValidPeriod(t *testing.T) { + t.Parallel() + + db := setupStatsServiceDB(t) + seedRequestLogs(t, db) + svc := NewStatsService(db) + + dist, err := svc.GetStatusDistribution(context.Background(), "30d") + require.NoError(t, err) + + require.NotEmpty(t, dist) + + // Collect all codes returned. + codes := make(map[int]int64) + for _, s := range dist { + codes[s.Code] = s.Count + } + assert.Equal(t, int64(3), codes[200]) + assert.Equal(t, int64(1), codes[201]) + assert.Equal(t, int64(1), codes[404]) + assert.Equal(t, int64(1), codes[500]) + assert.Equal(t, int64(1), codes[204]) +} + +// TestStatsService_GetStatusDistribution_InvalidPeriod verifies rejection. +func TestStatsService_GetStatusDistribution_InvalidPeriod(t *testing.T) { + t.Parallel() + + db := setupStatsServiceDB(t) + svc := NewStatsService(db) + + _, err := svc.GetStatusDistribution(context.Background(), "1y") + require.Error(t, err) + assert.Contains(t, err.Error(), "invalid period") +} + +// TestStatsService_GetTrafficVolume_ValidBucket verifies bucketed bytes_sent. +func TestStatsService_GetTrafficVolume_ValidBucket(t *testing.T) { + t.Parallel() + + db := setupStatsServiceDB(t) + seedRequestLogs(t, db) + svc := NewStatsService(db) + + buckets, err := svc.GetTrafficVolume(context.Background(), "1h") + require.NoError(t, err) + // Just verify it returns without error and each bucket has a non-empty label. + for _, b := range buckets { + assert.NotEmpty(t, b.Bucket) + assert.GreaterOrEqual(t, b.BytesSent, int64(0)) + } +} + +// TestStatsService_GetTrafficVolume_InvalidBucket verifies rejection. +func TestStatsService_GetTrafficVolume_InvalidBucket(t *testing.T) { + t.Parallel() + + db := setupStatsServiceDB(t) + svc := NewStatsService(db) + + _, err := svc.GetTrafficVolume(context.Background(), "12h") + require.Error(t, err) + assert.Contains(t, err.Error(), "invalid bucket") +} + +// TestStatsService_GetTrafficVolume_6hBucket verifies the 6-hour bucket SQL path. +func TestStatsService_GetTrafficVolume_6hBucket(t *testing.T) { + t.Parallel() + + db := setupStatsServiceDB(t) + seedRequestLogs(t, db) + svc := NewStatsService(db) + + buckets, err := svc.GetTrafficVolume(context.Background(), "6h") + require.NoError(t, err) + for _, b := range buckets { + assert.NotEmpty(t, b.Bucket) + assert.GreaterOrEqual(t, b.BytesSent, int64(0)) + } +} + +// TestStatsService_GetTrafficVolume_1dBucket verifies the 1-day bucket SQL path. +func TestStatsService_GetTrafficVolume_1dBucket(t *testing.T) { + t.Parallel() + + db := setupStatsServiceDB(t) + seedRequestLogs(t, db) + svc := NewStatsService(db) + + buckets, err := svc.GetTrafficVolume(context.Background(), "1d") + require.NoError(t, err) + for _, b := range buckets { + assert.NotEmpty(t, b.Bucket) + assert.GreaterOrEqual(t, b.BytesSent, int64(0)) + } +} + +// TestStatsService_GetSummary_DBError verifies that a closed DB returns a wrapped error. +func TestStatsService_GetSummary_DBError(t *testing.T) { + t.Parallel() + + db := setupStatsServiceDB(t) + svc := NewStatsService(db) + + sqlDB, err := db.DB() + require.NoError(t, err) + require.NoError(t, sqlDB.Close()) + + _, err = svc.GetSummary(context.Background()) + require.Error(t, err) + assert.Contains(t, err.Error(), "GetSummary") +} + +// TestStatsService_GetCertExpiry_ValidWithinDays verifies certs expiring soon are returned. +func TestStatsService_GetCertExpiry_ValidWithinDays(t *testing.T) { + t.Parallel() + + db := setupStatsServiceDB(t) + svc := NewStatsService(db) + + expiresSoon := time.Now().UTC().Add(5 * 24 * time.Hour) + expiresLater := time.Now().UTC().Add(60 * 24 * time.Hour) + + certSoon := models.SSLCertificate{ + UUID: "cert-soon", + Name: "soon.example.com", + ExpiresAt: &expiresSoon, + } + certLater := models.SSLCertificate{ + UUID: "cert-later", + Name: "later.example.com", + ExpiresAt: &expiresLater, + } + require.NoError(t, db.Create(&certSoon).Error) + require.NoError(t, db.Create(&certLater).Error) + + certID := certSoon.ID + host := models.ProxyHost{ + UUID: "host-cert-uuid", + DomainNames: "soon.example.com", + ForwardHost: "127.0.0.1", + ForwardPort: 8080, + CertificateID: &certID, + } + require.NoError(t, db.Create(&host).Error) + + results, err := svc.GetCertExpiry(context.Background(), 30) + require.NoError(t, err) + + require.NotEmpty(t, results) + found := false + for _, r := range results { + if r.HostID == host.UUID { + found = true + assert.Equal(t, "soon.example.com", r.Hostname) + assert.InDelta(t, 5, r.DaysLeft, 1) + } + } + assert.True(t, found, "expected to find cert-soon host in results") +} + +// TestStatsService_GetCertExpiry_Boundary365 verifies upper boundary is accepted. +func TestStatsService_GetCertExpiry_Boundary365(t *testing.T) { + t.Parallel() + + db := setupStatsServiceDB(t) + svc := NewStatsService(db) + + _, err := svc.GetCertExpiry(context.Background(), 365) + require.NoError(t, err) +} + +// TestStatsService_GetCertExpiry_InvalidZero verifies withinDays=0 is rejected. +func TestStatsService_GetCertExpiry_InvalidZero(t *testing.T) { + t.Parallel() + + db := setupStatsServiceDB(t) + svc := NewStatsService(db) + + _, err := svc.GetCertExpiry(context.Background(), 0) + require.Error(t, err) + assert.Contains(t, err.Error(), "withinDays must be between 1 and 365") +} + +// TestStatsService_GetCertExpiry_Invalid366 verifies withinDays=366 is rejected. +func TestStatsService_GetCertExpiry_Invalid366(t *testing.T) { + t.Parallel() + + db := setupStatsServiceDB(t) + svc := NewStatsService(db) + + _, err := svc.GetCertExpiry(context.Background(), 366) + require.Error(t, err) + assert.Contains(t, err.Error(), "withinDays must be between 1 and 365") +} diff --git a/backend/internal/services/stats_types.go b/backend/internal/services/stats_types.go new file mode 100644 index 000000000..97d5fff56 --- /dev/null +++ b/backend/internal/services/stats_types.go @@ -0,0 +1,58 @@ +// Package services provides business logic services for the application. +package services + +import "time" + +// StatsPushData holds a real-time stats snapshot for WebSocket broadcast. +type StatsPushData struct { + RequestsLast24h int64 `json:"requests_last_24h"` + RequestsLast7d int64 `json:"requests_last_7d"` + RequestsLast30d int64 `json:"requests_last_30d"` + TopHosts []HostStat `json:"top_hosts"` + StatusDist []StatusStat `json:"status_distribution"` +} + +// HostStat holds per-host request counts for the stats snapshot. +type HostStat struct { + HostID string `json:"host_id"` + Hostname string `json:"hostname"` + Count int64 `json:"count"` +} + +// StatusStat holds per-status-code request counts for the stats snapshot. +type StatusStat struct { + Code int `json:"code"` + Count int64 `json:"count"` +} + +// StatsPushMessage wraps StatsPushData for WebSocket broadcast. +type StatsPushMessage struct { + Type string `json:"type"` // always "stats_update" + Data StatsPushData `json:"data"` +} + +// BroadcastHub is the interface StatsIngester uses to push to WebSocket clients. +type BroadcastHub interface { + Broadcast(msg StatsPushMessage) +} + +// StatsSummary holds aggregated request counts over multiple time windows. +type StatsSummary struct { + RequestsLast24h int64 `json:"requests_last_24h"` + RequestsLast7d int64 `json:"requests_last_7d"` + RequestsLast30d int64 `json:"requests_last_30d"` +} + +// TrafficBucket holds bytes sent within a single time bucket. +type TrafficBucket struct { + Bucket string `json:"bucket"` // ISO 8601 truncated timestamp + BytesSent int64 `json:"bytes_sent"` +} + +// CertExpiry holds expiry metadata for a certificate attached to a proxy host. +type CertExpiry struct { + HostID string `json:"host_id"` + Hostname string `json:"hostname"` + ExpiresAt time.Time `json:"expires_at"` + DaysLeft int `json:"days_left"` +} diff --git a/docs/features.md b/docs/features.md index d7882dd82..83b2836d7 100644 --- a/docs/features.md +++ b/docs/features.md @@ -285,6 +285,22 @@ Watch requests flow through your proxy in real-time. Filter by domain, status co --- +### 📈 Dashboard Statistics + +See exactly how your sites are performing — right from the home screen. The Dashboard Statistics section shows request counts, which of your sites are busiest, how your traffic breaks down by response type, and a heads-up when any SSL certificate is getting close to its expiry date. + +**Highlights:** + +- **Live updates** — Charts refresh automatically as new traffic arrives; no manual refresh needed +- **Traffic overview** — Total requests over the last 24 hours, 7 days, and 30 days +- **Top sites** — Ranked list of your busiest proxy hosts +- **Response health** — Breakdown of successful responses versus errors at a glance +- **Cert expiry warnings** — See which certificates are expiring soon before visitors notice +- **Service health** — A single indicator showing whether stats collection is running normally +- **Privacy-safe** — Visitor IP addresses are never stored; only an anonymized fingerprint is kept + +--- + ### 🔔 Notifications Get alerted when it matters. Charon sends notifications through Discord, Gotify, Ntfy, Pushover, Slack, Email, and Custom Webhook providers. Choose a built-in JSON template or write your own to control exactly what your alerts look like. diff --git a/docs/plans/current_spec.md b/docs/plans/current_spec.md index eeee56b87..6c346d7ab 100644 --- a/docs/plans/current_spec.md +++ b/docs/plans/current_spec.md @@ -1,107 +1,310 @@ +# Technical Specification: TrafficVolumeChart Invisible Line Bug Fix + +**Version:** 1.0 +**Date:** 2026-06-17 +**Branch:** `feature/stats` +**Status:** Draft + --- -goal: Issue #579 — [Frontend] Add Auth Guard on Page Reload (root-cause verification + regression hardening) -version: 1.0 -date_created: 2026-06-09 -status: 'Approved' -tags: [fix, frontend, auth, security] + +## Table of Contents + +1. [Introduction](#introduction) +2. [Research Findings](#research-findings) +3. [Technical Specification](#technical-specification) +4. [Implementation Plan](#implementation-plan) +5. [Acceptance Criteria](#acceptance-criteria) +6. [Commit Slicing Strategy](#commit-slicing-strategy) + +--- + +## 1. Introduction + +### Overview + +The Traffic Volume widget on the Dashboard page renders a chart container with correct axes, grid lines, and a functional hover tooltip, but the line itself is completely invisible. This means users see a blank white rectangle where the traffic trend line should appear, even when data is present and the tooltip confirms values on hover. + +### Objectives + +- Identify and fix the root cause of the invisible line in `TrafficVolumeChart`. +- Add a unit test assertion that guards against regression of this specific failure mode. +- Confirm tooltip behavior is unaffected by the fix. +- Add a Playwright E2E assertion that the chart SVG contains a rendered `` element when data is present. + +### Scope + +- **In scope**: `frontend/src/components/stats/TrafficVolumeChart.tsx`, `frontend/src/components/stats/__tests__/TrafficVolumeChart.test.tsx`, `tests/stats.spec.ts`. +- **Out of scope**: Backend, other chart components, CSS design token definitions. + --- -# Issue #579 — Auth Guard on Page Reload - -Branch: `fix/authprovider` (no worktrees, per CLAUDE.md) -Scope: Frontend only. No backend/model changes (GORM scan not required). - -## Root Cause Analysis (verified 2026-06-09) - -Traced the full flow per the Context First rule: - -1. **Entry point**: page reload on a protected route (`/`). -2. **Transformation**: `frontend/src/context/AuthContext.tsx` `checkAuth()` runs on - mount. When `localStorage` has no `charon_auth_token` it clears auth state and - returns early (commit `901e824f`); when a token exists it validates it via - `fetchSessionUser()` (`GET /api/v1/auth/me`) and clears state on failure. -3. **Persistence**: token lives only in `localStorage` (`charon_auth_token`); - the axios Authorization header is mirrored via `setAuthToken()` in - `frontend/src/api/client.ts`. -4. **Exit point**: `frontend/src/components/RequireAuth.tsx` redirects to `/login` - when `isLoading` is false and either context state or the localStorage token is - missing. A global 401 interceptor in `client.ts` invokes the handler registered - by `AuthContext` via `setAuthErrorHandler()` (excluding `/auth/*` endpoints). - -**Finding**: the guard described in issue #579 is already implemented on -`development` (route-guard fix merged 2026-01-30 plus commits `901e824f`, -`6777f6e8`). The acceptance test -`tests/core/authentication.spec.ts › should redirect to login when session expires` -**passes** against a container rebuilt from current source, as do all 16 tests in -`tests/core/authentication.spec.ts` (firefox). The issue is stale with respect to -the redirect behavior itself. - -**Remaining defects/gaps (the actual work):** - -1. **Stale auth-error handler (correctness gap)**: `setAuthErrorHandler` in - `frontend/src/api/client.ts` only accepts `() => void`, and the registration - `useEffect` in `AuthContext` has no cleanup, so after `AuthProvider` unmounts - the axios interceptor keeps invoking a closure over dead state (calls - `setUser` on an unmounted component; relevant for remounts, tests, HMR). - Long-term fix: accept `(() => void) | null` and unregister on unmount. -2. **Zero unit-test regression coverage** for the guard behavior the issue is - about: there are no Vitest tests for `AuthContext` (reload paths) or - `RequireAuth` (redirect decision). The issue's own checklist requires - "Add unit tests for auth error handling". Without them the behavior can - silently regress again, which is how this issue arose. - -## Phases - -### Phase 1 — Harden auth-error handler lifecycle - -- `frontend/src/api/client.ts`: change `setAuthErrorHandler(handler: () => void)` - to `setAuthErrorHandler(handler: (() => void) | null)` (doc comment updated). -- `frontend/src/context/AuthContext.tsx`: in the registration `useEffect`, add - cleanup `return () => setAuthErrorHandler(null);`. -- No behavioral change for the running app; eliminates the stale-closure hazard. - -### Phase 2 — Regression unit tests (Vitest, jsdom) - -- **New** `frontend/src/components/__tests__/RequireAuth.test.tsx` - (render via `MemoryRouter` with `AuthContext.Provider`): - - shows `LoadingOverlay` while `isLoading` is true (no premature redirect); - - redirects to `/login` when `isAuthenticated` is false; - - redirects to `/login` when context says authenticated but - `localStorage.charon_auth_token` is absent (defense in depth); - - renders children when authenticated and token present. -- **New** `frontend/src/context/__tests__/AuthContext.test.tsx` - (mock `fetch` and the axios client module): - - reload with no stored token → no `/auth/me` call, `user=null`, - `isLoading=false`, `isAuthenticated=false`; - - reload with stored token + `/auth/me` 401 → auth token cleared, - `user=null`, `isAuthenticated=false`; - - reload with stored token + `/auth/me` 200 → user populated; - - registered auth-error handler clears `charon_auth_token` from localStorage - and resets user state; handler is unregistered (set to null) on unmount. -- **Update** `frontend/src/api/__tests__/client.test.ts`: add case asserting that - `setAuthErrorHandler(null)` unregisters (401 no longer invokes old handler). - -### Phase 3 — Validation (Definition of Done, frontend-only) - -1. E2E: `npx playwright test --project=firefox tests/core/authentication.spec.ts` - against rebuilt `charon-e2e` container — all pass. -2. Unit tests + coverage: `scripts/frontend-test-coverage.sh` (≥85%). -3. `cd frontend && npm run type-check`. -4. `cd frontend && npm run build`. -5. `lefthook run pre-commit`. - -## Commit Slicing Strategy (single PR `fix/authprovider` → `development`) - -| # | Commit | Scope | Files | Gate | -|---|--------|-------|-------|------| -| 1 | `fix(auth): unregister auth error handler on AuthProvider unmount and add reload guard regression tests` | Phase 1 + Phase 2 | `client.ts`, `AuthContext.tsx`, new/updated test files, this plan | full DoD above | - -One logical commit suffices: the production change is small and the new tests -validate it; splitting tests from the signature change would leave the first -commit without its validation gate. - -## Ignore-file review - -`.gitignore`, `.dockerignore`, `codecov.yml`: no new top-level paths introduced -(tests live in existing `__tests__` directories) — no changes required. -`Dockerfile`: unaffected. +## 2. Research Findings + +### 2.1 Component Architecture + +`TrafficVolumeChart` is a pure presentational component located at `frontend/src/components/stats/TrafficVolumeChart.tsx`. It accepts `data: TrafficBucket[] | undefined`, `isLoading: boolean`, and `bucket: StatsBucket` props. It renders via Recharts `LineChart` + `Line`. The component is consumed in `frontend/src/pages/Dashboard.tsx` at line 325. + +### 2.2 Chart Library + +The project uses **Recharts v3.8.1** (`"recharts": "^3.8.1"` in `frontend/package.json`). Recharts renders charts as inline SVG. Visual properties such as `stroke` and `fill` on components like `` and `` are passed directly as SVG presentation attributes — they are **not** resolved through the browser's CSS engine. + +### 2.3 Root Cause: Invalid SVG Color Value via CSS Variable + +The `` component in `TrafficVolumeChart.tsx` (line 135) specifies: + +```tsx +stroke="var(--color-brand-500, #6366f1)" +``` + +The CSS custom property `--color-brand-500` is defined in `frontend/src/index.css` (line 88) as: + +```css +--color-brand-500: 59 130 246; /* #3b82f6 - Primary */ +``` + +This is a **space-separated raw RGB triplet** — the design token format used by Tailwind v4's `rgb(var(--color-brand-500) / )` utility syntax. It is NOT a valid standalone CSS `` value. + +When Recharts passes `stroke="var(--color-brand-500, #6366f1)"` to the SVG DOM as a presentation attribute (not a CSS `style` property), the browser resolves `--color-brand-500` to `"59 130 246"` (the defined value), discards the `#6366f1` fallback (because the variable IS defined), and produces an invalid SVG color string `"59 130 246"`. The SVG renderer ignores invalid `stroke` values and falls back to `"none"`, making the line invisible. + +The tooltip still works because it is rendered as an HTML `
` element outside the SVG, driven by Recharts event handlers that receive the raw data regardless of visual rendering. + +### 2.4 Confirmation via Comparison + +All other working charts in the codebase use **literal hex color values** for SVG attributes: + +| Component | Color Approach | Works | +|---|---|---| +| `TopHostsChart` | `HOST_COLORS = ['#6366f1', ...]` literal hex in `` | Yes | +| `TopAttackingIPsChart` | `const BAR_COLOR = '#6366f1'` literal hex in `` | Yes | +| `BanTimelineChart` | `const BAN_COLOR = '#3b82f6'` literal hex in `` | Yes | +| `StatusDistributionChart` | `STATUS_COLORS` map with literal hex in `` | Yes | +| `TrafficVolumeChart` | `var(--color-brand-500, #6366f1)` CSS variable in `` | **Broken** | + +Note: `BanTimelineChart` uses `'#3b82f6'` which is exactly the hex equivalent of `--color-brand-500: 59 130 246`. + +### 2.5 Secondary Finding: activeDot Inherits Broken Stroke + +The `` also defines `activeDot={{ r: 4 }}` without an explicit `fill`. Recharts derives the active dot fill from the Line's `stroke`. Because the stroke is invalid, the active dot's fill is also unset, making the hover indicator invisible as well (though the tooltip div itself still appears). + +### 2.6 Existing Test Coverage Gap + +The existing test file at `frontend/src/components/stats/__tests__/TrafficVolumeChart.test.tsx` mocks `ResponsiveContainer`, `YAxis`, and `Tooltip` but does **not** mock the `Line` component. This means no test currently asserts the `stroke` prop value on ``, and the bug could not be caught by the test suite. + +### 2.7 Existing E2E Test Coverage Gap + +`tests/stats.spec.ts` includes a "Traffic Volume chart container" test (line 194) that only checks for the card heading and presence of `` elements in the page. It does not verify that the SVG contains a rendered `` element (which Recharts emits for each ``), so the invisibility bug is not caught there either. + +--- + +## 3. Technical Specification + +### 3.1 Fix Specification + +**File**: `frontend/src/components/stats/TrafficVolumeChart.tsx` + +**Change**: Replace the invalid CSS variable reference with a literal hex color constant, following the established pattern from `BanTimelineChart` and `TopAttackingIPsChart`. + +**Before** (line 135): +```tsx +stroke="var(--color-brand-500, #6366f1)" +``` + +**After**: +```tsx +stroke={LINE_COLOR} +``` + +Where `LINE_COLOR` is declared as a module-level constant above the component function: +```tsx +const LINE_COLOR = '#3b82f6' +``` + +The value `'#3b82f6'` is chosen because it is: +- The exact hex equivalent of `--color-brand-500: 59 130 246` (confirmed in `index.css` comment). +- Consistent with `BanTimelineChart`'s `BAN_COLOR = '#3b82f6'`. +- The project's primary brand color. + +No other changes to `TrafficVolumeChart.tsx` are needed. + +### 3.2 Unit Test Changes + +**File**: `frontend/src/components/stats/__tests__/TrafficVolumeChart.test.tsx` + +Extend the existing Recharts mock to also capture and expose the `` component's props for inspection: + +```tsx +// Add to the vi.mock('recharts', ...) return object: +Line: ({ stroke, strokeWidth, dataKey }: { stroke?: string; strokeWidth?: number; dataKey?: string }) => ( + +), +``` + +Add a new test case: + +```ts +it('passes a valid hex color to the Line stroke prop', () => { + render() + + const line = screen.getByTestId('line') + const stroke = line.getAttribute('data-stroke') + + // Must be a valid hex color, not a CSS variable reference + expect(stroke).toMatch(/^#[0-9a-f]{6}$/i) + expect(stroke).toBe('#3b82f6') +}) +``` + +Add a second new test case to guard against regression of tooltip behavior after the fix: + +```ts +it('tooltip renders bytes value correctly when line has valid stroke', () => { + render() + + // The mocked Tooltip fires content with 1_048_576 bytes + expect(screen.getByText(/1\.0 MB sent/i)).toBeInTheDocument() +}) +``` + +Note: The second test covers existing tooltip behavior and uses the already-mocked `Tooltip` that invokes `content?.({ active: true, payload: [{ value: 1_048_576, ... }] })`. The text "1.0 MB sent" is produced by `formatBytes(1_048_576)` + the tooltip template `{formatBytes(bytes)} sent`. This assertion was previously missing from the test suite. + +### 3.3 Playwright E2E Test Changes + +**File**: `tests/stats.spec.ts` + +Extend the existing "should render the Traffic Volume chart container" test to add a step that verifies a Recharts line path is rendered when data is available. + +New step to add within the existing test: + +```ts +await test.step('Verify SVG line path is rendered inside the chart', async () => { + // Recharts renders elements inside the svg for each Line series. + // This will only be reachable if actual traffic data exists in the E2E environment; + // guard with a conditional check similar to the certificate expiry test. + const chartCard = page.locator('text=Traffic Volume').first().locator('xpath=ancestor::*[contains(@class,"card") or @data-slot="card"][1]') + + // If the chart is showing the empty state, skip the SVG assertion + const hasEmptyState = await page.getByText(/no data available yet/i).isVisible().catch(() => false) + if (hasEmptyState) { + // Empty state is acceptable; just confirm the card is shown + await expect(page.getByText(/traffic volume/i).first()).toBeVisible() + return + } + + // When data is present, an SVG with recharts-line-curve path must exist + const svgLineCount = await page.locator('.recharts-line-curve').count() + expect(svgLineCount).toBeGreaterThan(0) +}) +``` + +The `.recharts-line-curve` CSS class is the stable Recharts class applied to the `` element of each `` series. + +--- + +## 4. Implementation Plan + +### Phase 1: Component Fix (single change, 1 file) + +**Task**: Edit `frontend/src/components/stats/TrafficVolumeChart.tsx`. + +Steps: +1. Add `const LINE_COLOR = '#3b82f6'` as a module-level constant immediately above the `formatBytes` function (consistent with the placement of `HOST_COLORS` in `TopHostsChart.tsx` and `BAR_COLOR` in `TopAttackingIPsChart.tsx`). +2. Replace the `stroke="var(--color-brand-500, #6366f1)"` JSX attribute on `` with `stroke={LINE_COLOR}`. +3. Do not modify any other props (`strokeWidth`, `dot`, `activeDot`, `type`, `dataKey`). + +**Expected result**: The line is now visible in the browser with a blue stroke matching the brand color. + +### Phase 2: Unit Test Update (1 file) + +**Task**: Edit `frontend/src/components/stats/__tests__/TrafficVolumeChart.test.tsx`. + +Steps: +1. Add `Line` to the Recharts mock in `vi.mock('recharts', ...)`, rendering a `` test element that exposes `stroke` via `data-stroke` attribute. +2. Add the `'passes a valid hex color to the Line stroke prop'` test case. +3. Add the `'tooltip renders bytes value correctly when line has valid stroke'` test case. +4. Run `cd frontend && npm test` to confirm all tests pass. + +### Phase 3: E2E Test Update (1 file) + +**Task**: Edit `tests/stats.spec.ts`. + +Steps: +1. Extend the `'should render the Traffic Volume chart container'` test with the new SVG path assertion step as specified in Section 3.3. +2. The new step is guarded by an empty-state check, so it will not fail in E2E environments with no traffic data. + +### Phase 4: Verification + +Run the full Definition of Done checklist: + +1. `cd frontend && npm run type-check` — no errors. +2. `cd frontend && npm test` — all tests pass including new assertions. +3. `npx playwright test tests/stats.spec.ts --project=firefox` — all tests pass. +4. `cd frontend && npm run build` — production build succeeds. + +--- + +## 5. Acceptance Criteria + +| # | Criterion | Verification Method | +|---|---|---| +| AC-1 | The `` stroke prop value is `'#3b82f6'` (a valid hex color) | Unit test: `data-stroke` attribute assertion | +| AC-2 | The stroke value does NOT contain `var(` or CSS variable syntax | Unit test: regex assertion `expect(stroke).toMatch(/^#[0-9a-f]{6}$/i)` | +| AC-3 | Tooltip still renders byte values correctly | Unit test: `'1.0 MB sent'` text assertion | +| AC-4 | All existing TrafficVolumeChart unit tests still pass | `npm test` — zero failures | +| AC-5 | Empty state renders correctly when data is `[]` | Existing unit test passes | +| AC-6 | Loading state renders skeleton when `isLoading=true` | Existing unit test passes | +| AC-7 | When data exists in E2E environment, `recharts-line-curve` path element is present | Playwright test step passes | +| AC-8 | `npm run type-check` passes with zero errors | TypeScript compiler | +| AC-9 | `npm run build` succeeds | Vite build | + +--- + +## 6. Commit Slicing Strategy + +**Decision**: Single PR, single commit. The fix is a two-line change (one constant, one prop swap) in one component file, with accompanying test changes in two files. Splitting this across multiple commits would add overhead without review benefit. + +### Commit 1 — Fix invisible line and add regression tests + +**Scope**: Bug fix + test coverage + +**Files changed**: +- `frontend/src/components/stats/TrafficVolumeChart.tsx` — add `LINE_COLOR` constant, replace CSS variable with literal hex on `` +- `frontend/src/components/stats/__tests__/TrafficVolumeChart.test.tsx` — add `Line` mock, add two new test cases +- `tests/stats.spec.ts` — extend Traffic Volume E2E test with SVG path assertion + +**Validation gate**: All unit tests pass, type-check passes, Playwright test passes. + +**Commit message**: +``` +fix(stats): replace invalid CSS variable with literal hex on TrafficVolumeChart Line stroke + +The prop was not working +because --color-brand-500 is defined as a space-separated RGB triplet +("59 130 246") for use with Tailwind's rgb(var(...) / alpha) syntax — +not as a valid SVG color string. Recharts passes stroke as an SVG +presentation attribute (not a CSS style), so the CSS variable resolved +to "59 130 246" which SVG treated as invalid and discarded, making the +line invisible. Tooltips continued to work because they are HTML elements. + +Fix: introduce LINE_COLOR = '#3b82f6' (the exact hex of brand-500, +consistent with BanTimelineChart's BAN_COLOR) and use it as the stroke. + +Adds unit test asserting stroke is a valid hex value and Playwright step +asserting the recharts-line-curve path is rendered when data is present. +``` + +### Rollback Notes + +This commit makes no API changes, no database changes, and no infrastructure changes. Rollback is simply reverting the single commit. There is no risk of data loss or state corruption. The only observable effect of the broken state vs the fixed state is the visual rendering of the line in the chart. + +--- + +## Appendix: File Reference Table + +| File | Role | Change Type | +|---|---|---| +| `frontend/src/components/stats/TrafficVolumeChart.tsx` | Presentational component | Bug fix | +| `frontend/src/components/stats/__tests__/TrafficVolumeChart.test.tsx` | Vitest unit tests | New test cases + mock extension | +| `tests/stats.spec.ts` | Playwright E2E tests | New assertion step | +| `frontend/src/index.css` | CSS design tokens | Read-only reference | +| `frontend/src/components/stats/TopHostsChart.tsx` | Comparison reference | No change | +| `frontend/src/components/crowdsec/BanTimelineChart.tsx` | Comparison reference | No change | diff --git a/docs/stats_feature_warmup.md b/docs/stats_feature_warmup.md new file mode 100644 index 000000000..e26a3c4e7 --- /dev/null +++ b/docs/stats_feature_warmup.md @@ -0,0 +1,124 @@ +# Enhanced Dashboard Statistics - Deployment & Warmup Guide + +## Overview +The enhanced statistics feature (Issue #25) adds real-time traffic analysis to the dashboard. When deployed, users will see new widgets: +- **Traffic Volume** - Bytes sent over time +- **Top Hosts** - Most frequently accessed domains +- **Status Distribution** - HTTP status code breakdown +- **Request Counts** - Total requests over rolling windows + +## Important: Warmup Period + +When users upgrade to this version, **the statistics widgets will be empty initially**. This is expected behavior, not a bug. + +### Why? +- Request logs are stored in a new `request_logs` database table +- The table is created automatically on first boot (via GORM AutoMigrate) +- Historical requests are not retroactively logged +- Data collection begins immediately after deployment + +### Timeline +Data will populate based on traffic and the selected bucket: + +| Bucket | Lookback Window | Time to Full Graph | +|--------|-----------------|-------------------| +| 1h | 30 hours | ~30 hours | +| 6h | 180 hours | ~7.5 days | +| 1d | 30 days | ~30 days | + +Users with active proxies will see: +- **First hour**: Initial data points appearing +- **First day**: Clear traffic patterns emerging +- **First week**: Comprehensive statistics with trends + +## For System Administrators + +### Deployment Checklist +1. ✅ Update Charon to latest version +2. ✅ Restart the backend (AutoMigrate runs automatically) +3. ✅ Verify LogWatcher started: Check logs for "Security log watcher started - stats collection enabled" +4. ✅ Inform users that stats widgets will populate over time +5. ✅ Check Stats Health endpoint: `GET /api/v1/stats/health` → should show `{"dropped_count": 0}` + +### Verification +After deployment, verify data collection is working: + +```bash +# Check request logs are being created +sqlite3 /path/to/data/charon.db "SELECT COUNT(*) FROM request_logs;" + +# Monitor LogWatcher startup logs +docker logs | grep "stats collection" +``` + +## For Users + +When you upgrade: + +1. **Stats widgets will be empty** - This is normal +2. **Data collection starts immediately** - Each request to your proxies is logged +3. **Check back soon** - Data will appear within hours as traffic flows +4. **Full picture takes time** - 30-day view needs 30 days of data + +### Example Timeline +- **Now**: Deploy Charon with stats feature +- **In 1 hour**: Traffic Volume shows first data points (1h bucket) +- **In 1 day**: Clear 24h trends visible +- **In 7 days**: Weekly patterns visible (6h bucket) +- **In 30 days**: Full 30-day statistics available (1d bucket) + +## Technical Details + +### Data Collection Pipeline +``` +Caddy Access Logs + ↓ +LogWatcher (parses JSON logs) + ↓ +StatsIngester (batches writes every 500ms) + ↓ +SQLite request_logs table + ↓ +Stats API (aggregates on-demand) + ↓ +Dashboard (displays with appropriate messaging) +``` + +### No Data Loss +- Requests are batched and flushed every 500ms +- 100-request batch flush ensures no data loss during shutdown +- Graceful context cancellation drains remaining entries +- Database backup includes all request logs + +### UI Messaging +When no data is available: +- Dashboard displays: "No data available yet" +- Helper text: "Data is being collected. Check back in a few hours..." +- Tooltip adds: "Data may take several hours to populate depending on traffic volume" + +## Troubleshooting + +### "No data available" persists after 24 hours +1. Check that LogWatcher is running: `curl localhost:5000/api/v1/stats/health` +2. Verify access log path is correct: Check `CHARON_CADDY_ACCESS_LOG` env var +3. Confirm Caddy is logging: Check `/var/log/caddy/access.log` has recent entries +4. Check database: `SELECT COUNT(*) FROM request_logs;` should be > 0 + +### Stats ingestion dropping entries +- Check: `GET /api/v1/stats/health` response +- If `dropped_count > 0`, the ingester channel buffer overflowed +- Increase `channelBufferSize` in stats_ingester.go or reduce traffic +- This is rare and indicates extreme load + +### Empty request logs +Verify all components are running: +1. LogWatcher: Logs show "stats collection enabled" +2. StatsIngester: `Go routines alive, processing incoming entries` +3. Database: `SELECT COUNT(*) FROM request_logs;` > 0 + +## Migration Notes + +- ✅ Automatic: No manual SQL needed +- ✅ Safe: Doesn't affect existing data +- ✅ Non-blocking: Won't delay server startup +- ✅ Backward compatible: Old instances continue working diff --git a/frontend/eslint.config.js b/frontend/eslint.config.js index 38b8b0a19..eb233f1b9 100644 --- a/frontend/eslint.config.js +++ b/frontend/eslint.config.js @@ -117,7 +117,6 @@ export default tseslint.config( // ── Unicorn (cherry-picked) ── 'unicorn/prefer-node-protocol': 'error', - 'unicorn/no-array-for-each': 'warn', 'unicorn/prefer-array-find': 'warn', 'unicorn/prefer-array-flat-map': 'warn', 'unicorn/prefer-array-some': 'warn', diff --git a/frontend/src/api/stats.test.ts b/frontend/src/api/stats.test.ts new file mode 100644 index 000000000..618da28de --- /dev/null +++ b/frontend/src/api/stats.test.ts @@ -0,0 +1,422 @@ +import { describe, it, expect, vi, beforeEach } from 'vitest' + +import { + getStatsSummary, + getTopHosts, + getStatusDistribution, + getTrafficVolume, + getCertExpiry, + getRequests, + getStatsHealth, + connectStatsWebSocket, + type StatsSummary, + type HostStat, + type StatusStat, + type TrafficBucket, + type CertExpiry, + type StatsHealth, + type StatsPushMessage, +} from './stats' +import client from './client' + +vi.mock('./client', () => ({ + default: { + get: vi.fn(), + }, +})) + +const mockedClient = client as unknown as { + get: ReturnType +} + +describe('stats api', () => { + beforeEach(() => { + vi.clearAllMocks() + }) + + describe('getStatsSummary', () => { + it('calls the correct endpoint', async () => { + const mockSummary: StatsSummary = { + requests_last_24h: 100, + requests_last_7d: 700, + requests_last_30d: 3000, + } + mockedClient.get.mockResolvedValueOnce({ data: mockSummary }) + + const result = await getStatsSummary() + + expect(mockedClient.get).toHaveBeenCalledWith('/stats/summary') + expect(result).toEqual(mockSummary) + expect(result.requests_last_24h).toBe(100) + expect(result.requests_last_7d).toBe(700) + expect(result.requests_last_30d).toBe(3000) + }) + + it('propagates errors', async () => { + mockedClient.get.mockRejectedValueOnce(new Error('Network error')) + + await expect(getStatsSummary()).rejects.toThrow('Network error') + }) + }) + + describe('getTopHosts', () => { + it('calls the correct endpoint with provided period and limit', async () => { + const mockHosts: HostStat[] = [ + { host_id: 'uuid-1', hostname: 'example.com', count: 500 }, + { host_id: 'uuid-2', hostname: 'api.example.com', count: 250 }, + ] + mockedClient.get.mockResolvedValueOnce({ data: mockHosts }) + + const result = await getTopHosts('7d', 5) + + expect(mockedClient.get).toHaveBeenCalledWith('/stats/top-hosts?period=7d&limit=5') + expect(result).toEqual(mockHosts) + expect(result[0].hostname).toBe('example.com') + }) + + it('uses default limit of 10 when limit is omitted', async () => { + mockedClient.get.mockResolvedValueOnce({ data: [] }) + + await getTopHosts('24h') + + expect(mockedClient.get).toHaveBeenCalledWith('/stats/top-hosts?period=24h&limit=10') + }) + + it('supports all valid periods', async () => { + mockedClient.get.mockResolvedValue({ data: [] }) + + await getTopHosts('30d') + expect(mockedClient.get).toHaveBeenCalledWith('/stats/top-hosts?period=30d&limit=10') + }) + + it('propagates errors', async () => { + mockedClient.get.mockRejectedValueOnce(new Error('Fetch failed')) + + await expect(getTopHosts('24h')).rejects.toThrow('Fetch failed') + }) + }) + + describe('getStatusDistribution', () => { + it('calls the correct endpoint with the given period', async () => { + const mockStats: StatusStat[] = [ + { code: 200, count: 900 }, + { code: 404, count: 50 }, + { code: 500, count: 10 }, + ] + mockedClient.get.mockResolvedValueOnce({ data: mockStats }) + + const result = await getStatusDistribution('7d') + + expect(mockedClient.get).toHaveBeenCalledWith('/stats/status-distribution?period=7d') + expect(result).toEqual(mockStats) + expect(result[0].code).toBe(200) + expect(result[1].count).toBe(50) + }) + + it('supports all valid periods', async () => { + mockedClient.get.mockResolvedValue({ data: [] }) + + await getStatusDistribution('24h') + expect(mockedClient.get).toHaveBeenCalledWith('/stats/status-distribution?period=24h') + + await getStatusDistribution('30d') + expect(mockedClient.get).toHaveBeenCalledWith('/stats/status-distribution?period=30d') + }) + + it('propagates errors', async () => { + mockedClient.get.mockRejectedValueOnce(new Error('Server error')) + + await expect(getStatusDistribution('7d')).rejects.toThrow('Server error') + }) + }) + + describe('getTrafficVolume', () => { + it('calls the correct endpoint with the given bucket', async () => { + const mockBuckets: TrafficBucket[] = [ + { bucket: '2024-01-01T00:00:00Z', bytes_sent: 1024000 }, + { bucket: '2024-01-01T01:00:00Z', bytes_sent: 2048000 }, + ] + mockedClient.get.mockResolvedValueOnce({ data: mockBuckets }) + + const result = await getTrafficVolume('1h') + + expect(mockedClient.get).toHaveBeenCalledWith('/stats/traffic-volume?bucket=1h') + expect(result).toEqual(mockBuckets) + expect(result[0].bytes_sent).toBe(1024000) + }) + + it('supports 6h bucket', async () => { + mockedClient.get.mockResolvedValueOnce({ data: [] }) + + await getTrafficVolume('6h') + + expect(mockedClient.get).toHaveBeenCalledWith('/stats/traffic-volume?bucket=6h') + }) + + it('supports 1d bucket', async () => { + mockedClient.get.mockResolvedValueOnce({ data: [] }) + + await getTrafficVolume('1d') + + expect(mockedClient.get).toHaveBeenCalledWith('/stats/traffic-volume?bucket=1d') + }) + + it('propagates errors', async () => { + mockedClient.get.mockRejectedValueOnce(new Error('Timeout')) + + await expect(getTrafficVolume('1h')).rejects.toThrow('Timeout') + }) + }) + + describe('getCertExpiry', () => { + it('calls the correct endpoint with provided withinDays', async () => { + const mockCerts: CertExpiry[] = [ + { + host_id: 'host-uuid-1', + hostname: 'secure.example.com', + expires_at: '2024-02-15T00:00:00Z', + days_left: 7, + }, + ] + mockedClient.get.mockResolvedValueOnce({ data: mockCerts }) + + const result = await getCertExpiry(14) + + expect(mockedClient.get).toHaveBeenCalledWith('/stats/cert-expiry?within_days=14') + expect(result).toEqual(mockCerts) + expect(result[0].days_left).toBe(7) + expect(result[0].hostname).toBe('secure.example.com') + }) + + it('uses default withinDays of 30 when omitted', async () => { + mockedClient.get.mockResolvedValueOnce({ data: [] }) + + await getCertExpiry() + + expect(mockedClient.get).toHaveBeenCalledWith('/stats/cert-expiry?within_days=30') + }) + + it('propagates errors', async () => { + mockedClient.get.mockRejectedValueOnce(new Error('Not found')) + + await expect(getCertExpiry()).rejects.toThrow('Not found') + }) + }) + + describe('getRequests', () => { + it('calls the correct endpoint with the given bucket', async () => { + const mockBuckets: TrafficBucket[] = [ + { bucket: '2024-01-01T00:00:00Z', bytes_sent: 320 }, + { bucket: '2024-01-01T06:00:00Z', bytes_sent: 480 }, + ] + mockedClient.get.mockResolvedValueOnce({ data: mockBuckets }) + + const result = await getRequests('6h') + + expect(mockedClient.get).toHaveBeenCalledWith('/stats/requests?bucket=6h') + expect(result).toEqual(mockBuckets) + expect(result[1].bucket).toBe('2024-01-01T06:00:00Z') + }) + + it('supports 1h bucket', async () => { + mockedClient.get.mockResolvedValueOnce({ data: [] }) + + await getRequests('1h') + + expect(mockedClient.get).toHaveBeenCalledWith('/stats/requests?bucket=1h') + }) + + it('supports 1d bucket', async () => { + mockedClient.get.mockResolvedValueOnce({ data: [] }) + + await getRequests('1d') + + expect(mockedClient.get).toHaveBeenCalledWith('/stats/requests?bucket=1d') + }) + + it('propagates errors', async () => { + mockedClient.get.mockRejectedValueOnce(new Error('Unauthorized')) + + await expect(getRequests('1h')).rejects.toThrow('Unauthorized') + }) + }) + + describe('getStatsHealth', () => { + it('calls the correct endpoint', async () => { + const mockHealth: StatsHealth = { dropped_count: 3 } + mockedClient.get.mockResolvedValueOnce({ data: mockHealth }) + + const result = await getStatsHealth() + + expect(mockedClient.get).toHaveBeenCalledWith('/stats/health') + expect(result).toEqual(mockHealth) + expect(result.dropped_count).toBe(3) + }) + + it('returns zero dropped_count when healthy', async () => { + const mockHealth: StatsHealth = { dropped_count: 0 } + mockedClient.get.mockResolvedValueOnce({ data: mockHealth }) + + const result = await getStatsHealth() + + expect(result.dropped_count).toBe(0) + }) + + it('propagates errors', async () => { + mockedClient.get.mockRejectedValueOnce(new Error('Service unavailable')) + + await expect(getStatsHealth()).rejects.toThrow('Service unavailable') + }) + }) + + describe('connectStatsWebSocket', () => { + let mockWs: { + onopen: (() => void) | null + onmessage: ((event: MessageEvent) => void) | null + onerror: ((event: Event) => void) | null + onclose: ((event: CloseEvent) => void) | null + close: ReturnType + readyState: number + } + + beforeEach(() => { + mockWs = { + onopen: null, + onmessage: null, + onerror: null, + onclose: null, + close: vi.fn(), + readyState: WebSocket.OPEN, + } + // Must be a vi.fn() spy wrapping a constructor so `new WebSocket(...)` works + // and vitest `toHaveBeenCalledWith` assertions succeed. + const MockWebSocket = vi.fn().mockImplementation(function () { + return mockWs + }) as ReturnType & { OPEN: number; CONNECTING: number; CLOSED: number } + // Attach the readyState constants used by connectStatsWebSocket + MockWebSocket.OPEN = 1 + MockWebSocket.CONNECTING = 0 + MockWebSocket.CLOSED = 3 + vi.stubGlobal('WebSocket', MockWebSocket) + }) + + it('connects to the correct WebSocket URL using ws: for http:', () => { + vi.stubGlobal('location', { + protocol: 'http:', + host: 'localhost:3000', + }) + + connectStatsWebSocket(vi.fn()) + + expect(WebSocket).toHaveBeenCalledWith('ws://localhost:3000/api/v1/stats/ws') + }) + + it('uses wss: when page is served over https:', () => { + vi.stubGlobal('location', { + protocol: 'https:', + host: 'proxy.example.com', + }) + + connectStatsWebSocket(vi.fn()) + + expect(WebSocket).toHaveBeenCalledWith('wss://proxy.example.com/api/v1/stats/ws') + }) + + it('invokes onMessage callback with parsed StatsPushMessage', () => { + vi.stubGlobal('location', { protocol: 'http:', host: 'localhost' }) + const onMessage = vi.fn() + + connectStatsWebSocket(onMessage) + + const msg: StatsPushMessage = { + type: 'stats_update', + data: { requests_last_24h: 10, requests_last_7d: 70, requests_last_30d: 300 }, + } + const event = { data: JSON.stringify(msg) } as MessageEvent + mockWs.onmessage?.(event) + + expect(onMessage).toHaveBeenCalledWith(msg) + }) + + it('invokes onOpen callback when connection opens', () => { + vi.stubGlobal('location', { protocol: 'http:', host: 'localhost' }) + const onOpen = vi.fn() + + connectStatsWebSocket(vi.fn(), onOpen) + mockWs.onopen?.() + + expect(onOpen).toHaveBeenCalledOnce() + }) + + it('invokes onError callback and logs on WebSocket error', () => { + vi.stubGlobal('location', { protocol: 'http:', host: 'localhost' }) + const onError = vi.fn() + const consoleSpy = vi.spyOn(console, 'error').mockImplementation(() => undefined) + + connectStatsWebSocket(vi.fn(), undefined, onError) + const event = new Event('error') + mockWs.onerror?.(event) + + expect(onError).toHaveBeenCalledWith(event) + consoleSpy.mockRestore() + }) + + it('invokes onClose callback when connection closes', () => { + vi.stubGlobal('location', { protocol: 'http:', host: 'localhost' }) + const onClose = vi.fn() + const consoleSpy = vi.spyOn(console, 'log').mockImplementation(() => undefined) + + connectStatsWebSocket(vi.fn(), undefined, undefined, onClose) + const event = new CloseEvent('close', { code: 1000, reason: 'Normal closure', wasClean: true }) + mockWs.onclose?.(event) + + expect(onClose).toHaveBeenCalledOnce() + consoleSpy.mockRestore() + }) + + it('returns a cleanup function that closes an open connection', () => { + vi.stubGlobal('location', { protocol: 'http:', host: 'localhost' }) + mockWs.readyState = WebSocket.OPEN + + const cleanup = connectStatsWebSocket(vi.fn()) + cleanup() + + expect(mockWs.close).toHaveBeenCalledOnce() + }) + + it('cleanup function closes a connecting WebSocket', () => { + vi.stubGlobal('location', { protocol: 'http:', host: 'localhost' }) + mockWs.readyState = WebSocket.CONNECTING + + const cleanup = connectStatsWebSocket(vi.fn()) + cleanup() + + expect(mockWs.close).toHaveBeenCalledOnce() + }) + + it('cleanup function does not close an already closed WebSocket', () => { + vi.stubGlobal('location', { protocol: 'http:', host: 'localhost' }) + mockWs.readyState = WebSocket.CLOSED + + const cleanup = connectStatsWebSocket(vi.fn()) + cleanup() + + expect(mockWs.close).not.toHaveBeenCalled() + }) + + it('does not invoke onMessage for malformed JSON', () => { + vi.stubGlobal('location', { protocol: 'http:', host: 'localhost' }) + const onMessage = vi.fn() + const consoleSpy = vi.spyOn(console, 'error').mockImplementation(() => undefined) + + connectStatsWebSocket(onMessage) + + const event = { data: 'not-valid-json{{{' } as MessageEvent + mockWs.onmessage?.(event) + + expect(onMessage).not.toHaveBeenCalled() + expect(consoleSpy).toHaveBeenCalled() + consoleSpy.mockRestore() + }) + }) +}) diff --git a/frontend/src/api/stats.ts b/frontend/src/api/stats.ts new file mode 100644 index 000000000..99195f0d6 --- /dev/null +++ b/frontend/src/api/stats.ts @@ -0,0 +1,180 @@ +import client from './client'; + +/** Aggregate request counts over rolling time windows. */ +export interface StatsSummary { + requests_last_24h: number; + requests_last_7d: number; + requests_last_30d: number; +} + +/** Per-host request count for a given period. */ +export interface HostStat { + host_id: string; + hostname: string; + count: number; +} + +/** HTTP status code distribution entry. */ +export interface StatusStat { + code: number; + count: number; +} + +/** Traffic volume data point for a time bucket. */ +export interface TrafficBucket { + /** ISO 8601 timestamp string marking the start of this bucket. */ + bucket: string; + bytes_sent: number; +} + +/** TLS certificate expiry information for a proxy host. */ +export interface CertExpiry { + host_id: string; + hostname: string; + /** ISO 8601 string of the certificate expiry date. */ + expires_at: string; + days_left: number; +} + +/** Stats ingestion health metrics. */ +export interface StatsHealth { + dropped_count: number; +} + +/** Rolling time window for stats queries. */ +export type StatsPeriod = '24h' | '7d' | '30d'; + +/** Bucket granularity for time-series stats queries. */ +export type StatsBucket = '1h' | '6h' | '1d'; + +/** WebSocket push message from the stats hub. */ +export interface StatsPushMessage { + type: 'stats_update'; + data: StatsSummary; +} + +/** + * Fetches aggregate request counts for the last 24h, 7d, and 30d. + * @returns Promise resolving to StatsSummary + * @throws {AxiosError} If the request fails + */ +export const getStatsSummary = async (): Promise => { + const { data } = await client.get('/stats/summary'); + return data; +}; + +/** + * Fetches the top hosts by request count for the given period. + * @param period - Rolling time window: '24h', '7d', or '30d' + * @param limit - Maximum number of hosts to return (default: 10) + * @returns Promise resolving to array of HostStat objects + * @throws {AxiosError} If the request fails + */ +export const getTopHosts = async (period: StatsPeriod, limit = 10): Promise => { + const { data } = await client.get(`/stats/top-hosts?period=${period}&limit=${limit}`); + return data; +}; + +/** + * Fetches HTTP status code distribution for the given period. + * @param period - Rolling time window: '24h', '7d', or '30d' + * @returns Promise resolving to array of StatusStat objects + * @throws {AxiosError} If the request fails + */ +export const getStatusDistribution = async (period: StatsPeriod): Promise => { + const { data } = await client.get(`/stats/status-distribution?period=${period}`); + return data; +}; + +/** + * Fetches traffic volume time-series data for the given bucket granularity. + * @param bucket - Bucket size: '1h', '6h', or '1d' + * @returns Promise resolving to array of TrafficBucket objects + * @throws {AxiosError} If the request fails + */ +export const getTrafficVolume = async (bucket: StatsBucket): Promise => { + const { data } = await client.get(`/stats/traffic-volume?bucket=${bucket}`); + return data; +}; + +/** + * Fetches TLS certificate expiry information for hosts expiring within the given window. + * @param withinDays - Number of days to look ahead (default: 30) + * @returns Promise resolving to array of CertExpiry objects + * @throws {AxiosError} If the request fails + */ +export const getCertExpiry = async (withinDays = 30): Promise => { + const { data } = await client.get(`/stats/cert-expiry?within_days=${withinDays}`); + return data; +}; + +/** + * Fetches request count time-series data for the given bucket granularity. + * @param bucket - Bucket size: '1h', '6h', or '1d' + * @returns Promise resolving to array of TrafficBucket objects + * @throws {AxiosError} If the request fails + */ +export const getRequests = async (bucket: StatsBucket): Promise => { + const { data } = await client.get(`/stats/requests?bucket=${bucket}`); + return data; +}; + +/** + * Fetches stats ingestion health metrics. + * @returns Promise resolving to StatsHealth with dropped_count + * @throws {AxiosError} If the request fails + */ +export const getStatsHealth = async (): Promise => { + const { data } = await client.get('/stats/health'); + return data; +}; + +/** + * Connects to the stats WebSocket endpoint for real-time summary updates. + * Authentication is handled via HttpOnly cookies sent automatically by the browser. + * @param onMessage - Callback invoked for each StatsPushMessage received + * @param onOpen - Optional callback when the connection is established + * @param onError - Optional callback on WebSocket error + * @param onClose - Optional callback when the connection closes + * @returns Function to close the WebSocket connection + */ +export const connectStatsWebSocket = ( + onMessage: (msg: StatsPushMessage) => void, + onOpen?: () => void, + onError?: (error: Event) => void, + onClose?: () => void +): (() => void) => { + const protocol = window.location.protocol === 'https:' ? 'wss:' : 'ws:'; + const wsUrl = `${protocol}//${window.location.host}/api/v1/stats/ws`; + + const ws = new WebSocket(wsUrl); + + ws.onopen = () => { + onOpen?.(); + }; + + ws.onmessage = (event: MessageEvent) => { + try { + const msg = JSON.parse(event.data as string) as StatsPushMessage; + onMessage(msg); + } catch (err) { + console.error('Failed to parse stats WebSocket message:', err); + } + }; + + ws.onerror = (error: Event) => { + console.error('Stats WebSocket error:', error); + onError?.(error); + }; + + ws.onclose = (event: CloseEvent) => { + console.log('Stats WebSocket closed', { code: event.code, reason: event.reason, wasClean: event.wasClean }); + onClose?.(); + }; + + return () => { + if (ws.readyState === WebSocket.OPEN || ws.readyState === WebSocket.CONNECTING) { + ws.close(); + } + }; +}; diff --git a/frontend/src/components/Layout.tsx b/frontend/src/components/Layout.tsx index 13b75fb5d..ff1997d9f 100644 --- a/frontend/src/components/Layout.tsx +++ b/frontend/src/components/Layout.tsx @@ -206,6 +206,7 @@ export default function Layout({ children }: LayoutProps) {
+ ))} +
+ ) +} diff --git a/frontend/src/components/stats/CertExpiryList.tsx b/frontend/src/components/stats/CertExpiryList.tsx new file mode 100644 index 000000000..35eba45f7 --- /dev/null +++ b/frontend/src/components/stats/CertExpiryList.tsx @@ -0,0 +1,124 @@ +import { Info, ShieldCheck } from 'lucide-react' + +import { cn } from '../../utils/cn' +import { Card, CardContent, CardHeader, CardTitle, Skeleton } from '../ui' +import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from '../ui' + +import type { CertExpiry } from '../../api/stats' + +export interface CertExpiryListProps { + data: CertExpiry[] | undefined + isLoading: boolean +} + +function formatDate(iso: string): string { + return new Intl.DateTimeFormat('en-US', { + year: 'numeric', + month: 'short', + day: 'numeric', + }).format(new Date(iso)) +} + +function urgencyClasses(daysLeft: number): { row: string; badge: string } { + if (daysLeft <= 7) { + return { row: 'bg-error/5', badge: 'text-error font-semibold' } + } + if (daysLeft <= 30) { + return { row: 'bg-warning/5', badge: 'text-warning font-semibold' } + } + return { row: '', badge: 'text-success font-semibold' } +} + +export function CertExpiryList({ data, isLoading }: CertExpiryListProps) { + return ( + + +
+
+ +
+
+ Certificate Expiry + + + + + + + SSL certificates are like ID cards for your websites — they prove your site is + safe. This shows when those ID cards expire. Red means it's urgent; renew + soon or visitors will see scary security warnings. + + + +
+
+ + + {isLoading ? ( +
+ {Array.from({ length: 4 }).map((_, i) => ( +
+ + +
+ ))} +
+ ) : (data ?? []).length === 0 ? ( +

+ No certificates expiring soon +

+ ) : ( +
+ {/* Header */} +
+ Hostname + Expires + Days left +
+ {(data ?? []).map((cert) => { + const { row, badge } = urgencyClasses(cert.days_left) + return ( +
+ + {cert.hostname} + + + {formatDate(cert.expires_at)} + + + {cert.days_left}d + +
+ ) + })} +
+ )} + + + ) +} diff --git a/frontend/src/components/stats/PeriodSelector.tsx b/frontend/src/components/stats/PeriodSelector.tsx new file mode 100644 index 000000000..6f7475bcd --- /dev/null +++ b/frontend/src/components/stats/PeriodSelector.tsx @@ -0,0 +1,44 @@ +import { cn } from '../../utils/cn' + +import type { StatsPeriod } from '../../api/stats' + +export interface PeriodSelectorProps { + value: StatsPeriod + onChange: (p: StatsPeriod) => void +} + +const PERIODS: { label: string; value: StatsPeriod }[] = [ + { label: '24h', value: '24h' }, + { label: '7d', value: '7d' }, + { label: '30d', value: '30d' }, +] + +export function PeriodSelector({ value, onChange }: PeriodSelectorProps) { + return ( +
+ {PERIODS.map((p) => ( + + ))} +
+ ) +} diff --git a/frontend/src/components/stats/RequestCountWidget.tsx b/frontend/src/components/stats/RequestCountWidget.tsx new file mode 100644 index 000000000..40731db00 --- /dev/null +++ b/frontend/src/components/stats/RequestCountWidget.tsx @@ -0,0 +1,85 @@ +import { Activity, Info } from 'lucide-react' + +import { Card, CardContent, CardHeader, CardTitle, Skeleton } from '../ui' +import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from '../ui' + +import type { StatsSummary } from '../../api/stats' + +export interface RequestCountWidgetProps { + summary: StatsSummary | undefined + isLoading: boolean +} + +interface StatItemProps { + label: string + value: number | undefined + isLoading: boolean +} + +function StatItem({ label, value, isLoading }: StatItemProps) { + return ( +
+

{label}

+ {isLoading ? ( + + ) : ( +

+ {value?.toLocaleString() ?? '—'} +

+ )} +
+ ) +} + +export function RequestCountWidget({ summary, isLoading }: RequestCountWidgetProps) { + return ( + + +
+
+ +
+
+ Request Counts + + + + + + + This counts how many times people visited your sites — like counting how many + customers walked through your door today, this week, and this month. + + + +
+
+ + +
+ + + +
+ + + ) +} diff --git a/frontend/src/components/stats/ServiceHealthWidget.tsx b/frontend/src/components/stats/ServiceHealthWidget.tsx new file mode 100644 index 000000000..2a881f638 --- /dev/null +++ b/frontend/src/components/stats/ServiceHealthWidget.tsx @@ -0,0 +1,115 @@ +import { Info, Wifi, WifiOff, AlertTriangle, CheckCircle2 } from 'lucide-react' + +import { Card, CardContent, CardHeader, CardTitle, Skeleton, Badge } from '../ui' +import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from '../ui' + +import type { StatsHealth } from '../../api/stats' + +export interface ServiceHealthWidgetProps { + health: StatsHealth | undefined + isLoading: boolean + wsConnected: boolean +} + +export function ServiceHealthWidget({ health, isLoading, wsConnected }: ServiceHealthWidgetProps) { + return ( + + +
+
+ Stats Service Health + + + + + + + This shows whether the real-time stats connection is working. A green 'Live' + dot means stats are updating instantly. If it says 'Offline', stats still + work but refresh every 30 seconds instead. + + + +
+ {!isLoading && ( + + {wsConnected ? 'Live' : 'Offline'} + + )} +
+ + + {/* WebSocket status */} +
+ {wsConnected ? ( + + ) : ( + + )} +
+

+ Real-time feed +

+

+ {wsConnected ? 'Connected via WebSocket' : 'Polling every 30 s'} +

+
+
+ + {/* Dropped count */} +
+ {isLoading ? ( + <> + +
+ + +
+ + ) : ( + <> + {(health?.dropped_count ?? 0) > 0 ? ( + + ) : ( + + )} +
+

+ Dropped events +

+

0 + ? 'text-warning' + : 'text-content-muted' + }`} + > + {health?.dropped_count ?? 0} events dropped + {(health?.dropped_count ?? 0) > 0 && ' — ingester may be overloaded'} +

+
+ + {health?.dropped_count ?? 0} + + + )} +
+ + + ) +} diff --git a/frontend/src/components/stats/StatusDistributionChart.tsx b/frontend/src/components/stats/StatusDistributionChart.tsx new file mode 100644 index 000000000..3d2d439fd --- /dev/null +++ b/frontend/src/components/stats/StatusDistributionChart.tsx @@ -0,0 +1,154 @@ +import { Info } from 'lucide-react' +import { PieChart, Pie, Cell, Tooltip, ResponsiveContainer, type TooltipContentProps } from 'recharts' + +import { Card, CardContent, CardHeader, CardTitle, Skeleton } from '../ui' +import { + Tooltip as UITooltip, + TooltipContent, + TooltipProvider, + TooltipTrigger, +} from '../ui' + +import type { StatusStat } from '../../api/stats' +import type { ValueType, NameType } from 'recharts/types/component/DefaultTooltipContent' + +export interface StatusDistributionChartProps { + data: StatusStat[] | undefined + isLoading: boolean +} + +function statusClass(code: number): string { + if (code >= 200 && code < 300) return '2xx' + if (code >= 300 && code < 400) return '3xx' + if (code >= 400 && code < 500) return '4xx' + if (code >= 500) return '5xx' + return 'other' +} + +const STATUS_COLORS: Record = { + '2xx': '#22c55e', // green + '3xx': '#3b82f6', // blue + '4xx': '#f59e0b', // amber + '5xx': '#ef4444', // red + other: '#94a3b8', // slate +} + +interface AggregatedStatus { + name: string + count: number + color: string +} + +function aggregateByClass(data: StatusStat[]): AggregatedStatus[] { + const map = new Map() + for (const s of data) { + const cls = statusClass(s.code) + map.set(cls, (map.get(cls) ?? 0) + s.count) + } + return Array.from(map.entries()).map(([name, count]) => ({ + name, + count, + color: STATUS_COLORS[name] ?? STATUS_COLORS.other, + })) +} + +export function StatusDistributionChart({ data, isLoading }: StatusDistributionChartProps) { + const chartData = aggregateByClass(data ?? []) + const total = chartData.reduce((sum, d) => sum + d.count, 0) + + return ( + + +
+ Status Distribution + + + + + + + Every time someone visits your site, the server sends back a status code — like a + thumbs up (200 OK) or a 'page not found' (404). This chart shows the mix. + Lots of green (2xx) is great; lots of red (5xx) means something needs fixing. + + + +
+ + + {isLoading ? ( +
+ +
+ ) : chartData.length === 0 ? ( +

No data available

+ ) : ( + + + + `${name} ${((percent ?? 0) * 100).toFixed(0)}%` + } + labelLine={false} + > + {chartData.map((entry) => ( + + ))} + + ) => { + const { active, payload } = props + if (!active || !payload?.length) return null + const name = payload[0]?.name + const value = payload[0]?.value + const count = typeof value === 'number' ? value : 0 + return ( +
+

{String(name ?? '')}

+

+ {count.toLocaleString()} ({total > 0 ? ((count / total) * 100).toFixed(1) : 0}%) Requests +

+
+ ) + }} + /> + + + )} + {/* Accessible status summary — renders as HTML so screen readers and tests can read it */} + {!isLoading && chartData.length > 0 && ( +
    + {chartData.map((d) => ( +
  • +
    • + ))} +
+ )} + + + ) +} diff --git a/frontend/src/components/stats/TopHostsChart.tsx b/frontend/src/components/stats/TopHostsChart.tsx new file mode 100644 index 000000000..a3965e769 --- /dev/null +++ b/frontend/src/components/stats/TopHostsChart.tsx @@ -0,0 +1,158 @@ +import { Info } from 'lucide-react' +import { + BarChart, + Bar, + Cell, + XAxis, + YAxis, + CartesianGrid, + Tooltip, + ResponsiveContainer, + type TooltipContentProps, +} from 'recharts' + +import { Card, CardContent, CardHeader, CardTitle, Skeleton } from '../ui' +import { Tooltip as UITooltip, TooltipContent, TooltipProvider, TooltipTrigger } from '../ui' + +import type { HostStat } from '../../api/stats' +import type { ValueType, NameType } from 'recharts/types/component/DefaultTooltipContent' + +export interface TopHostsChartProps { + data: HostStat[] | undefined + isLoading: boolean +} + +const MAX_LABEL_LEN = 24 + +const HOST_COLORS = [ + '#6366f1', + '#22c55e', + '#f59e0b', + '#ef4444', + '#3b82f6', + '#a855f7', + '#14b8a6', + '#f97316', +] + +function truncate(hostname: string): string { + return hostname.length > MAX_LABEL_LEN + ? `${hostname.slice(0, MAX_LABEL_LEN - 1)}…` + : hostname +} + +export function TopHostsChart({ data, isLoading }: TopHostsChartProps) { + const chartData = (data ?? []).map((h, i) => ({ + ...h, + label: truncate(h.hostname), + color: HOST_COLORS[i % HOST_COLORS.length], + })) + + return ( + + +
+ Top Hosts + + + + + + + This shows which of your sites get the most visitors. Think of it like a popularity + contest — the longer the bar, the busier that site is. + + + +
+ + + {isLoading ? ( +
+ {Array.from({ length: 5 }).map((_, i) => ( + + ))} +
+ ) : chartData.length === 0 ? ( +

No data available

+ ) : ( + <> + + + + + + ) => { + const { active, payload, label } = props + if (!active || !payload?.length) return null + const hostname = + (payload[0]?.payload as { hostname?: string })?.hostname ?? String(label) + const count = payload[0]?.value + return ( +
+

{hostname}

+

+ {typeof count === 'number' + ? count.toLocaleString() + : String(count ?? '')}{' '} + Requests +

+
+ ) + }} + /> + + {chartData.map((entry, index) => ( + + ))} + + + + +
    + {chartData.map((entry) => ( +
  • +
    • + ))} +
+ + )} + + + ) +} diff --git a/frontend/src/components/stats/TrafficVolumeChart.tsx b/frontend/src/components/stats/TrafficVolumeChart.tsx new file mode 100644 index 000000000..ed332b5b8 --- /dev/null +++ b/frontend/src/components/stats/TrafficVolumeChart.tsx @@ -0,0 +1,148 @@ +import { Info } from 'lucide-react' +import { + LineChart, + Line, + XAxis, + YAxis, + CartesianGrid, + Tooltip, + ResponsiveContainer, + type TooltipContentProps, +} from 'recharts' + +import { Card, CardContent, CardHeader, CardTitle, Skeleton } from '../ui' +import { + Tooltip as UITooltip, + TooltipContent, + TooltipProvider, + TooltipTrigger, +} from '../ui' + +import type { TrafficBucket, StatsBucket } from '../../api/stats' +import type { ValueType, NameType } from 'recharts/types/component/DefaultTooltipContent' + +const LINE_COLOR = '#3b82f6' + +export interface TrafficVolumeChartProps { + data: TrafficBucket[] | undefined + isLoading: boolean + bucket: StatsBucket +} + +function formatBytes(bytes: number): string { + if (bytes >= 1_048_576) return `${(bytes / 1_048_576).toFixed(1)} MB` + if (bytes >= 1_024) return `${(bytes / 1_024).toFixed(1)} KB` + return `${bytes} B` +} + +function formatTimestamp(iso: string, bucket: StatsBucket): string { + const date = new Date(iso) + if (bucket === '1d') { + return new Intl.DateTimeFormat('en-US', { month: 'short', day: 'numeric' }).format(date) + } + return new Intl.DateTimeFormat('en-US', { + hour: '2-digit', + minute: '2-digit', + hour12: false, + }).format(date) +} + +export function TrafficVolumeChart({ data, isLoading, bucket }: TrafficVolumeChartProps) { + const chartData = (data ?? []).map((d) => ({ + ...d, + label: formatTimestamp(d.bucket, bucket), + })) + + return ( + + +
+ Traffic Volume + + + + + + +

+ This shows how much data your sites sent over time — like checking how much water + flowed through a pipe. A big spike means lots of visitors or large files being + downloaded. +

+ {chartData.length === 0 && ( +

+ Data is being collected. It may take several hours to populate depending on traffic volume. +

+ )} + + + +
+ + + {isLoading ? ( +
+ +
+ ) : chartData.length === 0 ? ( +
+

No data available yet

+

+ Data is being collected. Check back in a few hours as traffic flows through your proxy. +

+
+ ) : ( + + + + + + ) => { + const { active, payload, label } = props + if (!active || !payload?.length) return null + const value = payload[0]?.value + const bytes = typeof value === 'number' ? value : 0 + return ( +
+

Time: {String(label ?? '')}

+

{formatBytes(bytes)} sent

+
+ ) + }} + /> + + + + )} + + + ) +} diff --git a/frontend/src/components/stats/__tests__/BucketSelector.test.tsx b/frontend/src/components/stats/__tests__/BucketSelector.test.tsx new file mode 100644 index 000000000..17a4dd225 --- /dev/null +++ b/frontend/src/components/stats/__tests__/BucketSelector.test.tsx @@ -0,0 +1,69 @@ +import { render, screen } from '@testing-library/react' +import userEvent from '@testing-library/user-event' +import { describe, it, expect, vi } from 'vitest' + +import { BucketSelector } from '../BucketSelector' + +describe('BucketSelector', () => { + it('renders all three bucket options', () => { + render() + + expect(screen.getByText('1h')).toBeInTheDocument() + expect(screen.getByText('6h')).toBeInTheDocument() + expect(screen.getByText('1d')).toBeInTheDocument() + }) + + it('marks the active bucket as checked', () => { + render() + + expect(screen.getByText('6h')).toHaveAttribute('aria-checked', 'true') + expect(screen.getByText('1h')).toHaveAttribute('aria-checked', 'false') + expect(screen.getByText('1d')).toHaveAttribute('aria-checked', 'false') + }) + + it('calls onChange with "1h" when 1h button is clicked', async () => { + const user = userEvent.setup() + const onChange = vi.fn() + render() + + await user.click(screen.getByText('1h')) + + expect(onChange).toHaveBeenCalledExactlyOnceWith('1h') + }) + + it('calls onChange with "6h" when 6h button is clicked', async () => { + const user = userEvent.setup() + const onChange = vi.fn() + render() + + await user.click(screen.getByText('6h')) + + expect(onChange).toHaveBeenCalledWith('6h') + }) + + it('calls onChange with "1d" when 1d button is clicked', async () => { + const user = userEvent.setup() + const onChange = vi.fn() + render() + + await user.click(screen.getByText('1d')) + + expect(onChange).toHaveBeenCalledWith('1d') + }) + + it('renders a group with accessible label', () => { + render() + + expect(screen.getByRole('group', { name: 'Select bucket granularity' })).toBeInTheDocument() + }) + + it('all buttons are keyboard accessible as radio roles', () => { + render() + + const buttons = screen.getAllByRole('radio') + expect(buttons).toHaveLength(3) + for (const btn of buttons) { + expect(btn.tagName).toBe('BUTTON') + } + }) +}) diff --git a/frontend/src/components/stats/__tests__/CertExpiryList.test.tsx b/frontend/src/components/stats/__tests__/CertExpiryList.test.tsx new file mode 100644 index 000000000..5df4b4cdd --- /dev/null +++ b/frontend/src/components/stats/__tests__/CertExpiryList.test.tsx @@ -0,0 +1,123 @@ +import { render, screen } from '@testing-library/react' +import { describe, it, expect } from 'vitest' + +import { CertExpiryList } from '../CertExpiryList' + +import type { CertExpiry } from '../../../api/stats' + +const mockCerts: CertExpiry[] = [ + { + host_id: 'h1', + hostname: 'critical.example.com', + expires_at: '2024-01-10T00:00:00Z', + days_left: 3, + }, + { + host_id: 'h2', + hostname: 'warning.example.com', + expires_at: '2024-01-25T00:00:00Z', + days_left: 20, + }, + { + host_id: 'h3', + hostname: 'healthy.example.com', + expires_at: '2024-03-01T00:00:00Z', + days_left: 60, + }, +] + +describe('CertExpiryList', () => { + it('renders loading skeletons when isLoading is true', () => { + render() + + expect(screen.queryByText('critical.example.com')).not.toBeInTheDocument() + expect(screen.getByText('Certificate Expiry')).toBeInTheDocument() + }) + + it('renders empty state when data is empty', () => { + render() + + expect(screen.getByText('No certificates expiring soon')).toBeInTheDocument() + }) + + it('renders hostnames when data is present', () => { + render() + + expect(screen.getByText('critical.example.com')).toBeInTheDocument() + expect(screen.getByText('warning.example.com')).toBeInTheDocument() + expect(screen.getByText('healthy.example.com')).toBeInTheDocument() + }) + + it('shows days left for each cert', () => { + render() + + expect(screen.getByText('3d')).toBeInTheDocument() + expect(screen.getByText('20d')).toBeInTheDocument() + expect(screen.getByText('60d')).toBeInTheDocument() + }) + + it('applies red class for certs expiring in ≤7 days', () => { + render() + + const redBadge = screen.getByText('3d') + expect(redBadge).toHaveClass('text-error') + }) + + it('applies amber class for certs expiring in ≤30 days but >7 days', () => { + render() + + const amberBadge = screen.getByText('20d') + expect(amberBadge).toHaveClass('text-warning') + }) + + it('applies green class for certs expiring in >30 days', () => { + render() + + const greenBadge = screen.getByText('60d') + expect(greenBadge).toHaveClass('text-success') + }) + + it('renders exactly at the 7-day boundary as red', () => { + const certs: CertExpiry[] = [ + { host_id: 'h1', hostname: 'edge.example.com', expires_at: '2024-01-08T00:00:00Z', days_left: 7 }, + ] + render() + + expect(screen.getByText('7d')).toHaveClass('text-error') + }) + + it('renders exactly at the 30-day boundary as amber', () => { + const certs: CertExpiry[] = [ + { host_id: 'h1', hostname: 'edge.example.com', expires_at: '2024-02-10T00:00:00Z', days_left: 30 }, + ] + render() + + expect(screen.getByText('30d')).toHaveClass('text-warning') + }) + + it('renders table structure with role attributes', () => { + render() + + expect(screen.getByRole('table')).toBeInTheDocument() + expect(screen.getAllByRole('row').length).toBeGreaterThan(1) + }) + + it('renders card title', () => { + render() + + expect(screen.getByText('Certificate Expiry')).toBeInTheDocument() + }) + + it('renders empty state when data is undefined and not loading', () => { + // Covers the (data ?? []).length === 0 branch when data is undefined. + render() + + expect(screen.getByText('No certificates expiring soon')).toBeInTheDocument() + }) + + it('renders info tooltip trigger button', () => { + render() + + expect(screen.getByRole('button', { name: 'About this widget' })).toBeInTheDocument() + }) +}) diff --git a/frontend/src/components/stats/__tests__/PeriodSelector.test.tsx b/frontend/src/components/stats/__tests__/PeriodSelector.test.tsx new file mode 100644 index 000000000..9dc2008f7 --- /dev/null +++ b/frontend/src/components/stats/__tests__/PeriodSelector.test.tsx @@ -0,0 +1,69 @@ +import { render, screen } from '@testing-library/react' +import userEvent from '@testing-library/user-event' +import { describe, it, expect, vi } from 'vitest' + +import { PeriodSelector } from '../PeriodSelector' + +describe('PeriodSelector', () => { + it('renders all three period options', () => { + render() + + expect(screen.getByText('24h')).toBeInTheDocument() + expect(screen.getByText('7d')).toBeInTheDocument() + expect(screen.getByText('30d')).toBeInTheDocument() + }) + + it('marks the active period as checked', () => { + render() + + expect(screen.getByText('7d')).toHaveAttribute('aria-checked', 'true') + expect(screen.getByText('24h')).toHaveAttribute('aria-checked', 'false') + expect(screen.getByText('30d')).toHaveAttribute('aria-checked', 'false') + }) + + it('calls onChange with "24h" when 24h button is clicked', async () => { + const user = userEvent.setup() + const onChange = vi.fn() + render() + + await user.click(screen.getByText('24h')) + + expect(onChange).toHaveBeenCalledExactlyOnceWith('24h') + }) + + it('calls onChange with "7d" when 7d button is clicked', async () => { + const user = userEvent.setup() + const onChange = vi.fn() + render() + + await user.click(screen.getByText('7d')) + + expect(onChange).toHaveBeenCalledWith('7d') + }) + + it('calls onChange with "30d" when 30d button is clicked', async () => { + const user = userEvent.setup() + const onChange = vi.fn() + render() + + await user.click(screen.getByText('30d')) + + expect(onChange).toHaveBeenCalledWith('30d') + }) + + it('renders a group with accessible label', () => { + render() + + expect(screen.getByRole('group', { name: 'Select time period' })).toBeInTheDocument() + }) + + it('all buttons are keyboard accessible (type=button)', () => { + render() + + const buttons = screen.getAllByRole('radio') + expect(buttons).toHaveLength(3) + for (const btn of buttons) { + expect(btn.tagName).toBe('BUTTON') + } + }) +}) diff --git a/frontend/src/components/stats/__tests__/RequestCountWidget.test.tsx b/frontend/src/components/stats/__tests__/RequestCountWidget.test.tsx new file mode 100644 index 000000000..f3d73873c --- /dev/null +++ b/frontend/src/components/stats/__tests__/RequestCountWidget.test.tsx @@ -0,0 +1,59 @@ +import { render, screen } from '@testing-library/react' +import { describe, it, expect } from 'vitest' + +import { RequestCountWidget } from '../RequestCountWidget' + +import type { StatsSummary } from '../../../api/stats' + +const mockSummary: StatsSummary = { + requests_last_24h: 1234, + requests_last_7d: 8765, + requests_last_30d: 42000, +} + +describe('RequestCountWidget', () => { + it('renders loading skeletons when isLoading is true', () => { + render() + + expect(screen.getByText('Last 24h')).toBeInTheDocument() + expect(screen.getByText('Last 7 days')).toBeInTheDocument() + expect(screen.getByText('Last 30 days')).toBeInTheDocument() + // Values should not be present (skeletons instead) + expect(screen.queryByText('1,234')).not.toBeInTheDocument() + }) + + it('renders stat values when data is provided', () => { + render() + + expect(screen.getByText('1,234')).toBeInTheDocument() + expect(screen.getByText('8,765')).toBeInTheDocument() + expect(screen.getByText('42,000')).toBeInTheDocument() + }) + + it('renders em-dash when summary is undefined and not loading', () => { + render() + + const dashes = screen.getAllByText('—') + expect(dashes).toHaveLength(3) + }) + + it('renders card title', () => { + render() + + expect(screen.getByText('Request Counts')).toBeInTheDocument() + }) + + it('renders all three period labels', () => { + render() + + expect(screen.getByText('Last 24h')).toBeInTheDocument() + expect(screen.getByText('Last 7 days')).toBeInTheDocument() + expect(screen.getByText('Last 30 days')).toBeInTheDocument() + }) + + it('renders info tooltip trigger button', () => { + render() + + expect(screen.getByRole('button', { name: 'About this widget' })).toBeInTheDocument() + }) +}) diff --git a/frontend/src/components/stats/__tests__/ServiceHealthWidget.test.tsx b/frontend/src/components/stats/__tests__/ServiceHealthWidget.test.tsx new file mode 100644 index 000000000..fae2ce9a8 --- /dev/null +++ b/frontend/src/components/stats/__tests__/ServiceHealthWidget.test.tsx @@ -0,0 +1,80 @@ +import { render, screen } from '@testing-library/react' +import { describe, it, expect } from 'vitest' + +import { ServiceHealthWidget } from '../ServiceHealthWidget' + +import type { StatsHealth } from '../../../api/stats' + +const healthOk: StatsHealth = { dropped_count: 0 } +const healthDegraded: StatsHealth = { dropped_count: 12 } + +describe('ServiceHealthWidget', () => { + it('renders card title', () => { + render() + + expect(screen.getByText('Stats Service Health')).toBeInTheDocument() + }) + + it('shows Live badge when WebSocket is connected', () => { + render() + + expect(screen.getByText('Live')).toBeInTheDocument() + }) + + it('shows Offline badge when WebSocket is disconnected', () => { + render() + + expect(screen.getByText('Offline')).toBeInTheDocument() + }) + + it('shows polling message when not connected via WebSocket', () => { + render() + + expect(screen.getByText('Polling every 30 s')).toBeInTheDocument() + }) + + it('shows connected message when WebSocket is live', () => { + render() + + expect(screen.getByText('Connected via WebSocket')).toBeInTheDocument() + }) + + it('shows 0 dropped events when health is ok', () => { + render() + + expect(screen.getByText('0 events dropped')).toBeInTheDocument() + }) + + it('shows warning message when dropped_count > 0', () => { + render() + + expect(screen.getByText(/12 events dropped/)).toBeInTheDocument() + expect(screen.getByText(/ingester may be overloaded/)).toBeInTheDocument() + }) + + it('shows dropped count in the metric display', () => { + render() + + expect(screen.getByLabelText('12 dropped')).toBeInTheDocument() + }) + + it('renders loading skeletons when isLoading is true', () => { + render() + + // Badge should not be rendered while loading + expect(screen.queryByText('Live')).not.toBeInTheDocument() + expect(screen.queryByText('Offline')).not.toBeInTheDocument() + }) + + it('falls back to 0 when health is undefined', () => { + render() + + expect(screen.getByText('0 events dropped')).toBeInTheDocument() + }) + + it('renders info tooltip trigger button', () => { + render() + + expect(screen.getByRole('button', { name: 'About this widget' })).toBeInTheDocument() + }) +}) diff --git a/frontend/src/components/stats/__tests__/StatusDistributionChart.test.tsx b/frontend/src/components/stats/__tests__/StatusDistributionChart.test.tsx new file mode 100644 index 000000000..04f32a50e --- /dev/null +++ b/frontend/src/components/stats/__tests__/StatusDistributionChart.test.tsx @@ -0,0 +1,119 @@ +import { render, screen } from '@testing-library/react' +import { describe, it, expect, vi } from 'vitest' + +import { StatusDistributionChart } from '../StatusDistributionChart' + +import type { StatusStat } from '../../../api/stats' + +vi.mock('recharts', async () => { + const Original = await vi.importActual('recharts') + return { + ...Original, + ResponsiveContainer: ({ children }: { children: React.ReactNode }) => ( +
{children}
+ ), + // Call label and content callbacks during render to cover those code paths. + Pie: ({ + label, + children, + }: { + label?: (props: { name: string; percent?: number }) => React.ReactNode + children?: React.ReactNode + }) => ( + + {label?.({ name: 'mock', percent: undefined })} + {label?.({ name: '2xx', percent: 0.8 })} + {children} + + ), + Tooltip: ({ + content, + }: { + content?: (props: object) => React.ReactNode + }) => ( +
+ {content?.({ active: true, payload: [{ name: '2xx', value: 100, payload: {} }] })} + {content?.({ active: true, payload: [{ name: '5xx', value: 'not-a-number', payload: {} }] })} + {content?.({ active: false, payload: [] })} +
+ ), + } +}) + +const mockStatuses: StatusStat[] = [ + { code: 200, count: 800 }, + { code: 201, count: 50 }, + { code: 301, count: 30 }, + { code: 404, count: 60 }, + { code: 500, count: 10 }, +] + +describe('StatusDistributionChart', () => { + it('renders loading state when isLoading is true', () => { + render() + + expect(screen.queryByTestId('responsive-container')).not.toBeInTheDocument() + }) + + it('renders empty state when data is empty', () => { + render() + + expect(screen.getByText('No data available')).toBeInTheDocument() + }) + + it('renders chart title', () => { + render() + + expect(screen.getByText('Status Distribution')).toBeInTheDocument() + }) + + it('renders chart when data is present', () => { + render() + + expect(screen.getByTestId('responsive-container')).toBeInTheDocument() + }) + + it('aggregates codes into status class groups and renders chart', () => { + render() + + // Chart renders when there is aggregated data + expect(screen.getByTestId('responsive-container')).toBeInTheDocument() + }) + + it('renders all status classes present in data', () => { + const allClasses: StatusStat[] = [ + { code: 200, count: 100 }, + { code: 302, count: 20 }, + { code: 403, count: 15 }, + { code: 503, count: 5 }, + ] + render() + + // Chart should render because all status classes are represented + expect(screen.getByTestId('responsive-container')).toBeInTheDocument() + }) + + it('renders status summary list with class names', () => { + render() + + // Status summary list renders accessible text for each class + expect(screen.getByText(/2xx/)).toBeInTheDocument() + expect(screen.getByText(/3xx/)).toBeInTheDocument() + expect(screen.getByText(/4xx/)).toBeInTheDocument() + expect(screen.getByText(/5xx/)).toBeInTheDocument() + }) + + it('classifies status codes below 200 as "other"', () => { + // 1xx codes fall into the "other" bucket — covers the final return branch in statusClass. + const withInfoStatus: StatusStat[] = [{ code: 101, count: 5 }] + render() + expect(screen.getByTestId('responsive-container')).toBeInTheDocument() + expect(screen.getByText(/other/)).toBeInTheDocument() + }) + + it('renders info tooltip trigger button', () => { + render() + + expect(screen.getByRole('button', { name: 'About this widget' })).toBeInTheDocument() + }) +}) diff --git a/frontend/src/components/stats/__tests__/TopHostsChart.test.tsx b/frontend/src/components/stats/__tests__/TopHostsChart.test.tsx new file mode 100644 index 000000000..6853d5314 --- /dev/null +++ b/frontend/src/components/stats/__tests__/TopHostsChart.test.tsx @@ -0,0 +1,144 @@ +import { render, screen } from '@testing-library/react' +import { describe, it, expect, vi } from 'vitest' + +import { TopHostsChart } from '../TopHostsChart' + +import type { HostStat } from '../../../api/stats' + +vi.mock('recharts', async () => { + const Original = await vi.importActual('recharts') + return { + ...Original, + ResponsiveContainer: ({ children }: { children: React.ReactNode }) => ( +
{children}
+ ), + // Call content callback to cover tooltip render paths including the hostname fallback. + Tooltip: ({ + content, + }: { + content?: (props: object) => React.ReactNode + }) => ( +
+ {/* With explicit hostname in payload — primary path */} + {content?.({ + active: true, + payload: [{ value: 500, payload: { hostname: 'api.example.com' } }], + label: 'api.example.com', + })} + {/* Without hostname in payload — exercises the ?? String(label) fallback */} + {content?.({ + active: true, + payload: [{ value: 300, payload: {} }], + label: 'fallback-host', + })} + {/* count is not a number — exercises String(count) branch */} + {content?.({ + active: true, + payload: [{ value: undefined, payload: { hostname: 'host' } }], + label: '', + })} + {content?.({ active: false, payload: [] })} +
+ ), + } +}) + +const mockHosts: HostStat[] = [ + { host_id: 'h1', hostname: 'api.example.com', count: 500 }, + { host_id: 'h2', hostname: 'www.example.com', count: 300 }, +] + +describe('TopHostsChart', () => { + it('renders loading skeletons when isLoading is true', () => { + render() + + expect(screen.queryByTestId('responsive-container')).not.toBeInTheDocument() + }) + + it('renders empty state when data is empty', () => { + render() + + expect(screen.getByText('No data available')).toBeInTheDocument() + }) + + it('renders chart title', () => { + render() + + expect(screen.getByText('Top Hosts')).toBeInTheDocument() + }) + + it('renders responsive container when data is present', () => { + render() + + expect(screen.getByTestId('responsive-container')).toBeInTheDocument() + }) + + it('truncates long hostnames to 24 characters', () => { + const longHostname = 'a'.repeat(30) + '.example.com' + render( + , + ) + + // The chart renders but truncation is applied at the data level + expect(screen.getByTestId('responsive-container')).toBeInTheDocument() + }) + + it('renders a color legend with different background colors per host', () => { + render() + + const legend = screen.getByRole('list', { name: 'Host color legend' }) + const dots = legend.querySelectorAll('[aria-hidden="true"]') + expect(dots.length).toBe(2) + + const colors = Array.from(dots).map(dot => (dot as HTMLElement).style.backgroundColor) + // Each host should have a distinct color + expect(colors[0]).not.toBe(colors[1]) + // Colors should be set (non-empty) + expect(colors[0]).toBeTruthy() + expect(colors[1]).toBeTruthy() + }) + + it('renders the color legend with host names', () => { + render() + + const legend = screen.getByRole('list', { name: 'Host color legend' }) + expect(legend).toBeInTheDocument() + + expect(legend).toHaveTextContent('api.example.com') + expect(legend).toHaveTextContent('www.example.com') + }) + + it('does not render the color legend when data is empty', () => { + render() + + expect(screen.queryByRole('list', { name: 'Host color legend' })).not.toBeInTheDocument() + }) + + it('wraps colors cyclically for more than 8 hosts', () => { + const manyHosts: HostStat[] = Array.from({ length: 10 }, (_, i) => ({ + host_id: `h${i}`, + hostname: `host${i}.example.com`, + count: 100 - i, + })) + + render() + + const legend = screen.getByRole('list', { name: 'Host color legend' }) + const dots = legend.querySelectorAll('[aria-hidden="true"]') + expect(dots.length).toBe(10) + + // Index 0 and 8 should share the same color (8 % 8 = 0) + const color0 = (dots[0] as HTMLElement).style.backgroundColor + const color8 = (dots[8] as HTMLElement).style.backgroundColor + expect(color0).toBe(color8) + }) + + it('renders info tooltip trigger button', () => { + render() + + expect(screen.getByRole('button', { name: 'About this widget' })).toBeInTheDocument() + }) +}) diff --git a/frontend/src/components/stats/__tests__/TrafficVolumeChart.test.tsx b/frontend/src/components/stats/__tests__/TrafficVolumeChart.test.tsx new file mode 100644 index 000000000..3a516d3b9 --- /dev/null +++ b/frontend/src/components/stats/__tests__/TrafficVolumeChart.test.tsx @@ -0,0 +1,110 @@ +import { render, screen } from '@testing-library/react' +import { describe, it, expect, vi } from 'vitest' + +import { TrafficVolumeChart } from '../TrafficVolumeChart' + +import type { TrafficBucket } from '../../../api/stats' + +vi.mock('recharts', async () => { + const Original = await vi.importActual('recharts') + return { + ...Original, + ResponsiveContainer: ({ children }: { children: React.ReactNode }) => ( +
{children}
+ ), + // Expose Line props via data attributes for stroke regression testing. + Line: ({ stroke, strokeWidth, dataKey }: { stroke?: string; strokeWidth?: number; dataKey?: string }) => ( + + ), + // Call tickFormatter and content callbacks to cover formatBytes and tooltip paths. + YAxis: ({ tickFormatter }: { tickFormatter?: (value: number) => string }) => ( + + {/* Exercise all three formatBytes branches: MB, KB, B */} + {tickFormatter?.(2_097_152)} + {tickFormatter?.(2_048)} + {tickFormatter?.(500)} + + ), + Tooltip: ({ + content, + }: { + content?: (props: object) => React.ReactNode + }) => ( +
+ {content?.({ + active: true, + payload: [{ value: 1_048_576, payload: {} }], + label: '10:00', + })} + {content?.({ active: true, payload: [{ value: 'not-a-number', payload: {} }], label: '' })} + {content?.({ active: false, payload: [] })} +
+ ), + } +}) + +const mockBuckets: TrafficBucket[] = [ + { bucket: '2024-01-15T10:00:00Z', bytes_sent: 1_048_576 }, + { bucket: '2024-01-15T11:00:00Z', bytes_sent: 2_097_152 }, +] + +describe('TrafficVolumeChart', () => { + it('renders loading skeleton when isLoading is true', () => { + render() + + expect(screen.queryByTestId('responsive-container')).not.toBeInTheDocument() + }) + + it('renders empty state when data is empty', () => { + render() + + expect(screen.getByText('No data available yet')).toBeInTheDocument() + expect(screen.getByText(/Data is being collected/)).toBeInTheDocument() + }) + + it('renders chart title', () => { + render() + + expect(screen.getByText('Traffic Volume')).toBeInTheDocument() + }) + + it('renders responsive container when data is present', () => { + render() + + expect(screen.getByTestId('responsive-container')).toBeInTheDocument() + }) + + it('renders with 6h bucket granularity', () => { + render() + + expect(screen.getByTestId('responsive-container')).toBeInTheDocument() + }) + + it('renders with 1d bucket granularity', () => { + render() + + expect(screen.getByTestId('responsive-container')).toBeInTheDocument() + }) + + it('renders info tooltip trigger button', () => { + render() + + expect(screen.getByRole('button', { name: 'About this widget' })).toBeInTheDocument() + }) + + it('passes a valid hex color to the Line stroke prop', () => { + render() + + const line = screen.getByTestId('line') + const stroke = line.getAttribute('data-stroke') + + expect(stroke).toMatch(/^#[0-9a-f]{6}$/i) + expect(stroke).toBe('#3b82f6') + }) + + it('tooltip renders bytes value correctly when line has valid stroke', () => { + render() + + expect(screen.getByText(/1\.0 MB sent/i)).toBeInTheDocument() + }) +}) diff --git a/frontend/src/components/stats/index.ts b/frontend/src/components/stats/index.ts new file mode 100644 index 000000000..b50e5e9e5 --- /dev/null +++ b/frontend/src/components/stats/index.ts @@ -0,0 +1,8 @@ +export { RequestCountWidget, type RequestCountWidgetProps } from './RequestCountWidget' +export { TopHostsChart, type TopHostsChartProps } from './TopHostsChart' +export { StatusDistributionChart, type StatusDistributionChartProps } from './StatusDistributionChart' +export { TrafficVolumeChart, type TrafficVolumeChartProps } from './TrafficVolumeChart' +export { CertExpiryList, type CertExpiryListProps } from './CertExpiryList' +export { ServiceHealthWidget, type ServiceHealthWidgetProps } from './ServiceHealthWidget' +export { PeriodSelector, type PeriodSelectorProps } from './PeriodSelector' +export { BucketSelector, type BucketSelectorProps } from './BucketSelector' diff --git a/frontend/src/hooks/__tests__/useStats.test.tsx b/frontend/src/hooks/__tests__/useStats.test.tsx new file mode 100644 index 000000000..4389a6816 --- /dev/null +++ b/frontend/src/hooks/__tests__/useStats.test.tsx @@ -0,0 +1,262 @@ +import { QueryClient, QueryClientProvider } from '@tanstack/react-query'; +import { renderHook, waitFor } from '@testing-library/react'; +import React from 'react'; +import { describe, it, expect, vi, beforeEach } from 'vitest'; + +import { + getStatsSummary, + getTopHosts, + getStatusDistribution, + getTrafficVolume, + getCertExpiry, + getStatsHealth, +} from '../../api/stats'; +import { + useStatsSummary, + useTopHosts, + useStatusDistribution, + useTrafficVolume, + useCertExpiry, + useStatsHealth, +} from '../useStats'; + +vi.mock('../../api/stats', () => ({ + getStatsSummary: vi.fn(), + getTopHosts: vi.fn(), + getStatusDistribution: vi.fn(), + getTrafficVolume: vi.fn(), + getCertExpiry: vi.fn(), + getRequests: vi.fn(), + getStatsHealth: vi.fn(), + connectStatsWebSocket: vi.fn(), +})); + +const mockSummary = { + requests_last_24h: 100, + requests_last_7d: 700, + requests_last_30d: 3000, +}; + +const mockHostStats = [ + { host_id: 'abc-123', hostname: 'example.com', count: 50 }, +]; + +const mockStatusStats = [ + { code: 200, count: 90 }, + { code: 404, count: 10 }, +]; + +const mockTrafficBuckets = [ + { bucket: '2026-06-14T00:00:00Z', bytes_sent: 1024 }, +]; + +const mockCertExpiry = [ + { host_id: 'def-456', hostname: 'secure.example.com', expires_at: '2026-09-01T00:00:00Z', days_left: 78 }, +]; + +const mockStatsHealth = { dropped_count: 0 }; + +function createWrapper() { + const queryClient = new QueryClient({ + defaultOptions: { + queries: { retry: false }, + }, + }); + return ({ children }: { children: React.ReactNode }) => ( + {children} + ); +} + +describe('useStatsSummary', () => { + beforeEach(() => { + vi.clearAllMocks(); + }); + + it('uses correct query key', async () => { + vi.mocked(getStatsSummary).mockResolvedValue(mockSummary); + + const { result } = renderHook(() => useStatsSummary(), { wrapper: createWrapper() }); + + await waitFor(() => expect(result.current.isSuccess).toBe(true)); + + expect(result.current.data).toEqual(mockSummary); + expect(getStatsSummary).toHaveBeenCalledOnce(); + }); + + it('calls getStatsSummary', async () => { + vi.mocked(getStatsSummary).mockResolvedValue(mockSummary); + + const { result } = renderHook(() => useStatsSummary(), { wrapper: createWrapper() }); + + await waitFor(() => expect(result.current.isSuccess).toBe(true)); + + expect(getStatsSummary).toHaveBeenCalled(); + }); + + it('disables refetchInterval when wsConnected is true', async () => { + vi.mocked(getStatsSummary).mockResolvedValue(mockSummary); + + // We test the hook renders correctly with wsConnected=true — polling is disabled + // but the initial fetch still fires. + const { result } = renderHook(() => useStatsSummary(true), { wrapper: createWrapper() }); + + await waitFor(() => expect(result.current.isSuccess).toBe(true)); + + expect(result.current.data).toEqual(mockSummary); + }); + + it('handles fetch error', async () => { + vi.mocked(getStatsSummary).mockRejectedValue(new Error('Network error')); + + const { result } = renderHook(() => useStatsSummary(), { wrapper: createWrapper() }); + + await waitFor(() => expect(result.current.isError).toBe(true)); + + expect(result.current.error).toBeInstanceOf(Error); + }); +}); + +describe('useTopHosts', () => { + beforeEach(() => { + vi.clearAllMocks(); + }); + + it('uses correct query key with period and limit', async () => { + vi.mocked(getTopHosts).mockResolvedValue(mockHostStats); + + const { result } = renderHook(() => useTopHosts('24h', 5), { wrapper: createWrapper() }); + + await waitFor(() => expect(result.current.isSuccess).toBe(true)); + + expect(getTopHosts).toHaveBeenCalledWith('24h', 5); + expect(result.current.data).toEqual(mockHostStats); + }); + + it('uses default limit of 10', async () => { + vi.mocked(getTopHosts).mockResolvedValue(mockHostStats); + + const { result } = renderHook(() => useTopHosts('7d'), { wrapper: createWrapper() }); + + await waitFor(() => expect(result.current.isSuccess).toBe(true)); + + expect(getTopHosts).toHaveBeenCalledWith('7d', 10); + }); + + it('handles different periods', async () => { + vi.mocked(getTopHosts).mockResolvedValue(mockHostStats); + + const { result } = renderHook(() => useTopHosts('30d'), { wrapper: createWrapper() }); + + await waitFor(() => expect(result.current.isSuccess).toBe(true)); + + expect(getTopHosts).toHaveBeenCalledWith('30d', 10); + }); +}); + +describe('useStatusDistribution', () => { + beforeEach(() => { + vi.clearAllMocks(); + }); + + it('fetches status distribution for given period', async () => { + vi.mocked(getStatusDistribution).mockResolvedValue(mockStatusStats); + + const { result } = renderHook(() => useStatusDistribution('24h'), { wrapper: createWrapper() }); + + await waitFor(() => expect(result.current.isSuccess).toBe(true)); + + expect(getStatusDistribution).toHaveBeenCalledWith('24h'); + expect(result.current.data).toEqual(mockStatusStats); + }); + + it('uses period in query key (re-fetches for different periods)', async () => { + vi.mocked(getStatusDistribution).mockResolvedValue(mockStatusStats); + + const wrapper = createWrapper(); + + const { result: r1 } = renderHook(() => useStatusDistribution('7d'), { wrapper }); + await waitFor(() => expect(r1.current.isSuccess).toBe(true)); + expect(getStatusDistribution).toHaveBeenCalledWith('7d'); + }); +}); + +describe('useTrafficVolume', () => { + beforeEach(() => { + vi.clearAllMocks(); + }); + + it('fetches traffic volume for given bucket', async () => { + vi.mocked(getTrafficVolume).mockResolvedValue(mockTrafficBuckets); + + const { result } = renderHook(() => useTrafficVolume('1h'), { wrapper: createWrapper() }); + + await waitFor(() => expect(result.current.isSuccess).toBe(true)); + + expect(getTrafficVolume).toHaveBeenCalledWith('1h'); + expect(result.current.data).toEqual(mockTrafficBuckets); + }); + + it('uses bucket in query key', async () => { + vi.mocked(getTrafficVolume).mockResolvedValue(mockTrafficBuckets); + + const { result } = renderHook(() => useTrafficVolume('6h'), { wrapper: createWrapper() }); + + await waitFor(() => expect(result.current.isSuccess).toBe(true)); + + expect(getTrafficVolume).toHaveBeenCalledWith('6h'); + }); +}); + +describe('useCertExpiry', () => { + beforeEach(() => { + vi.clearAllMocks(); + }); + + it('fetches cert expiry with default withinDays', async () => { + vi.mocked(getCertExpiry).mockResolvedValue(mockCertExpiry); + + const { result } = renderHook(() => useCertExpiry(), { wrapper: createWrapper() }); + + await waitFor(() => expect(result.current.isSuccess).toBe(true)); + + expect(getCertExpiry).toHaveBeenCalledWith(30); + expect(result.current.data).toEqual(mockCertExpiry); + }); + + it('fetches cert expiry with custom withinDays', async () => { + vi.mocked(getCertExpiry).mockResolvedValue(mockCertExpiry); + + const { result } = renderHook(() => useCertExpiry(14), { wrapper: createWrapper() }); + + await waitFor(() => expect(result.current.isSuccess).toBe(true)); + + expect(getCertExpiry).toHaveBeenCalledWith(14); + }); +}); + +describe('useStatsHealth', () => { + beforeEach(() => { + vi.clearAllMocks(); + }); + + it('fetches stats health', async () => { + vi.mocked(getStatsHealth).mockResolvedValue(mockStatsHealth); + + const { result } = renderHook(() => useStatsHealth(), { wrapper: createWrapper() }); + + await waitFor(() => expect(result.current.isSuccess).toBe(true)); + + expect(getStatsHealth).toHaveBeenCalledOnce(); + expect(result.current.data).toEqual(mockStatsHealth); + }); + + it('handles error state', async () => { + vi.mocked(getStatsHealth).mockRejectedValue(new Error('Service unavailable')); + + const { result } = renderHook(() => useStatsHealth(), { wrapper: createWrapper() }); + + await waitFor(() => expect(result.current.isError).toBe(true)); + + expect(result.current.error).toBeInstanceOf(Error); + }); +}); diff --git a/frontend/src/hooks/__tests__/useStatsWebSocket.test.tsx b/frontend/src/hooks/__tests__/useStatsWebSocket.test.tsx new file mode 100644 index 000000000..567504d98 --- /dev/null +++ b/frontend/src/hooks/__tests__/useStatsWebSocket.test.tsx @@ -0,0 +1,157 @@ +import { renderHook, act } from '@testing-library/react'; +import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'; + +import { useStatsWebSocket } from '../useStatsWebSocket'; + +// Minimal mock WebSocket implementation +interface MockWsInstance { + onopen: (() => void) | null; + onmessage: ((event: MessageEvent) => void) | null; + onerror: ((event: Event) => void) | null; + onclose: ((event: CloseEvent) => void) | null; + close: ReturnType; + readyState: number; +} + +let mockWsInstance: MockWsInstance; + +function setupMockWebSocket(initialReadyState = WebSocket.CONNECTING) { + mockWsInstance = { + onopen: null, + onmessage: null, + onerror: null, + onclose: null, + close: vi.fn(), + readyState: initialReadyState, + }; + + const MockWebSocket = vi.fn().mockImplementation(function () { + return mockWsInstance; + }) as ReturnType & { OPEN: number; CONNECTING: number; CLOSED: number }; + + MockWebSocket.OPEN = WebSocket.OPEN; + MockWebSocket.CONNECTING = WebSocket.CONNECTING; + MockWebSocket.CLOSED = WebSocket.CLOSED; + + vi.stubGlobal('WebSocket', MockWebSocket); +} + +describe('useStatsWebSocket', () => { + beforeEach(() => { + vi.stubGlobal('location', { protocol: 'http:', host: 'localhost:3000' }); + setupMockWebSocket(); + }); + + afterEach(() => { + vi.unstubAllGlobals(); + vi.clearAllMocks(); + }); + + it('starts with connected=false, lastMessage=null, latestSummary=null', () => { + const { result } = renderHook(() => useStatsWebSocket()); + + expect(result.current.connected).toBe(false); + expect(result.current.lastMessage).toBeNull(); + expect(result.current.latestSummary).toBeNull(); + }); + + it('sets connected=true when WebSocket opens', () => { + const { result } = renderHook(() => useStatsWebSocket()); + + act(() => { + mockWsInstance.onopen?.(); + }); + + expect(result.current.connected).toBe(true); + }); + + it('sets connected=false when WebSocket closes', () => { + const { result } = renderHook(() => useStatsWebSocket()); + + act(() => { + mockWsInstance.onopen?.(); + }); + expect(result.current.connected).toBe(true); + + act(() => { + const closeEvent = new CloseEvent('close', { code: 1000, wasClean: true }); + mockWsInstance.onclose?.(closeEvent); + }); + + expect(result.current.connected).toBe(false); + }); + + it('updates lastMessage and latestSummary on stats_update message', () => { + const { result } = renderHook(() => useStatsWebSocket()); + + const summary = { + requests_last_24h: 42, + requests_last_7d: 294, + requests_last_30d: 1260, + }; + + act(() => { + const event = { + data: JSON.stringify({ type: 'stats_update', data: summary }), + } as MessageEvent; + mockWsInstance.onmessage?.(event); + }); + + expect(result.current.lastMessage).toEqual({ type: 'stats_update', data: summary }); + expect(result.current.latestSummary).toEqual(summary); + }); + + it('updates lastMessage on each new message', () => { + const { result } = renderHook(() => useStatsWebSocket()); + + const summary1 = { requests_last_24h: 1, requests_last_7d: 7, requests_last_30d: 30 }; + const summary2 = { requests_last_24h: 2, requests_last_7d: 14, requests_last_30d: 60 }; + + act(() => { + mockWsInstance.onmessage?.({ data: JSON.stringify({ type: 'stats_update', data: summary1 }) } as MessageEvent); + }); + expect(result.current.latestSummary).toEqual(summary1); + + act(() => { + mockWsInstance.onmessage?.({ data: JSON.stringify({ type: 'stats_update', data: summary2 }) } as MessageEvent); + }); + expect(result.current.latestSummary).toEqual(summary2); + expect(result.current.lastMessage).toEqual({ type: 'stats_update', data: summary2 }); + }); + + it('calls the cleanup function returned by connectStatsWebSocket on unmount', () => { + mockWsInstance.readyState = WebSocket.OPEN; + + const { unmount } = renderHook(() => useStatsWebSocket()); + + unmount(); + + // The cleanup closure calls ws.close() when readyState is OPEN + expect(mockWsInstance.close).toHaveBeenCalledOnce(); + }); + + it('does not call ws.close() on unmount when connection is already closed', () => { + mockWsInstance.readyState = WebSocket.CLOSED; + + const { unmount } = renderHook(() => useStatsWebSocket()); + + unmount(); + + expect(mockWsInstance.close).not.toHaveBeenCalled(); + }); + + it('updates lastMessage but not latestSummary for non-stats_update message types', () => { + // Covers the else-branch of if (msg.type === 'stats_update'). + const { result } = renderHook(() => useStatsWebSocket()); + + const otherMsg = { type: 'ping', data: {} }; + + act(() => { + const event = { data: JSON.stringify(otherMsg) } as MessageEvent; + mockWsInstance.onmessage?.(event); + }); + + expect(result.current.lastMessage).toEqual(otherMsg); + expect(result.current.latestSummary).toBeNull(); + }); +}); diff --git a/frontend/src/hooks/__tests__/useWidgetVisibility.test.ts b/frontend/src/hooks/__tests__/useWidgetVisibility.test.ts new file mode 100644 index 000000000..027320ce9 --- /dev/null +++ b/frontend/src/hooks/__tests__/useWidgetVisibility.test.ts @@ -0,0 +1,144 @@ +import { renderHook, act } from '@testing-library/react' +import { beforeEach, describe, expect, it } from 'vitest' + +import { useWidgetVisibility } from '../useWidgetVisibility' +import type { WidgetKey } from '../useWidgetVisibility' + +const STORAGE_KEY = 'charon.stats.widgetVisibility' + +const ALL_KEYS: WidgetKey[] = [ + 'requestCount', + 'trafficVolume', + 'topHosts', + 'statusDistribution', + 'certExpiry', + 'serviceHealth', +] + +beforeEach(() => { + localStorage.clear() +}) + +describe('useWidgetVisibility', () => { + it('all widgets are visible by default', () => { + const { result } = renderHook(() => useWidgetVisibility()) + + for (const key of ALL_KEYS) { + expect(result.current.visibility[key]).toBe(true) + } + }) + + it('toggleWidget hides a visible widget', () => { + const { result } = renderHook(() => useWidgetVisibility()) + + act(() => { + result.current.toggleWidget('requestCount') + }) + + expect(result.current.visibility.requestCount).toBe(false) + }) + + it('toggleWidget shows a hidden widget', () => { + localStorage.setItem( + STORAGE_KEY, + JSON.stringify({ requestCount: false, trafficVolume: true, topHosts: true, statusDistribution: true, certExpiry: true, serviceHealth: true }) + ) + + const { result } = renderHook(() => useWidgetVisibility()) + + expect(result.current.visibility.requestCount).toBe(false) + + act(() => { + result.current.toggleWidget('requestCount') + }) + + expect(result.current.visibility.requestCount).toBe(true) + }) + + it('persists visibility state to localStorage after toggle', () => { + const { result } = renderHook(() => useWidgetVisibility()) + + act(() => { + result.current.toggleWidget('topHosts') + }) + + const stored = JSON.parse(localStorage.getItem(STORAGE_KEY) ?? '{}') as Record + expect(stored.topHosts).toBe(false) + }) + + it('loads persisted state from localStorage on mount', () => { + localStorage.setItem( + STORAGE_KEY, + JSON.stringify({ requestCount: false, trafficVolume: false, topHosts: true, statusDistribution: true, certExpiry: true, serviceHealth: true }) + ) + + const { result } = renderHook(() => useWidgetVisibility()) + + expect(result.current.visibility.requestCount).toBe(false) + expect(result.current.visibility.trafficVolume).toBe(false) + expect(result.current.visibility.topHosts).toBe(true) + }) + + it('resetAll restores all widgets to visible', () => { + localStorage.setItem( + STORAGE_KEY, + JSON.stringify({ requestCount: false, trafficVolume: false, topHosts: false, statusDistribution: false, certExpiry: false, serviceHealth: false }) + ) + + const { result } = renderHook(() => useWidgetVisibility()) + + act(() => { + result.current.resetAll() + }) + + for (const key of ALL_KEYS) { + expect(result.current.visibility[key]).toBe(true) + } + }) + + it('resetAll writes defaults back to localStorage', () => { + const { result } = renderHook(() => useWidgetVisibility()) + + act(() => { + result.current.toggleWidget('certExpiry') + }) + act(() => { + result.current.resetAll() + }) + + const stored = JSON.parse(localStorage.getItem(STORAGE_KEY) ?? '{}') as Record + expect(stored.certExpiry).toBe(true) + }) + + it('falls back to defaults when localStorage contains invalid JSON', () => { + localStorage.setItem(STORAGE_KEY, 'not-valid-json{{{') + + const { result } = renderHook(() => useWidgetVisibility()) + + for (const key of ALL_KEYS) { + expect(result.current.visibility[key]).toBe(true) + } + }) + + it('falls back to defaults when localStorage contains non-object value', () => { + localStorage.setItem(STORAGE_KEY, '"just-a-string"') + + const { result } = renderHook(() => useWidgetVisibility()) + + for (const key of ALL_KEYS) { + expect(result.current.visibility[key]).toBe(true) + } + }) + + it('ignores unknown keys in localStorage and keeps defaults for known keys', () => { + localStorage.setItem( + STORAGE_KEY, + JSON.stringify({ unknownKey: false, requestCount: false }) + ) + + const { result } = renderHook(() => useWidgetVisibility()) + + expect(result.current.visibility.requestCount).toBe(false) + expect(result.current.visibility.trafficVolume).toBe(true) + }) +}) diff --git a/frontend/src/hooks/useStats.ts b/frontend/src/hooks/useStats.ts new file mode 100644 index 000000000..215ddf8e7 --- /dev/null +++ b/frontend/src/hooks/useStats.ts @@ -0,0 +1,92 @@ +import { useQuery } from '@tanstack/react-query'; +import type { UseQueryResult } from '@tanstack/react-query'; + +import { + getStatsSummary, + getTopHosts, + getStatusDistribution, + getTrafficVolume, + getCertExpiry, + getStatsHealth, + type StatsSummary, + type HostStat, + type StatusStat, + type TrafficBucket, + type CertExpiry, + type StatsHealth, + type StatsPeriod, + type StatsBucket, +} from '../api/stats'; + +/** + * Fetches aggregate request counts for the last 24h, 7d, and 30d. + * When wsConnected is true, disables REST polling to avoid redundant calls + * alongside the WebSocket. + */ +export function useStatsSummary(wsConnected?: boolean): UseQueryResult { + return useQuery({ + queryKey: ['stats', 'summary'], + queryFn: getStatsSummary, + refetchInterval: wsConnected ? false : 30_000, + }); +} + +/** + * Fetches the top N hosts by request count for the given period. + * Polls every 60 seconds. + */ +export function useTopHosts(period: StatsPeriod, limit = 10): UseQueryResult { + return useQuery({ + queryKey: ['stats', 'top-hosts', period, limit], + queryFn: () => getTopHosts(period, limit), + refetchInterval: 60_000, + }); +} + +/** + * Fetches HTTP status code distribution for the given period. + * Polls every 60 seconds. + */ +export function useStatusDistribution(period: StatsPeriod): UseQueryResult { + return useQuery({ + queryKey: ['stats', 'status-distribution', period], + queryFn: () => getStatusDistribution(period), + refetchInterval: 60_000, + }); +} + +/** + * Fetches traffic volume bucketed by time. + * Polls every 30 seconds. + */ +export function useTrafficVolume(bucket: StatsBucket): UseQueryResult { + return useQuery({ + queryKey: ['stats', 'traffic-volume', bucket], + queryFn: () => getTrafficVolume(bucket), + refetchInterval: 30_000, + }); +} + +/** + * Fetches TLS certificate expiry information for hosts expiring within N days. + * Polls every 5 minutes. + */ +export function useCertExpiry(withinDays = 30): UseQueryResult { + return useQuery({ + queryKey: ['stats', 'cert-expiry', withinDays], + queryFn: () => getCertExpiry(withinDays), + refetchInterval: 5 * 60_000, + }); +} + +/** + * Fetches stats ingestion health metrics (dropped_count). + * Polls every 30 seconds. + */ +export function useStatsHealth(): UseQueryResult { + return useQuery({ + queryKey: ['stats', 'health'], + queryFn: getStatsHealth, + refetchInterval: 30_000, + }); +} diff --git a/frontend/src/hooks/useStatsWebSocket.ts b/frontend/src/hooks/useStatsWebSocket.ts new file mode 100644 index 000000000..dede33be3 --- /dev/null +++ b/frontend/src/hooks/useStatsWebSocket.ts @@ -0,0 +1,42 @@ +import { useEffect, useState } from 'react'; + +import { connectStatsWebSocket } from '../api/stats'; +import type { StatsPushMessage, StatsSummary } from '../api/stats'; + +export interface UseStatsWebSocketResult { + connected: boolean; + lastMessage: StatsPushMessage | null; + latestSummary: StatsSummary | null; +} + +/** + * Connects to the stats WebSocket endpoint and tracks real-time summary updates. + * Cleans up the WebSocket connection on unmount. + */ +export function useStatsWebSocket(): UseStatsWebSocketResult { + const [connected, setConnected] = useState(false); + const [lastMessage, setLastMessage] = useState(null); + const [latestSummary, setLatestSummary] = useState(null); + + useEffect(() => { + const cleanup = connectStatsWebSocket( + (msg) => { + setLastMessage(msg); + if (msg.type === 'stats_update') { + setLatestSummary(msg.data); + } + }, + () => { + setConnected(true); + }, + undefined, + () => { + setConnected(false); + } + ); + + return cleanup; + }, []); + + return { connected, lastMessage, latestSummary }; +} diff --git a/frontend/src/hooks/useWidgetVisibility.ts b/frontend/src/hooks/useWidgetVisibility.ts new file mode 100644 index 000000000..1816768eb --- /dev/null +++ b/frontend/src/hooks/useWidgetVisibility.ts @@ -0,0 +1,76 @@ +import { useState, useCallback } from 'react' + +export type WidgetKey = + | 'requestCount' + | 'trafficVolume' + | 'topHosts' + | 'statusDistribution' + | 'certExpiry' + | 'serviceHealth' + +const STORAGE_KEY = 'charon.stats.widgetVisibility' + +const ALL_WIDGETS: WidgetKey[] = [ + 'requestCount', + 'trafficVolume', + 'topHosts', + 'statusDistribution', + 'certExpiry', + 'serviceHealth', +] + +const DEFAULT_VISIBILITY: Record = { + requestCount: true, + trafficVolume: true, + topHosts: true, + statusDistribution: true, + certExpiry: true, + serviceHealth: true, +} + +function loadFromStorage(): Record { + try { + const raw = localStorage.getItem(STORAGE_KEY) + if (!raw) return { ...DEFAULT_VISIBILITY } + const parsed: unknown = JSON.parse(raw) + if (typeof parsed !== 'object' || parsed === null) return { ...DEFAULT_VISIBILITY } + const result = { ...DEFAULT_VISIBILITY } + for (const key of ALL_WIDGETS) { + const val = (parsed as Record)[key] + if (typeof val === 'boolean') { + result[key] = val + } + } + return result + } catch { + return { ...DEFAULT_VISIBILITY } + } +} + +function saveToStorage(visibility: Record): void { + try { + localStorage.setItem(STORAGE_KEY, JSON.stringify(visibility)) + } catch { + // Ignore storage errors (e.g. private browsing quota) + } +} + +export function useWidgetVisibility() { + const [visibility, setVisibility] = useState>(loadFromStorage) + + const toggleWidget = useCallback((key: WidgetKey) => { + setVisibility((prev) => { + const next = { ...prev, [key]: !prev[key] } + saveToStorage(next) + return next + }) + }, []) + + const resetAll = useCallback(() => { + const defaults = { ...DEFAULT_VISIBILITY } + saveToStorage(defaults) + setVisibility(defaults) + }, []) + + return { visibility, toggleWidget, resetAll } +} diff --git a/frontend/src/locales/de/translation.json b/frontend/src/locales/de/translation.json index d4de75f35..700d08ccf 100644 --- a/frontend/src/locales/de/translation.json +++ b/frontend/src/locales/de/translation.json @@ -734,7 +734,9 @@ "activeHosts": "{{count}} aktiv", "activeServers": "{{count}} aktiv", "activeLists": "{{count}} aktiv", - "validCerts": "{{count}} gültig" + "validCerts": "{{count}} gültig", + "statistics": "Statistiken", + "trafficVolume": "Datenvolumen" }, "setup": { "welcomeTitle": "Willkommen bei Charon", diff --git a/frontend/src/locales/en/translation.json b/frontend/src/locales/en/translation.json index 3731ff95f..dc11a6557 100644 --- a/frontend/src/locales/en/translation.json +++ b/frontend/src/locales/en/translation.json @@ -902,7 +902,9 @@ "activeHosts": "{{count}} active", "activeServers": "{{count}} active", "activeLists": "{{count}} active", - "validCerts": "{{count}} valid" + "validCerts": "{{count}} valid", + "statistics": "Statistics", + "trafficVolume": "Traffic Volume" }, "setup": { "welcomeTitle": "Welcome to Charon", diff --git a/frontend/src/locales/es/translation.json b/frontend/src/locales/es/translation.json index cc005763a..04d982100 100644 --- a/frontend/src/locales/es/translation.json +++ b/frontend/src/locales/es/translation.json @@ -734,7 +734,9 @@ "activeHosts": "{{count}} activo", "activeServers": "{{count}} activo", "activeLists": "{{count}} activo", - "validCerts": "{{count}} válido" + "validCerts": "{{count}} válido", + "statistics": "Estadísticas", + "trafficVolume": "Volumen de tráfico" }, "setup": { "welcomeTitle": "Bienvenido a Charon", diff --git a/frontend/src/locales/fr/translation.json b/frontend/src/locales/fr/translation.json index ee0232a04..2ba1afcd1 100644 --- a/frontend/src/locales/fr/translation.json +++ b/frontend/src/locales/fr/translation.json @@ -734,7 +734,9 @@ "activeHosts": "{{count}} actif", "activeServers": "{{count}} actif", "activeLists": "{{count}} actif", - "validCerts": "{{count}} valide" + "validCerts": "{{count}} valide", + "statistics": "Statistiques", + "trafficVolume": "Volume de trafic" }, "setup": { "welcomeTitle": "Bienvenue sur Charon", diff --git a/frontend/src/locales/zh/translation.json b/frontend/src/locales/zh/translation.json index 5f52bf5e7..0d20f4a4a 100644 --- a/frontend/src/locales/zh/translation.json +++ b/frontend/src/locales/zh/translation.json @@ -734,7 +734,9 @@ "activeHosts": "{{count}} 个活动", "activeServers": "{{count}} 个活动", "activeLists": "{{count}} 个活动", - "validCerts": "{{count}} 个有效" + "validCerts": "{{count}} 个有效", + "statistics": "统计", + "trafficVolume": "流量" }, "setup": { "welcomeTitle": "欢迎使用 Charon", diff --git a/frontend/src/pages/Dashboard.tsx b/frontend/src/pages/Dashboard.tsx index b5c2715e7..91309e271 100644 --- a/frontend/src/pages/Dashboard.tsx +++ b/frontend/src/pages/Dashboard.tsx @@ -1,16 +1,38 @@ import { useQuery, useQueryClient } from '@tanstack/react-query' -import { Globe, Server, FileKey, Activity, CheckCircle2, AlertTriangle } from 'lucide-react' -import { useMemo, useEffect } from 'react' +import { Globe, Server, FileKey, Activity, CheckCircle2, AlertTriangle, Settings } from 'lucide-react' +import { useMemo, useEffect, useState } from 'react' import { useTranslation } from 'react-i18next' import { checkHealth } from '../api/health' +import type { StatsPeriod, StatsBucket } from '../api/stats' import { PageShell } from '../components/layout/PageShell' -import { StatsCard, Skeleton } from '../components/ui' +import { + RequestCountWidget, + ServiceHealthWidget, + CertExpiryList, + TrafficVolumeChart, + TopHostsChart, + StatusDistributionChart, + PeriodSelector, + BucketSelector, +} from '../components/stats' +import { StatsCard, Skeleton, Switch } from '../components/ui' import UptimeWidget from '../components/UptimeWidget' import { useAccessLists } from '../hooks/useAccessLists' import { useCertificates } from '../hooks/useCertificates' import { useProxyHosts } from '../hooks/useProxyHosts' import { useRemoteServers } from '../hooks/useRemoteServers' +import { + useStatsSummary, + useTopHosts, + useStatusDistribution, + useTrafficVolume, + useCertExpiry, + useStatsHealth, +} from '../hooks/useStats' +import { useStatsWebSocket } from '../hooks/useStatsWebSocket' +import { useWidgetVisibility } from '../hooks/useWidgetVisibility' +import type { WidgetKey } from '../hooks/useWidgetVisibility' function StatsCardSkeleton() { return ( @@ -27,6 +49,24 @@ function StatsCardSkeleton() { ) } +const WIDGET_LABELS: Record = { + requestCount: 'Request Counts', + trafficVolume: 'Traffic Volume', + topHosts: 'Top Hosts', + statusDistribution: 'Status Distribution', + certExpiry: 'Certificate Expiry', + serviceHealth: 'Service Health', +} + +const WIDGET_KEYS: WidgetKey[] = [ + 'requestCount', + 'serviceHealth', + 'certExpiry', + 'trafficVolume', + 'topHosts', + 'statusDistribution', +] + export default function Dashboard() { const { t } = useTranslation() const { hosts, loading: hostsLoading } = useProxyHosts() @@ -34,6 +74,25 @@ export default function Dashboard() { const { data: accessLists, isLoading: accessListsLoading } = useAccessLists() const queryClient = useQueryClient() + // Stats state + const [period, setPeriod] = useState('24h') + const [bucket, setBucket] = useState('1h') + const [customizeOpen, setCustomizeOpen] = useState(false) + + // Widget visibility + const { visibility, toggleWidget } = useWidgetVisibility() + + // WebSocket for live stats updates + const { connected: wsConnected } = useStatsWebSocket() + + // Stats data hooks + const summaryResult = useStatsSummary(wsConnected) + const topHostsResult = useTopHosts(period) + const statusDistResult = useStatusDistribution(period) + const trafficResult = useTrafficVolume(bucket) + const certExpiryResult = useCertExpiry(30) + const statsHealthResult = useStatsHealth() + // Fetch certificates (polling interval managed via effect below) const { certificates, isLoading: certificatesLoading } = useCertificates() @@ -85,6 +144,8 @@ export default function Dashboard() { const isInitialLoading = hostsLoading || serversLoading || accessListsLoading || certificatesLoading + const allHidden = WIDGET_KEYS.every(key => !visibility[key]) + return (
+ + {/* Dashboard Statistics */} +
+ {/* Section header with period selector and customize button */} +
+

+ {t('dashboard.statistics', 'Statistics')} +

+
+ + +
+
+ + {/* Inline customization panel */} + {customizeOpen && ( +
+

Show / hide widgets

+
+ {WIDGET_KEYS.map((key) => ( + + ))} +
+
+ )} + + {allHidden ? ( +

(all hidden)

+ ) : ( + <> + {/* Top row: Request counts, WS health, cert expiry — 1 col → 3 cols on lg */} + {(visibility.requestCount || visibility.serviceHealth || visibility.certExpiry) && ( +
+ {visibility.requestCount && ( + + )} + {visibility.serviceHealth && ( + + )} + {visibility.certExpiry && ( + + )} +
+ )} + + {/* Traffic volume chart with bucket selector */} + {visibility.trafficVolume && ( +
+
+

+ {t('dashboard.trafficVolume', 'Traffic Volume')} +

+ +
+ +
+ )} + + {/* Bottom row: Top hosts + status distribution — 1 col → 2 cols on sm */} + {(visibility.topHosts || visibility.statusDistribution) && ( +
+ {visibility.topHosts && ( + + )} + {visibility.statusDistribution && ( + + )} +
+ )} + + )} +
) } diff --git a/frontend/src/pages/__tests__/Dashboard.test.tsx b/frontend/src/pages/__tests__/Dashboard.test.tsx index 0235e9f4a..48f63acfe 100644 --- a/frontend/src/pages/__tests__/Dashboard.test.tsx +++ b/frontend/src/pages/__tests__/Dashboard.test.tsx @@ -1,9 +1,14 @@ -import { screen } from '@testing-library/react' +import { screen, fireEvent } from '@testing-library/react' import { describe, it, expect, vi, beforeEach } from 'vitest' import { renderWithQueryClient } from '../../test-utils/renderWithQueryClient' import Dashboard from '../Dashboard' +// localStorage is available in jsdom — clear between tests +beforeEach(() => { + localStorage.clear() +}) + vi.mock('../../hooks/useProxyHosts', () => ({ useProxyHosts: () => ({ hosts: [ @@ -50,9 +55,91 @@ vi.mock('../../components/UptimeWidget', () => ({ default: () =>
Uptime Widget
, })) +// Mock stats hooks +vi.mock('../../hooks/useStats', () => ({ + useStatsSummary: () => ({ + data: { last_24h: 1200, last_7d: 8400, last_30d: 36000 }, + isLoading: false, + }), + useTopHosts: () => ({ + data: [ + { host: 'api.example.com', count: 500 }, + { host: 'app.example.com', count: 300 }, + ], + isLoading: false, + }), + useStatusDistribution: () => ({ + data: [ + { status_code: 200, count: 900 }, + { status_code: 404, count: 100 }, + ], + isLoading: false, + }), + useTrafficVolume: () => ({ + data: [ + { bucket: '2024-01-01T00:00:00Z', count: 42 }, + ], + isLoading: false, + }), + useCertExpiry: () => ({ + data: [ + { host: 'expire-soon.com', expires_at: '2024-02-01T00:00:00Z', days_left: 10 }, + ], + isLoading: false, + }), + useStatsHealth: () => ({ + data: { dropped_count: 0 }, + isLoading: false, + }), +})) + +// Mock WebSocket hook +vi.mock('../../hooks/useStatsWebSocket', () => ({ + useStatsWebSocket: () => ({ + connected: true, + lastMessage: null, + latestSummary: null, + }), +})) + +// Mock stats components to isolate Dashboard rendering +vi.mock('../../components/stats', () => ({ + RequestCountWidget: ({ isLoading }: { isLoading: boolean }) => ( +
{isLoading ? 'Loading...' : 'Request Counts'}
+ ), + ServiceHealthWidget: ({ wsConnected }: { wsConnected: boolean }) => ( +
{wsConnected ? 'Live' : 'Offline'}
+ ), + CertExpiryList: ({ isLoading }: { isLoading: boolean }) => ( +
{isLoading ? 'Loading...' : 'Cert Expiry'}
+ ), + TrafficVolumeChart: ({ bucket }: { bucket: string }) => ( +
Traffic Volume ({bucket})
+ ), + TopHostsChart: ({ isLoading }: { isLoading: boolean }) => ( +
{isLoading ? 'Loading...' : 'Top Hosts'}
+ ), + StatusDistributionChart: ({ isLoading }: { isLoading: boolean }) => ( +
{isLoading ? 'Loading...' : 'Status Distribution'}
+ ), + PeriodSelector: ({ value, onChange }: { value: string; onChange: (p: string) => void }) => ( +
+ + {value} +
+ ), + BucketSelector: ({ value, onChange }: { value: string; onChange: (b: string) => void }) => ( +
+ + {value} +
+ ), +})) + describe('Dashboard page', () => { beforeEach(() => { vi.clearAllMocks() + localStorage.clear() }) it('renders counts and health status', async () => { @@ -85,4 +172,151 @@ describe('Dashboard page', () => { expect(screen.getByText('1 valid')).toBeInTheDocument() }) + it('renders the uptime widget', async () => { + renderWithQueryClient() + + expect(await screen.findByTestId('uptime-widget')).toBeInTheDocument() + }) + + it('renders stats section heading', async () => { + renderWithQueryClient() + + // The heading text comes from the dashboard.statistics translation key + expect(await screen.findByRole('heading', { name: 'Statistics' })).toBeInTheDocument() + }) + + it('renders all stats widgets', async () => { + renderWithQueryClient() + + expect(await screen.findByTestId('request-count-widget')).toBeInTheDocument() + expect(screen.getByTestId('service-health-widget')).toBeInTheDocument() + expect(screen.getByTestId('cert-expiry-list')).toBeInTheDocument() + expect(screen.getByTestId('traffic-volume-chart')).toBeInTheDocument() + expect(screen.getByTestId('top-hosts-chart')).toBeInTheDocument() + expect(screen.getByTestId('status-distribution-chart')).toBeInTheDocument() + }) + + it('shows WebSocket connected state in service health widget', async () => { + renderWithQueryClient() + + expect(await screen.findByText('Live')).toBeInTheDocument() + }) + + it('renders period selector with default 24h', async () => { + renderWithQueryClient() + + const periodSelector = await screen.findByTestId('period-selector') + expect(periodSelector).toBeInTheDocument() + expect(periodSelector).toHaveTextContent('24h') + }) + + it('renders bucket selector with default 1h', async () => { + renderWithQueryClient() + + const bucketSelector = await screen.findByTestId('bucket-selector') + expect(bucketSelector).toBeInTheDocument() + expect(bucketSelector).toHaveTextContent('1h') + }) + + it('updates period state when PeriodSelector fires onChange', async () => { + renderWithQueryClient() + + const periodSelector = await screen.findByTestId('period-selector') + expect(periodSelector).toHaveTextContent('24h') + + fireEvent.click(screen.getByRole('button', { name: '7d' })) + + expect(periodSelector).toHaveTextContent('7d') + }) + + it('updates bucket state when BucketSelector fires onChange', async () => { + renderWithQueryClient() + + const bucketSelector = await screen.findByTestId('bucket-selector') + expect(bucketSelector).toHaveTextContent('1h') + + fireEvent.click(screen.getByRole('button', { name: '6h' })) + + expect(bucketSelector).toHaveTextContent('6h') + }) + + it('traffic volume chart reflects current bucket value', async () => { + renderWithQueryClient() + + expect(await screen.findByText('Traffic Volume (1h)')).toBeInTheDocument() + + fireEvent.click(screen.getByRole('button', { name: '6h' })) + + expect(screen.getByText('Traffic Volume (6h)')).toBeInTheDocument() + }) + + it('renders Customize button in the stats section header', async () => { + renderWithQueryClient() + + expect(await screen.findByRole('button', { name: /customize/i })).toBeInTheDocument() + }) + + it('customize panel is hidden by default', async () => { + renderWithQueryClient() + + await screen.findByRole('button', { name: /customize/i }) + + expect(screen.queryByText('Show / hide widgets')).not.toBeInTheDocument() + }) + + it('clicking Customize button opens the settings panel', async () => { + renderWithQueryClient() + + const btn = await screen.findByRole('button', { name: /customize/i }) + fireEvent.click(btn) + + expect(screen.getByText('Show / hide widgets')).toBeInTheDocument() + }) + + it('clicking Customize button again closes the panel', async () => { + renderWithQueryClient() + + const btn = await screen.findByRole('button', { name: /customize/i }) + fireEvent.click(btn) + expect(screen.getByText('Show / hide widgets')).toBeInTheDocument() + + fireEvent.click(btn) + expect(screen.queryByText('Show / hide widgets')).not.toBeInTheDocument() + }) + + it('toggling a widget switch hides that widget', async () => { + renderWithQueryClient() + + // Open customize panel + const btn = await screen.findByRole('button', { name: /customize/i }) + fireEvent.click(btn) + + // The Request Counts widget is visible initially + expect(screen.getByTestId('request-count-widget')).toBeInTheDocument() + + // Toggle it off + const toggle = screen.getByRole('checkbox', { name: /request counts/i }) + fireEvent.click(toggle) + + expect(screen.queryByTestId('request-count-widget')).not.toBeInTheDocument() + }) + + it('shows "(all hidden)" message when all widgets are hidden', async () => { + // Pre-seed localStorage with all hidden + localStorage.setItem( + 'charon.stats.widgetVisibility', + JSON.stringify({ + requestCount: false, + trafficVolume: false, + topHosts: false, + statusDistribution: false, + certExpiry: false, + serviceHealth: false, + }) + ) + + renderWithQueryClient() + + expect(await screen.findByText('(all hidden)')).toBeInTheDocument() + }) }) diff --git a/tests/core/navigation.spec.ts b/tests/core/navigation.spec.ts index 50f189cfc..7b67867c7 100644 --- a/tests/core/navigation.spec.ts +++ b/tests/core/navigation.spec.ts @@ -192,7 +192,7 @@ test.describe('Navigation', () => { await waitForLoadingComplete(page); await test.step('Find expandable sidebar sections', async () => { - const expandButtons = page.locator('[aria-expanded]'); + const expandButtons = page.locator('aside [aria-expanded]'); if ((await expandButtons.count()) > 0) { const firstExpandable = expandButtons.first(); diff --git a/tests/stats.spec.ts b/tests/stats.spec.ts new file mode 100644 index 000000000..5560883a2 --- /dev/null +++ b/tests/stats.spec.ts @@ -0,0 +1,288 @@ +/** + * Dashboard Statistics E2E Tests + * + * Tests the enhanced dashboard statistics feature (Issue #25) including: + * - Statistics section heading visibility + * - Period selector tab interactions + * - Bucket selector tab interactions + * - Request count widget rendering + * - WebSocket / health widget rendering + * - Certificate expiry section visibility + * - Traffic volume chart container + * - Top hosts chart container + * - Status distribution chart container + * + * @see backend/internal/api/handlers/stats_handler.go + * @see frontend/src/components/stats/ + */ + +import { test, expect, loginUser } from './fixtures/auth-fixtures'; +import { waitForAPIHealth } from './utils/api-helpers'; +import { waitForLoadingComplete } from './utils/wait-helpers'; + +test.describe('Dashboard Statistics', () => { + test.beforeEach(async ({ page, adminUser }) => { + await waitForAPIHealth(page.request); + await loginUser(page, adminUser); + await page.goto('/'); + await waitForLoadingComplete(page); + }); + + // ─── Section heading ──────────────────────────────────────────────────────── + + test('should display the Statistics section heading on the dashboard', async ({ page }) => { + await test.step('Navigate to dashboard root', async () => { + await page.goto('/'); + await waitForLoadingComplete(page); + }); + + await test.step('Verify Statistics heading is visible', async () => { + // The heading is rendered via t('dashboard.statistics', 'Statistics') + // inside a
+ const heading = page + .getByRole('heading', { name: /statistics/i }) + .or(page.locator('#stats-section-heading')); + + await expect(heading.first()).toBeVisible({ timeout: 15_000 }); + }); + }); + + // ─── Period selector ──────────────────────────────────────────────────────── + + test('should mark the selected period tab as active', async ({ page }) => { + await test.step('Wait for statistics section', async () => { + await expect( + page.getByRole('heading', { name: /statistics/i }).or(page.locator('#stats-section-heading')).first() + ).toBeVisible({ timeout: 15_000 }); + }); + + await test.step('Click the 7d period tab', async () => { + // PeriodSelector renders buttons with role="radio" inside a role="group" + const periodGroup = page.getByRole('group', { name: /select time period/i }); + const sevenDay = periodGroup.getByRole('radio', { name: '7d' }); + await sevenDay.click(); + }); + + await test.step('Verify 7d radio is checked', async () => { + const periodGroup = page.getByRole('group', { name: /select time period/i }); + const sevenDay = periodGroup.getByRole('radio', { name: '7d' }); + await expect(sevenDay).toHaveAttribute('aria-checked', 'true'); + }); + }); + + test('should allow switching back to the 24h period tab', async ({ page }) => { + await test.step('Wait for statistics section', async () => { + await expect( + page.getByRole('heading', { name: /statistics/i }).or(page.locator('#stats-section-heading')).first() + ).toBeVisible({ timeout: 15_000 }); + }); + + const periodGroup = page.getByRole('group', { name: /select time period/i }); + + await test.step('Switch to 30d', async () => { + await periodGroup.getByRole('radio', { name: '30d' }).click(); + }); + + await test.step('Switch back to 24h', async () => { + await periodGroup.getByRole('radio', { name: '24h' }).click(); + }); + + await test.step('Verify 24h is now active', async () => { + await expect(periodGroup.getByRole('radio', { name: '24h' })).toHaveAttribute('aria-checked', 'true'); + }); + }); + + // ─── Bucket selector ──────────────────────────────────────────────────────── + + test('should mark the selected bucket tab as active', async ({ page }) => { + await test.step('Wait for statistics section', async () => { + await expect( + page.getByRole('heading', { name: /statistics/i }).or(page.locator('#stats-section-heading')).first() + ).toBeVisible({ timeout: 15_000 }); + }); + + await test.step('Click the 6h bucket tab', async () => { + const bucketGroup = page.getByRole('group', { name: /select bucket granularity/i }); + await bucketGroup.getByRole('radio', { name: '6h' }).click(); + }); + + await test.step('Verify 6h is checked', async () => { + const bucketGroup = page.getByRole('group', { name: /select bucket granularity/i }); + await expect(bucketGroup.getByRole('radio', { name: '6h' })).toHaveAttribute('aria-checked', 'true'); + }); + }); + + // ─── Request count widget ─────────────────────────────────────────────────── + + test('should render the Request Counts card with period labels', async ({ page }) => { + await test.step('Wait for statistics section', async () => { + await expect( + page.getByRole('heading', { name: /statistics/i }).or(page.locator('#stats-section-heading')).first() + ).toBeVisible({ timeout: 15_000 }); + }); + + await test.step('Verify Request Counts heading is visible', async () => { + const requestCountsCard = page.getByText(/request counts/i); + await expect(requestCountsCard.first()).toBeVisible({ timeout: 10_000 }); + }); + + await test.step('Verify Last 24h label is visible in the widget', async () => { + const last24hLabel = page.getByText(/last 24h/i); + await expect(last24hLabel.first()).toBeVisible({ timeout: 10_000 }); + }); + }); + + // ─── WebSocket / health widget ────────────────────────────────────────────── + + test('should render the Stats Service Health widget', async ({ page }) => { + await test.step('Wait for statistics section', async () => { + await expect( + page.getByRole('heading', { name: /statistics/i }).or(page.locator('#stats-section-heading')).first() + ).toBeVisible({ timeout: 15_000 }); + }); + + await test.step('Verify Stats Service Health card heading is visible', async () => { + const healthCard = page.getByText(/stats service health/i); + await expect(healthCard.first()).toBeVisible({ timeout: 10_000 }); + }); + + await test.step('Verify Live or Offline badge is rendered', async () => { + // ServiceHealthWidget renders either "Live" or "Offline" badge depending on WS state + const badge = page + .getByText(/^live$/i) + .or(page.getByText(/^offline$/i)); + await expect(badge.first()).toBeVisible({ timeout: 10_000 }); + }); + + await test.step('Verify Real-time feed label is present', async () => { + const feedLabel = page.getByText(/real-time feed/i); + await expect(feedLabel.first()).toBeVisible({ timeout: 10_000 }); + }); + }); + + // ─── Certificate expiry section ───────────────────────────────────────────── + + test('should render the Certificate Expiry section', async ({ page }) => { + await test.step('Wait for statistics section', async () => { + await expect( + page.getByRole('heading', { name: /statistics/i }).or(page.locator('#stats-section-heading')).first() + ).toBeVisible({ timeout: 15_000 }); + }); + + await test.step('Verify Certificate Expiry card is rendered', async () => { + const certCard = page.getByText(/certificate expiry/i); + await expect(certCard.first()).toBeVisible({ timeout: 10_000 }); + }); + + await test.step('Verify expiry content or empty-state message is shown', async () => { + // Either a table with certificates or the empty-state paragraph + const hasRows = await page + .getByRole('table', { name: /certificate expiry/i }) + .isVisible() + .catch(() => false); + const hasEmptyMsg = await page + .getByText(/no certificates expiring soon/i) + .isVisible() + .catch(() => false); + + expect(hasRows || hasEmptyMsg).toBeTruthy(); + }); + }); + + // ─── Traffic volume chart ─────────────────────────────────────────────────── + + test('should render the Traffic Volume chart container', async ({ page }) => { + await test.step('Wait for statistics section', async () => { + await expect( + page.getByRole('heading', { name: /statistics/i }).or(page.locator('#stats-section-heading')).first() + ).toBeVisible({ timeout: 15_000 }); + }); + + await test.step('Verify Traffic Volume chart card is visible', async () => { + const chartCard = page.getByText(/traffic volume/i); + await expect(chartCard.first()).toBeVisible({ timeout: 10_000 }); + }); + + await test.step('Verify chart SVG or empty-state is rendered', async () => { + // Recharts renders an ; when no data exists the component shows a skeleton or placeholder + const chartSection = page + .locator('section[aria-labelledby="stats-section-heading"]') + .or(page.getByRole('main')); + + const hasSvg = await chartSection.locator('svg').count() > 0; + const hasChartText = await page.getByText(/traffic volume/i).isVisible().catch(() => false); + + expect(hasSvg || hasChartText).toBeTruthy(); + }); + + await test.step('Verify SVG line path is rendered inside the chart', async () => { + // If the chart is showing the empty state, skip the SVG assertion + const hasEmptyState = await page.getByText(/no data available yet/i).isVisible().catch(() => false); + if (hasEmptyState) { + // Empty state is acceptable; just confirm the card is shown + await expect(page.getByText(/traffic volume/i).first()).toBeVisible(); + return; + } + + // When data is present, an SVG with recharts-line-curve path must exist + const svgLineCount = await page.locator('.recharts-line-curve').count(); + expect(svgLineCount).toBeGreaterThan(0); + }); + }); + + // ─── Top hosts chart ──────────────────────────────────────────────────────── + + test('should render the Top Hosts chart container', async ({ page }) => { + await test.step('Wait for statistics section', async () => { + await expect( + page.getByRole('heading', { name: /statistics/i }).or(page.locator('#stats-section-heading')).first() + ).toBeVisible({ timeout: 15_000 }); + }); + + await test.step('Verify Top Hosts chart card heading is visible', async () => { + const topHostsCard = page.getByText(/top hosts/i); + await expect(topHostsCard.first()).toBeVisible({ timeout: 10_000 }); + }); + }); + + // ─── Status distribution chart ────────────────────────────────────────────── + + test('should render the Status Distribution chart container', async ({ page }) => { + await test.step('Wait for statistics section', async () => { + await expect( + page.getByRole('heading', { name: /statistics/i }).or(page.locator('#stats-section-heading')).first() + ).toBeVisible({ timeout: 15_000 }); + }); + + await test.step('Verify Status Distribution chart card heading is visible', async () => { + const statusCard = page.getByText(/status distribution/i); + await expect(statusCard.first()).toBeVisible({ timeout: 10_000 }); + }); + }); + + // ─── Accessibility snapshot ───────────────────────────────────────────────── + + test('should expose all stats selector controls as accessible radio buttons', async ({ page }) => { + await test.step('Wait for statistics section', async () => { + await expect( + page.getByRole('heading', { name: /statistics/i }).or(page.locator('#stats-section-heading')).first() + ).toBeVisible({ timeout: 15_000 }); + }); + + await test.step('Verify period selector group has accessible radio options', async () => { + const periodGroup = page.getByRole('group', { name: /select time period/i }); + await expect(periodGroup).toBeVisible(); + + const radios = periodGroup.getByRole('radio'); + await expect(radios).toHaveCount(3); + }); + + await test.step('Verify bucket selector group has accessible radio options', async () => { + const bucketGroup = page.getByRole('group', { name: /select bucket granularity/i }); + await expect(bucketGroup).toBeVisible(); + + const radios = bucketGroup.getByRole('radio'); + await expect(radios).toHaveCount(3); + }); + }); +});