Sansan/MusicServer
1
0 Fork 0
Code Issues 9 Pull Requests 1 Actions Packages Projects Releases Wiki Activity

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

Browse Source 
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
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

cmd/docs/swagger.yaml
+147 -126
View File
@@ -1,4 +1,20 @@
basePath: /
definitions:
backend.SongInfo:
properties:
CurrentlyPlaying:
type: boolean
Song:
type: string
SongNo:
type: integer
SongPlayed:
type: integer
Soundtrack:
type: string
SoundtrackPlayed:
type: integer
type: object
backend.SongInfoForStats:
properties:
file_name:
@@ -46,6 +62,35 @@ definitions:
total_soundtracks:
type: integer
type: object
backend.SyncResponse:
properties:
catched_errors:
items:
type: string
type: array
soundtracks_added:
items:
type: string
type: array
soundtracks_changed_content:
items:
type: string
type: array
soundtracks_changed_title:
additionalProperties:
type: string
type: object
soundtracks_re_added:
items:
type: string
type: array
soundtracks_removed:
items:
type: string
type: array
total_time:
type: string
type: object
backend.VersionData:
properties:
changelog:
@@ -65,7 +110,7 @@ definitions:
description: 'Optional: "web", "mobile", "api"'
type: string
password:
description: 'Required: API password'
description: API password, required when API_PASSWORD is set
type: string
type: object
server.TokenResponse:
@@ -78,15 +123,22 @@ definitions:
type: string
type: object
info:
contact: {}
contact:
email: zarnor91@gmail.com
name: Sebastian Olsson
description: API for the MusicServer application
license:
name: MIT
url: http://opensource.org/licenses/MIT
termsOfService: http://sanplex.xyz/terms/
title: MusicServer API
version: "1.0"
paths:
/api/v1/statistics/songs/least-played:
get:
consumes:
- application/json
description: Returns the top N least played songs with their soundtrack info
parameters:
- description: 'Number of results (default: 10)'
- description: 'Number of results (default: 10, max: 100)'
in: query
name: limit
type: integer
@@ -116,11 +168,9 @@ paths:
- statistics
/api/v1/statistics/songs/most-played:
get:
consumes:
- application/json
description: Returns the top N most played songs with their soundtrack info
parameters:
- description: 'Number of results (default: 10)'
- description: 'Number of results (default: 10, max: 100)'
in: query
name: limit
type: integer
@@ -150,11 +200,9 @@ paths:
- statistics
/api/v1/statistics/soundtracks/last-played:
get:
consumes:
- application/json
description: Returns the most recently played soundtracks
description: Returns the most recently played soundtracks with their songs
parameters:
- description: 'Number of results (default: 10)'
- description: 'Number of results (default: 10, max: 100)'
in: query
name: limit
type: integer
@@ -184,11 +232,9 @@ paths:
- statistics
/api/v1/statistics/soundtracks/least-played:
get:
consumes:
- application/json
description: Returns the top N least played soundtracks with their songs
parameters:
- description: 'Number of results (default: 10)'
- description: 'Number of results (default: 10, max: 100)'
in: query
name: limit
type: integer
@@ -218,11 +264,9 @@ paths:
- statistics
/api/v1/statistics/soundtracks/most-played:
get:
consumes:
- application/json
description: Returns the top N most played soundtracks with their songs
parameters:
- description: 'Number of results (default: 10)'
- description: 'Number of results (default: 10, max: 100)'
in: query
name: limit
type: integer
@@ -252,10 +296,7 @@ paths:
- statistics
/api/v1/statistics/soundtracks/never-played:
get:
consumes:
- application/json
description: Returns all soundtracks that have never been played (times_played
= 0)
description: Returns all soundtracks that have never been played
produces:
- application/json
responses:
@@ -276,12 +317,9 @@ paths:
- statistics
/api/v1/statistics/soundtracks/oldest-played:
get:
consumes:
- application/json
description: Returns the least recently played soundtracks (that have been played
at least once)
description: Returns the least recently played soundtracks with their songs
parameters:
- description: 'Number of results (default: 10)'
- description: 'Number of results (default: 10, max: 100)'
in: query
name: limit
type: integer
@@ -311,9 +349,7 @@ paths:
- statistics
/api/v1/statistics/summary:
get:
consumes:
- application/json
description: Returns overall statistics about the music library
description: Returns overall play statistics
produces:
- application/json
responses:
@@ -332,8 +368,6 @@ paths:
- statistics
/api/v1/token:
delete:
consumes:
- application/json
description: Deletes the current session token
parameters:
- description: Bearer token
@@ -368,8 +402,8 @@ paths:
post:
consumes:
- application/json
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.
parameters:
- description: Password and client type
in: body
@@ -396,6 +430,12 @@ paths:
additionalProperties:
type: string
type: object
"429":
description: Too Many Requests
schema:
additionalProperties:
type: string
type: object
"500":
description: Internal Server Error
schema:
@@ -407,8 +447,6 @@ paths:
- auth
/api/v1/token/cleanup:
post:
consumes:
- application/json
description: Removes all expired session tokens from the database
parameters:
- description: Bearer token
@@ -422,7 +460,8 @@ paths:
"200":
description: OK
schema:
additionalProperties: true
additionalProperties:
type: string
type: object
"401":
description: Unauthorized
@@ -441,29 +480,34 @@ paths:
- auth
/character:
get:
consumes:
- application/json
description: Returns the image for a specific character
parameters:
- description: Character name
- description: Character file name
in: query
name: name
required: true
type: string
produces:
- image/png
- image/jpeg
responses:
"200":
description: OK
schema:
type: file
"400":
description: invalid name
schema:
type: string
"404":
description: not found
schema:
type: string
summary: Get character image
tags:
- characters
/characters:
get:
consumes:
- application/json
description: Returns a list of all available characters
produces:
- application/json
@@ -479,9 +523,7 @@ paths:
- characters
/download:
get:
consumes:
- application/json
description: Checks for the latest version of the application
description: Returns the latest version of the client application
produces:
- application/json
responses:
@@ -489,26 +531,34 @@ paths:
description: OK
schema:
type: string
"502":
description: upstream service unavailable
schema:
type: string
summary: Check for latest version
tags:
- download
/download/linux:
get:
description: Redirects to download the latest Linux version
produces:
- application/octet-stream
responses:
"302":
description: Found
schema:
type: string
"404":
description: not found
schema:
type: string
"502":
description: upstream service unavailable
schema:
type: string
summary: Download latest Linux version
tags:
- download
/download/list:
get:
consumes:
- application/json
description: Lists all assets available for the latest version
produces:
- application/json
@@ -519,26 +569,34 @@ paths:
items:
type: string
type: array
"502":
description: upstream service unavailable
schema:
type: string
summary: List assets of latest version
tags:
- download
/download/windows:
get:
description: Redirects to download the latest Windows version
produces:
- application/octet-stream
responses:
"302":
description: Found
schema:
type: string
"404":
description: not found
schema:
type: string
"502":
description: upstream service unavailable
schema:
type: string
summary: Download latest Windows version
tags:
- download
/health:
get:
consumes:
- application/json
description: Returns the health status of the server
produces:
- application/json
@@ -546,21 +604,21 @@ paths:
"200":
description: OK
schema:
type: string
additionalProperties:
type: string
type: object
summary: Check server health
tags:
- health
/music:
get:
consumes:
- application/json
description: Returns a specific song by name
description: Returns the song at the given position in the queue
parameters:
- description: Song name
- description: Song number in the queue
in: query
name: song
required: true
type: string
type: integer
produces:
- audio/mpeg
responses:
@@ -568,8 +626,12 @@ paths:
description: OK
schema:
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
"404":
@@ -585,12 +647,10 @@ paths:
- music
/music/addPlayed:
get:
consumes:
- application/json
description: Adds the latest song to the played list
description: Marks the current song as played
responses:
"204":
description: ""
"200":
description: OK
"423":
description: Syncing is in progress
schema:
@@ -600,12 +660,10 @@ paths:
- music
/music/addQue:
get:
consumes:
- application/json
description: Adds the latest song to the queue
responses:
"204":
description: ""
"200":
description: OK
"423":
description: Syncing is in progress
schema:
@@ -615,8 +673,6 @@ paths:
- music
/music/all/order:
get:
consumes:
- application/json
description: Returns a list of all soundtracks in order
produces:
- application/json
@@ -625,8 +681,7 @@ paths:
description: OK
schema:
items:
additionalProperties: true
type: object
type: string
type: array
"423":
description: Syncing is in progress
@@ -637,8 +692,6 @@ paths:
- music
/music/all/random:
get:
consumes:
- application/json
description: Returns a list of all soundtracks in random order
produces:
- application/json
@@ -647,8 +700,7 @@ paths:
description: OK
schema:
items:
additionalProperties: true
type: object
type: string
type: array
"423":
description: Syncing is in progress
@@ -659,8 +711,6 @@ paths:
- music
/music/info:
get:
consumes:
- application/json
description: Returns information about the current song
produces:
- application/json
@@ -668,15 +718,12 @@ paths:
"200":
description: OK
schema:
additionalProperties: true
type: object
$ref: '#/definitions/backend.SongInfo'
summary: Get current song info
tags:
- music
/music/list:
get:
consumes:
- application/json
description: Returns a list of played songs
produces:
- application/json
@@ -685,8 +732,7 @@ paths:
description: OK
schema:
items:
additionalProperties: true
type: object
$ref: '#/definitions/backend.SongInfo'
type: array
summary: Get played songs list
tags:
@@ -714,20 +760,16 @@ paths:
- music
/music/played:
put:
consumes:
- application/json
description: Marks a song as played by its ID
description: Marks the song at the given queue position as played
parameters:
- description: Song ID
- description: Song number in the queue
in: query
name: song
required: true
type: integer
produces:
- application/json
responses:
"204":
description: ""
"200":
description: OK
"400":
description: Bad Request
schema:
@@ -783,7 +825,7 @@ paths:
- music
/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
responses:
@@ -804,7 +846,8 @@ paths:
- music
/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
responses:
@@ -825,12 +868,10 @@ paths:
- music
/music/reset:
get:
consumes:
- application/json
description: Resets the music state
responses:
"204":
description: ""
"200":
description: OK
"423":
description: Syncing is in progress
schema:
@@ -860,10 +901,8 @@ paths:
tags:
- music
/sync:
get:
consumes:
- application/json
description: Starts syncing soundtracks with only new changes
post:
description: Starts syncing soundtracks that have changed
produces:
- application/json
responses:
@@ -879,9 +918,7 @@ paths:
tags:
- sync
/sync/full:
get:
consumes:
- application/json
post:
description: Starts a full sync of all soundtracks
produces:
- application/json
@@ -899,24 +936,20 @@ paths:
- sync
/sync/progress:
get:
consumes:
- application/json
description: Returns the current sync progress or result
description: Returns the progress of the running sync, or the result of the
last sync
produces:
- application/json
responses:
"200":
description: OK
schema:
additionalProperties: true
type: object
$ref: '#/definitions/backend.SyncResponse'
summary: Get sync progress
tags:
- sync
/sync/reset:
get:
consumes:
- application/json
post:
description: Resets the soundtracks database by deleting all soundtracks and
songs
produces:
@@ -935,8 +968,6 @@ paths:
- sync
/version:
get:
consumes:
- application/json
description: get latest version info
produces:
- application/json
@@ -945,17 +976,11 @@ paths:
description: OK
schema:
$ref: '#/definitions/backend.VersionData'
"404":
description: Not Found
schema:
type: string
summary: Getting the latest version of the backend
tags:
- version
/version/history:
get:
consumes:
- application/json
description: get version history
produces:
- application/json
@@ -966,10 +991,6 @@ paths:
items:
$ref: '#/definitions/backend.VersionData'
type: array
"404":
description: Not Found
schema:
type: string
summary: Getting the version history of the backend
tags:
- version