Commit graph sonda/sonda.example.toml
Author SHA1 Message Date
tgiachi
89f1b5275a feat: scan the libraries by themselves when their music changed
Every 15 minutes (library.auto_scan_minutes, SONDA_AUTO_SCAN_MINUTES, 0 turns it off)
Sonda takes the signature of each library, a hash of the names of everything in it folder
by folder, which costs only the names of the files and so suits a NAS that sleeps. A
library whose signature changed (a song or a folder came, went or was renamed) is
scanned the usual way; every library is also scanned at least once a day, to find a song
tagged again where it stands.

It does not scan while another scan runs, tries again at the next look when a scan failed,
leaves alone a folder that cannot be read (a NAS that is not mounted), and ignores the
housekeeping folders of a NAS.
2026-11-16 13:05:09 +01:00
tgiachi
7180a747e9 docs: duplicates, library.allow_delete and the one exception to read-only music folders
README: the Duplicates feature, the new setting and its environment variable, the endpoints, and the two places that promised the music folders are never written. The example config and the compose file say how to turn it on and that the folder must then be writable.
2026-11-12 16:50:11 +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
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
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
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
tgiachi
7047e07906 feat(listening): count a listen after a minimum play time and expose the history
- feat: an event counts as a listen when it is `complete`, or when it was
  played for at least listening.min_listen_seconds (default 20, 1 to 3600).
  The rule is applied when the history is read, not when an event is stored,
  so changing the setting re-reads the past; streaming never counts
- feat(api): POST /listens answers with `counted`, also for a duplicate
- feat(api): GET /listens returns the signed-in user's own history, newest
  first, with `counted` per event, paging and ?counted=true; nobody sees
  anybody else's events
- feat: a reported play time more than twice the track length plus ten seconds
  is rejected as implausible; looping and seeking back stay allowed, and a
  track of unknown length is not checked
- feat(storage): TrackDurationMs and ListEvents on SQLite and PostgreSQL
- docs: OpenAPI operations and schemas, README rule, setting, API table and a
  demo that reports a 25 s and a 3 s play and reads the history; the demo tones
  now last 30 s so a 25 s play is plausible
- test: the rule at its boundaries, the plausibility bound, history order,
  paging and isolation on both databases, and the contract test for the new
  operation

Closes #17
2026-11-11 14:58:47 +01:00
tgiachi
46463846b3 feat(library): named media libraries managed through the API
- feat(storage): libraries table (name, path); audio_files points at a library
  by id instead of repeating the root path; migration 0005 for both drivers
  turns every existing root into a library and keeps file ids, tracks and the
  missing flag
- feat(library): Libraries service validates names and paths: absolute, an
  existing directory, never the filesystem root, never inside or around
  another library (checked on real paths, so symlinks cannot hide an overlap)
- feat(api): admin-only GET/POST /libraries, PATCH/DELETE /libraries/{id} and
  POST /libraries/{id}/scan; deleting a library drops its index entries and
  keeps tracks and listening history
- feat(library): the scanner and the scan manager work on libraries; scanning
  with no libraries answers 409 no_libraries
- feat(streaming): the library directory comes from the database instead of
  a configured list of roots
- breaking(config): library.roots is removed; an old config fails with a hint
  to use POST /api/v1/libraries
- test: CRUD and duplicates on both databases, path change keeps files,
  upgrade of a database written before libraries existed
2026-11-11 13:30:25 +01:00
tgiachi
dbe9338af3 feat(auth): add refresh tokens, admin role and user management
- feat(auth): short-lived access tokens plus rotating refresh tokens stored as
  SHA-256 hashes; replaying a spent token revokes every session of that user
- feat(auth): is_admin flag; the first registered user is the admin and the
  last admin can be neither demoted nor deleted
- feat(api): POST /auth/refresh, /auth/logout, /auth/password and GET /auth/me
- feat(api): admin-only GET/POST /users, PATCH /users/{id}, PUT
  /users/{id}/password and DELETE /users/{id}; the admin check reads the role
  from the database on every call
- feat(api): starting a library scan is now admin-only
- feat(storage): users and refresh token repositories for SQLite and
  PostgreSQL (migration 0004; the oldest existing account becomes admin)
- feat(config): auth.access_ttl_minutes and auth.refresh_ttl_hours replace
  auth.token_ttl_hours
- test: rotation, reuse detection, concurrent rotation with a single winner,
  admin rules, role changes taking effect immediately
2026-11-11 12:38:42 +01:00
tgiachi
4c7e99bd6a feat(library): add concurrent read-only scanner with progress events
- feat(library): walk each root, plan the changes, read tags with N parallel
  workers and write from a single goroutine
- feat(library): detect renames by size and mtime only when the match is
  unambiguous; mark vanished files missing instead of deleting them
- fix-safe: an unreadable root, an unreadable subdirectory or an interrupted
  scan never marks files as missing; symlinks are skipped
- feat(library): event hub that fans scan progress out to subscribers without
  ever blocking the scan (ready for a websocket client)
- feat(library): TagLib (WASM, no CGO) reader for MP3 and FLAC tags and
  audio properties, with title and artist fallbacks
- feat(storage): library repository for SQLite and PostgreSQL
- feat(api): POST/GET /api/v1/library/scan to start a scan and read its status
- feat(config): library.scan_workers
2026-11-11 12:16:45 +01:00
tgiachi
3a739dc3ae feat: add sondad server with config, storage, auth and listening API
- feat(config): TOML config with env overrides, strict parsing and validation
- feat(storage): SQLite (modernc) and PostgreSQL (pgx) backends through bun,
  embedded per-driver SQL migrations with a transactional runner
- feat(schema): catalog tables (artists, albums, tracks, audio_files with
  per-root paths), users and listening events with idempotency keys
- feat(auth): Argon2id password hashing, HS256 JWT tokens, first-user-only
  registration and login
- feat(api): gin REST API under /api/v1 (health, register, login, listens)
  with a consistent error envelope, body limit and request logging
- feat(sondad): zap logger, graceful shutdown, composition root in main
- chore: example config, .gitignore for secrets, DB files, IDE and agent files
2026-11-11 12:06:15 +01:00