@devioarts/capacitor-mdns 0.0.2

package/DevioartsCapacitorMdns.podspec

@@ -0,0 +1,17 @@
+require 'json'
+
+package = JSON.parse(File.read(File.join(__dir__, 'package.json')))
+
+Pod::Spec.new do |s|
+  s.name = 'DevioartsCapacitorMdns'
+  s.version = package['version']
+  s.summary = package['description']
+  s.license = package['license']
+  s.homepage = package['repository']['url']
+  s.author = package['author']
+  s.source = { :git => package['repository']['url'], :tag => s.version.to_s }
+  s.source_files = 'ios/Sources/**/*.{swift,h,m,c,cc,mm,cpp}'
+  s.ios.deployment_target = '14.0'
+  s.dependency 'Capacitor'
+  s.swift_version = '5.1'
+end

package/Package.swift

@@ -0,0 +1,28 @@
+// swift-tools-version: 5.9
+import PackageDescription
+
+let package = Package(
+    name: "DevioartsCapacitorMdns",
+    platforms: [.iOS(.v14)],
+    products: [
+        .library(
+            name: "DevioartsCapacitorMdns",
+            targets: ["mDNSPlugin"])
+    ],
+    dependencies: [
+        .package(url: "https://github.com/ionic-team/capacitor-swift-pm.git", from: "7.0.0")
+    ],
+    targets: [
+        .target(
+            name: "mDNSPlugin",
+            dependencies: [
+                .product(name: "Capacitor", package: "capacitor-swift-pm"),
+                .product(name: "Cordova", package: "capacitor-swift-pm")
+            ],
+            path: "ios/Sources/mDNSPlugin"),
+        .testTarget(
+            name: "mDNSPluginTests",
+            dependencies: ["mDNSPlugin"],
+            path: "ios/Tests/mDNSPluginTests")
+    ]
+)

package/README.md

@@ -0,0 +1,248 @@
+# @devioarts/capacitor-mdns
+
+mDNS plugin for Capacitor that supports Bonjour/mDNS advertisements and discovery.
+
+#### 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)
+
+## Install
+
+```bash
+npm install @devioarts/capacitor-mdns
+npx cap sync
+```
+
+## Android
+#### /android/app/src/main/AndroidManifest.xml
+```xml
+<uses-permission android:name="android.permission.INTERNET" />
+```
+
+## 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>
+```
+
+---
+## ElectronJS
+
+```shell
+npm i bonjour-service@1.3.0
+```
+
+> 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.
+
+#### /electron/main.ts
+
+```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
+```
+
+---
+## API
+
+<docgen-index>
+
+* [`startBroadcast(...)`](#startbroadcast)
+* [`stopBroadcast()`](#stopbroadcast)
+* [`discover(...)`](#discover)
+* [Interfaces](#interfaces)
+* [Type Aliases](#type-aliases)
+
+</docgen-index>
+
+<docgen-api>
+<!--Update the source file JSDoc comments and rerun docgen to update the docs below-->
+
+Public API surface of the Capacitor mDNS plugin.
+
+### startBroadcast(...)
+
+```typescript
+startBroadcast(options: MdnsBroadcastOptions) => Promise<MdnsBroadcastResult>
+```
+
+Start advertising a Bonjour/mDNS service.
+
+| Param         | Type                                                                  | Description                                                        |
+| ------------- | --------------------------------------------------------------------- | ------------------------------------------------------------------ |
+| **`options`** | <code><a href="#mdnsbroadcastoptions">MdnsBroadcastOptions</a></code> | - {@link <a href="#mdnsbroadcastoptions">MdnsBroadcastOptions</a>} |
+
+**Returns:** <code>Promise&lt;<a href="#mdnsbroadcastresult">MdnsBroadcastResult</a>&gt;</code>
+
+--------------------
+
+
+### stopBroadcast()
+
+```typescript
+stopBroadcast() => Promise<MdnsStopResult>
+```
+
+Stop advertising the currently registered service (no-op if none).
+
+**Returns:** <code>Promise&lt;<a href="#mdnsstopresult">MdnsStopResult</a>&gt;</code>
+
+--------------------
+
+
+### discover(...)
+
+```typescript
+discover(options?: MdnsDiscoverOptions | undefined) => Promise<MdnsDiscoverResult>
+```
+
+Discover services of a given type and optionally filter by instance name.
+
+| Param         | Type                                                                | Description                                                      |
+| ------------- | ------------------------------------------------------------------- | ---------------------------------------------------------------- |
+| **`options`** | <code><a href="#mdnsdiscoveroptions">MdnsDiscoverOptions</a></code> | - {@link <a href="#mdnsdiscoveroptions">MdnsDiscoverOptions</a>} |
+
+**Returns:** <code>Promise&lt;<a href="#mdnsdiscoverresult">MdnsDiscoverResult</a>&gt;</code>
+
+--------------------
+
+
+### Interfaces
+
+
+#### MdnsBroadcastResult
+
+Result of startBroadcast(). Indicates whether advertising is active
+and the final service name. On failure, `error` is true and `errorMessage`
+describes the issue.
+
+| Prop               | Type                        | Description                                                          |
+| ------------------ | --------------------------- | -------------------------------------------------------------------- |
+| **`error`**        | <code>boolean</code>        | True if the operation failed.                                        |
+| **`errorMessage`** | <code>string \| null</code> | Error description or null on success.                                |
+| **`name`**         | <code>string</code>         | Final (possibly uniquified) service instance name. Empty on failure. |
+| **`publishing`**   | <code>boolean</code>        | Whether the advertiser is currently active.                          |
+
+
+#### MdnsBroadcastOptions
+
+Options for starting a Bonjour/mDNS advertisement.
+
+| Prop       | Type                                        | Description                                   |
+| ---------- | ------------------------------------------- | --------------------------------------------- |
+| **`type`** | <code>string</code>                         | Service type (including the trailing dot).    |
+| **`name`** | <code>string</code>                         | Service instance name.                        |
+| **`port`** | <code>number</code>                         | TCP port to advertise.                        |
+| **`txt`**  | <code><a href="#mdnstxt">MdnsTxt</a></code> | Optional TXT key–value pairs (UTF-8 strings). |
+
+
+#### MdnsStopResult
+
+Result of stopBroadcast(). Indicates whether the advertiser is active
+after the call (normally false) and includes error information.
+
+| Prop               | Type                        | Description                                                         |
+| ------------------ | --------------------------- | ------------------------------------------------------------------- |
+| **`error`**        | <code>boolean</code>        | True if an error occurred while stopping.                           |
+| **`errorMessage`** | <code>string \| null</code> | Error description or null on success.                               |
+| **`publishing`**   | <code>boolean</code>        | Whether the advertiser remains active (should be false on success). |
+
+
+#### MdnsDiscoverResult
+
+Result of discover(). Contains normalized services and error information.
+
+| Prop                | Type                        | Description                                                                    |
+| ------------------- | --------------------------- | ------------------------------------------------------------------------------ |
+| **`error`**         | <code>boolean</code>        | True if discovery encountered an error (partial results may still be present). |
+| **`errorMessage`**  | <code>string \| null</code> | Error description or null when no error occurred.                              |
+| **`servicesFound`** | <code>number</code>         | Convenience count equal to services.length.                                    |
+| **`services`**      | <code>MdnsService[]</code>  | Normalized list of discovered services.                                        |
+
+
+#### MdnsService
+
+Normalized description of a discovered Bonjour/mDNS service.
+Returned from {@link mDNSPlugin.discover}.
+
+| Prop         | Type                                        | Description                                                                               |
+| ------------ | ------------------------------------------- | ----------------------------------------------------------------------------------------- |
+| **`name`**   | <code>string</code>                         | Instance name of the service (may be uniqued by the OS, e.g. "My App (2)").               |
+| **`type`**   | <code>string</code>                         | Full service type including the trailing dot, e.g. `"_http._tcp."`.                       |
+| **`domain`** | <code>string</code>                         | Service domain; typically `"local."`.                                                     |
+| **`port`**   | <code>number</code>                         | TCP port the service advertises.                                                          |
+| **`hosts`**  | <code>string[]</code>                       | Resolved numeric IP addresses (IPv4/IPv6).                                                |
+| **`txt`**    | <code><a href="#mdnstxt">MdnsTxt</a></code> | TXT dictionary (key → value). Usually present on iOS; Android NSD does not populate this. |
+
+
+#### MdnsDiscoverOptions
+
+Options for Bonjour/mDNS discovery.
+
+| Prop          | Type                 | Description                                                      |
+| ------------- | -------------------- | ---------------------------------------------------------------- |
+| **`type`**    | <code>string</code>  | Service type (including the trailing dot).                       |
+| **`name`**    | <code>string</code>  | Optional instance name filter (prefix-safe).                     |
+| **`timeout`** | <code>number</code>  | Discovery timeout in milliseconds.                               |
+| **`useNW`**   | <code>boolean</code> | iOS-only hint to use `NWBrowser` instead of `NetServiceBrowser`. |
+
+
+### Type Aliases
+
+
+#### MdnsTxt
+
+Key–value map for TXT records of a Bonjour/mDNS service.
+Values are UTF-8 strings; binary payloads are not supported by this API.
+
+<code><a href="#record">Record</a>&lt;string, string&gt;</code>
+
+
+#### Record
+
+Construct a type with a set of properties K of type T
+
+<code>{
 [P in K]: T;
 }</code>
+
+</docgen-api>

package/android/build.gradle

@@ -0,0 +1,64 @@
+ext {
+    junitVersion = project.hasProperty('junitVersion') ? rootProject.ext.junitVersion : '4.13.2'
+    androidxAppCompatVersion = project.hasProperty('androidxAppCompatVersion') ? rootProject.ext.androidxAppCompatVersion : '1.7.0'
+    androidxJunitVersion = project.hasProperty('androidxJunitVersion') ? rootProject.ext.androidxJunitVersion : '1.2.1'
+    androidxEspressoCoreVersion = project.hasProperty('androidxEspressoCoreVersion') ? rootProject.ext.androidxEspressoCoreVersion : '3.6.1'
+}
+
+buildscript {
+    repositories {
+        google()
+        mavenCentral()
+    }
+    dependencies {
+        classpath 'com.android.tools.build:gradle:8.7.2'
+        classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:1.9.24"
+    }
+}
+
+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
+    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"
+    }
+    buildTypes {
+        release {
+            minifyEnabled false
+            proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-rules.pro'
+        }
+    }
+    lintOptions {
+        abortOnError false
+    }
+    compileOptions {
+        sourceCompatibility JavaVersion.VERSION_21
+        targetCompatibility JavaVersion.VERSION_21
+    }
+
+    kotlinOptions {
+        jvmTarget = '21'
+    }
+}
+
+repositories {
+    google()
+    mavenCentral()
+}
+
+
+dependencies {
+    implementation fileTree(dir: 'libs', include: ['*.jar'])
+    implementation project(':capacitor-android')
+    implementation "androidx.appcompat:appcompat:$androidxAppCompatVersion"
+    testImplementation "junit:junit:$junitVersion"
+    androidTestImplementation "androidx.test.ext:junit:$androidxJunitVersion"
+    androidTestImplementation "androidx.test.espresso:espresso-core:$androidxEspressoCoreVersion"
+}

package/android/src/main/AndroidManifest.xml

@@ -0,0 +1,2 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+</manifest>

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

@@ -0,0 +1,221 @@
+package com.devioarts.capacitor.mdns
+// English-only code and comments.
+
+import android.content.Context
+import android.net.nsd.NsdManager
+import android.net.nsd.NsdServiceInfo
+import android.os.Handler
+import android.os.Looper
+import kotlinx.coroutines.*
+import java.util.concurrent.atomic.AtomicReference
+
+/**
+ * Thin Android NSD (Bonjour/mDNS) wrapper used by the Capacitor bridge.
+ *
+ * Responsibilities:
+ * - Register/unregister (advertise/stop) a single service.
+ * - Discover services of a given type and resolve them to host/port.
+ * - Optional exact-or-prefix name filter (iOS-like behavior, handles " (n)" suffix).
+ * - Timebox discovery; early-exit when the target match is resolved.
+ *
+ * Threading:
+ * - All public APIs are main-thread safe. Calls hop to the main looper internally,
+ *   since NSD APIs deliver callbacks on the main thread and expect a looper.
+ *
+ * Platform notes:
+ * - Android NSD has no public API for TXT records.
+ */
+class mDNS(
+    context: Context,
+    private val externalScope: CoroutineScope? = null
+) {
+    /** 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 port: Int
+    )
+
+    /** 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 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)
+
+    /** Main looper utilities for non-suspending entry points. */
+    private val mainHandler = Handler(Looper.getMainLooper())
+    private inline fun runOnMain(crossinline block: () -> Unit) {
+        if (Looper.myLooper() === Looper.getMainLooper()) block() else mainHandler.post { block() }
+    }
+
+    /**
+     * Start advertising a service. If already registered, the previous one is unregistered first.
+     *
+     * @param typeRaw Service type; trailing dot appended if missing (e.g., "_http._tcp.")
+     * @param name    Instance name; OS may append " (n)" to ensure uniqueness.
+     * @param port    TCP port (> 0).
+     * @param onSuccess Called with the (potentially uniquified) registered name.
+     * @param onError   Called on registration failure.
+     */
+    fun broadcast(
+        typeRaw: String,
+        name: String,
+        port: Int,
+        onSuccess: (String) -> Unit,
+        onError: (Throwable) -> Unit
+    ) {
+        require(port > 0) { "Port must be > 0" }
+        val type = if (typeRaw.endsWith(".")) typeRaw else "$typeRaw."
+
+        runOnMain {
+            // Ensure a clean state before registering again.
+            regListenerRef.getAndSet(null)?.let { safeUnregister(it) }
+
+            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 */ }
+            }
+
+            regListenerRef.set(listener)
+            nsd.registerService(info, NsdManager.PROTOCOL_DNS_SD, listener)
+        }
+    }
+
+    /**
+     * Stop advertising the currently registered service (if any). Safe to call multiple times.
+     */
+    fun stopBroadcast() {
+        runOnMain {
+            regListenerRef.getAndSet(null)?.let { safeUnregister(it) }
+        }
+    }
+
+    /**
+     * Discover services, optionally filtering by instance name using a normalized exact-or-prefix match.
+     *
+     * Behavior:
+     * - Runs on the main dispatcher.
+     * - Resolves candidates to host/port.
+     * - If `targetName` is provided, compare using normalized names and accept exact OR prefix match.
+     * - Early-exits when a matching service is resolved (stops discovery immediately).
+     * - Otherwise returns what was found when `timeoutMs` elapses.
+     *
+     * @param typeRaw     Service type; trailing dot appended if missing.
+     * @param targetName  Optional instance name for normalized exact/prefix match.
+     * @param timeoutMs   Timebox for discovery+resolve.
+     * @return List of resolved services accumulated (or early-exit match).
+     */
+    suspend fun discover(
+        typeRaw: String,
+        targetName: String? = null,
+        timeoutMs: Int = 3000
+    ): List<MdnsService> = 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 result = CompletableDeferred<List<MdnsService>>()
+
+        // Normalization for "(n)" suffix appended by the OS.
+        fun normalize(s: String): String = s.replace(Regex(" \\(\\d+\\)\$"), "")
+        fun matchesTarget(candidate: String): Boolean {
+            val c = normalize(candidate)
+            val t = normalize(targetName ?: return true) // if no target, accept all
+            return (c == t) || c.startsWith(t)
+        }
+
+        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())
+            }
+            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 (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())
+                        }
+                    }
+                })
+            }
+
+            override fun onServiceLost(serviceInfo: NsdServiceInfo) { /* no-op */ }
+        }
+
+        // Start discovery and schedule timeout
+        discListenerRef.set(listener)
+        nsd.discoverServices(type, NsdManager.PROTOCOL_DNS_SD, listener)
+
+        val timeoutJob = scope.launch {
+            delay(timeoutMs.toLong())
+            safeStopDiscovery(listener)
+            if (!result.isCompleted) result.complete(found.toList())
+        }
+
+        try {
+            result.await()
+        } finally {
+            // Cleanup in all cases (early-exit or timeout)
+            timeoutJob.cancel()
+            discListenerRef.getAndSet(null)?.let { safeStopDiscovery(it) }
+        }
+    }
+
+    /**
+     * 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) }
+        if (externalScope == null) scope.cancel()
+    }
+
+    // ---- Internal helpers ----------------------------------------------------
+
+    /** Best-effort unregister; NSD may throw if already unregistered. */
+    private fun safeUnregister(l: NsdManager.RegistrationListener) {
+        try { nsd.unregisterService(l) } catch (_: Throwable) {}
+    }
+
+    /** Best-effort stop discovery; NSD may throw if discovery is not active. */
+    private fun safeStopDiscovery(l: NsdManager.DiscoveryListener) {
+        try { nsd.stopServiceDiscovery(l) } catch (_: Throwable) {}
+    }
+}