rust_mc_status/client/
facade.rs

1//! One-shot facade functions for single pings without a client.
2//!
3//! [`ping_java`] and [`ping_bedrock`] use a lazily-initialised process-global
4//! [`McClient`] with default settings (10 s timeout, no response cache).
5//!
6//! Use these when you need a quick one-off ping without setting up a client.
7//! For repeated pings, custom timeouts, caching, or proxy support, construct
8//! a client with [`McClient::builder()`].
9
10use tokio::sync::OnceCell;
11
12use super::McClient;
13use crate::error::McError;
14use crate::status::{BedrockServerStatus, JavaServerStatus};
15
16/// Process-global client shared by all facade calls.
17/// Initialised once on first use with all-default settings.
18static DEFAULT_CLIENT: OnceCell<McClient> = OnceCell::const_new();
19
20async fn default_client() -> &'static McClient {
21    DEFAULT_CLIENT
22        .get_or_init(|| async { McClient::builder().build() })
23        .await
24}
25
26/// Ping a Java Edition server with a single call — no client setup required.
27///
28/// Uses a shared global client with default settings (10 s timeout, no
29/// response cache, no proxy).  For custom settings use [`McClient::builder()`].
30///
31/// # Errors
32///
33/// See [`McError`] — most commonly [`NetworkError::Timeout`](crate::error::NetworkError::Timeout)
34/// or [`NetworkError::Dns`](crate::error::NetworkError::Dns).
35///
36/// # Example
37///
38/// ```rust,no_run
39/// use rust_mc_status::{ping_java, StatusExt};
40///
41/// # #[tokio::main] async fn main() -> Result<(), rust_mc_status::McError> {
42/// let status = ping_java("mc.hypixel.net").await?;
43/// println!("{}", status);                     // Display: "mc.hypixel.net [42 ms] 21000/200000 — …"
44/// println!("{}", status.display_players());   // "21000/200000"
45/// println!("{:.1} ms", status.latency_ms());  // "42.3 ms"
46/// # Ok(()) }
47/// ```
48pub async fn ping_java(address: impl Into<String>) -> Result<JavaServerStatus, McError> {
49    default_client().await.java(address).await
50}
51
52/// Ping a Bedrock Edition server with a single call — no client setup required.
53///
54/// Uses a shared global client with default settings (10 s timeout, no
55/// response cache, no proxy).  For custom settings use [`McClient::builder()`].
56///
57/// # Errors
58///
59/// See [`McError`] — Bedrock uses UDP so network errors may differ from Java.
60///
61/// # Example
62///
63/// ```rust,no_run
64/// use rust_mc_status::{ping_bedrock, StatusExt};
65///
66/// # #[tokio::main] async fn main() -> Result<(), rust_mc_status::McError> {
67/// let status = ping_bedrock("geo.hivebedrock.network").await?;
68/// println!("{}", status.edition());           // "MCPE"
69/// println!("{}", status.display_players());   // "14000/unlimited"
70/// println!("{}", status.motd_clean());        // "The Hive"
71/// # Ok(()) }
72/// ```
73pub async fn ping_bedrock(address: impl Into<String>) -> Result<BedrockServerStatus, McError> {
74    default_client().await.bedrock(address).await
75}
rust_mc_status/client/facade.rs

rust_mc_status/client/
facade.rs
