feat: honour ANDROID_ADB_SERVER_PORT env variable

dadb/src/main/kotlin/dadb/Dadb.kt

@@ -240,6 +240,29 @@ interface Dadb : AutoCloseable {
         private const val MIN_EMULATOR_PORT = 5555
         private const val MAX_EMULATOR_PORT = 5683
 
+        /**
+         * Upper bound of the emulator port scan, honouring ADB_LOCAL_TRANSPORT_MAX_PORT like the
+         * adb client does. adb ignores invalid values here rather than failing, and a bound below
+         * [MIN_EMULATOR_PORT] disables the scan.
+         */
+        internal fun resolveMaxEmulatorPort(raw: String?): Int {
+            val trimmed = raw?.trim()
+            if (trimmed.isNullOrEmpty()) return MAX_EMULATOR_PORT
+            val port = trimmed.toIntOrNull()
+            if (port == null || port !in 0..65535) return MAX_EMULATOR_PORT
+            return port
+        }
+
+        private fun isLoopbackHost(host: String) =
+            host == "localhost" || host == "127.0.0.1" || host == "::1"
+
+        /**
+         * Whether the emulator scan should run. Scanning bypasses the adb server entirely, so it is
+         * skipped when a non-default local server was explicitly asked for.
+         */
+        internal fun shouldScanForEmulators(host: String, adbServerPort: Int) =
+            !isLoopbackHost(host) || adbServerPort == AdbServer.STANDARD_ADB_SERVER_PORT
+
         @JvmStatic
         @JvmOverloads
         fun create(host: String, port: Int, keyPair: AdbKeyPair? = AdbKeyPair.readDefault(), connectTimeout: Int = 0, socketTimeout: Int = 0, keepAlive: Boolean = false): Dadb = DadbImpl(host, port, keyPair, connectTimeout, socketTimeout, keepAlive = keepAlive)
@@ -256,7 +279,10 @@ interface Dadb : AutoCloseable {
             val dadbs = AdbServer.listDadbs(adbServerHost = host)
             if (dadbs.isNotEmpty()) return dadbs
 
-            return (MIN_EMULATOR_PORT .. MAX_EMULATOR_PORT).mapNotNull { port ->
+            if (!shouldScanForEmulators(host, AdbServer.DEFAULT_ADB_SERVER_PORT)) return emptyList()
+
+            val maxEmulatorPort = resolveMaxEmulatorPort(System.getenv("ADB_LOCAL_TRANSPORT_MAX_PORT"))
+            return (MIN_EMULATOR_PORT .. maxEmulatorPort).mapNotNull { port ->
                 val dadb = create(host, port, keyPair, connectTimeout, socketTimeout, keepAlive = keepAlive)
                 val response = try {
                     dadb.shell("echo success").allOutput

dadb/src/main/kotlin/dadb/adbserver/AdbServer.kt

@@ -14,6 +14,31 @@ import java.nio.charset.StandardCharsets
 
 object AdbServer {
 
+    /**
+     * The adb server port used when ANDROID_ADB_SERVER_PORT is not set.
+     */
+    const val STANDARD_ADB_SERVER_PORT = 5037
+
+    /**
+     * Default adb server port, honouring ANDROID_ADB_SERVER_PORT like the adb CLI does.
+     *
+     * Throws [IllegalArgumentException] if the variable holds something that is not a valid port,
+     * rather than silently falling back to [STANDARD_ADB_SERVER_PORT].
+     */
+    @JvmStatic
+    val DEFAULT_ADB_SERVER_PORT: Int
+        get() = resolveAdbServerPort(System.getenv("ANDROID_ADB_SERVER_PORT"))
+
+    internal fun resolveAdbServerPort(raw: String?): Int {
+        val trimmed = raw?.trim()
+        if (trimmed.isNullOrEmpty()) return STANDARD_ADB_SERVER_PORT
+        val port = trimmed.toIntOrNull()
+        require(port != null && port in 1..65535) {
+            "ANDROID_ADB_SERVER_PORT must be a port in 1..65535: got \"$raw\""
+        }
+        return port
+    }
+
     /**
      * Experimental API
      *
@@ -45,7 +70,7 @@ object AdbServer {
     @JvmOverloads
     fun createDadb(
         adbServerHost: String = "localhost",
-        adbServerPort: Int = 5037,
+        adbServerPort: Int = DEFAULT_ADB_SERVER_PORT,
         deviceQuery: String = "host:transport-any",
         connectTimeout: Int = 0,
         socketTimeout: Int = 0
@@ -63,7 +88,7 @@ object AdbServer {
     @JvmOverloads
     fun listDadbs(
         adbServerHost: String = "localhost",
-        adbServerPort: Int = 5037,
+        adbServerPort: Int = DEFAULT_ADB_SERVER_PORT,
     ): List<Dadb> {
         if (!AdbBinary.tryStartServer(adbServerHost, adbServerPort)) {
             return emptyList()

dadb/src/test/kotlin/dadb/EmulatorScanPolicyTest.kt

@@ -0,0 +1,29 @@
+package dadb
+
+import com.google.common.truth.Truth.assertThat
+import kotlin.test.Test
+
+internal class EmulatorScanPolicyTest {
+
+    @Test
+    fun defaultServerStillScans() {
+        assertThat(Dadb.shouldScanForEmulators("localhost", 5037)).isTrue()
+    }
+
+    @Test
+    fun customLocalServerSkipsTheScan() {
+        assertThat(Dadb.shouldScanForEmulators("localhost", 5039)).isFalse()
+    }
+
+    @Test
+    fun loopbackSpellingsAreTreatedAsLocal() {
+        assertThat(Dadb.shouldScanForEmulators("127.0.0.1", 5039)).isFalse()
+        assertThat(Dadb.shouldScanForEmulators("::1", 5039)).isFalse()
+    }
+
+    @Test
+    fun remoteHostsStillScanRegardlessOfTheConfiguredPort() {
+        assertThat(Dadb.shouldScanForEmulators("10.0.0.5", 5039)).isTrue()
+        assertThat(Dadb.shouldScanForEmulators("10.0.0.5", 5037)).isTrue()
+    }
+}

dadb/src/test/kotlin/dadb/EmulatorScanPortTest.kt

@@ -0,0 +1,58 @@
+package dadb
+
+import com.google.common.truth.Truth.assertThat
+import kotlin.test.Test
+
+internal class EmulatorScanPortTest {
+
+    @Test
+    fun unsetKeepsDefaultBound() {
+        assertThat(Dadb.resolveMaxEmulatorPort(null)).isEqualTo(5683)
+    }
+
+    @Test
+    fun emptyKeepsDefaultBound() {
+        assertThat(Dadb.resolveMaxEmulatorPort("")).isEqualTo(5683)
+        assertThat(Dadb.resolveMaxEmulatorPort("   ")).isEqualTo(5683)
+    }
+
+    @Test
+    fun boundIsParsed() {
+        assertThat(Dadb.resolveMaxEmulatorPort("5565")).isEqualTo(5565)
+    }
+
+    @Test
+    fun surroundingWhitespaceIsIgnored() {
+        assertThat(Dadb.resolveMaxEmulatorPort(" 5565 ")).isEqualTo(5565)
+        assertThat(Dadb.resolveMaxEmulatorPort("\t5565\n")).isEqualTo(5565)
+    }
+
+    @Test
+    fun invalidValuesAreIgnoredRatherThanRejected() {
+        assertThat(Dadb.resolveMaxEmulatorPort("not-a-port")).isEqualTo(5683)
+        assertThat(Dadb.resolveMaxEmulatorPort("5565abc")).isEqualTo(5683)
+        assertThat(Dadb.resolveMaxEmulatorPort("-1")).isEqualTo(5683)
+        assertThat(Dadb.resolveMaxEmulatorPort("65536")).isEqualTo(5683)
+    }
+
+    @Test
+    fun boundaryValuesAreAccepted() {
+        assertThat(Dadb.resolveMaxEmulatorPort("0")).isEqualTo(0)
+        assertThat(Dadb.resolveMaxEmulatorPort("65535")).isEqualTo(65535)
+    }
+
+    @Test
+    fun boundBelowFirstEmulatorPortYieldsAnEmptyScan() {
+        listOf("0", "1", "5554").forEach { raw ->
+            val range = 5555..Dadb.resolveMaxEmulatorPort(raw)
+            assertThat(range.isEmpty()).isTrue()
+        }
+    }
+
+    @Test
+    fun boundNarrowsTheScanRange() {
+        val range = 5555..Dadb.resolveMaxEmulatorPort("5565")
+        assertThat(range.toList()).hasSize(11)
+        assertThat(range.last).isEqualTo(5565)
+    }
+}

dadb/src/test/kotlin/dadb/adbserver/AdbServerPortTest.kt

@@ -0,0 +1,61 @@
+package dadb.adbserver
+
+import com.google.common.truth.Truth.assertThat
+import kotlin.test.Test
+import kotlin.test.assertFailsWith
+
+internal class AdbServerPortTest {
+
+    @Test
+    fun unsetFallsBackToStandardPort() {
+        assertThat(AdbServer.resolveAdbServerPort(null)).isEqualTo(5037)
+    }
+
+    @Test
+    fun emptyFallsBackToStandardPort() {
+        assertThat(AdbServer.resolveAdbServerPort("")).isEqualTo(5037)
+    }
+
+    @Test
+    fun blankFallsBackToStandardPort() {
+        assertThat(AdbServer.resolveAdbServerPort("   ")).isEqualTo(5037)
+    }
+
+    @Test
+    fun portIsParsed() {
+        assertThat(AdbServer.resolveAdbServerPort("5039")).isEqualTo(5039)
+    }
+
+    @Test
+    fun surroundingWhitespaceIsIgnored() {
+        assertThat(AdbServer.resolveAdbServerPort(" 5039 ")).isEqualTo(5039)
+        assertThat(AdbServer.resolveAdbServerPort("\t5039\n")).isEqualTo(5039)
+    }
+
+    @Test
+    fun boundaryPortsAreAccepted() {
+        assertThat(AdbServer.resolveAdbServerPort("1")).isEqualTo(1)
+        assertThat(AdbServer.resolveAdbServerPort("65535")).isEqualTo(65535)
+    }
+
+    @Test
+    fun nonNumericIsRejected() {
+        assertFailsWith<IllegalArgumentException> { AdbServer.resolveAdbServerPort("not-a-port") }
+        assertFailsWith<IllegalArgumentException> { AdbServer.resolveAdbServerPort("5039abc") }
+    }
+
+    @Test
+    fun outOfRangeIsRejected() {
+        assertFailsWith<IllegalArgumentException> { AdbServer.resolveAdbServerPort("0") }
+        assertFailsWith<IllegalArgumentException> { AdbServer.resolveAdbServerPort("-1") }
+        assertFailsWith<IllegalArgumentException> { AdbServer.resolveAdbServerPort("65536") }
+        assertFailsWith<IllegalArgumentException> { AdbServer.resolveAdbServerPort("99999") }
+    }
+
+    @Test
+    fun rejectionMessageIncludesTheRawValue() {
+        val error = assertFailsWith<IllegalArgumentException> { AdbServer.resolveAdbServerPort(" 99999 ") }
+        assertThat(error).hasMessageThat().contains("ANDROID_ADB_SERVER_PORT")
+        assertThat(error).hasMessageThat().contains(" 99999 ")
+    }
+}