feat(notifications): requests and flags reach the people who act on them (#5340)

- A new request still pending after any auto-approval notifies the
  admins (request_pending), but not the requester if they are an admin.
  A request that dedups into one already in flight is not announced again.
- Approving or rejecting a request notifies the requester, and a
  rejection carries the admin's notes as the reason. An admin deciding
  their own request gets nothing.
- The reconciler notifies the requester when their request arrives
  (request_completed), linking the matched album or artist.
- A request the re-acquisition sweeper files and cannot approve itself
  notifies the admins.
- A quarantine flag notifies every admin except the flagger, naming the
  track, the flagger and the reason.

lidarrrequests.Service.CreateTracked reports whether a request was
inserted or deduped; Create wraps it.

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

internal/api/admin_requests.go

@@ -12,6 +12,7 @@ import (
 	"git.fabledsword.com/bvandeusen/minstrel/internal/db/dbq"
 	"git.fabledsword.com/bvandeusen/minstrel/internal/lidarr"
 	"git.fabledsword.com/bvandeusen/minstrel/internal/lidarrrequests"
+	"git.fabledsword.com/bvandeusen/minstrel/internal/notifications"
 )
 
 // validRequestStatuses is the set of allowed values for the ?status= param.
@@ -125,6 +126,7 @@ func (h *handlers) handleApproveRequest(w http.ResponseWriter, r *http.Request)
 		return
 	}
 
+	h.notifyRequestDecided(r.Context(), notifications.KindRequestApproved, admin, row, "")
 	h.publishRequestStatusChanged(row)
 	writeJSON(w, http.StatusOK, requestViewFrom(row))
 }
@@ -165,6 +167,7 @@ func (h *handlers) handleRejectRequest(w http.ResponseWriter, r *http.Request) {
 		return
 	}
 
+	h.notifyRequestDecided(r.Context(), notifications.KindRequestRejected, admin, row, body.Notes)
 	h.publishRequestStatusChanged(row)
 	writeJSON(w, http.StatusOK, requestViewFrom(row))
 }

internal/api/api.go

@@ -23,6 +23,7 @@ import (
 	"git.fabledsword.com/bvandeusen/minstrel/internal/lidarrrequests"
 	"git.fabledsword.com/bvandeusen/minstrel/internal/mailer"
 	"git.fabledsword.com/bvandeusen/minstrel/internal/netsettings"
+	"git.fabledsword.com/bvandeusen/minstrel/internal/notifications"
 	"git.fabledsword.com/bvandeusen/minstrel/internal/playevents"
 	"git.fabledsword.com/bvandeusen/minstrel/internal/playlists"
 	"git.fabledsword.com/bvandeusen/minstrel/internal/reacquisition"
@@ -61,6 +62,7 @@ func Mount(r chi.Router, pool *pgxpool.Pool, logger *slog.Logger, events *playev
 		dataDir:             dataDir,
 		mailer:              sender,
 		eventbus:            bus,
+		notifier:            notifications.New(pool, bus, logger.With("component", "notifications")),
 		playlistScheduler:   playlistScheduler,
 		streamSecret:        streamSecret,
 		netSettings:         netSettings,
@@ -333,20 +335,23 @@ type handlers struct {
 	// librarySize memoises the track count that sizes the candidate pool
 	// (#3880). Held here rather than counted per request: the count is a
 	// full table scan, and library size only moves when a scan runs.
-	librarySize       *recommendation.LibrarySize
-	lidarrCfg         *lidarrconfig.Service
-	lidarrRequests    *lidarrrequests.Service
-	lidarrQuarantine  *lidarrquarantine.Service
-	tracks            *tracks.Service
-	playlists         *playlists.Service
-	coverart          *coverart.Enricher
-	coverSettings     *coverart.SettingsService
-	tagSettings       *tags.SettingsService
-	scanner           *library.Scanner
-	scanCfg           library.RunScanConfig
-	dataDir           string
-	mailer            mailer.Sender
-	eventbus          *eventbus.Bus
+	librarySize      *recommendation.LibrarySize
+	lidarrCfg        *lidarrconfig.Service
+	lidarrRequests   *lidarrrequests.Service
+	lidarrQuarantine *lidarrquarantine.Service
+	tracks           *tracks.Service
+	playlists        *playlists.Service
+	coverart         *coverart.Enricher
+	coverSettings    *coverart.SettingsService
+	tagSettings      *tags.SettingsService
+	scanner          *library.Scanner
+	scanCfg          library.RunScanConfig
+	dataDir          string
+	mailer           mailer.Sender
+	eventbus         *eventbus.Bus
+	// notifier writes the notifications inbox (M489). Nil-safe: a nil
+	// notifier records nothing, which is what most handler tests want.
+	notifier          *notifications.Notifier
 	playlistScheduler *playlists.Scheduler
 	// reacqSettings is the DB-backed policy for auto re-acquisition of
 	// missing files (milestone #290) — grace window, backoff, attempt caps.

internal/api/auth_test.go

@@ -27,6 +27,7 @@ import (
 	"git.fabledsword.com/bvandeusen/minstrel/internal/lidarrquarantine"
 	"git.fabledsword.com/bvandeusen/minstrel/internal/lidarrrequests"
 	"git.fabledsword.com/bvandeusen/minstrel/internal/mailer"
+	"git.fabledsword.com/bvandeusen/minstrel/internal/notifications"
 	"git.fabledsword.com/bvandeusen/minstrel/internal/playevents"
 	"git.fabledsword.com/bvandeusen/minstrel/internal/playlists"
 	"git.fabledsword.com/bvandeusen/minstrel/internal/recsettings"
@@ -72,7 +73,7 @@ func testHandlers(t *testing.T) (*handlers, *pgxpool.Pool) {
 	dataDir := t.TempDir()
 	tracksSvc := tracks.NewService(pool, logger, nil, dataDir)
 	playlistsSvc := playlists.NewService(pool, logger, dataDir)
-	h := &handlers{pool: pool, logger: logger, events: w, recCfg: recCfg, recSettings: recSettings, rng: func() float64 { return 0.5 }, lidarrCfg: lidarrCfg, lidarrRequests: lidarrReqs, lidarrQuarantine: lidarrQuar, tracks: tracksSvc, playlists: playlistsSvc, dataDir: dataDir, scanner: nil, scanCfg: library.RunScanConfig{}, mailer: &mailer.FakeSender{}}
+	h := &handlers{pool: pool, logger: logger, events: w, recCfg: recCfg, recSettings: recSettings, rng: func() float64 { return 0.5 }, lidarrCfg: lidarrCfg, lidarrRequests: lidarrReqs, lidarrQuarantine: lidarrQuar, tracks: tracksSvc, playlists: playlistsSvc, dataDir: dataDir, scanner: nil, scanCfg: library.RunScanConfig{}, mailer: &mailer.FakeSender{}, notifier: notifications.New(pool, nil, nil)}
 	return h, pool
 }
 

internal/api/notify_producers.go

@@ -0,0 +1,73 @@
+package api
+
+import (
+	"context"
+
+	"github.com/jackc/pgx/v5/pgtype"
+
+	"git.fabledsword.com/bvandeusen/minstrel/internal/db/dbq"
+	"git.fabledsword.com/bvandeusen/minstrel/internal/lidarrrequests"
+	"git.fabledsword.com/bvandeusen/minstrel/internal/notifications"
+)
+
+// Helpers for the handlers that produce notifications (M489). Every call is
+// NotifyLogged: a notification never fails the action that caused it.
+
+// userLabel is how a user is named to someone else: their display name, or
+// their username when they have none.
+func userLabel(u dbq.User) string {
+	if u.DisplayName != nil && *u.DisplayName != "" {
+		return *u.DisplayName
+	}
+	return u.Username
+}
+
+func requestPayload(row dbq.LidarrRequest) notifications.Payload {
+	return notifications.Payload{
+		RequestID:   uuidToString(row.ID),
+		RequestKind: string(row.Kind),
+		Name:        lidarrrequests.DisplayName(row),
+	}
+}
+
+// notifyRequestDecided tells the requester an admin approved or declined
+// their request. An admin deciding their own request needs no notice.
+func (h *handlers) notifyRequestDecided(ctx context.Context, kind notifications.Kind, admin dbq.User, row dbq.LidarrRequest, reason string) {
+	if row.UserID == admin.ID {
+		return
+	}
+	p := requestPayload(row)
+	p.Reason = reason
+	h.notifier.NotifyLogged(ctx, kind, notifications.ToUser(row.UserID), p.Map())
+}
+
+// quarantineReasonLabel is a flag reason as the flag popover words it, in
+// lower case to sit inside a sentence ("flagged X: bad rip").
+func quarantineReasonLabel(reason string) string {
+	switch reason {
+	case "bad_rip":
+		return "bad rip"
+	case "wrong_file":
+		return "wrong file"
+	case "wrong_tags":
+		return "wrong tags"
+	case "duplicate":
+		return "duplicate"
+	default:
+		return ""
+	}
+}
+
+// trackLabel names a track "Artist – Title" for a notification, falling back
+// to the title alone, or to nothing, rather than failing the caller.
+func (h *handlers) trackLabel(ctx context.Context, trackID pgtype.UUID) string {
+	q := dbq.New(h.pool)
+	t, err := q.GetTrackByID(ctx, trackID)
+	if err != nil {
+		return ""
+	}
+	if a, aerr := q.GetArtistByID(ctx, t.ArtistID); aerr == nil && a.Name != "" {
+		return a.Name + " – " + t.Title
+	}
+	return t.Title
+}

internal/api/notify_producers_test.go

@@ -0,0 +1,212 @@
+package api
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+
+	"github.com/jackc/pgx/v5/pgxpool"
+
+	"git.fabledsword.com/bvandeusen/minstrel/internal/db/dbq"
+	"git.fabledsword.com/bvandeusen/minstrel/internal/notifications"
+)
+
+// inboxItem is one thing the notifier left for one user: kind and decoded payload,
+// newest first.
+type inboxItem struct {
+	Kind    string
+	Payload notifications.Payload
+}
+
+func inboxOf(t *testing.T, pool *pgxpool.Pool, user dbq.User) []inboxItem {
+	t.Helper()
+	rows, err := dbq.New(pool).ListNotifications(context.Background(), dbq.ListNotificationsParams{
+		UserID: user.ID, PageLimit: 100,
+	})
+	if err != nil {
+		t.Fatalf("list notifications: %v", err)
+	}
+	out := make([]inboxItem, 0, len(rows))
+	for _, r := range rows {
+		var p notifications.Payload
+		if err := json.Unmarshal(r.Payload, &p); err != nil {
+			t.Fatalf("payload %s: %v", r.Payload, err)
+		}
+		out = append(out, inboxItem{Kind: r.Kind, Payload: p})
+	}
+	return out
+}
+
+func wantInbox(t *testing.T, who string, got []inboxItem, kinds ...notifications.Kind) {
+	t.Helper()
+	if len(got) != len(kinds) {
+		t.Fatalf("%s inbox = %+v, want kinds %v", who, got, kinds)
+	}
+	for i, k := range kinds {
+		if got[i].Kind != string(k) {
+			t.Errorf("%s inbox[%d] = %q, want %q", who, i, got[i].Kind, k)
+		}
+	}
+}
+
+// newApprovingLidarrStub answers every Lidarr call an approval makes.
+func newApprovingLidarrStub(t *testing.T) *httptest.Server {
+	t.Helper()
+	stub := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "application/json")
+		switch {
+		case strings.Contains(r.URL.Path, "/metadataprofile"):
+			_, _ = w.Write([]byte(`[{"id":1,"name":"Standard"}]`))
+		case strings.Contains(r.URL.Path, "/qualityprofile"):
+			_, _ = w.Write([]byte(`[{"id":1,"name":"Lossless"}]`))
+		default:
+			_, _ = w.Write([]byte(`{"id":1}`))
+		}
+	}))
+	t.Cleanup(stub.Close)
+	return stub
+}
+
+func TestNotify_NewRequestReachesOtherAdminsOnce(t *testing.T) {
+	h, pool := testHandlers(t)
+	resetLidarrState(t, h)
+
+	alice := seedUser(t, pool, "np-alice", "pw", false)
+	admin := seedUser(t, pool, "np-admin", "pw", true)
+	selfAdmin := seedUser(t, pool, "np-self", "pw", true)
+
+	rv := createArtistRequest(t, h, alice, "np-mbid-1", "Pending Band")
+	// The same request again dedups into the first and is not announced twice.
+	createArtistRequest(t, h, alice, "np-mbid-1", "Pending Band")
+
+	got := inboxOf(t, pool, admin)
+	wantInbox(t, "admin", got, notifications.KindRequestPending)
+	if got[0].Payload.RequestID != uuidToString(rv.ID) || got[0].Payload.Name != "Pending Band" || got[0].Payload.Actor != alice.Username {
+		t.Errorf("pending payload = %+v", got[0].Payload)
+	}
+	wantInbox(t, "requester", inboxOf(t, pool, alice))
+
+	// An admin's own request goes to the other admins, never back to them.
+	createArtistRequest(t, h, selfAdmin, "np-mbid-2", "Own Band")
+	wantInbox(t, "self-admin", inboxOf(t, pool, selfAdmin), notifications.KindRequestPending)
+	if n := len(inboxOf(t, pool, admin)); n != 2 {
+		t.Errorf("admin inbox = %d, want 2 (alice's and the self-admin's)", n)
+	}
+}
+
+func TestNotify_AutoApprovedRequestWaitsOnNobody(t *testing.T) {
+	h, _ := testHandlersWithClientFn(t)
+	resetLidarrState(t, h)
+	saveLidarrConfig(t, h, newApprovingLidarrStub(t).URL, true)
+
+	alice := seedUser(t, h.pool, "np-auto", "pw", false)
+	admin := seedUser(t, h.pool, "np-auto-admin", "pw", true)
+	if _, err := h.pool.Exec(context.Background(),
+		"UPDATE users SET auto_approve_requests = true WHERE id = $1", alice.ID); err != nil {
+		t.Fatalf("set auto_approve: %v", err)
+	}
+	alice, err := dbq.New(h.pool).GetUserByID(context.Background(), alice.ID)
+	if err != nil {
+		t.Fatalf("reload user: %v", err)
+	}
+
+	rv := createArtistRequest(t, h, alice, "np-auto-mbid", "Auto Band")
+	if rv.Status != "approved" {
+		t.Fatalf("status = %q, want approved — the stub should accept the add", rv.Status)
+	}
+	wantInbox(t, "admin", inboxOf(t, h.pool, admin))
+	wantInbox(t, "requester", inboxOf(t, h.pool, alice))
+}
+
+func TestNotify_DecisionsReachTheRequester(t *testing.T) {
+	h, _ := testHandlersWithClientFn(t)
+	resetLidarrState(t, h)
+	saveLidarrConfig(t, h, newApprovingLidarrStub(t).URL, true)
+
+	alice := seedUser(t, h.pool, "np-dec-alice", "pw", false)
+	admin := seedUser(t, h.pool, "np-dec-admin", "pw", true)
+
+	approved := seedPendingArtistRequest(t, h, alice, "np-dec-1", "Yes Band")
+	rejected := seedPendingArtistRequest(t, h, alice, "np-dec-2", "No Band")
+	own := seedPendingArtistRequest(t, h, admin, "np-dec-3", "Own Band")
+
+	for _, c := range []struct {
+		id   string
+		verb string
+		body []byte
+	}{
+		{uuidToString(approved.ID), "approve", nil},
+		{uuidToString(rejected.ID), "reject", []byte(`{"notes":"Only a live bootleg exists"}`)},
+		{uuidToString(own.ID), "approve", nil},
+	} {
+		w := doAdminRequestReq(t, h, http.MethodPost, "/api/admin/requests/"+c.id+"/"+c.verb, c.body, admin)
+		if w.Code != http.StatusOK {
+			t.Fatalf("%s %s: status = %d; body = %s", c.verb, c.id, w.Code, w.Body.String())
+		}
+	}
+
+	got := inboxOf(t, h.pool, alice)
+	wantInbox(t, "requester", got, notifications.KindRequestRejected, notifications.KindRequestApproved)
+	if got[0].Payload.Name != "No Band" || got[0].Payload.Reason != "Only a live bootleg exists" {
+		t.Errorf("rejected payload = %+v", got[0].Payload)
+	}
+	if got[1].Payload.Name != "Yes Band" || got[1].Payload.Reason != "" {
+		t.Errorf("approved payload = %+v", got[1].Payload)
+	}
+	// The admin decided their own request: no notice. alice's two pending
+	// notices are all the admin holds.
+	for _, it := range inboxOf(t, h.pool, admin) {
+		if it.Kind != string(notifications.KindRequestPending) {
+			t.Errorf("admin inbox holds %q, want only request_pending", it.Kind)
+		}
+	}
+}
+
+func TestNotify_FlagReachesAdminsButNotTheFlagger(t *testing.T) {
+	h, pool := testHandlers(t)
+	truncateLibrary(t, pool)
+
+	alice := seedUser(t, pool, "np-flag-alice", "pw", false)
+	admin := seedUser(t, pool, "np-flag-admin", "pw", true)
+	other := seedUser(t, pool, "np-flag-other", "pw", true)
+	track := seedQuarantineTrack(t, h, "np")
+
+	w := doFlag(h, alice, fmt.Sprintf(`{"track_id":%q,"reason":"bad_rip"}`, uuidToString(track.ID)))
+	if w.Code != http.StatusCreated {
+		t.Fatalf("flag: status = %d; body = %s", w.Code, w.Body.String())
+	}
+	got := inboxOf(t, pool, admin)
+	wantInbox(t, "admin", got, notifications.KindQuarantineFlagged)
+	if p := got[0].Payload; p.Name != "Q Artist np – Q Track np" || p.Actor != alice.Username || p.Reason != "bad rip" {
+		t.Errorf("flag payload = %+v", p)
+	}
+	wantInbox(t, "flagger", inboxOf(t, pool, alice))
+
+	// An admin flagging a track tells the other admins only.
+	track2 := seedQuarantineTrack(t, h, "np2")
+	w = doFlag(h, admin, fmt.Sprintf(`{"track_id":%q,"reason":"other"}`, uuidToString(track2.ID)))
+	if w.Code != http.StatusCreated {
+		t.Fatalf("admin flag: status = %d; body = %s", w.Code, w.Body.String())
+	}
+	if n := len(inboxOf(t, pool, admin)); n != 1 {
+		t.Errorf("flagging admin inbox = %d, want 1 (alice's flag only)", n)
+	}
+	if n := len(inboxOf(t, pool, other)); n != 2 {
+		t.Errorf("other admin inbox = %d, want 2", n)
+	}
+}
+
+func TestQuarantineReasonLabel(t *testing.T) {
+	for in, want := range map[string]string{
+		"bad_rip": "bad rip", "wrong_file": "wrong file", "wrong_tags": "wrong tags",
+		"duplicate": "duplicate", "other": "", "": "",
+	} {
+		if got := quarantineReasonLabel(in); got != want {
+			t.Errorf("quarantineReasonLabel(%q) = %q, want %q", in, got, want)
+		}
+	}
+}

internal/api/quarantine.go

@@ -9,6 +9,7 @@ import (
 	"git.fabledsword.com/bvandeusen/minstrel/internal/apierror"
 	"git.fabledsword.com/bvandeusen/minstrel/internal/db/dbq"
 	"git.fabledsword.com/bvandeusen/minstrel/internal/lidarrquarantine"
+	"git.fabledsword.com/bvandeusen/minstrel/internal/notifications"
 )
 
 // quarantineView is the JSON shape returned by the user-facing endpoints
@@ -70,6 +71,10 @@ func (h *handlers) handleFlag(w http.ResponseWriter, r *http.Request) {
 	// Broadcast: the flagging user's other clients invalidate their
 	// Hidden tab; admins' clients invalidate their quarantine queue.
 	h.publishQuarantineEvent("quarantine.flagged", user.ID, trackID, true)
+	// Admins review flags (M489). An admin flagging a track needs no notice
+	// of their own flag.
+	h.notifier.NotifyLogged(r.Context(), notifications.KindQuarantineFlagged, notifications.ToAdmins(user.ID),
+		notifications.Payload{Name: h.trackLabel(r.Context(), trackID), Actor: userLabel(user), Reason: quarantineReasonLabel(body.Reason)}.Map())
 	writeJSON(w, http.StatusCreated, quarantineViewFrom(row))
 }
 

internal/api/requests.go

@@ -10,6 +10,7 @@ import (
 	"git.fabledsword.com/bvandeusen/minstrel/internal/apierror"
 	"git.fabledsword.com/bvandeusen/minstrel/internal/db/dbq"
 	"git.fabledsword.com/bvandeusen/minstrel/internal/lidarrrequests"
+	"git.fabledsword.com/bvandeusen/minstrel/internal/notifications"
 )
 
 // requestView is the JSON shape returned by all /api/requests handlers.
@@ -130,7 +131,7 @@ func (h *handlers) handleCreateRequest(w http.ResponseWriter, r *http.Request) {
 		return
 	}
 
-	row, err := h.lidarrRequests.Create(r.Context(), user.ID, lidarrrequests.CreateParams{
+	row, created, err := h.lidarrRequests.CreateTracked(r.Context(), user.ID, lidarrrequests.CreateParams{
 		Kind:             body.Kind,
 		LidarrArtistMBID: body.LidarrArtistMBID,
 		LidarrAlbumMBID:  body.LidarrAlbumMBID,
@@ -175,6 +176,16 @@ func (h *handlers) handleCreateRequest(w http.ResponseWriter, r *http.Request) {
 		}
 	}
 
+	// A new request still pending after any auto-approval waits on an admin
+	// (M489). One that deduped into a request already in flight was
+	// announced when it was first made, and the requester, if they are an
+	// admin themselves, needs no notice of their own request.
+	if created && row.Status == dbq.LidarrRequestStatusPending {
+		p := requestPayload(row)
+		p.Actor = userLabel(user)
+		h.notifier.NotifyLogged(r.Context(), notifications.KindRequestPending, notifications.ToAdmins(user.ID), p.Map())
+	}
+
 	h.publishRequestStatusChanged(row)
 	writeJSON(w, http.StatusCreated, requestViewFrom(row))
 }