rust_mc_status/

models.rs

//! Data models for Minecraft server status responses.
//!
//! This module provides structured data types for representing server status
//! information from both Java Edition and Bedrock Edition servers.
//!
//! # Examples
//!
//! ## Basic Usage
//!
//! ```no_run
//! use rust_mc_status::{McClient, ServerEdition};
//!
//! # #[tokio::main]
//! # async fn main() -> Result<(), Box<dyn std::error::Error>> {
//! let client = McClient::new();
//! let status = client.ping("mc.hypixel.net", ServerEdition::Java).await?;
//!
//! println!("Server: {}:{}", status.ip, status.port);
//! println!("Online: {}", status.online);
//! println!("Latency: {:.2}ms", status.latency);
//!
//! match status.data {
//!     rust_mc_status::ServerData::Java(java) => {
//!         println!("Players: {}/{}", java.players.online, java.players.max);
//!     }
//!     rust_mc_status::ServerData::Bedrock(bedrock) => {
//!         println!("Players: {}/{}", bedrock.online_players, bedrock.max_players);
//!     }
//! }
//! # Ok(())
//! # }
//! ```

use std::fmt;
use std::fs::File;
use std::io::Write;

use base64::{engine::general_purpose, Engine as _};
use serde::{Deserialize, Serialize};
use serde_json::Value;

use crate::McError;

/// Server status information.
///
/// This structure contains all information about a Minecraft server's status.
/// Even if the server is offline, some fields may still be populated (e.g., DNS info).
///
/// # Example
///
/// ```no_run
/// use rust_mc_status::{McClient, ServerEdition};
///
/// # #[tokio::main]
/// # async fn main() -> Result<(), Box<dyn std::error::Error>> {
/// let client = McClient::new();
/// let status = client.ping("mc.hypixel.net", ServerEdition::Java).await?;
///
/// println!("Hostname: {}", status.hostname);
/// println!("IP: {}", status.ip);
/// println!("Port: {}", status.port);
/// println!("Online: {}", status.online);
/// println!("Latency: {:.2}ms", status.latency);
/// # Ok(())
/// # }
/// ```
#[derive(Debug, Serialize, Deserialize, Clone)]
pub struct ServerStatus {
    /// Whether the server is online and responding.
    ///
    /// This field is always `true` for successful pings. If the server
    /// is offline or unreachable, the `ping()` method returns an error instead.
    pub online: bool,

    /// Resolved IP address of the server.
    ///
    /// This is the actual IP address that was connected to, which may differ
    /// from the hostname if SRV records were used or if the hostname resolves
    /// to multiple IP addresses.
    ///
    /// Example: `"172.65.197.160"`
    pub ip: String,

    /// Port number of the server.
    ///
    /// This is the actual port that was connected to. For Java servers, this
    /// may differ from the default port (25565) if an SRV record was found.
    ///
    /// Example: `25565` (Java) or `19132` (Bedrock)
    pub port: u16,

    /// Original hostname used for the query.
    ///
    /// This is the hostname that was provided to the `ping()` method, before
    /// any DNS resolution or SRV lookup.
    ///
    /// Example: `"mc.hypixel.net"`
    pub hostname: String,

    /// Latency in milliseconds.
    ///
    /// This is the round-trip time (RTT) from sending the ping request to
    /// receiving the response. Lower values indicate better network connectivity.
    ///
    /// Example: `45.23` (45.23 milliseconds)
    pub latency: f64,

    /// Optional DNS information (A records, CNAME, TTL).
    ///
    /// This field contains DNS resolution details if available. It may be `None`
    /// if DNS information could not be retrieved or if an IP address was used
    /// directly instead of a hostname.
    pub dns: Option<DnsInfo>,

    /// Server data (Java or Bedrock specific information).
    ///
    /// This field contains edition-specific server information including version,
    /// players, plugins, mods, and more. Use pattern matching to access the data:
    ///
    /// ```no_run
    /// # use rust_mc_status::ServerData;
    /// # let data = ServerData::Java(rust_mc_status::JavaStatus {
    /// #     version: rust_mc_status::JavaVersion { name: "1.20.1".to_string(), protocol: 763 },
    /// #     players: rust_mc_status::JavaPlayers { online: 0, max: 100, sample: None },
    /// #     description: "".to_string(),
    /// #     favicon: None,
    /// #     map: None,
    /// #     gamemode: None,
    /// #     software: None,
    /// #     plugins: None,
    /// #     mods: None,
    /// #     raw_data: serde_json::Value::Null,
    /// # });
    /// match data {
    ///     ServerData::Java(java) => println!("Java server: {}", java.version.name),
    ///     ServerData::Bedrock(bedrock) => println!("Bedrock server: {}", bedrock.version),
    /// }
    /// ```
    pub data: ServerData,
}

impl ServerStatus {
    /// Get player count information.
    ///
    /// Returns a tuple of `(online, max)` players, or `None` if not available.
    ///
    /// # Example
    ///
    /// ```no_run
    /// # use rust_mc_status::{McClient, ServerEdition};
    /// # #[tokio::main]
    /// # async fn main() -> Result<(), Box<dyn std::error::Error>> {
    /// # let client = McClient::new();
    /// # let status = client.ping("mc.hypixel.net", ServerEdition::Java).await?;
    /// if let Some((online, max)) = status.players() {
    ///     println!("Players: {}/{}", online, max);
    /// }
    /// # Ok(())
    /// # }
    /// ```
    pub fn players(&self) -> Option<(i64, i64)> {
        match &self.data {
            ServerData::Java(java) => Some((java.players.online, java.players.max)),
            ServerData::Bedrock(bedrock) => {
                let online = bedrock.online_players.parse().ok()?;
                let max = bedrock.max_players.parse().ok()?;
                Some((online, max))
            }
        }
    }
}

/// Server data (Java or Bedrock specific).
///
/// This enum contains edition-specific server information.
#[derive(Debug, Serialize, Deserialize, Clone)]
#[serde(untagged)]
pub enum ServerData {
    /// Java Edition server data.
    Java(JavaStatus),
    /// Bedrock Edition server data.
    Bedrock(BedrockStatus),
}

impl ServerData {
    /// Get player count if available.
    ///
    /// Returns `(online, max)` for Java servers, or parsed values for Bedrock servers.
    pub fn players(&self) -> Option<(i64, i64)> {
        match self {
            ServerData::Java(java) => Some((java.players.online, java.players.max)),
            ServerData::Bedrock(bedrock) => {
                let online = bedrock.online_players.parse().ok()?;
                let max = bedrock.max_players.parse().ok()?;
                Some((online, max))
            }
        }
    }
}

/// DNS information about the server.
///
/// Contains resolved A records, optional CNAME, and TTL information.
/// This information is retrieved during DNS resolution and cached for 5 minutes.
///
/// # Example
///
/// ```no_run
/// use rust_mc_status::{McClient, ServerEdition};
///
/// # #[tokio::main]
/// # async fn main() -> Result<(), Box<dyn std::error::Error>> {
/// let client = McClient::new();
/// let status = client.ping("mc.hypixel.net", ServerEdition::Java).await?;
///
/// if let Some(dns) = status.dns {
///     println!("A records: {:?}", dns.a_records);
///     if let Some(cname) = dns.cname {
///         println!("CNAME: {}", cname);
///     }
///     println!("TTL: {} seconds", dns.ttl);
/// }
/// # Ok(())
/// # }
/// ```
#[derive(Debug, Serialize, Deserialize, Clone)]
pub struct DnsInfo {
    /// A record IP addresses.
    ///
    /// This is a list of IPv4 and IPv6 addresses that the hostname resolves to.
    /// Typically contains one or more IP addresses.
    ///
    /// Example: `vec!["172.65.197.160".to_string()]`
    pub a_records: Vec<String>,

    /// Optional CNAME record.
    ///
    /// If the hostname is a CNAME (canonical name), this field contains the
    /// canonical hostname. Most servers don't use CNAME records.
    ///
    /// Example: `Some("canonical.example.com".to_string())`
    pub cname: Option<String>,

    /// Time-to-live in seconds.
    ///
    /// This is the DNS cache TTL used by the library. DNS records are cached
    /// for this duration to improve performance.
    ///
    /// Default: `300` (5 minutes)
    pub ttl: u32,
}

/// Java Edition server status.
///
/// Contains detailed information about a Java Edition server, including version,
/// players, plugins, mods, and more.
///
/// # Example
///
/// ```no_run
/// use rust_mc_status::{McClient, ServerEdition};
///
/// # #[tokio::main]
/// # async fn main() -> Result<(), Box<dyn std::error::Error>> {
/// let client = McClient::new();
/// let status = client.ping("mc.hypixel.net", ServerEdition::Java).await?;
///
/// if let rust_mc_status::ServerData::Java(java) = status.data {
///     println!("Version: {}", java.version.name);
///     println!("Players: {}/{}", java.players.online, java.players.max);
///     println!("Description: {}", java.description);
///     
///     if let Some(plugins) = &java.plugins {
///         println!("Plugins: {}", plugins.len());
///     }
/// }
/// # Ok(())
/// # }
/// ```
#[derive(Serialize, Deserialize, Clone)]
pub struct JavaStatus {
    /// Server version information.
    pub version: JavaVersion,
    /// Player information.
    pub players: JavaPlayers,
    /// Server description (MOTD).
    pub description: String,
    /// Base64-encoded favicon (PNG image data).
    #[serde(skip_serializing)]
    pub favicon: Option<String>,
    /// Current map name.
    pub map: Option<String>,
    /// Game mode.
    pub gamemode: Option<String>,
    /// Server software (e.g., "Paper", "Spigot", "Vanilla").
    pub software: Option<String>,
    /// List of installed plugins.
    pub plugins: Option<Vec<JavaPlugin>>,
    /// List of installed mods.
    pub mods: Option<Vec<JavaMod>>,
    /// Raw JSON data from server response.
    #[serde(skip)]
    pub raw_data: Value,
}

impl JavaStatus {
    /// Save the server favicon to a file.
    ///
    /// The favicon is decoded from base64 and saved as a PNG image.
    ///
    /// # Arguments
    ///
    /// * `filename` - Path where the favicon should be saved
    ///
    /// # Errors
    ///
    /// Returns an error if:
    /// - No favicon is available
    /// - Base64 decoding fails
    /// - File I/O fails
    ///
    /// # Example
    ///
    /// ```no_run
    /// use rust_mc_status::{McClient, ServerEdition};
    ///
    /// # #[tokio::main]
    /// # async fn main() -> Result<(), Box<dyn std::error::Error>> {
    /// let client = McClient::new();
    /// let status = client.ping("mc.hypixel.net", ServerEdition::Java).await?;
    ///
    /// if let rust_mc_status::ServerData::Java(java) = status.data {
    ///     java.save_favicon("server_icon.png")?;
    /// }
    /// # Ok(())
    /// # }
    /// ```
    pub fn save_favicon(&self, filename: &str) -> Result<(), McError> {
        if let Some(favicon) = &self.favicon {
            let data = favicon.split(',').nth(1).unwrap_or(favicon);
            let bytes = general_purpose::STANDARD
                .decode(data)
                .map_err(McError::Base64Error)?;

            let mut file = File::create(filename).map_err(McError::IoError)?;
            file.write_all(&bytes).map_err(McError::IoError)?;

            Ok(())
        } else {
            Err(McError::InvalidResponse("No favicon available".to_string()))
        }
    }
}

impl fmt::Debug for JavaStatus {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.debug_struct("JavaStatus")
            .field("version", &self.version)
            .field("players", &self.players)
            .field("description", &self.description)
            .field("map", &self.map)
            .field("gamemode", &self.gamemode)
            .field("software", &self.software)
            .field("plugins", &self.plugins.as_ref().map(|p| p.len()))
            .field("mods", &self.mods.as_ref().map(|m| m.len()))
            .field("favicon", &self.favicon.as_ref().map(|_| "[Favicon data]"))
            .field("raw_data", &"[Value]")
            .finish()
    }
}

/// Java Edition server version information.
#[derive(Debug, Serialize, Deserialize, Clone)]
pub struct JavaVersion {
    /// Version name (e.g., "1.20.1").
    pub name: String,
    /// Protocol version number.
    pub protocol: i64,
}

/// Java Edition player information.
#[derive(Debug, Serialize, Deserialize, Clone)]
pub struct JavaPlayers {
    /// Number of players currently online.
    pub online: i64,
    /// Maximum number of players.
    pub max: i64,
    /// Sample of online players (if provided by server).
    pub sample: Option<Vec<JavaPlayer>>,
}

/// Java Edition player sample.
#[derive(Debug, Serialize, Deserialize, Clone)]
pub struct JavaPlayer {
    /// Player name.
    pub name: String,
    /// Player UUID.
    pub id: String,
}

/// Java Edition plugin information.
#[derive(Debug, Serialize, Deserialize, Clone)]
pub struct JavaPlugin {
    /// Plugin name.
    pub name: String,
    /// Plugin version (if available).
    pub version: Option<String>,
}

/// Java Edition mod information.
#[derive(Debug, Serialize, Deserialize, Clone)]
pub struct JavaMod {
    /// Mod ID.
    pub modid: String,
    /// Mod version (if available).
    pub version: Option<String>,
}

/// Bedrock Edition server status.
///
/// Contains information about a Bedrock Edition server.
///
/// # Example
///
/// ```no_run
/// use rust_mc_status::{McClient, ServerEdition};
///
/// # #[tokio::main]
/// # async fn main() -> Result<(), Box<dyn std::error::Error>> {
/// let client = McClient::new();
/// let status = client.ping("geo.hivebedrock.network:19132", ServerEdition::Bedrock).await?;
///
/// if let rust_mc_status::ServerData::Bedrock(bedrock) = status.data {
///     println!("Edition: {}", bedrock.edition);
///     println!("Version: {}", bedrock.version);
///     println!("Players: {}/{}", bedrock.online_players, bedrock.max_players);
///     println!("MOTD: {}", bedrock.motd);
/// }
/// # Ok(())
/// # }
/// ```
#[derive(Serialize, Deserialize, Clone)]
pub struct BedrockStatus {
    /// Minecraft edition (e.g., "MCPE").
    pub edition: String,
    /// Message of the day.
    pub motd: String,
    /// Protocol version.
    pub protocol_version: String,
    /// Server version.
    pub version: String,
    /// Number of online players (as string).
    pub online_players: String,
    /// Maximum number of players (as string).
    pub max_players: String,
    /// Server UID.
    pub server_uid: String,
    /// Secondary MOTD.
    pub motd2: String,
    /// Game mode.
    pub game_mode: String,
    /// Game mode numeric value.
    pub game_mode_numeric: String,
    /// IPv4 port.
    pub port_ipv4: String,
    /// IPv6 port.
    pub port_ipv6: String,
    /// Current map name.
    pub map: Option<String>,
    /// Server software.
    pub software: Option<String>,
    /// Raw response data.
    pub raw_data: String,
}

impl fmt::Debug for BedrockStatus {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.debug_struct("BedrockStatus")
            .field("edition", &self.edition)
            .field("motd", &self.motd)
            .field("protocol_version", &self.protocol_version)
            .field("version", &self.version)
            .field("online_players", &self.online_players)
            .field("max_players", &self.max_players)
            .field("server_uid", &self.server_uid)
            .field("motd2", &self.motd2)
            .field("game_mode", &self.game_mode)
            .field("game_mode_numeric", &self.game_mode_numeric)
            .field("port_ipv4", &self.port_ipv4)
            .field("port_ipv6", &self.port_ipv6)
            .field("map", &self.map)
            .field("software", &self.software)
            .field("raw_data", &self.raw_data.len())
            .finish()
    }
}

/// Server information for batch queries.
///
/// Used to specify multiple servers to ping in parallel.
///
/// # Example
///
/// ```no_run
/// use rust_mc_status::{McClient, ServerEdition, ServerInfo};
///
/// # #[tokio::main]
/// # async fn main() -> Result<(), Box<dyn std::error::Error>> {
/// let client = McClient::new();
/// let servers = vec![
///     ServerInfo {
///         address: "mc.hypixel.net".to_string(),
///         edition: ServerEdition::Java,
///     },
///     ServerInfo {
///         address: "geo.hivebedrock.network:19132".to_string(),
///         edition: ServerEdition::Bedrock,
///     },
/// ];
///
/// let results = client.ping_many(&servers).await;
/// for (server, result) in results {
///     println!("{}: {:?}", server.address, result.is_ok());
/// }
/// # Ok(())
/// # }
/// ```
#[derive(Debug, Serialize, Deserialize, Clone)]
pub struct ServerInfo {
    /// Server address (hostname or IP, optionally with port).
    pub address: String,
    /// Server edition.
    pub edition: ServerEdition,
}

/// Minecraft server edition.
///
/// Specifies whether the server is Java Edition or Bedrock Edition.
#[derive(Debug, Serialize, Deserialize, Clone, Copy, PartialEq, Eq)]
pub enum ServerEdition {
    /// Java Edition server (default port: 25565).
    Java,
    /// Bedrock Edition server (default port: 19132).
    Bedrock,
}

/// Cache statistics.
///
/// Provides information about the current state of DNS and SRV caches.
///
/// # Example
///
/// ```no_run
/// use rust_mc_status::McClient;
///
/// # #[tokio::main]
/// # async fn main() {
/// let client = McClient::new();
/// let stats = client.cache_stats();
/// println!("DNS entries: {}, SRV entries: {}", stats.dns_entries, stats.srv_entries);
/// # }
/// ```
#[derive(Debug, Clone, Copy)]
pub struct CacheStats {
    /// Number of entries in DNS cache.
    pub dns_entries: usize,
    /// Number of entries in SRV cache.
    pub srv_entries: usize,
}

impl std::str::FromStr for ServerEdition {
    type Err = McError;

    fn from_str(s: &str) -> Result<Self, Self::Err> {
        match s.to_lowercase().as_str() {
            "java" => Ok(ServerEdition::Java),
            "bedrock" => Ok(ServerEdition::Bedrock),
            _ => Err(McError::InvalidEdition(s.to_string())),
        }
    }
}