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
This commit is contained in:
tgiachi 2026-11-11 12:06:15 +01:00
commit 3a739dc3ae
5 changed files with 2739 additions and 0 deletions

29
migrations/embed.go Normal file
View file

@ -0,0 +1,29 @@
// Package migrations embeds the versioned SQL migrations, one folder per
// database driver. Both folders must describe the same schema.
//
// Files are named NNNN_description.sql and applied in lexical order.
package migrations
import (
"embed"
"fmt"
"io/fs"
)
//go:embed sqlite/*.sql
var sqliteFS embed.FS
//go:embed postgres/*.sql
var postgresFS embed.FS
// For returns the migrations for driver ("sqlite" or "postgres").
func For(driver string) (fs.FS, error) {
switch driver {
case "sqlite":
return fs.Sub(sqliteFS, "sqlite")
case "postgres":
return fs.Sub(postgresFS, "postgres")
default:
return nil, fmt.Errorf("unknown database driver %q", driver)
}
}

View file

@ -0,0 +1,55 @@
-- Core catalog for local music (M1). PostgreSQL flavour of sqlite/0001_init.sql.
-- Keep both files in step: same tables, same columns, same meaning.
CREATE TABLE artists (
id BIGINT GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY,
mbid TEXT UNIQUE, -- MusicBrainz artist id, NULL when unknown
name TEXT NOT NULL,
tags TEXT NOT NULL DEFAULT '[]' -- JSON array
);
CREATE TABLE albums (
id BIGINT GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY,
mbid TEXT UNIQUE, -- MusicBrainz release-group id, NULL when unknown
title TEXT NOT NULL,
artist_id BIGINT REFERENCES artists(id)
);
CREATE TABLE tracks (
id BIGINT GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY,
title TEXT NOT NULL,
duration_ms BIGINT,
track_no INTEGER,
disc_no INTEGER,
album_id BIGINT REFERENCES albums(id),
recording_mbid TEXT UNIQUE -- MusicBrainz recording id, NULL when unknown
);
CREATE TABLE track_artists (
track_id BIGINT NOT NULL REFERENCES tracks(id) ON DELETE CASCADE,
artist_id BIGINT NOT NULL REFERENCES artists(id) ON DELETE CASCADE,
role TEXT NOT NULL DEFAULT 'main',
PRIMARY KEY (track_id, artist_id, role)
);
-- Physical files, kept separate from tracks so several encodings can exist.
-- Missing files are marked, not deleted, so history survives a rescan.
CREATE TABLE audio_files (
id BIGINT GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY,
track_id BIGINT NOT NULL REFERENCES tracks(id) ON DELETE CASCADE,
root TEXT NOT NULL, -- configured library root the file belongs to
rel_path TEXT NOT NULL, -- relative to that root
format TEXT NOT NULL,
size_bytes BIGINT NOT NULL,
mtime_unix BIGINT NOT NULL,
sample_rate INTEGER,
bitrate INTEGER,
content_hash TEXT,
missing_at BIGINT, -- unix time the file was last seen missing
UNIQUE (root, rel_path)
);
CREATE INDEX idx_albums_artist ON albums(artist_id);
CREATE INDEX idx_tracks_album ON tracks(album_id);
CREATE INDEX idx_track_artists_artist ON track_artists(artist_id);
CREATE INDEX idx_audio_files_track ON audio_files(track_id);

View file

@ -0,0 +1,26 @@
-- Local users and the listening history. PostgreSQL flavour of sqlite/0002_users_listening.sql.
CREATE TABLE users (
id BIGINT GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY,
username TEXT NOT NULL,
password_hash TEXT NOT NULL, -- Argon2id PHC string
created_at BIGINT NOT NULL -- unix seconds
);
-- Case-insensitive uniqueness (SQLite uses COLLATE NOCASE for the same effect).
CREATE UNIQUE INDEX users_username_lower ON users (lower(username));
-- Explicit listen events only. Opening or prefetching an audio URL is never recorded.
CREATE TABLE listening_events (
id BIGINT GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY,
user_id BIGINT NOT NULL REFERENCES users(id) ON DELETE CASCADE,
track_id BIGINT NOT NULL REFERENCES tracks(id) ON DELETE CASCADE,
event_type TEXT NOT NULL CHECK (event_type IN ('play', 'complete', 'skip')),
occurred_at BIGINT NOT NULL, -- unix seconds, client or server time
duration_played_ms BIGINT NOT NULL DEFAULT 0 CHECK (duration_played_ms >= 0),
idempotency_key TEXT NOT NULL, -- client generated, makes retries safe
UNIQUE (user_id, idempotency_key)
);
CREATE INDEX idx_listening_user_time ON listening_events(user_id, occurred_at);
CREATE INDEX idx_listening_track ON listening_events(track_id);

View file

@ -0,0 +1,55 @@
-- Core catalog for local music (M1).
-- Internal ids are authoritative; MusicBrainz ids are optional and never invented.
CREATE TABLE artists (
id INTEGER PRIMARY KEY,
mbid TEXT UNIQUE, -- MusicBrainz artist id, NULL when unknown
name TEXT NOT NULL,
tags TEXT NOT NULL DEFAULT '[]' -- JSON array
);
CREATE TABLE albums (
id INTEGER PRIMARY KEY,
mbid TEXT UNIQUE, -- MusicBrainz release-group id, NULL when unknown
title TEXT NOT NULL,
artist_id INTEGER REFERENCES artists(id)
);
CREATE TABLE tracks (
id INTEGER PRIMARY KEY,
title TEXT NOT NULL,
duration_ms INTEGER,
track_no INTEGER,
disc_no INTEGER,
album_id INTEGER REFERENCES albums(id),
recording_mbid TEXT UNIQUE -- MusicBrainz recording id, NULL when unknown
);
CREATE TABLE track_artists (
track_id INTEGER NOT NULL REFERENCES tracks(id) ON DELETE CASCADE,
artist_id INTEGER NOT NULL REFERENCES artists(id) ON DELETE CASCADE,
role TEXT NOT NULL DEFAULT 'main',
PRIMARY KEY (track_id, artist_id, role)
);
-- Physical files, kept separate from tracks so several encodings can exist.
-- Missing files are marked, not deleted, so history survives a rescan.
CREATE TABLE audio_files (
id INTEGER PRIMARY KEY,
track_id INTEGER NOT NULL REFERENCES tracks(id) ON DELETE CASCADE,
root TEXT NOT NULL, -- configured library root the file belongs to
rel_path TEXT NOT NULL, -- relative to that root
format TEXT NOT NULL,
size_bytes INTEGER NOT NULL,
mtime_unix INTEGER NOT NULL,
sample_rate INTEGER,
bitrate INTEGER,
content_hash TEXT,
missing_at INTEGER, -- unix time the file was last seen missing
UNIQUE (root, rel_path)
);
CREATE INDEX idx_albums_artist ON albums(artist_id);
CREATE INDEX idx_tracks_album ON tracks(album_id);
CREATE INDEX idx_track_artists_artist ON track_artists(artist_id);
CREATE INDEX idx_audio_files_track ON audio_files(track_id);

View file

@ -0,0 +1,23 @@
-- Local users and the listening history used for recommendations.
CREATE TABLE users (
id INTEGER PRIMARY KEY,
username TEXT NOT NULL UNIQUE COLLATE NOCASE,
password_hash TEXT NOT NULL, -- Argon2id PHC string
created_at INTEGER NOT NULL -- unix seconds
);
-- Explicit listen events only. Opening or prefetching an audio URL is never recorded.
CREATE TABLE listening_events (
id INTEGER PRIMARY KEY,
user_id INTEGER NOT NULL REFERENCES users(id) ON DELETE CASCADE,
track_id INTEGER NOT NULL REFERENCES tracks(id) ON DELETE CASCADE,
event_type TEXT NOT NULL CHECK (event_type IN ('play', 'complete', 'skip')),
occurred_at INTEGER NOT NULL, -- unix seconds, client or server time
duration_played_ms INTEGER NOT NULL DEFAULT 0 CHECK (duration_played_ms >= 0),
idempotency_key TEXT NOT NULL, -- client generated, makes retries safe
UNIQUE (user_id, idempotency_key)
);
CREATE INDEX idx_listening_user_time ON listening_events(user_id, occurred_at);
CREATE INDEX idx_listening_track ON listening_events(track_id);