A client starts an upload with the soundtrack's name, sends one MP3 per
request, and finishes it. The server then moves the songs into a new folder
in the music folder and syncs only that folder, so the soundtrack is in the
library, lists and search right away.
- POST /api/v1/soundtracks/uploads, GET/DELETE .../uploads/{id},
PUT .../uploads/{id}/files/{file} and POST .../uploads/{id}/finish.
- Names must work as file names on every system and be free, ignoring case.
File names are plain: clients flatten disc folders.
- Only MP3 files. Size limits from UPLOAD_MAX_FILE_MB (50) and
UPLOAD_MAX_TOTAL_MB (2048).
- Refused while a sync runs, and a sync cannot start while an upload is
finished. Songs equal to an existing soundtrack's are refused, as the sync
would take them for that soundtrack renamed.
- Unfinished uploads live in MUSIC_PATH/.uploads and are removed after a day.
The sync now skips every hidden folder.
Closes#33
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Alternative names (#32):
- PUT /api/v1/soundtracks/{uuid}/alternative-names replaces a soundtrack's
alternative names (trimmed, deduplicated, without the soundtrack's own name).
- alternative_names is in the soundtrack and statistics responses.
- /find matches them too and shows which name matched.
Covers (#12), stored in COVERS_PATH and off when it is not set:
- GET, PUT (upload) and DELETE /api/v1/soundtracks/{uuid}/cover, and
PUT .../cover/source to pick a SteamGridDB game or AniList anime by ID.
Uploaded and picked covers are never replaced automatically.
- With STEAMGRIDDB_API_KEY, a background job searches SteamGridDB, then
AniList, by name, alternative names and the name without bracketed parts,
at startup, after a sync and after names change. Search results are ranked
by matching words, so "Civilization IV" gets "Sid Meier's Civilization IV".
- cover_modified (Unix seconds) is in the soundtrack and statistics responses,
so clients can cache covers.
The new columns are added to migration 000006, which is not released yet.
Closes#12, closes#32
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Metrics are served on METRICS_PORT (default 2112, "off" to disable), never on
the public port. Besides the Go runtime and process metrics this adds:
- http_requests_total and http_request_duration_seconds per route pattern,
from an Echo middleware.
- musicserver_songs_requested_total and musicserver_songs_played_total by
pick mode (random, low, classic). The mode is now stored with each queued
song (migration 000006, not released yet).
- Library size, sync duration, last successful sync, broken songs from the
last full sync, and the database connection pool.
Refs #35, #36, #37
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Echo compares allowed origins literally, so "https://*" and "http://*" never
matched a real origin and no CORS headers were sent. The allowed origins now
come from CORS_ALLOWED_ORIGINS (comma-separated, checked at startup). When it
is empty, only same-origin requests work, which is enough for the bundled
frontend.
Credentials are no longer allowed since the API uses Bearer tokens. Browsers
may now send Range and X-Queue-Id and read X-Queue-Id and Content-Range.
Security
- Serve character images through os.Root so names like ../ can't escape
the characters folder
- Sync start and /sync/reset are POST only (legacy and /api/v1)
- /api/v1/token/cleanup requires a token, password compared in constant
time, tokens no longer logged
- Echo's rate limiter replaces the custom one; TRUSTED_PROXIES enables
X-Forwarded-For for reverse proxies
Crashes and races
- Sync state lives in SyncService with atomics and a mutex instead of
unsynchronised globals (fixes concurrent map writes during full sync)
- Only one sync can run; /api/v1 sync and music routes are locked during
sync like the legacy ones
- No log.Fatal outside startup: errors become 4xx/5xx responses
- Search uses an in-order character match instead of unescaped regexes
- Empty queue / no songs return 404 instead of panicking or looping
Behaviour
- Sync result is computed once and stays the same between polls
- Swagger and /openapi serve the embedded spec
- Shutdown stops HTTP before closing the database
- Expired tokens are deleted with a context that outlives the request
- Files are served with Range support and correct content types; audio
has no write deadline
Performance
- Migration 000006 adds soundtrack.fingerprint (names, sizes, mtimes) so
unchanged folders are skipped without reading any files
- Songs are reconciled per soundtrack with one query plus needed writes;
renames keep play counts
- Moved MUSIC_PATH updates soundtrack and song paths
- .id cleanup only runs for changed soundtracks or a full sync
- Classic random uses one SQL query; Gitea release lookups are cached
with a timeout
Structure
- internal/config reads all environment variables once
- sqlc emits a Querier interface; backend globals become services
injected into handlers
- One route registration shared by legacy and /api/v1
- Removed dead code (dbHelper.go, unused middleware, duplicate Gitea
functions, embedded Swagger UI copy) and lib/pq
- templ and swag pinned as go tools
SansanandClaude Opus 5.5