feat: Add and document optional kadb-mdns module

README.md

@@ -6,7 +6,7 @@ Kadb is a Kotlin Multiplatform ADB client library for talking directly to `adbd`
 
 It is intended for apps and tools that need shell, sync, install, pairing, or port forwarding without embedding the full `adb` CLI or server stack.
 
-[Platform Notes](docs/platform.md) · [Host Identity](docs/kadbcert.md) · [Docs Index](docs/README.md)
+[Platform Notes](docs/platform.md) · [mDNS Discovery](docs/mdns.md) · [Host Identity](docs/kadbcert.md) · [Docs Index](docs/README.md)
 
 ## Overview
 
@@ -21,7 +21,15 @@ Kadb is not a full adb server replacement. USB discovery, transport brokering, a
 
 ```kotlin
 dependencies {
-    implementation("com.flyfishxu:kadb:2.1.1")
+    implementation("com.flyfishxu:kadb:2.1.2")
+}
+```
+
+Optional mDNS discovery:
+
+```kotlin
+dependencies {
+    implementation("com.flyfishxu:kadb-mdns:2.1.2")
 }
 ```
 
@@ -43,6 +51,20 @@ Pair with a new Android 11+ device:
 Kadb.pair("10.0.0.175", 37755, "643102")
 ```
 
+Discover wireless debugging endpoints with the optional mDNS artifact:
+
+```kotlin
+val mdns = KadbMdnsAndroid(context)
+mdns.start()
+```
+
+```kotlin
+val mdns = KadbMdnsJvm()
+mdns.start()
+```
+
+Discovered endpoints can be passed to `Kadb.create(host, port)` or `Kadb.pair(host, port, code)`.
+
 ## API Overview
 
 | Capability | API |
@@ -54,6 +76,7 @@ Kadb.pair("10.0.0.175", 37755, "643102")
 | APK install | `install(...)`, `installMultiple(...)`, `uninstall(...)` |
 | Port forwarding | `tcpForward(...)` |
 | Transport reuse | `resetConnection()` |
+| Optional mDNS discovery | `KadbMdnsAndroid`, `KadbMdnsJvm` |
 
 ## Examples
 
@@ -96,7 +119,7 @@ Example JVM pairing dependency:
 
 ```kotlin
 dependencies {
-    implementation("com.flyfishxu:kadb:2.1.1")
+    implementation("com.flyfishxu:kadb:2.1.2")
     implementation("org.conscrypt:conscrypt-openjdk-uber:2.5.2")
 }
 ```
@@ -112,6 +135,7 @@ More detail: [docs/platform.md](docs/platform.md)
 
 - [Documentation Index](docs/README.md)
 - [Platform Notes](docs/platform.md)
+- [mDNS Discovery](docs/mdns.md)
 - [KadbCert](docs/kadbcert.md)
 
 ## Acknowledgements

docs/README.md

@@ -1,6 +1,7 @@
 # Documentation
 
 - [Platform Notes](platform.md)
+- [mDNS Discovery](mdns.md)
 - [KadbCert](kadbcert.md)
 
 The main project overview and quick-start examples live in [../README.md](../README.md).

docs/mdns.md

@@ -0,0 +1,76 @@
+# mDNS Discovery
+
+Kadb mDNS discovery is available as the optional `com.flyfishxu:kadb-mdns` artifact.
+
+The module discovers ADB-related mDNS services only. It does not open ADB connections, perform pairing, or manage device authorization. Consumers decide how to use discovered endpoints with `Kadb.create(host, port)` or `Kadb.pair(host, port, code)`.
+
+## Installation
+
+```kotlin
+dependencies {
+    implementation("com.flyfishxu:kadb-mdns:2.1.2")
+}
+```
+
+Use the core Kadb artifact separately when you also need ADB connections:
+
+```kotlin
+dependencies {
+    implementation("com.flyfishxu:kadb:2.1.2")
+    implementation("com.flyfishxu:kadb-mdns:2.1.2")
+}
+```
+
+## Service Types
+
+The default configuration searches for:
+
+- `_adb._tcp`
+- `_adb-tls-connect._tcp`
+- `_adb-tls-pairing._tcp`
+
+`_adb._tcp` and `_adb-tls-connect._tcp` are exposed as connect endpoints. `_adb-tls-pairing._tcp` is exposed as pairing endpoints.
+
+## Android
+
+Android discovery requires an explicit `Context`:
+
+```kotlin
+val mdns = KadbMdnsAndroid(context)
+mdns.start()
+```
+
+The Android implementation uses platform `NsdManager`, stores `context.applicationContext`, and supports API 23+. Android API 34 and newer use `NsdManager.ServiceInfoCallback`; older versions use `resolveService`.
+
+## JVM
+
+JVM discovery does not require Android concepts:
+
+```kotlin
+val mdns = KadbMdnsJvm()
+mdns.start()
+```
+
+The JVM implementation uses JmDNS internally. It attempts to create discovery backends for eligible active network interfaces and falls back to a default JmDNS instance if interface enumeration cannot provide a usable address.
+
+## Lifecycle
+
+`KadbMdns` exposes a `StateFlow<MdnsDiscoveryState>`:
+
+```kotlin
+mdns.state.collect { state ->
+    val target = state.connectDevices.firstOrNull()
+    if (target != null) {
+        // Kadb.create(target.host, target.port)
+    }
+}
+```
+
+Call `start()` to begin discovery. Call `stop()` or `close()` to stop listeners and clear state.
+
+## Notes
+
+- No default logging is emitted by the module.
+- Discovery data is best-effort and network-dependent.
+- The library trusts mDNS host/port data; connection failures should be handled by the caller.
+- USB discovery remains out of scope.

docs/platform.md

@@ -12,6 +12,7 @@ This page documents the platform-specific runtime requirements and behavior diff
 | APK install / uninstall | Yes | Yes |
 | TCP forward | Yes | Yes |
 | Wireless pairing | Yes | Yes |
+| Optional mDNS discovery | Yes | Yes |
 | USB discovery | No | No |
 
 ## Pairing Requirements
@@ -31,6 +32,8 @@ Basic connect / shell / sync / install usage does not require the same provider
 - `minSdk 23`
 - direct client features are supported on Android targets
 - pairing support depends on TLS provider availability
+- optional mDNS discovery is provided by `com.flyfishxu:kadb-mdns`
+- mDNS discovery requires an explicit Android `Context` and uses platform `NsdManager`
 
 ### Pairing
 
@@ -58,6 +61,9 @@ The JVM target supports:
 - APK install / uninstall
 - TCP forward
 - wireless pairing
+- optional mDNS discovery through `com.flyfishxu:kadb-mdns`
+
+The JVM mDNS implementation uses JmDNS internally and does not require Android concepts such as `Context`.
 
 ### Pairing
 
@@ -67,7 +73,7 @@ Recommended setup:
 
 ```kotlin
 dependencies {
-    implementation("com.flyfishxu:kadb:2.1.1")
+    implementation("com.flyfishxu:kadb:2.1.2")
     implementation("org.conscrypt:conscrypt-openjdk-uber:2.5.2")
 }
 ```
@@ -87,4 +93,5 @@ Further detail: [kadbcert.md](kadbcert.md)
 ## Related Docs
 
 - [Project README](../README.md)
+- [mDNS Discovery](mdns.md)
 - [KadbCert](kadbcert.md)

gradle/libs.versions.toml

@@ -17,6 +17,7 @@ documentfile = "1.1.0"
 dokka = "2.1.0"
 hiddenapibypass = "6.1"
 conscrypt-java = "2.5.2"
+jmdns = "3.6.3"
 
 [libraries]
 
@@ -29,3 +30,4 @@ okio = { module = "com.squareup.okio:okio", version.ref = "okio" }
 documentfile = { group = "androidx.documentfile", name = "documentfile", version.ref = "documentfile" }
 hiddenapibypass = { module = "org.lsposed.hiddenapibypass:hiddenapibypass", version.ref = "hiddenapibypass" }
 conscrypt-java = { module = "org.conscrypt:conscrypt-openjdk-uber", version.ref = "conscrypt-java" }
+jmdns = { module = "org.jmdns:jmdns", version.ref = "jmdns" }

kadb-mdns/build.gradle.kts

@@ -0,0 +1,83 @@
+plugins {
+    alias(libs.plugins.kotlinMultiplatform)
+    alias(libs.plugins.androidMultiplatformLibrary)
+    id("com.vanniktech.maven.publish")
+    id("signing")
+}
+
+kotlin {
+    jvm {
+        kotlin {
+            jvmToolchain(21)
+        }
+    }
+
+    android {
+        namespace = "com.flyfishxu.kadb.mdns"
+        compileSdk = 37
+        minSdk = 23
+
+        withJava()
+    }
+
+    sourceSets {
+        commonMain.dependencies {
+            api(libs.kotlinx.coroutines.core)
+        }
+
+        commonTest.dependencies {
+            implementation(libs.kotlin.test)
+        }
+
+        jvmMain.dependencies {
+            implementation(libs.jmdns)
+        }
+    }
+}
+
+tasks.withType<org.jetbrains.kotlin.gradle.tasks.KotlinCompilationTask<*>>().configureEach {
+    compilerOptions {
+        freeCompilerArgs.add("-Xexpect-actual-classes")
+    }
+}
+
+signing {
+    useGpgCmd()
+}
+
+mavenPublishing {
+    publishToMavenCentral()
+    if (providers.gradleProperty("signAllPublications").map { it.toBoolean() }.orElse(true).get()) {
+        signAllPublications()
+    }
+
+    coordinates("com.flyfishxu", "kadb-mdns", "2.1.2")
+
+    pom {
+        name.set("Kadb mDNS")
+        description.set("Optional Kotlin Multiplatform mDNS discovery module for ADB services.")
+        url.set("https://github.com/flyfishxu/Kadb.git")
+
+        licenses {
+            license {
+                name.set("Apache License 2.0")
+                url.set("http://www.apache.org/licenses/LICENSE-2.0.txt")
+                distribution.set("repo")
+            }
+        }
+        developers {
+            developer {
+                id.set("flyfishxu")
+                name.set("Flyfish Xu")
+                url.set("https://github.com/flyfishxu")
+                organization.set("Flyfish Studio")
+                email.set("flyfishxu@outlook.com")
+            }
+        }
+        scm {
+            connection.set("scm:git:git://github.com/flyfishxu/Kadb.git")
+            developerConnection.set("scm:git:ssh://github.com/flyfishxu/Kadb.git")
+            url.set("https://github.com/flyfishxu/Kadb.git")
+        }
+    }
+}