@devioarts/capacitor-mdns 0.0.3 → 0.2.0

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

@@ -16,13 +16,13 @@ import org.json.JSONObject
  * - Never reject for runtime errors; always resolve with { error, errorMessage }.
  *
  * Parameters (strict, no legacy):
- * - startBroadcast: { type?: string, name?: string, port: number, txt?: Record<string,string> }  // txt ignored by Android
+ * - startBroadcast: { type?: string, name?: string, port: number, txt?: Record<string,string> }
  * - stopBroadcast:  {}
  * - discover:       { type?: string, name?: string, timeout?: number }
  *
  * Return shapes:
  * - startBroadcast -> { publishing: boolean, name: string, error: boolean, errorMessage: string|null }
- * - stopBroadcast  -> { publishing: false, error: boolean, errorMessage: string|null }
+ * - stopBroadcast  -> { publishing: boolean, error: boolean, errorMessage: string|null }
  * - discover       -> {
  *       error: boolean, errorMessage: string|null,
  *       servicesFound: number,
@@ -41,8 +41,7 @@ class mDNSPlugin : Plugin() {
     }
 
     override fun handleOnDestroy() {
-        mdns.close()
-        scope.cancel()
+        mdns.close { scope.cancel() }
     }
 
     // ----------------------- Helpers -----------------------
@@ -58,8 +57,8 @@ class mDNSPlugin : Plugin() {
             .put("error", error)
             .put("errorMessage", jnull(msg))
 
-    private fun jsResultStop(error: Boolean, msg: String?): JSObject =
-        JSObject().put("publishing", false)
+    private fun jsResultStop(publishing: Boolean, error: Boolean, msg: String?): JSObject =
+        JSObject().put("publishing", publishing)
             .put("error", error)
             .put("errorMessage", jnull(msg))
 
@@ -70,39 +69,51 @@ class mDNSPlugin : Plugin() {
             .put("servicesFound", services.length())
             .put("services", services)
 
+    private fun serviceObject(s: mDNS.MdnsService): JSObject = JSObject().apply {
+        put("name", s.name)
+        put("type", s.type)
+        put("domain", "local.")
+        put("port", s.port)
+        put("hosts", JSONArray(s.hosts))
+        if (s.txt.isNotEmpty()) put("txt", JSObject().apply { s.txt.forEach { (k, v) -> put(k, v) } })
+    }
+
     // ----------------------- API -----------------------
 
+    @PluginMethod
+    fun getPluginPlatform(call: PluginCall) {
+        call.resolve(JSObject().put("platform", "android"))
+    }
+
     /**
      * Start advertising a Bonjour/mDNS service.
      * - type: default "_http._tcp."
-     * - name: default packageName
+     * - name: default DevIOArtsMDNS
      * - port: required (> 0)
      */
     @PluginMethod
     fun startBroadcast(call: PluginCall) {
-        val type = call.getString("type") ?: "_http._tcp."
-        val name = call.getString("name") ?: (context?.packageName ?: "DevIOArtsMDNS")
-        val port = call.getInt("port") ?: 0
-
-        if (port <= 0) {
-            call.resolve(jsResultBroadcast(false, "", true, "Missing/invalid port"))
-            return
-        }
-
-        try {
-            mdns.broadcast(
-                typeRaw = type,
-                name = name,
-                port = port,
-                onSuccess = { published ->
-                    call.resolve(jsResultBroadcast(true, published, false, null))
-                },
-                onError = { err ->
-                    call.resolve(jsResultBroadcast(false, "", true, toErrorMessage(err)))
-                }
-            )
-        } catch (t: Throwable) {
-            call.resolve(jsResultBroadcast(false, "", true, toErrorMessage(t)))
+        scope.launch {
+            try {
+                val type = MdnsValidation.type(MdnsOptions.string(call.data.opt("type"), "type"))
+                val name = MdnsValidation.name(MdnsOptions.string(call.data.opt("name"), "name")).ifEmpty { "DevIOArtsMDNS" }
+                val port = MdnsOptions.port(call.data.opt("port"))
+                val txt = MdnsOptions.txt(call.data.opt("txt"))
+                mdns.broadcast(
+                    typeRaw = type,
+                    name = name,
+                    port = port,
+                    txt = txt,
+                    onSuccess = { published ->
+                        call.resolve(jsResultBroadcast(true, published, false, null))
+                    },
+                    onError = { err ->
+                        call.resolve(jsResultBroadcast(mdns.isPublishing, "", true, toErrorMessage(err)))
+                    }
+                )
+            } catch (t: Throwable) {
+                call.resolve(jsResultBroadcast(mdns.isPublishing, "", true, toErrorMessage(t)))
+            }
         }
     }
 
@@ -112,10 +123,11 @@ class mDNSPlugin : Plugin() {
     @PluginMethod
     fun stopBroadcast(call: PluginCall) {
         try {
-            mdns.stopBroadcast()
-            call.resolve(jsResultStop(false, null))
+            mdns.stopBroadcast { publishing, error ->
+                call.resolve(jsResultStop(publishing, error != null, error?.let { toErrorMessage(it) }))
+            }
         } catch (t: Throwable) {
-            call.resolve(jsResultStop(true, toErrorMessage(t)))
+            call.resolve(jsResultStop(true, true, toErrorMessage(t)))
         }
     }
 
@@ -127,29 +139,53 @@ class mDNSPlugin : Plugin() {
      */
     @PluginMethod
     fun discover(call: PluginCall) {
-        val type = call.getString("type") ?: "_http._tcp."
-        val targetName = call.getString("name")
-        val timeout = call.getInt("timeout") ?: 3000
-
         scope.launch {
             try {
+                val type = MdnsValidation.type(MdnsOptions.string(call.data.opt("type"), "type"))
+                val targetName = MdnsValidation.name(MdnsOptions.string(call.data.opt("name"), "name")).takeIf { it.isNotEmpty() }
+                val timeout = MdnsOptions.timeout(call.data.opt("timeout"))
                 val list = mdns.discover(type, targetName, timeout)
-                val arr = JSONArray(list.map { s ->
-                    JSObject().apply {
-                        put("name", s.name)
-                        put("type", s.type)         // Android returns full type with dot
-                        put("domain", "local.")     // NSD is mDNS only
-                        val hosts = JSONArray()
-                        s.hosts.forEach { hosts.put(it) }
-                        put("hosts", hosts)
-                        put("port", s.port)
-                        // TXT not available via NSD -> omitted on Android
-                    }
-                })
+                val arr = JSONArray(list.map { serviceObject(it) })
                 call.resolve(jsResultDiscover(false, null, arr))
             } catch (t: Throwable) {
                 call.resolve(jsResultDiscover(true, toErrorMessage(t), JSONArray()))
             }
         }
     }
+
+    @PluginMethod
+    fun watchServices(call: PluginCall) {
+        val types = call.getArray("types")
+        val raw = if (types == null) emptyList() else (0 until types.length()).map { types.opt(it) }
+        if (raw.isEmpty() || raw.any { it !is String }) {
+            call.resolve(JSObject().put("error", true).put("errorMessage", "Expected a nonempty array of service types").put("watchersStarted", 0))
+            return
+        }
+        scope.launch {
+            try {
+                val started = mdns.watchServices(raw.map { it as String }, object : mDNS.WatchListener {
+                    override fun onServiceFound(service: mDNS.MdnsService) {
+                        notifyListeners("serviceFound", JSObject().put("service", serviceObject(service)))
+                    }
+                    override fun onServiceLost(service: mDNS.MdnsService) {
+                        notifyListeners("serviceLost", JSObject().put("service", serviceObject(service)))
+                    }
+                    override fun onError(type: String, message: String, watching: Boolean) {
+                        notifyListeners("watchError", JSObject().put("type", type).put("errorMessage", message).put("watching", watching))
+                    }
+                })
+                call.resolve(JSObject().put("error", false).put("errorMessage", JSONObject.NULL).put("watchersStarted", started))
+            } catch (t: Throwable) {
+                call.resolve(JSObject().put("error", true).put("errorMessage", toErrorMessage(t)).put("watchersStarted", 0))
+            }
+        }
+    }
+
+    @PluginMethod
+    fun stopWatching(call: PluginCall) {
+        scope.launch {
+            val error = mdns.stopWatching()
+            call.resolve(JSObject().put("watching", false).put("error", error != null).put("errorMessage", jnull(error?.message)))
+        }
+    }
 }

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).",
@@ -84,7 +101,7 @@
           },
           {
             "name": "remarks",
-            "text": "The result list is normalized across platforms. On Android, `txt` is typically absent."
+            "text": "The result list is normalized across platforms."
           }
         ],
         "docs": "Discover services of a given type and optionally filter by instance name.",
@@ -93,11 +110,122 @@
           "MdnsDiscoverOptions"
         ],
         "slug": "discover"
+      },
+      {
+        "name": "watchServices",
+        "signature": "(options: MdnsWatchOptions) => Promise<MdnsWatchResult>",
+        "parameters": [
+          {
+            "name": "options",
+            "docs": "",
+            "type": "MdnsWatchOptions"
+          }
+        ],
+        "returns": "Promise<MdnsWatchResult>",
+        "tags": [],
+        "docs": "Continuously watch several service types. A valid call replaces the previous watch.\nRegister listeners before starting. Each resolved service emits `serviceFound` once;\ndisappearance emits `serviceLost` with its last snapshot. No loss is emitted for an\nunresolved service. Watching and one-shot discovery can run together.\nThanks to Idrimi for contributing the original continuous discovery feature (PR #7).",
+        "complexTypes": [
+          "MdnsWatchResult",
+          "MdnsWatchOptions"
+        ],
+        "slug": "watchservices"
+      },
+      {
+        "name": "stopWatching",
+        "signature": "() => Promise<MdnsWatchStopResult>",
+        "parameters": [],
+        "returns": "Promise<MdnsWatchStopResult>",
+        "tags": [],
+        "docs": "Stop all watchers. No events from that watch are emitted after this resolves.",
+        "complexTypes": [
+          "MdnsWatchStopResult"
+        ],
+        "slug": "stopwatching"
+      },
+      {
+        "name": "addListener",
+        "signature": "(eventName: 'serviceFound' | 'serviceLost', handler: (event: MdnsServiceEvent) => void) => Promise<PluginListenerHandle>",
+        "parameters": [
+          {
+            "name": "eventName",
+            "docs": "",
+            "type": "'serviceFound' | 'serviceLost'"
+          },
+          {
+            "name": "handler",
+            "docs": "",
+            "type": "(event: MdnsServiceEvent) => void"
+          }
+        ],
+        "returns": "Promise<PluginListenerHandle>",
+        "tags": [],
+        "docs": "",
+        "complexTypes": [
+          "PluginListenerHandle",
+          "MdnsServiceEvent"
+        ],
+        "slug": "addlistenerservicefound--servicelost-"
+      },
+      {
+        "name": "addListener",
+        "signature": "(eventName: 'watchError', handler: (event: MdnsWatchErrorEvent) => void) => Promise<PluginListenerHandle>",
+        "parameters": [
+          {
+            "name": "eventName",
+            "docs": "",
+            "type": "'watchError'"
+          },
+          {
+            "name": "handler",
+            "docs": "",
+            "type": "(event: MdnsWatchErrorEvent) => void"
+          }
+        ],
+        "returns": "Promise<PluginListenerHandle>",
+        "tags": [],
+        "docs": "",
+        "complexTypes": [
+          "PluginListenerHandle",
+          "MdnsWatchErrorEvent"
+        ],
+        "slug": "addlistenerwatcherror-"
+      },
+      {
+        "name": "removeAllListeners",
+        "signature": "() => Promise<void>",
+        "parameters": [],
+        "returns": "Promise<void>",
+        "tags": [],
+        "docs": "",
+        "complexTypes": [],
+        "slug": "removealllisteners"
       }
     ],
     "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",
@@ -133,7 +261,7 @@
         {
           "name": "publishing",
           "tags": [],
-          "docs": "Whether the advertiser is currently active.",
+          "docs": "Whether an advertiser is active, or may still be active after failed cleanup.",
           "complexTypes": [],
           "type": "boolean"
         }
@@ -145,7 +273,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": "- Service types accept an optional trailing dot; results always include it.\n- Instance `name` should be short and human-readable; the OS may append `\" (n)\"` to ensure uniqueness.\n  Electron rejects a name conflict instead of renaming the service.\n- Advertising TXT is supported on iOS, Android and Electron. Invalid input preserves the active advertisement.\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"
         },
         {
@@ -173,9 +301,9 @@
         {
           "name": "name",
           "tags": [],
-          "docs": "Service instance name.",
+          "docs": "Service instance name (maximum 63 UTF-8 bytes). Defaults to `DevIOArtsMDNS`.",
           "complexTypes": [],
-          "type": "string"
+          "type": "string | undefined"
         },
         {
           "name": "port",
@@ -193,7 +321,7 @@
           "name": "txt",
           "tags": [
             {
-              "text": "May be ignored on Android due to platform limitations.",
+              "text": "Keys must be unique ignoring case, nonempty printable ASCII without `=`. Each `key=value` entry must fit in 255 UTF-8 bytes. The complete record is limited to 1300 bytes including length prefixes. Non-string values are rejected.",
               "name": "remarks"
             }
           ],
@@ -233,7 +361,7 @@
         {
           "name": "publishing",
           "tags": [],
-          "docs": "Whether the advertiser remains active (should be false on success).",
+          "docs": "False after confirmed stop; true when stopping failed and the advertiser may still be active.",
           "complexTypes": [],
           "type": "boolean"
         }
@@ -274,7 +402,7 @@
         {
           "name": "services",
           "tags": [],
-          "docs": "Normalized list of discovered services.",
+          "docs": "Resolved services with numeric addresses. Empty on error; partial results are discarded.",
           "complexTypes": [
             "MdnsService"
           ],
@@ -288,7 +416,7 @@
       "docs": "Normalized description of a discovered Bonjour/mDNS service.\nReturned from {@link mDNSPlugin.discover}.",
       "tags": [
         {
-          "text": "- `hosts` contains resolved IPv4/IPv6 numeric addresses (no DNS names).\n- iOS returns `txt` when present. Android (NSD) does not expose TXT records via public APIs,\n  so `txt` is usually omitted on Android.\n- `domain` is typically `\"local.\"`.",
+          "text": "- `hosts` contains resolved IPv4/IPv6 numeric addresses (no DNS names).\n- IPv4 addresses precede IPv6; order within each family follows discovery order.\n- Native IPv6 scope suffixes are preserved (`%<scope-id>` on iOS; the OS-provided scope on Android).\n  Electron may return link-local IPv6 without a scope; callers must not assume every address is reachable.\n- Resolved TXT records are returned when present.\n- `domain` is typically `\"local.\"`.",
           "name": "remarks"
         },
         {
@@ -321,7 +449,7 @@
         {
           "name": "port",
           "tags": [],
-          "docs": "TCP port the service advertises.",
+          "docs": "Port the service advertises.",
           "complexTypes": [],
           "type": "number"
         },
@@ -333,10 +461,17 @@
               "name": "example"
             }
           ],
-          "docs": "Resolved numeric IP addresses (IPv4/IPv6).",
+          "docs": "Resolved numeric IP addresses, IPv4 first, then IPv6 with any available scope suffix.",
           "complexTypes": [],
           "type": "string[]"
         },
+        {
+          "name": "hostname",
+          "tags": [],
+          "docs": "Host name when supplied by the platform, e.g. `\"my-device.local.\"`.",
+          "complexTypes": [],
+          "type": "string | undefined"
+        },
         {
           "name": "txt",
           "tags": [
@@ -345,7 +480,7 @@
               "name": "remarks"
             }
           ],
-          "docs": "TXT dictionary (key → value). Usually present on iOS; Android NSD does not populate this.",
+          "docs": "TXT dictionary (key → value).",
           "complexTypes": [
             "MdnsTxt"
           ],
@@ -359,7 +494,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- A valid new discovery replaces the previous request with an error on every platform.\n- Dots and hyphens are equivalent when matching names; returned names retain their advertised spelling.\n- Without a name filter, browsing continues for the entire timeout. With a filter it may finish once a matching IP address resolves.",
           "name": "remarks"
         },
         {
@@ -404,7 +539,7 @@
               "name": "defaultValue"
             }
           ],
-          "docs": "Discovery timeout in milliseconds.",
+          "docs": "Discovery timeout in milliseconds. Finite numbers only; fractions are truncated and the delay is clamped to 0–2147483647.",
           "complexTypes": [],
           "type": "number | undefined"
         },
@@ -421,10 +556,173 @@
           "type": "boolean | undefined"
         }
       ]
+    },
+    {
+      "name": "MdnsWatchResult",
+      "slug": "mdnswatchresult",
+      "docs": "Native browsers have been requested; later failures are reported through `watchError`.",
+      "tags": [],
+      "methods": [],
+      "properties": [
+        {
+          "name": "error",
+          "tags": [],
+          "docs": "",
+          "complexTypes": [],
+          "type": "boolean"
+        },
+        {
+          "name": "errorMessage",
+          "tags": [],
+          "docs": "",
+          "complexTypes": [],
+          "type": "string | null"
+        },
+        {
+          "name": "watchersStarted",
+          "tags": [],
+          "docs": "",
+          "complexTypes": [],
+          "type": "number"
+        }
+      ]
+    },
+    {
+      "name": "MdnsWatchOptions",
+      "slug": "mdnswatchoptions",
+      "docs": "Options for continuous discovery on iOS, Android and Electron.",
+      "tags": [],
+      "methods": [],
+      "properties": [
+        {
+          "name": "types",
+          "tags": [],
+          "docs": "Nonempty list of service types. Trailing dots are optional; duplicates are merged.",
+          "complexTypes": [],
+          "type": "string[]"
+        }
+      ]
+    },
+    {
+      "name": "MdnsWatchStopResult",
+      "slug": "mdnswatchstopresult",
+      "docs": "Stops watching independently of any active broadcast.",
+      "tags": [],
+      "methods": [],
+      "properties": [
+        {
+          "name": "error",
+          "tags": [],
+          "docs": "",
+          "complexTypes": [],
+          "type": "boolean"
+        },
+        {
+          "name": "errorMessage",
+          "tags": [],
+          "docs": "",
+          "complexTypes": [],
+          "type": "string | null"
+        },
+        {
+          "name": "watching",
+          "tags": [],
+          "docs": "",
+          "complexTypes": [],
+          "type": "boolean"
+        }
+      ]
+    },
+    {
+      "name": "PluginListenerHandle",
+      "slug": "pluginlistenerhandle",
+      "docs": "",
+      "tags": [],
+      "methods": [],
+      "properties": [
+        {
+          "name": "remove",
+          "tags": [],
+          "docs": "",
+          "complexTypes": [],
+          "type": "() => Promise<void>"
+        }
+      ]
+    },
+    {
+      "name": "MdnsServiceEvent",
+      "slug": "mdnsserviceevent",
+      "docs": "Both found and lost events contain a complete service snapshot, including `hosts`.",
+      "tags": [],
+      "methods": [],
+      "properties": [
+        {
+          "name": "service",
+          "tags": [],
+          "docs": "",
+          "complexTypes": [
+            "MdnsService"
+          ],
+          "type": "MdnsService"
+        }
+      ]
+    },
+    {
+      "name": "MdnsWatchErrorEvent",
+      "slug": "mdnswatcherrorevent",
+      "docs": "Browser failures stop the watch; exhausted service resolution retries leave it running.",
+      "tags": [],
+      "methods": [],
+      "properties": [
+        {
+          "name": "type",
+          "tags": [],
+          "docs": "",
+          "complexTypes": [],
+          "type": "string"
+        },
+        {
+          "name": "errorMessage",
+          "tags": [],
+          "docs": "",
+          "complexTypes": [],
+          "type": "string"
+        },
+        {
+          "name": "watching",
+          "tags": [],
+          "docs": "",
+          "complexTypes": [],
+          "type": "boolean"
+        }
+      ]
     }
   ],
   "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",