Skip to content

A rootless Android app that boots Alpine Linux: run containers (Podman/Docker/LXC) and GUI desktop apps.

fix(service): surface asset extraction failures

Kybernetria7c39754567ff
diff --git a/CLAUDE.md b/CLAUDE.md
index afbab47..e846543 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -233,7 +233,7 @@ In `QemuEngine.buildCommand()`: `tcg,thread=multi`, larger `tb-size` for ≥2GB
## VM migration / upgrades (how the guest updates without a reset)
-Asset extraction readiness fails if any bundled asset cannot be extracted, so `PodroidService` aborts startup rather than booting a mixed asset set. Extraction retries on the next app process launch; temporary-file cleanup targets only known asset destinations.
+Asset extraction readiness fails if any bundled asset cannot be extracted, so `PodroidService` publishes a localized `VmState.Error` and aborts startup rather than booting a mixed asset set. Extraction retries on the next app process launch; temporary-file cleanup targets only known asset destinations and is best-effort so a stale temporary sibling cannot block an already-current destination.
The guest system layer updates across app versions with **no VM reset and no data loss**, on both backends. The machinery:
diff --git a/app/src/main/java/com/excp/podroid/PodroidApplication.kt b/app/src/main/java/com/excp/podroid/PodroidApplication.kt
index efd4917..468651c 100644
--- a/app/src/main/java/com/excp/podroid/PodroidApplication.kt
+++ b/app/src/main/java/com/excp/podroid/PodroidApplication.kt
@@ -148,7 +148,13 @@ class PodroidApplication : Application() {
// Only inspect the temporary sibling owned by this extraction
// destination. Never scan filesDir recursively: unrelated app data may
// legitimately use a .tmp suffix.
- AssetExtractionSupport.deleteStaleTemporaryFile(destFile)
+ if (!AssetExtractionSupport.deleteStaleTemporaryFile(destFile)) {
+ Log.w(
+ TAG,
+ "Could not delete stale temporary asset " +
+ "${AssetExtractionSupport.temporaryFileFor(destFile).path}; continuing",
+ )
+ }
if (!forceCopy && destFile.exists() && (assetSize < 0 || destFile.length() == assetSize)) return
destFile.parentFile?.mkdirs()
diff --git a/app/src/main/java/com/excp/podroid/engine/EngineHolder.kt b/app/src/main/java/com/excp/podroid/engine/EngineHolder.kt
index e7a9f0b..3649a7f 100644
--- a/app/src/main/java/com/excp/podroid/engine/EngineHolder.kt
+++ b/app/src/main/java/com/excp/podroid/engine/EngineHolder.kt
@@ -130,6 +130,11 @@ class EngineHolder @Inject constructor(
// publish; set when start() runs.
@Volatile private var startedEngine: VmEngine? = null
+ // Service-side preflight can fail before a concrete backend is started.
+ // Keep that failure at the holder layer so it survives the asynchronous
+ // first backend pick and is visible through the same state flow the UI uses.
+ private val _startFailure = MutableStateFlow<VmState.Error?>(null)
+
init {
// 0. Publish the real first pick as soon as it resolves off-main, so the
// delegate flows (state/bootStage/consoleText via flatMapLatest) and
@@ -362,9 +367,14 @@ class EngineHolder @Inject constructor(
// Stopped that PodroidService would treat as a teardown signal. Once start()
// marks the engine started, its real state (including a later Stopped) passes
// through unchanged.
- override val state: StateFlow<VmState> = currentFlow
- .flatMapLatest { eng -> eng.state.map { st -> normalizeCycleState(eng, st) } }
- .stateIn(scope, SharingStarted.Eagerly, VmState.Idle)
+ override val state: StateFlow<VmState> = combine(
+ currentFlow.flatMapLatest { eng ->
+ eng.state.map { st -> normalizeCycleState(eng, st) }
+ },
+ _startFailure,
+ ) { backendState, failure ->
+ failure ?: backendState
+ }.stateIn(scope, SharingStarted.Eagerly, VmState.Idle)
override val bootStage: StateFlow<String> = currentFlow
.flatMapLatest { it.bootStage }
@@ -386,7 +396,12 @@ class EngineHolder @Inject constructor(
get() = current.sessionClientDelegate
set(v) { current.sessionClientDelegate = v }
+ override fun reportStartFailure(message: String) {
+ _startFailure.value = VmState.Error(message)
+ }
+
override suspend fun start(portForwards: List<PortForwardRule>, config: VmConfig) {
+ _startFailure.value = null
// Guarantee the first Start runs on the correctly-picked engine even on a
// fast cold launch where Start beats the init publish coroutine. start()
// is always called off-main (PodroidService.launchPodroid → withContext
diff --git a/app/src/main/java/com/excp/podroid/engine/VmEngine.kt b/app/src/main/java/com/excp/podroid/engine/VmEngine.kt
index fd089d0..bcf19b9 100644
--- a/app/src/main/java/com/excp/podroid/engine/VmEngine.kt
+++ b/app/src/main/java/com/excp/podroid/engine/VmEngine.kt
@@ -68,6 +68,15 @@ interface VmEngine {
*/
var sessionClientDelegate: TerminalSessionClient?
+ /**
+ * Publishes a launch failure that happened before a concrete backend's
+ * [start] method was entered. EngineHolder layers this into [state] so the
+ * existing UI error handling can explain service-side preflight failures.
+ * Concrete backends keep the default because these failures happen outside
+ * them.
+ */
+ fun reportStartFailure(message: String) = Unit
+
suspend fun start(portForwards: List<PortForwardRule>, config: VmConfig)
fun stop()
diff --git a/app/src/main/java/com/excp/podroid/service/PodroidService.kt b/app/src/main/java/com/excp/podroid/service/PodroidService.kt
index 13f9391..e47df4c 100644
--- a/app/src/main/java/com/excp/podroid/service/PodroidService.kt
+++ b/app/src/main/java/com/excp/podroid/service/PodroidService.kt
@@ -71,6 +71,26 @@ private fun runIgnoringBackgroundFgsDenial(tag: String, action: () -> Unit) {
}
}
+/**
+ * Awaits application asset readiness and publishes a user-visible VM error if
+ * readiness fails. The original exception is rethrown so the service's normal
+ * startup-failure cleanup still releases the WakeLock and foreground service.
+ */
+internal suspend fun awaitAssetsReadyForVm(
+ awaitReady: suspend () -> Unit,
+ failureMessage: String,
+ reportFailure: (String) -> Unit,
+) {
+ try {
+ awaitReady()
+ } catch (c: CancellationException) {
+ throw c
+ } catch (e: Exception) {
+ reportFailure(failureMessage)
+ throw e
+ }
+}
+
@AndroidEntryPoint
class PodroidService : Service() {
@@ -350,7 +370,13 @@ class PodroidService : Service() {
// reads vmlinuz/initrd/squashfs synchronously in start(), so
// we MUST block here until extraction has fully completed or
// the VM could launch against a partial/missing file.
- (application as? PodroidApplication)?.awaitAssetsReady()
+ (application as? PodroidApplication)?.let { app ->
+ awaitAssetsReadyForVm(
+ awaitReady = { app.awaitAssetsReady() },
+ failureMessage = getString(R.string.asset_extraction_failed),
+ reportFailure = engine::reportStartFailure,
+ )
+ }
val rules = portForwardRepository.getRulesSnapshot().toMutableList()
val sshEnabled = settingsRepository.getSshEnabledSnapshot()
diff --git a/app/src/main/java/com/excp/podroid/util/AssetExtractionSupport.kt b/app/src/main/java/com/excp/podroid/util/AssetExtractionSupport.kt
index c3e7eea..313673a 100644
--- a/app/src/main/java/com/excp/podroid/util/AssetExtractionSupport.kt
+++ b/app/src/main/java/com/excp/podroid/util/AssetExtractionSupport.kt
@@ -44,13 +44,12 @@ internal object AssetExtractionSupport {
fun temporaryFileFor(destFile: File): File =
File(destFile.parentFile, destFile.name + TMP_SUFFIX)
- /** Deletes only the temporary sibling owned by [destFile]. */
- fun deleteStaleTemporaryFile(destFile: File) {
+ /**
+ * Deletes only the temporary sibling owned by [destFile]. Returns false if
+ * a stale sibling exists but cannot be removed; callers may log and continue.
+ */
+ fun deleteStaleTemporaryFile(destFile: File): Boolean {
val temporaryFile = temporaryFileFor(destFile)
- if (temporaryFile.exists() && !temporaryFile.delete()) {
- throw java.io.IOException(
- "stale temporary asset file ${temporaryFile.path} could not be deleted",
- )
- }
+ return !temporaryFile.exists() || temporaryFile.delete()
}
}
diff --git a/app/src/main/res/values-zh/strings.xml b/app/src/main/res/values-zh/strings.xml
index bccc6ba..b956807 100644
--- a/app/src/main/res/values-zh/strings.xml
+++ b/app/src/main/res/values-zh/strings.xml
@@ -228,6 +228,7 @@
<!-- Error -->
<string name="error_title">错误</string>
+ <string name="asset_extraction_failed">无法解压虚拟机文件。请释放一些存储空间并重启应用。</string>
<string name="try_again">重试</string>
<!-- Sharing -->
diff --git a/app/src/main/res/values/strings.xml b/app/src/main/res/values/strings.xml
index 53b4979..6c513b2 100644
--- a/app/src/main/res/values/strings.xml
+++ b/app/src/main/res/values/strings.xml
@@ -228,6 +228,7 @@
<!-- Error -->
<string name="error_title">Error</string>
+ <string name="asset_extraction_failed">Could not unpack the VM files. Free some storage and restart the app.</string>
<string name="try_again">Try again</string>
<!-- Sharing -->
diff --git a/app/src/test/java/com/excp/podroid/service/PodroidServiceReadinessTest.kt b/app/src/test/java/com/excp/podroid/service/PodroidServiceReadinessTest.kt
new file mode 100644
index 0000000..666a71f
--- /dev/null
+++ b/app/src/test/java/com/excp/podroid/service/PodroidServiceReadinessTest.kt
@@ -0,0 +1,30 @@
+package com.excp.podroid.service
+
+import com.excp.podroid.engine.VmState
+import java.io.IOException
+import kotlinx.coroutines.runBlocking
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertSame
+import org.junit.Test
+
+class PodroidServiceReadinessTest {
+ @Test
+ fun awaitAssetsReadyForVm_reportsErrorBeforeRethrowing() = runBlocking {
+ val failure = IOException("disk full")
+ var state: VmState = VmState.Idle
+
+ val thrown = try {
+ awaitAssetsReadyForVm(
+ awaitReady = { throw failure },
+ failureMessage = "localized extraction failure",
+ reportFailure = { state = VmState.Error(it) },
+ )
+ null
+ } catch (e: Exception) {
+ e
+ }
+
+ assertSame(failure, thrown)
+ assertEquals(VmState.Error("localized extraction failure"), state)
+ }
+}
diff --git a/app/src/test/java/com/excp/podroid/util/AssetExtractionSupportTest.kt b/app/src/test/java/com/excp/podroid/util/AssetExtractionSupportTest.kt
index 6d763c3..832b7f2 100644
--- a/app/src/test/java/com/excp/podroid/util/AssetExtractionSupportTest.kt
+++ b/app/src/test/java/com/excp/podroid/util/AssetExtractionSupportTest.kt
@@ -37,9 +37,22 @@ class AssetExtractionSupportTest {
destinationTemporary.writeText("stale")
unrelatedTemporary.writeText("keep")
- AssetExtractionSupport.deleteStaleTemporaryFile(destination)
+ assertTrue(AssetExtractionSupport.deleteStaleTemporaryFile(destination))
assertFalse(destinationTemporary.exists())
assertTrue(unrelatedTemporary.exists())
}
+
+ @Test
+ fun deleteStaleTemporaryFile_reportsFailureWithoutThrowing() {
+ val destination = File(temporaryFolder.root, "assets/initrd.img").apply {
+ parentFile.mkdirs()
+ }
+ val destinationTemporary = AssetExtractionSupport.temporaryFileFor(destination)
+ destinationTemporary.mkdirs()
+ File(destinationTemporary, "child").writeText("keep")
+
+ assertFalse(AssetExtractionSupport.deleteStaleTemporaryFile(destination))
+ assertTrue(destinationTemporary.exists())
+ }
}