Library docs

Author: vi

Cargo.lock

@@ -14,14 +14,7 @@ keywords = ["wireguard","onetun","slirp","nat"]
 [dependencies]
 anyhow = "1.0.72"
 argh = "0.1.10"
-base64 = "0.21.2"
-boringtun = "0.6.0"
-bytes = "1.4.0"
-hashbrown = "0.14.0"
-hex = "0.4.3"
-simple-dns = "0.5.3"
-smoltcp = { version = "0.10.0", default-features = false, features = ["socket", "socket-tcp", "socket-udp", "std", "proto-ipv4", "proto-ipv4-fragmentation", "proto-ipv6", "fragmentation-buffer-size-65536", "assembler-max-segment-count-32", "log", "medium-ip"] }
-tokio = { version = "1.29.1", features = ["rt", "net", "sync", "macros", "io-util", "time"] }
+tokio = { version = "1.29.1", features = ["rt",  "macros"] }
 tracing = "0.1.37"
 tracing-subscriber = {version="0.3.17", optional=true}
 libwgslirpy = {version = "0.2.0", path="crates/libwgslirpy"}

Cargo.toml

@@ -1,4 +1,6 @@
+//! Helper module to create `smoltcp` devices that use single slot for received packet and a tokio::mpsc channel to transmit packets.
 
+#![allow(missing_docs)]
 
 use bytes::BytesMut;
 use smoltcp::phy::{Device,RxToken,TxToken, Checksum};
@@ -9,12 +11,24 @@ use crate::TEAR_OF_ALLOCATION_SIZE;
 
 pub struct ChannelizedDevice {
     pub tx : Sender<BytesMut>,
+
+    /// Put a packet to be handled by smoltcp here. Channelized device would take it from here.
     pub rx: Option<BytesMut>,
+
+    /// Moderately big allocation to snip away pieces from it when we need to transmit packets into [`tx`].
+    /// 
+    /// When remaining capacity falls below some threshold, the buffer gets allocated again.
+    /// 
+    /// Idea is to reduce number of allocations at the expense of the size of allocated block.
     pub tear_off_buffer: BytesMut,
+
     pub mtu : usize,
 }
 
 impl ChannelizedDevice {
+    /// Create the device using given queue for transmitting packets, retuning given `mtu` as MTU.
+    /// 
+    /// Checksumming is enabled, menium is "IP".
     pub fn new(tx: Sender<BytesMut>, mtu: usize) -> Self {
         ChannelizedDevice {
             tx,

crates/libwgslirpy/src/channelized_smoltcp_device.rs

@@ -1,3 +1,8 @@
+#![warn(missing_docs)]
+//! Library part of wgslirpy - Tokio-, smoltcp- and boringtun-based user-space router.
+//! See main (i.e. CLI tool) documentation for what is it.
+
+
 const TEAR_OF_ALLOCATION_SIZE : usize = 65536;
 
 pub mod wg;
@@ -8,6 +13,14 @@ use tracing::warn;
 
 pub use wg::parsebase64_32;
 
+pub extern crate bytes;
+pub extern crate boringtun;
+pub extern crate smoltcp;
+pub extern crate tokio;
+
+/// Start the application using given Wireguard and routing options.
+/// 
+/// Aboring `Future` returned by this function should abort all tasks spawned related by it and close all sockets.
 pub async fn run(wireguard_options: wg::Opts, router_options: router::Opts, transmit_queue_capacity: usize) -> anyhow::Result<()> { 
     let (tx_towg, rx_towg) = tokio::sync::mpsc::channel(transmit_queue_capacity);
     let (tx_fromwg, rx_fromwg) = tokio::sync::mpsc::channel(4);

crates/libwgslirpy/src/lib.rs

@@ -1,3 +1,12 @@
+//! Routing and smoltcp-facing part of the library.
+//! 
+//! This moduile allows a pair of tokio::sync::mpsc channels that represent sent and transmitted IP bytes to be used to access outer
+//! network using operating system's sockets.
+//! 
+//! "host" network represents operating system's sockets and communication counterparts that are accessed using them.
+//! 
+//! "internal" network represents senders and receivers of `BytesMut`-wrapped IP packet queues.
+
 use std::net::{IpAddr, SocketAddr};
 
 use bytes::BytesMut;
@@ -42,18 +51,40 @@ impl std::fmt::Display for NatKey {
     }
 }
 
+/// Options regarding interaction with smoltcp and host sockets.
 pub struct Opts {
+    /// If UDP datagrams are directed at this socket address then attempt to reply to a DNS request internally instead of forwarding the datagram properly
     pub dns_addr: Option<SocketAddr>,
+
+    /// If ICMP or ICMPv6 packet is directed at this address, route it to smoltcp's interface (which will reply to ICMP echo requests) instead of dropping it.
     pub pingable: Option<IpAddr>,
+
+    /// Maximum transfer unit to use for smoltcp stack
     pub mtu: usize,
+
+    /// Receive and send smoltcp TCP socket buffer sizes. Does not affect host socket buffer sizes.
     pub tcp_buffer_size: usize,
+
+    /// Listen these UDP ports and direct content into the internal network.
+    
     pub incoming_udp: Vec<PortForward>,
+
+    /// Listen these TCP ports on host and direct connections into the internal network.
     pub incoming_tcp: Vec<PortForward>,
 }
 
+/// Instructions how to forward a port from host to our internal IP network.
 pub struct PortForward {
+    /// Which socket address to use to bind the host socket to.
     pub host: SocketAddr,
+
+    /// Typically incoming connection or datagram address is also used as a source address within internal network.
+    /// Setting `src` allows you to override this and just use source fixed address.
+    /// 
+    /// If port part is `0` and this port forward is used for `incoming_tcp`, the port number is filled in with nonzero value is some way.
     pub src: Option<SocketAddr>,
+
+    /// Where within our internal network to forward connections or datagrams to.
     pub dst: SocketAddr,
 }
 
@@ -62,6 +93,9 @@ mod serve_pingable;
 mod serve_tcp;
 mod serve_udp;
 
+/// Start the router using given options and a part of channels that represent internal network.
+/// 
+/// Dropping the resulting `Future` should abort the entire router.
 pub async fn run(
     mut rx_from_wg: Receiver<BytesMut>,
     tx_to_wg: Sender<BytesMut>,

crates/libwgslirpy/src/router.rs

@@ -1,23 +1,47 @@
+//! Simplified interface to `boringtun` based on Tokio's mpsc channels.
+
 use std::{net::SocketAddr, time::Duration};
 
 use base64::Engine;
 use boringtun::noise::TunnResult;
-use boringtun::x25519::{PublicKey, StaticSecret};
+pub use boringtun::x25519::{PublicKey, StaticSecret};
 use bytes::BytesMut;
 use tokio::sync::mpsc::{Receiver, Sender};
 use tracing::{error, warn};
 
 use crate::TEAR_OF_ALLOCATION_SIZE;
 
+/// Options for being a Wireguard peer
 pub struct Opts {
+    /// Private key of this Wireguard node.
+    /// 
+    /// Use `parsebase64_32` and `into()` to specify it from a string.
     pub private_key: StaticSecret,
+
+
+    /// Public key of single Wireguard peer we are connecting to.
+    /// 
+    /// Use `parsebase64_32` and `into()` to specify it from a string.
     pub peer_key: PublicKey,
+
+    /// Static socket address of Wireguard peer to connect to.
+    /// 
+    /// If it is missing, it listens for incoming datagrams and remembers last seen `from` address
+    /// (data from which Wireguard implementation recognized) for `sendto` purposes.
     pub peer_endpoint: Option<SocketAddr>,
+
+    /// How often to send keepalive packets to the peer.
     pub keepalive_interval: Option<u16>,
+
+    /// Socket address to bind local UDP port to.
     pub bind_ip_port: SocketAddr,
 }
 
 impl Opts {
+    /// Start Wireguard implementation using this options set.
+    /// 
+    /// Received IP packets would appear at `tx_fromwg`'s channel.
+    /// IP packets to be sent to Wireguard tunnel is to be written to `rx_towg`'s channel.
     pub async fn start(
         &self,
         tx_fromwg: Sender<BytesMut>,
@@ -111,6 +135,7 @@ impl Opts {
     }
 }
 
+/// Helper funtion to simplify creating [`StaticSecret`]s and [`PublicKey`]s.
 pub fn parsebase64_32(x: &str) -> anyhow::Result<[u8; 32]> {
     let b = base64::engine::general_purpose::STANDARD.decode(x)?;
     Ok(b[..].try_into()?)