feat: add client compatibility endpoints and a smoke test script

- getMusicDirectory for folder/album browsing
- server-side play queues with savePlayQueue/getPlayQueue and index variants
- jukebox status and internet radio compatibility responses
- scripts/smoke.sh generates a tagged MP3 library, runs the server and
  verifies all endpoints clients use, including Range, download and covers
This commit is contained in:
TapTap committed 2026-11-13 12:40:00 +00:00
1 parent 46266d8071
commit 4d313a2846
9 files changed
+474

No files matched your search

+17
View File
@@ -592,6 +592,10 @@ For every `/rest/*` call (except an optional health check):
- `createPlaylist(playlistId, name, songId)`: owner is the caller. - `createPlaylist(playlistId, name, songId)`: owner is the caller.
- `updatePlaylist(playlistId, name, comment, public, songIdToAdd, songIndexToRemove)`: owner only; indices are applied in order. - `updatePlaylist(playlistId, name, comment, public, songIdToAdd, songIndexToRemove)`: owner only; indices are applied in order.
- `deletePlaylist(playlistId)`: owner only. - `deletePlaylist(playlistId)`: owner only.
- `getMusicDirectory(id)`: folder IDs return their albums as directories; album IDs return their songs. Used by folder-browsing clients.
- `savePlayQueue` / `getPlayQueue` (and the `*ByIndex` variants): per-user queue kept in memory.
- `jukeboxControl(action=status)` returns a stopped status; other jukebox actions report that jukebox is unsupported.
- `getInternetRadioStations` returns an empty list; radio mutation endpoints report that radio is unsupported.
No `createUser` / `updateUser` / `deleteUser` endpoints: config/Vault is the source of truth. No `createUser` / `updateUser` / `deleteUser` endpoints: config/Vault is the source of truth.
@@ -660,8 +664,21 @@ The server fails its readiness probe if a configured root path is missing or unr
- `search3` with Unicode and wildcards - `search3` with Unicode and wildcards
- scrobble/star/rating/bookmark isolation between users - scrobble/star/rating/bookmark isolation between users
- playlist ownership and public visibility - playlist ownership and public visibility
- music directory browsing and server-side play queues
- transcoding: `maxBitRate` produces MP3, `timeOffset` seeks (skipped when `ffmpeg` is unavailable) - transcoding: `maxBitRate` produces MP3, `timeOffset` seeks (skipped when `ffmpeg` is unavailable)
### Compatibility smoke test
`scripts/smoke.sh` generates a tagged MP3 with ffmpeg, starts the real server against a temporary library, and checks every endpoint a Subsonic client uses (browsing, feeds, search, stars, ratings, bookmarks, playlists, queues, stream with Range, download and covers). It prints PASS/FAIL per endpoint and exits non-zero on the first failure summary:
```bash
nix-shell --run scripts/smoke.sh
# or, with ffmpeg/sqlite/curl installed:
scripts/smoke.sh
```
The work directory can be passed as the first argument; the server log is kept there for debugging.
--- ---
## 11. Implementation Order ## 11. Implementation Order
+200
View File
@@ -0,0 +1,200 @@
#!/usr/bin/env bash
#
# End-to-end smoke test: generates a tiny tagged MP3 library, starts the server
# against it, and exercises the endpoints a Subsonic client uses.
#
# Requirements: ffmpeg, sqlite3, curl, md5sum, java (or use nix-shell).
# Usage: scripts/smoke.sh [work-dir]
#
set -euo pipefail
ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
WORK="${1:-$(mktemp -d "${TMPDIR:-/tmp}/musicmanager-smoke.XXXXXX")}"
PORT="${SMOKE_PORT:-18099}"
USER="smoke"
PASS="smoke-pass"
BASE="http://127.0.0.1:${PORT}"
SALT="smoke-salt"
TOKEN="$(printf '%s%s' "$PASS" "$SALT" | md5sum | cut -d' ' -f1)"
AUTH="u=${USER}&t=${TOKEN}&s=${SALT}&v=1.16.1&c=smoke&f=json"
PASSED=0
FAILED=0
log() { printf '%s\n' "$*"; }
pass() { PASSED=$((PASSED + 1)); log "PASS $1"; }
fail() { FAILED=$((FAILED + 1)); log "FAIL $1: $2"; }
mkdir -p "$WORK/music/Smoke Artist/Smoke Album" "$WORK/longform" "$WORK/data"
log "Generated test library in $WORK"
ffmpeg -hide_banner -loglevel error -y \
-f lavfi -i "sine=frequency=440:duration=2" \
-metadata title="Smoke Song" \
-metadata artist="Smoke Artist" \
-metadata album="Smoke Album" \
-metadata album_artist="Smoke Artist" \
-metadata genre="Rock" \
-metadata track="1" \
-metadata date="2026" \
-q:a 9 "$WORK/music/Smoke Artist/Smoke Album/01 - Smoke Song.mp3"
ffmpeg -hide_banner -loglevel error -y \
-f lavfi -i "color=c=red:s=64x64" -frames:v 1 \
"$WORK/music/Smoke Artist/Smoke Album/cover.jpg"
cat > "$WORK/library.yaml" <<EOF
library:
folders:
- id: 1
name: "Music"
type: music
path: $WORK/music
- id: 10
name: "Long-form"
type: longform
path: $WORK/longform
EOF
cat > "$WORK/users.yaml" <<EOF
users:
- name: $USER
password: "$PASS"
admin: true
folders: [1]
EOF
log "Building fat JAR..."
(cd "$ROOT" && ./gradlew -q shadowJar)
JAR="$(find "$ROOT/build/libs" -name 'musicmanager-*-all.jar' | head -1)"
if [[ -z "$JAR" ]]; then
log "Could not find the fat JAR under build/libs"
exit 1
fi
DATA_DIR="$WORK/data" LIBRARY_CONFIG="$WORK/library.yaml" USERS_FILE="$WORK/users.yaml" PORT="$PORT" \
java -jar "$JAR" > "$WORK/server.log" 2>&1 &
SERVER_PID=$!
trap 'kill $SERVER_PID 2>/dev/null || true' EXIT
log "Waiting for the server and initial scan..."
for _ in $(seq 1 120); do
if curl -sf "$BASE/health" >/dev/null 2>&1; then
SONGS="$(sqlite3 "$WORK/data/musicmanager.db" 'select count(*) from songs' 2>/dev/null || echo 0)"
[[ "$SONGS" -gt 0 ]] && break
fi
sleep 1
done
if [[ "${SONGS:-0}" -eq 0 ]]; then
log "Server did not scan the test library; see $WORK/server.log"
tail -20 "$WORK/server.log" || true
exit 1
fi
ALBUM_ID="$(sqlite3 "$WORK/data/musicmanager.db" 'select id from albums limit 1')"
ARTIST_ID="$(sqlite3 "$WORK/data/musicmanager.db" 'select id from artists limit 1')"
SONG_ID="$(sqlite3 "$WORK/data/musicmanager.db" 'select id from songs limit 1')"
log "Scanned: artist=$ARTIST_ID album=$ALBUM_ID song=$SONG_ID"
# check <name> <path-with-query> [expected-status]
check() {
local name="$1" path="$2" expected="${3:-200}" body status
body="$(curl -s -w '\n%{http_code}' "$BASE$path")"
status="$(printf '%s' "$body" | tail -1)"
body="$(printf '%s' "$body" | sed '$d')"
if [[ "$status" != "$expected" ]]; then
fail "$name" "HTTP $status (expected $expected): $(printf '%s' "$body" | head -c 200)"
return
fi
if [[ "$expected" == "200" ]] && ! printf '%s' "$body" | grep -q '"status":"ok"'; then
fail "$name" "$(printf '%s' "$body" | head -c 200)"
return
fi
pass "$name"
}
check "ping" "/rest/ping.view?$AUTH"
check "getLicense" "/rest/getLicense.view?$AUTH"
check "getOpenSubsonicExtensions" "/rest/getOpenSubsonicExtensions.view?$AUTH"
check "getMusicFolders" "/rest/getMusicFolders.view?$AUTH"
check "getIndexes" "/rest/getIndexes.view?$AUTH"
check "getArtists" "/rest/getArtists.view?$AUTH"
check "getArtist" "/rest/getArtist.view?$AUTH&id=$ARTIST_ID"
check "getAlbum" "/rest/getAlbum.view?$AUTH&id=$ALBUM_ID"
check "getSong" "/rest/getSong.view?$AUTH&id=$SONG_ID"
check "search3" "/rest/search3.view?$AUTH&query=smoke"
check "getAlbumList2" "/rest/getAlbumList2.view?$AUTH&type=alphabeticalByName&size=10"
check "getAlbumList" "/rest/getAlbumList.view?$AUTH&type=newest&size=10"
check "getRandomSongs" "/rest/getRandomSongs.view?$AUTH&size=10"
check "getGenres" "/rest/getGenres.view?$AUTH"
check "getSongsByGenre" "/rest/getSongsByGenre.view?$AUTH&genre=Rock"
check "getMusicDirectory (folder)" "/rest/getMusicDirectory.view?$AUTH&id=1"
check "getMusicDirectory (album)" "/rest/getMusicDirectory.view?$AUTH&id=$ALBUM_ID"
check "getUser" "/rest/getUser.view?$AUTH&username=$USER"
check "getUsers" "/rest/getUsers.view?$AUTH"
check "getScanStatus" "/rest/getScanStatus.view?$AUTH"
check "getStarred2" "/rest/getStarred2.view?$AUTH"
check "getLyricsBySongId" "/rest/getLyricsBySongId.view?$AUTH&id=$SONG_ID"
check "getArtistInfo2" "/rest/getArtistInfo2.view?$AUTH&id=$ARTIST_ID"
check "getAlbumInfo2" "/rest/getAlbumInfo2.view?$AUTH&id=$ALBUM_ID"
check "getSimilarSongs2" "/rest/getSimilarSongs2.view?$AUTH&id=$ARTIST_ID"
check "getTopSongs" "/rest/getTopSongs.view?$AUTH&artist=Smoke%20Artist"
check "getInternetRadioStations" "/rest/getInternetRadioStations.view?$AUTH"
check "jukeboxControl" "/rest/jukeboxControl.view?$AUTH&action=status"
check "scrobble" "/rest/scrobble.view?$AUTH&id=$SONG_ID"
check "star" "/rest/star.view?$AUTH&id=$SONG_ID&albumId=$ALBUM_ID&artistId=$ARTIST_ID"
check "getStarred2 after star" "/rest/getStarred2.view?$AUTH"
check "setRating" "/rest/setRating.view?$AUTH&id=$SONG_ID&rating=4"
check "unstar" "/rest/unstar.view?$AUTH&id=$SONG_ID&albumId=$ALBUM_ID&artistId=$ARTIST_ID"
check "createBookmark" "/rest/createBookmark.view?$AUTH&id=$SONG_ID&position=1000"
check "getBookmarks" "/rest/getBookmarks.view?$AUTH"
check "deleteBookmark" "/rest/deleteBookmark.view?$AUTH&id=$SONG_ID"
PLAYLIST_JSON="$(curl -s "$BASE/rest/createPlaylist.view?$AUTH&name=Smoke%20List&songId=$SONG_ID")"
PLAYLIST_ID="$(printf '%s' "$PLAYLIST_JSON" | python3 -c 'import json,sys; print(json.load(sys.stdin)["subsonic-response"]["playlist"]["id"])' 2>/dev/null || true)"
if [[ -z "$PLAYLIST_ID" ]]; then
fail "createPlaylist" "$(printf '%s' "$PLAYLIST_JSON" | head -c 300)"
else
pass "createPlaylist"
check "getPlaylists" "/rest/getPlaylists.view?$AUTH"
check "getPlaylist" "/rest/getPlaylist.view?$AUTH&id=$PLAYLIST_ID"
check "updatePlaylist" "/rest/updatePlaylist.view?$AUTH&playlistId=$PLAYLIST_ID&songIndexToRemove=0"
check "deletePlaylist" "/rest/deletePlaylist.view?$AUTH&id=$PLAYLIST_ID"
fi
check "savePlayQueue" "/rest/savePlayQueue.view?$AUTH&id=$SONG_ID&position=0"
check "getPlayQueue" "/rest/getPlayQueue.view?$AUTH"
check "savePlayQueueByIndex" "/rest/savePlayQueueByIndex.view?$AUTH&id=$SONG_ID&currentIndex=0&position=0"
check "getPlayQueueByIndex" "/rest/getPlayQueueByIndex.view?$AUTH"
STREAM_STATUS="$(curl -s -o "$WORK/stream.mp3" -w '%{http_code}' "$BASE/rest/stream.view?$AUTH&id=$SONG_ID")"
if [[ "$STREAM_STATUS" == "200" && -s "$WORK/stream.mp3" ]]; then
pass "stream"
else
fail "stream" "HTTP $STREAM_STATUS, $(wc -c < "$WORK/stream.mp3" 2>/dev/null || echo 0) bytes"
fi
RANGE_STATUS="$(curl -s -o /dev/null -w '%{http_code}' -H 'Range: bytes=0-9' "$BASE/rest/stream.view?$AUTH&id=$SONG_ID")"
if [[ "$RANGE_STATUS" == "206" ]]; then pass "stream range"; else fail "stream range" "HTTP $RANGE_STATUS"; fi
DOWNLOAD_STATUS="$(curl -s -o /dev/null -w '%{http_code}' "$BASE/rest/download.view?$AUTH&id=$SONG_ID")"
if [[ "$DOWNLOAD_STATUS" == "200" ]]; then pass "download"; else fail "download" "HTTP $DOWNLOAD_STATUS"; fi
COVER_STATUS="$(curl -s -o "$WORK/cover.jpg" -w '%{http_code}' "$BASE/rest/getCoverArt.view?$AUTH&id=$ALBUM_ID&size=32")"
if [[ "$COVER_STATUS" == "200" && -s "$WORK/cover.jpg" ]]; then
pass "getCoverArt"
else
fail "getCoverArt" "HTTP $COVER_STATUS"
fi
log ""
log "Smoke test finished: $PASSED passed, $FAILED failed"
log "Server log: $WORK/server.log"
if [[ "$FAILED" -gt 0 ]]; then
exit 1
fi
@@ -0,0 +1,33 @@
package win.taptap.musicmanager.subsonic
import java.time.Instant
import java.util.concurrent.ConcurrentHashMap
data class PlayQueueState(
val songIds: List<String>,
val currentIndex: Int,
val positionMs: Long,
val changed: String,
val changedBy: String,
)
/**
* Server-side play queue per user. Kept in memory: losing it on restart only means
* clients restore their local queue instead, which is acceptable for the MVP.
*/
object PlayQueueStore {
private val queues = ConcurrentHashMap<String, PlayQueueState>()
fun save(userName: String, songIds: List<String>, currentIndex: Int, positionMs: Long) {
queues[userName] = PlayQueueState(
songIds = songIds,
currentIndex = currentIndex.coerceIn(0, (songIds.size - 1).coerceAtLeast(0)),
positionMs = positionMs.coerceAtLeast(0),
changed = Instant.now().toString(),
changedBy = userName,
)
}
fun get(userName: String): PlayQueueState? = queues[userName]
}
@@ -118,6 +118,81 @@ fun Route.browsingRoutes(users: UsersConfig, library: LibraryConfig) {
call.respondSubsonic(buildJsonObject { put("song", songJson(song)) }) call.respondSubsonic(buildJsonObject { put("song", songJson(song)) })
} }
subsonicGet(users, "/getMusicDirectory") { call, user ->
val parameters = call.subsonicParams()
val id = parameters["id"]
if (id.isNullOrBlank()) {
call.respondSubsonicError(10, "Required parameter is missing: id")
return@subsonicGet
}
val folders = user.effectiveFolderIds(library, parameters["musicFolderId"])
if (id.startsWith("al-")) {
val album = LibraryRepository.album(id, folders, user.name)
if (album == null) {
call.respondSubsonicError(70, "Album not found")
return@subsonicGet
}
val songs = LibraryRepository.albumSongs(id, folders, user.name)
call.respondSubsonic(
buildJsonObject {
put("directory", buildJsonObject {
put("id", album.id)
put("title", album.name)
album.artistName?.let { put("artist", it) }
album.coverArt?.let { put("coverArt", it) }
put("child", buildJsonArray { songs.forEach { add(songJson(it)) } })
})
},
)
return@subsonicGet
}
val folderId = id.toIntOrNull()
if (folderId == null || folderId !in folders) {
call.respondSubsonicError(70, "Directory not found")
return@subsonicGet
}
val folder = library.byId(folderId) ?: run {
call.respondSubsonicError(70, "Directory not found")
return@subsonicGet
}
val albums = LibraryRepository.albumList(
type = "alphabeticalByName",
size = 10_000,
offset = 0,
fromYear = null,
toYear = null,
genre = null,
folderIds = setOf(folderId),
userName = user.name,
)
call.respondSubsonic(
buildJsonObject {
put("directory", buildJsonObject {
put("id", folderId)
put("title", folder.name)
put("child", buildJsonArray {
albums.forEach { album ->
add(buildJsonObject {
put("id", album.id)
put("parent", folderId)
put("title", album.name)
put("isDir", true)
put("album", album.name)
album.artistName?.let { put("artist", it) }
album.coverArt?.let { put("coverArt", it) }
})
}
})
})
},
)
}
val albumListTypes = setOf( val albumListTypes = setOf(
"newest", "newest",
"recent", "recent",
@@ -0,0 +1,67 @@
package win.taptap.musicmanager.subsonic.routes
import io.ktor.server.routing.Route
import kotlinx.serialization.json.add
import kotlinx.serialization.json.buildJsonArray
import kotlinx.serialization.json.buildJsonObject
import kotlinx.serialization.json.put
import win.taptap.musicmanager.config.LibraryConfig
import win.taptap.musicmanager.config.UsersConfig
import win.taptap.musicmanager.db.LibraryRepository
import win.taptap.musicmanager.subsonic.PlayQueueStore
import win.taptap.musicmanager.subsonic.models.songJson
import win.taptap.musicmanager.subsonic.respondSubsonic
/** Optional server-side queue used by clients that support queue hand-off. */
fun Route.playQueueRoutes(users: UsersConfig, library: LibraryConfig) {
for (endpoint in listOf("/savePlayQueue", "/savePlayQueueByIndex")) {
subsonicGet(users, endpoint) { call, user ->
val parameters = call.subsonicParams()
val folders = user.visibleFolderIds(library)
val requestedIds = parameters.getAll("id").orEmpty().filter { it.isNotBlank() }
val visible = requestedIds.filter { LibraryRepository.song(it, folders, user.name) != null }
val currentId = parameters["current"]
val explicitIndex = parameters["currentIndex"]?.toIntOrNull()
val currentIndex = explicitIndex
?: currentId?.let { visible.indexOf(it) }?.takeIf { it >= 0 }
?: 0
val position = parameters["position"]?.toLongOrNull() ?: 0L
PlayQueueStore.save(user.name, visible, currentIndex, position)
call.respondSubsonic()
}
}
for (endpoint in listOf("/getPlayQueue", "/getPlayQueueByIndex")) {
subsonicGet(users, endpoint) { call, user ->
val state = PlayQueueStore.get(user.name)
val folders = user.visibleFolderIds(library)
val songs = LibraryRepository.songsByIds(state?.songIds.orEmpty(), folders, user.name)
val byIndex = endpoint == "/getPlayQueueByIndex"
val queue = buildJsonObject {
put("entry", buildJsonArray { songs.forEach { add(songJson(it)) } })
put("position", state?.positionMs ?: 0L)
put("username", user.name)
put("changed", state?.changed.orEmpty())
put("changedBy", state?.changedBy.orEmpty())
if (byIndex) {
put("currentIndex", state?.currentIndex ?: 0)
} else {
state?.songIds?.getOrNull(state.currentIndex)?.let { put("current", it) }
}
}
call.respondSubsonic(
buildJsonObject {
put(if (byIndex) "playQueueByIndex" else "playQueue", queue)
},
)
}
}
}
@@ -21,5 +21,6 @@ fun Route.subsonicRoutes(
mediaRoutes(users, library, coverArtService) mediaRoutes(users, library, coverArtService)
interactionRoutes(users, library) interactionRoutes(users, library)
playlistRoutes(users, library) playlistRoutes(users, library)
playQueueRoutes(users, library)
} }
} }
@@ -90,6 +90,44 @@ fun Route.systemRoutes(
call.respondSubsonic(buildJsonObject { put("user", userJson(requested, library)) }) call.respondSubsonic(buildJsonObject { put("user", userJson(requested, library)) })
} }
subsonicGet(users, "/getInternetRadioStations") { call, _ ->
call.respondSubsonic(
buildJsonObject {
put("internetRadioStations", buildJsonObject {
put("internetRadioStation", buildJsonArray { })
})
},
)
}
for (endpoint in listOf(
"/createInternetRadioStation",
"/updateInternetRadioStation",
"/deleteInternetRadioStation",
)) {
subsonicGet(users, endpoint) { call, _ ->
call.respondSubsonicError(0, "Internet radio is not supported")
}
}
subsonicGet(users, "/jukeboxControl") { call, _ ->
if (call.subsonicParams()["action"] != "status") {
call.respondSubsonicError(0, "Jukebox is not supported")
return@subsonicGet
}
call.respondSubsonic(
buildJsonObject {
put("jukeboxStatus", buildJsonObject {
put("currentIndex", 0)
put("playing", false)
put("gain", 1.0)
put("position", 0)
})
},
)
}
subsonicGet(users, "/getUsers") { call, currentUser -> subsonicGet(users, "/getUsers") { call, currentUser ->
if (!currentUser.admin) { if (!currentUser.admin) {
call.respondSubsonicError(50, "Not authorized") call.respondSubsonicError(50, "Not authorized")
@@ -335,6 +335,35 @@ class BrowsingRoutesTest {
} }
} }
@Test
fun `music directory and play queue expose folders albums and songs`() {
seededContext().use { seed ->
testApplication {
setupApp(seed)
val auth = credentials("alice", "alice-pw")
val folder = parseBody(
client.get("/rest/getMusicDirectory?$auth&id=1").bodyAsText(),
)["directory"]!!.jsonObject
val folderChildren = folder["child"]!!.jsonArray
assertEquals(1, folderChildren.size)
assertEquals(seed.aliceAlbumId, folderChildren[0].jsonObject["id"]!!.jsonPrimitive.content)
assertEquals("true", folderChildren[0].jsonObject["isDir"]!!.jsonPrimitive.content)
val album = parseBody(
client.get("/rest/getMusicDirectory?$auth&id=${seed.aliceAlbumId}").bodyAsText(),
)["directory"]!!.jsonObject
assertEquals(seed.aliceSongId, album["child"]!!.jsonArray[0].jsonObject["id"]!!.jsonPrimitive.content)
client.get("/rest/savePlayQueue?$auth&id=${seed.aliceSongId}&position=1000")
val queue = parseBody(client.get("/rest/getPlayQueue?$auth").bodyAsText())["playQueue"]!!
.jsonObject
assertEquals(seed.aliceSongId, queue["entry"]!!.jsonArray[0].jsonObject["id"]!!.jsonPrimitive.content)
assertEquals(1000, queue["position"]!!.jsonPrimitive.int)
}
}
}
@Test @Test
fun `lyrics endpoint returns an empty structure when the song has no lyrics`() { fun `lyrics endpoint returns an empty structure when the song has no lyrics`() {
seededContext().use { seed -> seededContext().use { seed ->
@@ -136,6 +136,20 @@ class SystemRoutesTest {
assertEquals(10, missing["error"]!!.jsonObject["code"]!!.jsonPrimitive.int) assertEquals(10, missing["error"]!!.jsonObject["code"]!!.jsonPrimitive.int)
} }
@Test
fun `jukebox and internet radio endpoints return valid empty responses`() = testApplication {
setupApp()
val jukebox = parse(client.get("/rest/jukeboxControl?${credentials()}&action=status").bodyAsText())
assertEquals("false", jukebox["jukeboxStatus"]!!.jsonObject["playing"]!!.jsonPrimitive.content)
val radio = parse(client.get("/rest/getInternetRadioStations?${credentials()}").bodyAsText())
assertEquals(
0,
radio["internetRadioStations"]!!.jsonObject["internetRadioStation"]!!.jsonArray.size,
)
}
@Test @Test
fun `getUsers is admin only`() = testApplication { fun `getUsers is admin only`() = testApplication {
setupApp() setupApp()