@devioarts/capacitor-mdns 0.0.3 → 0.1.0

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/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

@@ -8,6 +8,8 @@ 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
 
@@ -31,6 +33,10 @@ 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,
@@ -39,16 +45,26 @@ class mDNS(
         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())
@@ -73,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 */ }
+                }
+
+                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
+                        )
+                    }
+                }
 
-            regListenerRef.set(listener)
-            nsd.registerService(info, NsdManager.PROTOCOL_DNS_SD, listener)
+                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)
+            }
         }
     }
 
@@ -104,7 +149,7 @@ class mDNS(
      */
     fun stopBroadcast() {
         runOnMain {
-            regListenerRef.getAndSet(null)?.let { safeUnregister(it) }
+            stopActiveRegistration("Publish stopped before completion")
         }
     }
 
@@ -127,7 +172,7 @@ 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
@@ -155,23 +200,35 @@ class mDNS(
         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) {
-            nsd.resolveService(si, object : NsdManager.ResolveListener {
-                override fun onResolveFailed(s: NsdServiceInfo, errorCode: Int) { /* ignore */ }
+            try {
+                nsd.resolveService(si, object : NsdManager.ResolveListener {
+                    override fun onResolveFailed(s: NsdServiceInfo, errorCode: Int) { /* ignore */ }
 
-                override fun onServiceResolved(s: NsdServiceInfo) {
-                    upsert(toMdnsService(s))
+                    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)
+                        // 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) {
@@ -186,6 +243,7 @@ class mDNS(
                 override fun onServiceLost() { /* no-op */ }
 
                 override fun onServiceUpdated(serviceInfo: NsdServiceInfo) {
+                    if (result.isCompleted) return
                     upsert(toMdnsService(serviceInfo))
 
                     // Early-exit for exact/prefix target match.
@@ -205,14 +263,14 @@ class mDNS(
 
         val listener = object : NsdManager.DiscoveryListener {
             override fun onStartDiscoveryFailed(serviceType: String, errorCode: Int) {
-                // Fail fast: stop discovery and complete with whatever we have (likely empty).
-                completeWithCurrentResults(this)
+                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
@@ -224,10 +282,15 @@ 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())
+            delay(timeoutMs.coerceAtLeast(0).toLong())
             completeWithCurrentResults(listener)
         }
 
@@ -237,17 +300,19 @@ class mDNS(
             // Cleanup in all cases (early-exit or timeout)
             timeoutJob.cancel()
             unregisterServiceInfoCallbacks()
-            discListenerRef.getAndSet(null)?.let { safeStopDiscovery(it) }
+            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()
     }
 
@@ -258,6 +323,38 @@ 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) {}

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

@@ -52,6 +52,14 @@ class mDNSPlugin : Plugin() {
 
     private fun jnull(msg: String?): Any = msg ?: JSONObject.NULL
 
+    private fun normalizeType(raw: String?): String {
+        val type = raw?.trim()?.takeIf { it.isNotEmpty() } ?: "_http._tcp."
+        return if (type.endsWith(".")) type else "$type."
+    }
+
+    private fun normalizeName(raw: String?): String =
+        raw?.trim()?.takeIf { it.isNotEmpty() } ?: (context?.packageName ?: "DevIOArtsMDNS")
+
     private fun jsResultBroadcast(publishing: Boolean, name: String, error: Boolean, msg: String?): JSObject =
         JSObject().put("publishing", publishing)
             .put("name", name)
@@ -72,6 +80,11 @@ class mDNSPlugin : Plugin() {
 
     // ----------------------- API -----------------------
 
+    @PluginMethod
+    fun getPluginPlatform(call: PluginCall) {
+        call.resolve(JSObject().put("platform", "android"))
+    }
+
     /**
      * Start advertising a Bonjour/mDNS service.
      * - type: default "_http._tcp."
@@ -80,11 +93,11 @@ class mDNSPlugin : Plugin() {
      */
     @PluginMethod
     fun startBroadcast(call: PluginCall) {
-        val type = call.getString("type") ?: "_http._tcp."
-        val name = call.getString("name") ?: (context?.packageName ?: "DevIOArtsMDNS")
+        val type = normalizeType(call.getString("type"))
+        val name = normalizeName(call.getString("name"))
         val port = call.getInt("port") ?: 0
 
-        if (port <= 0) {
+        if (port !in 1..65535) {
             call.resolve(jsResultBroadcast(false, "", true, "Missing/invalid port"))
             return
         }
@@ -127,8 +140,8 @@ class mDNSPlugin : Plugin() {
      */
     @PluginMethod
     fun discover(call: PluginCall) {
-        val type = call.getString("type") ?: "_http._tcp."
-        val targetName = call.getString("name")
+        val type = normalizeType(call.getString("type"))
+        val targetName = call.getString("name")?.trim()?.takeIf { it.isNotEmpty() }
         val timeout = call.getInt("timeout") ?: 3000
 
         scope.launch {

package/dist/docs.json

@@ -13,6 +13,23 @@
       }
     ],
     "methods": [
+      {
+        "name": "getPluginPlatform",
+        "signature": "() => Promise<MdnsPluginPlatformResult>",
+        "parameters": [],
+        "returns": "Promise<MdnsPluginPlatformResult>",
+        "tags": [
+          {
+            "name": "returns",
+            "text": "Promise resolving to `MdnsPluginPlatformResult`."
+          }
+        ],
+        "docs": "Return the platform implementation currently serving plugin calls.",
+        "complexTypes": [
+          "MdnsPluginPlatformResult"
+        ],
+        "slug": "getpluginplatform"
+      },
       {
         "name": "startBroadcast",
         "signature": "(options: MdnsBroadcastOptions) => Promise<MdnsBroadcastResult>",
@@ -53,7 +70,7 @@
           },
           {
             "name": "remarks",
-            "text": "The `publishing` flag may be `false` after a successful stop."
+            "text": "The `publishing` flag may be `false` after a successful stop.\nStopping is idempotent and is safe to call even if publishing never fully started."
           }
         ],
         "docs": "Stop advertising the currently registered service (no-op if none).",
@@ -98,6 +115,28 @@
     "properties": []
   },
   "interfaces": [
+    {
+      "name": "MdnsPluginPlatformResult",
+      "slug": "mdnspluginplatformresult",
+      "docs": "Result of getPluginPlatform(). Useful for validating that calls are routed\nthrough the expected platform bridge.",
+      "tags": [
+        {
+          "name": "public"
+        }
+      ],
+      "methods": [],
+      "properties": [
+        {
+          "name": "platform",
+          "tags": [],
+          "docs": "Platform implementation that produced this result.",
+          "complexTypes": [
+            "MdnsPluginPlatform"
+          ],
+          "type": "MdnsPluginPlatform"
+        }
+      ]
+    },
     {
       "name": "MdnsBroadcastResult",
       "slug": "mdnsbroadcastresult",
@@ -145,7 +184,7 @@
       "docs": "Options for starting a Bonjour/mDNS advertisement.",
       "tags": [
         {
-          "text": "- The `type` **must** end with a dot (`.`). If omitted, the implementation appends it.\n- Instance `name` should be short and human-readable; the OS may append `\" (n)\"` to ensure uniqueness.\n- Android NSD does not expose TXT records to other apps; advertising TXT is supported on iOS.",
+          "text": "- The `type` **must** end with a dot (`.`). If omitted, the implementation appends it.\n- Instance `name` should be short and human-readable; the OS may append `\" (n)\"` to ensure uniqueness.\n- Android NSD does not expose TXT records to other apps; advertising TXT is supported on iOS.\n- Native implementations guard publish with a timeout and return `error: true` instead of\n  leaving the Promise pending when the OS does not deliver a publish callback.\n- Only one advertisement is active at a time. Starting a new one stops the previous one first.",
           "name": "remarks"
         },
         {
@@ -359,7 +398,7 @@
       "docs": "Options for Bonjour/mDNS discovery.",
       "tags": [
         {
-          "text": "- The `id` filter matches the normalized name and also accepts prefix matches\n  (to handle OS-added `\" (n)\"` suffixes).\n- When `useNW` is `true` on iOS, discovery uses `NWBrowser` for better P2P behavior.",
+          "text": "- The `name` filter matches the normalized name and also accepts prefix matches\n  (to handle OS-added `\" (n)\"` suffixes).\n- When `useNW` is `true` on iOS, discovery uses `NWBrowser` for better P2P behavior.\n- Discovery is timeboxed. Concurrent discovery requests are serialized or safely replace\n  the previous native session so old callbacks cannot complete a newer request.",
           "name": "remarks"
         },
         {
@@ -425,6 +464,29 @@
   ],
   "enums": [],
   "typeAliases": [
+    {
+      "name": "MdnsPluginPlatform",
+      "slug": "mdnspluginplatform",
+      "docs": "Runtime implementation that handled a plugin call.",
+      "types": [
+        {
+          "text": "'ios'",
+          "complexTypes": []
+        },
+        {
+          "text": "'android'",
+          "complexTypes": []
+        },
+        {
+          "text": "'electron'",
+          "complexTypes": []
+        },
+        {
+          "text": "'web'",
+          "complexTypes": []
+        }
+      ]
+    },
     {
       "name": "MdnsTxt",
       "slug": "mdnstxt",