rust-mc-status 3.0.0

High-performance asynchronous Rust library for querying Minecraft server status (Java & Bedrock)
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99

//! Protocol abstraction layer.
//!
//! Each Minecraft ping variant lives in its own sub-module and implements
//! [`PingProtocol`]. [`McClient`](crate::McClient) orchestrates DNS resolution
//! and then delegates the wire work to whichever protocol is needed.
//!
//! # Adding a new protocol
//!
//! 1. Create `src/protocol/your_protocol.rs`.
//! 2. Implement [`PingProtocol`] for a **unit struct** (zero-size, `Copy`).
//! 3. Re-export it here.
//! 4. Add a thin method on `McClient` that calls `ping_with(…, &YourProtocol)`.
//!
//! No other files need to change.
//!
//! # Example skeleton
//!
//! ```rust,ignore
//! use rust_mc_status::protocol::{PingProtocol, ResolvedTarget, PingResult};
//! use rust_mc_status::models::{ServerData, QueryData};
//! use rust_mc_status::proxy::ProxyConfig;
//! use rust_mc_status::McError;
//! use std::time::Duration;
//!
//! #[derive(Debug, Clone, Copy, Default)]
//! pub struct QueryProtocol;
//!
//! impl PingProtocol for QueryProtocol {
//!     fn name(&self) -> &'static str { "query" }
//!
//!     async fn ping(
//!         &self,
//!         target:  &ResolvedTarget,
//!         timeout: Duration,
//!         proxy:   Option<&ProxyConfig>,
//!     ) -> Result<PingResult, McError> {
//!         let start = crate::core::time::start_timer();
//!         // … UDP handshake, stat request, parse …
//!         Ok(PingResult::new(
//!             ServerData::Query(QueryData { /* … */ ..Default::default() }),
//!             crate::core::time::elapsed_ms(start),
//!         ))
//!     }
//! }
//! ```

pub mod java_modern;
pub mod bedrock;

pub use java_modern::JavaModernProtocol;
pub use bedrock::BedrockProtocol;

use std::future::Future;
use std::net::SocketAddr;
use std::time::Duration;

use crate::error::McError;
use crate::models::{DnsInfo, PingResult};
use crate::proxy::ProxyConfig;

// ─── Resolved target ─────────────────────────────────────────────────────────

/// A server address after DNS/SRV resolution, passed into [`PingProtocol::ping`].
pub struct ResolvedTarget {
    /// Resolved socket address (IP + port).
    pub addr:     SocketAddr,
    /// Original hostname provided by the caller (used in handshake packets).
    pub hostname: String,
    /// DNS metadata to embed in [`ServerStatus`](crate::models::ServerStatus).
    pub dns_info: DnsInfo,
}

// ─── PingProtocol trait ───────────────────────────────────────────────────────

/// Low-level wire protocol for pinging a Minecraft server.
///
/// Implementors should be **unit structs** (zero-size, `Copy`, no heap
/// allocation per call).  Proxy config is passed by reference — no cloning.
///
/// Returns a [`PingResult`] which carries:
/// - `data`    — typed edition-specific payload ([`ServerData`](crate::models::ServerData))
/// - `latency` — round-trip time in milliseconds (monotonic)
/// - `meta`    — escape hatch for unstructured/future protocol fields
pub trait PingProtocol: Send + Sync {
    /// Short human-readable identifier, e.g. `"java-modern"`, `"bedrock"`,
    /// `"query"`.  Used as part of the response-cache key.
    fn name(&self) -> &'static str;

    /// Execute the ping against an already-resolved target.
    ///
    /// `proxy` is `None` when no proxy is configured or the `proxy` feature
    /// is disabled — implementors should fall back to a direct connection.
    fn ping(
        &self,
        target:  &ResolvedTarget,
        timeout: Duration,
        proxy:   Option<&ProxyConfig>,
    ) -> impl Future<Output = Result<PingResult, McError>> + Send;
}