sonda/internal/providers/settings.go
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

385 lines
12 KiB
Go

// Package providers manages the external services Sonda can ask about artists
// (Last.fm, MusicBrainz) and the rules for talking to them.
//
// Nothing here makes a request on its own. Every provider is off until an admin
// turns it on, and the settings (including any API key) live in the database.
package providers
import (
"context"
"errors"
"fmt"
"regexp"
"strings"
"sync"
"time"
"unicode"
"unicode/utf8"
)
// The providers Sonda knows.
const (
LastFM = "lastfm"
MusicBrainz = "musicbrainz"
)
// Errors returned by the service.
var (
ErrUnknownProvider = errors.New("unknown provider")
ErrInvalidSettings = errors.New("invalid provider settings")
ErrNoTest = errors.New("this provider has no test")
)
// What a checker says went wrong, so that the result of a test does not depend
// on the client of any one provider.
var (
ErrKeyRefused = errors.New("the provider refused the API key")
ErrRateLimited = errors.New("the provider's rate limit was reached")
ErrUnreachable = errors.New("the provider could not be reached")
)
const maxContactLen = 200
var lastfmKeyRe = regexp.MustCompile(`^[0-9a-f]{32}$`)
// Settings are the stored settings of one provider, API key included. They are
// only for code that talks to the provider; the API never returns the key.
type Settings struct {
Provider string
Enabled bool
APIKey string
Contact string // goes into the User-Agent; empty means the project address
UpdatedAt time.Time
}
// Info is what the API shows about a provider: the settings without the key,
// plus a plain statement of what leaves the server.
type Info struct {
Name string
Enabled bool
NeedsAPIKey bool
HasAPIKey bool
Contact string
Sends string // what is sent to the provider, and what never is
Notes string // terms of use and attribution
UpdatedAt time.Time // zero when the provider was never configured
}
// Patch changes some settings. A nil field is left alone. An empty APIKey or
// Contact clears it.
type Patch struct {
Enabled *bool
APIKey *string
Contact *string
}
// Store persists provider settings.
type Store interface {
// Get returns found=false when the provider was never configured.
Get(ctx context.Context, name string) (s Settings, found bool, err error)
List(ctx context.Context) ([]Settings, error)
Save(ctx context.Context, s Settings) error
}
type meta struct {
name string
needsKey bool
sends, note string
}
// known lists the providers in the order the API shows them.
var known = []meta{
{
name: LastFM,
needsKey: true,
sends: "The artist name (or MusicBrainz id) you look up, your API key, your IP address and the " +
"User-Agent. Never your users, your listens, track titles or file paths.",
note: "Last.fm data is for non-commercial use only. Credit Last.fm when you show it. " +
"Images are not licensed and are never stored.",
},
{
name: MusicBrainz,
sends: "The MusicBrainz id of the artist you look up (never a name: Sonda does not search), your " +
"IP address and the User-Agent, which carries the contact below. Never your users, your listens, " +
"track titles or file paths.",
note: "Core data (artist names and ids) is public domain. Tags and genres are CC BY-NC-SA 3.0: " +
"non-commercial, with attribution to MusicBrainz.",
},
}
func lookup(name string) (meta, bool) {
for _, m := range known {
if m.name == name {
return m, true
}
}
return meta{}, false
}
// Service reads and changes provider settings.
type Service struct {
store Store
now func() time.Time
mu sync.Mutex // an update reads then writes: keep two of them apart
checkers map[string]Checker
purger Purger
}
// NewService builds a Service.
func NewService(store Store) *Service { return &Service{store: store, now: time.Now} }
func info(m meta, s Settings) Info {
return Info{
Name: m.name, NeedsAPIKey: m.needsKey, Sends: m.sends, Notes: m.note,
Enabled: s.Enabled, HasAPIKey: s.APIKey != "", Contact: s.Contact, UpdatedAt: s.UpdatedAt,
}
}
// List returns every known provider, configured or not, in a fixed order.
func (s *Service) List(ctx context.Context) ([]Info, error) {
rows, err := s.store.List(ctx)
if err != nil {
return nil, fmt.Errorf("list provider settings: %w", err)
}
byName := map[string]Settings{}
for _, r := range rows {
byName[r.Provider] = r
}
out := make([]Info, 0, len(known))
for _, m := range known {
out = append(out, info(m, byName[m.name]))
}
return out, nil
}
// Update applies a patch and returns the provider as it is afterwards.
func (s *Service) Update(ctx context.Context, name string, p Patch) (Info, error) {
m, ok := lookup(name)
if !ok {
return Info{}, ErrUnknownProvider
}
if p.Enabled == nil && p.APIKey == nil && p.Contact == nil {
return Info{}, fmt.Errorf("%w: nothing to change", ErrInvalidSettings)
}
s.mu.Lock()
defer s.mu.Unlock()
cur, _, err := s.store.Get(ctx, name)
if err != nil {
return Info{}, fmt.Errorf("read provider settings: %w", err)
}
cur.Provider = name
if p.APIKey != nil {
key, err := validateKey(m, *p.APIKey)
if err != nil {
return Info{}, err
}
cur.APIKey = key
if key == "" && m.needsKey {
cur.Enabled = false // a provider that needs a key is off without one
}
}
if p.Contact != nil {
contact, err := validateContact(*p.Contact)
if err != nil {
return Info{}, err
}
cur.Contact = contact
}
if p.Enabled != nil {
if *p.Enabled && m.needsKey && cur.APIKey == "" {
return Info{}, fmt.Errorf("%w: %s needs an API key before it can be enabled", ErrInvalidSettings, name)
}
cur.Enabled = *p.Enabled
}
cur.UpdatedAt = s.now()
if err := s.store.Save(ctx, cur); err != nil {
return Info{}, fmt.Errorf("save provider settings: %w", err)
}
return info(m, cur), nil
}
// Active returns the settings of a provider when it can be used right now: it
// is on and, if it needs a key, has one. Provider clients call this before
// every outbound request; false means "do not contact anyone".
func (s *Service) Active(ctx context.Context, name string) (Settings, bool, error) {
m, ok := lookup(name)
if !ok {
return Settings{}, false, ErrUnknownProvider
}
cur, found, err := s.store.Get(ctx, name)
if err != nil {
return Settings{}, false, fmt.Errorf("read provider settings: %w", err)
}
if !found || !cur.Enabled || (m.needsKey && cur.APIKey == "") {
return Settings{}, false, nil
}
return cur, true, nil
}
func validateKey(m meta, raw string) (string, error) {
key := strings.ToLower(strings.TrimSpace(raw))
if key == "" {
return "", nil
}
if !m.needsKey {
return "", fmt.Errorf("%w: %s does not use an API key", ErrInvalidSettings, m.name)
}
if m.name == LastFM && !lastfmKeyRe.MatchString(key) {
return "", fmt.Errorf("%w: a Last.fm API key is 32 hexadecimal characters", ErrInvalidSettings)
}
return key, nil
}
// validateContact accepts what MusicBrainz asks for in a User-Agent: a URL or an
// e-mail address. Parentheses are refused because they delimit it there.
func validateContact(raw string) (string, error) {
c := strings.TrimSpace(raw)
if utf8.RuneCountInString(c) > maxContactLen {
return "", fmt.Errorf("%w: contact is longer than %d characters", ErrInvalidSettings, maxContactLen)
}
for _, r := range c {
if unicode.IsControl(r) || r == '(' || r == ')' {
return "", fmt.Errorf("%w: contact cannot contain control characters or parentheses", ErrInvalidSettings)
}
}
return c, nil
}
// ProjectURL is the contact used in the User-Agent when no other is set.
const ProjectURL = "https://codeberg.org/squidd/sonda"
// UserAgent builds the header sent to providers, in the shape MusicBrainz asks
// for: "Application/version ( contact )". The version and the contact are
// cleaned, so the result is always a single safe line.
func UserAgent(version, contact string) string {
clean := func(s string) string {
var b strings.Builder
for _, r := range s {
if unicode.IsControl(r) || r == '(' || r == ')' {
continue
}
b.WriteRune(r)
}
return strings.TrimSpace(b.String())
}
v := strings.ReplaceAll(clean(version), " ", "")
if v == "" {
v = "dev"
}
c := clean(contact)
if c == "" {
c = ProjectURL
}
return fmt.Sprintf("Sonda/%s ( %s )", v, c)
}
// Checker asks a provider one cheap question with a key, to find out whether the
// key works. It returns nil, or one of ErrKeyRefused, ErrRateLimited and
// ErrUnreachable (any other error counts as an unknown failure).
type Checker func(ctx context.Context, key string) error
// SetChecker registers the test of a provider. Call it before the service is used.
func (s *Service) SetChecker(name string, c Checker) {
if s.checkers == nil {
s.checkers = map[string]Checker{}
}
s.checkers[name] = c
}
// Results of a test.
const (
TestOK = "ok"
TestNoKey = "no_api_key"
TestKeyRefused = "key_refused"
TestRateLimited = "rate_limited"
TestUnreachable = "unreachable"
TestFailed = "error"
)
// TestResult is the outcome of Test. Status is one of the Test constants.
type TestResult struct {
OK bool
Status string
}
// Test checks a provider with the stored key. It works whether the provider is
// on or off, because an admin wants to know before switching it on; it is the one
// request Sonda makes on demand of an admin and not of a listener, and it sends
// nothing but the key. The key is never part of the result.
func (s *Service) Test(ctx context.Context, name string) (TestResult, error) {
m, ok := lookup(name)
if !ok {
return TestResult{}, ErrUnknownProvider
}
check := s.checkers[name]
if check == nil {
return TestResult{}, ErrNoTest
}
cur, _, err := s.store.Get(ctx, name)
if err != nil {
return TestResult{}, fmt.Errorf("read provider settings: %w", err)
}
if m.needsKey && cur.APIKey == "" {
return TestResult{Status: TestNoKey}, nil
}
switch err := check(ctx, cur.APIKey); {
case err == nil:
return TestResult{OK: true, Status: TestOK}, nil
case errors.Is(err, ErrKeyRefused):
return TestResult{Status: TestKeyRefused}, nil
case errors.Is(err, ErrRateLimited):
return TestResult{Status: TestRateLimited}, nil
case errors.Is(err, ErrUnreachable):
return TestResult{Status: TestUnreachable}, nil
default:
return TestResult{Status: TestFailed}, nil
}
}
// UserAgentFor returns a function that builds the User-Agent for a provider from
// the contact stored now, so a change by an admin applies to the next request.
// If the settings cannot be read it uses the project address: a request is never
// held up or sent with a broken header because of it.
func (s *Service) UserAgentFor(name, version string) func() string {
return func() string {
ctx, cancel := context.WithTimeout(context.Background(), 2*time.Second)
defer cancel()
cur, _, err := s.store.Get(ctx, name)
if err != nil {
return UserAgent(version, "")
}
return UserAgent(version, cur.Contact)
}
}
// Purged says how much a purge removed.
type Purged struct {
SimilarArtists int // lists of similar artists
Tags int // tags
Artists int // artists that only the removed data named
}
// Purger removes everything a provider gave, and reports how much.
type Purger func(ctx context.Context, name string) (Purged, error)
// SetPurger registers how provider data is removed. Call it before the service is used.
func (s *Service) SetPurger(p Purger) { s.purger = p }
// Purge removes everything a provider gave: what it said about artists, and the
// artists that only that data named and that nobody has files for. It works
// whether the provider is on or off and does not change that; a provider that is
// still on will be asked again when someone asks. Last.fm's terms ask for exactly
// this at the end of an agreement. The user's music, artists and listens stay.
func (s *Service) Purge(ctx context.Context, name string) (Purged, error) {
if _, ok := lookup(name); !ok {
return Purged{}, ErrUnknownProvider
}
if s.purger == nil {
return Purged{}, errors.New("no way to remove provider data was set up")
}
return s.purger(ctx, name)
}