rust-mc-status 3.0.0

//! One-shot facade functions for single pings without a client.
//!
//! [`ping_java`] and [`ping_bedrock`] use a lazily-initialised process-global
//! [`McClient`] with default settings (10 s timeout, no response cache).
//!
//! Use these when you need a quick one-off ping without setting up a client.
//! For repeated pings, custom timeouts, caching, or proxy support, construct
//! a client with [`McClient::builder()`].

use tokio::sync::OnceCell;

use super::McClient;
use crate::error::McError;
use crate::status::{BedrockServerStatus, JavaServerStatus};

/// Process-global client shared by all facade calls.
/// Initialised once on first use with all-default settings.
static DEFAULT_CLIENT: OnceCell<McClient> = OnceCell::const_new();

async fn default_client() -> &'static McClient {
    DEFAULT_CLIENT
        .get_or_init(|| async { McClient::builder().build() })
        .await
}

/// Ping a Java Edition server with a single call — no client setup required.
///
/// Uses a shared global client with default settings (10 s timeout, no
/// response cache, no proxy).  For custom settings use [`McClient::builder()`].
///
/// # Errors
///
/// See [`McError`] — most commonly [`NetworkError::Timeout`](crate::error::NetworkError::Timeout)
/// or [`NetworkError::Dns`](crate::error::NetworkError::Dns).
///
/// # Example
///
/// ```rust,no_run
/// use rust_mc_status::{ping_java, StatusExt};
///
/// # #[tokio::main] async fn main() -> Result<(), rust_mc_status::McError> {
/// let status = ping_java("mc.hypixel.net").await?;
/// println!("{}", status);                     // Display: "mc.hypixel.net [42 ms] 21000/200000 — …"
/// println!("{}", status.display_players());   // "21000/200000"
/// println!("{:.1} ms", status.latency_ms());  // "42.3 ms"
/// # Ok(()) }
/// ```
pub async fn ping_java(address: impl Into<String>) -> Result<JavaServerStatus, McError> {
    default_client().await.java(address).await
}

/// Ping a Bedrock Edition server with a single call — no client setup required.
///
/// Uses a shared global client with default settings (10 s timeout, no
/// response cache, no proxy).  For custom settings use [`McClient::builder()`].
///
/// # Errors
///
/// See [`McError`] — Bedrock uses UDP so network errors may differ from Java.
///
/// # Example
///
/// ```rust,no_run
/// use rust_mc_status::{ping_bedrock, StatusExt};
///
/// # #[tokio::main] async fn main() -> Result<(), rust_mc_status::McError> {
/// let status = ping_bedrock("geo.hivebedrock.network").await?;
/// println!("{}", status.edition());           // "MCPE"
/// println!("{}", status.display_players());   // "14000/unlimited"
/// println!("{}", status.motd_clean());        // "The Hive"
/// # Ok(()) }
/// ```
pub async fn ping_bedrock(address: impl Into<String>) -> Result<BedrockServerStatus, McError> {
    default_client().await.bedrock(address).await
}