react-native-zeroconf 0.13.8 → 0.15.0

package/NOTICE

@@ -0,0 +1,49 @@
+react-native-zeroconf
+Copyright (c) 2016 Balthazar Gronon
+
+This project is licensed under the MIT License.
+
+================================================================================
+
+This project includes code from RxDNSSD, which is licensed under the
+Apache License, Version 2.0.
+
+RxDNSSD
+https://github.com/discord/RxDNSSD (Discord's fork)
+https://github.com/andriydruk/RxDNSSD (Original)
+
+Copyright (C) 2022 Andriy Druk
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+
+The following files are derived from RxDNSSD:
+
+android/src/main/jni/*
+  - Native mDNS/DNS-SD implementation (mDNSResponder)
+  - JNI bindings for Android
+
+android/src/main/java/com/github/druk/dnssd/*
+  - Java DNS-SD API classes
+
+android/src/main/java/com/github/druk/rx2dnssd/*
+  - RxJava2 reactive wrappers for DNS-SD
+
+================================================================================
+
+mDNSResponder
+The native code in android/src/main/jni/mdnsresponder/ is derived from
+Apple's mDNSResponder project.
+
+Copyright (c) 2002-2020 Apple Inc. All rights reserved.
+
+Licensed under the Apache License, Version 2.0.

package/README.md

@@ -1,126 +1,550 @@
 # react-native-zeroconf
 
-> Basic Zeroconf implementation for React-native
+> Zeroconf (Bonjour/mDNS) implementation for React Native
 
-Get running services advertizing themselves using Zeroconf implementations like Avahi, Bonjour or NSD.
+Discover and publish network services using Zeroconf protocols (Bonjour, Avahi, mDNS).
 
-### Install
+## Features
 
-    yarn add react-native-zeroconf
-    # for react-native < 0.60 only (all platforms):
-    react-native link
-    # for ios (when using CocoaPods): 
-    (cd ios && pod install)
-    # for macOS (when using CocoaPods):
-    (cd macos && pod install)
+- **Service Discovery**: Find services advertised on your local network
+- **Service Publishing**: Advertise your own services
+- **Cross-Platform**: Works on iOS and Android
+- **Dual Android Implementation**: Choose between NSD (Android native) or DNSSD (embedded mDNSResponder)
+- **Android 15+ Compatible**: Includes 16KB page size alignment (Google Play requirement starting November 1, 2025)
+- **TypeScript**: Type definitions included
 
-You can look at [the wiki](https://github.com/Apercu/react-native-zeroconf/wiki) if you prefer a manual install.
+## Installation
 
-TXT records will be available on iOS and Android >= 7.
+```bash
+# Install using yarn
+yarn add react-native-zeroconf
 
-For Android please ensure your manifest is requesting all necessary permissions.
+# For React Native < 0.60 only (all platforms):
+react-native link
+
+# For iOS (using CocoaPods):
+cd ios && pod install
+
+# For macOS (using CocoaPods):
+cd macos && pod install
+```
+
+For manual installation, see the [wiki](https://github.com/balthazar/react-native-zeroconf/wiki).
+
+## Setup
+
+### Android Permissions
+
+The library declares the following permissions in its own manifest, so they are merged into your app automatically:
 
 ```xml
+<uses-permission android:name="android.permission.INTERNET" />
 <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
 <uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
 <uses-permission android:name="android.permission.CHANGE_WIFI_MULTICAST_STATE" />
 ```
 
-### IOS 14 Permissions
-IOS 14 requires you to specify the services you want to scan for and a description for what you're using them.
+### iOS 14+ Permissions
+
+iOS 14+ requires you to declare the services you want to discover in your `Info.plist`:
 
-In your `info.plist` add the following strings:
 ```xml
 <key>NSBonjourServices</key>
-	<array>
-		<string>my_service._tcp.</string>
-		<string>my_other_service._tcp.</string>
-	</array>
+<array>
+    <string>_http._tcp.</string>
+    <string>_printer._tcp.</string>
+    <!-- Add other service types you need -->
+</array>
 <key>NSLocalNetworkUsageDescription</key>
-<string>Describe why you want to use local network discovery here</string>
+<string>This app uses the local network to discover printers and other devices.</string>
+```
+
+## Quick Start
+
+```javascript
+import Zeroconf from 'react-native-zeroconf'
+
+const zeroconf = new Zeroconf()
+
+// Listen for resolved services
+zeroconf.on('resolved', service => {
+  console.log('Found service:', service.name)
+  console.log('IP addresses:', service.addresses)
+  console.log('Port:', service.port)
+})
+
+// Start scanning for HTTP services
+zeroconf.scan('http', 'tcp', 'local.')
+
+// Stop scanning after 10 seconds
+setTimeout(() => {
+  zeroconf.stop()
+  console.log('All services:', zeroconf.getServices())
+}, 10000)
 ```
 
-### Example
+## TypeScript
+
+Type definitions ship with the package, so `@types/react-native-zeroconf` is no longer needed (uninstall it to avoid conflicting types). Event listeners are typed by event name:
+
+```typescript
+import Zeroconf, { ImplType, Service } from 'react-native-zeroconf'
 
-Take a look at the [example folder](./example). Install the dependencies, run `node server.js` and launch the project.
+const zeroconf = new Zeroconf()
+
+zeroconf.on('resolved', (service: Service) => {
+  console.log(service.name, service.addresses, service.txt)
+})
+zeroconf.on('remove', name => console.log(`${name} left`))
+
+zeroconf.scan('http', 'tcp', 'local.', ImplType.DNSSD)
+```
+
+## API Reference
 
-### API
+### Constructor
 
 ```javascript
 import Zeroconf from 'react-native-zeroconf'
 const zeroconf = new Zeroconf()
 ```
 
-##### Methods
+### Methods
+
+#### `scan(type, protocol, domain, implType)`
+
+Start scanning for services on the network.
+
+| Parameter  | Type   | Default    | Description                                                                                        |
+| ---------- | ------ | ---------- | -------------------------------------------------------------------------------------------------- |
+| `type`     | string | `'http'`   | Service type (e.g., `'http'`, `'printer'`, `'ssh'`, `'pdl-datastream'`)                            |
+| `protocol` | string | `'tcp'`    | Protocol (`'tcp'` or `'udp'`)                                                                      |
+| `domain`   | string | `'local.'` | Domain to search (typically `'local.'`)                                                            |
+| `implType` | string | `'NSD'`    | **Android only**: `'NSD'` or `'DNSSD'` (see [Implementation Types](#android-implementation-types)) |
+
+```javascript
+// Scan for HTTP services using default NSD implementation
+zeroconf.scan('http', 'tcp', 'local.')
+
+// Scan for printers using DNSSD (recommended for better compatibility)
+zeroconf.scan('pdl-datastream', 'tcp', 'local.', 'DNSSD')
+```
+
+#### `stop(implType)`
 
-###### `scan(type = 'http', protocol = 'tcp', domain = 'local.')` Start the zeroconf scan
+Stop the current scan.
 
-This will initialize the scan from the `Zeroconf` instance. Will stop another scan if any is running.
+| Parameter  | Type   | Default | Description                                    |
+| ---------- | ------ | ------- | ---------------------------------------------- |
+| `implType` | string | last scan's | **Android only**: Which implementation to stop. Defaults to the one used by the last `scan()` |
 
-###### `stop()` Stop the scan
+```javascript
+zeroconf.stop()
+```
+
+#### `getServices()`
 
-If any scan is running, stop it. Otherwise do nothing.
+Returns all currently discovered services.
 
-###### `getServices()` Returns resolved services
+```javascript
+const services = zeroconf.getServices()
+// Returns: { 'ServiceName': { name, host, port, addresses, txt, fullName }, ... }
+```
 
-Will return all names of services that have been resolved.
+#### `publishService(type, protocol, domain, name, port, txt, implType)`
 
-###### `removeDeviceListeners()` Remove listeners
+Publish a service on the network.
 
-Allow you to clean the listeners, avoiding potential memory leaks ([#33](https://github.com/Apercu/react-native-zeroconf/issues/33)).
+| Parameter  | Type   | Default    | Description                            |
+| ---------- | ------ | ---------- | -------------------------------------- |
+| `type`     | string | required   | Service type (e.g., `'http'`)          |
+| `protocol` | string | required   | Protocol (`'tcp'` or `'udp'`)          |
+| `domain`   | string | `'local.'` | Domain                                 |
+| `name`     | string | required   | Service name (should be unique)        |
+| `port`     | number | required   | Port number                            |
+| `txt`      | object | `{}`       | TXT record key-value pairs             |
+| `implType` | string | `'NSD'`    | **Android only**: `'NSD'` or `'DNSSD'` |
 
-###### `addDeviceListeners()` Add listeners
+```javascript
+zeroconf.publishService('http', 'tcp', 'local.', 'MyWebServer', 8080, {
+  path: '/api',
+  version: '1.0',
+})
+```
 
-If you cleaned the listeners and need to get them back on.
+#### `unpublishService(name, implType)`
 
-###### `publishService(type, protocol, domain, name, port, txt)` Publish a service
+Remove a published service.
 
-This adds a service for the current device to the discoverable services on the network.
+| Parameter  | Type   | Default  | Description                            |
+| ---------- | ------ | -------- | -------------------------------------- |
+| `name`     | string | required | Name of the service to unpublish       |
+| `implType` | string | publish's | **Android only**: Which implementation. Defaults to the one the service was published with |
 
-`domain` should be the domain the service is sitting on, dot suffixed, for example `'local.'`
-`type` should be both type and protocol, underscore prefixed, for example `'_http._tcp'`
-`name` should be unique to the device, often the device name
-`port` should be an integer
-`txt` should be a hash, for example `{"foo": "bar"}`
+```javascript
+zeroconf.unpublishService('MyWebServer')
+```
 
-###### `unpublishService(name)` Unpublish a service
+#### `addDeviceListeners()`
 
-This removes a service from those discoverable on the network.
+Manually add event listeners (called automatically in constructor).
 
-`name` should be the name used when publishing the service
+#### `removeDeviceListeners()`
 
-##### Events
+Remove all event listeners. Call this to prevent memory leaks when unmounting components.
 
 ```javascript
-zeroconf.on('start', () => console.log('The scan has started.'))
+// In React useEffect cleanup
+useEffect(() => {
+  const zeroconf = new Zeroconf()
+  zeroconf.scan('http', 'tcp', 'local.')
+
+  return () => {
+    zeroconf.stop()
+    zeroconf.removeDeviceListeners()
+  }
+}, [])
 ```
 
-###### `start` Triggered on scan start
-###### `stop` Triggered on scan stop
-###### `found` Triggered when a service is found
+### Events
+
+#### Scan Events
 
-Broadcast a service name as soon as it is found.
+| Event      | Payload                 | Description                              |
+| ---------- | ----------------------- | ---------------------------------------- |
+| `start`    | none                    | Scan has started                         |
+| `stop`     | none                    | Scan has stopped                         |
+| `found`    | `string` (service name) | Service found (before resolution)        |
+| `resolved` | `Service` object        | Service fully resolved with network info |
+| `remove`   | `string` (service name) | Service removed from network             |
+| `update`   | none                    | Services list changed (found or removed) |
+| `error`    | `Error` object          | An error occurred                        |
 
-###### `resolved` Triggered when a service is resolved
+#### Publishing Events
 
-Broadcast a service object once it is fully resolved
+| Event         | Payload          | Description                      |
+| ------------- | ---------------- | -------------------------------- |
+| `published`   | `Service` object | Service successfully published   |
+| `unpublished` | `Service` object | Service successfully unpublished |
 
-```json
+### Service Object
+
+```javascript
 {
-  "host": "XeroxPrinter.local.",
-  "addresses": [
-    "192.168.1.23",
-    "fe80::aebc:123:ffff:abcd"
+  name: 'Xerox Printer',                    // Human-readable name
+  fullName: 'XeroxPrinter._http._tcp.local.', // Full service name
+  host: 'XeroxPrinter.local.',              // Hostname
+  port: 8080,                               // Port number
+  addresses: [                              // IP addresses (IPv4 and/or IPv6)
+    '192.168.1.23',
+    'fe80::aebc:123:ffff:abcd'
   ],
-  "name": "Xerox Printer",
-  "fullName": "XeroxPrinter.local._http._tcp.",
-  "port": 8080
+  txt: {                                    // TXT record attributes
+    path: '/status',
+    color: 'yes'
+  }
 }
 ```
 
-###### `remove` Triggered when a service is removed
+## Android Implementation Types
+
+This library supports two implementations on Android:
+
+### NSD (Network Service Discovery)
+
+- Uses Android's built-in `NsdManager` API
+- Default implementation
+- Good for most use cases
+
+### DNSSD (Embedded mDNSResponder)
+
+- Uses bundled Apple mDNSResponder
+- More reliable across different Android versions and manufacturers
+- Required for 16KB page size compliance (Android 15+)
+- Recommended for production apps
+
+```javascript
+import Zeroconf, { ImplType } from 'react-native-zeroconf'
+
+const zeroconf = new Zeroconf()
+
+// Use DNSSD for better compatibility
+zeroconf.scan('http', 'tcp', 'local.', ImplType.DNSSD)
+```
+
+### When to Use DNSSD
+
+- **Targeting Android 15+**: Google Play requires 16KB page size alignment
+- **Cross-device compatibility**: More consistent behavior across manufacturers
+- **Printer discovery**: Better support for `_pdl-datastream._tcp` and similar services
+- **When NSD doesn't find services**: Some devices have buggy NSD implementations
+
+## Platform Support
+
+| Feature            | iOS    | Android (NSD) | Android (DNSSD) |
+| ------------------ | ------ | ------------- | --------------- |
+| Service Discovery  | ✅     | ✅            | ✅              |
+| Service Publishing | ✅     | ✅            | ✅              |
+| TXT Records        | ✅     | ✅ (API 21+)  | ✅              |
+| IPv4 Addresses     | ✅     | ✅            | ✅              |
+| IPv6 Addresses     | ✅     | ✅            | ✅              |
+| Min API Level      | iOS 7+ | API 16+       | API 21+         |
+
+## Android Emulator Limitations
+
+**Important:** The Android emulator does not support IGMP or multicast by default. This is a [documented limitation](https://developer.android.com/studio/run/emulator-networking).
+
+Since mDNS/Bonjour relies on multicast UDP packets to `224.0.0.251:5353`, Zeroconf discovery **will not work on Android emulators** without special configuration.
+
+### Recommendations
+
+**Use a Real Device (Recommended)**
+
+For reliable mDNS testing, use a physical Android device connected to the same network as the services you want to discover.
+
+**TAP Bridged Networking (Linux - Really Advanced - Not Recommended for Most Users)**
+
+> **⚠️ Important:**
+>
+> - **Use "Google APIs" system image**, not "Google Play". Google Play images are production builds that don't allow root access (`adb root` fails). You need root to configure the `eth1` interface.
+> - **Always use `-no-snapshot-load`** when starting the emulator. Without this flag, the emulator loads from a saved state and ignores the QEMU network device parameters (eth1 won't exist).
+> - **Network configuration doesn't persist.** You must reconfigure eth1 after every emulator restart.
+> - **Only one emulator per TAP interface.** If running multiple emulators, create additional TAP interfaces (tap1, tap2, etc.).
+> - **Use your network's subnet.** Replace the example IPs below with addresses matching your actual network (e.g., if your network is `192.168.1.x`, use `192.168.1.213/24` and gateway `192.168.1.1`).
+
+On Linux with Ethernet, you can configure TAP bridged networking:
+
+1. Create TAP interface and bridge (one-time setup):
+
+   ```bash
+   sudo ip tuntap add dev tap0 mode tap user $USER
+   sudo ip link add name br0 type bridge
+   sudo ip link show # Get the list of network interfaces
+   sudo ip link set <your-ethernet-interface> master br0  # Replace with your ethernet interface (e.g. enp3s0)
+   sudo ip link set tap0 master br0
+   sudo ip link set dev tap0 up
+   sudo ip link set dev br0 up
+   sudo dhcpcd br0  # Or: sudo dhclient br0
+   ```
+
+2. Start emulator with TAP (must use `-no-snapshot-load`):
+
+   ```bash
+   emulator -avd <avd_name> \
+     -no-snapshot-load \
+     -qemu \
+     -netdev tap,id=mynet0,ifname=tap0,script=no,downscript=no \
+     -device virtio-net-pci,netdev=mynet0
+   ```
+
+3. Configure the emulator's eth1 interface:
+
+   ```bash
+   adb root
+   adb shell ip link set eth1 up
+   adb shell ip addr add <unused_ip> dev eth1   # e.g., 192.168.1.213
+   adb shell ip route add default via <gateway> dev eth1  # e.g., 192.168.1.1
+
+   # Verify connectivity
+   adb shell ping -c 2 <your_printer_or_device_ip>
+   ```
+
+4. Start your dev server with the host's bridge IP:
+
+   ```bash
+   # Find your host's bridge IP
+   ip addr show br0 | grep "inet "
+   # Example output: inet 192.168.1.28/24 ...
+
+   # Example to use that IP to start with Expo
+   REACT_NATIVE_PACKAGER_HOSTNAME=192.168.1.28 npx expo start --android
+   ```
+
+**Note:** WiFi bridging doesn't work on most systems. Use Ethernet for TAP networking.
+
+## Common Service Types
+
+| Service       | Type             | Protocol |
+| ------------- | ---------------- | -------- |
+| HTTP          | `http`           | `tcp`    |
+| HTTPS         | `https`          | `tcp`    |
+| Printer (Raw) | `pdl-datastream` | `tcp`    |
+| Printer (IPP) | `ipp`            | `tcp`    |
+| SSH           | `ssh`            | `tcp`    |
+| FTP           | `ftp`            | `tcp`    |
+| AirPlay       | `airplay`        | `tcp`    |
+| Chromecast    | `googlecast`     | `tcp`    |
+
+## Example
+
+See the [example folder](./example) for a complete React Native app demonstrating service discovery and publishing.
+
+```bash
+cd example
+yarn install
+cd ios && pod install && cd ..
+yarn ios  # or yarn android
+```
+
+## Troubleshooting
+
+### Services not being discovered
+
+1. **Check permissions**: Ensure all required permissions are granted
+2. **iOS 14+**: Verify `NSBonjourServices` includes your service type
+3. **Android emulator**: Use a real device (emulators don't support multicast)
+4. **Try DNSSD**: Switch from NSD to DNSSD implementation on Android
+5. **Same network**: Ensure device and services are on the same network/subnet
+
+### TXT records empty or missing
+
+- TXT records require Android API 21+ (Android 5.0)
+- Verify the service actually publishes TXT records
+
+### Memory leaks
+
+Call `removeDeviceListeners()` when unmounting:
+
+```javascript
+useEffect(() => {
+  const zeroconf = new Zeroconf()
+  // ... setup
+  return () => {
+    zeroconf.stop()
+    zeroconf.removeDeviceListeners()
+  }
+}, [])
+```
+
+## Known Issues
+
+### Android mDNS/NSD Reliability
+
+Android's Network Service Discovery (NSD) implementation has well-documented reliability issues that affect **all** mDNS libraries on Android, including this one. These are platform-level limitations, not bugs in this library.
+
+#### Symptoms
+
+- Discovery works initially, then stops finding services after a few scans
+- `start` event fires but no `resolved` events follow
+- Inconsistent results between scans on the same network
+- Discovery fails silently without error callbacks
+
+#### Root Causes
+
+1. **Android NSD limitations (Android 8–14+)**:
+   - Discovery may silently stop without error callbacks
+   - `onServiceFound` fires but resolve fails
+   - Discovery stops after screen lock or app backgrounding
+   - Multiple concurrent scans conflict with each other
+
+2. **OEM-specific issues** (Samsung, Xiaomi, Huawei, etc.):
+   - Multicast packets throttled or dropped
+   - Background discovery threads killed by battery optimization
+   - Aggressive Doze mode delays mDNS packets
+
+3. **Network change sensitivity**:
+   - mDNS breaks on WiFi reconnect, AP band switching (2.4↔5 GHz), mesh handoff, or VPN changes
+
+#### Recommended Workarounds
+
+**1. Implement retry logic**
+
+Since Android NSD fails silently, implement automatic retries:
+
+```javascript
+async function scanWithRetry(zeroconf, maxAttempts = 5) {
+  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+    const results = await performScan(zeroconf)
+    if (results.length > 0) return results
+
+    // Stop and wait before retry
+    zeroconf.stop('DNSSD')
+    await new Promise(r => setTimeout(r, 1000))
+  }
+  return []
+}
+```
+
+**2. Add delays between stop and start**
+
+The native DNSSD module needs time to fully stop before starting a new scan:
+
+```javascript
+zeroconf.stop('DNSSD')
+await new Promise(r => setTimeout(r, 500)) // Wait 500ms
+zeroconf.scan('pdl-datastream', 'tcp', 'local.', 'DNSSD')
+```
+
+**3. Use DNSSD instead of NSD**
+
+DNSSD (embedded mDNSResponder) is generally more reliable than Android's native NSD:
+
+```javascript
+// Use DNSSD for better reliability
+zeroconf.scan('http', 'tcp', 'local.', 'DNSSD')
+```
+
+**4. Handle app lifecycle**
+
+Stop scans when app backgrounds and restart when foregrounding:
+
+```javascript
+import { AppState } from 'react-native'
+
+AppState.addEventListener('change', (state) => {
+  if (state === 'background') {
+    zeroconf.stop('DNSSD')
+  } else if (state === 'active') {
+    // Restart scan
+    zeroconf.scan('http', 'tcp', 'local.', 'DNSSD')
+  }
+})
+```
+
+**5. Don't call stop() on already-stopped scans**
+
+Track scan state to avoid calling `stop()` multiple times, which can put the native module in a bad state:
+
+```javascript
+let isScanning = false
+
+function startScan() {
+  if (isScanning) return
+  isScanning = true
+  zeroconf.scan('http', 'tcp', 'local.', 'DNSSD')
+}
+
+function stopScan() {
+  if (!isScanning) return
+  isScanning = false
+  zeroconf.stop('DNSSD')
+}
+```
+
+#### What Doesn't Help
+
+- Creating multiple Zeroconf instances (native module is a singleton)
+- Calling `removeDeviceListeners()` + `addDeviceListeners()` rapidly
+- Very short scan timeouts (< 3 seconds)
+
+#### References
+
+- [Android NsdManager documentation](https://developer.android.com/reference/android/net/nsd/NsdManager)
+- [Android emulator multicast limitations](https://developer.android.com/studio/run/emulator-networking)
+
+## About
+
+The library [react-native-zeroconf](https://github.com/balthazar/react-native-zeroconf) includes:
+
+- **16KB Page Size Support**: Native libraries built with 16KB alignment for Android 15+ (Google Play requirement as of November 1, 2025)
+- **Bundled RxDNSSD**: Native DNS-SD code from [Discord's RxDNSSD fork](https://github.com/discord/RxDNSSD) is embedded directly
+- **Embedded mDNSResponder**: Works reliably across all Android versions without depending on system daemons
+- **Zero Security Vulnerabilities**: All dependencies updated to modern versions
+
+## License
+
+MIT License - see [LICENSE](LICENSE) file.
 
-Broadcast a service name removed from the network.
+### Third-Party Licenses
 
-###### `update` Triggered either when a service is found or removed
-###### `error` Triggered when an error occurs
+This project includes code from [RxDNSSD](https://github.com/discord/RxDNSSD) (originally by Andriy Druk, maintained by Discord), licensed under the Apache License 2.0. See [NOTICE](NOTICE) file.