feat: initial implementation of metadata aggregator

- gRPC service with MusicBrainz provider
- PostgreSQL schema with migrations
- Service layer with database-first caching
- Repository pattern for data access
- YAML configuration support
- Research documentation for 17 music metadata projects

internal/provider/musicbrainz/client.go

@@ -0,0 +1,127 @@
+package musicbrainz
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+	"net/url"
+	"time"
+
+	"golang.org/x/time/rate"
+)
+
+const (
+	baseURL   = "https://musicbrainz.org/ws/2"
+	userAgent = "MetadataAggregator/0.1.0 (https://github.com/metadata-agregator)"
+)
+
+type client struct {
+	http    *http.Client
+	limiter *rate.Limiter
+}
+
+func newClient() *client {
+	return &client{
+		http: &http.Client{
+			Timeout: 30 * time.Second,
+		},
+		limiter: rate.NewLimiter(rate.Every(time.Second), 1),
+	}
+}
+
+func (c *client) get(ctx context.Context, endpoint string, params url.Values) ([]byte, error) {
+	if err := c.limiter.Wait(ctx); err != nil {
+		return nil, fmt.Errorf("rate limiter: %w", err)
+	}
+
+	if params == nil {
+		params = url.Values{}
+	}
+	params.Set("fmt", "json")
+
+	reqURL := fmt.Sprintf("%s/%s?%s", baseURL, endpoint, params.Encode())
+
+	req, err := http.NewRequestWithContext(ctx, http.MethodGet, reqURL, nil)
+	if err != nil {
+		return nil, fmt.Errorf("create request: %w", err)
+	}
+
+	req.Header.Set("User-Agent", userAgent)
+	req.Header.Set("Accept", "application/json")
+
+	resp, err := c.http.Do(req)
+	if err != nil {
+		return nil, fmt.Errorf("do request: %w", err)
+	}
+	defer resp.Body.Close()
+
+	if resp.StatusCode == http.StatusNotFound {
+		return nil, ErrNotFound
+	}
+
+	if resp.StatusCode == http.StatusServiceUnavailable {
+		return nil, ErrRateLimited
+	}
+
+	if resp.StatusCode != http.StatusOK {
+		body, _ := io.ReadAll(resp.Body)
+		return nil, fmt.Errorf("unexpected status %d: %s", resp.StatusCode, string(body))
+	}
+
+	return io.ReadAll(resp.Body)
+}
+
+func (c *client) lookup(ctx context.Context, entity, id string, inc []string) ([]byte, error) {
+	params := url.Values{}
+	if len(inc) > 0 {
+		incStr := ""
+		for i, v := range inc {
+			if i > 0 {
+				incStr += "+"
+			}
+			incStr += v
+		}
+		params.Set("inc", incStr)
+	}
+
+	return c.get(ctx, fmt.Sprintf("%s/%s", entity, id), params)
+}
+
+func (c *client) browse(ctx context.Context, entity, linkedEntity, linkedID string, limit, offset int, inc []string) ([]byte, error) {
+	params := url.Values{}
+	params.Set(linkedEntity, linkedID)
+	params.Set("limit", fmt.Sprintf("%d", limit))
+	params.Set("offset", fmt.Sprintf("%d", offset))
+
+	if len(inc) > 0 {
+		incStr := ""
+		for i, v := range inc {
+			if i > 0 {
+				incStr += "+"
+			}
+			incStr += v
+		}
+		params.Set("inc", incStr)
+	}
+
+	return c.get(ctx, entity, params)
+}
+
+func (c *client) search(ctx context.Context, entity, query string, limit, offset int) ([]byte, error) {
+	params := url.Values{}
+	params.Set("query", query)
+	params.Set("limit", fmt.Sprintf("%d", limit))
+	params.Set("offset", fmt.Sprintf("%d", offset))
+
+	return c.get(ctx, entity, params)
+}
+
+func decode[T any](data []byte) (*T, error) {
+	var result T
+	if err := json.Unmarshal(data, &result); err != nil {
+		return nil, fmt.Errorf("decode: %w", err)
+	}
+	return &result, nil
+}