rust-mc-status 3.0.0

Documentation: https://docs.rs/rust-mc-status

Source Code: https://github.com/NameOfShadow/rust-mc-status

🎉 v3.0.0 — Released 2026-07-01

A major rewrite focused on ergonomics, performance, and extensibility. Breaking changes from 2.x — see the Migration Guide.

Headline changes:

• Builder API — McClient::builder().timeout(...).response_cache(...).build() replaces ad-hoc with_* chaining.
• Per-request fluent pings — client.java("addr").timeout(3s).await? with optional .is_online().
• Response cache with in-flight deduplication — repeated pings to the same server collapse into one network request; cache hits return in ~0 ms.
• Two-level error hierarchy — McError::Network(NetworkError::Timeout) etc. for fine-grained matching and retry policy.
• Proxy support (feature = "proxy") — SOCKS5 (with optional UDP for Bedrock) and HTTP CONNECT, with auth.
• Tower integration (feature = "tower") — McService + McRetryPolicy plug into the Tower middleware ecosystem.
• Layer-based source tree — client/, core/, models/, protocol/, proxy/, status/ for cleaner navigation.
• Zero-cost defaults — without optional features, no extra tower / pin-project / tokio-socks dependencies are pulled in.
• 149 tests across 8 integration test files — DNS parsing, Bedrock/Java decoders, error hierarchy, response cache, proxy config, MOTD formatting.

Full release notes and the migration guide are in CHANGELOG.md.

Features

• Dual Protocol Support — ping both Java Edition (port 25565) and Bedrock Edition (port 19132)
• Ergonomic Builder API — client.java("addr").timeout(3s).await? with per-request timeout override
• Typed Status Wrappers — JavaServerStatus and BedrockServerStatus with edition-specific methods
• Facade Functions — ping_java("addr").await? without creating a client
• Tower Middleware (optional feature) — rate limiting, retries, buffering, tracing via the Tower ecosystem
• Async/Await — built on Tokio for non-blocking, high-concurrency operation
• Batch Queries — ping multiple servers in parallel with configurable concurrency
• LRU DNS Cache — DNS and SRV lookups cached with automatic eviction (default 1024 entries)
• SRV Record Support — automatic SRV lookup for Java servers, mimicking the official client
• JSON Serialisation — all status types implement serde::Serialize; favicon and raw data excluded automatically
• MOTD Formatting — motd_clean() strips Minecraft §-color codes; truncate_str() safely slices Unicode
• Zero-Panic Design — all server-supplied data validated before use; no silent index panics
• SmallVec Optimisation — player sample, plugins, and mods use stack allocation for small lists
• Zero-cost without Tower — the default build pulls in no tower, async-trait, or pin-project dependency

Installation

[dependencies]
rust-mc-status = "3.0.0"
tokio = { version = "*", features = ["full"] }

To enable Tower middleware (rate limiting, retries, buffering, tracing):

rust-mc-status = { version = "3.0.0", features = ["tower"] }

Quick Start

One-liner (no client needed)

use rust_mc_status::{ping_java, ping_bedrock, StatusExt};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let status = ping_java("mc.hypixel.net").await?;
    println!("{}", status);                    // "mc.hypixel.net [42 ms] 32000/200000 — Hypixel Network"
    println!("{}", status.display_players());  // "32000/200000"
    println!("{}", status.motd_clean());       // MOTD without §-codes
    Ok(())
}

Client with custom settings

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

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

    // Typed Java status
    let java = client.java("mc.hypixel.net").await?;
    println!("Version : {}", java.version());
    println!("Players : {}", java.display_players());
    println!("Latency : {:.0} ms", java.latency_ms());
    println!("MOTD    : {}", java.motd_clean());

    // Per-request timeout override — client config unchanged
    let fast = client.java("mc.hypixel.net")
        .timeout(Duration::from_secs(3))
        .await?;
    println!("Fast check: {} ms", fast.latency_ms() as u32);

    // Typed Bedrock status
    let bedrock = client.bedrock("geo.hivebedrock.network:19132").await?;
    println!("Edition : {}", bedrock.edition());
    println!("Players : {}", bedrock.display_players());

    Ok(())
}

Batch queries

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".into(),                edition: ServerEdition::Java },
        ServerInfo { address: "geo.hivebedrock.network:19132".into(), edition: ServerEdition::Bedrock },
    ];

    for (server, result) in client.ping_many(&servers).await {
        match result {
            Ok(s)  => println!("{}: online ({:.0} ms)", server.address, s.latency),
            Err(e) => println!("{}: {}", server.address, e),
        }
    }
    Ok(())
}

JSON serialisation

let status = client.java("mc.hypixel.net").await?;
let json = serde_json::to_string(&status)?;         // compact
let json = serde_json::to_string_pretty(&status)?;  // pretty-printed
// favicon and raw_data are excluded automatically

Runtime edition selection

let edition: ServerEdition = "java".parse()?;

// Full status
let status = client.server("mc.hypixel.net", edition).await?;

// Lightweight reachability check only
let online = client.server("mc.hypixel.net", edition)
    .timeout(Duration::from_secs(3))
    .is_online()
    .await;

Custom address types

struct ServerId(String);
impl From<ServerId> for String { fn from(s: ServerId) -> Self { s.0 } }

let status = client.java(ServerId("mc.hypixel.net".into())).await?;

Tower Middleware

Enable with features = ["tower"]. Converts McClient into a standard tower::Service that works with the entire Tower ecosystem — rate limiting, retries, buffering, tower-http tracing, and any custom tower::Layer.

use tower::{ServiceBuilder, ServiceExt};
use rust_mc_status::{McClient, McRetryPolicy, PingRequestTower};
use std::time::Duration;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut svc = ServiceBuilder::new()
        .buffer(64)                                      // Clone + concurrent
        .rate_limit(100, Duration::from_secs(1))         // 100 req/s
        .retry(McRetryPolicy::new(3))                    // 3 attempts on timeout/connection error
        .service(McClient::new().into_service());

    svc.ready().await?;
    let resp = svc.call(PingRequestTower::java("mc.hypixel.net")).await?;
    println!("{:.0} ms", resp.status.latency);
    Ok(())
}

Custom Tower Layer

Implement tower::Layer for logging, metrics, or any middleware:

use std::future::Future;
use std::pin::Pin;
use std::task::{Context, Poll};
use tower::{Layer, Service};
use rust_mc_status::{McError, PingRequestTower, PingResponseTower};

#[derive(Clone)]
struct LogLayer;

impl<S> Layer<S> for LogLayer {
    type Service = LogService<S>;
    fn layer(&self, inner: S) -> LogService<S> { LogService { inner } }
}

#[derive(Clone)]
struct LogService<S> { inner: S }

impl<S> Service<PingRequestTower> for LogService<S>
where
    S: Service<PingRequestTower, Response = PingResponseTower, Error = McError> + Send,
    S::Future: Send + 'static,
{
    type Response = PingResponseTower;
    type Error    = McError;
    type Future   = Pin<Box<dyn Future<Output = Result<PingResponseTower, McError>> + Send>>;

    fn poll_ready(&mut self, cx: &mut Context<'_>) -> Poll<Result<(), McError>> {
        self.inner.poll_ready(cx)
    }

    fn call(&mut self, req: PingRequestTower) -> Self::Future {
        println!("→ {}", req.address);
        let fut = self.inner.call(req);
        Box::pin(async move {
            let resp = fut.await?;
            println!("{:.0} ms", resp.status.latency);
            Ok(resp)
        })
    }
}

// Usage
let mut svc = ServiceBuilder::new()
    .layer(LogLayer)
    .service(McClient::new().into_service());

SRV Record Lookup

When pinging a Java server without an explicit port, the library queries _minecraft._tcp.{hostname} for SRV records — exactly as the official Minecraft client does. Results are cached for 5 minutes.

// SRV lookup performed automatically
let status = client.java("hypixel.net").await?;

// Explicit port — SRV lookup skipped
let status = client.java("mc.hypixel.net:25565").await?;

MOTD Formatting

use rust_mc_status::strip_formatting;

let raw = "§aHypixel §c[1.8/1.21]";
println!("{}", strip_formatting(raw)); // "Hypixel [1.8/1.21]"

// Or via the wrapper method
let status = client.java("mc.hypixel.net").await?;
println!("{}", status.motd_clean()); // same result

Examples

cargo run --example basic_usage
cargo run --example cache_management
cargo run --example tower_usage --features tower
cargo run --example performance_test --release

API Reference

McClient builder methods

Ping methods

Tower types (feature = "tower")

JavaServerStatus methods

motd(), motd_clean(), version(), players_online(), players_max(), display_players(), favicon(), save_favicon(path), ip(), port(), hostname(), latency_ms(), is_online(), raw()

BedrockServerStatus methods

motd(), motd_clean(), motd2(), motd2_clean(), edition(), version(), players_online(), players_max(), display_players(), game_mode(), ip(), port(), hostname(), latency_ms(), is_online(), raw()

Utility functions

Cache methods (all async)

cache_stats().await, clear_caches().await

Error Handling

use rust_mc_status::McError;

match client.java("server.com").await {
    Ok(s)                              => println!("online: {}", s.display_players()),
    Err(McError::Timeout)              => println!("timed out"),
    Err(McError::DnsError(msg))        => println!("DNS: {}", msg),
    Err(McError::ConnectionError(msg)) => println!("connection: {}", msg),
    Err(e)                             => println!("error: {}", e),
}

Performance Notes

• DNS and SRV results cached for 5 minutes with LRU eviction — no memory leaks
• tokio::sync::RwLock allows concurrent readers with minimal contention
• SmallVec for player sample (≤ 12), plugins (≤ 8), and mods (≤ 8) — stack-allocated for common case
• Per-request .timeout() reduces tail latency in batch scenarios without touching the client
• ping_bedrock uses UDP; ping_java uses TCP with TCP_NODELAY
• Default build has zero tower/async-trait dependency — only pulled in with features = ["tower"]

License

MIT — see LICENSE.

Changelog

See CHANGELOG.md.

Version

Current version: 3.0.0 (released 2026-07-01) — see CHANGELOG.md for full history and migration guide.