Crate nym_smoldvpn

Expand description

§smoldvpn

A pure-Rust, userspace 1-/2-hop WireGuard dVPN datapath built on boringtun and nym_smol_core, with no OS tun device and no root. Application traffic flows through the tunnel via ordinary tokio socket surfaces (TcpStream, UdpSocket, and the tonic/hyper/reqwest connectors in [connectors]).

The datapath is decoupled from provisioning: build a PeerConfig per hop (e.g. from a nym-sdk-session registration) and hand it to a TunnelBuilder. Three data-plane modes are supported: one-hop, two-hop, and QUIC-tunnelling two-hop (see BridgeParams).

use nym_smoldvpn::TunnelBuilder;

let tunnel = TunnelBuilder::two_hop(entry, exit).connect().await?;
let mut tcp = tunnel.tcp_connect("1.1.1.1:443".parse()?).await?;
// ... use `tcp` as any AsyncRead + AsyncWrite ...
tunnel.shutdown().await;

Structs§

BridgeParams: Bridge connection parameters, sourced from the gateway directory / VPN API.
MtuConfig: Per-hop MTU. Defaults follow the reference: overhead 80 B/hop; desktop entry 1420 / exit 1340; mobile entry 1360 / exit 1280.
NotEstablished: The tunnel’s WireGuard session(s) did not establish within the caller’s bound. Reports per-hop status so a caller reusing cached registrations can invalidate (and re-register) exactly the failed hop(s).
PeerConfig: One WireGuard peer/hop
ProviderCredentialSource: A ready-made BandwidthCredentialSource backed by any BandwidthTicketProvider (e.g. nym-sdk-session’s controller sender). Spends one stored ticket of ticket_type against gateway_id per call.
SocketProtector: A hook invoked with a freshly-created socket’s file descriptor so the host can protect it from the tunnel’s own routes (Linux/Android). No-op on other platforms.
TcpStream: tokio socket types produced by the tunnel (re-exported from smol-core). A TCP stream between a local and a remote socket.
TopupConfig: Configuration for the background top-up / monitoring task.
Tunnel: A running dVPN tunnel exposing tokio socket surfaces.
TunnelBuilder: Builder for a Tunnel.
TunnelConfig: Tunnel-wide options.
TunnelConnector: A tower connector that dials through the dVPN tunnel. Cloneable and cheap; holds the tunnel’s swappable stack handle so it keeps working across a runtime MTU change (which rebuilds the stack).
UdpSocket: tokio socket types produced by the tunnel (re-exported from smol-core). A UDP socket.

Enums§

BandwidthEvent: An event emitted by the bandwidth monitor/top-up task. Subscribe via Tunnel::bandwidth_events.
DnsMode: DNS behaviour inside the tunnel.
DvpnError: Errors from the smoldvpn datapath.

Constants§

DEFAULT_EXIT_WG_CLIENT_PORT: Fixed client source port used inside the two-hop inner IPv4/UDP frame — the exit tunnel’s packets are framed with this as their UDP source port before being encapsulated to the entry gateway (matching the reference DEFAULT_EXIT_WG_CLIENT_PORT, two_hop_config.rs:17). It is NOT a port any node listens on; it only identifies the client side of the inner exit flow.

Traits§

BandwidthCredentialSource: Supplies bandwidth credentials on demand — one spent ticket per call.

Functions§

probe_bridge: Diagnostic: attempt a full bridge connect (real ed25519 cert pinning + open the WireGuard bi-stream), then drop it. Ok(()) means the QUIC handshake and stream open succeeded. Useful for testing QUIC-gateway reachability without bringing up a whole tunnel (see the quic-probe example).
query_available_bandwidth: One-shot (host network): query available bandwidth (bytes) at a metadata endpoint.
topup_bandwidth: One-shot (host network): spend credential at a metadata endpoint, returning the updated available bandwidth (bytes).

Type Aliases§

CredentialFuture: Future returned by a BandwidthCredentialSource.
Result: Result alias for the datapath.