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/docs.go
+204 -220
View File
@@ -1,23 +1,23 @@
// Package docs GENERATED BY THE COMMAND ABOVE; DO NOT EDIT
// This file was generated by swaggo/swag
// Package docs Code generated by swaggo/swag. DO NOT EDIT
package docs
import (
"bytes"
"encoding/json"
"strings"
"text/template"
import "github.com/swaggo/swag"
"github.com/swaggo/swag"
)
var doc = `{
const docTemplate = `{
"schemes": {{ marshal .Schemes }},
"swagger": "2.0",
"info": {
"description": "{{escape .Description}}",
"title": "{{.Title}}",
"contact": {},
"termsOfService": "http://sanplex.xyz/terms/",
"contact": {
"name": "Sebastian Olsson",
"email": "zarnor91@gmail.com"
},
"license": {
"name": "MIT",
"url": "http://opensource.org/licenses/MIT"
},
"version": "{{.Version}}"
},
"host": "{{.Host}}",
@@ -26,9 +26,6 @@ var doc = `{
"/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"
],
@@ -39,7 +36,7 @@ var doc = `{
"parameters": [
{
"type": "integer",
"description": "Number of results (default: 10)",
"description": "Number of results (default: 10, max: 100)",
"name": "limit",
"in": "query"
}
@@ -78,9 +75,6 @@ var doc = `{
"/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"
],
@@ -91,7 +85,7 @@ var doc = `{
"parameters": [
{
"type": "integer",
"description": "Number of results (default: 10)",
"description": "Number of results (default: 10, max: 100)",
"name": "limit",
"in": "query"
}
@@ -129,10 +123,7 @@ var doc = `{
},
"/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"
],
@@ -143,7 +134,7 @@ var doc = `{
"parameters": [
{
"type": "integer",
"description": "Number of results (default: 10)",
"description": "Number of results (default: 10, max: 100)",
"name": "limit",
"in": "query"
}
@@ -182,9 +173,6 @@ var doc = `{
"/api/v1/statistics/soundtracks/least-played": {
"get": {
"description": "Returns the top N least played soundtracks with their songs",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
@@ -195,7 +183,7 @@ var doc = `{
"parameters": [
{
"type": "integer",
"description": "Number of results (default: 10)",
"description": "Number of results (default: 10, max: 100)",
"name": "limit",
"in": "query"
}
@@ -234,9 +222,6 @@ var doc = `{
"/api/v1/statistics/soundtracks/most-played": {
"get": {
"description": "Returns the top N most played soundtracks with their songs",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
@@ -247,7 +232,7 @@ var doc = `{
"parameters": [
{
"type": "integer",
"description": "Number of results (default: 10)",
"description": "Number of results (default: 10, max: 100)",
"name": "limit",
"in": "query"
}
@@ -285,10 +270,7 @@ var doc = `{
},
"/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"
],
@@ -320,10 +302,7 @@ var doc = `{
},
"/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"
],
@@ -334,7 +313,7 @@ var doc = `{
"parameters": [
{
"type": "integer",
"description": "Number of results (default: 10)",
"description": "Number of results (default: 10, max: 100)",
"name": "limit",
"in": "query"
}
@@ -372,10 +351,7 @@ var doc = `{
},
"/api/v1/statistics/summary": {
"get": {
"description": "Returns overall statistics about the music library",
"consumes": [
"application/json"
],
"description": "Returns overall play statistics",
"produces": [
"application/json"
],
@@ -404,7 +380,7 @@ var doc = `{
},
"/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"
],
@@ -451,6 +427,15 @@ var doc = `{
}
}
},
"429": {
"description": "Too Many Requests",
"schema": {
"type": "object",
"additionalProperties": {
"type": "string"
}
}
},
"500": {
"description": "Internal Server Error",
"schema": {
@@ -464,9 +449,6 @@ var doc = `{
},
"delete": {
"description": "Deletes the current session token",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
@@ -517,9 +499,6 @@ var doc = `{
"/api/v1/token/cleanup": {
"post": {
"description": "Removes all expired session tokens from the database",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
@@ -541,7 +520,9 @@ var doc = `{
"description": "OK",
"schema": {
"type": "object",
"additionalProperties": true
"additionalProperties": {
"type": "string"
}
}
},
"401": {
@@ -568,11 +549,9 @@ var doc = `{
"/character": {
"get": {
"description": "Returns the image for a specific character",
"consumes": [
"application/json"
],
"produces": [
"image/png"
"image/png",
"image/jpeg"
],
"tags": [
"characters"
@@ -581,7 +560,7 @@ var doc = `{
"parameters": [
{
"type": "string",
"description": "Character name",
"description": "Character file name",
"name": "name",
"in": "query",
"required": true
@@ -593,6 +572,18 @@ var doc = `{
"schema": {
"type": "file"
}
},
"400": {
"description": "invalid name",
"schema": {
"type": "string"
}
},
"404": {
"description": "not found",
"schema": {
"type": "string"
}
}
}
}
@@ -600,9 +591,6 @@ var doc = `{
"/characters": {
"get": {
"description": "Returns a list of all available characters",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
@@ -625,10 +613,7 @@ var doc = `{
},
"/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"
],
@@ -642,6 +627,12 @@ var doc = `{
"schema": {
"type": "string"
}
},
"502": {
"description": "upstream service unavailable",
"schema": {
"type": "string"
}
}
}
}
@@ -649,9 +640,6 @@ var doc = `{
"/download/linux": {
"get": {
"description": "Redirects to download the latest Linux version",
"produces": [
"application/octet-stream"
],
"tags": [
"download"
],
@@ -662,6 +650,18 @@ var doc = `{
"schema": {
"type": "string"
}
},
"404": {
"description": "not found",
"schema": {
"type": "string"
}
},
"502": {
"description": "upstream service unavailable",
"schema": {
"type": "string"
}
}
}
}
@@ -669,9 +669,6 @@ var doc = `{
"/download/list": {
"get": {
"description": "Lists all assets available for the latest version",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
@@ -688,6 +685,12 @@ var doc = `{
"type": "string"
}
}
},
"502": {
"description": "upstream service unavailable",
"schema": {
"type": "string"
}
}
}
}
@@ -695,9 +698,6 @@ var doc = `{
"/download/windows": {
"get": {
"description": "Redirects to download the latest Windows version",
"produces": [
"application/octet-stream"
],
"tags": [
"download"
],
@@ -708,6 +708,18 @@ var doc = `{
"schema": {
"type": "string"
}
},
"404": {
"description": "not found",
"schema": {
"type": "string"
}
},
"502": {
"description": "upstream service unavailable",
"schema": {
"type": "string"
}
}
}
}
@@ -715,9 +727,6 @@ var doc = `{
"/health": {
"get": {
"description": "Returns the health status of the server",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
@@ -729,7 +738,10 @@ var doc = `{
"200": {
"description": "OK",
"schema": {
"type": "string"
"type": "object",
"additionalProperties": {
"type": "string"
}
}
}
}
@@ -737,10 +749,7 @@ var doc = `{
},
"/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"
],
@@ -750,8 +759,8 @@ var doc = `{
"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
@@ -764,8 +773,14 @@ var doc = `{
"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"
}
@@ -787,17 +802,14 @@ var doc = `{
},
"/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",
@@ -811,16 +823,13 @@ var doc = `{
"/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",
@@ -834,9 +843,6 @@ var doc = `{
"/music/all/order": {
"get": {
"description": "Returns a list of all soundtracks in order",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
@@ -850,8 +856,7 @@ var doc = `{
"schema": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true
"type": "string"
}
}
},
@@ -867,9 +872,6 @@ var doc = `{
"/music/all/random": {
"get": {
"description": "Returns a list of all soundtracks in random order",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
@@ -883,8 +885,7 @@ var doc = `{
"schema": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true
"type": "string"
}
}
},
@@ -900,9 +901,6 @@ var doc = `{
"/music/info": {
"get": {
"description": "Returns information about the current song",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
@@ -914,8 +912,7 @@ var doc = `{
"200": {
"description": "OK",
"schema": {
"type": "object",
"additionalProperties": true
"$ref": "#/definitions/backend.SongInfo"
}
}
}
@@ -924,9 +921,6 @@ var doc = `{
"/music/list": {
"get": {
"description": "Returns a list of played songs",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
@@ -940,8 +934,7 @@ var doc = `{
"schema": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true
"$ref": "#/definitions/backend.SongInfo"
}
}
}
@@ -982,13 +975,7 @@ var doc = `{
},
"/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"
],
@@ -996,15 +983,15 @@ var doc = `{
"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",
@@ -1087,7 +1074,7 @@ var doc = `{
},
"/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"
],
@@ -1119,7 +1106,7 @@ var doc = `{
},
"/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"
],
@@ -1152,16 +1139,13 @@ var doc = `{
"/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",
@@ -1205,11 +1189,8 @@ var doc = `{
}
},
"/sync": {
"get": {
"description": "Starts syncing soundtracks with only new changes",
"consumes": [
"application/json"
],
"post": {
"description": "Starts syncing soundtracks that have changed",
"produces": [
"application/json"
],
@@ -1234,11 +1215,8 @@ var doc = `{
}
},
"/sync/full": {
"get": {
"post": {
"description": "Starts a full sync of all soundtracks",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
@@ -1264,10 +1242,7 @@ var doc = `{
},
"/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"
],
@@ -1279,19 +1254,15 @@ var doc = `{
"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"
],
@@ -1318,9 +1289,6 @@ var doc = `{
"/version": {
"get": {
"description": "get latest version info",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
@@ -1334,12 +1302,6 @@ var doc = `{
"schema": {
"$ref": "#/definitions/backend.VersionData"
}
},
"404": {
"description": "Not Found",
"schema": {
"type": "string"
}
}
}
}
@@ -1347,9 +1309,6 @@ var doc = `{
"/version/history": {
"get": {
"description": "get version history",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
@@ -1366,18 +1325,35 @@ var doc = `{
"$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": {
@@ -1450,6 +1426,50 @@ var doc = `{
}
}
},
"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": {
@@ -1477,7 +1497,7 @@ var doc = `{
"type": "string"
},
"password": {
"description": "Required: API password",
"description": "API password, required when API_PASSWORD is set",
"type": "string"
}
}
@@ -1499,56 +1519,20 @@ var doc = `{
}
}`
type swaggerInfo struct {
Version string
Host string
BasePath string
Schemes []string
Title string
Description string
}
// SwaggerInfo holds exported Swagger Info so clients can modify it
var SwaggerInfo = swaggerInfo{
Version: "",
Host: "",
BasePath: "",
Schemes: []string{},
Title: "",
Description: "",
}
type s struct{}
func (s *s) ReadDoc() string {
sInfo := SwaggerInfo
sInfo.Description = strings.Replace(sInfo.Description, "\n", "\\n", -1)
t, err := template.New("swagger_info").Funcs(template.FuncMap{
"marshal": func(v interface{}) string {
a, _ := json.Marshal(v)
return string(a)
},
"escape": func(v interface{}) string {
// escape tabs
str := strings.Replace(v.(string), "\t", "\\t", -1)
// replace " with \", and if that results in \\", replace that with \\\"
str = strings.Replace(str, "\"", "\\\"", -1)
return strings.Replace(str, "\\\\\"", "\\\\\\\"", -1)
},
}).Parse(doc)
if err != nil {
return doc
}
var tpl bytes.Buffer
if err := t.Execute(&tpl, sInfo); err != nil {
return doc
}
return tpl.String()
var SwaggerInfo = &swag.Spec{
Version: "1.0",
Host: "",
BasePath: "/",
Schemes: []string{},
Title: "MusicServer API",
Description: "API for the MusicServer application",
InfoInstanceName: "swagger",
SwaggerTemplate: docTemplate,
LeftDelim: "{{",
RightDelim: "}}",
}
func init() {
swag.Register("swagger", &s{})
swag.Register(SwaggerInfo.InstanceName(), SwaggerInfo)
}
cmd/docs/swagger.json
+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"
}
}
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