a2s-protocol 0.1.1

A protocol core for building A2S server query clients
Documentation
//! Legacy GoldSrc response types and request builders.
//!
//! A2S_INFO, A2S_PLAYER, and A2S_RULES are supported for both Source and GoldSrc
//! servers. This module also exposes the older GoldSrc ping and challenge request
//! formats.

use borrowme::borrowme;

use crate::{cursor::Cursor, info::{ServerType}};
use crate::{request, RequestType};
use crate::info::Error;

pub(crate) const INFO_RESPONSE_HEADER: u8 = b'm';
pub(crate) const CHALLENGE_RESPONSE_HEADER: u8 = b'A';
pub(crate) const PING_RESPONSE_HEADER: u8 = b'j';
pub(crate) const PING_REQUEST_HEADER: &[u8] = b"i";
pub(crate) const CHALLENGE_REQUEST_HEADER: &[u8] = b"W";

#[derive(Debug, Clone)]
/// Operating system reported by a GoldSrc server.
pub enum Environment {
    /// Linux.
    Linux,
    /// Windows.
    Windows
}

#[borrowme]
#[derive(Debug)]
#[owned_attr(derive(Clone))]
#[owned_attr(doc(hidden))]
/// Optional GoldSrc mod metadata included in a server information response.
pub struct Mod<'a> {
    /// Mod website URL.
    pub link: &'a str,
    /// Mod download URL.
    pub download_link: &'a str,
    /// Mod version number.
    pub version: i32,
    /// Mod size in bytes.
    pub size: i32,
    /// Whether the mod is multiplayer-only.
    pub multiplayer_only: bool,
    /// Whether the mod provides its own client DLL.
    pub own_dll: bool,
}

#[borrowme]
#[derive(Debug)]
#[owned_attr(derive(Clone))]
#[owned_attr(doc(hidden))]
/// Parsed legacy GoldSrc server information.
///
/// Text fields borrow from the response packet, which must remain alive while
/// those fields are used.
pub struct GoldSrcInfo<'a> {
    /// Server address string as reported in the response.
    pub address: &'a str,
    /// Human-readable server name.
    pub name: &'a str,
    /// Current map name.
    pub map: &'a str,
    /// Game directory name.
    pub folder: &'a str,
    /// Human-readable game description.
    pub game: &'a str,
    /// Current number of players.
    pub players: u8,
    /// Maximum number of players.
    pub max_players: u8,
    /// Protocol version reported by the server.
    pub protocol: u8,
    /// Server role (dedicated, listen, or proxy).
    pub server_type: ServerType,
    /// Operating system reported by the server.
    pub environment: Environment,
    /// Whether the server is password-protected.
    pub is_private: bool,
    /// Optional metadata about the installed game mod.
    pub mod_data: Option<Mod<'a>>,
    /// Whether Valve Anti-Cheat is enabled.
    pub vac: bool,
    /// Number of bots reported by the server.
    pub bots: u8,
}

pub(crate) fn parse_info(raw: &[u8]) -> Result<GoldSrcInfo<'_>, Error> {
    let mut cur = Cursor::new(raw);

    let address = cur.read_str()?;
    let name = cur.read_str()?;
    let map = cur.read_str()?;
    let folder = cur.read_str()?;
    let game = cur.read_str()?;
    let players = cur.read_byte()?;
    let max_players = cur.read_byte()?;
    let protocol = cur.read_byte()?;
    let server_type = ServerType::try_from(cur.read_byte()?)?;
    let environment = match cur.read_byte()? {
        b'l' => Environment::Linux,
        b'w' => Environment::Windows,
        other => return Err(Error::InvalidPlatform(other)),
    };
    let is_private = cur.read_byte()? != 0;
    let mod_data = if cur.read_byte()? != 0 {
        Some(Mod {
            link: cur.read_str()?,
            download_link: cur.read_str()?,
            version: cur.read_long()?,
            size: cur.read_long()?,
            multiplayer_only: cur.read_byte()? != 0,
            own_dll: cur.read_byte()? != 0,
        })
    } else {
        None
    };
    let vac = cur.read_byte()? != 0;
    let bots = cur.read_byte()?;

    Ok(GoldSrcInfo { address, name, map, folder, game, players, max_players, protocol, server_type, environment, is_private, mod_data, vac, bots })
}

/// Builds a legacy GoldSrc ping request packet.
///
/// Use this with a UDP socket and parse the reply using [`crate::parse_payload`].
pub fn ping_request() -> Vec<u8> {
    request(RequestType::Ping, None)
}

/// Builds a legacy GoldSrc challenge request packet.
///
/// Use this when a server requires a challenge before accepting another request.
pub fn challenge_request() -> Vec<u8> {
    request(crate::RequestType::Challenge, None)
}