Crate rust_mc_status

Crate rust_mc_status 

Source
Expand description

§Rust Minecraft Server Status Library

A high-performance, asynchronous Rust library for querying the status of both Minecraft Java Edition and Bedrock Edition servers.

§Features

  • Dual Protocol Support: Ping both Minecraft Java Edition (25565) and Bedrock Edition (19132) servers
  • Async/Await: Built on Tokio for non-blocking operations and high concurrency
  • Batch Queries: Ping multiple servers in parallel with configurable concurrency limits
  • DNS Caching: Automatically caches DNS lookups and SRV records to reduce latency
  • SRV Record Support: Automatically resolves SRV records for Java servers (mimics Minecraft client behavior)
  • Structured Data: Returns richly structured, serializable data (using serde)
  • Favicon Handling: Easily retrieve and save server favicons (Java Edition only)
  • Robust Error Handling: Comprehensive error types using thiserror
  • Extended Information: Detailed data about plugins, mods, DNS, and more

§Quick Start

use rust_mc_status::{McClient, ServerEdition};
use std::time::Duration;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = McClient::new()
        .with_timeout(Duration::from_secs(5))
        .with_max_parallel(10);

    // Ping a Java server (automatically uses SRV lookup if port not specified)
    let status = client.ping("mc.hypixel.net", ServerEdition::Java).await?;
    println!("Server is online: {}", status.online);
    if let Some((online, max)) = status.players() {
        println!("Players: {}/{}", online, max);
    }

    Ok(())
}

§SRV Record Lookup

When pinging Java servers without an explicit port, the library automatically performs an SRV DNS lookup for _minecraft._tcp.{hostname}. This mimics the behavior of the official Minecraft client.

  • If an SRV record is found, the target host and port from the record are used
  • If no SRV record exists, the default port (25565) is used
  • Explicitly specifying a port (e.g., "server.com:25565") skips SRV lookup
  • SRV lookup results are cached for 5 minutes to improve performance

§Examples

See the examples/ directory for more detailed usage examples.

  • basic_usage.rs - Basic server status queries
  • advanced_usage.rs - Advanced features and batch queries
  • srv_lookup_example.rs - SRV record lookup demonstration
  • performance_test.rs - Performance benchmarking and speed tests
  • cache_management.rs - Cache management and statistics

Re-exports§

pub use client::McClient;
pub use error::McError;
pub use models::CacheStats;
pub use models::*;

Modules§

client
Client for querying Minecraft server status.
error
Error types for the Minecraft server status library.
models
Data models for Minecraft server status responses.