a2s-protocol 0.1.0

A protocol core for building A2S server query clients
Documentation
use std::borrow::Cow;
use std::collections::HashMap;
use std::net::SocketAddr;

use crate::transport::{compression};
use crate::transport::packet::Compression;

use super::packet_assembler::Assembler;
use super::packet::PacketKind;
use super::Error;

/// Reassembles fragmented server responses and decompresses compressed packets.
///
/// Create one processor for a query session and pass every received UDP datagram
/// to [`process`](Self::process). The processor keeps incomplete fragments keyed
/// by source address and packet ID. It does not perform network I/O.
pub struct PacketProcessor {
    waiting: HashMap<(SocketAddr, i32), Assembler>
}

impl PacketProcessor {
    /// Creates a processor with no pending fragment sequences.
    pub fn new() -> Self {
        Self {
            waiting: HashMap::new()
        }
    }

    /// Processes one received UDP datagram.
    ///
    /// Returns `Ok(None)` while more fragments are needed. For a complete
    /// single-packet response, the result borrows from `raw`; assembled or
    /// decompressed responses are owned. Pass the returned bytes to
    /// [`crate::parse_payload`] to decode the A2S response.
    ///
    /// `addr` should be the datagram's source address. It keeps fragments from
    /// different servers in separate sequences.
    ///
    /// # Errors
    ///
    /// Returns an error for an invalid packet header, malformed fragment
    /// sequence, or failed decompression/checksum validation.
    pub fn process<'a>(&mut self, addr: SocketAddr, raw: &'a [u8]) -> Result<Option<Cow<'a, [u8]>>, Error> {
        Ok(match PacketKind::try_from(raw)? {
            PacketKind::Single => Some(Cow::Borrowed(raw)),
            PacketKind::Multi(packet) => {
                let packet_id = packet.id;

                let entry = self.waiting.entry((addr, packet_id)).or_default();
                let Some((mut payload, compression)) = entry.add_and_try_assemble(packet)? else {
                    return Ok(None)
                };

                self.waiting.remove(&(addr, packet_id));

                if let Some(Compression{ size, crc32_sum }) = compression {
                    payload = compression::decode(&payload, size as usize, crc32_sum as u32)?;
                }

                Some(Cow::Owned(payload))
            }
        })
    }
}