fix: detect unsupported transport multiaddrs before dialing (issue #391)

[paschal533]

Fixes #391.

What was happening

When the peerstore contained multiaddrs that the registered transport doesn't handle — for example, /udp/9090 or /udp/9090/quic addresses when only TCP is registered — dial_peer() would call transport.dial() for each of those addresses anyway. That eventually reached TCP._dial_resolved(), which called maddr.value_for_protocol("tcp") without guarding against the ProtocolLookupError it raises on non-TCP multiaddrs. The exception propagated all the way up uncaught, crashing the caller with an error that gives no indication of what actually went wrong.

Making it worse: the default RetryConfig has max_retries=3 and initial_delay=0.1s with backoff_multiplier=2.0. So for each unsupported address, the stack would sleep ~0.1s + ~0.2s + ~0.4s = ~700ms before finally raising the wrong exception. A peer with two bad addresses (UDP + QUIC) would waste ~1.4 seconds before crashing.

The fix

Three small, self-contained changes:

ITransport gets a can_dial(maddr) method (default True) so the interface can express whether a transport handles a given multiaddr, without breaking existing custom transports that don't implement it.

TCP.can_dial() returns False for any multiaddr without a tcp component. The check is a simple protocol lookup, ~30 µs — negligible compared to the cost of an actual TCP handshake (~1–100 ms).

Swarm.dial_peer() filters addresses through can_dial() before entering the dial loop. If no address passes, it raises SwarmException("No supported transport for any address of peer ...") immediately, before touching the transport or sleeping.

TCP._dial_resolved() also now wraps the value_for_protocol("tcp") call in a try/except and re-raises as OpenConnectionError, consistent with how listen() already handled it. This is a defence-in-depth change — the can_dial() filter should prevent us from ever reaching this path with a bad address, but if something slips through it will still produce a clean error.

Note: QUIC and WebSocket already had can_dial() methods on their transport classes, but nothing was calling them. This PR formalises the pattern and wires it into Swarm.

What it looks like now

Before:

ProtocolLookupError: <no tcp in multiaddr>   # wrong layer, no context

After:

SwarmException: No supported transport for any address of peer <id>: [/ip4/127.0.0.1/udp/9090]

Testing

Five new regression tests in tests/core/network/test_swarm.py, all verified in a clean Docker environment (Python 3.13.14 / Linux):

test_tcp_can_dial_returns_true_for_tcp_addr   PASSED
test_tcp_can_dial_returns_false_for_udp_addr  PASSED
test_tcp_can_dial_returns_false_for_quic_addr PASSED
test_swarm_skips_unsupported_multiaddrs       PASSED   ← regression test for #391
test_swarm_can_dial_filters_unsupported       PASSED

Dockerfile.issue391 and benchmarks/bench_issue391.py are included so the numbers can be reproduced:

can_dial() guard cost:          ~30 µs/call
dial_peer() before (no filter): ~620 µs/call  (no retry, 2 bad addrs)
dial_peer() after  (filtered):  ~154 µs/call
Speedup (no retry baseline):    4x

With default max_retries=3 the before-fix cost is ~1.4 s of sleep alone,
before raising ProtocolLookupError on a peer that simply has no TCP address.

Backwards compatibility

ITransport.can_dial() defaults to True, so any existing transport that doesn't implement it continues to work exactly as before.