feat: download lifecycle — stalled and failed downloads are given up and searched again; imported ones seed, then go (M502 #5523)

Ported from Fabled Librarian's System 104. A new lifecycle poller, every
ten minutes:
- a download the client fails is given up at once;
- one nobody shares, or still fetching its file list, past the stall
  setting (6 h) is asked for again three times, then given up;
- giving up removes the download with its files, holds the release back
  for a week (release_blocks.expires_at), ends the grab and searches the
  album again, with no limit per album;
- a running download the client stops listing for half an hour ends and is
  searched again, not held back; an empty list is not taken as gone;
- an imported download seeds to ratio 2.0 or 14 days, then is removed;
- a download the client would not remove is asked again every pass.

Every condition and act is one open row per (client, download, condition)
in download_interventions. Activity shows what is wrong with a download and
how often it was retried, why one ended, its seeding, and a banner for a
client that does not answer. A running download can be given up by hand
(set aside for good). The seed ratio, seed days and stall hours are on the
search settings card. The download client lookup moves to
acquire.DownloadClientFor, shared by the importer and the lifecycle.

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

internal/api/admin_import.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/importer"
+	"git.fabledsword.com/bvandeusen/minstrel/internal/lifecycle"
 )
 
 // Downloads and their imports (M502 #5522): the Wanted view's Activity tab,
@@ -40,6 +41,24 @@ type downloadView struct {
 	Files         []string           `json:"files"`
 	Skipped       int                `json:"skipped"`
 	RehomedFrom   string             `json:"rehomed_from,omitempty"`
+	// EndDetail says why an ended download ended (#5523).
+	EndDetail string `json:"end_detail"`
+	// Seeding: imported and still sharing; Ratio its share ratio as last
+	// read; SeedReleasedAt when it was removed once it had shared enough.
+	Seeding        bool    `json:"seeding"`
+	Ratio          float32 `json:"ratio"`
+	SeedReleasedAt *string `json:"seed_released_at"`
+	// Condition is what is wrong with it now, if anything.
+	Condition *conditionView `json:"condition"`
+}
+
+// conditionView is an open row of the intervention ledger: what was seen,
+// since when, and how many times it was retried.
+type conditionView struct {
+	Trigger string `json:"trigger"`
+	Detail  string `json:"detail"`
+	Retries int32  `json:"retries"`
+	Since   string `json:"since"`
 }
 
 func downloadFrom(g dbq.ListGrabsRow) downloadView {
@@ -48,6 +67,18 @@ func downloadFrom(g dbq.ListGrabsRow) downloadView {
 		Origin: g.Origin, GrabbedAt: formatTimestamp(g.GrabbedAt), EndReason: g.EndReason,
 		Progress: g.Progress, ImportState: g.ImportState, ImportReason: g.ImportReason,
 		ImportedFiles: g.ImportedFiles, Destination: g.Destination, Files: []string{},
+		EndDetail: g.EndDetail, Seeding: g.Seeding, Ratio: g.Ratio,
+	}
+	if g.SeedReleasedAt.Valid {
+		at := formatTimestamp(g.SeedReleasedAt)
+		v.SeedReleasedAt = &at
+	}
+	if g.Condition != nil {
+		v.Condition = &conditionView{Trigger: *g.Condition, Detail: deref(g.ConditionDetail),
+			Since: formatTimestamp(g.ConditionSince)}
+		if g.ConditionRetries != nil {
+			v.Condition.Retries = *g.ConditionRetries
+		}
 	}
 	if g.WantID.Valid {
 		id := uuidToString(g.WantID)
@@ -82,6 +113,14 @@ type downloadsPage struct {
 	Items  []downloadView `json:"items"`
 	Limit  int            `json:"limit"`
 	Offset int            `json:"offset"`
+	// ClientsDown are the download clients not answering now (#5523).
+	ClientsDown []clientDownView `json:"clients_down"`
+}
+
+type clientDownView struct {
+	Client string `json:"client"`
+	Detail string `json:"detail"`
+	Since  string `json:"since"`
 }
 
 // handleListDownloads implements GET /api/admin/downloads?offset=: running
@@ -97,13 +136,47 @@ func (h *handlers) handleListDownloads(w http.ResponseWriter, r *http.Request) {
 		writeErrWithLog(w, h.logger, "admin downloads: list", apierror.Internal(err))
 		return
 	}
-	out := downloadsPage{Items: make([]downloadView, 0, len(rows)), Limit: limit, Offset: offset}
+	down, err := dbq.New(h.pool).ListClientsDown(r.Context())
+	if err != nil {
+		writeErrWithLog(w, h.logger, "admin downloads: clients down", apierror.Internal(err))
+		return
+	}
+	out := downloadsPage{Items: make([]downloadView, 0, len(rows)), Limit: limit, Offset: offset,
+		ClientsDown: make([]clientDownView, 0, len(down))}
 	for _, g := range rows {
 		out.Items = append(out.Items, downloadFrom(g))
 	}
+	for _, c := range down {
+		out.ClientsDown = append(out.ClientsDown, clientDownView{Client: c.Client, Detail: c.Detail,
+			Since: formatTimestamp(c.FirstSeen)})
+	}
 	writeJSON(w, http.StatusOK, out)
 }
 
+// handleAbandonDownload implements POST /api/admin/downloads/{id}/abandon: a
+// running download is given up, its release set aside, the download removed
+// and the album searched again.
+func (h *handlers) handleAbandonDownload(w http.ResponseWriter, r *http.Request) {
+	admin, ok := requireUser(w, r)
+	if !ok {
+		return
+	}
+	id, ok := requireURLUUID(w, r, "id")
+	if !ok {
+		return
+	}
+	if _, err := h.lifecycle.Abandon(r.Context(), id, admin.ID); err != nil {
+		switch {
+		case errors.Is(err, pgx.ErrNoRows), errors.Is(err, lifecycle.ErrNotAbandonable):
+			writeErr(w, apierror.Conflict("not_running", "that download is no longer running"))
+		default:
+			writeErrWithLog(w, h.logger, "admin downloads: abandon", apierror.Internal(err))
+		}
+		return
+	}
+	w.WriteHeader(http.StatusNoContent)
+}
+
 // handleImportAnyway implements POST /api/admin/downloads/{id}/import: a
 // download the check held for a person (or one that failed) is imported on
 // the next pass whatever the check says.
@@ -160,13 +233,16 @@ func (h *handlers) writeImportErr(w http.ResponseWriter, what string, err error)
 }
 
 type releaseBlockView struct {
-	InfoHash   string `json:"info_hash"`
-	Name       string `json:"name"`
-	Reason     string `json:"reason"`
-	Detail     string `json:"detail"`
-	BlockedAt  string `json:"blocked_at"`
-	WantTitle  string `json:"want_title"`
-	WantArtist string `json:"want_artist"`
+	InfoHash  string `json:"info_hash"`
+	Name      string `json:"name"`
+	Reason    string `json:"reason"`
+	Detail    string `json:"detail"`
+	BlockedAt string `json:"blocked_at"`
+	// ExpiresAt is when a release given up on may be taken again; null is
+	// for good (#5523).
+	ExpiresAt  *string `json:"expires_at"`
+	WantTitle  string  `json:"want_title"`
+	WantArtist string  `json:"want_artist"`
 }
 
 type releaseBlocksPage struct {
@@ -193,6 +269,10 @@ func (h *handlers) handleListReleaseBlocks(w http.ResponseWriter, r *http.Reques
 	for _, b := range rows {
 		v := releaseBlockView{InfoHash: b.InfoHash, Name: b.Name, Reason: b.Reason, Detail: b.Detail,
 			BlockedAt: formatTimestamp(b.BlockedAt)}
+		if b.ExpiresAt.Valid {
+			at := formatTimestamp(b.ExpiresAt)
+			v.ExpiresAt = &at
+		}
 		if b.WantTitle != nil {
 			v.WantTitle = *b.WantTitle
 		}

internal/api/admin_search.go

@@ -37,6 +37,12 @@ type searchSettingsView struct {
 	// is the first of ScanPaths, the library's folders.
 	ImportRoot string   `json:"import_root"`
 	ScanPaths  []string `json:"scan_paths"`
+	// The download lifecycle (#5523): seed an imported download to this
+	// ratio or for this many days; give up on one nobody shares after this
+	// many hours. 0 is: remove once imported, no time limit, never.
+	SeedRatio  float32 `json:"seed_ratio"`
+	SeedDays   int32   `json:"seed_days"`
+	StallHours int32   `json:"stall_hours"`
 }
 
 func searchSettings(s dbq.AcquisitionSetting, roots []string) searchSettingsView {
@@ -44,6 +50,7 @@ func searchSettings(s dbq.AcquisitionSetting, roots []string) searchSettingsView
 		AutoGrab: s.AutoGrab, SearchIntervalHours: s.SearchIntervalHours,
 		AllowedQualities: s.AllowedQualities, Tiers: release.Tiers, LastPass: s.LastPass,
 		ImportRoot: s.ImportRoot, ScanPaths: roots,
+		SeedRatio: s.SeedRatio, SeedDays: s.SeedDays, StallHours: s.StallHours,
 	}
 	if v.ScanPaths == nil {
 		v.ScanPaths = []string{}
@@ -76,6 +83,9 @@ type putSearchSettingsBody struct {
 	SearchIntervalHours int32    `json:"search_interval_hours"`
 	AllowedQualities    []string `json:"allowed_qualities"`
 	ImportRoot          string   `json:"import_root"`
+	SeedRatio           float32  `json:"seed_ratio"`
+	SeedDays            int32    `json:"seed_days"`
+	StallHours          int32    `json:"stall_hours"`
 }
 
 // handlePutSearchSettings implements PUT /api/admin/acquisition/settings.
@@ -102,9 +112,15 @@ func (h *handlers) handlePutSearchSettings(w http.ResponseWriter, r *http.Reques
 		writeErr(w, apierror.BadRequest("bad_import_root", "file new music into one of the library's folders"))
 		return
 	}
+	if body.SeedRatio < 0 || body.SeedRatio > 100 || body.SeedDays < 0 || body.SeedDays > 365 ||
+		body.StallHours < 0 || body.StallHours > 720 {
+		writeErr(w, apierror.BadRequest("bad_lifecycle",
+			"seed ratio must be 0 to 100, seed days 0 to 365 and stall hours 0 to 720"))
+		return
+	}
 	s, err := dbq.New(h.pool).UpdateAcquisitionSettings(r.Context(), dbq.UpdateAcquisitionSettingsParams{
 		AutoGrab: body.AutoGrab, SearchIntervalHours: body.SearchIntervalHours, AllowedQualities: body.AllowedQualities,
-		ImportRoot: body.ImportRoot,
+		ImportRoot: body.ImportRoot, SeedRatio: body.SeedRatio, SeedDays: body.SeedDays, StallHours: body.StallHours,
 	})
 	if err != nil {
 		writeErrWithLog(w, h.logger, "admin search settings: put", apierror.Internal(err))

internal/api/admin_wanted.go

@@ -62,6 +62,7 @@ type wantGrabView struct {
 	Progress      float32 `json:"progress"`
 	ImportState   string  `json:"import_state"`
 	ImportReason  string  `json:"import_reason"`
+	EndDetail     string  `json:"end_detail"`
 	ImportedAt    *string `json:"imported_at"`
 	ImportedFiles int32   `json:"imported_files"`
 }
@@ -164,7 +165,8 @@ func (h *handlers) handleListWants(w http.ResponseWriter, r *http.Request) {
 			v.Grab = &wantGrabView{ID: uuidToString(row.GrabID), Name: *row.GrabName,
 				GrabbedAt: formatTimestamp(row.GrabbedAt), Live: !row.GrabEndedAt.Valid,
 				Origin: deref(row.GrabOrigin), Quality: deref(row.GrabQuality), EndReason: deref(row.GrabEndReason),
-				ImportState: deref(row.GrabImportState), ImportReason: deref(row.GrabImportReason)}
+				ImportState: deref(row.GrabImportState), ImportReason: deref(row.GrabImportReason),
+				EndDetail: deref(row.GrabEndDetail)}
 			if row.GrabProgress != nil {
 				v.Grab.Progress = *row.GrabProgress
 			}

internal/api/api.go

@@ -23,6 +23,7 @@ import (
 	"git.fabledsword.com/bvandeusen/minstrel/internal/library"
 	"git.fabledsword.com/bvandeusen/minstrel/internal/lidarrconfig"
 	"git.fabledsword.com/bvandeusen/minstrel/internal/lidarrquarantine"
+	"git.fabledsword.com/bvandeusen/minstrel/internal/lifecycle"
 	"git.fabledsword.com/bvandeusen/minstrel/internal/mailer"
 	"git.fabledsword.com/bvandeusen/minstrel/internal/netsettings"
 	"git.fabledsword.com/bvandeusen/minstrel/internal/notifications"
@@ -80,6 +81,7 @@ func Mount(r chi.Router, pool *pgxpool.Pool, logger *slog.Logger, events *playev
 		wanted:              wanted.New(pool, cat, logger),
 		searcher:            wanted.NewSearcher(pool, cat, logger),
 		importer:            importer.New(pool, scanner, cat, nil, scannerRoots(scanner), logger),
+		lifecycle:           lifecycle.New(pool, logger),
 		catalogueSearches:   newSearchCache(),
 		catalogueArt:        catalogue.NewArt(dataDir, artSources(coverSettings)),
 		leveled:             newLeveledRenderer(dataDir, loudSettings, logger),
@@ -264,6 +266,7 @@ func Mount(r chi.Router, pool *pgxpool.Pool, logger *slog.Logger, events *playev
 				admin.Post("/downloads/{id}/import", h.handleImportAnyway)
 				admin.Post("/downloads/{id}/retry", h.handleRetryImport)
 				admin.Post("/downloads/{id}/refuse", h.handleRefuseDownload)
+				admin.Post("/downloads/{id}/abandon", h.handleAbandonDownload)
 				admin.Get("/follows", h.handleListFollows)
 				admin.Get("/follows/{mbid}", h.handleGetFollow)
 				admin.Put("/follows/{mbid}", h.handlePutFollow)
@@ -437,6 +440,9 @@ type handlers struct {
 	// importer refuses a download at a person's word (#5522). The import
 	// loop itself runs in main; this one only acts on a request.
 	importer *importer.Importer
+	// lifecycle gives up on a download at a person's word (#5523); its loop
+	// runs in main.
+	lifecycle *lifecycle.Service
 	// catalogueSearches reuses recent MusicBrainz answers; nil asks every
 	// time, which is what handler tests get.
 	catalogueSearches *searchCache