Address review: optional JNA, scoped nativeDnssd, drop dead tests.

Make JNA optional, catch LinkageError when it is absent, let callers force
JmDNS or pass InetAddress to scope DNS-SD interface/host, deprecate auto(),
and replace the non-running live IT with fuller TXT/JmDNS unit coverage.

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: kgoderis

CHANGES.md

@@ -1,8 +1,8 @@
 # HAP-Java 2.0.10
 * Add optional Mute characteristic to Doorbell service
 * Add pluggable `HomekitAdvertiser` with native DNS-SD / Bonjour implementation (`DnssdHomekitAdvertiser`) so macOS can advertise `_hap._tcp` without binding UDP 5353 [#212](https://github.com/hap-java/HAP-Java/issues/212) (see [docs/NATIVE_DNSSD.md](docs/NATIVE_DNSSD.md))
-* Extract shared HAP TXT helpers (`HapDnsTxt`)
-* Add optional runtime dependency on JNA (`net.java.dev.jna:jna`) for native `DNSServiceRegister` (macOS `libSystem` / Avahi `libdns_sd`); JmDNS path unchanged when native DNS-SD is not used
+* Extract shared HAP TXT helpers (`HapDnsTxt`) with stable key order; JmDNS and native advertisers publish the same property set
+* JNA (`net.java.dev.jna:jna`) is **optional** for `nativeDnssd()`; JmDNS-only consumers do not need it. Applications should choose `jmdns(...)` or `nativeDnssd(InetAddress)` explicitly (`auto(...)` is deprecated)
 
 # HAP-Java 2.0.9
 * Fix Set Duration and Remaining Duration characteristics to advertise format `uint32` instead of `int` [#202](https://github.com/hap-java/HAP-Java/issues/202)

README.md

@@ -28,19 +28,20 @@ read the [Javadoc](https://hap-java.github.io/HAP-Java/apidocs/index.html)
 Native DNS-SD / Bonjour (macOS)
 =========
 
-JmDNS binds UDP **5353**. On macOS that port is owned by `mDNSResponder`, so dedicated JmDNS advertising fails with “Address already in use” and Home never sees `_hap._tcp`.
+JmDNS binds UDP **5353**. On macOS that port is owned by `mDNSResponder`, so dedicated JmDNS advertising can fail with “Address already in use” and Home never sees `_hap._tcp`.
 
-This build adds a native advertiser that registers through Bonjour without binding 5353:
+This build adds a native advertiser that registers through Bonjour without binding 5353. Choose the advertiser explicitly in your application (e.g. openHAB); declare optional JNA when using the native path:
 
 ```java
 import io.github.hapjava.server.HomekitAdvertisers;
 import io.github.hapjava.server.impl.HomekitServer;
 
+// Scope native registration to the HAP bind address, or use jmdns(sharedJmDNS) to force JmDNS:
 HomekitServer server =
-    new HomekitServer(bindAddress, 9124, HomekitAdvertisers.nativeDnssd());
+    new HomekitServer(bindAddress, 9124, HomekitAdvertisers.nativeDnssd(bindAddress));
 ```
 
-Or `HomekitAdvertisers.auto(bindAddress)` to prefer native DNS-SD when available. Full details: [docs/NATIVE_DNSSD.md](docs/NATIVE_DNSSD.md).
+Full details: [docs/NATIVE_DNSSD.md](docs/NATIVE_DNSSD.md).
 
 Supported HomeKit Accessories
 =========

docs/NATIVE_DNSSD.md

@@ -10,7 +10,7 @@ Typical symptoms on macOS: empty `dns-sd -B _hap._tcp` results while `lsof -iUDP
 
 ## Solution
 
-This fork adds a pluggable **`HomekitAdvertiser`** and a native implementation **`DnssdHomekitAdvertiser`** that calls Apple’s DNS-SD API (`DNSServiceRegister`) via JNA:
+This library adds a pluggable **`HomekitAdvertiser`** and a native implementation **`DnssdHomekitAdvertiser`** that calls Apple’s DNS-SD API (`DNSServiceRegister`) via JNA:
 
 | Implementation | Class | Binds UDP 5353? | Typical platform |
 | --- | --- | --- | --- |
@@ -19,43 +19,58 @@ This fork adds a pluggable **`HomekitAdvertiser`** and a native implementation *
 
 TXT records (`sf`, `id`, `md`, `sh`, `c#`, `s#`, `ff`, `ci`, `pv`) are shared via `HapDnsTxt` so both advertisers publish the same HAP payload.
 
+**Policy belongs in the application** (e.g. openHAB): choose `jmdns(...)` or `nativeDnssd(...)` explicitly. Do not rely on HAP-Java to auto-pick.
+
 ## Quick start
 
+Declare the optional JNA dependency if you use the native advertiser (JmDNS-only consumers can omit it):
+
+```xml
+<dependency>
+  <groupId>net.java.dev.jna</groupId>
+  <artifactId>jna</artifactId>
+  <version>5.14.0</version>
+</dependency>
+```
+
 ```java
 import io.github.hapjava.server.HomekitAdvertisers;
 import io.github.hapjava.server.impl.HomekitServer;
 import java.net.InetAddress;
 
 InetAddress bind = InetAddress.getByName("192.168.0.6");
+
+// Prefer scoping native registration to the HAP bind address (interface + SRV host):
 HomekitServer server =
-    new HomekitServer(bind, 9124, HomekitAdvertisers.nativeDnssd());
+    new HomekitServer(bind, 9124, HomekitAdvertisers.nativeDnssd(bind));
 
-// or: prefer native when present, else JmDNS
-HomekitServer auto =
-    new HomekitServer(bind, 9124, HomekitAdvertisers.auto(bind));
+// Or share an existing JmDNS (e.g. openHAB's):
+// HomekitServer server =
+//     new HomekitServer(bind, 9124, HomekitAdvertisers.jmdns(sharedJmDNS));
 ```
 
-Check availability:
+Check whether the native library **loads** (does not prove registration will succeed on the LAN):
 
 ```java
 if (HomekitAdvertisers.isNativeDnssdSupported()) {
-  // safe to call nativeDnssd()
+  // safe to construct nativeDnssd(...)
 }
 ```
 
 Existing constructors that take only `InetAddress` / `JmDNS` keep the previous JmDNS behaviour (backward compatible).
 
-## Verifying on macOS
+## Verifying on macOS (manual)
 
-After starting a server with `HomekitAdvertisers.nativeDnssd()` (or `auto(...)`):
+There is no automated live IT in CI (ubuntu runners lack `libdns_sd` / Bonjour). After starting a server with `HomekitAdvertisers.nativeDnssd(bind)`:
 
 ```bash
 dns-sd -B _hap._tcp local.
+dns-sd -L "<instance name>" _hap._tcp local.
 # or
 dns-sd -Z _hap._tcp local.
 ```
 
-You should see the bridge/accessory instance. No Java process should be listening on UDP 5353 (`lsof -iUDP:5353` should only show `mDNSResponder`).
+You should see the bridge/accessory instance and HAP TXT keys. No Java process should be listening on UDP 5353 (`lsof -iUDP:5353` should only show `mDNSResponder`).
 
 ## API surface
 
@@ -73,11 +88,12 @@ setConfigurationIndex(int)
 
 | Factory | Behaviour |
 | --- | --- |
-| `jmdns(JmDNS)` | Wrap an existing JmDNS |
-| `jmdns(InetAddress)` | Create JmDNS on that address |
-| `nativeDnssd()` | Native Bonjour / dns_sd (throws if unsupported) |
-| `auto(InetAddress)` | Native if supported, else JmDNS |
-| `isNativeDnssdSupported()` | Probe without constructing |
+| `jmdns(JmDNS)` | Wrap an existing JmDNS (force JmDNS / share openHAB’s instance) |
+| `jmdns(InetAddress)` | Create dedicated JmDNS on that address |
+| `nativeDnssd()` | Native Bonjour on **all** interfaces (`interfaceIndex = 0`, default host) |
+| `nativeDnssd(InetAddress)` | Native Bonjour scoped to that address’s interface index + SRV host |
+| `isNativeDnssdSupported()` | Whether JNA + dns_sd **load** (not a live register probe) |
+| `auto(InetAddress)` | **Deprecated** — prefer an explicit `jmdns` / `nativeDnssd` choice |
 
 ### `HomekitServer` constructors
 
@@ -90,21 +106,20 @@ When an advertiser is supplied, `createBridge` / `createStandaloneAccessory` use
 
 ## Implementation notes
 
-* **JNA** loads `System` on macOS/Darwin and `dns_sd` elsewhere (Avahi Bonjour compatibility).
+* **JNA** is an **optional** dependency. It loads `System` on macOS/Darwin and `dns_sd` elsewhere (Avahi Bonjour compatibility). Missing JNA surfaces as `LinkageError` and `isNativeDnssdSupported()` returns `false`.
 * `DNSServiceRegister` receives the TCP port in **network byte order**.
-* TXT is RFC 6763 length-prefixed `key=value` bytes (`HapDnsTxt.encodeTxt`).
+* Default `nativeDnssd()` uses `interfaceIndex = 0` (all interfaces) and `host = null` (system hostname). Prefer `nativeDnssd(InetAddress)` when the HAP TCP listener is bound to one LAN address.
+* TXT is RFC 6763 length-prefixed `key=value` bytes (`HapDnsTxt.encodeTxt`). Key insertion order is stable (`LinkedHashMap`); RFC 6763 does not require a particular pair order.
 * A daemon thread runs `DNSServiceProcessResult` until `DNSServiceRefDeallocate` on `stop()` / re-register.
 * Re-registration (discoverability, MAC, `c#`) deallocates and registers again — same pattern as the JmDNS advertiser.
 
 ## Tests
 
 | Test | Purpose |
 | --- | --- |
-| `HapDnsTxtTest` | Required TXT keys + wire encoding |
-| `DnssdHomekitAdvertiserTest` | Mocked JNA register / re-register / stop / port endianness |
-| `JmdnsHomekitAdvertiserTest` | Existing JmDNS behaviour (unchanged) |
-| `HomekitAdvertisersTest` | Factory / support probe |
-| `DnssdLiveAdvertiserIT` | Real register+stop when native DNS-SD is present |
+| `HapDnsTxtTest` | Full TXT key set, stable order, wire encoding |
+| `DnssdHomekitAdvertiserTest` | Mocked JNA register / interface+host / re-register / stop / port endianness |
+| `JmdnsHomekitAdvertiserTest` | JmDNS register including full HAP property set |
 
 ```bash
 mvn test
@@ -114,10 +129,10 @@ mvn test
 
 | Symptom | Likely cause |
 | --- | --- |
-| `Address already in use` / “no suitable mDNS” | Still using JmDNS against mDNSResponder — switch to `nativeDnssd()` |
-| `UnsupportedOperationException: Native DNS-SD` | No `libSystem`/`libdns_sd` on this JVM/OS |
+| `Address already in use` / “no suitable mDNS” | Still using dedicated JmDNS against mDNSResponder — switch to `nativeDnssd(bind)` or share an existing JmDNS |
+| `UnsupportedOperationException: Native DNS-SD` | No JNA on classpath, or no `libSystem`/`libdns_sd` on this JVM/OS |
 | `DNSServiceRegister failed with error code …` | Bad name/type, permissions, or daemon unavailable — check Console / `mDNSResponder` |
-| Browse empty after register | Wrong interface, firewall, or advertiser stopped; confirm with `dns-sd -B _hap._tcp` |
+| Browse empty after register / too many interfaces | Prefer `nativeDnssd(localAddress)` instead of all-interfaces `nativeDnssd()` |
 
 ## License
 

pom.xml

@@ -145,11 +145,14 @@
 			<version>3.5.6</version>
 		</dependency>
 
-		<!-- Native Bonjour / DNS-SD (macOS libSystem, Linux libdns_sd) -->
+		<!-- Native Bonjour / DNS-SD (macOS libSystem, Linux libdns_sd). Optional:
+		     consumers that only use JmDNS need not pull JNA; nativeDnssd() users
+		     must declare JNA themselves (openHAB already embeds it). -->
 		<dependency>
 			<groupId>net.java.dev.jna</groupId>
 			<artifactId>jna</artifactId>
 			<version>5.14.0</version>
+			<optional>true</optional>
 		</dependency>
 
 		<dependency>

src/main/java/io/github/hapjava/server/HomekitAdvertisers.java

@@ -9,15 +9,18 @@
 /**
  * Factories for {@link HomekitAdvertiser} implementations.
  *
- * <p>Typical macOS usage:
+ * <p>Callers (e.g. openHAB) should choose the advertiser explicitly: use {@link #jmdns(JmDNS)} to
+ * share an existing JmDNS instance, {@link #jmdns(InetAddress)} for a dedicated JmDNS socket, or
+ * {@link #nativeDnssd()} / {@link #nativeDnssd(InetAddress)} for Bonjour without binding UDP 5353.
+ * Do not rely on HAP-Java to pick a policy automatically.
  *
  * <pre>{@code
- * HomekitServer server =
- *     new HomekitServer(InetAddress.getByName("192.168.0.6"), 9124, HomekitAdvertisers.nativeDnssd());
- * }</pre>
+ * // Force JmDNS (e.g. share openHAB's instance):
+ * HomekitAdvertiser adv = HomekitAdvertisers.jmdns(sharedJmDNS);
  *
- * That listens on HAP TCP without binding UDP 5353; Bonjour/mDNSResponder publishes {@code
- * _hap._tcp}.
+ * // Native DNS-SD limited to one LAN address / interface:
+ * HomekitAdvertiser adv = HomekitAdvertisers.nativeDnssd(InetAddress.getByName("192.168.0.6"));
+ * }</pre>
  *
  * @author Karel Goderis
  */
@@ -47,11 +50,14 @@ public static HomekitAdvertiser jmdns(InetAddress localAddress) throws IOExcepti
   }
 
   /**
-   * Native DNS-SD / Bonjour advertiser (macOS {@code mDNSResponder}, or Avahi's dns_sd compat
-   * layer). Does not bind UDP 5353. Requires the JNA runtime dependency.
+   * Native DNS-SD / Bonjour advertiser on <strong>all</strong> interfaces ({@code interfaceIndex =
+   * 0}, default host). Prefer {@link #nativeDnssd(InetAddress)} when the HAP TCP listener is bound
+   * to a single LAN address.
+   *
+   * <p>Requires the optional JNA dependency on the classpath.
    *
    * @return a native DNS-SD advertiser
-   * @throws UnsupportedOperationException if the native library cannot be loaded
+   * @throws UnsupportedOperationException if JNA or the native library cannot be loaded
    */
   public static HomekitAdvertiser nativeDnssd() {
     if (!DnssdHomekitAdvertiser.isSupported()) {
@@ -62,22 +68,49 @@ public static HomekitAdvertiser nativeDnssd() {
   }
 
   /**
-   * Prefer native DNS-SD when available (macOS); otherwise create a dedicated JmDNS instance on
-   * {@code localAddress}.
+   * Native DNS-SD / Bonjour advertiser scoped to {@code localAddress}: SRV host is that address and
+   * registration uses the matching network interface index when resolvable.
    *
-   * @param localAddress address used if falling back to JmDNS
-   * @return a native DNS-SD advertiser when supported, otherwise a JmDNS-backed advertiser
+   * @param localAddress LAN address the HAP TCP server listens on
+   * @return a native DNS-SD advertiser
+   * @throws UnsupportedOperationException if JNA or the native library cannot be loaded
+   */
+  public static HomekitAdvertiser nativeDnssd(InetAddress localAddress) {
+    if (!DnssdHomekitAdvertiser.isSupported()) {
+      throw new UnsupportedOperationException(
+          "Native DNS-SD (dns_sd / Bonjour) is not available on this platform/JVM");
+    }
+    return new DnssdHomekitAdvertiser(localAddress);
+  }
+
+  /**
+   * Convenience: prefer native DNS-SD when the library loads, otherwise JmDNS on {@code
+   * localAddress}.
+   *
+   * <p><strong>Applications should prefer an explicit {@link #jmdns(JmDNS)} / {@link
+   * #nativeDnssd(InetAddress)} choice</strong> (policy belongs in openHAB / the integrator). This
+   * helper only probes whether the native library <em>loads</em>; it does not verify that
+   * registration will succeed on the network.
+   *
+   * @param localAddress address used for native scoping or JmDNS fallback
+   * @return a native DNS-SD advertiser when the library loads, otherwise a JmDNS-backed advertiser
    * @throws IOException if native DNS-SD is unavailable and JmDNS cannot be created
+   * @deprecated Prefer {@link #jmdns(JmDNS)}, {@link #jmdns(InetAddress)}, or {@link
+   *     #nativeDnssd(InetAddress)} so the application chooses the advertiser.
    */
+  @Deprecated
   public static HomekitAdvertiser auto(InetAddress localAddress) throws IOException {
     if (DnssdHomekitAdvertiser.isSupported()) {
-      return new DnssdHomekitAdvertiser();
+      return new DnssdHomekitAdvertiser(localAddress);
     }
     return new JmdnsHomekitAdvertiser(localAddress);
   }
 
   /**
-   * Whether {@link #nativeDnssd()} can be used on this JVM/OS.
+   * Whether {@link #nativeDnssd()} can be constructed on this JVM/OS.
+   *
+   * <p>Only checks that JNA and the platform DNS-SD library <em>load</em>. It does not register a
+   * service or prove mDNS is reachable on the LAN.
    *
    * @return {@code true} if the platform DNS-SD library loaded successfully
    */