fix(download): explain filesystem failures and prepare the import dir
CI / chart (push) Successful in 3s
CI / chart-push (push) Successful in 4s
CI / test (push) Successful in 1m47s
CI / image (push) Successful in 3m45s

A failing Files.createDirectories only produced the directory path in the log,
which hid whether the music hostPath was read-only or owned by another user.
Errors now include the exception type, cause and a hint about UID 10001, and
permission or read-only failures fail immediately instead of retrying three
times.

The chart gets a prepare-imports init container (downloads.prepare) that
creates "<music>/AudioManager Imports" and gives it to UID 10001, so downloads
work on a hostPath owned by root. Chart version 0.2.4.
This commit is contained in:
TapTap committed 2026-11-15 14:40:28 +00:00
1 parent a5af1ee83f
commit e7704c42ea
6 files changed
+113 -7

No files matched your search

+1 -1
View File
@@ -311,7 +311,7 @@ deploy into the wrong place. Set `allowDefaultNamespace=true` to opt in to
The chart expects:
- a `users.yaml` Secret (Vault-managed) referenced by `users.existingSecret`;
- a writable music hostPath when automatic downloads are enabled;
- a writable music hostPath when automatic downloads are enabled. The chart runs a `prepare-imports` init container (`downloads.prepare`) that creates `<music>/AudioManager Imports` and gives it to UID 10001. If the host denies the write, jobs fail immediately with the underlying error instead of retrying;
- a `library.yaml` ConfigMap;
- read-only hostPaths for music and long-form;
- a registry pull secret for the private image.
+1 -1
View File
@@ -2,5 +2,5 @@ apiVersion: v2
name: audiomanager
description: Mood-first self-hosted music server
type: application
version: 0.2.3
version: 0.2.4
appVersion: "0.1.0"
@@ -25,6 +25,24 @@ spec:
{{- end }}
securityContext:
{{- toYaml .Values.podSecurityContext | nindent 8 }}
{{- if and .Values.downloads.enabled .Values.downloads.prepare }}
initContainers:
- name: prepare-imports
image: "{{ include "audiomanager.image" . }}"
imagePullPolicy: {{ .Values.image.pullPolicy }}
command:
- sh
- -c
- |
dir='{{ .Values.media.music.mountPath }}/AudioManager Imports'
mkdir -p "$dir" && chown -R 10001:10001 "$dir" \
|| echo "AudioManager: cannot prepare $dir; check the music hostPath permissions"
securityContext:
runAsUser: 0
volumeMounts:
- name: music
mountPath: {{ .Values.media.music.mountPath }}
{{- end }}
containers:
- name: audiomanager
image: "{{ include "audiomanager.image" . }}"
+3
View File
@@ -46,6 +46,9 @@ data:
# hostPath must be writable by the pod.
downloads:
enabled: true
# Runs a root init container that creates "<music>/AudioManager Imports" and
# gives it to UID 10001. Disable only if the hostPath is already writable.
prepare: true
# Empty uses the first music folder visible to the user.
folderId: null
@@ -1,7 +1,10 @@
package win.taptap.musicmanager.download
import java.io.IOException
import java.nio.file.AccessDeniedException
import java.nio.file.Files
import java.nio.file.Path
import java.nio.file.ReadOnlyFileSystemException
import java.nio.file.StandardCopyOption
import org.slf4j.LoggerFactory
import win.taptap.musicmanager.config.FolderType
@@ -42,9 +45,10 @@ class DownloadService(
try {
process(job)
} catch (t: Throwable) {
val message = t.message ?: t::class.simpleName ?: "Download failed"
log.warn("Download {} failed (attempt {}): {}", job.videoId, job.attempts, message)
if (job.attempts >= maxAttempts) {
val message = describe(t)
val attempts = if (isPermanent(t)) maxAttempts else job.attempts
log.warn("Download {} failed (attempt {}): {}", job.videoId, attempts, message)
if (attempts >= maxAttempts) {
DownloadRepository.markFailed(job.id, message)
} else {
DownloadRepository.retryLater(job.id, message)
@@ -64,8 +68,7 @@ class DownloadService(
?: folders.values.firstOrNull()
?: throw IllegalStateException("No writable music folder for ${job.userName}")
val importDir = folder.path.resolve(IMPORT_DIR)
Files.createDirectories(importDir)
val importDir = prepareImportDir(folder.path)
val working = tempDir.resolve(job.id)
Files.createDirectories(working)
@@ -73,7 +76,14 @@ class DownloadService(
val downloaded = downloader.download(job.videoId, job.title, job.artist, working)
val extension = downloaded.fileName.toString().substringAfterLast('.', "mp3")
val target = uniqueTarget(importDir, job.artist, job.title, extension)
try {
Files.move(downloaded, target, StandardCopyOption.REPLACE_EXISTING)
} catch (e: IOException) {
throw IllegalStateException(
"Downloaded file could not be moved to $target: ${describe(e)}",
e,
)
}
log.info("Downloaded {} to {}", job.videoId, target)
awaitScan()
@@ -88,6 +98,22 @@ class DownloadService(
}
}
private fun prepareImportDir(musicFolder: Path): Path {
val dir = musicFolder.resolve(IMPORT_DIR)
try {
Files.createDirectories(dir)
} catch (e: IOException) {
throw IllegalStateException(
"Cannot write to the music folder: $dir. The server runs as UID 10001; " +
"make sure the hostPath is mounted read-write and that UID 10001 can write " +
"to it (the chart's prepare-imports init container does this). " +
"Underlying error: ${describe(e)}",
e,
)
}
return dir
}
private fun awaitScan() {
// If another scan is already running, wait for that one instead.
startScan()
@@ -122,6 +148,28 @@ class DownloadService(
return candidate
}
/** Includes the exception type and cause, which plain NIO messages omit. */
private fun describe(t: Throwable): String =
generateSequence(t) { it.cause }
.map { cause ->
val text = cause.message?.takeIf { it.isNotBlank() }
if (text == null) cause::class.simpleName ?: "error"
else "${cause::class.simpleName}: $text"
}
.distinct()
.take(3)
.joinToString(" -> ")
.take(1000)
/** Retrying a permission or read-only error never helps. */
private fun isPermanent(t: Throwable): Boolean =
generateSequence(t) { it.cause }.any { cause ->
cause is AccessDeniedException ||
cause is ReadOnlyFileSystemException ||
cause.message?.contains("Read-only", ignoreCase = true) == true ||
cause.message?.contains("Permission denied", ignoreCase = true) == true
}
private fun sanitize(value: String): String =
value.replace(Regex("[\\\\/:*?\"<>|\\p{Cntrl}]"), "_")
.replace(Regex("\\s+"), " ")
@@ -1,5 +1,6 @@
package win.taptap.musicmanager.download
import java.nio.file.AccessDeniedException
import java.nio.file.Files
import java.nio.file.Path
import java.time.Instant
@@ -142,6 +143,42 @@ class DownloadServiceTest {
}
}
@Test
fun `permission errors fail without burning retries`() {
withDatabase { _, library, users ->
val mood = MoodRepository.create(
owner = "alice",
name = "Denied",
description = null,
query = null,
genres = emptyList(),
targetSize = 30,
refreshHours = 24,
ytEnabled = true,
seedSongIds = emptyList(),
)
DownloadRepository.enqueue("alice", mood.id, "v-3", "Blocked", "Nobody")
val service = DownloadService(
users = users,
library = library,
downloader = AudioDownloader { _, _, _, _ ->
throw AccessDeniedException("/mnt/media/music/AudioManager Imports")
},
tempDir = tempDir.resolve("downloads"),
startScan = { true },
isScanning = { false },
)
assertTrue(service.processOne())
val job = assertNotNull(DownloadRepository.forRecommendation("alice", mood.id, "v-3"))
assertEquals("failed", job.state)
assertEquals(1, job.attempts)
assertTrue(job.error?.contains("AccessDeniedException") == true)
}
}
private fun withDatabase(block: (DatabaseHandle, LibraryConfig, UsersConfig) -> Unit) {
val musicDir = Files.createDirectories(tempDir.resolve("music"))
val library = LibraryConfig(