@devioarts/capacitor-mdns 0.0.2 → 0.1.0

package/Package.swift

@@ -10,7 +10,7 @@ let package = Package(
             targets: ["mDNSPlugin"])
     ],
     dependencies: [
-        .package(url: "https://github.com/ionic-team/capacitor-swift-pm.git", from: "7.0.0")
+        .package(url: "https://github.com/ionic-team/capacitor-swift-pm.git", from: "8.0.0")
     ],
     targets: [
         .target(

package/README.md

@@ -1,9 +1,11 @@
 # @devioarts/capacitor-mdns
 
-mDNS plugin for Capacitor that supports Bonjour/mDNS advertisements and discovery.
+mDNS plugin for Capacitor that supports Bonjour/mDNS advertisements and discovery on iOS,
+Android, Electron, and a safe web fallback.
 
-#### Supported platforms: ✓ iOS ✓ Android ✓ Electron
-#### Demo (sources): [application](https://github.com/devioarts/capacitor-examples/tree/main/capacitor-mdns) or directly [file](https://github.com/devioarts/capacitor-examples/blob/main/capacitor-mdns/src/Playground.tsx)
+#### Supported platforms: ✓ iOS ✓ Android ✓ Electron ✓ Web fallback
+
+The in-repository [`playground`](./playground) is the example app used during development.
 
 ## Install
 
@@ -12,82 +14,37 @@ npm install @devioarts/capacitor-mdns
 npx cap sync
 ```
 
-## Android
-#### /android/app/src/main/AndroidManifest.xml
-```xml
-<uses-permission android:name="android.permission.INTERNET" />
-```
+## Usage
 
-## iOS
-#### /ios/App/App/Info.plist
-```xml
-<key>NSLocalNetworkUsageDescription</key>
-<string>It is needed for the correct functioning of the application</string>
-<key>NSAppTransportSecurity</key>
-<dict>
-    <key>NSAllowsLocalNetworking</key>
-    <true/>
-</dict>
-<key>NSBonjourServices</key>
-<array>
-    <string>_http._tcp</string>
-</array>
-```
+```ts
+import { mDNS } from '@devioarts/capacitor-mdns';
 
----
-## ElectronJS
+const runtime = await mDNS.getPluginPlatform();
 
-```shell
-npm i bonjour-service@1.3.0
+await mDNS.startBroadcast({ type: '_http._tcp.', name: 'MyService', port: 9100 });
+const result = await mDNS.discover({ type: '_http._tcp.', timeout: 3000 });
+await mDNS.stopBroadcast();
 ```
 
-> Implementation example was developed on [capacitor-electron](https://github.com/devioarts/capacitor-examples/tree/main/capacitor-electron)
-> base, if you run electron differently, you may need to adjust the code.
+## Platform Setup
 
-#### /electron/main.ts
+Android requires mDNS/network permissions in `AndroidManifest.xml`; the plugin also declares them
+so they are merged during sync. iOS requires local network keys in `Info.plist`.
+Electron support is intended for [`devioarts/capacitor-electron`](https://github.com/devioarts/capacitor-electron)
+and uses metadata exported from `@devioarts/capacitor-mdns/electron/settings`.
 
-```typescript
-// ...
-import { mDNS } from '@devioarts/capacitor-mdns/electron/mdns'
-// ...
-const mdns = new mDNS();
-// ...
-app.whenReady().then(() => {
-	//...
-	mdns.init();
-	//...
-});
-/* Or you can use app.on:ready (whenReady is recomended)
-app.on('ready', () => {
-	// ...
-	mdns.init();
-	// ...
-});
-*/
-
-app.on('before-quit', async () => {
-	// ...
-	mdns.destroy();
-	// ...
-})
-//...
-```
-### electron/preload.cjs
-```javascript
-//...
-// THIS IS IMPORTANT FOR PLUGIN!
-const {createMDNSAPI} = require("@devioarts/capacitor-mdns/electron/mdns-bridge.cjs");
-//...
-// THIS IS IMPORTANT FOR PLUGIN!
-contextBridge.exposeInMainWorld('mDNS', createMDNSAPI({ ipcRenderer }));
-contextBridge.exposeInMainWorld('mdns', createMDNSAPI({ ipcRenderer })) // alias
-```
+Detailed setup lives in:
+
+- [iOS and Android setup](./docs/platform-setup.md)
+- [Electron setup](./docs/electron.md)
+- [Playground](./docs/playground.md)
+- [Runtime behavior](./docs/runtime-behavior.md)
 
----
 ## API
 
 <docgen-index>
 
+* [`getPluginPlatform()`](#getpluginplatform)
 * [`startBroadcast(...)`](#startbroadcast)
 * [`stopBroadcast()`](#stopbroadcast)
 * [`discover(...)`](#discover)
@@ -101,6 +58,19 @@ contextBridge.exposeInMainWorld('mdns', createMDNSAPI({ ipcRenderer })) // alias
 
 Public API surface of the Capacitor mDNS plugin.
 
+### getPluginPlatform()
+
+```typescript
+getPluginPlatform() => Promise<MdnsPluginPlatformResult>
+```
+
+Return the platform implementation currently serving plugin calls.
+
+**Returns:** <code>Promise&lt;<a href="#mdnspluginplatformresult">MdnsPluginPlatformResult</a>&gt;</code>
+
+--------------------
+
+
 ### startBroadcast(...)
 
 ```typescript
@@ -151,6 +121,16 @@ Discover services of a given type and optionally filter by instance name.
 ### Interfaces
 
 
+#### MdnsPluginPlatformResult
+
+Result of getPluginPlatform(). Useful for validating that calls are routed
+through the expected platform bridge.
+
+| Prop           | Type                                                              | Description                                        |
+| -------------- | ----------------------------------------------------------------- | -------------------------------------------------- |
+| **`platform`** | <code><a href="#mdnspluginplatform">MdnsPluginPlatform</a></code> | Platform implementation that produced this result. |
+
+
 #### MdnsBroadcastResult
 
 Result of startBroadcast(). Indicates whether advertising is active
@@ -231,6 +211,13 @@ Options for Bonjour/mDNS discovery.
 ### Type Aliases
 
 
+#### MdnsPluginPlatform
+
+Runtime implementation that handled a plugin call.
+
+<code>'ios' | 'android' | 'electron' | 'web'</code>
+
+
 #### MdnsTxt
 
 Key–value map for TXT records of a Bonjour/mDNS service.

package/android/build.gradle

@@ -11,7 +11,7 @@ buildscript {
         mavenCentral()
     }
     dependencies {
-        classpath 'com.android.tools.build:gradle:8.7.2'
+        classpath 'com.android.tools.build:gradle:8.13.2'
         classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:1.9.24"
     }
 }
@@ -20,23 +20,23 @@ apply plugin: 'com.android.library'
 apply plugin: 'org.jetbrains.kotlin.android'
 
 android {
-    namespace "com.devioarts.capacitor.mdns"
-    compileSdk project.hasProperty('compileSdkVersion') ? rootProject.ext.compileSdkVersion : 35
+    namespace = "com.devioarts.capacitor.mdns"
+    compileSdk = project.hasProperty('compileSdkVersion') ? rootProject.ext.compileSdkVersion : 36
     defaultConfig {
-        minSdkVersion project.hasProperty('minSdkVersion') ? rootProject.ext.minSdkVersion : 23
-        targetSdkVersion project.hasProperty('targetSdkVersion') ? rootProject.ext.targetSdkVersion : 35
-        versionCode 1
-        versionName "1.0"
-        testInstrumentationRunner "androidx.test.runner.AndroidJUnitRunner"
+        minSdk = project.hasProperty('minSdkVersion') ? rootProject.ext.minSdkVersion : 23
+        targetSdk = project.hasProperty('targetSdkVersion') ? rootProject.ext.targetSdkVersion : 36
+        versionCode = 1
+        versionName = "1.0"
+        testInstrumentationRunner = "androidx.test.runner.AndroidJUnitRunner"
     }
     buildTypes {
         release {
-            minifyEnabled false
+            minifyEnabled = false
             proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-rules.pro'
         }
     }
-    lintOptions {
-        abortOnError false
+    lint {
+        abortOnError = false
     }
     compileOptions {
         sourceCompatibility JavaVersion.VERSION_21

package/android/src/main/AndroidManifest.xml

@@ -1,2 +1,4 @@
 <manifest xmlns:android="http://schemas.android.com/apk/res/android">
+    <uses-permission android:name="android.permission.INTERNET" />
+    <uses-permission android:name="android.permission.CHANGE_WIFI_MULTICAST_STATE" />
 </manifest>

package/android/src/main/java/com/devioarts/capacitor/mdns/mDNS.kt

@@ -4,9 +4,13 @@ package com.devioarts.capacitor.mdns
 import android.content.Context
 import android.net.nsd.NsdManager
 import android.net.nsd.NsdServiceInfo
+import android.os.Build
 import android.os.Handler
 import android.os.Looper
 import kotlinx.coroutines.*
+import kotlinx.coroutines.sync.Mutex
+import kotlinx.coroutines.sync.withLock
+import java.util.concurrent.Executor
 import java.util.concurrent.atomic.AtomicReference
 
 /**
@@ -29,27 +33,42 @@ class mDNS(
     context: Context,
     private val externalScope: CoroutineScope? = null
 ) {
+    private companion object {
+        const val PUBLISH_TIMEOUT_MS = 5000L
+    }
+
     /** Normalized service representation returned to the bridge. */
     data class MdnsService(
         val name: String,
         val type: String,
-        val host: String?, // numeric address (v4/v6) or null if resolve fails
+        val hosts: List<String>, // numeric addresses (v4/v6)
         val port: Int
     )
 
+    private class RegistrationSession(
+        val listener: NsdManager.RegistrationListener,
+        val timeoutJob: Job,
+        val onSuccess: (String) -> Unit,
+        val onError: (Throwable) -> Unit
+    ) {
+        var completed = false
+    }
+
     /** NSD system service. */
     private val nsd: NsdManager =
         context.getSystemService(Context.NSD_SERVICE) as NsdManager
 
     /** Keep strong references to listeners so they outlive registration/discovery. */
-    private val regListenerRef = AtomicReference<NsdManager.RegistrationListener?>(null)
+    private var activeRegistration: RegistrationSession? = null
     private val discListenerRef = AtomicReference<NsdManager.DiscoveryListener?>(null)
 
     /** Optional external scope (from plugin); otherwise create our own on Main. */
     private val scope = externalScope ?: CoroutineScope(SupervisorJob() + Dispatchers.Main.immediate)
+    private val discoverMutex = Mutex()
 
     /** Main looper utilities for non-suspending entry points. */
     private val mainHandler = Handler(Looper.getMainLooper())
+    private val mainExecutor = Executor { command -> mainHandler.post(command) }
     private inline fun runOnMain(crossinline block: () -> Unit) {
         if (Looper.myLooper() === Looper.getMainLooper()) block() else mainHandler.post { block() }
     }
@@ -70,29 +89,58 @@ class mDNS(
         onSuccess: (String) -> Unit,
         onError: (Throwable) -> Unit
     ) {
-        require(port > 0) { "Port must be > 0" }
+        require(port in 1..65535) { "Port must be between 1 and 65535" }
         val type = if (typeRaw.endsWith(".")) typeRaw else "$typeRaw."
 
         runOnMain {
-            // Ensure a clean state before registering again.
-            regListenerRef.getAndSet(null)?.let { safeUnregister(it) }
+            try {
+                // Restarting while publish is pending must complete the old JS promise.
+                stopActiveRegistration("Replaced by a new broadcast request")
 
-            val info = NsdServiceInfo().apply {
-                serviceType = type
-                serviceName = name
-                setPort(port)
-            }
+                val info = NsdServiceInfo().apply {
+                    serviceType = type
+                    serviceName = name
+                    setPort(port)
+                }
 
-            val listener = object : NsdManager.RegistrationListener {
-                override fun onServiceRegistered(nsi: NsdServiceInfo) = onSuccess(nsi.serviceName)
-                override fun onRegistrationFailed(nsi: NsdServiceInfo, errorCode: Int) =
-                    onError(IllegalStateException("Registration failed: $errorCode"))
-                override fun onServiceUnregistered(nsi: NsdServiceInfo) { /* no-op */ }
-                override fun onUnregistrationFailed(nsi: NsdServiceInfo, errorCode: Int) { /* no-op */ }
-            }
+                lateinit var session: RegistrationSession
+                val listener = object : NsdManager.RegistrationListener {
+                    override fun onServiceRegistered(nsi: NsdServiceInfo) =
+                        completeRegistrationSuccess(session, nsi.serviceName)
+
+                    override fun onRegistrationFailed(nsi: NsdServiceInfo, errorCode: Int) =
+                        completeRegistrationError(
+                            session,
+                            IllegalStateException("Registration failed: $errorCode"),
+                            clearActive = true
+                        )
+
+                    override fun onServiceUnregistered(nsi: NsdServiceInfo) { /* no-op */ }
+                    override fun onUnregistrationFailed(nsi: NsdServiceInfo, errorCode: Int) { /* no-op */ }
+                }
 
-            regListenerRef.set(listener)
-            nsd.registerService(info, NsdManager.PROTOCOL_DNS_SD, listener)
+                val timeoutJob = scope.launch {
+                    delay(PUBLISH_TIMEOUT_MS)
+                    runOnMain {
+                        completeRegistrationError(
+                            session,
+                            IllegalStateException("Timed out waiting for service publish after ${PUBLISH_TIMEOUT_MS}ms"),
+                            clearActive = true,
+                            unregister = true
+                        )
+                    }
+                }
+
+                session = RegistrationSession(listener, timeoutJob, onSuccess, onError)
+                activeRegistration = session
+                try {
+                    nsd.registerService(info, NsdManager.PROTOCOL_DNS_SD, listener)
+                } catch (t: Throwable) {
+                    completeRegistrationError(session, t, clearActive = true)
+                }
+            } catch (t: Throwable) {
+                onError(t)
+            }
         }
     }
 
@@ -101,7 +149,7 @@ class mDNS(
      */
     fun stopBroadcast() {
         runOnMain {
-            regListenerRef.getAndSet(null)?.let { safeUnregister(it) }
+            stopActiveRegistration("Publish stopped before completion")
         }
     }
 
@@ -124,12 +172,13 @@ class mDNS(
         typeRaw: String,
         targetName: String? = null,
         timeoutMs: Int = 3000
-    ): List<MdnsService> = withContext(Dispatchers.Main.immediate) {
+    ): List<MdnsService> = discoverMutex.withLock { withContext(Dispatchers.Main.immediate) {
         val type = if (typeRaw.endsWith(".")) typeRaw else "$typeRaw."
 
         // Prepare state
         discListenerRef.getAndSet(null)?.let { safeStopDiscovery(it) }
         val found = mutableListOf<MdnsService>()
+        val serviceInfoCallbacks = mutableListOf<NsdManager.ServiceInfoCallback>()
         val result = CompletableDeferred<List<MdnsService>>()
 
         // Normalization for "(n)" suffix appended by the OS.
@@ -139,40 +188,93 @@ class mDNS(
             val t = normalize(targetName ?: return true) // if no target, accept all
             return (c == t) || c.startsWith(t)
         }
+        fun upsert(item: MdnsService) {
+            val index = found.indexOfFirst { it.name == item.name && it.type == item.type && it.port == item.port }
+            if (index >= 0) found[index] = item else found.add(item)
+        }
+        fun unregisterServiceInfoCallbacks() {
+            if (Build.VERSION.SDK_INT < Build.VERSION_CODES.UPSIDE_DOWN_CAKE) return
+            serviceInfoCallbacks.toList().forEach { safeUnregisterServiceInfoCallback(it) }
+            serviceInfoCallbacks.clear()
+        }
+        fun completeWithCurrentResults(discoveryListener: NsdManager.DiscoveryListener) {
+            unregisterServiceInfoCallbacks()
+            safeStopDiscovery(discoveryListener)
+            discListenerRef.compareAndSet(discoveryListener, null)
+            if (!result.isCompleted) result.complete(found.toList())
+        }
+        fun completeWithError(discoveryListener: NsdManager.DiscoveryListener, error: Throwable) {
+            unregisterServiceInfoCallbacks()
+            safeStopDiscovery(discoveryListener)
+            discListenerRef.compareAndSet(discoveryListener, null)
+            if (!result.isCompleted) result.completeExceptionally(error)
+        }
+
+        @Suppress("DEPRECATION")
+        fun resolveLegacy(si: NsdServiceInfo, discoveryListener: NsdManager.DiscoveryListener) {
+            try {
+                nsd.resolveService(si, object : NsdManager.ResolveListener {
+                    override fun onResolveFailed(s: NsdServiceInfo, errorCode: Int) { /* ignore */ }
+
+                    override fun onServiceResolved(s: NsdServiceInfo) {
+                        if (result.isCompleted) return
+                        upsert(toMdnsService(s))
+
+                        // Early-exit for exact/prefix target match.
+                        if (targetName != null && matchesTarget(s.serviceName)) {
+                            completeWithCurrentResults(discoveryListener)
+                        }
+                    }
+                })
+            } catch (_: Throwable) {
+                // Some Android releases throw when the NSD daemon is busy; ignore this candidate.
+            }
+        }
+
+        fun registerServiceInfoCallback(si: NsdServiceInfo, discoveryListener: NsdManager.DiscoveryListener) {
+            if (Build.VERSION.SDK_INT < Build.VERSION_CODES.UPSIDE_DOWN_CAKE) {
+                resolveLegacy(si, discoveryListener)
+                return
+            }
+
+            val callback = object : NsdManager.ServiceInfoCallback {
+                override fun onServiceInfoCallbackRegistrationFailed(errorCode: Int) { /* ignore */ }
+                override fun onServiceInfoCallbackUnregistered() { /* no-op */ }
+                override fun onServiceLost() { /* no-op */ }
+
+                override fun onServiceUpdated(serviceInfo: NsdServiceInfo) {
+                    if (result.isCompleted) return
+                    upsert(toMdnsService(serviceInfo))
+
+                    // Early-exit for exact/prefix target match.
+                    if (targetName != null && matchesTarget(serviceInfo.serviceName)) {
+                        completeWithCurrentResults(discoveryListener)
+                    }
+                }
+            }
+
+            serviceInfoCallbacks.add(callback)
+            try {
+                nsd.registerServiceInfoCallback(si, mainExecutor, callback)
+            } catch (_: Throwable) {
+                serviceInfoCallbacks.remove(callback)
+            }
+        }
 
         val listener = object : NsdManager.DiscoveryListener {
             override fun onStartDiscoveryFailed(serviceType: String, errorCode: Int) {
-                // Fail fast: stop discovery and complete with whatever we have (likely empty).
-                safeStopDiscovery(this)
-                if (!result.isCompleted) result.complete(found.toList())
+                completeWithError(this, IllegalStateException("Discovery failed to start: $errorCode"))
             }
             override fun onStopDiscoveryFailed(serviceType: String, errorCode: Int) { /* no-op */ }
             override fun onDiscoveryStarted(serviceType: String) { /* no-op */ }
             override fun onDiscoveryStopped(serviceType: String) { /* no-op */ }
 
             override fun onServiceFound(si: NsdServiceInfo) {
+                if (result.isCompleted) return
                 if (targetName != null && !matchesTarget(si.serviceName)) return
 
                 val discoveryListener = this
-                nsd.resolveService(si, object : NsdManager.ResolveListener {
-                    override fun onResolveFailed(s: NsdServiceInfo, errorCode: Int) { /* ignore */ }
-
-                    override fun onServiceResolved(s: NsdServiceInfo) {
-                        val item = MdnsService(
-                            name = s.serviceName,
-                            type = s.serviceType,
-                            host = s.host?.hostAddress,
-                            port = s.port
-                        )
-                        found.add(item)
-
-                        // Early-exit for exact/prefix target match.
-                        if (targetName != null && matchesTarget(s.serviceName)) {
-                            safeStopDiscovery(discoveryListener)
-                            if (!result.isCompleted) result.complete(found.toList())
-                        }
-                    }
-                })
+                registerServiceInfoCallback(si, discoveryListener)
             }
 
             override fun onServiceLost(serviceInfo: NsdServiceInfo) { /* no-op */ }
@@ -180,12 +282,16 @@ class mDNS(
 
         // Start discovery and schedule timeout
         discListenerRef.set(listener)
-        nsd.discoverServices(type, NsdManager.PROTOCOL_DNS_SD, listener)
+        try {
+            nsd.discoverServices(type, NsdManager.PROTOCOL_DNS_SD, listener)
+        } catch (t: Throwable) {
+            discListenerRef.compareAndSet(listener, null)
+            throw t
+        }
 
         val timeoutJob = scope.launch {
-            delay(timeoutMs.toLong())
-            safeStopDiscovery(listener)
-            if (!result.isCompleted) result.complete(found.toList())
+            delay(timeoutMs.coerceAtLeast(0).toLong())
+            completeWithCurrentResults(listener)
         }
 
         try {
@@ -193,17 +299,20 @@ class mDNS(
         } finally {
             // Cleanup in all cases (early-exit or timeout)
             timeoutJob.cancel()
-            discListenerRef.getAndSet(null)?.let { safeStopDiscovery(it) }
+            unregisterServiceInfoCallbacks()
+            if (discListenerRef.compareAndSet(listener, null)) safeStopDiscovery(listener)
         }
-    }
+    } }
 
     /**
      * Close the manager and release any outstanding NSD listeners.
      * Safe to call multiple times; also invoked by the plugin's handleOnDestroy().
      */
     fun close() {
-        stopBroadcast()
-        discListenerRef.getAndSet(null)?.let { safeStopDiscovery(it) }
+        runOnMain {
+            stopActiveRegistration("mDNS manager closed before publish completed")
+            discListenerRef.getAndSet(null)?.let { safeStopDiscovery(it) }
+        }
         if (externalScope == null) scope.cancel()
     }
 
@@ -214,8 +323,65 @@ class mDNS(
         try { nsd.unregisterService(l) } catch (_: Throwable) {}
     }
 
+    private fun completeRegistrationSuccess(session: RegistrationSession, publishedName: String) {
+        if (session.completed) return
+        session.completed = true
+        session.timeoutJob.cancel()
+        session.onSuccess(publishedName)
+    }
+
+    private fun completeRegistrationError(
+        session: RegistrationSession,
+        error: Throwable,
+        clearActive: Boolean,
+        unregister: Boolean = false
+    ) {
+        if (session.completed) return
+        session.completed = true
+        session.timeoutJob.cancel()
+        if (unregister) safeUnregister(session.listener)
+        if (clearActive && activeRegistration === session) activeRegistration = null
+        session.onError(error)
+    }
+
+    private fun stopActiveRegistration(reason: String) {
+        val session = activeRegistration ?: return
+        activeRegistration = null
+        safeUnregister(session.listener)
+        if (!session.completed) {
+            completeRegistrationError(session, IllegalStateException(reason), clearActive = false)
+        } else {
+            session.timeoutJob.cancel()
+        }
+    }
+
     /** Best-effort stop discovery; NSD may throw if discovery is not active. */
     private fun safeStopDiscovery(l: NsdManager.DiscoveryListener) {
         try { nsd.stopServiceDiscovery(l) } catch (_: Throwable) {}
     }
+
+    /** Best-effort stop service info updates; NSD may throw if not registered. */
+    private fun safeUnregisterServiceInfoCallback(l: NsdManager.ServiceInfoCallback) {
+        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.UPSIDE_DOWN_CAKE) {
+            try { nsd.unregisterServiceInfoCallback(l) } catch (_: Throwable) {}
+        }
+    }
+
+    private fun toMdnsService(s: NsdServiceInfo): MdnsService =
+        MdnsService(
+            name = s.serviceName,
+            type = s.serviceType,
+            hosts = hostAddresses(s),
+            port = s.port
+        )
+
+    private fun hostAddresses(s: NsdServiceInfo): List<String> =
+        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.UPSIDE_DOWN_CAKE) {
+            s.hostAddresses.mapNotNull { it.hostAddress }
+        } else {
+            legacyHostAddress(s)?.let { listOf(it) } ?: emptyList()
+        }
+
+    @Suppress("DEPRECATION")
+    private fun legacyHostAddress(s: NsdServiceInfo): String? = s.host?.hostAddress
 }