Struct McClient 

pub struct McClient { /* private fields */ }

Async client for pinging Minecraft Java and Bedrock servers.

Constructed via McClient::builder() — there is no new(). Cheaply Clone-able — all clones share the same DNS/SRV and response caches.

Example

use rust_mc_status::McClient;
use std::time::Duration;

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?;

Implementations

impl McClient

pub fn builder() -> McClientBuilder

Return a McClientBuilder — the only way to construct a McClient.

pub fn timeout(&self) -> Duration

Returns the configured request timeout.

pub fn max_parallel(&self) -> usize

Returns the configured maximum number of concurrent pings in ping_many.

pub async fn clear_caches(&self)

Clear the DNS and SRV caches.

The next ping to any host will re-resolve DNS from scratch. The response cache is unaffected — use clear_response_cache to clear it separately.

pub async fn clear_response_cache(&self)

Clear the response cache only.

The next ping to any cached server will perform a live network request. DNS/SRV caches are unaffected.

pub async fn cache_stats(&self) -> CacheStats

Return a snapshot of current cache entry counts.

Useful for monitoring and debugging — does not block any in-flight pings.

pub fn java(&self, address: impl Into<String>) -> JavaPingBuilder

Start a Java Edition ping for address.

Returns a JavaPingBuilder — call .await to execute, or chain .timeout(Duration) to override the timeout for this request only.

Errors

The returned future may fail with:

• McError::Config — if address is malformed (bad port, missing ]).
• McError::Network — DNS failure, connection refused, or timeout.
• McError::Protocol — unexpected server response.

Example

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

let client = McClient::builder().build();

// Default timeout
let s = client.java("mc.hypixel.net").await?;

// Per-request timeout
let s = client.java("mc.hypixel.net")
    .timeout(Duration::from_secs(3))
    .await?;

pub fn bedrock(&self, address: impl Into<String>) -> BedrockPingBuilder

Start a Bedrock Edition ping for address.

Returns a BedrockPingBuilder — call .await to execute, or chain .timeout(Duration) to override the timeout for this request only.

Errors

The returned future may fail with:

• McError::Config — if address is malformed.
• McError::Network — DNS failure, UDP send/receive error, or timeout.
• McError::Protocol — pong packet too short or malformed MOTD.
• [McError::Proxy] — proxy does not support UDP (feature = “proxy”).

Example

use rust_mc_status::{McClient, StatusExt};

let client = McClient::builder().build();
let s = client.bedrock("geo.hivebedrock.network:19132").await?;
println!("{} — {}", s.edition(), s.display_players());

pub fn server( &self, address: impl Into<String>, edition: ServerEdition, ) -> ServerPingBuilder

Start a ping where the edition is chosen at runtime.

Useful when edition comes from user input or a config file. Returns a ServerPingBuilder — call .await for a raw ServerStatus, or .is_online().await for a simple boolean reachability check.

Example

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

let client = McClient::builder().build();
let edition: ServerEdition = "java".parse()?;

let online = client
    .server("mc.hypixel.net", edition)
    .timeout(Duration::from_secs(5))
    .is_online()
    .await;

println!("online: {online}");

pub async fn ping_many( &self, servers: &[ServerInfo], ) -> Vec<(ServerInfo, Result<ServerStatus, McError>)>

Ping multiple servers concurrently with bounded parallelism.

All tasks are spawned immediately — a Semaphore limits how many run at once (max_parallel, default 10). Results are streamed back as they complete so a slow or timed-out server never blocks the rest.

When the response cache is enabled, duplicate addresses in the list benefit from in-flight deduplication — only one real ping is made per unique key regardless of how many times it appears.

Return value

A Vec of (ServerInfo, Result<ServerStatus, McError>) pairs in completion order (not input order). Each entry either contains the full ServerStatus or the error that occurred for that server.

All tasks are spawned immediately — a Semaphore limits how many run at once. Results stream back as they complete, so a slow or timed-out server never blocks the rest.

Duplicate addresses benefit from in-flight deduplication when the response cache is enabled.

Trait Implementations

impl Clone for McClient

fn clone(&self) -> McClient

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.