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//! - [`firewall`] - Inbound firewall-rule management (Windows; stub on other OSes)
18//! - [`health`] - Health checking for peer connectivity
19//! - [`transport`] - Overlay transport (boringtun device management via UAPI)
20//!
21//! # Example
22//!
23//! ## Initialize as cluster leader
24//!
25//! ```ignore
26//! use zlayer_overlay::bootstrap::OverlayBootstrap;
27//! use std::path::Path;
28//!
29//! let bootstrap = OverlayBootstrap::init_leader(
30//!     "10.200.0.0/16",
31//!     51820,
32//!     Path::new("/var/lib/zlayer"),
33//! ).await?;
34//!
35//! // Start the overlay network (creates boringtun TUN device)
36//! bootstrap.start().await?;
37//!
38//! println!("Overlay IP: {}", bootstrap.node_ip());
39//! println!("Public key: {}", bootstrap.public_key());
40//! ```
41//!
42//! ## Join an existing overlay
43//!
44//! ```ignore
45//! use zlayer_overlay::bootstrap::OverlayBootstrap;
46//! use std::path::Path;
47//!
48//! let bootstrap = OverlayBootstrap::join(
49//!     "10.200.0.0/16",           // Leader's CIDR
50//!     "192.168.1.100:51820",     // Leader's endpoint
51//!     "leader_public_key",       // Leader's public key
52//!     "10.200.0.1".parse()?,     // Leader's overlay IP
53//!     "10.200.0.5".parse()?,     // Our allocated IP
54//!     51820,                      // Our listen port
55//!     Path::new("/var/lib/zlayer"),
56//! ).await?;
57//!
58//! bootstrap.start().await?;
59//! ```
60//!
61//! ## With DNS service discovery
62//!
63//! ```ignore
64//! use zlayer_overlay::OverlayBootstrap;
65//! use std::path::Path;
66//!
67//! // Enable DNS service discovery on the overlay
68//! let mut bootstrap = OverlayBootstrap::init_leader(
69//!     "10.200.0.0/16",
70//!     51820,
71//!     Path::new("/var/lib/zlayer"),
72//! )
73//! .await?
74//! .with_dns("overlay.local.", 15353)?;  // Zone and port
75//!
76//! bootstrap.start().await?;
77//!
78//! // Peers are auto-registered:
79//! // - node-0-1.overlay.local -> 10.200.0.1 (leader)
80//! // - leader.overlay.local -> 10.200.0.1 (alias)
81//!
82//! // Query DNS from another machine:
83//! // dig @10.200.0.1 -p 15353 node-0-1.overlay.local
84//! ```
85//!
86//! ## Health checking
87//!
88//! ```ignore
89//! use zlayer_overlay::health::OverlayHealthChecker;
90//! use std::time::Duration;
91//!
92//! let checker = OverlayHealthChecker::new("zl-overlay0", Duration::from_secs(30));
93//!
94//! // Check all peers
95//! let health = checker.check_all().await?;
96//! println!("Healthy: {}/{}", health.healthy_peers, health.total_peers);
97//!
98//! // Start continuous monitoring
99//! checker.run(|public_key, healthy| {
100//!     println!("Peer {} is now {}", public_key, if healthy { "UP" } else { "DOWN" });
101//! }).await;
102//! ```
103
104pub mod allocator;
105pub mod bootstrap;
106pub mod config;
107pub mod dns;
108pub mod edge_cache;
109pub mod egress;
110pub mod error;
111pub mod firewall;
112pub mod gossip;
113pub mod health;
114pub mod transport;
115
116pub(crate) mod interface;
117pub(crate) mod netlink;
118pub(crate) mod tun;
119
120#[cfg(feature = "nat")]
121pub mod nat;
122
123// Re-export commonly used types
124pub use allocator::{IpAllocator, NodeSliceAllocator, NodeSliceAllocatorSnapshot};
125pub use bootstrap::{
126    BootstrapConfig, BootstrapState, OverlayBootstrap, PeerConfig, DEFAULT_INTERFACE_NAME,
127    DEFAULT_KEEPALIVE_SECS, DEFAULT_OVERLAY_CIDR, DEFAULT_SLICE_PREFIX, DEFAULT_WG_PORT,
128};
129// Re-export `ipnet` so consumers can parse CIDRs for the slice allocator
130// without needing their own direct dependency.
131pub use config::*;
132pub use dns::*;
133pub use egress::{bind_to_device, detect_physical_egress, is_virtual_interface, PhysicalEgress};
134pub use error::{OverlayError, Result};
135pub use gossip::{GossipConfig, GossipPool, TopologyEvent};
136pub use health::{OverlayHealth, OverlayHealthChecker, PeerStatus};
137pub use ipnet;
138pub use transport::*;
139
140#[cfg(feature = "nat")]
141pub use nat::{
142    Candidate, CandidateType, ConnectionType, NatConfig, NatPeerSnapshot, NatStatusSnapshot,
143    NatTraversal, RelayClient, RelayDiscovery, RelayServer, StunClient,
144};
zlayer_overlay/lib.rs

zlayer_overlay/
lib.rs
