Commit graph sonda/README.md
Author SHA1 Message Date
tgiachi
95c1fa3e27 build: make build and an image with the web app inside; README describes it
make build builds the app and then sondad with -tags webui. The Dockerfile builds the app in a Node stage and embeds it in the Go build, so the image serves it with no Node on the host. README: how to build, what the image holds, the policy of the page, and how to work on the interface with the dev server.
2026-11-12 15:56:36 +01:00
tgiachi
82f6e91d7a feat(web): a Jobs section in the admin area
Three cards at /admin/jobs, for admins only; anyone else gets the notice and the server is not asked. The page reads which providers are on to block a job whose provider is off. README says the admin area now covers everything the API offers an admin.
2026-11-12 15:34:33 +01:00
tgiachi
99d25acd9a feat(web): the volume control in the player bar and the full-screen player
Both places move the same volume. README mentions it.
2026-11-12 15:23:50 +01:00
tgiachi
fed1213030 feat(web): a Providers section in the admin area
One card for each provider at /admin/providers, for admins only; anyone else gets the notice and the server is not asked. README says what the admin area covers.
2026-11-12 15:12:23 +01:00
tgiachi
52569a0f8d feat(web): a Users section in the admin area
Opens at /admin/users next to Libraries, for admins only; anyone else gets the notice and the server is not asked. README says what the admin area covers.
2026-11-12 14:58:01 +01:00
squidd
0b9d158f2b Merge pull request 'feat(web): admin area with libraries and scanning (F3a)' (#70) from feat/admin-libraries into main 2026-11-12 14:49:29 +01:00
tgiachi
d88710fd73 feat(web): the Admin area with libraries and scanning, and an Admin link for admins
The Admin link is shown only to an admin and /admin opens the libraries. Someone else who opens the address gets a notice and the server is not asked anything. README describes what the admin area covers so far.
2026-11-12 14:44:08 +01:00
squidd
7b24f76c46 Merge pull request 'feat(auth): accounts are identified by an email address' (#69) from feat/email-login into main 2026-11-12 14:41:32 +01:00
tgiachi
96ad8b1f62 feat(auth): accounts are identified by an email address
Registration, login and the admin's create-user call take `email` instead of
`username`, and the user object returns `email`. The address is checked for its
shape (a plain address, no display name, at most 254 bytes), trimmed, lowercased
and unique. Sonda sends no mail and does not verify it.

- Migration 0018 renames the users column (and the PostgreSQL index); values are
  kept, so an account made before keeps its plain name and still logs in with it
  (login does not check the shape).
- Error code username_taken becomes email_taken; the JWT claim is now `email`,
  so access tokens issued before the upgrade are refused once and clients refresh.
- OpenAPI spec, README, the web login form (type email), strings (en, it) and
  the generated API types follow.

Closes #65
2026-11-12 14:40:33 +01:00
tgiachi
6d830a3f21 docs: the Lidarr button in the web app section 2026-11-12 14:31:53 +01:00
tgiachi
88d3df9f61 feat(web): the Discover page with its three tabs, a sidebar link and a route
The tab is kept in the address (?tab=) and moves with the arrow keys; only the open tab asks the server for its list. README now describes Discover in the web app.
2026-11-12 14:11:27 +01:00
tgiachi
95ba06311e fix(docker): keep the secret, quiet health checks, and tighter files
- The README keeps the JWT secret in a file that is passed every time, so an upgrade
  does not make a new one and sign everybody out.
- A health check that succeeds is logged at debug level, so a container does not write
  thousands of lines a day; any other answer, and every other request, still goes at info.
- .dockerignore patterns match in every folder, as .gitignore does.
- compose.yaml waits 15 seconds for Sonda to stop (it allows itself 10) and requires
  MUSIC_DIR instead of creating an empty folder.
- The README says that the library path is the one inside the container, that the health
  check follows SONDA_LISTEN, and that a sonda.toml in /data works as a secrets file.
2026-11-12 12:29:38 +01:00
tgiachi
ddabcd3bb3 feat(docker): an image of sondad and a compose example
- A multi-stage Dockerfile: Sonda has no CGO, so the binary is static and the final
  image (alpine, 69 MB) holds only it, the CA certificates and the time zones.
- It runs as an ordinary user (uid 10001), keeps the database and the files it makes
  under /data (a volume), listens on 0.0.0.0:8080 inside the container, and does not
  start without SONDA_JWT_SECRET.
- A health check on /api/v1/health that follows SONDA_LISTEN.
- compose.yaml as an example: the secret comes from .env (which is not committed), the
  music is mounted read-only, and the port is published on this machine only.
- .dockerignore keeps the web client, the databases and the agent files out of the build.
- The README says how to build, run and back up, and how to use a host folder.
2026-11-12 12:23:41 +01:00
squidd
2d478055f2 Merge pull request 'feat(web): web app with player, library browsing, themes and languages (F1)' (#55) from feat/web-f1 into main 2026-11-12 12:15:12 +01:00
tgiachi
241c1efc5d feat(web): Neon theme
- colour in the surfaces too: deep indigo ground, saturated violet panels, electric yellow accent
- checked by the same contrast test as the other themes
- README lists six themes
2026-11-12 12:10:36 +01:00
tgiachi
0d5805fd37 feat(web): Dracula theme
- a livelier dark theme: violet ground, hot pink accent
- covered by the same contrast test as the others
- README lists five themes
2026-11-12 12:08:54 +01:00
tgiachi
69da67065d fix(discover): refusals do not wait for a turn, and waiting for one has an end
- The gate now comes after what only the database decides (a seed that is not an
  artist, no seed and no permission), so those answers are not held up by three
  slow Discovers and do not make the listener "busy".
- A request that waits more than 30 seconds for a turn answers 429 instead of
  hanging for as long as the providers are slow.
- The spec and the README say that a waiting request counts as running.
2026-11-12 12:00:18 +01:00
tgiachi
63fee32271 feat(discover): one Discover at a time for each listener, three at once on the server
A cold Discover can make dozens of provider requests, and nothing stopped one
listener, or a client that keeps opening and cancelling requests, from lining up
work for the providers and slowing everyone else's.

- A listener who already has a Discover running gets 429 `discover_busy` with
  Retry-After, at once.
- At most three Discovers run at the same time, whoever asks; the others wait for
  their turn, and one that stops waiting does no work and keeps no place.
- The place and the turn are given back when a Discover fails or ends.
- Spec and README describe it; the fakes of the tests are safe for parallel runs.
2026-11-12 11:52:20 +01:00
tgiachi
e0c42dd5ac docs(web): how to run and build the web app
- README section for the web client: how to run it next to sondad, what it does today, the commands
- the greeting on Home is read once per visit (lint: no Date during render)
- checked against a real sondad: login, renewal and spent refresh tokens, media URLs with Range, listens, search, and the provider-off answers
2026-11-12 11:45:20 +01:00
tgiachi
22cd0aecd4 fix(lidarr): protect Lidarr from many asks, refuse bad ids, give up when the request does
- Asking whether Lidarr has an artist keeps the answer for a minute, asks once however
  many ask at once, and has at most four questions on their way; what cannot be
  answered is not kept, and a send forgets what was kept.
- An id that is not a MusicBrainz id (one that a provider named and that was only
  cleaned) is no id: it is refused or shown as no_id instead of becoming a 500.
- A send that waits for its turn gives up when its request does.
- A bad answer after the add also says the artist may have been added; a canceled
  send ends like the other canceled requests.
- The README says which artists can be sent.
2026-11-12 11:35:28 +01:00
tgiachi
8160c33960 feat(lidarr): send an artist to Lidarr and see whether it has it
- POST /artists/{id}/lidarr (admin) adds the artist to the admin's own Lidarr by its
  MusicBrainz id, never by name, with the profiles, the folder and the monitor
  option the admin chose. It works for any artist that has an id, also one that
  Sonda only learned of from a list of similar artists. It can be repeated: an artist
  that Lidarr already has changes nothing. Two sends at once go one after the other.
- GET /artists/{id}/lidarr (signed in) says whether Lidarr has the artist and
  monitors it; what stops the answer is a status (disabled, no_id, not_configured,
  error), as for the descriptions.
- It needs the provider switched on and the profiles and folder chosen; a timeout
  says the artist may have been added anyway.
- Spec, contract test and README, which also say that Sonda downloads nothing.
2026-11-12 11:28:15 +01:00
tgiachi
4dbe1074ba fix(lidarr): saved defaults, conflicts, no proxy, readable addresses
- Setting the address alone now stores the default options (monitor all, search
  for missing albums), so what is shown is what will be sent.
- A 409 from Lidarr, when two adds of the same artist cross, means the artist is
  already there; only "an artist with this ID was not found" is an unknown artist.
- The client never goes through a proxy named by the environment, since Lidarr is
  on the admin's own network and the key travels in a header.
- An address that cannot be read back (an IPv6 zone) is refused instead of being
  stored and reported as "not configured".
- A deadline asking Lidarr is a bad gateway, not an internal error; a redirect is
  reported with a hint to use the final address; the request schema of the Lidarr
  options is closed.
2026-11-12 11:11:35 +01:00
tgiachi
fb9e923197 feat(lidarr): set up Lidarr as a provider and read what it offers
Lidarr is a server of the user's own that looks for and downloads music. Sonda
never downloads; this is the first piece of letting an admin send it an artist.

- The `lidarr` provider, off by default: an address, an API key (32 hexadecimal
  characters, never returned) and, chosen once, a quality profile, a metadata
  profile, a root folder, the monitor option and whether to search for missing
  albums. It cannot be enabled without an address and a key.
- The address is checked: http or https, no user and password, no query, no
  fragment, no closing slash.
- A small client of its own, apart from the outbound one (which only makes plain
  GETs): the key travels in a header, no redirect is ever followed, answers and
  time are bounded, and the address and key are read for every request.
  Status, options, artist by MusicBrainz id and add (lookup, then the add that
  Lidarr's own screen sends).
- `GET /providers/lidarr/options` lists the profiles and root folders; the test of
  the provider checks the address and the key (`no_address` when it has none).
- Migration 0017 adds the address and the options to the provider settings.
- OpenAPI, contract test and README say what is sent and where.
2026-11-12 11:04:53 +01:00
tgiachi
271c88743c feat(search): search ignores accents
- A search key apart from the key that identifies artists, albums and tracks:
  lower case, accents taken off (Latin, Greek and Cyrillic marks only, so kana
  and Hangul stay intact), and letters like ß, æ, ø, ł written plain.
- GET /artists, /albums and /tracks look in it, so "bjork" finds "Björk" and
  "strasse" finds "Straße".
- "Beyoncé" and "Beyonce" stay two artists: the identity key keeps accents.
- Migration 0016 adds the column on SQLite and PostgreSQL; RefreshMatchKeys
  fills it for existing rows at start.
- golang.org/x/text is now a direct dependency.
2026-11-12 10:17:21 +01:00
tgiachi
e3843ad7d6 feat(jobs): background jobs for artist photos and descriptions
Add one engine, internal/jobs, that runs the jobs which go through the whole
library: start, stop, progress, one at a time, give up after five failures in
a row, end at once when a provider is off.

- The covers job now runs on the engine; its API is unchanged.
- POST/GET/DELETE /library/artist-images looks for the picture of every
  artist of the library that has a MusicBrainz id.
- POST/GET/DELETE /library/descriptions does the same for the Wikipedia
  description.
- ?refresh=true searches everything again and never replaces a stored result
  by a failure; artists without an id are never touched, nothing is looked up
  by name.
- images.Service.EnsureArtistImage and about.Service.Ensure do the work for one
  artist; the lists come from ImageRepo and DiscoveryRepo.
- jobs.Runner binds a job to the application context, replacing the two
  hand-written controls.
- OpenAPI, contract test and README describe the new endpoints and say that
  they are bulk requests.
2026-11-12 09:58:45 +01:00
tgiachi
345ad8eecb fix(images): a refresh never wipes covers, the job sees outages and starts cleanly
- A refresh (or any rebuild) while the Cover Art Archive is switched off, but its data
  not taken back, no longer turns the covers it gave into "no cover" and deletes their
  files: the stored cover is kept and its date renewed, so the files are not searched
  again at every request.
- When none of an album's files and folders can be looked at (an unmounted disk, a
  permission), that is ErrFilesUnreadable (503 files_unreadable), not "no picture": nothing
  is remembered, nothing built is touched, the archive is not asked, and the job counts it
  as a failure and gives up after five. A link that leaves the library is still just refused.
- The job calls the build for every album that is not good yet and does not serve an older
  cover on an outage, so a dead provider shows as failures and trips the limit instead of
  being reported as covers from the archive.
- Start marks the job as running before counting the albums and does not hold the lock
  meanwhile; a stop that comes back as a plain driver error is not a failure; a job that
  finished by itself is never marked stopped.
- Spec and README say so; the tests cover each case, including a list that fails midway.
2026-11-12 09:43:51 +01:00
tgiachi
548ee03d83 feat(images): a background job that builds all the covers
- POST /library/covers (admin) starts, in the background and one at a time like a scan,
  a job that builds the cover of every album that has something to play and no cover that
  is still good; GET /library/covers shows the progress and how the last job ended;
  DELETE /library/covers stops it. ?refresh=true searches every album again.
- For each album it does what opening its cover does: the user's own files first, then the
  Cover Art Archive if the provider is on. It gives up, and says why, when the provider
  fails for five albums in a row; an album that vanished is skipped, not a failure.
- This is the one request that goes through the whole library, and the README and the
  provider text say so: with the archive on it sends the release group id of each album with
  no picture in its files, one after the other, spaced out.
- NewRouter now refuses to build when a service was not wired, naming it, instead of
  panicking at the first request (the wiring of this job in main had been missed, which no
  test could see).
- The outbound spacing test measures where the request leaves the client, so a busy
  machine cannot make it fail.
- Spec, contract and HTTP tests, README updated.

Closes #45
2026-11-12 09:34:27 +01:00
tgiachi
5fecd394e4 fix(images): purge removes every archive cover, the id of an emptied album moves on
- The covers that come from the Cover Art Archive now live in a folder of their own
  (images/album-remote). Taking the provider's data back deletes that folder, so nothing
  from the archive is left whatever became of its records: a rescan makes a record stale
  and a later search that finds nothing replaces it, and neither of those used to remove
  the files. A cover that moves between the user's files and the archive, or goes away,
  no longer leaves the old files behind.
- A redirect to a place that is not allowed is an outage (502, not remembered, an older
  cover served), not "no cover" for a day for every album. A picture over the limit is
  still "no cover".
- A track that moves to another album (a fixed title) leaves the first with no track: it
  gives up its release group id, so the album the track went to can take it. An album
  that has an id keeps it; an id another album owns is not given twice.
- Waiting for a local slot is no longer reported as the provider being unreachable, and a
  build whose reads were purged three times is not served with files that were never written.
- README and spec no longer say covers never contact anybody.
- Tests: the new folder and the purge after a rescan, files left by a replaced cover, the
  local wait, repeated purges, a refused redirect, the update path with a taken id and the
  emptied album.
2026-11-12 09:21:11 +01:00
tgiachi
d5ed0f2e9c feat(images): album covers from the Cover Art Archive
- The scan reads the MusicBrainz release group id of an album from the tags of its
  files (MUSICBRAINZ_RELEASEGROUPID, a vorbis comment or an ID3 frame) and stores it in
  albums.mbid: it is taken only when the file has an album and exactly one valid id, an
  album keeps the one it has, and an id that another album owns is not given twice. A full
  rescan reads it for music that was already indexed.
- New provider "coverartarchive" (off by default, no key, contact in the User-Agent). When
  an album has no picture in the user's own files, which always come first, its cover is
  asked from the archive by that id and never by a title: only the id leaves the server.
  The same GET /albums/{id}/cover; the record keeps the source. An outage is a 502
  provider_unavailable and is not remembered, and an older cover is served in its place.
- The archive answers with three redirects (coverartarchive.org, archive.org, a data node
  whose name changes). The outbound client can now follow redirects, but only the ones the
  caller allows, up to a limit; here that is https on archive.org and its subdomains.
- A purge counter now guards the covers too: a read that started before the provider's data
  was taken back is not kept. Removing the provider's data forgets the covers that came from
  it and deletes their files, and leaves the ones from the user's files.
- Spec, contract and HTTP tests, README updated; the facts of the real archive are written down.

Closes #43
2026-11-12 09:09:31 +01:00
tgiachi
e752d15536 feat(images): free photos of artists from Wikimedia Commons
- GET and HEAD /artists/{id}/image serve a free picture of an artist as a JPEG
  (size=small 300 px or large 1000 px, token in the query allowed for an <img>), and
  GET /artists/{id}/image/credit gives the author, the licence and the page of the file,
  to be shown next to it.
- New provider "commons" (off by default, no key, contact in the User-Agent), which also
  needs MusicBrainz on. The way to the picture uses ids only, never a name: the artist's
  MusicBrainz id, the Wikidata item MusicBrainz links to it, the file Wikidata names for
  it (P18), Commons for its licence, and a 960 px copy from a Wikimedia picture host.
- Only free licences: public domain, CC0, CC BY and CC BY-SA. Non-commercial,
  no-derivatives, GFDL alone, fair use and unknown licences are refused, since a copy is
  kept. The author is plain text, the licence address is kept only on creativecommons.org,
  and the download only from https thumb.wikimedia.org or upload.wikimedia.org.
- Built on the first request, kept in the data folder: 30 days, or a week when there is no
  free picture; an older copy is served when Commons cannot be reached; a failure is not
  remembered. Credit changes change the ETag.
- Removing the provider's data forgets the records and deletes the files; a read that started
  before it is not saved over it.
- images table gets the credit (migration 0015); the purge reports images.
- Spec, contract test, README updated; the facts of the real APIs are written down.

Closes #41
2026-11-11 22:03:32 +01:00
tgiachi
762d424816 fix(about): unusable pages fall through, MusicBrainz switch, merged items
- A page that cannot be used (no text, an address off Wikipedia, a redirect that is
  never followed) is now an answer: the chain goes on to the next language and the
  outcome is stored. Before, it was a failure asked about again at every view, and
  redirects counted against the provider's breaker.
- The chain also needs the MusicBrainz provider to be on, since the id goes to it
  with its own contact: nothing is sent to MusicBrainz that the admin did not allow.
  The disclosure in the provider settings, the spec and the README say so.
- A Wikidata item that was merged into another is understood through the target: the
  entity's own id is returned, compared with the page's item and stored. Verified on
  the real API.
- The title shown is the one Wikidata names (with spaces), control characters are
  dropped from the text (PostgreSQL refuses NUL), the text is cut to at most 4000
  characters with the mark included, and a stored description is reported disabled
  when the provider is off.
- A read that started before the provider was switched off does not save its result.
- Tests: the real clients with a redirect and a page without text, merged items,
  MusicBrainz off, switching off during a read.
2026-11-11 21:45:20 +01:00
tgiachi
48cb903115 feat(about): artist descriptions from Wikipedia
- GET /artists/{id}/description shows what Wikipedia says about an artist: a short
  text with its page, a link and the licence (CC BY-SA 4.0).
- New provider "wikipedia" (off by default, no key, contact in the User-Agent, which
  Wikimedia requires). The way to the text is a chain of ids, never a name: the
  artist's MusicBrainz id, the Wikidata item MusicBrainz links to it, the Wikipedia
  page Wikidata names in the first configured language that has one. A page is used
  only if it is an article about that same item.
- [wikipedia] languages in the config (one to five codes of two or three lower case
  letters, checked before they are sent: an unknown site makes Wikidata answer with
  every language).
- Stored 30 days (a day when there was nothing to find), served stale if Wikipedia
  fails, removed with the provider's data (the purge now reports descriptions).
- MusicBrainz client: WikidataID. Wikipedia client for Wikidata and the summary,
  which also reads Wikidata's errors that come with HTTP 200.
- artist_descriptions table (migration 0014, SQLite and PostgreSQL).
- Spec, contract test, README and example config updated.

Closes #39
2026-11-11 21:36:27 +01:00
tgiachi
7bdbc9e160 fix(images): limit parallel builds, no stale saves, safer files
- At most two covers are built at the same time: a page of albums asked for at once
  could decode dozens of large pictures together.
- A change to an album's files marks its record stale and moves a generation instead
  of deleting the row. A build that started before the change is not saved over it
  and starts again, so a "no cover" found too early cannot win for a day.
- A cover that was found is checked again after a week, so a picture replaced in a
  folder is noticed.
- For CD1/Disc 2 folders the picture in the folder above is used. Folder pictures
  are read one at a time, and the pixel count is computed in 64 bits.
- Stored files are synced before they get their name, an empty one counts as
  missing, and old temporary files from a crash are removed.
- Files without track or disc numbers sort the same on both databases.
- storage.data_dir defaults next to the SQLite database, so a service started from
  another folder does not need a writable working directory.
- Tests: a listener who leaves, a change during a build, the build limit, a named
  pipe, an embedded picture of a file outside the library that exists, builds that
  really overlap.
2026-11-11 21:03:26 +01:00
tgiachi
0e121ead8e feat(images): album covers from my own files
- GET and HEAD /albums/{id}/cover serve a JPEG made from the picture embedded in
  the album's files, or else a cover, folder, front, album or albumart image
  (jpg, jpeg, png) in the album's folder. ?size=small (300 px) or large (1000 px).
  The token can be in the query, so an <img> element can use it.
- Built the first time it is asked for, scaled, and kept in storage.data_dir
  (SONDA_DATA_DIR, default "data"); an album with no cover is remembered for a day.
  A new or changed file of the album, or a full rescan, clears the record.
- Nothing is sent anywhere. Pictures are untrusted: files are opened inside the
  library only (links are not followed), over 20 MB or 16 million pixels are
  ignored, and what is served is always a JPEG made here. Stored files are 0600.
- images table (migration 0013, SQLite and PostgreSQL).
- Spec, contract test, README and example config updated.

Closes #37
2026-11-11 20:52:36 +01:00
tgiachi
65e93ee84b fix(feedback): purge only what the provider named, no leak between users
- Purging a provider removes only the artists that provider's lists named. A
  purge of MusicBrainz, which names none, no longer deletes an artist only a
  wish kept alive, nor the wish.
- A mark no longer makes an artist visible to everybody: GET /artists/{id} and
  the similar lookups did, which showed what other users marked. Marking or
  unmarking needs an artist the user can see or has marked themselves, with the
  same answer for both.
- Deleting an account cleans up the discovered artists only its marks kept, in
  the same transaction and under the artist lock.
- Tests: a purge of another provider, deleting an account, the scanner adopting
  a marked artist, and what another user can see of a marked artist.
2026-11-11 20:18:04 +01:00
tgiachi
a6dbf60ac8 feat(feedback): a wishlist and "not interested"
- PUT/DELETE /wishlist/{artist} and GET /wishlist: the artists I want.
- POST/DELETE /discover/{artist}/dismiss and GET /discover/dismissed: the
  artists I am not interested in. An artist is wished or dismissed, never both,
  and both lists are mine alone.
- Discover never suggests a dismissed artist, does not use one as a seed taken
  from my listening, and marks the wished ones it shows (wishlisted).
- New artist_feedback table (migration 0012, SQLite and PostgreSQL), removed
  with the account.
- An artist I marked is not cleaned up when the list that named it is replaced,
  and goes when its last mark is taken off and nobody names it. Taking a
  provider's data back still removes what only it named, marks included.
- Spec, contract test and README updated.

Closes #35
2026-11-11 20:11:18 +01:00
tgiachi
f548423f73 fix(discover): ask permission first, stable order, honest docs
- Check the discover_from_listening setting before reading the listening
  history, so a refused request does no work and a database failure cannot turn
  it into a 500.
- Cosine adds up in tag order: the sum in map order changed in the last digit
  between runs, and equal artists could swap places between requests.
- A seed that could not be read is no longer listed as a seed.
- README and spec: Discover exists now; "disabled" means something had to be
  asked and Last.fm is off; the stored lookups are shared, so another local user
  can see from retrieved_at that an artist was looked up, but not who.
- Tests: the history is not read for a refused request, a stable cosine, tags
  fetched only for the pool and four at a time, a cancelled request stops,
  MusicBrainz is never asked, the setting is per user.
2026-11-11 19:48:51 +01:00
tgiachi
28c249c268 feat(discover): artists I may like, with a score I can explain
- GET /discover suggests artists, in my library or not, with a score from 0 to 1
  and its parts: affinity (similar to the artists I like), genre (tags close to
  mine), preference (what my listening says) and discovery (a bonus for what I
  have not played). Default weights 0.40, 0.25, 0.25, 0.10, set in [scoring].
- A part with no data (no tags) is left out and the others rescaled; the answer
  says which parts were there, and which seeds led to each suggestion.
- Seeds are the artists I name with ?seed=, or, only when I turned on
  discover_from_listening, the artists I play most. Without either the request is
  refused and nothing is sent to anyone.
- The tags of the best candidates are read from Last.fm only, only for those with
  none stored, a few at a time.
- taste.Service.Learn gives the whole picture (every preference, the liked
  artists, the tag profile); TagService.ProviderTags asks one provider.
- Spec, contract test, README and example config updated.

Closes #33
2026-11-11 19:42:09 +01:00
tgiachi
52d1828b46 fix(auth): a token stops working when its account is deleted
SQLite gives the highest user id again after that user is deleted, and an access
token lives for minutes, so the token of a deleted user worked as whoever got the
id next (settings, taste, listens, account).

requireAuth now looks the account up after checking the token and refuses it when
the account is gone, has another name, or was created after the token was signed.
The token carries its issue time for this.

Tests: a unit test of every case, and the real scenario on SQLite (delete the
highest id, create another user, the old token gets 401, the new one works).

Closes #30
2026-11-11 19:25:09 +01:00
tgiachi
acede4bd91 fix(settings): strict body, deleted-account race, doc wording
- PATCH /me/settings accepts exactly one JSON object: text after it, null, a
  differently cased name or an unknown name are refused (400) and change nothing.
- A user deleted between the read and the write of the settings gives 401, not a
  500, on PostgreSQL too (foreign key violation mapped to user not found).
- The spec says a 401 can also mean the account no longer exists, and that the
  body is strict.
- README no longer says more than the setting does.
- Tests: strict body cases, tokens of a deleted account on GET and PATCH,
  recognising a foreign key violation on both databases.
2026-11-11 19:20:42 +01:00
tgiachi
e0592c0260 feat(settings): my own settings, starting with Discover from my listening
- GET and PATCH /me/settings: settings that belong to the signed-in user.
- First setting, discover_from_listening, is off by default. When on, Discover
  may start from the artists I listen to most, which sends their names to
  Last.fm.
- New user_settings table (migration 0011, SQLite and PostgreSQL), removed with
  the account. A user with no row has the private defaults.
- A misspelt setting is rejected instead of being ignored.
- Spec, contract test and README updated.

Refs #29
2026-11-11 19:16:26 +01:00
tgiachi
d251cc4f39 fix(taste): order by the score, clamp future events, keep tags short
- Order the liked artists by the weighted sum, not by tanh, which rounds to
  exactly 1 after about 58 listens and made heavy artists tie.
- An event dated after now counts as happening now, also for the last listen.
- Genres of files that are gone no longer shape the tag profile, as in
  /artists/{id}/tags.
- The tag list is capped at 50.
- A zero half-life falls back to 90 days instead of producing NaN.
- Document the 10 half-lives window and the new rules in the spec and README.
- Tests: heavy artists keep their order, tracks with two artists credit both,
  genres of a missing file are left out, the tag cap, a zero half-life.
2026-11-11 18:52:08 +01:00
tgiachi
544ec67dd1 feat(taste): learn what I like from what I listen to
- taste package: each listening event has a value (complete +1, a play that
  counts +0.5, a skip that does not count -1, a short play 0), older events
  weigh less (half-life 90 days, taste.half_life_days), and the values of an
  artist become a preference in (-1, 1) with tanh.
- Tag profile built from the artists I like: genres of my files plus the tags
  already stored from providers, each source scaled to its own best tag.
- GET /me/taste shows the liked artists and the tags. It reads local data only
  and never asks a provider.
- TasteRepo reads events, names and tags; tests on SQLite and PostgreSQL.
- OpenAPI spec, contract test, README and example config updated.

Closes #27
2026-11-11 18:46:58 +01:00
tgiachi
b0a7a562a6 fix(discovery): purge lock, cleanup chains and rescans that cannot read
- fix: on PostgreSQL a purge could delete a discovered artist while a scan was
  adopting it. The scan then failed on the missing artist for the whole file,
  and the two could also deadlock. Purge now takes the same artist lock as the
  scanner and discovery before it removes anything. Saving a list or tags does
  too, and an artist that is gone by then is reported as not found instead of a
  foreign key error, so a user who opened an artist that was removed meanwhile
  gets a 404
- fix: a discovered artist that was only the source of a list stayed forever and
  kept the artists of its own list alive, so chains built up. Cleanup now removes
  such an artist and then follows the chain until nothing more goes
- fix: in a full rescan a file that came back but could not be read stayed
  marked missing. It is restored first, as in a normal scan, and read as well
- fix: ?full given twice is refused, so a typo cannot start a scan of another
  kind
- fix: genre cleaning lives in one place, used by the reader and the store
- docs: the files genres count the tracks the artist is credited on, and the spec
  says every files tag is a genre
- test: a purge colliding with a scan on both databases (it fails without the
  lock), a chain of discovered artists, saving for an artist that is gone, a
  file that returns unreadable during a full scan
2026-11-11 17:36:14 +01:00
tgiachi
1857bb9c53 feat(discovery): remove provider data, genres from my files, full rescans
- feat: DELETE /api/v1/providers/{name}/data (admin) removes everything a
  provider gave: its lists of similar artists, its tags and the records of
  when it was asked, then the artists that only that data named and that
  nobody has files for. Last.fm's terms ask for this when an agreement ends.
  The user's own artists, music, listens and settings stay, the provider is not
  switched off, and a second call removes nothing
- feat: a discovered artist that no list names any more is removed when the
  list that named it is replaced, together with its tags, so they do not pile
  up. Real artists, and any artist that another list still names, are kept
- feat: the scan reads the GENRE tag of each file, offline (several genres
  separated by ";", lower case, at most five per file), and
  GET /artists/{id}/tags gets a third entry, files: the genres of the artist's
  own playable tracks, each weighted by how many tracks have it. It asks nobody
  and is always there
- feat: POST /library/scan and POST /libraries/{id}/scan take full=true to read
  every file again, not only the new or changed ones, so MusicBrainz ids and
  genres reach music that was indexed before. Files keep their identity, so
  listening history is kept. Anything but true or false is a 400
- test: the plan of a full scan, the scanner and the manager; the purge on both
  databases, checked by removing the rule that spares real artists; the
  cleanup of replaced lists; genres per file and per artist
- docs: README, OpenAPI and the todo list updated
2026-11-11 17:27:29 +01:00
tgiachi
175b87a4cc fix(discovery): ids from files, adoption and the scanner lock
- fix: a discovered artist adopted by id under another spelling kept its old
  match key, so the next file with the new spelling and no id created a second
  artist. The key now follows the name
- fix: when a real artist without an id and a discovered artist holding the id
  have the same name, the id now goes to the real artist and the discovered one
  lets go of it. Before, the scan created a second real artist and a second
  album, and could not repair it because the id was taken
- fix: when a file without an id adopts a discovered artist that had a provider
  id, the tags, the fetch records and the similar artists read under that id
  are dropped, since they are not known to be about the user's artist. Links
  from other artists to it stay. A file that confirms the very same id keeps
  everything
- fix: the album artist id is only read when the file has an album artist tag;
  with the tag missing the name is a fallback and the id would have landed on the
  wrong artist (a Various Artists id on the track's own artist)
- fix: one artist credit with one id ("X feat. Y" with the id of X, how beets
  writes it) is not paired: no id is safer than a wrong one. A name that is
  itself a single letter or contains a slash still gets its id
- fix: on PostgreSQL the scanner took the artist lock after it had already
  changed artist rows, which could deadlock with a concurrent similar-artists
  save. SaveFile now takes the lock first, once
- fix: Last.fm does not know every MusicBrainz id: when it does not know the id
  and there is a name, the name is tried, never autocorrected, as before ids
  were read from files
- fix: waiting for one provider's tags is bounded at 20 seconds, so a rate
  limited provider cannot hold a page for a minute
- docs: the tag range is 1 to 100 (a tag with no votes is dropped), the spec says
  where an artist's id can come from, and the README says when Last.fm gets an id
- test: adoption by spelling, the real artist with a discovered namesake,
  dropping and keeping what was read, album artist fallback, credits, an ID3
  frame, and the id-then-name fallback of Last.fm
2026-11-11 17:13:31 +01:00
tgiachi
07ea997cd0 feat(discovery): artist tags from Last.fm and MusicBrainz, and ids from my files
- feat: GET /api/v1/artists/{id}/tags lists, for each provider that is on, the
  tags it gives to an artist with its own weights, kept as they came: Last.fm's
  are relative to the artist, MusicBrainz's are counts of votes, and they are
  never mixed. MusicBrainz also marks the tags it lists as genres. The same
  rules as similar artists apply: asked only on demand, kept 7 days (1 for an
  unknown artist), old data served when a provider fails, and one call for
  simultaneous requests. A provider that is off, failing or lacking an id does
  not hide the other
- feat: a thin MusicBrainz client that reads an artist's tags and genres by its
  id. It never searches by name, because a search returns look-alikes and
  picking one would be a guess. The id is checked before it reaches the path,
  and errors never repeat the provider's text
- feat: the User-Agent can change while the server runs, so the contact an
  admin sets for MusicBrainz applies to the next request; if the settings
  cannot be read it falls back to the project address
- feat: Last.fm top tags, by id when known and by name otherwise, never
  autocorrected
- feat: the scan reads MusicBrainz artist ids from the file tags, offline, and
  keeps them on the artists. An id is only used when it can be paired with its
  artist for certain: the same number of ids as artists, all valid. The same id
  is the same artist whatever the spelling, an artist without an id takes the
  one its file gives, and another id under the same name is another artist. A
  file that confirms the id a provider gave to a discovered artist keeps it
- feat: POST /providers/musicbrainz/test checks that the service answers
- test: what leaves the server for MusicBrainz is checked from the other end:
  the id of the artist and the admin's contact, nothing from the library;
  removing the safeguards on ids and pairing makes tests fail
- docs: README, OpenAPI and the provider text updated
2026-11-11 17:01:43 +01:00
tgiachi
b769ad7ac5 fix(discovery): concurrent writes, adopted artists and a client that leaves
- fix: on SQLite a transaction that read and then wrote failed at once with
  "database is locked" when another writer committed in between, because the
  busy timeout does not apply there. Transactions now start with BEGIN
  IMMEDIATE. Before this change a scan running while someone opened similar
  artists made files fail, and parallel requests stored nothing
- fix: on PostgreSQL two requests naming the same new artist could fail on the
  unique MusicBrainz id or leave two rows with one name. Creating artists, in
  the discovery store and in the scanner, now takes turns through an advisory
  lock and looks again once it has the turn
- fix: music arriving for an artist that a provider only named used to keep the
  provider's spelling and its unchecked MusicBrainz id, which later lookups
  would then send instead of the name. Such artists are now marked
  (artists.discovered); the first scan that finds them renames them to the
  spelling of the file tags, drops the id and clears the mark
- fix: a panic in the shared provider call is turned into a failure; the
  singleflight group would have re-raised it where nothing can recover
- fix: a client that leaves while Last.fm is being asked no longer gets a 500
  and an error in the log
- fix: no page can ask for more than is stored (limit tops out at 50), and the
  docs no longer say the best score is always 1
- test: concurrent saves plus a scan on both databases, checked by removing each
  fix; adoption keeps neither the name nor the id; the panic; the client that
  leaves
2026-11-11 16:47:33 +01:00
tgiachi
aafb2dd906 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
2026-11-11 16:42:52 +01:00
tgiachi
9f4da2e77e feat(providers): provider settings in a table and a careful outbound HTTP client
- feat(storage): provider_settings table (provider, enabled, api_key, contact);
  migration 0007 for both drivers. A provider with no row, or turned off, is
  never contacted
- feat(providers): a service that validates and applies settings: a Last.fm key
  is 32 hexadecimal characters, enabling a provider that needs a key without
  one is refused, clearing the key turns the provider off, a contact cannot
  contain parentheses or control characters. Each provider states what it sends
  and under which terms, and what it never sends
- feat(api): admin-only GET /providers and PUT /providers/{name}. The API key is
  write-only: responses carry only has_api_key, errors never repeat it and the
  request log never contains it (tested)
- feat(providers/outbound): the only way Sonda talks to the outside: plain GET
  with an identifiable User-Agent, no cookies, no Referer, no Authorization, no
  redirects, bounded answers, a timeout per attempt, a minimum interval between
  requests, retries with exponential backoff that honour Retry-After without
  waiting past the caller's deadline or for an absurd time, and a circuit
  breaker that makes a failing provider fail fast
- feat(providers): UserAgent builds "Sonda/version ( contact )" as MusicBrainz
  asks, defaulting to the project address so no personal address is sent
- breaking(config): providers.lastfm and SONDA_LASTFM_API_KEY are gone; an old
  config, or the variable, fails with a hint instead of being ignored
- docs: OpenAPI operations and schemas, README section on the providers and on
  what leaves the server
- test: fake servers and a fake clock only; no network in the suite
2026-11-11 16:07:12 +01:00