feat: the admin Overview shows who is listening, downloads, the library and its disk, and the server's version, uptime and recent errors; a download waiting on you, a client not answering or a full disk count in its verdict (M504 #5627 #5628 #5629 #5630)

The version moves to internal/buildinfo, so /rest/ping reports the build
instead of "dev".

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

internal/api/admin_status.go

@@ -0,0 +1,229 @@
+package api
+
+import (
+	"net/http"
+	"syscall"
+	"time"
+
+	"git.fabledsword.com/bvandeusen/minstrel/internal/buildinfo"
+	"git.fabledsword.com/bvandeusen/minstrel/internal/db/dbq"
+	"git.fabledsword.com/bvandeusen/minstrel/internal/logging"
+)
+
+// The admin Overview's status sections (M504): after the verdict, who is
+// listening, what is downloading, what the library holds and how much room
+// it has, and how the server itself is doing. One read for the page, polled
+// while it is open.
+
+type listeningView struct {
+	Username    string `json:"username"`
+	TrackID     string `json:"track_id"`
+	Title       string `json:"title"`
+	ArtistName  string `json:"artist_name"`
+	AlbumID     string `json:"album_id"`
+	AlbumTitle  string `json:"album_title"`
+	DurationMs  int32  `json:"duration_ms"`
+	StartedAt   string `json:"started_at"`
+	Client      string `json:"client"`
+	DeviceClass string `json:"device_class"`
+}
+
+type listeningStatusView struct {
+	Now []listeningView `json:"now"`
+	// The last day: how many plays, by how many people, the latest when.
+	PlaysDay     int64   `json:"plays_day"`
+	ListenersDay int64   `json:"listeners_day"`
+	LastPlayAt   *string `json:"last_play_at"`
+}
+
+type downloadsStatusView struct {
+	Running       int64   `json:"running"`
+	NeedsYou      int64   `json:"needs_you"`
+	NeedsYouSince *string `json:"needs_you_since"`
+	ImportedDay   int64   `json:"imported_day"`
+	GivenUpDay    int64   `json:"given_up_day"`
+	// Live is the downloads not yet ended, the ones needing a person first.
+	Live        []downloadView   `json:"live"`
+	ClientsDown []clientDownView `json:"clients_down"`
+}
+
+// diskView is the filesystem one library folder, or the data folder, sits
+// on.
+type diskView struct {
+	Path string `json:"path"`
+	// Data marks Minstrel's own data folder (covers, fingerprints), beside
+	// the library's.
+	Data       bool   `json:"data,omitempty"`
+	TotalBytes uint64 `json:"total_bytes"`
+	FreeBytes  uint64 `json:"free_bytes"`
+	// Error says why the folder could not be read, which is itself the
+	// news: a drive that did not mount.
+	Error string `json:"error,omitempty"`
+}
+
+type libraryStatusView struct {
+	Tracks  int64      `json:"tracks"`
+	Albums  int64      `json:"albums"`
+	Artists int64      `json:"artists"`
+	Bytes   int64      `json:"bytes"`
+	Disks   []diskView `json:"disks"`
+}
+
+type serverErrorView struct {
+	At      string `json:"at"`
+	Message string `json:"message"`
+	Attrs   string `json:"attrs"`
+}
+
+type serverStatusView struct {
+	Version   string `json:"version"`
+	Channel   string `json:"channel"`
+	StartedAt string `json:"started_at"`
+	// Migration is the database schema's version, and Dirty whether its
+	// last migration stopped part way.
+	Migration int64 `json:"migration"`
+	Dirty     bool  `json:"dirty"`
+	// Errors is the newest few errors logged since the start, newest first;
+	// ErrorCount is all of them.
+	Errors     []serverErrorView `json:"errors"`
+	ErrorCount int64             `json:"error_count"`
+}
+
+type adminStatusView struct {
+	Listening listeningStatusView `json:"listening"`
+	Downloads downloadsStatusView `json:"downloads"`
+	Library   libraryStatusView   `json:"library"`
+	Server    serverStatusView    `json:"server"`
+}
+
+// overviewLiveDownloads is how many running downloads the Overview lists;
+// Activity has the rest.
+const overviewLiveDownloads = 5
+
+// overviewErrors is how many recent errors the Overview lists.
+const overviewErrors = 10
+
+// handleGetAdminStatus implements GET /api/admin/status.
+func (h *handlers) handleGetAdminStatus(w http.ResponseWriter, r *http.Request) {
+	q := dbq.New(h.pool)
+	ctx := r.Context()
+	var out adminStatusView
+
+	now, err := q.ListListeningNow(ctx)
+	if err != nil {
+		h.logger.Error("admin status: listening", "err", err)
+		writeAdminJSONErr(w, http.StatusInternalServerError, "server_error")
+		return
+	}
+	out.Listening.Now = make([]listeningView, 0, len(now))
+	for _, p := range now {
+		out.Listening.Now = append(out.Listening.Now, listeningView{
+			Username: p.Username, TrackID: uuidToString(p.TrackID), Title: p.TrackTitle,
+			ArtistName: p.ArtistName, AlbumID: uuidToString(p.AlbumID), AlbumTitle: p.AlbumTitle,
+			DurationMs: p.DurationMs, StartedAt: formatTimestamp(p.StartedAt),
+			Client: deref(p.ClientID), DeviceClass: deref(p.DeviceClass),
+		})
+	}
+	day, err := q.PlaysLastDay(ctx)
+	if err != nil {
+		h.logger.Error("admin status: plays", "err", err)
+		writeAdminJSONErr(w, http.StatusInternalServerError, "server_error")
+		return
+	}
+	out.Listening.PlaysDay, out.Listening.ListenersDay = day.Plays, day.Listeners
+	if day.LastAt.Valid {
+		at := formatTimestamp(day.LastAt)
+		out.Listening.LastPlayAt = &at
+	}
+
+	if err := h.downloadsStatus(r, q, &out.Downloads); err != nil {
+		h.logger.Error("admin status: downloads", "err", err)
+		writeAdminJSONErr(w, http.StatusInternalServerError, "server_error")
+		return
+	}
+
+	lib, err := q.LibraryStatus(ctx)
+	if err != nil {
+		h.logger.Error("admin status: library", "err", err)
+		writeAdminJSONErr(w, http.StatusInternalServerError, "server_error")
+		return
+	}
+	out.Library = libraryStatusView{Tracks: lib.Tracks, Albums: lib.Albums, Artists: lib.Artists,
+		Bytes: lib.Bytes, Disks: []diskView{}}
+	if h.importer != nil {
+		for _, root := range h.importer.Roots {
+			out.Library.Disks = append(out.Library.Disks, diskOf(root))
+		}
+	}
+	if h.dataDir != "" {
+		d := diskOf(h.dataDir)
+		d.Data = true
+		out.Library.Disks = append(out.Library.Disks, d)
+	}
+
+	out.Server = serverStatus(logging.Errors)
+	// golang-migrate's own table, outside sqlc's schema.
+	if err := h.pool.QueryRow(ctx, `SELECT version, dirty FROM schema_migrations LIMIT 1`).
+		Scan(&out.Server.Migration, &out.Server.Dirty); err != nil {
+		h.logger.Warn("admin status: migration version", "err", err)
+	}
+	writeJSON(w, http.StatusOK, out)
+}
+
+func (h *handlers) downloadsStatus(r *http.Request, q *dbq.Queries, out *downloadsStatusView) error {
+	st, err := q.DownloadsStatus(r.Context())
+	if err != nil {
+		return err
+	}
+	*out = downloadsStatusView{Running: st.Running, NeedsYou: st.NeedsYou,
+		ImportedDay: st.ImportedDay, GivenUpDay: st.GivenUpDay,
+		Live: []downloadView{}, ClientsDown: []clientDownView{}}
+	if st.NeedsYou > 0 && st.NeedsYouSince.Valid {
+		since := formatTimestamp(st.NeedsYouSince)
+		out.NeedsYouSince = &since
+	}
+	// ListGrabs puts the ones needing a person first, then the running ones.
+	rows, err := q.ListGrabs(r.Context(), dbq.ListGrabsParams{MaxRows: overviewLiveDownloads})
+	if err != nil {
+		return err
+	}
+	for _, g := range rows {
+		if !g.EndedAt.Valid {
+			out.Live = append(out.Live, downloadFrom(g))
+		}
+	}
+	down, err := q.ListClientsDown(r.Context())
+	if err != nil {
+		return err
+	}
+	for _, c := range down {
+		out.ClientsDown = append(out.ClientsDown, clientDownView{Client: c.Client, Detail: c.Detail,
+			Since: formatTimestamp(c.FirstSeen)})
+	}
+	return nil
+}
+
+// diskOf reads the size and free space of the filesystem path is on.
+func diskOf(path string) diskView {
+	var st syscall.Statfs_t
+	if err := syscall.Statfs(path, &st); err != nil {
+		return diskView{Path: path, Error: err.Error()}
+	}
+	bsize := uint64(st.Bsize)
+	return diskView{Path: path, TotalBytes: st.Blocks * bsize, FreeBytes: st.Bavail * bsize}
+}
+
+func serverStatus(ring *logging.ErrorRing) serverStatusView {
+	kept, total := ring.Snapshot()
+	v := serverStatusView{Version: buildinfo.Version, Channel: buildinfo.Channel,
+		StartedAt: buildinfo.Started.UTC().Format(time.RFC3339), ErrorCount: total,
+		Errors: make([]serverErrorView, 0, min(len(kept), overviewErrors))}
+	for i, e := range kept {
+		if i == overviewErrors {
+			break
+		}
+		v.Errors = append(v.Errors, serverErrorView{At: e.At.UTC().Format(time.RFC3339),
+			Message: e.Message, Attrs: e.Attrs})
+	}
+	return v
+}

internal/api/admin_status_test.go

@@ -0,0 +1,89 @@
+package api
+
+import (
+	"context"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"github.com/jackc/pgx/v5/pgtype"
+
+	"git.fabledsword.com/bvandeusen/minstrel/internal/buildinfo"
+	"git.fabledsword.com/bvandeusen/minstrel/internal/logging"
+)
+
+// openPlay records a play by user of track that started ago and has not
+// ended.
+func openPlay(t *testing.T, h *handlers, user, track pgtype.UUID, ago string) {
+	t.Helper()
+	ctx := context.Background()
+	var session pgtype.UUID
+	if err := h.pool.QueryRow(ctx,
+		`INSERT INTO play_sessions (user_id, started_at, last_event_at) VALUES ($1, now(), now()) RETURNING id`,
+		user).Scan(&session); err != nil {
+		t.Fatalf("session: %v", err)
+	}
+	if _, err := h.pool.Exec(ctx,
+		`INSERT INTO play_events (user_id, track_id, session_id, started_at, client_id)
+		 VALUES ($1, $2, $3, now() - $4::interval, 'web')`, user, track, session, ago); err != nil {
+		t.Fatalf("play: %v", err)
+	}
+}
+
+// The Overview's status (M504): a play still inside its track's length is
+// listening now; one long past it, never closed by its client, is not.
+func TestAdminStatus_ListeningAndServer(t *testing.T) {
+	h, pool := testHandlers(t)
+	truncateLibrary(t, pool)
+	admin := seedUser(t, pool, "admin", "pw", true)
+
+	fresh, _ := seedTrackOnDisk(t, h, "statusfresh") // 30 s long
+	stale, _ := seedTrackOnDisk(t, h, "statusstale")
+	openPlay(t, h, admin.ID, fresh.ID, "10 seconds")
+	openPlay(t, h, admin.ID, stale.ID, "1 hour")
+
+	req := withUser(httptest.NewRequest(http.MethodGet, "/api/admin/status", nil), admin)
+	w := httptest.NewRecorder()
+	h.handleGetAdminStatus(w, req)
+	if w.Code != http.StatusOK {
+		t.Fatalf("status %d: %s", w.Code, w.Body.String())
+	}
+	var got adminStatusView
+	if err := json.Unmarshal(w.Body.Bytes(), &got); err != nil {
+		t.Fatalf("decode: %v", err)
+	}
+
+	var sawFresh, sawStale bool
+	for _, p := range got.Listening.Now {
+		switch p.TrackID {
+		case uuidToString(fresh.ID):
+			sawFresh = true
+			if p.Username != admin.Username || p.Client != "web" || p.Title != "AdmQ Track statusfresh" {
+				t.Errorf("listening row = %+v", p)
+			}
+		case uuidToString(stale.ID):
+			sawStale = true
+		}
+	}
+	if !sawFresh || sawStale {
+		t.Errorf("listening now: fresh %v (want true), stale %v (want false)", sawFresh, sawStale)
+	}
+	if got.Listening.PlaysDay < 2 || got.Listening.LastPlayAt == nil {
+		t.Errorf("last day: plays %d, last %v", got.Listening.PlaysDay, got.Listening.LastPlayAt)
+	}
+
+	if got.Library.Tracks != 2 || got.Library.Albums != 2 || got.Library.Bytes != 10 {
+		t.Errorf("library = %+v, want 2 tracks, 2 albums, 10 bytes", got.Library)
+	}
+	if got.Downloads.Live == nil || got.Downloads.ClientsDown == nil || got.Library.Disks == nil {
+		t.Error("lists must be [], never null")
+	}
+
+	if got.Server.Version != buildinfo.Version || got.Server.StartedAt == "" || got.Server.Migration < 92 {
+		t.Errorf("server = %+v", got.Server)
+	}
+	if _, total := logging.Errors.Snapshot(); got.Server.ErrorCount != total {
+		t.Errorf("error count = %d, ring says %d", got.Server.ErrorCount, total)
+	}
+}

internal/api/api.go

@@ -238,6 +238,7 @@ func Mount(r chi.Router, pool *pgxpool.Pool, logger *slog.Logger, events *playev
 				admin.Delete("/acquisition/services/{code}/password", h.handleSetAcquisitionSecret("password"))
 				// The queues that wait on an admin, for the rail and the Overview (#5605).
 				admin.Get("/summary", h.handleGetAdminSummary)
+				admin.Get("/status", h.handleGetAdminStatus)
 				admin.Get("/requests", h.handleListAdminRequests)
 				admin.Post("/requests/{id}/approve", h.handleApproveRequest)
 				admin.Post("/requests/{id}/reject", h.handleRejectRequest)