Struct ockam_transport_udp::UdpHolePuncher

pub struct UdpHolePuncher { /* private fields */ }

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

impl 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

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().

pub fn address(&self) -> Address

Address of this UDP NAT Hole Puncher’s worker.