feat: choose an artist's portrait from a Deezer search

docs/rfcs/RFC-013-chosen-artist-imagery.md

@@ -5,10 +5,14 @@
   below: [#308](https://github.com/InstaZDLL/waveflow-server/pull/308) (this
   RFC), [#309](https://github.com/InstaZDLL/waveflow-server/pull/309)
   (serving the choice: `artist_image_choice`, the effective portrait,
-  `banner_hash`, the upload and removal routes) and
+  `banner_hash`, the upload and removal routes),
   [#310](https://github.com/InstaZDLL/waveflow-server/pull/310) (drawing it in
   the web client: the banner behind the artist header, and "Change
-  portrait" / "Change banner" for owners and managers). The
+  portrait" / "Change banner" for owners and managers) and
+  [#311](https://github.com/InstaZDLL/waveflow-server/pull/311) (Deezer
+  candidates: the search and candidate tables, the candidates route with
+  server-held previews, the pick checked against a live search, and "Search
+  Deezer" in the web client). The
   *Status* field above never flips in this project; this line is the one that
   says what is running.
 - **Date**: 2026-10-23
@@ -160,9 +164,12 @@ So the server does the looking:
   id, a name, a fan count — **without picture URLs**;
 - each candidate's picture is fetched by the server through `src/portrait.rs`'s
   narrow fetcher (https, host allowlist, public addresses only, pinned
-  resolution, 10 MiB) into the artwork store, at Deezer's small picture size,
-  and the candidate carries its `artwork_hash`. The client shows previews from
-  the server, never from Deezer;
+  resolution, 10 MiB) into the artwork store, at Deezer's big picture size
+  (500 pixels) — not the small one, since the preview is what a pick makes the
+  portrait — and the candidate carries its `artwork_hash`. A hit with no real
+  picture (Deezer's placeholder) is not offered, nor one whose picture the
+  fetcher refuses for what it is: there would be nothing to choose. The client
+  shows previews from the server, never from Deezer;
 - choosing one writes the choice with `source = 'deezer'` from a candidate the
   server fetched. The client sends a Deezer id; it never sends a URL, so no
   user input ever names a target the server dereferences — #217's line holds.
@@ -254,9 +261,10 @@ CREATE TABLE artist_image_candidate (
     the handler with it, mid-await, running none of its remaining code — but
     not the task, which goes on to complete the search or delete it. The next
     picker that asks the same query finds it complete;
-  - a search whose Deezer query or any preview fetch fails is **deleted** by
-    that task. Its candidates go by cascade, and the previews already stored
-    become unreferenced artwork for the sweep;
+  - a search whose Deezer query fails, or whose picture host cannot be
+    reached for any preview, is **deleted** by that task. Its candidates go by
+    cascade, and the previews already stored become unreferenced artwork for
+    the sweep;
   - **a deadline the task itself obeys.** Every search gets a fetch deadline,
     `searched_at` plus five minutes, and its task runs under that deadline as
     a whole — waiting for the provider's pace, which it shares with enrichment
@@ -299,8 +307,10 @@ in **one transaction** each.
   the task writing its candidates. Its ways out are the ones named above: its
   task completes it or deletes it, the sweep deletes it once past its fetch
   deadline — which no running task can be — or boot deletes it. The previews
-  an incomplete search has stored so far are named by its candidates, so the
-  sweep keeps them too until one of those happens.
+  an incomplete search has stored so far have no row yet: their rows and the
+  candidates naming them are written together, in the transaction that
+  completes the search. Until then the files are kept by the sweep's write
+  grace — an hour, against a fetch deadline of five minutes.
 - If anything ever slipped through, the foreign key from
   `artist_image_choice.artwork_hash` to `artwork` fails the insert rather than
   storing a dangling hash; the route answers `422`, as for an expired search,
@@ -355,7 +365,7 @@ caller may not see, and for a write by someone who may not make it.
 | `GET /artists/{id}` | Gains `banner_hash` (absent when none), and `image_choice` per kind (`source`, `set_at`) so a client can say "chosen by hand" instead of "from Deezer". `artwork_hash` becomes the effective portrait. |
 | `PUT /artists/{id}/image/{kind}` | `kind` is `portrait` or `banner`. The body is the image's bytes. `200` with the artist; `413` past 10 MiB; `422` for bytes that are not JPEG, PNG or WebP. |
 | `PUT /artists/{id}/image/portrait/deezer` | `{ "deezer_id": … }`, offered by a live search of this artist; that candidate's preview becomes the portrait, never fetched again. `422` for an id no live search offered; `404` where Deezer is not configured now, a live search notwithstanding. |
-| `GET /artists/{id}/image/candidates?q=` | Owners and managers only. Up to 20 Deezer artists, each with a server-held preview `artwork_hash`, stored as a search for an hour; the same query answered from it while it lives. `429` while the same account's previous search is still fetching; `404` where Deezer is not configured. |
+| `GET /artists/{id}/image/candidates?q=` | Owners and managers only. Up to 20 Deezer artists, each with a server-held preview `artwork_hash`, stored as a search for an hour; the same query answered from it while it lives. `429` while the same account's previous search is still fetching; `404` where Deezer is not configured; `422` for an empty query; `503` when Deezer or a picture host could not be reached. Each preview is served by `GET /artwork/{hash}` to the owners and managers of the artist's library. |
 | `DELETE /artists/{id}/image/{kind}` | Back to automatic. `204`; `404` when nothing was chosen. |
 
 Every write goes through `DomainServices` (CLAUDE.md, "One set of domain
@@ -365,7 +375,9 @@ services"), so the desktop can reach the same rules when it chooses to.
 
 - **RFC-011**: decision 11 gains a sentence naming this document as the one
   write path it does not cover.
-- **The artwork sweep** keeps hashes named by `artist_image_choice`.
+- **The artwork sweep** keeps hashes named by `artist_image_choice`, and from
+  step 4 those named by `artist_image_candidate`, once it has deleted the
+  spent searches in the same transaction.
 - **The Subsonic façade**: `coverArt` on an artist names the effective portrait.
   No element is added or removed.
 - **The desktop app** (`InstaZDLL/WaveFlow`): nothing in this repository. Its

migrations-v2/20261024000000_artist_image_search.sql

@@ -0,0 +1,45 @@
+-- A Deezer search for an artist's portrait, and what it offered (RFC-013
+-- decision 4).
+--
+-- The pick names a Deezer id and nothing else, so the server remembers what it
+-- offered: a search per artist and query, and its candidates in Deezer's
+-- order, each with the preview the server fetched. Keyed by the artist row,
+-- which is per library, so any owner or manager of that library may pick from
+-- it and no other library ever finds it.
+CREATE TABLE artist_image_search (
+    id TEXT PRIMARY KEY NOT NULL,
+    artist_id TEXT NOT NULL REFERENCES artist(id) ON DELETE CASCADE,
+    -- The query as typed, trimmed and case-folded: "Björk " and "björk" are
+    -- one search.
+    query_key TEXT NOT NULL,
+    searched_by TEXT NOT NULL,
+    searched_at INTEGER NOT NULL,
+    -- An hour from the moment the search completed; NULL while it fetches.
+    expires_at INTEGER,
+    -- Set when every candidate's preview is stored. 0 means a task is
+    -- fetching for it now: a failed search is deleted, a search past its
+    -- fetch deadline is swept, and boot deletes any left at 0. It is what
+    -- makes a second search by the account answer 429.
+    complete INTEGER NOT NULL DEFAULT 0 CHECK (complete IN (0, 1)),
+    CHECK ((complete = 1) = (expires_at IS NOT NULL))
+) STRICT;
+
+CREATE INDEX artist_image_search_artist ON artist_image_search(artist_id, query_key);
+CREATE INDEX artist_image_search_account ON artist_image_search(searched_by, complete);
+
+-- The preview names its artwork with no `ON DELETE`, as a choice does: the
+-- sweep keeps what a candidate names, and one that forgot would fail rather
+-- than leave a candidate pointing at nothing.
+CREATE TABLE artist_image_candidate (
+    search_id TEXT NOT NULL REFERENCES artist_image_search(id) ON DELETE CASCADE,
+    -- Deezer's order, so the answer reads as the search did.
+    position INTEGER NOT NULL,
+    deezer_id INTEGER NOT NULL,
+    name TEXT NOT NULL,
+    fans INTEGER,
+    artwork_hash TEXT NOT NULL REFERENCES artwork(hash),
+    PRIMARY KEY (search_id, position),
+    UNIQUE (search_id, deezer_id)
+) STRICT;
+
+CREATE INDEX artist_image_candidate_artwork ON artist_image_candidate(artwork_hash);

src/api/catalog.rs

@@ -390,3 +390,60 @@ pub async fn delete_artist_image(
         .map(|()| StatusCode::NO_CONTENT)
         .map_err(service_error)
 }
+
+#[derive(Debug, Deserialize)]
+pub struct CandidateQuery {
+    pub q: String,
+}
+
+/// Deezer's artists for `q`, offered as this artist's portrait (RFC-013): up
+/// to 20, each with a preview the server fetched and holds, and no picture
+/// URL. Stored as a search for an hour, and the same query answered from it
+/// while it lives. Owners and managers; `404` for anyone else and where
+/// Deezer is not configured; `429` while the account's previous search is
+/// still fetching; `503` when Deezer could not be reached.
+#[utoipa::path(get, path = "/api/v2/artists/{artist_id}/image/candidates", tag = "catalog", params(("artist_id" = Uuid, Path), ("q" = String, Query)), responses((status = 200, body = [crate::services::ArtistImageCandidate]), (status = 401, body = ErrorResponse), (status = 404, body = ErrorResponse), (status = 422, body = ErrorResponse), (status = 429, body = ErrorResponse), (status = 503, body = ErrorResponse)))]
+pub async fn list_artist_image_candidates(
+    State(state): State<AppState>,
+    Path(artist_id): Path<Uuid>,
+    Query(query): Query<CandidateQuery>,
+    headers: HeaderMap,
+) -> Result<Json<Vec<crate::services::ArtistImageCandidate>>, ApiError> {
+    let user = authenticated(&state, &headers, Access::Write).await?;
+    state
+        .services
+        .artist_image_candidates(user.id, artist_id, &query.q)
+        .await
+        .map(Json)
+        .map_err(service_error)
+}
+
+#[derive(Debug, Deserialize, ToSchema)]
+pub struct DeezerPortraitPick {
+    /// A Deezer artist id offered by a live search of this artist.
+    pub deezer_id: i64,
+}
+
+/// Chooses as the portrait the preview a live search of this artist offered
+/// for `deezer_id`, never fetched again. `422` for an id no live search of
+/// this artist offered; `404` where Deezer is not configured now.
+#[utoipa::path(put, path = "/api/v2/artists/{artist_id}/image/portrait/deezer", tag = "catalog", params(("artist_id" = Uuid, Path)), request_body = DeezerPortraitPick, responses((status = 200, body = crate::services::ArtistDetail), (status = 401, body = ErrorResponse), (status = 404, body = ErrorResponse), (status = 422, body = ErrorResponse)))]
+pub async fn put_artist_deezer_portrait(
+    State(state): State<AppState>,
+    Path(artist_id): Path<Uuid>,
+    headers: HeaderMap,
+    Json(pick): Json<DeezerPortraitPick>,
+) -> Result<Json<crate::services::ArtistDetail>, ApiError> {
+    let user = authenticated(&state, &headers, Access::Write).await?;
+    state
+        .services
+        .choose_deezer_portrait(user.id, artist_id, pick.deezer_id)
+        .await
+        .map_err(service_error)?;
+    state
+        .services
+        .artist_page(user.id, artist_id)
+        .await
+        .map(Json)
+        .map_err(service_error)
+}

src/api/error.rs

@@ -25,6 +25,8 @@ pub enum ApiError {
     /// a conflict means mint a new operation id, this one means discard the
     /// local projection and take a fresh snapshot.
     CursorExpired,
+    /// The caller's previous request of the same kind is still running.
+    TooManyRequests,
     Unavailable,
     NotFound,
 }
@@ -63,6 +65,11 @@ impl IntoResponse for ApiError {
                 "cursor_expired",
                 "The cursor precedes the oldest retained event; take a fresh snapshot",
             ),
+            Self::TooManyRequests => (
+                StatusCode::TOO_MANY_REQUESTS,
+                "too_many_requests",
+                "The previous request is still running",
+            ),
             Self::Unavailable => (
                 StatusCode::SERVICE_UNAVAILABLE,
                 "service_unavailable",
@@ -98,6 +105,7 @@ pub(super) fn service_error(error: crate::services::ServiceError) -> ApiError {
         ServiceError::NotFound | ServiceError::Forbidden => ApiError::NotFound,
         ServiceError::Invalid => ApiError::Validation,
         ServiceError::Conflict => ApiError::Conflict,
+        ServiceError::Busy => ApiError::TooManyRequests,
         ServiceError::Unavailable => ApiError::Unavailable,
         ServiceError::Database(error) => db_error(error),
         ServiceError::Security(error) => {

src/api/mod.rs

@@ -186,6 +186,10 @@ pub fn router(state: AppState) -> Router {
                 axum::extract::DefaultBodyLimit::max(crate::portrait::MAX_IMAGE_BYTES),
             ),
         )
+        .route(
+            "/api/v2/artists/{artist_id}/image/portrait/deezer",
+            put(put_artist_deezer_portrait),
+        )
         .route(
             "/api/v2/artists/{artist_id}/top-songs",
             get(list_artist_top_songs),
@@ -344,3 +348,25 @@ pub fn router(state: AppState) -> Router {
         )
         .with_state(state)
 }
+
+/// The one `/api/v2` route that may outlive the ordinary request timeout.
+///
+/// A Deezer portrait search (RFC-013) waits for the task fetching it, which
+/// runs for up to its own five-minute deadline at the provider's pace. Under
+/// the ordinary thirty seconds the client would get a `408` while the task
+/// went on, and its retry a `429` until the task ended. So it is merged beside
+/// the ordinary API rather than inside it, as the media routes are, under a
+/// timeout of its own just past that deadline: the request answers what the
+/// task did.
+pub fn search_router(state: AppState) -> Router {
+    Router::new()
+        .route(
+            "/api/v2/artists/{artist_id}/image/candidates",
+            get(list_artist_image_candidates),
+        )
+        .layer(tower_http::timeout::TimeoutLayer::with_status_code(
+            StatusCode::REQUEST_TIMEOUT,
+            crate::services::ARTIST_IMAGE_SEARCH_DEADLINE + Duration::from_secs(30),
+        ))
+        .with_state(state)
+}