Crate rust_mc_status 

rust-mc-status

High-performance asynchronous Rust library for querying Minecraft server status — Java Edition and Bedrock Edition.

Quick start

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().

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.

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:

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

[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)

Re-exports

pub use client::McClient;

pub use client::McClientBuilder;

pub use client::ping_java;

pub use client::ping_bedrock;

pub use client::JavaPingBuilder;

pub use client::BedrockPingBuilder;

pub use client::ServerPingBuilder;

pub use error::McError;

pub use error::NetworkError;

pub use error::ProtocolError;

pub use error::ConfigError;

pub use models::CacheStats;

pub use models::PingResult;

pub use models::LegacyData;

pub use models::QueryData;

pub use proxy::ProxyConfig;

pub use proxy::ProxyKind;

pub use status::JavaServerStatus;

pub use status::BedrockServerStatus;

pub use status::StatusExt;

pub use status::strip_formatting;

pub use status::truncate_str;

pub use models::*;

Modules

client

core

Internal infrastructure modules.

error

Error types for the rust-mc-status library.

models

Data models for Minecraft server status responses.

protocol

Protocol abstraction layer.

proxy

Proxy configuration for routing Minecraft pings through SOCKS5 or HTTP CONNECT proxies.

status

Typed status wrappers and the StatusExt trait.