From e7704c42eac9930f8eeb188574aec3b6966ba2aa Mon Sep 17 00:00:00 2001 From: TapTap Date: Sun, 15 Nov 2026 14:40:28 +0000 Subject: [PATCH] fix(download): explain filesystem failures and prepare the import dir 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 "/AudioManager Imports" and gives it to UID 10001, so downloads work on a hostPath owned by root. Chart version 0.2.4. --- README.md | 2 +- charts/audiomanager/Chart.yaml | 2 +- charts/audiomanager/templates/deployment.yaml | 18 ++++++ charts/audiomanager/values.yaml | 3 + .../musicmanager/download/DownloadService.kt | 60 +++++++++++++++++-- .../download/DownloadServiceTest.kt | 37 ++++++++++++ 6 files changed, 114 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index 6afd896..e7771bf 100644 --- a/README.md +++ b/README.md @@ -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 `/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. diff --git a/charts/audiomanager/Chart.yaml b/charts/audiomanager/Chart.yaml index 23b2b8d..6040b5d 100644 --- a/charts/audiomanager/Chart.yaml +++ b/charts/audiomanager/Chart.yaml @@ -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" diff --git a/charts/audiomanager/templates/deployment.yaml b/charts/audiomanager/templates/deployment.yaml index 4f9e8c7..85ca8b5 100644 --- a/charts/audiomanager/templates/deployment.yaml +++ b/charts/audiomanager/templates/deployment.yaml @@ -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" . }}" diff --git a/charts/audiomanager/values.yaml b/charts/audiomanager/values.yaml index f88b7a2..e92ce49 100644 --- a/charts/audiomanager/values.yaml +++ b/charts/audiomanager/values.yaml @@ -46,6 +46,9 @@ data: # hostPath must be writable by the pod. downloads: enabled: true + # Runs a root init container that creates "/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 diff --git a/src/main/kotlin/win/taptap/musicmanager/download/DownloadService.kt b/src/main/kotlin/win/taptap/musicmanager/download/DownloadService.kt index 12c5bff..d99b537 100644 --- a/src/main/kotlin/win/taptap/musicmanager/download/DownloadService.kt +++ b/src/main/kotlin/win/taptap/musicmanager/download/DownloadService.kt @@ -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) - Files.move(downloaded, target, StandardCopyOption.REPLACE_EXISTING) + 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+"), " ") diff --git a/src/test/kotlin/win/taptap/musicmanager/download/DownloadServiceTest.kt b/src/test/kotlin/win/taptap/musicmanager/download/DownloadServiceTest.kt index 7e96bd0..65e6f5d 100644 --- a/src/test/kotlin/win/taptap/musicmanager/download/DownloadServiceTest.kt +++ b/src/test/kotlin/win/taptap/musicmanager/download/DownloadServiceTest.kt @@ -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(