Add Support for mDNS-Based Local Peer Discovery in py-libp2p

[seetadev]

This proposal outlines how we can introduce Multicast DNS (mDNS)-based peer discovery into py-libp2p, aligned with the behavior of go-libp2p and js-libp2p.

Module Structure & Responsibilities

We propose creating a dedicated module, libp2p.discovery.mdns, with the following internal components:

libp2p/
└── discovery/
    └── mdns/
        ├── broadcaster.py  # Registers local peer via mDNS
        ├── listener.py     # Listens for mDNS broadcasts from other peers
        └── __init__.py

Each component would manage distinct responsibilities:

1. Broadcaster

   • Advertises the local peer's presence on the network using the _p2p._udp.local service name.
   • Uses a TXT record to encode the local peer ID:
     Example: id=QmPeerID123...

2. Listener

   • Listens on 224.0.0.251:5353 for mDNS responses.
   • Parses valid mDNS responses to extract PeerInfo for peers discovered on the same LAN.
   • Emits these to the libp2p Swarm/Host layer for dialing.

3. Integration Layer

   • Provides an API surface for enabling/disabling mDNS.
   • Hooks into Swarm or Host to trigger connection attempts when peers are discovered.

---

🛠️ How it Works (Expected Flow)

• On startup, if mdns is enabled:

  • mdns_broadcaster advertises the peer using Zeroconf (or equivalent).
  • mdns_listener listens for peer advertisements.

• When a peer is found:

  • A PeerInfo object is emitted.
  • If supported, Swarm auto-dials the discovered peer or adds it to its peerstore.

Dependency Suggestion: [zeroconf](https://github.com/jstasiak/python-zeroconf) Python Library

We suggest using zeroconf, a well-supported Python library with support for:

• Multicast broadcast and listening
• TXT record parsing
• Cross-platform support (Linux/macOS/Windows)

The library is used in projects like Home Assistant, which shows it handles real-world, high-performance discovery.

Configuration Options

Add a new config object or flags to enable/disable mDNS:

Host(..., enable_mdns=True)

Advanced options could include:

• Service name override (for scoped discovery)
• Peer ID filtering
• Interval control for rebroadcasts

---

Testing Plan

1. Unit Tests

   • TXT record parsing
   • PeerInfo extraction
   • Service registration lifecycle

2. Integration Tests

   • Simulate two libp2p hosts on the same subnet
   • Validate discovery and peerstore updates

We can leverage pytest fixtures to spin up hosts in subprocesses on local ports.

Example Usage (Preview)

from libp2p import new_node

node = await new_node(enable_mdns=True)

@node.on_peer_discovered
def on_new_peer(peer_info):
    print(f"Discovered peer: {peer_info.peer_id}")
    await node.connect(peer_info)

🔍 Open Questions for Discussion

1. Where should peer discovery events be surfaced?

   • Should Host expose a listener pattern or use async callbacks?
   • How should we handle multiple discovery mechanisms (mDNS, DHT, etc.) consistently?

2. How do we ensure safety and scoping?

   • Should we support namespaces for service names to avoid collisions on shared networks?

3. Do we want to align broadcast intervals with go/js defaults?

   • Example: js-libp2p re-broadcasts every 10 seconds.

4. Should we emit events even if the peer is already known (i.e., for heartbeats)?

Why This Is a Good Fit for py-libp2p

• Improves feature parity with Go and JS libp2p.
• Enables new use cases (local collaboration, demos, P2P offline apps).
• Provides easier onboarding for developers experimenting with libp2p in Python.
• Aligns with libp2p’s modular discovery framework and specs.