Skip to content

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

fix(portforward): keep user rules off QEMU's launch command line

ExTv0b42df8b1389
diff --git a/app/src/main/java/com/excp/podroid/data/repository/PortForwardRepository.kt b/app/src/main/java/com/excp/podroid/data/repository/PortForwardRepository.kt
index 08ba4b3..ebba0e0 100644
--- a/app/src/main/java/com/excp/podroid/data/repository/PortForwardRepository.kt
+++ b/app/src/main/java/com/excp/podroid/data/repository/PortForwardRepository.kt
@@ -66,6 +66,36 @@ data class PortForwardRule(
* with the same host port and protocol would produce duplicate QEMU hostfwd
* arguments and a duplicate Compose key crash.
*/
+/**
+ * Ceiling on persisted rules. Not a human limit — it exists because
+ * `podroid-forward add` in a shell loop can produce thousands, and every rule is
+ * a listening socket, a row in the Settings list, and a QMP round trip on every
+ * boot. One user scripted 1005 of them and made their VM unstartable.
+ */
+internal const val MAX_PORT_FORWARD_RULES = 128
+
+/** Outcome of [PortForwardRepository.addRule]. */
+enum class AddRuleResult { ADDED, RESERVED, TABLE_FULL }
+
+/**
+ * Whether [newRule] would push the table past [max]. Replacing an existing
+ * (hostPort, protocol) is not growth, so it stays allowed at the limit —
+ * otherwise a full table could not be corrected, only cleared.
+ */
+internal fun portForwardTableIsFull(
+ current: Set<String>,
+ newRule: PortForwardRule,
+ max: Int = MAX_PORT_FORWARD_RULES,
+): Boolean {
+ if (current.size < max) return false
+ return current.none { serialized ->
+ val existing = PortForwardRule.deserialize(serialized)
+ existing != null &&
+ existing.hostPort == newRule.hostPort &&
+ existing.protocol == newRule.protocol
+ }
+}
+
internal fun deduplicatePortForwards(
current: Set<String>,
newRule: PortForwardRule,
@@ -112,12 +142,23 @@ class PortForwardRepository @Inject constructor(
}
.distinctUntilChanged()
- suspend fun addRule(rule: PortForwardRule) {
- if (rule.hostPort in RESERVED_HOST_PORTS) return
+ /**
+ * Persist a rule. Returns why it was refused when it was, so a caller that
+ * can show the reason does not have to guess — the guest CLI in particular
+ * used to print OK for a rule that was dropped here.
+ */
+ suspend fun addRule(rule: PortForwardRule): AddRuleResult {
+ if (rule.hostPort in RESERVED_HOST_PORTS) return AddRuleResult.RESERVED
+ var result = AddRuleResult.ADDED
context.dataStore.edit { prefs ->
val current = prefs[KEY_PORT_FORWARDS] ?: emptySet()
+ if (portForwardTableIsFull(current, rule)) {
+ result = AddRuleResult.TABLE_FULL
+ return@edit
+ }
prefs[KEY_PORT_FORWARDS] = deduplicatePortForwards(current, rule)
}
+ return result
}
suspend fun removeRule(rule: PortForwardRule) {
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 4de6eab..7cf2555 100644
--- a/app/src/main/java/com/excp/podroid/engine/EngineHolder.kt
+++ b/app/src/main/java/com/excp/podroid/engine/EngineHolder.kt
@@ -156,10 +156,13 @@ class EngineHolder @Inject constructor(
return@collect
}
if (!wasRunning) {
- // Entering Running: launchRules are already baked into the
- // launch cmdline, so treat them as applied. Unchanged boot →
- // added/removed empty; a rule removed mid-boot → removed.
- appliedRules = launchRules
+ // Entering Running: seed from what the engine actually applied
+ // while launching, which is NOT always the whole launch set.
+ // QEMU keeps user rules off its cmdline (one hostfwd it cannot
+ // bind kills the VM), so those arrive here as `added` and go in
+ // over QMP. Seeding from launchRules instead would mark them
+ // applied and they would silently never exist.
+ appliedRules = eng.rulesAppliedAtLaunch(launchRules)
// The implicit always-on forwards (in launchRules but never
// persisted to the DataStore) must never be torn down by the
// diff. Capture them once here so they can be folded into
diff --git a/app/src/main/java/com/excp/podroid/engine/QemuEngine.kt b/app/src/main/java/com/excp/podroid/engine/QemuEngine.kt
index d0a2537..8381231 100644
--- a/app/src/main/java/com/excp/podroid/engine/QemuEngine.kt
+++ b/app/src/main/java/com/excp/podroid/engine/QemuEngine.kt
@@ -635,7 +635,10 @@ class QemuEngine @Inject constructor(
val netdevArg = buildString {
append("user,id=net0,ipv6=off")
- for (rule in portForwards) {
+ // Only the implicit forwards go here; user rules arrive over QMP once
+ // the VM is up. See inlineLaunchRules for why that distinction is
+ // load-bearing rather than cosmetic.
+ for (rule in inlineLaunchRules(portForwards)) {
// hostfwd hostaddr: empty = 0.0.0.0 (LAN-reachable, user rules);
// 127.0.0.1 for loopbackOnly rules (implicit VNC/audio) so they
// aren't exposed to the network.
@@ -792,10 +795,44 @@ class QemuEngine @Inject constructor(
}
}
+ /**
+ * QEMU applies only the implicit forwards while launching; the rest have to
+ * be pushed in over QMP once the VM is Running.
+ */
+ override fun rulesAppliedAtLaunch(all: Collection<PortForwardRule>): Set<PortForwardRule> =
+ inlineLaunchRules(all).toSet()
+
companion object {
private const val TAG = "QemuEngine"
private const val STDERR_TAIL_LINES = 40
+ /**
+ * The port forwards allowed onto QEMU's launch command line.
+ *
+ * SLIRP treats a hostfwd it cannot set up as fatal: QEMU exits 1 before
+ * the machine starts. Rules are persisted, so anything inlined here can
+ * make the VM permanently unstartable, with the app offering no way to
+ * edit the rules that are blocking it. One user hit exactly that by
+ * scripting 1005 forwards, most of them inside Android's ephemeral port
+ * range where something is always already bound; the VM never booted
+ * again and they wiped it believing the data was gone.
+ *
+ * So the command line carries only what the app injects itself and needs
+ * from the first instant: the loopback-bound VNC and audio pair behind
+ * the in-app viewer, and SSH (guest port 22), which is the way back in
+ * when everything else is broken. Those are three fixed ports the app
+ * controls, all below the ephemeral range.
+ *
+ * User rules go in through [addPortForward] on the →Running edge, where
+ * a rule that cannot bind fails alone and is retried on the next diff.
+ * This also un-bricks anyone already stuck: their rules simply stop being
+ * a launch argument.
+ */
+ fun inlineLaunchRules(all: Collection<PortForwardRule>): List<PortForwardRule> =
+ all.filter { it.loopbackOnly || it.guestPort == SSH_GUEST_PORT }
+
+ private const val SSH_GUEST_PORT = 22
+
/** Shared deadline for start()'s socket-readiness loop and the boot monitor's connect wait. */
private const val SOCKET_READY_TIMEOUT_MS = 10_000L
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 3ccfebf..fc286fc 100644
--- a/app/src/main/java/com/excp/podroid/engine/VmEngine.kt
+++ b/app/src/main/java/com/excp/podroid/engine/VmEngine.kt
@@ -83,6 +83,19 @@ interface VmEngine {
suspend fun addPortForward(rule: PortForwardRule)
suspend fun removePortForward(rule: PortForwardRule)
+ /**
+ * Of the rules handed to [start], the ones this backend has actually applied
+ * by the time the VM reaches Running. Everything else must be pushed in
+ * afterwards through [addPortForward].
+ *
+ * EngineHolder seeds its reconciliation state from this, so an engine that
+ * over-reports here loses the difference silently: those rules are recorded
+ * as live and never applied. Defaults to all of them, which is true for AVF
+ * (its forwarder takes the whole set at start). QEMU narrows it, because a
+ * forward on its command line can stop the VM booting at all.
+ */
+ fun rulesAppliedAtLaunch(all: Collection<PortForwardRule>): Set<PortForwardRule> = all.toSet()
+
/**
* Backend-specific diagnostics for the export log: AVF stop/crash reason +
* launch config, or QEMU exit code + stderr tail. Empty when there's nothing
diff --git a/app/src/main/java/com/excp/podroid/engine/hostbridge/HostRequestDispatcher.kt b/app/src/main/java/com/excp/podroid/engine/hostbridge/HostRequestDispatcher.kt
index b8848ef..180c1c8 100644
--- a/app/src/main/java/com/excp/podroid/engine/hostbridge/HostRequestDispatcher.kt
+++ b/app/src/main/java/com/excp/podroid/engine/hostbridge/HostRequestDispatcher.kt
@@ -8,12 +8,14 @@
*/
package com.excp.podroid.engine.hostbridge
+import com.excp.podroid.data.repository.AddRuleResult
+import com.excp.podroid.data.repository.MAX_PORT_FORWARD_RULES
import com.excp.podroid.data.repository.PortForwardRule
import kotlinx.coroutines.CancellationException
class HostRequestDispatcher(
private val notifications: NotificationPoster,
- private val addForward: suspend (PortForwardRule) -> Unit,
+ private val addForward: suspend (PortForwardRule) -> AddRuleResult,
private val removeForward: suspend (PortForwardRule) -> Unit,
private val listForwards: suspend () -> List<PortForwardRule>,
private val openUrl: suspend (String) -> String,
@@ -80,8 +82,15 @@ class HostRequestDispatcher(
// fails to apply on every diff and every boot while the guest CLI saw OK.
if (host < 1024) return HostProtocol.err("host port must be >= 1024 (Android apps can't bind privileged ports)")
if (proto !in validProtocols) return HostProtocol.err("bad protocol")
- addForward(PortForwardRule(host, guest, proto))
- return HostProtocol.ok()
+ // Report a refusal instead of printing OK for a rule that was dropped:
+ // a CLI that lies about this is how a user ends up believing 1000 rules
+ // exist when the table stopped accepting them long before.
+ return when (addForward(PortForwardRule(host, guest, proto))) {
+ AddRuleResult.ADDED -> HostProtocol.ok()
+ AddRuleResult.RESERVED -> HostProtocol.err("host port $host is reserved for the in-app desktop")
+ AddRuleResult.TABLE_FULL ->
+ HostProtocol.err("port forward table is full ($MAX_PORT_FORWARD_RULES rules); remove some first")
+ }
}
// FWD-REMOVE <hostPort> <proto>
diff --git a/app/src/main/java/com/excp/podroid/ui/screens/settings/SettingsScreen.kt b/app/src/main/java/com/excp/podroid/ui/screens/settings/SettingsScreen.kt
index 068235a..eb6ab94 100644
--- a/app/src/main/java/com/excp/podroid/ui/screens/settings/SettingsScreen.kt
+++ b/app/src/main/java/com/excp/podroid/ui/screens/settings/SettingsScreen.kt
@@ -70,6 +70,7 @@ import androidx.lifecycle.compose.LocalLifecycleOwner
import androidx.lifecycle.compose.collectAsStateWithLifecycle
import com.excp.podroid.BuildConfig
import com.excp.podroid.R
+import com.excp.podroid.data.repository.MAX_PORT_FORWARD_RULES
import com.excp.podroid.data.repository.PortForwardRepository
import com.excp.podroid.data.repository.PortForwardRule
import com.excp.podroid.engine.EngineSelection
@@ -414,6 +415,7 @@ fun SettingsScreen(
if (showAddDialog) {
AddPortForwardDialog(
onDismiss = { showAddDialog = false },
+ tableFull = portForwardRules.size >= MAX_PORT_FORWARD_RULES,
onAdd = { hostPort, guestPort, protocol ->
// Only close the dialog when the rule was actually added.
// addPortForward returns false if the (hostPort, protocol) pair
@@ -703,6 +705,9 @@ private fun AdvancedFieldsBlock(
@Composable
private fun AddPortForwardDialog(
onDismiss: () -> Unit,
+ // The repository refuses rules past its ceiling. Checking here too keeps the
+ // message truthful: without it a refusal would surface as "already forwarded".
+ tableFull: Boolean,
// Returns true if the rule was added, false if it was a duplicate.
// The dialog shows an error and stays open on false.
onAdd: (hostPort: Int, guestPort: Int, protocol: String) -> Boolean,
@@ -774,6 +779,10 @@ private fun AddPortForwardDialog(
error = context.getString(R.string.port_reserved, hp)
return@TextButton
}
+ if (tableFull) {
+ error = context.getString(R.string.port_forward_table_full, MAX_PORT_FORWARD_RULES)
+ return@TextButton
+ }
val added = onAdd(hp, gp, protocol)
if (!added) error = context.getString(R.string.port_already_forwarded, hp, protocol.uppercase())
}) {
diff --git a/app/src/main/res/values-zh/strings.xml b/app/src/main/res/values-zh/strings.xml
index 7038b46..2653d38 100644
--- a/app/src/main/res/values-zh/strings.xml
+++ b/app/src/main/res/values-zh/strings.xml
@@ -116,6 +116,7 @@
<string name="enter_valid_ports">输入有效的端口号 (1-65535)</string>
<string name="port_already_forwarded">端口 %1$d (%2$s) 已转发</string>
<string name="port_reserved">端口 %1$d 已保留给应用内桌面</string>
+ <string name="port_forward_table_full">端口转发已达上限 %1$d 条,请先删除一条。</string>
<string name="reset">重置</string>
<string name="remove">删除</string>
<string name="port_forwards_count">端口转发 (%1$d)</string>
diff --git a/app/src/main/res/values/strings.xml b/app/src/main/res/values/strings.xml
index 0d332a6..154a4cf 100644
--- a/app/src/main/res/values/strings.xml
+++ b/app/src/main/res/values/strings.xml
@@ -116,6 +116,7 @@
<string name="enter_valid_ports">Enter valid port numbers (1–65535)</string>
<string name="port_already_forwarded">Port %1$d (%2$s) is already forwarded</string>
<string name="port_reserved">Port %1$d is reserved for the in-app desktop</string>
+ <string name="port_forward_table_full">Limit of %1$d port forwards reached. Remove one first.</string>
<string name="reset">Reset</string>
<string name="remove">Remove</string>
<string name="port_forwards_count">Port forwards (%1$d)</string>
diff --git a/app/src/test/java/com/excp/podroid/data/repository/PortForwardRepositoryTest.kt b/app/src/test/java/com/excp/podroid/data/repository/PortForwardRepositoryTest.kt
index 9e94671..29d0311 100644
--- a/app/src/test/java/com/excp/podroid/data/repository/PortForwardRepositoryTest.kt
+++ b/app/src/test/java/com/excp/podroid/data/repository/PortForwardRepositoryTest.kt
@@ -130,4 +130,45 @@ class PortForwardRepositoryTest {
val result = deduplicatePortForwards(emptySet<String>(), newRule)
assertEquals(setOf(newRule.serialize()), result)
}
+
+ // ------------------------------------------------------------------
+ // table size limit
+ //
+ // Unbounded growth is how one user ended up with 1005 persisted rules,
+ // which is both unusable in the UI and a thousand QMP round trips on every
+ // boot. The limit is a guard rail on a scripted loop, not on human use.
+ // ------------------------------------------------------------------
+
+ private fun tableOf(n: Int): Set<String> =
+ (1..n).map { PortForwardRule(20000 + it, 20000 + it, "tcp").serialize() }.toSet()
+
+ @Test
+ fun `a table below the limit accepts a new rule`() {
+ val full = portForwardTableIsFull(tableOf(MAX_PORT_FORWARD_RULES - 1), PortForwardRule(9000, 9000))
+ assertEquals(false, full)
+ }
+
+ @Test
+ fun `a full table rejects a new host port`() {
+ val full = portForwardTableIsFull(tableOf(MAX_PORT_FORWARD_RULES), PortForwardRule(9000, 9000))
+ assertEquals(true, full)
+ }
+
+ @Test
+ fun `a full table still accepts a rule that replaces an existing one`() {
+ // Re-pointing an existing (hostPort, protocol) is not growth, and refusing
+ // it would leave a user at the limit unable to correct a wrong rule.
+ val existing = tableOf(MAX_PORT_FORWARD_RULES)
+ val replacement = PortForwardRule(20001, 40001, "tcp")
+ assertEquals(false, portForwardTableIsFull(existing, replacement))
+ assertEquals(MAX_PORT_FORWARD_RULES, deduplicatePortForwards(existing, replacement).size)
+ }
+
+ @Test
+ fun `a full table accepts the other protocol on a used host port`() {
+ // (hostPort, protocol) is the key, so udp on a tcp port is a NEW rule and
+ // must be refused at the limit rather than silently overwriting the tcp one.
+ val existing = tableOf(MAX_PORT_FORWARD_RULES)
+ assertEquals(true, portForwardTableIsFull(existing, PortForwardRule(20001, 20001, "udp")))
+ }
}
diff --git a/app/src/test/java/com/excp/podroid/engine/EngineHolderDiffTest.kt b/app/src/test/java/com/excp/podroid/engine/EngineHolderDiffTest.kt
index d160f6d..015ec36 100644
--- a/app/src/test/java/com/excp/podroid/engine/EngineHolderDiffTest.kt
+++ b/app/src/test/java/com/excp/podroid/engine/EngineHolderDiffTest.kt
@@ -60,6 +60,28 @@ class EngineHolderDiffTest {
assertEquals(emptySet<PortForwardRule>(), removed)
}
+ @Test
+ fun `user rules kept off the cmdline are applied on the Running edge`() {
+ // QEMU bakes only the implicit forwards into its launch cmdline, because
+ // SLIRP kills the whole VM over one hostfwd it cannot bind. Everything
+ // else has to arrive over QMP instead, which only happens if the →Running
+ // seeding reflects what the engine ACTUALLY applied rather than the whole
+ // launch set. Seeding it from launchRules here would compute added ==
+ // empty and the user's forwards would silently never exist.
+ // loopbackOnly is what marks the viewer's pair as app-injected, and it is
+ // what keeps them on the cmdline, so the fixture has to carry it.
+ val ssh = rule(9922, 22)
+ val vnc = PortForwardRule(5900, 5900, "tcp", loopbackOnly = true)
+ val audio = PortForwardRule(4713, 4713, "tcp", loopbackOnly = true)
+ val userRules = setOf(rule(8080), rule(2121))
+ val launch = userRules + setOf(ssh, vnc, audio)
+ val appliedAtLaunch = QemuEngine.inlineLaunchRules(launch).toSet()
+ val implicit = launch - userRules
+ val (added, removed) = computeRuleDiff(applied = appliedAtLaunch, desired = userRules + implicit)
+ assertEquals(userRules, added)
+ assertEquals(emptySet<PortForwardRule>(), removed)
+ }
+
@Test
fun `implicit always-on forwards are never removed`() {
// SSH/VNC/audio are injected into the launch set by PodroidService but
diff --git a/app/src/test/java/com/excp/podroid/engine/QemuLaunchRulesTest.kt b/app/src/test/java/com/excp/podroid/engine/QemuLaunchRulesTest.kt
new file mode 100644
index 0000000..054ef39
--- /dev/null
+++ b/app/src/test/java/com/excp/podroid/engine/QemuLaunchRulesTest.kt
@@ -0,0 +1,76 @@
+/*
+ * Podroid - Rootless Podman for Android
+ * Copyright (C) 2024-2026 Podroid contributors
+ */
+package com.excp.podroid.engine
+
+import com.excp.podroid.data.repository.PortForwardRule
+import com.excp.podroid.engine.QemuEngine.Companion.inlineLaunchRules
+import com.excp.podroid.x11.X11Constants
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertTrue
+import org.junit.Test
+
+/**
+ * Pins which port forwards are allowed onto QEMU's launch command line.
+ *
+ * This is a safety boundary, not a style choice. SLIRP aborts the whole launch
+ * when any single hostfwd cannot be set up, and the rules are persisted, so
+ * every rule inlined here is a rule that can permanently stop the VM from
+ * starting. That is not hypothetical: a user who added 1005 forwards, most of
+ * them inside Android's ephemeral port range where something is always already
+ * bound, was left with a VM that could never boot again and concluded it had
+ * destroyed their data.
+ *
+ * User rules therefore go in over QMP once the VM is up, where a rule that
+ * cannot bind is one failed rule instead of a dead VM.
+ */
+class QemuLaunchRulesTest {
+
+ private fun user(host: Int, guest: Int = host) = PortForwardRule(host, guest)
+
+ private val vnc = PortForwardRule(
+ X11Constants.VNC_PORT, X11Constants.VNC_PORT, "tcp", loopbackOnly = true,
+ )
+ private val audio = PortForwardRule(
+ X11Constants.AUDIO_PORT, X11Constants.AUDIO_PORT, "tcp", loopbackOnly = true,
+ )
+ private val ssh = PortForwardRule(9922, 22)
+
+ @Test
+ fun `user rules never reach the launch command line`() {
+ val inline = inlineLaunchRules(listOf(user(8080), user(2121), user(30000)))
+ assertEquals(emptyList<PortForwardRule>(), inline)
+ }
+
+ @Test
+ fun `the in-app viewer forwards stay inline`() {
+ // The viewer dials these the moment the VM is Running, so they must be
+ // live at that instant rather than after a round of QMP calls.
+ val inline = inlineLaunchRules(listOf(vnc, audio, user(8080)))
+ assertEquals(listOf(vnc, audio), inline)
+ }
+
+ @Test
+ fun `ssh stays inline so a wrecked forward table is still recoverable`() {
+ // If everything else fails to apply, the user must still be able to get
+ // into the guest and undo whatever they did.
+ val inline = inlineLaunchRules(listOf(user(8080), ssh))
+ assertEquals(listOf(ssh), inline)
+ }
+
+ @Test
+ fun `a thousand user rules collapse to the implicit ones`() {
+ // The exact shape of the report: seq 30000 31000 through podroid-forward,
+ // plus the three the app injects itself.
+ val flood = (30000..31000).map { user(it) }
+ val inline = inlineLaunchRules(flood + listOf(ssh, vnc, audio))
+ assertEquals(listOf(ssh, vnc, audio), inline)
+ assertTrue("1001 user rules must not reach the cmdline", inline.size == 3)
+ }
+
+ @Test
+ fun `an empty set stays empty`() {
+ assertEquals(emptyList<PortForwardRule>(), inlineLaunchRules(emptyList()))
+ }
+}
diff --git a/app/src/test/java/com/excp/podroid/engine/hostbridge/HostRequestDispatcherTest.kt b/app/src/test/java/com/excp/podroid/engine/hostbridge/HostRequestDispatcherTest.kt
index 42fca36..9e4ffb9 100644
--- a/app/src/test/java/com/excp/podroid/engine/hostbridge/HostRequestDispatcherTest.kt
+++ b/app/src/test/java/com/excp/podroid/engine/hostbridge/HostRequestDispatcherTest.kt
@@ -3,6 +3,7 @@ package com.excp.podroid.engine.hostbridge
import org.junit.Assert.assertEquals
import org.junit.Assert.assertNull
import org.junit.Test
+import com.excp.podroid.data.repository.AddRuleResult
import com.excp.podroid.data.repository.PortForwardRule
import kotlinx.coroutines.runBlocking
import org.junit.Assert.assertTrue
@@ -35,9 +36,16 @@ private fun dispatcher(
openUrl: suspend (String) -> String = { HostProtocol.ok() },
power: suspend (String) -> String = { HostProtocol.ok() },
setHeadless: suspend (String) -> String = { HostProtocol.ok() },
+ addResult: AddRuleResult = AddRuleResult.ADDED,
) = HostRequestDispatcher(
notifications = poster,
- addForward = { r -> rules.removeAll { it.hostPort == r.hostPort && it.protocol == r.protocol }; rules.add(r) },
+ addForward = { r ->
+ if (addResult == AddRuleResult.ADDED) {
+ rules.removeAll { it.hostPort == r.hostPort && it.protocol == r.protocol }
+ rules.add(r)
+ }
+ addResult
+ },
removeForward = { r -> rules.removeAll { it.hostPort == r.hostPort && it.protocol == r.protocol } },
listForwards = { rules.toList() },
openUrl = openUrl,
@@ -94,6 +102,23 @@ class HostRequestDispatcherTest {
assertEquals("tcp", rules.single().protocol)
}
+ @Test fun fwdAddReportsARefusedRuleInsteadOfOk() = runBlocking {
+ // The CLI printing OK for a rule the repository dropped is how a user ends
+ // up believing a thousand forwards exist when the table stopped taking them.
+ val rules = mutableListOf<PortForwardRule>()
+ val resp = dispatcher(rules = rules, addResult = AddRuleResult.TABLE_FULL)
+ .handle("FWD-ADD 8080 80 tcp")
+ assertTrue(resp.startsWith("ERR "))
+ // The reason rides base64 like every other free-text field on this wire.
+ assertTrue(HostProtocol.dec(resp.removePrefix("ERR "))!!.contains("full"))
+ assertEquals(0, rules.size)
+ }
+
+ @Test fun fwdAddReportsAReservedPort() = runBlocking {
+ val resp = dispatcher(addResult = AddRuleResult.RESERVED).handle("FWD-ADD 5900 5900 tcp")
+ assertTrue(resp.startsWith("ERR "))
+ }
+
@Test fun fwdAddRejectsBadPort() = runBlocking {
assertTrue(dispatcher().handle("FWD-ADD 0 80 tcp").startsWith("ERR "))
assertTrue(dispatcher().handle("FWD-ADD 70000 80 tcp").startsWith("ERR "))
diff --git a/docs/guide/networking.html b/docs/guide/networking.html
index f4c121d..c4e0418 100644
--- a/docs/guide/networking.html
+++ b/docs/guide/networking.html
@@ -123,6 +123,11 @@ podman run -d -p 8080:80 nginx
# Then from your laptop on the same Wi-Fi:</span>
curl http://&lt;phone-ip&gt;:8080</code></pre>
+ <h3>Limits on the rule list</h3>
+ <p>A host port that something else on the phone is already using cannot be forwarded. That rule alone fails and is retried whenever the list changes; the VM keeps running and every other rule is unaffected. Android hands out ports from 32768 upwards to ordinary apps, so a rule in that range is the most likely one to collide - pick host ports below it when you have the choice.</p>
+
+ <p>Up to 128 rules can be saved. The limit exists because each rule is a listening socket and a row in Settings, and because a shell loop can otherwise add thousands of them in a second. <code>podroid-forward</code> reports an error rather than reporting success once the list is full.</p>
+
<h2>Talking back to Android from the guest</h2>
<p>Several command-line tools ship inside the VM so scripts and shell sessions can reach the Android side directly, without the in-app UI. They all work on the QEMU and AVF backends.</p>