- 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
339 lines
10 KiB
Go
339 lines
10 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 artist name or MusicBrainz id you look up, 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
|
|
}
|
|
|
|
// 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
|
|
}
|
|
}
|