ferrotunnel 1.5.0

A production-ready reverse tunnel system in Rust
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

//! # `FerroTunnel`
//!
//! A production-ready, secure reverse tunnel system in Rust.
//!
//! `FerroTunnel` is the **first embeddable Rust reverse tunnel**, allowing you to
//! integrate tunneling directly into your applications with a simple builder API.
//!
//! ## Features
//!
//! - 🔒 **Secure** - Token-based authentication
//! - ⚡ **Fast** - Built on Tokio for high-performance async I/O
//! - 🔌 **Embeddable** - Use as a library in your own applications
//! - 🛡️ **Resilient** - Automatic reconnection, heartbeat monitoring
//!
//! ## Quick Start: Embedded Client
//!
//! ```rust,no_run
//! use ferrotunnel::Client;
//!
//! #[tokio::main]
//! async fn main() -> ferrotunnel::Result<()> {
//!     let mut client = Client::builder()
//!         .server_addr("tunnel.example.com:7835")
//!         .token("my-secret-token")
//!         .local_addr("127.0.0.1:8080")
//!         .build()?;
//!
//!     let info = client.start().await?;
//!     println!("Connected! Session: {:?}", info.session_id());
//!
//!     // Keep running until Ctrl+C
//!     tokio::signal::ctrl_c().await?;
//!     client.shutdown().await?;
//!     Ok(())
//! }
//! ```
//!
//! ## Quick Start: Embedded Server
//!
//! ```rust,no_run
//! use ferrotunnel::Server;
//!
//! #[tokio::main]
//! async fn main() -> ferrotunnel::Result<()> {
//!     let mut server = Server::builder()
//!         .bind("0.0.0.0:7835".parse().unwrap())
//!         .http_bind("0.0.0.0:8080".parse().unwrap())
//!         .token("my-secret-token")
//!         .build()?;
//!
//!     server.start().await?;
//!     tokio::signal::ctrl_c().await?;
//!     server.shutdown().await?;
//!     Ok(())
//! }
//! ```
//!
//! ## Architecture
//!
//! `FerroTunnel` consists of several crates:
//!
//! - `ferrotunnel` - Main library with builder API (this crate)
//! - `ferrotunnel-common` - Shared types, errors, and utilities
//! - `ferrotunnel-protocol` - Wire protocol definitions and codec
//! - `ferrotunnel-core` - Core tunnel implementation
//! - `ferrotunnel-http` - HTTP ingress and proxy
//!
//! ## Re-exports
//!
//! This crate re-exports the most commonly used items from the subcrates
//! for convenience.

// Modules
pub mod client;
pub mod config;
pub mod server;

// Re-export the shared vocabulary crate (errors, `Result`, config types).
pub use ferrotunnel_common as common;

// Implementation crates are re-exported for advanced use but are not part of
// the stable public API surface, so they are hidden from the generated docs.
// The prelude re-exports the specific protocol types intended for public use.
#[doc(hidden)]
pub use ferrotunnel_core as core;
#[doc(hidden)]
pub use ferrotunnel_http as http;
#[doc(hidden)]
pub use ferrotunnel_protocol as protocol;

// Public API exports
pub use client::{Client, ClientBuilder};
pub use config::{ClientConfig, ServerConfig, TunnelInfo};
pub use server::{Server, ServerBuilder};

/// Prelude module for convenient imports
pub mod prelude {
    // Builder API
    pub use crate::client::{Client, ClientBuilder};
    pub use crate::config::{ClientConfig, ServerConfig, TunnelInfo};
    pub use crate::server::{Server, ServerBuilder};

    // Common types
    pub use crate::common::{Result, TunnelError};

    // Protocol types
    pub use crate::protocol::{
        CloseReason, Frame, HandshakeStatus, Protocol, RegisterStatus, StreamStatus, TunnelCodec,
    };
}

// Convenience re-exports at crate root
pub use common::{Result, TunnelError};
pub use protocol::{
    CloseReason, Frame, HandshakeStatus, Protocol, RegisterStatus, StreamStatus, TunnelCodec,
};