rust_mc_status/protocol/
mod.rs

1//! Protocol abstraction layer.
2//!
3//! Each Minecraft ping variant lives in its own sub-module and implements
4//! [`PingProtocol`]. [`McClient`](crate::McClient) orchestrates DNS resolution
5//! and then delegates the wire work to whichever protocol is needed.
6//!
7//! # Adding a new protocol
8//!
9//! 1. Create `src/protocol/your_protocol.rs`.
10//! 2. Implement [`PingProtocol`] for a **unit struct** (zero-size, `Copy`).
11//! 3. Re-export it here.
12//! 4. Add a thin method on `McClient` that calls `ping_with(…, &YourProtocol)`.
13//!
14//! No other files need to change.
15//!
16//! # Example skeleton
17//!
18//! ```rust,ignore
19//! use rust_mc_status::protocol::{PingProtocol, ResolvedTarget, PingResult};
20//! use rust_mc_status::models::{ServerData, QueryData};
21//! use rust_mc_status::proxy::ProxyConfig;
22//! use rust_mc_status::McError;
23//! use std::time::Duration;
24//!
25//! #[derive(Debug, Clone, Copy, Default)]
26//! pub struct QueryProtocol;
27//!
28//! impl PingProtocol for QueryProtocol {
29//!     fn name(&self) -> &'static str { "query" }
30//!
31//!     async fn ping(
32//!         &self,
33//!         target:  &ResolvedTarget,
34//!         timeout: Duration,
35//!         proxy:   Option<&ProxyConfig>,
36//!     ) -> Result<PingResult, McError> {
37//!         let start = crate::core::time::start_timer();
38//!         // … UDP handshake, stat request, parse …
39//!         Ok(PingResult::new(
40//!             ServerData::Query(QueryData { /* … */ ..Default::default() }),
41//!             crate::core::time::elapsed_ms(start),
42//!         ))
43//!     }
44//! }
45//! ```
46
47pub mod java_modern;
48pub mod bedrock;
49
50pub use java_modern::JavaModernProtocol;
51pub use bedrock::BedrockProtocol;
52
53use std::future::Future;
54use std::net::SocketAddr;
55use std::time::Duration;
56
57use crate::error::McError;
58use crate::models::{DnsInfo, PingResult};
59use crate::proxy::ProxyConfig;
60
61// ─── Resolved target ─────────────────────────────────────────────────────────
62
63/// A server address after DNS/SRV resolution, passed into [`PingProtocol::ping`].
64pub struct ResolvedTarget {
65    /// Resolved socket address (IP + port).
66    pub addr:     SocketAddr,
67    /// Original hostname provided by the caller (used in handshake packets).
68    pub hostname: String,
69    /// DNS metadata to embed in [`ServerStatus`](crate::models::ServerStatus).
70    pub dns_info: DnsInfo,
71}
72
73// ─── PingProtocol trait ───────────────────────────────────────────────────────
74
75/// Low-level wire protocol for pinging a Minecraft server.
76///
77/// Implementors should be **unit structs** (zero-size, `Copy`, no heap
78/// allocation per call).  Proxy config is passed by reference — no cloning.
79///
80/// Returns a [`PingResult`] which carries:
81/// - `data`    — typed edition-specific payload ([`ServerData`](crate::models::ServerData))
82/// - `latency` — round-trip time in milliseconds (monotonic)
83/// - `meta`    — escape hatch for unstructured/future protocol fields
84pub trait PingProtocol: Send + Sync {
85    /// Short human-readable identifier, e.g. `"java-modern"`, `"bedrock"`,
86    /// `"query"`.  Used as part of the response-cache key.
87    fn name(&self) -> &'static str;
88
89    /// Execute the ping against an already-resolved target.
90    ///
91    /// `proxy` is `None` when no proxy is configured or the `proxy` feature
92    /// is disabled — implementors should fall back to a direct connection.
93    fn ping(
94        &self,
95        target:  &ResolvedTarget,
96        timeout: Duration,
97        proxy:   Option<&ProxyConfig>,
98    ) -> impl Future<Output = Result<PingResult, McError>> + Send;
99}
rust_mc_status/protocol/mod.rs

rust_mc_status/protocol/
mod.rs
