V0.8.0 (#3)

Author: vikpe

Cargo.toml

@@ -4,32 +4,26 @@ description = "Get server addresses from QuakeWorld master servers."
 keywords = ["masters", "quake", "quakeworld", "servers"]
 repository = "https://github.com/quakeworld/masterstat"
 authors = ["Viktor Persson <viktor.persson@arcsin.se>"]
-version = "0.7.0"
+version = "0.8.0"
 edition = "2024"
 license = "MIT"
-include = [
-    "/Cargo.toml",
-    "/LICENSE",
-    "/README.md",
-    "/src/**",
-    "/tests/**",
-]
-
-# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
+include = ["/Cargo.toml", "/LICENSE", "/README.md", "/src/**", "/tests/**"]
 
 [dependencies]
 anyhow = "1.0.97"
-binrw = "0.14.1"
+binrw = "0.15.0"
 futures = "0.3.31"
-tokio = { version = "1.44.1", features = ["macros", "net", "rt-multi-thread", "sync", "time"] }
-tinyudp = "0.5.1"
-
-serde = { optional = true, version = "1.0.219", features = ["derive"] }
-serde_json = { optional = true, version = "1.0.140" }
+tokio = { version = "1.44.1", features = [
+    "macros",
+    "net",
+    "rt-multi-thread",
+    "sync",
+    "time",
+] }
+tinyudp = { version = "0.6.0", features = ["tokio"] }
 
 [dev-dependencies]
 pretty_assertions = "1.4.1"
 
 [features]
 ci = []
-json = ["dep:serde", "dep:serde_json"]

README.md

@@ -1,6 +1,6 @@
 # masterstat [![Test](https://github.com/quakeworld/masterstat/actions/workflows/test.yml/badge.svg?branch=main)](https://github.com/quakeworld/masterstat/actions/workflows/test.yml) [![crates](https://img.shields.io/crates/v/masterstat)](https://crates.io/crates/masterstat) [![docs.rs](https://img.shields.io/docsrs/masterstat)](https://docs.rs/masterstat/)
 
-> Get server addresses from QuakeWorld master servers
+> A Rust crate for querying QuakeWorld master servers
 
 ## Installation
 

src/command.rs

@@ -2,8 +2,9 @@
 //!
 //! Get server addresses from QuakeWorld master servers.
 
-mod command;
+mod query;
+mod query_multiple;
 mod server_address;
 
-pub use crate::command::{server_addresses, server_addresses_from_many};
-pub use crate::server_address::ServerAddress;
+pub use crate::query::query;
+pub use crate::query_multiple::{MultiQueryResult, query_multiple};

src/lib.rs

@@ -0,0 +1,87 @@
+use std::{io::Cursor, time::Duration};
+
+use anyhow::{Result, anyhow as e};
+use binrw::BinRead;
+
+use crate::server_address::RawServerAddress;
+
+/// Get server addresses from a single master server
+///
+/// # Example
+///
+/// ```
+/// use std::time::Duration;
+///
+/// async fn test() {
+///     let master = "master.quakeworld.nu:27000";
+///     let timeout = Duration::from_secs(2);
+///     match masterstat::query(&master, timeout).await {
+///         Ok(addresses) => { println!("found {} server addresses", addresses.len()) },
+///         Err(e) => { eprintln!("error: {}", e); }
+///     }
+/// }
+/// ```
+pub async fn query(master_address: &str, timeout: Duration) -> Result<Vec<String>> {
+    const STATUS_MSG: [u8; 3] = [99, 10, 0];
+    const BUFFER_SIZE: usize = 64 * 1024;
+    let options = tinyudp::ReadOptions::new(timeout, BUFFER_SIZE);
+    let response = tinyudp::send_and_receive_async(master_address, &STATUS_MSG, options).await?;
+    parse_response(&response)
+}
+
+fn parse_response(response: &[u8]) -> Result<Vec<String>> {
+    const RESPONSE_HEADER: [u8; 6] = [255, 255, 255, 255, 100, 10];
+
+    if !response.starts_with(&RESPONSE_HEADER) {
+        return Err(e!("Invalid response"));
+    }
+
+    let body = &mut Cursor::new(&response[RESPONSE_HEADER.len()..]);
+    let mut addresses = vec![];
+
+    while let Ok(raw_address) = RawServerAddress::read(body) {
+        addresses.push(raw_address.to_string());
+    }
+
+    Ok(addresses)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use pretty_assertions::assert_eq;
+
+    #[tokio::test]
+    #[cfg_attr(feature = "ci", ignore)]
+    async fn test_query() -> Result<()> {
+        let master = "master.quakeservers.net:27000";
+        let timeout = Duration::from_secs(2);
+        let result = query(master, timeout).await?;
+        assert!(!result.is_empty());
+        Ok(())
+    }
+
+    #[tokio::test]
+    async fn test_parse_response() -> Result<()> {
+        // invalid response header
+        {
+            let response = [0xff, 0xff];
+            let result = parse_response(&response);
+            assert_eq!(result.unwrap_err().to_string(), "Invalid response");
+        }
+
+        // valid response
+        {
+            let response = [
+                0xff, 0xff, 0xff, 0xff, 0x64, 0x0a, 192, 168, 1, 1, 0x75, 0x30, 192, 168, 1, 2,
+                0x75, 0x30,
+            ];
+            let result = parse_response(&response)?;
+            assert_eq!(result.len(), 2);
+            assert_eq!(result[0], "192.168.1.1:30000".to_string());
+            assert_eq!(result[1], "192.168.1.2:30000".to_string());
+        }
+
+        Ok(())
+    }
+}