relayport_rs/
lib.rs

1//! Fast and easy abstraction for proxying TCP ports.
2//!
3//! This library simplifies the creation of asynchronous TCP proxies from rust applications. The only limit on the number
4//! of proxies are the resources available on the system on which it is run. This library depends on [tokio](https::/tokio.rs)
5//! for its runtime.
6//!
7//! # Example
8//! A simple program to proxy web traffic to a server might look like this:
9//! ```no_run
10//! use std::error::Error;
11//! use tokio::sync::broadcast;
12//! use relayport_rs::RelayTcpSocket;
13//! use relayport_rs::command::RelayCommand;
14//! use tokio::signal::unix::{signal, SignalKind};
15//!
16//! #[tokio::main]
17//! pub async fn main() -> Result<(), Box<dyn Error>> {
18//!     // The relay expects a broadcast channel on which to listen for shutdown commands
19//!     let (tx, rx) = broadcast::channel(16);
20//!
21//!     // build a relay with a listener TCP socket
22//!     let relay = RelayTcpSocket::build()
23//!         .set_so_reuseaddr(true)
24//!         .set_tcp_nodelay(true)
25//!         .bind("0.0.0.0:8080")?
26//!         .listen()?;
27//!
28//!     // spawn a task to handle the acceptance and dispatch of a relay connection
29//!     let _ = tokio::task::spawn(async move {
30//!         relay
31//!             .run("127.0.0.1:80", &rx)
32//!             .await
33//!             .expect("failed to start relay")
34//!     });
35//!
36//!
37//!    // Wait for Ctrl-C to send the shutdown command
38//!    let mut sigint = signal(SignalKind::interrupt())?;
39//!    match sigint.recv().await {
40//!        Some(()) => { tx.send(RelayCommand::Shutdown)?; {} },
41//!        None => {},
42//!    }
43//!
44//!    Ok(())
45//! }
46//! ```
47//!
48//! This is the same program again, but we don't care about catching a SIGINT:
49//! ```no_run
50//! use std::error::Error;
51//! use tokio::sync::broadcast;
52//! use relayport_rs::command::RelayCommand;
53//! use relayport_rs::RelayPortError;
54//! use relayport_rs::RelayTcpSocket;
55//!
56//! #[tokio::main]
57//! pub async fn main() -> Result<(), RelayPortError> {
58//!     // The relay expects a broadcast channel on which to listen for shutdown commands
59//!     let (tx, rx) = broadcast::channel(16);
60//!
61//!     // build a relay with a listener TCP socket
62//!     let relay = RelayTcpSocket::build()
63//!         .set_so_reuseaddr(true)
64//!         .set_tcp_nodelay(true)
65//!         .bind("0.0.0.0:8080")?
66//!         .listen()?;
67//!
68//!     // spawn a task to handle the acceptance and dispatch of a relay connection
69//!     relay
70//!         .run("127.0.0.1:80", &rx)
71//!         .await
72//!
73//! }
74//! ```
75//!
76//! This program relays UDP DNS transactions to CloudFlare's DNS service:
77//! ```no_run
78//! use std::error::Error;
79//! use tokio::sync::broadcast;
80//! use relayport_rs::RelayUdpSocket;
81//! use relayport_rs::command::RelayCommand;
82//! use tokio::signal::unix::{signal, SignalKind};
83//!
84//! #[tokio::main]
85//! pub async fn main() -> Result<(), Box<dyn Error>> {
86//!     // The relay expects a broadcast channel on which to listen for shutdown commands
87//!     let (tx, rx) = broadcast::channel(16);
88//!
89//!     // build a relay with a listener TCP socket
90//!     let relay = RelayUdpSocket::build()
91//!         .set_so_reuseaddr(true)
92//!         .bind("0.0.0.0:55353")
93//!         .await?;
94//!
95//!     // spawn a task to handle the acceptance and dispatch of a relay connection
96//!     let _ = tokio::task::spawn(async move {
97//!         relay
98//!             .run("1.1.1.1:53", &rx)
99//!             .await
100//!             .expect("failed to start relay")
101//!     });
102//!
103//!
104//!    // Wait for Ctrl-C to send the shutdown command
105//!    let mut sigint = signal(SignalKind::interrupt())?;
106//!    match sigint.recv().await {
107//!        Some(()) => { tx.send(RelayCommand::Shutdown)?; {} },
108//!        None => {},
109//!    }
110//!
111//!    Ok(())
112//! }
113//! ```
114
115pub mod command;
116pub mod error;
117pub mod relay;
118pub use command::RelayCommand;
119pub use error::RelayPortError;
120pub use relay::tcp::{RelaySocket as RelayTcpSocket, RelayStream as RelayTcpStream};
121pub use relay::udp::RelaySocket as RelayUdpSocket;
relayport_rs/lib.rs

relayport_rs/
lib.rs
