triglav 0.2.0

High-performance multi-path networking tool with intelligent uplink management
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125

//! # Triglav
//!
//! High-performance multi-path VPN with intelligent uplink management.
//!
//! Triglav provides a true virtual network interface (TUN) that transparently
//! tunnels all IP traffic across multiple network paths with encryption,
//! intelligent scheduling, automatic failover, and bandwidth aggregation.
//!
//! ## Architecture
//!
//! ```text
//! ┌─────────────────────────────────────────────────────────────────┐
//! │                    Applications (Any Protocol)                   │
//! │              (TCP, UDP, ICMP, DNS, etc. - All traffic)          │
//! ├─────────────────────────────────────────────────────────────────┤
//! │                      Kernel TCP/IP Stack                         │
//! ├─────────────────────────────────────────────────────────────────┤
//! │                    TUN Virtual Interface                         │
//! │                 (utun/tun0 - Layer 3 IP packets)                 │
//! ├─────────────────────────────────────────────────────────────────┤
//! │                        TunnelRunner                              │
//! │  ┌──────────────┐  ┌─────────────┐  ┌─────────────────────────┐ │
//! │  │  IP Parser   │──│    NAT      │──│  MultipathManager       │ │
//! │  │  (5-tuple)   │  │ Translation │  │  (encryption, routing)  │ │
//! │  └──────────────┘  └─────────────┘  └─────────────────────────┘ │
//! ├─────────────────────────────────────────────────────────────────┤
//! │                   Multi-Path Connection Manager                  │
//! │  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐         │
//! │  │ Uplink 1 │  │ Uplink 2 │  │ Uplink 3 │  │ Uplink N │         │
//! │  │  (WiFi)  │  │(Cellular)│  │(Ethernet)│  │   ...    │         │
//! │  └──────────┘  └──────────┘  └──────────┘  └──────────┘         │
//! ├─────────────────────────────────────────────────────────────────┤
//! │              Quality Metrics & Prediction Engine                 │
//! ├─────────────────────────────────────────────────────────────────┤
//! │                    Noise NK Encryption Layer                     │
//! ├─────────────────────────────────────────────────────────────────┤
//! │               Transport (UDP Fast Path / TCP Fallback)           │
//! └─────────────────────────────────────────────────────────────────┘
//! ```
//!
//! ## Key Features
//!
//! - **True VPN**: Virtual TUN interface captures all IP traffic transparently
//! - **Multi-path**: Aggregate bandwidth across WiFi, cellular, ethernet
//! - **ECMP-aware**: Flow-based routing maintains TCP connection consistency
//! - **Encrypted**: Noise NK protocol with per-uplink sessions
//! - **NAT traversal**: Works behind NATs with Dublin Traceroute-style probing
//! - **Cross-platform**: Linux, macOS, Windows support

#![warn(clippy::all, clippy::pedantic, clippy::nursery)]
// Allow stylistic lints that don't affect correctness
#![allow(clippy::module_name_repetitions)]
#![allow(clippy::must_use_candidate)]
#![allow(clippy::missing_errors_doc)]
#![allow(clippy::missing_panics_doc)]
#![allow(clippy::missing_const_for_fn)] // Many functions can't be const due to trait bounds
#![allow(clippy::doc_markdown)] // ASCII diagrams in docs
#![allow(clippy::unreadable_literal)] // Numeric literals are clear
#![allow(clippy::cast_possible_truncation)] // Intentional score calculations
#![allow(clippy::cast_sign_loss)] // Scores are always positive
#![allow(clippy::cast_precision_loss)] // Acceptable for stats
#![allow(clippy::cast_possible_wrap)] // Intentional for sequence arithmetic
#![allow(clippy::suboptimal_flops)] // Clarity over micro-optimization
#![allow(clippy::similar_names)] // state/stats are intentionally named
#![allow(clippy::significant_drop_tightening)] // Lock ordering is intentional
#![allow(clippy::option_if_let_else)] // More readable in context
#![allow(clippy::use_self)] // Explicit type names in matches
#![allow(clippy::redundant_pub_crate)] // Explicit visibility
#![allow(clippy::cognitive_complexity)] // Complex state machines
#![allow(clippy::too_many_lines)] // Complete implementations
#![allow(clippy::future_not_send)] // Async internals
#![allow(clippy::struct_excessive_bools)] // Boolean config fields are appropriate
#![allow(clippy::match_same_arms)] // Explicit arm per variant is clearer
#![allow(clippy::return_self_not_must_use)] // Builder methods don't need must_use
#![allow(clippy::ignored_unit_patterns)] // Ok(_) vs Ok(()) is stylistic

pub mod config;
pub mod crypto;
pub mod error;
pub mod metrics;
pub mod multipath;
pub mod protocol;
pub mod proxy;
pub mod server;
pub mod transport;
pub mod tun;
pub mod types;
pub mod util;

#[cfg(feature = "cli")]
pub mod cli;

pub use config::Config;
pub use error::{Error, Result};
pub use types::*;

/// Library version
pub const VERSION: &str = env!("CARGO_PKG_VERSION");

/// Protocol version for wire compatibility
pub const PROTOCOL_VERSION: u8 = 1;

/// Maximum transmission unit for packets
pub const MAX_MTU: usize = 1500;

/// Maximum payload size after encryption overhead
pub const MAX_PAYLOAD: usize = MAX_MTU - 64; // Reserve space for headers + auth tag

/// Default port for Triglav server
pub const DEFAULT_PORT: u16 = 7443;

/// Prelude module for convenient imports
pub mod prelude {
    pub use crate::config::Config;
    pub use crate::crypto::{KeyPair, PublicKey, SecretKey};
    pub use crate::error::{Error, Result};
    pub use crate::metrics::QualityMetrics;
    pub use crate::multipath::{MultipathManager, Uplink};
    pub use crate::protocol::{Message, Packet};
    pub use crate::proxy::{HttpProxyConfig, HttpProxyServer, Socks5Config, Socks5Server};
    pub use crate::transport::{Transport, TransportConfig};
    pub use crate::tun::{TunConfig, TunDevice, TunnelConfig, TunnelRunner};
    pub use crate::types::UplinkId;
    pub use crate::types::*;
}