Add NAT traversal via UPnP port mapping

[GautamBytes]

What was wrong?

py-libp2p lacked support for automatic port mapping via UPnP, making nodes behind home routers non-dialable from the public internet. This limited peer connectivity in common NAT scenarios.

Issue: NAT traversal for home network users

How was it fixed?

1. Implemented a thread-safe UpnpManager class that:
   • Discovers UPnP gateways with caching
   • Maps TCP ports with permanent leases
   • Detects double-NAT scenarios
   • Automatically cleans mappings on shutdown
2. Added optional dependency miniupnpc via pip install .[upnp]
3. Created a comprehensive example demonstrating:
   • Successful mapping
   • Gateway failure cases
   • Clean shutdown behavior

Summary:

• Standalone manager avoids host/swarm refactoring
• Event-driven error handling (GatewayNotFound, NonRoutableGateway)
• IPv4/IPv6 compatible address handling

To-Do

• Clean up commit history (single cohesive commit)
• Add documentation (example + README)

[GautamBytes]

@seetadev please review it whenever feasible and suggest improvements!

[lla-dane]

This should be:

pip install -e ".[upnp]"

[GautamBytes]

my bad , will update it soon. Any other changes apart from this??

[lla-dane]

Is there a specific edge case in miniupnpc where it raises an exception with the message "Success" but should actually be treated as a valid discovery result?

This looks a bit fragile, so I was wondering if it's based on something you've seen happen in the wild. Could you clarify the motivation?

[lla-dane]

if port <= 0 or port > 65535:
    logger.error(f"Invalid port number: {port}")
    return False
if port < 1024:
    logger.warning(f"Mapping a well-known port: {port} (may fail)")

Setting up these kinds of warning for sketchy port numbers in the params, would save computation time in cases of misbehaviour. Also add similar checks to remove_port_mapping.

[lla-dane]

It would be better to integrate the UpnpManager into the Host runtime. You can see how the mdns service is integrated, Unpn will follow the same thing.

class BasicHost(IHost):
	...

    def __init__(
        self,
        network: INetworkService,
        enable_mDNS: bool = False,
        default_protocols: Optional["OrderedDict[TProtocol, StreamHandlerFn]"] = None,
        negotitate_timeout: int = DEFAULT_NEGOTIATE_TIMEOUT,
    ) -> None:
	...
        if enable_mDNS:
            self.mDNS = MDNSDiscovery(network)

Could go with an enable_upnp bool to set up the manager object and then inside this part in the example:

    async with host.run(listen_addrs=[listen_maddr]):

call host.upnp to start the relevant operations.
Embedding this in the host logic would be much cleaner and more consistent to updates.
Let me know if you need any pointers on how to set this up.

[lla-dane]

@seetadev @GautamBytes: Added some inline comments and suggestions.
Couldn’t test the upnp_demo example since I’m currently on a college network without access to a personal router.
Would be great if someone with a UPnP-enabled router could give it a spin and verify the behavior.

[luu-alex]

negotitate_timeout Should be negotiate_timeout

[GautamBytes]

that was already there so didn't notice , will correct it!

[luu-alex]

UpnpManager would benefit with unit tests

[GautamBytes]

Sure , will be adding that asap!