feat(discovery): similar artists from Last.fm

- feat: GET /api/v1/artists/{id}/similar lists the artists Last.fm finds similar
  to one in the library, best first, each with the provider's own score and
  rank and a flag saying whether it is in the library. It answers 200 when the
  provider is off or failing, with provider_status, stale and retrieved_at
- feat: a thin Last.fm client on top of the outbound client. It always sends
  autocorrect=0 so a misspelled local name cannot turn into another artist,
  prefers the MusicBrainz id when known, always sets a limit, and reads the
  error field even when the status is 200. Errors never carry the URL or the
  provider's own message, because the key travels in the query string
- feat: results are stored in artist_similar with a freshness ledger in
  provider_fetches: 7 days for an answer, 1 day for "unknown artist". Old data
  is served when the provider fails, and concurrent requests for the same
  artist share one call that does not depend on the first caller staying
- feat: artists named by a provider but without files become artists without
  tracks. GET /artists/{id} can show them (track_count 0), the lists of the
  library never include them, and a later scan adopts them by name. A provider
  id is never written onto an existing artist; names match only when at least
  one side has no id, and different ids always mean different artists
- feat: POST /providers/{name}/test (admin) checks a stored key with one cheap
  request, whether the provider is on or off, and reports ok, no_api_key,
  key_refused, rate_limited, unreachable or error
- test: the whole request is checked from the receiving end, with a user, a
  listen, a title and a library path in the database: only the artist and the
  key leave, with a User-Agent that names the project
- docs: README and OpenAPI updated; the contract test calls the new operations
This commit is contained in:
tgiachi 2026-11-11 16:36:16 +01:00
commit aafb2dd906
2 changed files with 2651 additions and 19 deletions

View file

@ -0,0 +1,30 @@
-- What the discovery providers said about artists, kept as they said it.
--
-- artist_similar holds one row per "artist A is similar to artist B according to
-- provider P". similar_id can be an artist that has no files: such rows are how
-- music outside the library is known. score is the provider's own number and is
-- relative to the list it came in; rank is the position in that list (1 = first).
--
-- provider_fetches remembers when a provider was last asked about an artist and
-- what it answered ('ok' or 'not_found'), so a fresh answer is not asked again
-- and an unknown artist is not asked again at once.
CREATE TABLE artist_similar (
artist_id BIGINT NOT NULL REFERENCES artists(id) ON DELETE CASCADE,
provider TEXT NOT NULL,
similar_id BIGINT NOT NULL REFERENCES artists(id) ON DELETE CASCADE,
rank INTEGER NOT NULL,
score DOUBLE PRECISION NOT NULL,
PRIMARY KEY (artist_id, provider, similar_id)
);
CREATE INDEX idx_artist_similar_similar ON artist_similar(similar_id);
CREATE TABLE provider_fetches (
provider TEXT NOT NULL,
kind TEXT NOT NULL, -- what was asked: 'similar'
artist_id BIGINT NOT NULL REFERENCES artists(id) ON DELETE CASCADE,
status TEXT NOT NULL, -- 'ok' or 'not_found'
retrieved_at BIGINT NOT NULL, -- unix seconds
PRIMARY KEY (provider, kind, artist_id)
);

View file

@ -0,0 +1,30 @@
-- What the discovery providers said about artists, kept as they said it.
--
-- artist_similar holds one row per "artist A is similar to artist B according to
-- provider P". similar_id can be an artist that has no files: such rows are how
-- music outside the library is known. score is the provider's own number and is
-- relative to the list it came in; rank is the position in that list (1 = first).
--
-- provider_fetches remembers when a provider was last asked about an artist and
-- what it answered ('ok' or 'not_found'), so a fresh answer is not asked again
-- and an unknown artist is not asked again at once.
CREATE TABLE artist_similar (
artist_id INTEGER NOT NULL REFERENCES artists(id) ON DELETE CASCADE,
provider TEXT NOT NULL,
similar_id INTEGER NOT NULL REFERENCES artists(id) ON DELETE CASCADE,
rank INTEGER NOT NULL,
score REAL NOT NULL,
PRIMARY KEY (artist_id, provider, similar_id)
);
CREATE INDEX idx_artist_similar_similar ON artist_similar(similar_id);
CREATE TABLE provider_fetches (
provider TEXT NOT NULL,
kind TEXT NOT NULL, -- what was asked: 'similar'
artist_id INTEGER NOT NULL REFERENCES artists(id) ON DELETE CASCADE,
status TEXT NOT NULL, -- 'ok' or 'not_found'
retrieved_at INTEGER NOT NULL, -- unix seconds
PRIMARY KEY (provider, kind, artist_id)
);