Struct ockam_transport_udp::UdpHolePuncher
source · pub struct UdpHolePuncher { /* private fields */ }
Expand description
High level management interface for UDP NAT Hole Punchers
See Wikipedia and ‘Peer-to-Peer Communication Across Network Address Translators’.
A node can have multiple Hole Punchers (punchers) at a time, each one with a unique name and working with a different peer puncher in a remote node.
For a puncher to work a (e.g. from ‘alice’ to ‘bob’, using rendezvous service ‘zurg’) the remote node will also need to create its own puncher (e.g. from ‘bob’ to ‘alice’, using ‘zurg’).
Warnings
This UDP NAT Hole Puncher implementation is currently a prototype. No guarantees are provided.
UDP and NAT Hole Punching are unreliable protocols. Expect send and receive failures.
Example
use ockam_transport_udp::{UdpHolePuncher, UdpTransport, UDP};
// Create transport
UdpTransport::create(ctx).await?;
// Create a NAT hole from us 'alice' to them 'bob' using
// the Rendezvous service 'zurg' at public IP address `192.168.1.10:4000`
let rendezvous_route = route![(UDP, "192.168.1.10:4000"), "zurg"];
let mut puncher = UdpHolePuncher::create(ctx, "alice", "bob", rendezvous_route).await?;
// Note: For this to work, 'bob' will likewise need to create a hole thru to us
// Wait for hole to open.
// Note that the hole could close at anytime. If the hole closes, the
// puncher will automatically try to re-open it.
puncher.wait_for_hole_open().await?;
// Try to send a message to a remote 'echoer' via our puncher
ctx.send(route![puncher.address(), "echoer"], "Góðan daginn".to_string()).await?;
Implementations§
source§impl UdpHolePuncher
impl UdpHolePuncher
sourcepub async fn create<S: AsRef<str>, R: Into<Route>>(
ctx: &mut Context,
puncher_name: S,
peer_puncher_name: S,
rendezvous_route: R
) -> Result<UdpHolePuncher>
pub async fn create<S: AsRef<str>, R: Into<Route>>( ctx: &mut Context, puncher_name: S, peer_puncher_name: S, rendezvous_route: R ) -> Result<UdpHolePuncher>
Create a new UDP NAT Hole Puncher
sourcepub async fn wait_for_hole_open(&mut self) -> Result<()>
pub async fn wait_for_hole_open(&mut self) -> Result<()>
Wait until Hole Puncher successfully opens a hole to the peer or a timeout
Note that the hole could close at anytime. If the hole closes, the puncher will automatically try to re-open it.
Timeout is the same as that of Context::receive()
.