implement GET /api/v1/admin/status endpoint for system health monitoring

Author: diveshpatil9104

handlers.go

@@ -147,6 +147,27 @@ func buildFeed(vehicles []*VehicleState) *gtfs.FeedMessage {
 	return feed
 }
 
+type adminStatusResponse struct {
+	Status               string     `json:"status"`
+	UptimeSeconds        int64      `json:"uptime_seconds"`
+	ActiveVehicles       int        `json:"active_vehicles"`
+	TotalVehiclesTracked int        `json:"total_vehicles_tracked"`
+	LastUpdate           *time.Time `json:"last_update,omitempty"`
+}
+
+func handleAdminStatus(tracker *Tracker, startTime time.Time) http.HandlerFunc {
+	return func(w http.ResponseWriter, r *http.Request) {
+		ts := tracker.Status()
+		writeJSON(w, http.StatusOK, adminStatusResponse{
+			Status:               "ok",
+			UptimeSeconds:        int64(time.Since(startTime).Seconds()),
+			ActiveVehicles:       ts.ActiveVehicles,
+			TotalVehiclesTracked: ts.TotalVehiclesTracked,
+			LastUpdate:           ts.LastUpdate,
+		})
+	}
+}
+
 func writeJSON(w http.ResponseWriter, status int, v any) {
 	w.Header().Set("Content-Type", "application/json")
 	w.WriteHeader(status)

handlers_test.go

@@ -213,6 +213,87 @@ func TestHandlePostLocation_Validation(t *testing.T) {
 	}
 }
 
+func TestHandleAdminStatus_Empty(t *testing.T) {
+	tracker := NewTracker(5 * time.Minute)
+	defer tracker.Stop()
+
+	handler := handleAdminStatus(tracker, time.Now())
+	req := httptest.NewRequest("GET", "/api/v1/admin/status", nil)
+	w := httptest.NewRecorder()
+	handler(w, req)
+
+	assert.Equal(t, http.StatusOK, w.Code)
+	assert.Equal(t, "application/json", w.Header().Get("Content-Type"))
+
+	var resp adminStatusResponse
+	err := json.NewDecoder(w.Body).Decode(&resp)
+	require.NoError(t, err)
+
+	assert.Equal(t, "ok", resp.Status)
+	assert.Equal(t, 0, resp.ActiveVehicles)
+	assert.Equal(t, 0, resp.TotalVehiclesTracked)
+	assert.Nil(t, resp.LastUpdate)
+}
+
+func TestHandleAdminStatus_WithVehicles(t *testing.T) {
+	tracker := NewTracker(5 * time.Minute)
+	defer tracker.Stop()
+
+	tracker.Update(&LocationReport{VehicleID: "bus-1", Latitude: 1, Longitude: 2, Timestamp: 100})
+	tracker.Update(&LocationReport{VehicleID: "bus-2", Latitude: 3, Longitude: 4, Timestamp: 200})
+
+	handler := handleAdminStatus(tracker, time.Now())
+	req := httptest.NewRequest("GET", "/api/v1/admin/status", nil)
+	w := httptest.NewRecorder()
+	handler(w, req)
+
+	assert.Equal(t, http.StatusOK, w.Code)
+
+	var resp adminStatusResponse
+	err := json.NewDecoder(w.Body).Decode(&resp)
+	require.NoError(t, err)
+
+	assert.Equal(t, "ok", resp.Status)
+	assert.Equal(t, 2, resp.ActiveVehicles)
+	assert.Equal(t, 2, resp.TotalVehiclesTracked)
+	require.NotNil(t, resp.LastUpdate)
+	assert.False(t, resp.LastUpdate.IsZero())
+}
+
+func TestHandleAdminStatus_Uptime(t *testing.T) {
+	tracker := NewTracker(5 * time.Minute)
+	defer tracker.Stop()
+
+	startTime := time.Now().Add(-10 * time.Second)
+	handler := handleAdminStatus(tracker, startTime)
+	req := httptest.NewRequest("GET", "/api/v1/admin/status", nil)
+	w := httptest.NewRecorder()
+	handler(w, req)
+
+	var resp adminStatusResponse
+	err := json.NewDecoder(w.Body).Decode(&resp)
+	require.NoError(t, err)
+
+	assert.GreaterOrEqual(t, resp.UptimeSeconds, int64(10))
+}
+
+func TestHandleAdminStatus_ZeroVehiclesNotNull(t *testing.T) {
+	tracker := NewTracker(5 * time.Minute)
+	defer tracker.Stop()
+
+	handler := handleAdminStatus(tracker, time.Now())
+	req := httptest.NewRequest("GET", "/api/v1/admin/status", nil)
+	w := httptest.NewRecorder()
+	handler(w, req)
+
+	var raw map[string]any
+	err := json.NewDecoder(w.Body).Decode(&raw)
+	require.NoError(t, err)
+
+	assert.Equal(t, float64(0), raw["active_vehicles"])
+	assert.Equal(t, float64(0), raw["total_vehicles_tracked"])
+}
+
 type mockStore struct {
 	err   error
 	saved bool

main.go

@@ -47,9 +47,12 @@ func main() {
 		log.Printf("seeded tracker with %d active vehicles", len(recentLocations))
 	}
 
+	startTime := time.Now()
+
 	mux := http.NewServeMux()
 	mux.HandleFunc("POST /api/v1/locations", handlePostLocation(store, tracker))
 	mux.HandleFunc("GET /gtfs-rt/vehicle-positions", handleGetFeed(tracker))
+	mux.HandleFunc("GET /api/v1/admin/status", handleAdminStatus(tracker, startTime))
 	mux.HandleFunc("GET /health", func(w http.ResponseWriter, r *http.Request) {
 		writeJSON(w, http.StatusOK, map[string]string{"status": "ok"})
 	})

tracker.go

@@ -91,6 +91,35 @@ func (t *Tracker) ActiveVehicles() []*VehicleState {
 	return active
 }
 
+// TrackerStatus holds aggregate statistics about tracked vehicles.
+type TrackerStatus struct {
+	ActiveVehicles       int
+	TotalVehiclesTracked int
+	LastUpdate           *time.Time
+}
+
+// Status returns aggregate statistics with a single lock acquisition.
+func (t *Tracker) Status() TrackerStatus {
+	t.mu.RLock()
+	defer t.mu.RUnlock()
+	cutoff := time.Now().Add(-t.maxAge)
+	var s TrackerStatus
+	s.TotalVehiclesTracked = len(t.vehicles)
+	var latest time.Time
+	for _, v := range t.vehicles {
+		if v.UpdatedAt.After(cutoff) {
+			s.ActiveVehicles++
+		}
+		if v.UpdatedAt.After(latest) {
+			latest = v.UpdatedAt
+		}
+	}
+	if !latest.IsZero() {
+		s.LastUpdate = &latest
+	}
+	return s
+}
+
 // cleanup removes old entries from the tracker to prevent unbounded memory growth.
 func (t *Tracker) cleanup() {
 	t.mu.Lock()

tracker_test.go

@@ -148,6 +148,50 @@ func TestTracker_StopIsIdempotent(t *testing.T) {
 	assert.NotPanics(t, func() { tracker.Stop() })
 }
 
+func TestTracker_Status_Empty(t *testing.T) {
+	tracker := NewTracker(5 * time.Minute)
+	defer tracker.Stop()
+
+	s := tracker.Status()
+
+	assert.Equal(t, 0, s.ActiveVehicles)
+	assert.Equal(t, 0, s.TotalVehiclesTracked)
+	assert.Nil(t, s.LastUpdate)
+}
+
+func TestTracker_Status_WithActiveVehicles(t *testing.T) {
+	tracker := NewTracker(5 * time.Minute)
+	defer tracker.Stop()
+
+	tracker.Update(&LocationReport{VehicleID: "bus-1", Latitude: 1, Longitude: 2, Timestamp: 100})
+	tracker.Update(&LocationReport{VehicleID: "bus-2", Latitude: 3, Longitude: 4, Timestamp: 200})
+
+	s := tracker.Status()
+
+	assert.Equal(t, 2, s.ActiveVehicles)
+	assert.Equal(t, 2, s.TotalVehiclesTracked)
+	require.NotNil(t, s.LastUpdate)
+	assert.False(t, s.LastUpdate.IsZero())
+}
+
+func TestTracker_Status_WithStaleVehicles(t *testing.T) {
+	tracker := NewTracker(5 * time.Minute)
+	defer tracker.Stop()
+
+	tracker.Update(&LocationReport{VehicleID: "old-bus", Latitude: 1, Longitude: 2, Timestamp: 100})
+	tracker.mu.Lock()
+	tracker.vehicles["old-bus"].UpdatedAt = time.Now().Add(-10 * time.Minute)
+	tracker.mu.Unlock()
+
+	tracker.Update(&LocationReport{VehicleID: "new-bus", Latitude: 3, Longitude: 4, Timestamp: 200})
+
+	s := tracker.Status()
+
+	assert.Equal(t, 1, s.ActiveVehicles)
+	assert.Equal(t, 2, s.TotalVehiclesTracked)
+	require.NotNil(t, s.LastUpdate)
+}
+
 func TestTracker_CleanupPreservesFreshVehicles(t *testing.T) {
 	maxAge := 50 * time.Millisecond
 	tracker := NewTracker(maxAge)