feat: add experimental Android native download worker

Introduce a service-owned download worker that offloads the full download-and-finalize pipeline to DownloadService on Android, keeping downloads alive independently of the Flutter UI process. Key changes: - Extract SAF download logic from MainActivity into SafDownloadHandler - Add NativeDownloadFinalizer for Kotlin-side decryption, format conversion, metadata embedding, ReplayGain, post-processing, and history persistence - Extend DownloadService with native queue management (start, pause, resume, cancel) using coroutine-based worker with AtomicFile snapshots - Add Dart-side orchestration: snapshot polling, run-id correlation, adoption on app restart, and fallback to Dart queue - Forward embedReplayGain, tidalHighFormat, and postProcessingEnabled through Go backend DownloadRequest struct - Add nativeDownloadWorkerEnabled setting with UI toggle - Make DownloadQueueLookup collections unmodifiable
2026-08-13 22:50:20 +02:00 · 2026-05-05 02:41:00 +07:00
parent b306056995
commit 6b342aeac6
18 changed files with 4716 additions and 368 deletions
@@ -124,4 +124,5 @@ dependencies {
    implementation("androidx.lifecycle:lifecycle-runtime-ktx:2.10.0")
    implementation("androidx.documentfile:documentfile:1.1.0")
    implementation("androidx.activity:activity-ktx:1.13.0")
+    implementation("com.antonkarpenko:ffmpeg-kit-full:2.1.0")
 }
@@ -311,21 +311,6 @@ class MainActivity: FlutterFragmentActivity() {
        }
    }

-    private fun forceFilenameExt(name: String, outputExt: String): String {
-        val normalizedExt = normalizeExt(outputExt)
-        if (normalizedExt.isBlank()) return sanitizeFilename(name)
-
-        val safeName = sanitizeFilename(name)
-        val lower = safeName.lowercase(Locale.ROOT)
-        val knownExts = listOf(".flac", ".m4a", ".mp4", ".mp3", ".opus", ".lrc")
-        for (knownExt in knownExts) {
-            if (lower.endsWith(knownExt)) {
-                return safeName.dropLast(knownExt.length) + normalizedExt
-            }
-        }
-        return safeName + normalizedExt
-    }
-
    private fun sanitizeFilename(name: String): String {
        var sanitized = name
            .replace("/", " ")
@@ -700,16 +685,6 @@ class MainActivity: FlutterFragmentActivity() {
        return obj.toString()
    }

-    private fun buildSafFileName(req: JSONObject, outputExt: String): String {
-        val provided = req.optString("saf_file_name", "")
-        if (provided.isNotBlank()) return forceFilenameExt(provided, outputExt)
-
-        val trackName = req.optString("track_name", "track")
-        val artistName = req.optString("artist_name", "")
-        val baseName = if (artistName.isNotBlank()) "$artistName - $trackName" else trackName
-        return forceFilenameExt(baseName, outputExt)
-    }
-
    private fun errorJson(message: String): String {
        val obj = JSONObject()
        obj.put("success", false)
@@ -991,112 +966,6 @@ class MainActivity: FlutterFragmentActivity() {
        return true
    }

-    private fun handleSafDownload(requestJson: String, downloader: (String) -> String): String {
-        val req = JSONObject(requestJson)
-        val storageMode = req.optString("storage_mode", "")
-        val treeUriStr = req.optString("saf_tree_uri", "")
-        if (storageMode != "saf" || treeUriStr.isBlank()) {
-            return downloader(requestJson)
-        }
-
-        val treeUri = Uri.parse(treeUriStr)
-        val relativeDir = sanitizeRelativeDir(req.optString("saf_relative_dir", ""))
-        val outputExt = normalizeExt(req.optString("saf_output_ext", ""))
-        val mimeType = mimeTypeForExt(outputExt)
-        val fileName = buildSafFileName(req, outputExt)
-
-        val existingDir = findDocumentDir(treeUri, relativeDir)
-        if (existingDir != null) {
-            val existing = existingDir.findFile(fileName)
-            if (existing != null && existing.isFile && existing.length() > 0) {
-                val obj = JSONObject()
-                obj.put("success", true)
-                obj.put("message", "File already exists")
-                obj.put("file_path", existing.uri.toString())
-                obj.put("file_name", existing.name ?: fileName)
-                obj.put("already_exists", true)
-                return obj.toString()
-            }
-        }
-
-        val targetDir = ensureDocumentDir(treeUri, relativeDir)
-            ?: return errorJson("Failed to access SAF directory")
-
-        var document = createOrReuseDocumentFile(targetDir, mimeType, fileName)
-            ?: return errorJson("Failed to create SAF file")
-
-        val pfd = contentResolver.openFileDescriptor(document.uri, "rw")
-            ?: return errorJson("Failed to open SAF file")
-
-        var detachedFd: Int? = null
-        try {
-            // Prefer handing off a detached FD directly to Go.
-            // Some devices/providers reject re-opening /proc/self/fd/* with permission denied.
-            detachedFd = pfd.detachFd()
-            req.put("output_path", "")
-            req.put("output_fd", detachedFd)
-            req.put("output_ext", outputExt)
-            val response = downloader(req.toString())
-            val respObj = JSONObject(response)
-            if (respObj.optBoolean("success", false)) {
-                // Extension providers write to a local temp path instead of the SAF FD.
-                val goFilePath = respObj.optString("file_path", "")
-                if (goFilePath.isNotEmpty() &&
-                    !goFilePath.startsWith("content://") &&
-                    !goFilePath.startsWith("/proc/self/fd/")
-                ) {
-                    try {
-                        val srcFile = java.io.File(goFilePath)
-                        if (!srcFile.exists() || srcFile.length() <= 0) {
-                            throw IllegalStateException("extension output missing or empty: $goFilePath")
-                        }
-                        val actualExt = normalizeExt(srcFile.extension)
-                        if (actualExt.isNotBlank() && actualExt != outputExt) {
-                            val actualFileName = buildSafFileName(req, actualExt)
-                            val actualMimeType = mimeTypeForExt(actualExt)
-                            val replacement = createOrReuseDocumentFile(
-                                targetDir,
-                                actualMimeType,
-                                actualFileName,
-                            )
-                                ?: throw IllegalStateException("failed to create SAF output with actual extension")
-                            if (replacement.uri != document.uri) {
-                                document.delete()
-                                document = replacement
-                            }
-                        }
-                        contentResolver.openOutputStream(document.uri, "wt")?.use { output ->
-                            srcFile.inputStream().use { input ->
-                                input.copyTo(output)
-                            }
-                        } ?: throw IllegalStateException("failed to open SAF output stream")
-                        srcFile.delete()
-                    } catch (e: Exception) {
-                        document.delete()
-                        android.util.Log.w("SpotiFLAC", "Failed to copy extension output to SAF: ${e.message}")
-                        return errorJson("Failed to copy extension output to SAF: ${e.message}")
-                    }
-                }
-                respObj.put("file_path", document.uri.toString())
-                respObj.put("file_name", document.name ?: fileName)
-            } else {
-                document.delete()
-            }
-            return respObj.toString()
-        } catch (e: Exception) {
-            document.delete()
-            return errorJson("SAF download failed: ${e.message}")
-        } finally {
-            // If detachFd() failed before handoff, close original ParcelFileDescriptor.
-            // Otherwise Go owns the detached raw FD and is responsible for closing it.
-            if (detachedFd == null) {
-                try {
-                    pfd.close()
-                } catch (_: Exception) {}
-            }
-        }
-    }
-
    /**
     * Get the parent DocumentFile directory for a SAF document URI.
     * The child URI must be a tree-based document URI (e.g. from SAF tree scan).
@@ -2195,7 +2064,7 @@ class MainActivity: FlutterFragmentActivity() {
                        "downloadByStrategy" -> {
                            val requestJson = call.arguments as String
                            val response = withContext(Dispatchers.IO) {
-                                handleSafDownload(requestJson) { json ->
+                                SafDownloadHandler.handle(this@MainActivity, requestJson) { json ->
                                    Gobackend.downloadByStrategy(json)
                                }
                            }
@@ -2886,6 +2755,27 @@ class MainActivity: FlutterFragmentActivity() {
                        "isDownloadServiceRunning" -> {
                            result.success(DownloadService.isServiceRunning())
                        }
+                        "startNativeDownloadWorker" -> {
+                            val requestsJson = call.argument<String>("requests_json") ?: "[]"
+                            val settingsJson = call.argument<String>("settings_json") ?: "{}"
+                            DownloadService.startNativeQueue(this@MainActivity, requestsJson, settingsJson)
+                            result.success(null)
+                        }
+                        "pauseNativeDownloadWorker" -> {
+                            DownloadService.pauseNativeQueue(this@MainActivity)
+                            result.success(null)
+                        }
+                        "resumeNativeDownloadWorker" -> {
+                            DownloadService.resumeNativeQueue(this@MainActivity)
+                            result.success(null)
+                        }
+                        "cancelNativeDownloadWorker" -> {
+                            DownloadService.cancelNativeQueue(this@MainActivity)
+                            result.success(null)
+                        }
+                        "getNativeDownloadWorkerSnapshot" -> {
+                            result.success(parseJsonPayload(DownloadService.getNativeWorkerSnapshot(this@MainActivity)))
+                        }
                        "preWarmTrackCache" -> {
                            val tracksJson = call.argument<String>("tracks") ?: "[]"
                            withContext(Dispatchers.IO) {
@@ -0,0 +1,390 @@
+package com.zarz.spotiflac
+
+import android.content.Context
+import android.net.Uri
+import androidx.documentfile.provider.DocumentFile
+import org.json.JSONObject
+import java.io.File
+import java.util.Locale
+
+/**
+ * Shared SAF download wrapper for foreground activity calls and service-owned
+ * native workers.
+ */
+object SafDownloadHandler {
+    private val safDirLock = Any()
+
+    fun handle(context: Context, requestJson: String, downloader: (String) -> String): String {
+        val req = JSONObject(requestJson)
+        val storageMode = req.optString("storage_mode", "")
+        val treeUriStr = req.optString("saf_tree_uri", "")
+        if (storageMode != "saf" || treeUriStr.isBlank()) {
+            return downloader(requestJson)
+        }
+
+        val treeUri = Uri.parse(treeUriStr)
+        val relativeDir = sanitizeRelativeDir(req.optString("saf_relative_dir", ""))
+        val outputExt = normalizeExt(req.optString("saf_output_ext", ""))
+        val mimeType = mimeTypeForExt(outputExt)
+        val fileName = buildSafFileName(req, outputExt)
+        val useStagedOutput = req.optBoolean("stage_saf_output", false)
+        val stagedFileName = if (useStagedOutput) buildStagedSafFileName(fileName, outputExt) else fileName
+
+        val existingDir = findDocumentDir(context, treeUri, relativeDir)
+        if (existingDir != null) {
+            val existing = existingDir.findFile(fileName)
+            if (existing != null && existing.isFile && existing.length() > 0) {
+                if (useStagedOutput) {
+                    existingDir.findFile(stagedFileName)?.delete()
+                }
+                val obj = JSONObject()
+                obj.put("success", true)
+                obj.put("message", "File already exists")
+                obj.put("file_path", existing.uri.toString())
+                obj.put("file_name", existing.name ?: fileName)
+                obj.put("already_exists", true)
+                return obj.toString()
+            }
+        }
+
+        val targetDir = ensureDocumentDir(context, treeUri, relativeDir)
+            ?: return errorJson("Failed to access SAF directory")
+
+        var document = createOrReuseDocumentFile(targetDir, mimeType, stagedFileName)
+            ?: return errorJson("Failed to create SAF file")
+
+        val pfd = context.contentResolver.openFileDescriptor(document.uri, "rw")
+            ?: return errorJson("Failed to open SAF file")
+
+        var detachedFd: Int? = null
+        try {
+            detachedFd = pfd.detachFd()
+            req.put("output_path", "")
+            req.put("output_fd", detachedFd)
+            req.put("output_ext", outputExt)
+            val response = downloader(req.toString())
+            val respObj = JSONObject(response)
+            if (respObj.optBoolean("success", false)) {
+                val goFilePath = respObj.optString("file_path", "")
+                if (goFilePath.isNotEmpty() &&
+                    !goFilePath.startsWith("content://") &&
+                    !goFilePath.startsWith("/proc/self/fd/")
+                ) {
+                    try {
+                        val srcFile = File(goFilePath)
+                        if (!srcFile.exists() || srcFile.length() <= 0) {
+                            throw IllegalStateException("extension output missing or empty: $goFilePath")
+                        }
+                        val actualExt = normalizeExt(srcFile.extension)
+                        if (actualExt.isNotBlank()) {
+                            respObj.put("actual_extension", actualExt)
+                        }
+                        if (actualExt.isNotBlank() && actualExt != outputExt) {
+                            val actualFileName = buildSafFileName(req, actualExt)
+                            val actualStagedFileName = if (useStagedOutput) {
+                                buildStagedSafFileName(actualFileName, actualExt)
+                            } else {
+                                actualFileName
+                            }
+                            val actualMimeType = mimeTypeForExt(actualExt)
+                            val replacement = createOrReuseDocumentFile(
+                                targetDir,
+                                actualMimeType,
+                                actualStagedFileName
+                            ) ?: throw IllegalStateException(
+                                "failed to create SAF output with actual extension"
+                            )
+                            if (replacement.uri != document.uri) {
+                                document.delete()
+                                document = replacement
+                            }
+                        }
+                        context.contentResolver.openOutputStream(document.uri, "wt")?.use { output ->
+                            srcFile.inputStream().use { input ->
+                                input.copyTo(output)
+                            }
+                        } ?: throw IllegalStateException("failed to open SAF output stream")
+                        srcFile.delete()
+                    } catch (e: Exception) {
+                        document.delete()
+                        android.util.Log.w(
+                            "SpotiFLAC",
+                            "Failed to copy extension output to SAF: ${e.message}"
+                        )
+                        return errorJson("Failed to copy extension output to SAF: ${e.message}")
+                    }
+                }
+                respObj.put("file_path", document.uri.toString())
+                respObj.put("file_name", document.name ?: fileName)
+                if (useStagedOutput) {
+                    respObj.put("saf_staged_output", true)
+                    respObj.put("saf_staged_file_name", document.name ?: stagedFileName)
+                }
+            } else {
+                document.delete()
+            }
+            return respObj.toString()
+        } catch (e: Exception) {
+            document.delete()
+            return errorJson("SAF download failed: ${e.message}")
+        } finally {
+            if (detachedFd == null) {
+                try {
+                    pfd.close()
+                } catch (_: Exception) {
+                }
+            }
+        }
+    }
+
+    fun copyContentUriToTemp(context: Context, uriStr: String): String? {
+        return try {
+            val uri = Uri.parse(uriStr)
+            val extension = DocumentFile.fromSingleUri(context, uri)
+                ?.name
+                ?.substringAfterLast('.', "")
+                ?.takeIf { it.isNotBlank() }
+                ?.let { ".$it" }
+                ?: ".tmp"
+            val temp = File.createTempFile("native_saf_", extension, context.cacheDir)
+            context.contentResolver.openInputStream(uri)?.use { input ->
+                temp.outputStream().use { output ->
+                    input.copyTo(output)
+                }
+            } ?: return null
+            temp.absolutePath
+        } catch (e: Exception) {
+            android.util.Log.w("SpotiFLAC", "Failed to copy SAF URI to temp: ${e.message}")
+            null
+        }
+    }
+
+    fun writeFileToSaf(
+        context: Context,
+        treeUriStr: String,
+        relativeDir: String,
+        fileName: String,
+        mimeType: String,
+        srcPath: String
+    ): String? {
+        return try {
+            val treeUri = Uri.parse(treeUriStr)
+            val targetDir = ensureDocumentDir(context, treeUri, relativeDir) ?: return null
+            val finalName = sanitizeFilename(fileName)
+            val ext = normalizeExt(finalName.substringAfterLast('.', ""))
+            val stagedName = buildStagedSafFileName(finalName, ext)
+            val document = createOrReuseDocumentFile(targetDir, mimeType, stagedName)
+                ?: return null
+            context.contentResolver.openOutputStream(document.uri, "wt")?.use { output ->
+                File(srcPath).inputStream().use { input ->
+                    input.copyTo(output)
+                }
+            } ?: return null
+
+            val existingFinal = targetDir.findFile(finalName)
+            if (existingFinal != null && existingFinal.uri != document.uri) {
+                existingFinal.delete()
+            }
+            if (!document.renameTo(finalName)) {
+                document.delete()
+                return null
+            }
+            targetDir.findFile(finalName)?.uri?.toString() ?: document.uri.toString()
+        } catch (e: Exception) {
+            android.util.Log.w("SpotiFLAC", "Failed to write file to SAF: ${e.message}")
+            null
+        }
+    }
+
+    fun deleteContentUri(context: Context, uriStr: String): Boolean {
+        return try {
+            DocumentFile.fromSingleUri(context, Uri.parse(uriStr))?.delete() == true
+        } catch (_: Exception) {
+            false
+        }
+    }
+
+    private fun normalizeExt(ext: String?): String {
+        if (ext.isNullOrBlank()) return ""
+        return if (ext.startsWith(".")) {
+            ext.lowercase(Locale.ROOT)
+        } else {
+            ".${ext.lowercase(Locale.ROOT)}"
+        }
+    }
+
+    private fun mimeTypeForExt(ext: String?): String {
+        return when (normalizeExt(ext)) {
+            ".m4a", ".mp4" -> "audio/mp4"
+            ".mp3" -> "audio/mpeg"
+            ".opus" -> "audio/ogg"
+            ".flac" -> "audio/flac"
+            ".lrc" -> "application/octet-stream"
+            else -> "application/octet-stream"
+        }
+    }
+
+    private fun forceFilenameExt(name: String, outputExt: String): String {
+        val normalizedExt = normalizeExt(outputExt)
+        if (normalizedExt.isBlank()) return sanitizeFilename(name)
+
+        val safeName = sanitizeFilename(name)
+        val lower = safeName.lowercase(Locale.ROOT)
+        val knownExts = listOf(".flac", ".m4a", ".mp4", ".mp3", ".opus", ".lrc")
+        for (knownExt in knownExts) {
+            if (lower.endsWith(knownExt)) {
+                return safeName.dropLast(knownExt.length) + normalizedExt
+            }
+        }
+        return safeName + normalizedExt
+    }
+
+    private fun buildStagedSafFileName(fileName: String, outputExt: String): String {
+        val safeName = sanitizeFilename(fileName)
+        val ext = normalizeExt(outputExt)
+        if (ext.isNotBlank() && safeName.lowercase(Locale.ROOT).endsWith(ext)) {
+            return safeName.dropLast(ext.length).trimEnd('.', ' ') + ".partial$ext"
+        }
+
+        val dot = safeName.lastIndexOf('.')
+        if (dot > 0 && dot < safeName.lastIndex) {
+            return safeName.substring(0, dot).trimEnd('.', ' ') +
+                ".partial" +
+                safeName.substring(dot)
+        }
+        return "$safeName.partial"
+    }
+
+    private fun sanitizeFilename(name: String): String {
+        var sanitized = name
+            .replace("/", " ")
+            .replace(Regex("[\\\\:*?\"<>|]"), " ")
+            .filter { ch ->
+                val code = ch.code
+                !((code < 0x20 && ch != '\t' && ch != '\n' && ch != '\r') ||
+                    code == 0x7F ||
+                    (Character.isISOControl(ch) && ch != '\t' && ch != '\n' && ch != '\r'))
+            }
+            .trim()
+            .trim('.', ' ')
+
+        sanitized = sanitized
+            .replace(Regex("\\s+"), " ")
+            .replace(Regex("_+"), "_")
+            .trim('_', ' ')
+
+        return if (sanitized.isBlank()) "Unknown" else sanitized
+    }
+
+    private fun sanitizeRelativeDir(relativeDir: String): String {
+        if (relativeDir.isBlank()) return ""
+        return relativeDir
+            .split("/")
+            .map { sanitizeFilename(it) }
+            .filter { it.isNotBlank() && it != "." && it != ".." }
+            .joinToString("/")
+    }
+
+    private fun ensureDocumentDir(
+        context: Context,
+        treeUri: Uri,
+        relativeDir: String
+    ): DocumentFile? {
+        val safeRelativeDir = sanitizeRelativeDir(relativeDir)
+        if (safeRelativeDir.isBlank()) {
+            return DocumentFile.fromTreeUri(context, treeUri)
+        }
+
+        synchronized(safDirLock) {
+            var current = DocumentFile.fromTreeUri(context, treeUri) ?: return null
+            val parts = safeRelativeDir.split("/").filter { it.isNotBlank() }
+            for (part in parts) {
+                val existing = current.findFile(part)
+                current = if (existing != null && existing.isDirectory) {
+                    existing
+                } else {
+                    val created = current.createDirectory(part) ?: return null
+                    val createdName = created.name ?: part
+                    if (createdName != part) {
+                        created.delete()
+                        current.findFile(part) ?: return null
+                    } else {
+                        created
+                    }
+                }
+            }
+            return current
+        }
+    }
+
+    private fun findDocumentDir(
+        context: Context,
+        treeUri: Uri,
+        relativeDir: String
+    ): DocumentFile? {
+        var current = DocumentFile.fromTreeUri(context, treeUri) ?: return null
+        val safeRelativeDir = sanitizeRelativeDir(relativeDir)
+        if (safeRelativeDir.isBlank()) return current
+
+        val parts = safeRelativeDir.split("/").filter { it.isNotBlank() }
+        for (part in parts) {
+            val existing = current.findFile(part)
+            if (existing == null || !existing.isDirectory) return null
+            current = existing
+        }
+        return current
+    }
+
+    private fun createOrReuseDocumentFile(
+        parent: DocumentFile,
+        mimeType: String,
+        fileName: String
+    ): DocumentFile? {
+        val safeFileName = sanitizeFilename(fileName)
+        if (safeFileName.isBlank()) return null
+
+        synchronized(safDirLock) {
+            val existing = parent.findFile(safeFileName)
+            if (existing != null && existing.isFile) {
+                return existing
+            }
+
+            val created = parent.createFile(mimeType, safeFileName) ?: return null
+            val createdName = created.name ?: safeFileName
+            if (createdName == safeFileName) {
+                return created
+            }
+
+            val winner = parent.findFile(safeFileName)
+            if (winner != null && winner.isFile) {
+                if (winner.uri != created.uri) {
+                    try {
+                        created.delete()
+                    } catch (_: Exception) {
+                    }
+                }
+                return winner
+            }
+
+            return created
+        }
+    }
+
+    private fun buildSafFileName(req: JSONObject, outputExt: String): String {
+        val provided = req.optString("saf_file_name", "")
+        if (provided.isNotBlank()) return forceFilenameExt(provided, outputExt)
+
+        val trackName = req.optString("track_name", "track")
+        val artistName = req.optString("artist_name", "")
+        val baseName = if (artistName.isNotBlank()) "$artistName - $trackName" else trackName
+        return forceFilenameExt(baseName, outputExt)
+    }
+
+    private fun errorJson(message: String): String {
+        val obj = JSONObject()
+        obj.put("success", false)
+        obj.put("error", message)
+        obj.put("message", message)
+        return obj.toString()
+    }
+}