Restructure backend into services and fix security, crash and sync issues

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
This commit is contained in:
Sansan committed 2026-10-06 15:20:14 +02:00
1 parent 75b6f0c1cf
commit 090e794460
78 files changed
+2919 -6303

No files matched your search

+193 -161
View File
@@ -1,15 +1,24 @@
{
"swagger": "2.0",
"info": {
"contact": {}
"description": "API for the MusicServer application",
"title": "MusicServer API",
"termsOfService": "http://sanplex.xyz/terms/",
"contact": {
"name": "Sebastian Olsson",
"email": "zarnor91@gmail.com"
},
"license": {
"name": "MIT",
"url": "http://opensource.org/licenses/MIT"
},
"version": "1.0"
},
"basePath": "/",
"paths": {
"/api/v1/statistics/songs/least-played": {
"get": {
"description": "Returns the top N least played songs with their soundtrack info",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
@@ -20,7 +29,7 @@
"parameters": [
{
"type": "integer",
"description": "Number of results (default: 10)",
"description": "Number of results (default: 10, max: 100)",
"name": "limit",
"in": "query"
}
@@ -59,9 +68,6 @@
"/api/v1/statistics/songs/most-played": {
"get": {
"description": "Returns the top N most played songs with their soundtrack info",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
@@ -72,7 +78,7 @@
"parameters": [
{
"type": "integer",
"description": "Number of results (default: 10)",
"description": "Number of results (default: 10, max: 100)",
"name": "limit",
"in": "query"
}
@@ -110,10 +116,7 @@
},
"/api/v1/statistics/soundtracks/last-played": {
"get": {
"description": "Returns the most recently played soundtracks",
"consumes": [
"application/json"
],
"description": "Returns the most recently played soundtracks with their songs",
"produces": [
"application/json"
],
@@ -124,7 +127,7 @@
"parameters": [
{
"type": "integer",
"description": "Number of results (default: 10)",
"description": "Number of results (default: 10, max: 100)",
"name": "limit",
"in": "query"
}
@@ -163,9 +166,6 @@
"/api/v1/statistics/soundtracks/least-played": {
"get": {
"description": "Returns the top N least played soundtracks with their songs",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
@@ -176,7 +176,7 @@
"parameters": [
{
"type": "integer",
"description": "Number of results (default: 10)",
"description": "Number of results (default: 10, max: 100)",
"name": "limit",
"in": "query"
}
@@ -215,9 +215,6 @@
"/api/v1/statistics/soundtracks/most-played": {
"get": {
"description": "Returns the top N most played soundtracks with their songs",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
@@ -228,7 +225,7 @@
"parameters": [
{
"type": "integer",
"description": "Number of results (default: 10)",
"description": "Number of results (default: 10, max: 100)",
"name": "limit",
"in": "query"
}
@@ -266,10 +263,7 @@
},
"/api/v1/statistics/soundtracks/never-played": {
"get": {
"description": "Returns all soundtracks that have never been played (times_played = 0)",
"consumes": [
"application/json"
],
"description": "Returns all soundtracks that have never been played",
"produces": [
"application/json"
],
@@ -301,10 +295,7 @@
},
"/api/v1/statistics/soundtracks/oldest-played": {
"get": {
"description": "Returns the least recently played soundtracks (that have been played at least once)",
"consumes": [
"application/json"
],
"description": "Returns the least recently played soundtracks with their songs",
"produces": [
"application/json"
],
@@ -315,7 +306,7 @@
"parameters": [
{
"type": "integer",
"description": "Number of results (default: 10)",
"description": "Number of results (default: 10, max: 100)",
"name": "limit",
"in": "query"
}
@@ -353,10 +344,7 @@
},
"/api/v1/statistics/summary": {
"get": {
"description": "Returns overall statistics about the music library",
"consumes": [
"application/json"
],
"description": "Returns overall play statistics",
"produces": [
"application/json"
],
@@ -385,7 +373,7 @@
},
"/api/v1/token": {
"post": {
"description": "Returns a new session token for API access. Requires valid API password.",
"description": "Returns a new session token for API access. Requires the API password when one is configured.",
"consumes": [
"application/json"
],
@@ -432,6 +420,15 @@
}
}
},
"429": {
"description": "Too Many Requests",
"schema": {
"type": "object",
"additionalProperties": {
"type": "string"
}
}
},
"500": {
"description": "Internal Server Error",
"schema": {
@@ -445,9 +442,6 @@
},
"delete": {
"description": "Deletes the current session token",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
@@ -498,9 +492,6 @@
"/api/v1/token/cleanup": {
"post": {
"description": "Removes all expired session tokens from the database",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
@@ -522,7 +513,9 @@
"description": "OK",
"schema": {
"type": "object",
"additionalProperties": true
"additionalProperties": {
"type": "string"
}
}
},
"401": {
@@ -549,11 +542,9 @@
"/character": {
"get": {
"description": "Returns the image for a specific character",
"consumes": [
"application/json"
],
"produces": [
"image/png"
"image/png",
"image/jpeg"
],
"tags": [
"characters"
@@ -562,7 +553,7 @@
"parameters": [
{
"type": "string",
"description": "Character name",
"description": "Character file name",
"name": "name",
"in": "query",
"required": true
@@ -574,6 +565,18 @@
"schema": {
"type": "file"
}
},
"400": {
"description": "invalid name",
"schema": {
"type": "string"
}
},
"404": {
"description": "not found",
"schema": {
"type": "string"
}
}
}
}
@@ -581,9 +584,6 @@
"/characters": {
"get": {
"description": "Returns a list of all available characters",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
@@ -606,10 +606,7 @@
},
"/download": {
"get": {
"description": "Checks for the latest version of the application",
"consumes": [
"application/json"
],
"description": "Returns the latest version of the client application",
"produces": [
"application/json"
],
@@ -623,6 +620,12 @@
"schema": {
"type": "string"
}
},
"502": {
"description": "upstream service unavailable",
"schema": {
"type": "string"
}
}
}
}
@@ -630,9 +633,6 @@
"/download/linux": {
"get": {
"description": "Redirects to download the latest Linux version",
"produces": [
"application/octet-stream"
],
"tags": [
"download"
],
@@ -643,6 +643,18 @@
"schema": {
"type": "string"
}
},
"404": {
"description": "not found",
"schema": {
"type": "string"
}
},
"502": {
"description": "upstream service unavailable",
"schema": {
"type": "string"
}
}
}
}
@@ -650,9 +662,6 @@
"/download/list": {
"get": {
"description": "Lists all assets available for the latest version",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
@@ -669,6 +678,12 @@
"type": "string"
}
}
},
"502": {
"description": "upstream service unavailable",
"schema": {
"type": "string"
}
}
}
}
@@ -676,9 +691,6 @@
"/download/windows": {
"get": {
"description": "Redirects to download the latest Windows version",
"produces": [
"application/octet-stream"
],
"tags": [
"download"
],
@@ -689,6 +701,18 @@
"schema": {
"type": "string"
}
},
"404": {
"description": "not found",
"schema": {
"type": "string"
}
},
"502": {
"description": "upstream service unavailable",
"schema": {
"type": "string"
}
}
}
}
@@ -696,9 +720,6 @@
"/health": {
"get": {
"description": "Returns the health status of the server",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
@@ -710,7 +731,10 @@
"200": {
"description": "OK",
"schema": {
"type": "string"
"type": "object",
"additionalProperties": {
"type": "string"
}
}
}
}
@@ -718,10 +742,7 @@
},
"/music": {
"get": {
"description": "Returns a specific song by name",
"consumes": [
"application/json"
],
"description": "Returns the song at the given position in the queue",
"produces": [
"audio/mpeg"
],
@@ -731,8 +752,8 @@
"summary": "Get a specific song",
"parameters": [
{
"type": "string",
"description": "Song name",
"type": "integer",
"description": "Song number in the queue",
"name": "song",
"in": "query",
"required": true
@@ -745,8 +766,14 @@
"type": "file"
}
},
"206": {
"description": "Partial Content",
"schema": {
"type": "file"
}
},
"400": {
"description": "song can't be empty",
"description": "song must be a number",
"schema": {
"type": "string"
}
@@ -768,17 +795,14 @@
},
"/music/addPlayed": {
"get": {
"description": "Adds the latest song to the played list",
"consumes": [
"application/json"
],
"description": "Marks the current song as played",
"tags": [
"music"
],
"summary": "Add latest to played",
"responses": {
"204": {
"description": ""
"200": {
"description": "OK"
},
"423": {
"description": "Syncing is in progress",
@@ -792,16 +816,13 @@
"/music/addQue": {
"get": {
"description": "Adds the latest song to the queue",
"consumes": [
"application/json"
],
"tags": [
"music"
],
"summary": "Add latest to queue",
"responses": {
"204": {
"description": ""
"200": {
"description": "OK"
},
"423": {
"description": "Syncing is in progress",
@@ -815,9 +836,6 @@
"/music/all/order": {
"get": {
"description": "Returns a list of all soundtracks in order",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
@@ -831,8 +849,7 @@
"schema": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true
"type": "string"
}
}
},
@@ -848,9 +865,6 @@
"/music/all/random": {
"get": {
"description": "Returns a list of all soundtracks in random order",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
@@ -864,8 +878,7 @@
"schema": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true
"type": "string"
}
}
},
@@ -881,9 +894,6 @@
"/music/info": {
"get": {
"description": "Returns information about the current song",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
@@ -895,8 +905,7 @@
"200": {
"description": "OK",
"schema": {
"type": "object",
"additionalProperties": true
"$ref": "#/definitions/backend.SongInfo"
}
}
}
@@ -905,9 +914,6 @@
"/music/list": {
"get": {
"description": "Returns a list of played songs",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
@@ -921,8 +927,7 @@
"schema": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true
"$ref": "#/definitions/backend.SongInfo"
}
}
}
@@ -963,13 +968,7 @@
},
"/music/played": {
"put": {
"description": "Marks a song as played by its ID",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"description": "Marks the song at the given queue position as played",
"tags": [
"music"
],
@@ -977,15 +976,15 @@
"parameters": [
{
"type": "integer",
"description": "Song ID",
"description": "Song number in the queue",
"name": "song",
"in": "query",
"required": true
}
],
"responses": {
"204": {
"description": ""
"200": {
"description": "OK"
},
"400": {
"description": "Bad Request",
@@ -1068,7 +1067,7 @@
},
"/music/rand/classic": {
"get": {
"description": "Returns a random song from the classic selection",
"description": "Returns a random song where every song has the same chance",
"produces": [
"audio/mpeg"
],
@@ -1100,7 +1099,7 @@
},
"/music/rand/low": {
"get": {
"description": "Returns a random song with low chance selection",
"description": "Returns a random song, favouring soundtracks that have been played less",
"produces": [
"audio/mpeg"
],
@@ -1133,16 +1132,13 @@
"/music/reset": {
"get": {
"description": "Resets the music state",
"consumes": [
"application/json"
],
"tags": [
"music"
],
"summary": "Reset music state",
"responses": {
"204": {
"description": ""
"200": {
"description": "OK"
},
"423": {
"description": "Syncing is in progress",
@@ -1186,11 +1182,8 @@
}
},
"/sync": {
"get": {
"description": "Starts syncing soundtracks with only new changes",
"consumes": [
"application/json"
],
"post": {
"description": "Starts syncing soundtracks that have changed",
"produces": [
"application/json"
],
@@ -1215,11 +1208,8 @@
}
},
"/sync/full": {
"get": {
"post": {
"description": "Starts a full sync of all soundtracks",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
@@ -1245,10 +1235,7 @@
},
"/sync/progress": {
"get": {
"description": "Returns the current sync progress or result",
"consumes": [
"application/json"
],
"description": "Returns the progress of the running sync, or the result of the last sync",
"produces": [
"application/json"
],
@@ -1260,19 +1247,15 @@
"200": {
"description": "OK",
"schema": {
"type": "object",
"additionalProperties": true
"$ref": "#/definitions/backend.SyncResponse"
}
}
}
}
},
"/sync/reset": {
"get": {
"post": {
"description": "Resets the soundtracks database by deleting all soundtracks and songs",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
@@ -1299,9 +1282,6 @@
"/version": {
"get": {
"description": "get latest version info",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
@@ -1315,12 +1295,6 @@
"schema": {
"$ref": "#/definitions/backend.VersionData"
}
},
"404": {
"description": "Not Found",
"schema": {
"type": "string"
}
}
}
}
@@ -1328,9 +1302,6 @@
"/version/history": {
"get": {
"description": "get version history",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
@@ -1347,18 +1318,35 @@
"$ref": "#/definitions/backend.VersionData"
}
}
},
"404": {
"description": "Not Found",
"schema": {
"type": "string"
}
}
}
}
}
},
"definitions": {
"backend.SongInfo": {
"type": "object",
"properties": {
"CurrentlyPlaying": {
"type": "boolean"
},
"Song": {
"type": "string"
},
"SongNo": {
"type": "integer"
},
"SongPlayed": {
"type": "integer"
},
"Soundtrack": {
"type": "string"
},
"SoundtrackPlayed": {
"type": "integer"
}
}
},
"backend.SongInfoForStats": {
"type": "object",
"properties": {
@@ -1431,6 +1419,50 @@
}
}
},
"backend.SyncResponse": {
"type": "object",
"properties": {
"catched_errors": {
"type": "array",
"items": {
"type": "string"
}
},
"soundtracks_added": {
"type": "array",
"items": {
"type": "string"
}
},
"soundtracks_changed_content": {
"type": "array",
"items": {
"type": "string"
}
},
"soundtracks_changed_title": {
"type": "object",
"additionalProperties": {
"type": "string"
}
},
"soundtracks_re_added": {
"type": "array",
"items": {
"type": "string"
}
},
"soundtracks_removed": {
"type": "array",
"items": {
"type": "string"
}
},
"total_time": {
"type": "string"
}
}
},
"backend.VersionData": {
"type": "object",
"properties": {
@@ -1458,7 +1490,7 @@
"type": "string"
},
"password": {
"description": "Required: API password",
"description": "API password, required when API_PASSWORD is set",
"type": "string"
}
}