Commit graph sonda/internal/api/http/api_test.go
Author SHA1 Message Date
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
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
9d28a8a99c feat(api): OpenAPI spec and an offline Swagger UI
- feat: internal/api/openapi/openapi.yaml describes every operation (OpenAPI
  3.0.3), written by hand and embedded in the binary; GET /api/v1/openapi.yaml
  serves it
- feat: GET /api/docs/ serves Swagger UI from assets embedded in the binary
  (github.com/swaggest/swgui, v5emb), so opening it never contacts another
  server; both are public because they contain no data
- feat: response objects in the spec are closed (additionalProperties: false)
- test: the spec is valid OpenAPI; the router and the spec describe the same
  operations in both directions; every operation has an id, a summary, a tag,
  a documented 401 when it needs a token and a 403 when it is admin only
- test: a contract test drives every operation through the real services,
  including a real scan and real streaming, and validates each response
  (status, headers, JSON body) against the spec with kin-openapi; it fails if
  an operation was never exercised. Checked by breaking the code and the spec
  on purpose
- test: the docs page loads without any external address and every asset it
  references is served
- docs: README section on the interactive documentation and on keeping the
  spec in step with the code

Closes #15
2026-11-11 14:35:16 +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
49f1051b3f feat(streaming): stream tracks with HTTP Range support
- feat(streaming): open a track's file only after checking it against the
  configured library roots: relative paths only, no "..", symlinks resolved on
  both sides so none can leave the root, regular files only
- feat(api): GET and HEAD /api/v1/tracks/{id}/stream via http.ServeContent
  (206, 416, Content-Length, conditional requests), MIME type from the
  extension, nosniff, no-referrer and private caching headers
- feat(api): the stream route also accepts the access token as access_token in
  the query string, because an audio element cannot send headers; no other
  route does, and the query string is never logged
- feat(storage): PlayableFile picks the oldest file of a track that is not
  flagged missing
- fix(api): internal errors set by handlers are now written to the request log
- test: range variants, HEAD, conditional requests, auth variants, traversal,
  symlink escape, symlinked root, missing file, directory instead of file
2026-11-11 12:56:20 +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