zlayer_overlay/
lib.rs

1//! `ZLayer` Overlay - Encrypted overlay networking via boringtun
2//!
3//! Provides encrypted overlay networks using boringtun (Cloudflare's Rust userspace
4//! `WireGuard` implementation) with DNS service discovery, automatic bootstrap on
5//! node init/join, IP allocation, and health checking.
6//!
7//! No kernel `WireGuard` module or wireguard-tools required -- uses TUN devices
8//! (Linux `/dev/net/tun`, macOS `utun`) and configures peers via the UAPI protocol.
9//!
10//! # Modules
11//!
12//! - [`allocator`] - IP address allocation for overlay networks
13//! - [`bootstrap`] - Overlay network initialization and joining
14//! - [`config`] - Configuration types for overlay networks
15//! - [`dns`] - DNS server for service discovery
16//! - [`error`] - Error types for overlay operations
17//! - [`health`] - Health checking for peer connectivity
18//! - [`transport`] - Overlay transport (boringtun device management via UAPI)
19//!
20//! # Example
21//!
22//! ## Initialize as cluster leader
23//!
24//! ```ignore
25//! use zlayer_overlay::bootstrap::OverlayBootstrap;
26//! use std::path::Path;
27//!
28//! let bootstrap = OverlayBootstrap::init_leader(
29//!     "10.200.0.0/16",
30//!     51820,
31//!     Path::new("/var/lib/zlayer"),
32//! ).await?;
33//!
34//! // Start the overlay network (creates boringtun TUN device)
35//! bootstrap.start().await?;
36//!
37//! println!("Overlay IP: {}", bootstrap.node_ip());
38//! println!("Public key: {}", bootstrap.public_key());
39//! ```
40//!
41//! ## Join an existing overlay
42//!
43//! ```ignore
44//! use zlayer_overlay::bootstrap::OverlayBootstrap;
45//! use std::path::Path;
46//!
47//! let bootstrap = OverlayBootstrap::join(
48//!     "10.200.0.0/16",           // Leader's CIDR
49//!     "192.168.1.100:51820",     // Leader's endpoint
50//!     "leader_public_key",       // Leader's public key
51//!     "10.200.0.1".parse()?,     // Leader's overlay IP
52//!     "10.200.0.5".parse()?,     // Our allocated IP
53//!     51820,                      // Our listen port
54//!     Path::new("/var/lib/zlayer"),
55//! ).await?;
56//!
57//! bootstrap.start().await?;
58//! ```
59//!
60//! ## With DNS service discovery
61//!
62//! ```ignore
63//! use zlayer_overlay::OverlayBootstrap;
64//! use std::path::Path;
65//!
66//! // Enable DNS service discovery on the overlay
67//! let mut bootstrap = OverlayBootstrap::init_leader(
68//!     "10.200.0.0/16",
69//!     51820,
70//!     Path::new("/var/lib/zlayer"),
71//! )
72//! .await?
73//! .with_dns("overlay.local.", 15353)?;  // Zone and port
74//!
75//! bootstrap.start().await?;
76//!
77//! // Peers are auto-registered:
78//! // - node-0-1.overlay.local -> 10.200.0.1 (leader)
79//! // - leader.overlay.local -> 10.200.0.1 (alias)
80//!
81//! // Query DNS from another machine:
82//! // dig @10.200.0.1 -p 15353 node-0-1.overlay.local
83//! ```
84//!
85//! ## Health checking
86//!
87//! ```ignore
88//! use zlayer_overlay::health::OverlayHealthChecker;
89//! use std::time::Duration;
90//!
91//! let checker = OverlayHealthChecker::new("zl-overlay0", Duration::from_secs(30));
92//!
93//! // Check all peers
94//! let health = checker.check_all().await?;
95//! println!("Healthy: {}/{}", health.healthy_peers, health.total_peers);
96//!
97//! // Start continuous monitoring
98//! checker.run(|public_key, healthy| {
99//!     println!("Peer {} is now {}", public_key, if healthy { "UP" } else { "DOWN" });
100//! }).await;
101//! ```
102
103pub mod allocator;
104pub mod bootstrap;
105pub mod config;
106pub mod dns;
107pub mod error;
108pub mod health;
109pub mod transport;
110
111#[cfg(target_os = "linux")]
112pub(crate) mod netlink;
113
114#[cfg(feature = "nat")]
115pub mod nat;
116
117// Re-export commonly used types
118pub use allocator::IpAllocator;
119pub use bootstrap::{
120    BootstrapConfig, BootstrapState, OverlayBootstrap, PeerConfig, DEFAULT_INTERFACE_NAME,
121    DEFAULT_KEEPALIVE_SECS, DEFAULT_OVERLAY_CIDR, DEFAULT_WG_PORT,
122};
123pub use config::*;
124pub use dns::*;
125pub use error::{OverlayError, Result};
126pub use health::{OverlayHealth, OverlayHealthChecker, PeerStatus};
127pub use transport::*;
128
129#[cfg(feature = "nat")]
130pub use nat::{
131    Candidate, CandidateType, ConnectionType, NatConfig, NatTraversal, RelayClient, RelayDiscovery,
132    RelayServer, StunClient,
133};
zlayer_overlay/lib.rs

zlayer_overlay/
lib.rs
