rust-mc-status 3.0.0

#![cfg_attr(docsrs, feature(doc_cfg))]
//! # rust-mc-status
//!
//! High-performance asynchronous Rust library for querying Minecraft server
//! status — Java Edition and Bedrock Edition.
//!
//! ## Quick start
//!
//! ```rust,no_run
//! use rust_mc_status::{ping_java, ping_bedrock, StatusExt};
//!
//! #[tokio::main]
//! async fn main() -> Result<(), rust_mc_status::McError> {
//!     // One-shot facade — no setup required
//!     let java = ping_java("mc.hypixel.net").await?;
//!     println!("{} — {} ms", java.motd_clean(), java.latency_ms() as u32);
//!
//!     let bedrock = ping_bedrock("geo.hivebedrock.network").await?;
//!     println!("{} [{}]", bedrock.motd_clean(), bedrock.edition());
//!     Ok(())
//! }
//! ```
//!
//! ## Using a client
//!
//! Build a [`McClient`] when you need custom timeouts, caching, or a proxy.
//! `McClient::builder()` is the **only** constructor — there is no `new()`.
//!
//! ```rust,no_run
//! use rust_mc_status::{McClient, StatusExt};
//! use std::time::Duration;
//!
//! #[tokio::main]
//! async fn main() -> Result<(), rust_mc_status::McError> {
//!     let client = McClient::builder()
//!         .timeout(Duration::from_secs(5))
//!         .max_parallel(20)
//!         .response_cache(Duration::from_secs(30), 256)
//!         .build();
//!
//!     let status = client.java("mc.hypixel.net").await?;
//!     println!("{}", status.display_players()); // "21000/200000"
//!     println!("{:.0} ms", status.latency_ms());
//!     println!("cached: {}", status.is_cached());
//!     Ok(())
//! }
//! ```
//!
//! ## Batch pings
//!
//! [`McClient::ping_many`] pings multiple servers concurrently using a
//! semaphore — slow or timed-out servers never block the rest.
//!
//! ```rust,no_run
//! use rust_mc_status::{McClient, ServerEdition, ServerInfo};
//!
//! #[tokio::main]
//! async fn main() -> Result<(), rust_mc_status::McError> {
//!     let client = McClient::builder().max_parallel(10).build();
//!     let servers = vec![
//!         ServerInfo { address: "mc.hypixel.net".into(), edition: ServerEdition::Java },
//!         ServerInfo { address: "geo.hivebedrock.network".into(), edition: ServerEdition::Bedrock },
//!     ];
//!     for (server, result) in client.ping_many(&servers).await {
//!         match result {
//!             Ok(s)  => println!("{} — {} ms", server.address, s.latency),
//!             Err(e) => println!("{} — ❌ {e}", server.address),
//!         }
//!     }
//!     Ok(())
//! }
//! ```
//!
//! ## Error handling
//!
//! [`McError`] is a two-level hierarchy — match broadly or drill into details:
//!
//! ```rust,no_run
//! use rust_mc_status::{McClient, McError, StatusExt};
//! use rust_mc_status::error::{NetworkError, ProtocolError};
//!
//! #[tokio::main]
//! async fn main() {
//!     let client = McClient::builder().build();
//!     match client.java("mc.hypixel.net").await {
//!         Ok(s) => println!("online: {}", s.display_players()),
//!         Err(McError::Network(NetworkError::Timeout))       => println!("timed out"),
//!         Err(McError::Network(NetworkError::Dns(msg)))      => println!("DNS: {msg}"),
//!         Err(McError::Protocol(ProtocolError::InvalidResponse(msg))) => println!("bad packet: {msg}"),
//!         Err(e) => println!("other: {e}"),
//!     }
//! }
//! ```
//!
//! ## Optional features
//!
//! | Feature | What it adds |
//! |---------|-------------|
//! | `proxy` | SOCKS5 and HTTP CONNECT proxy support via [`ProxyConfig`] |
//! | `tower` | [`McService`] — wrap `McClient` in Tower middleware (retries, rate-limiting, etc.) |
//! | `full`  | Both `proxy` and `tower` |
//!
//! ```toml
//! [dependencies]
//! rust-mc-status = { version = "3", features = ["full"] }
//! ```
//!
//! ## Crate structure
//!
//! | Module | Contents |
//! |--------|----------|
//! | *(root)* | [`McClient`], [`McClientBuilder`], [`ping_java`], [`ping_bedrock`] |
//! | [`error`] | [`McError`] and sub-error types |
//! | [`models`] | [`ServerStatus`], [`ServerData`], [`JavaStatus`], [`BedrockStatus`], etc. |
//! | [`status`] | [`JavaServerStatus`], [`BedrockServerStatus`], [`StatusExt`] trait |
//! | [`proxy`] | [`ProxyConfig`] *(feature = "proxy")* |
//! | [`service`] | [`McService`], [`McRetryPolicy`] *(feature = "tower")* |
//! | [`core`] | Internal DNS resolver, response cache, address parser *(not stable API)* |

pub mod core;
pub mod client;
pub mod error;
pub mod models;
pub mod protocol;
pub mod proxy;
pub mod status;

#[cfg(feature = "tower")]
#[cfg_attr(docsrs, doc(cfg(feature = "tower")))]
pub mod service;

pub use client::{McClient, McClientBuilder, ping_java, ping_bedrock};
pub use client::{JavaPingBuilder, BedrockPingBuilder, ServerPingBuilder};
pub use error::{McError, NetworkError, ProtocolError, ConfigError};
#[cfg(feature = "proxy")]
#[cfg_attr(docsrs, doc(cfg(feature = "proxy")))]
pub use error::ProxyError;
pub use models::*;
pub use models::CacheStats;
pub use models::{PingResult, LegacyData, QueryData};
pub use proxy::{ProxyConfig, ProxyKind};
pub use status::{JavaServerStatus, BedrockServerStatus, StatusExt, strip_formatting, truncate_str};

#[cfg(feature = "tower")]
#[cfg_attr(docsrs, doc(cfg(feature = "tower")))]
pub use service::{McService, McRetryPolicy, PingRequestTower, PingResponseTower};