zlayer_tunnel/
lib.rs

1//! `ZLayer` Tunnel - Secure tunneling for `ZLayer` services
2//!
3//! Provides secure tunnel functionality for accessing `ZLayer` services
4//! through authenticated tunnels, including:
5//!
6//! - **SSH to containers** - Tunnel SSH access to specific containers without exposing overlay network
7//! - **Database access** - Securely expose PostgreSQL/MySQL through tunnel with auth
8//! - **Game server tunneling** - TCP/UDP tunneling for game servers
9//! - **Node-to-node bridging** - Connect `ZLayer` nodes across different networks/datacenters
10//! - **On-demand access** - Like Cloudflare Access, users request temporary access to hidden services via CLI
11//!
12//! # Architecture
13//!
14//! The tunnel system consists of:
15//!
16//! - **Control Channel**: WebSocket over TLS for authentication and coordination
17//! - **Data Channels**: Direct TCP/UDP connections for actual traffic
18//! - **Registry**: Tracks active tunnels and their services
19//!
20//! # Protocol
21//!
22//! Uses a compact binary message format:
23//!
24//! ```text
25//! +----------+----------+----------------------------------+
26//! | Type(1)  | Len(4)   | Payload (variable)               |
27//! +----------+----------+----------------------------------+
28//! ```
29//!
30//! # Example
31//!
32//! ```rust,no_run
33//! use zlayer_tunnel::{TunnelClientConfig, ServiceConfig};
34//!
35//! // Create a client configuration
36//! let config = TunnelClientConfig::new(
37//!     "wss://tunnel.example.com/tunnel/v1",
38//!     "tun_abc123"
39//! )
40//! .with_service(ServiceConfig::tcp("ssh", 22).with_remote_port(2222))
41//! .with_service(ServiceConfig::tcp("postgres", 5432));
42//!
43//! // Validate the configuration
44//! config.validate().expect("invalid config");
45//! ```
46
47#![deny(unsafe_code)]
48#![warn(missing_docs)]
49#![warn(clippy::all)]
50#![warn(clippy::pedantic)]
51#![allow(clippy::module_name_repetitions)]
52
53pub mod access;
54pub mod client;
55pub mod config;
56pub mod error;
57pub mod node;
58pub mod overlay;
59pub mod protocol;
60pub mod server;
61
62// Re-export main types at crate root
63pub use access::{AccessManager, AccessSession, SessionInfo};
64pub use client::{
65    AgentState, ConnectionCallback, ControlCommand, ControlEvent, LocalProxy, RegisteredService,
66    ServiceStatus, TunnelAgent,
67};
68pub use config::{ServiceConfig, TunnelClientConfig, TunnelServerConfig};
69pub use error::{Result, TunnelError};
70pub use node::{NodeTunnel, NodeTunnelManager, TunnelState, TunnelStatus};
71pub use overlay::{
72    DynOverlayResolver, DynTunnelDnsRegistrar, OverlayReachability, OverlayResolver, RoutingMode,
73    TunnelDnsRegistrar,
74};
75pub use protocol::{
76    Message, MessageType, ServiceProtocol, HEADER_SIZE, MAX_MESSAGE_SIZE, PROTOCOL_VERSION,
77};
78pub use server::{
79    accept_all_tokens, hash_token, ControlHandler, ControlMessage, ListenerManager, TokenValidator,
80    Tunnel, TunnelInfo, TunnelRegistry, TunnelService,
81};
82pub use zlayer_spec::ExposeType;
zlayer_tunnel/lib.rs

zlayer_tunnel/
lib.rs
