Replace Embedded Functionality with mdns library (written in C)

[CMCDragonkai]

Specification

Migrate the existing embedded MDNS functionality in js-mdns to use the lightweight, portable C library mjansson/mdns via Rust FFI bindings. Implement a hybrid discovery model:

1. Prefer OS-native MDNS stacks (Avahi on Linux, Bonjour on macOS, etc.) when available.
2. Fallback to embedded mjansson/mdns when OS-native stacks are unavailable (e.g., Docker containers, minimal OS environments).

The MDNS class must:

• Manage all multicast group lifecycle state explicitly when using the embedded library.
• Remain stateless when delegating to OS-native stacks (rely on their managed state).
• Support cross-platform multicast discovery (IPv4/IPv6) on Linux, macOS, and Windows.

Additional Context

• Current js-mdns uses custom JavaScript logic for multicast handling, which lacks IGMP optimizations and cross-platform reliability.
• Docker/container use-case: OS-native stacks (Avahi) are often unavailable, necessitating an embedded solution.
• Hybrid design ensures broad compatibility.
• The mjansson/mdns library is:
  • Stateless at the library level (application manages sockets/groups).
  • Portable across Linux/macOS/Windows.
  • MIT-licensed and dependency-free.
• Native Windows mDNS Stack Support (Windows.Networking.ServiceDiscovery.Dnssd) #3
• Native Linux mDNS Stack Support (Avahi and systemd-resolved) #2
• Native macOS/iOS mDNS stack support (NWListener) #4
• Rely on OS-native MDNS stack when possible #8

Tasks

1. Create Rust FFI bindings for mjansson/mdns:

2. Integrate Rust module with Node.js:

   • Use napi-rs or similar to expose functionality via Node.js N-API.
   • Design JS API mirroring current js-mdns interface for backward compatibility.

3. Implement OS-native stack detection:

   • Linux: Check for Avahi DBus service (dbus-send or socket presence).
   • macOS: Verify Bonjour/mDNSResponder availability via dns-sd CLI or headers.
   • Windows: Validate Bonjour SDK installation/registry entries.
   • Return detection status to JS layer.

4. Implement hybrid mode:

   • If OS-native stack detected:
     • Delegate advertisement/discovery to native APIs (Avahi/Bonjour bindings).
   • Else:
     • Use embedded mjansson/mdns via Rust bindings.
     • Explicitly manage multicast group joins/leaves per interface.
     • Handle TXT record serialization/parsing in Rust.

5. State management for embedded mode:

   • MDNS class to track:
     • Active multicast sockets per interface.
     • Service advertisement TTLs.
     • Discovery query intervals.
   • Ensure resource cleanup (socket closure, group leaves) on shutdown.

6. Testing & CI/CD:

   • Add cross-platform tests for hybrid mode:
     • Native stack available (Linux host).
     • Embedded fallback (Docker bridge network).
   • Verify Windows firewall allows multicast traffic during tests.
   • Build ARM binaries for container/embedded use.

7. Documentation:

   • Update README with hybrid mode explanation.
   • Add troubleshooting guide for multicast firewall rules.
   • Note Docker-specific considerations (e.g., --network host vs. bridge).

[linear]

ENG-550

[CMCDragonkai]

Design Commentary for Migration to mjansson/mdns (Hybrid Model)

---

① OS-Native vs. Embedded Stack: Key Differences

Aspect	OS-Native Stack (Avahi/Bonjour)	Embedded mjansson/mdns
State Management	Managed by OS daemon (e.g., Avahi tracks services, groups, interfaces). Application delegates fully.	Application must manage: - Multicast sockets per interface. - Active service advertisements (TTL renewals). - IGMP/MLD group joins/leaves per interface.
IGMP/MLD Handling	Fully automated by OS kernel. No explicit action needed.	Kernel still handles IGMP/MLD packet generation, but application must: - Explicitly join/leave groups via setsockopt. - Track interface availability (hotplugging).
Network Efficiency	Optimized via OS-level multicast routing (IGMP snooping, querier).	Relies on kernel’s baseline multicast routing. No IGMP snooping unless switches/routes support it.
Deployment Complexity	Requires OS dependencies (DBus, Avahi/Bonjour). May fail in containers.	Zero external dependencies. Works in isolated environments (Docker, minimal OS).

---

② IPv4 vs. IPv6 Multicast: Implementation Considerations

The mjansson/mdns library abstracts most protocol differences, but the following apply:

Protocol	Key Technicalities	Application-Level Impact
IPv4 (IGMP)	- Uses multicast group 224.0.0.251. - IGMPv3 membership reports required. - Kernel handles IGMP packets; app manages IP_ADD_MEMBERSHIP.	Ensure dual-stack sockets or separate IPv4/IPv6 sockets. Handle EAFNOSUPPORT gracefully if IPv6 disabled.
IPv6 (MLD)	- Uses multicast group ff02::fb. - MLDv2 equivalent to IGMPv3. - Managed via IPV6_JOIN_GROUP socket option.	Same socket can bind to IPv6 + IPv4 (on Linux via IPV6_V6ONLY=0). Windows requires separate sockets.

Library Abstraction:
The C library uses standard multicast addresses and socket APIs. The kernel handles protocol-specific IGMP/MLD mechanics. The Rust layer must:

• Use AF_INET6 sockets for dual-stack support where possible.
• Explicitly bind to 0.0.0.0 (IPv4) and :: (IPv6) for interface-agnostic listening.

---

③ Portability of mjansson/mdns Across Windows/macOS/Linux

Why It Works:

• Standard Sockets: Uses POSIX-compliant socket()/bind()/sendto()/recvfrom(), mapped to Winsock2 on Windows.
• Kernel-Dependent Optimizations:
  Relies on OS kernels to handle:
  • Multicast routing tables (e.g., route.h on Linux, ws2ipdef.h on Windows).
  • Interface enumeration via getifaddrs() (Linux/macOS) or GetAdaptersAddresses() (Windows).
• Minimal Dependencies: No reliance on external libraries (only libc).

Platform-Specific Adjustments:

• Windows:
  • Requires WSAStartup() for socket initialization.
  • Uses DWORD instead of int for socket handles.
  • IGMPv3/MLDv2 support depends on Windows version (post-Windows 10 1709).
• macOS:
  • Bonjour may conflict if using the same multicast groups (use distinct groups to avoid interference).
  • Uses SO_NET_SERVICE_TYPE for QoS tagging (background/standard).
• Linux:
  • Kernel ≥3.9 required for robust dual-stack behavior.
  • CONFIG_IP_MULTICAST must be enabled (standard in most distros).

---

④ Hybrid Mode Execution Flow

graph TD
    A[Start Discovery] --> B{OS Native Stack Detected?}
    B -- Yes --> C[Delegate to Avahi/Bonjour APIs]
    B -- No --> D[Initialize mjansson/mdns]
    D --> E[Enumerate Interfaces]
    E --> F[Create Socket per Interface]
    F --> G[Join Multicast Groups IGMP/MLD via setsockopt]
    G --> H[Start Advertising/Searching]
    H --> I[Manage Socket Lifecycle]

Loading

Critical Checks for Native Stack:

• Linux: Verify avahi-daemon is running via DBus (org.freedesktop.Avahi).
• macOS: Check for dns-sd binary or DNSServiceRegister API availability.
• Windows: Validate Bonjour Service (Bonjour Service in task manager).

---

⑤ Testing Matrix

Platform	Test Scenario	Expected Outcome
Linux (Avahi)	Host with Avahi running	Discovery via Avahi; no embedded sockets.
Linux (Docker)	Container without Avahi	Embedded stack binds to all interfaces; multicast within Docker network.
Windows	Bonjour installed	Prefer Bonjour; fallback only if service stopped.
macOS	Default setup	Use Bonjour; embedded stack only if dns-sd unavailable.

---

This design leverages the kernel’s existing multicast infrastructure while ensuring compatibility in constrained environments. The Rust layer must rigorously manage platform-specific socket behaviors and state transitions.

[CMCDragonkai]

Relative to #8, this issue focuses on replacing the embedded stack that we have coded up.

[CMCDragonkai]

In the case of #42, it should be automatically solved if the MDNS socket handling is entirely handled on the native code side, rather than passing in a socket from JS level to the native code.

[CMCDragonkai]

The good thing is that JS-side can still track resource lifecycles, so although the socket is opened on the native side, it isn't somehow being managed in a different resource context.

[CMCDragonkai]

Answer:
The mjansson/mdns library opens and manages its own UDP sockets internally. The workflow is as follows:

1. Socket Creation:
   Use library-provided functions like:

   int mdns_socket_open_ipv4();
   int mdns_socket_open_ipv6();

   These functions handle:

   • Socket creation (socket()).
   • Setting SO_REUSEADDR/SO_REUSEPORT.
   • Binding to 0.0.0.0:5353 (IPv4) or [::]:5353 (IPv6).
   • Joining multicast groups (IP_ADD_MEMBERSHIP/IPV6_JOIN_GROUP).

2. Socket Usage:
   You receive raw socket file descriptors, which you pass to other library functions:

   mdns_query_send(socket, /*...*/);
   mdns_query_recv(/*..., */ socket, /*...*/);

---

Key Notes:

• No Manual Socket Passing: You do not create sockets via socket() and pass them to the library. The library’s API assumes it fully controls socket configuration.
• Portability: The implementation handles OS-specific nuances (e.g., Winsock2 on Windows vs. POSIX sockets on Linux/macOS).
• Multicast Compliance: Sockets are preconfigured for mDNS standards (port 5353, TTL 255, loopback disabled).

---

When to Deviate:
If custom sockets are required (e.g., non-standard ports), you’d need to modify the library or handle multicast routing/exceptions manually, which is not recommended. The library is designed to abstract low-level socket management for mDNS correctness.

[CMCDragonkai]

From a NAPI perspective, the JS side will have "object references" that point to the socket on the native side.

So there's no usable socket on the JS side. That's great though as it does make it more cross-platform later.

[CMCDragonkai]

Precise Analysis & Guidance:

1. Socket Lifecycle Ownership:
   mjansson/mdns creates sockets via mdns_socket_open_ipv4()/mdns_socket_open_ipv6(), but does not manage their lifecycle.
   ⟶ JS Wrapper Must:

   • Track socket descriptors (e.g., in a Set or object property).
   • Explicitly close sockets via mdns_socket_close(socket) before the JS object is garbage-collected.

2. Critical Resource Leak Scenario:
   Failing to close sockets leaves:

   • Multicast group memberships active (IGMP/MLD subscriptions persist).
   • Port 5353 bound, blocking future socket creation.

3. JavaScript-Specific Requirements:

   • Explicit .close() Method: Mandatory for users to invoke, as JS garbage collection timing is non-deterministic.

     class MDNS {
       constructor() { this.sockets = new Set(); }
       start() {
         const ipv4Socket = mdns.mdns_socket_open_ipv4();
         this.sockets.add(ipv4Socket);
         // ...
       }
       close() {
         for (const socket of this.sockets) {
           mdns.mdns_socket_close(socket); // Critical for IGMP cleanup
         }
       }
     }

   • WeakRef/FinalizationRegistry: Optionally, register sockets for cleanup, but do not rely solely on this due to GC unpredictability.

4. Cross-Platform Socket Behavior:

   • POSIX (Linux/macOS): Closing a socket automatically triggers IGMP/MLD "leave" via kernel.
   • Windows: Requires explicit setsockopt(IP_DROP_MEMBERSHIP) – but mjansson/mdns does not expose this.
     ⟹ Mitigation: Always use mdns_socket_close(), which internally handles OS-specific leave mechanics.

5. Recommendations:

   • Mandate explicit .close() calls in documentation.
   • Instrument resource tracking: Log unclosed sockets in development mode.
   • Validate socket states: Before (re)opening, check EADDRINUSE errors indicating leaks.

This structure ensures safe multicast group management and port reuse.