rust_mc_status/proxy/mod.rs
1//! Proxy configuration for routing Minecraft pings through SOCKS5 or HTTP
2//! CONNECT proxies.
3//!
4//! Enabled with `features = ["proxy"]` in `Cargo.toml`.
5//!
6//! # Supported proxy types
7//!
8//! | Constructor | Protocol | UDP (Bedrock) | Auth |
9//! |-------------|----------|--------------|------|
10//! | [`ProxyConfig::socks5`] | SOCKS5 | No | optional |
11//! | [`ProxyConfig::socks5_with_udp`] | SOCKS5 + UDP ASSOCIATE | Yes | optional |
12//! | [`ProxyConfig::http`] | HTTP CONNECT | No | optional (Basic) |
13//!
14//! # Quick start
15//!
16//! ```rust,no_run
17//! use rust_mc_status::{McClient, ProxyConfig};
18//!
19//! # #[tokio::main] async fn main() -> Result<(), rust_mc_status::McError> {
20//! // Anonymous SOCKS5
21//! let client = McClient::builder()
22//! .proxy(ProxyConfig::socks5("127.0.0.1:1080"))
23//! .build();
24//!
25//! // Authenticated HTTP CONNECT
26//! let client = McClient::builder()
27//! .proxy(ProxyConfig::http("squid.corp.example.com:3128")
28//! .with_auth("alice", "s3cr3t"))
29//! .build();
30//! # Ok(()) }
31//! ```
32//!
33//! # Bedrock and UDP
34//!
35//! Bedrock Edition uses UDP (RakNet). Most SOCKS5 proxies and **all** HTTP
36//! CONNECT proxies do not support UDP. Attempting a Bedrock ping through such
37//! a proxy returns
38//! [`McError::Proxy(ProxyError::UdpUnsupported)`](crate::error::ProxyError)
39//! immediately without making a network connection.
40//!
41//! Use [`ProxyConfig::socks5_with_udp`] only when your proxy server actually
42//! advertises UDP ASSOCIATE support (e.g. `dante` with `udp_relay yes`,
43//! or a `tun2socks` setup).
44
45pub mod socks5;
46#[cfg(feature = "proxy")]
47pub mod http;
48
49pub use socks5::{ProxyConfig, ProxyAuth, ProxyAddr, ProxyKind, UdpSupport};