From de05313d4a2629e918378271dd67bc4b55b2e297 Mon Sep 17 00:00:00 2001 From: Elena Frank Date: Tue, 4 Oct 2022 13:42:56 +0200 Subject: [PATCH] core/transports: enhance `Transport::address_translation` docs --- core/src/transport.rs | 18 +++++++++++++++--- 1 file changed, 15 insertions(+), 3 deletions(-) diff --git a/core/src/transport.rs b/core/src/transport.rs index df6e094ed80..84557c3fb46 100644 --- a/core/src/transport.rs +++ b/core/src/transport.rs @@ -149,9 +149,21 @@ pub trait Transport { cx: &mut Context<'_>, ) -> Poll>; - /// Performs a transport-specific mapping of an address `observed` by - /// a remote onto a local `listen` address to yield an address for - /// the local node that may be reachable for other peers. + /// Performs a transport-specific mapping of an address `observed` by a remote onto a + /// local `listen` address to yield an address for the local node that may be reachable + /// for other peers. + /// + /// This is relevant for transports where Network Address Translation (NAT) can occur + /// so that e.g. the peer is observed at a different IP than the IP of the local + /// listening address. See also [`address_translation`][crate::address_translation]. + /// + /// Within [`libp2p_swarm::Swarm`][libp2p_swarm::Swarm] this is used when extending the + /// listening addresses of the local peer with external addresses observed by remote peers. + /// On transports where this is not relevant (i.e. no NATs are present) `None` should be + /// returned for the sake of de-duplication. + /// + /// Note: if the listen or observed address is not a valid address of this transport, + /// `None` should be returned as well. fn address_translation(&self, listen: &Multiaddr, observed: &Multiaddr) -> Option; /// Boxes the transport, including custom transport errors.