nym_smoldvpn/lib.rs
1// Copyright 2026 - Nym Technologies SA <contact@nymtech.net>
2// SPDX-License-Identifier: Apache-2.0
3
4//! # smoldvpn
5//!
6//! A pure-Rust, userspace 1-/2-hop WireGuard dVPN datapath built on
7//! [`boringtun`](https://docs.rs/boringtun) and [`nym_smol_core`], with **no OS
8//! `tun` device and no root**. Application traffic flows through the tunnel via
9//! ordinary tokio socket surfaces ([`TcpStream`], [`UdpSocket`], and the
10//! `tonic`/`hyper`/`reqwest` connectors in [`connectors`]).
11//!
12//! The datapath is decoupled from provisioning: build a [`PeerConfig`] per hop
13//! (e.g. from a `nym-sdk-session` registration) and hand it to a
14//! [`TunnelBuilder`]. Three data-plane modes are supported: one-hop, two-hop,
15//! and QUIC-tunnelling two-hop (see [`BridgeParams`]).
16//!
17//! ```no_run
18//! # async fn example(entry: nym_smoldvpn::PeerConfig, exit: nym_smoldvpn::PeerConfig)
19//! # -> Result<(), Box<dyn std::error::Error>> {
20//! use nym_smoldvpn::TunnelBuilder;
21//!
22//! let tunnel = TunnelBuilder::two_hop(entry, exit).connect().await?;
23//! let mut tcp = tunnel.tcp_connect("1.1.1.1:443".parse()?).await?;
24//! // ... use `tcp` as any AsyncRead + AsyncWrite ...
25//! tunnel.shutdown().await;
26//! # Ok(())
27//! # }
28//! ```
29
30mod bridge;
31mod config;
32mod connectors;
33mod engine;
34mod error;
35mod framing;
36mod topup;
37mod transport;
38mod tunnel;
39
40pub use bridge::{probe as probe_bridge, BridgeParams};
41pub use config::{DnsMode, MtuConfig, PeerConfig, TunnelConfig, DEFAULT_EXIT_WG_CLIENT_PORT};
42pub use connectors::TunnelConnector;
43pub use error::{DvpnError, Result};
44pub use topup::{
45 query_available_bandwidth, topup_bandwidth, BandwidthCredentialSource, BandwidthEvent,
46 CredentialFuture, ProviderCredentialSource, TopupConfig,
47};
48pub use transport::SocketProtector;
49pub use tunnel::{NotEstablished, Tunnel, TunnelBuilder};
50
51/// tokio socket types produced by the tunnel (re-exported from `smol-core`).
52pub use nym_smol_core::{TcpStream, UdpSocket};