haprox-rs 0.2.3

/*-
 * haprox-rs - a HaProxy protocol parser.
 * 
 * Copyright 2025 Aleksandr Morozov
 * The scram-rs crate can be redistributed and/or modified
 * under the terms of either of the following licenses:
 *
 *   1. the Mozilla Public License Version 2.0 (the “MPL”) OR
 *                     
 *   2. EUROPEAN UNION PUBLIC LICENCE v. 1.2 EUPL © the European Union 2007, 2016
 */

use std::{fmt, io::Cursor};

use crate::error::HaProxRes;

pub mod protocol;

pub mod protocol_raw;
pub mod protocol_parser;
pub mod protocol_composer;

pub mod autogen;

/// Should be implemented by the structure which contains UniqID in order to be passed
/// as argument to TLV.
pub trait PP2TlvUniqId: fmt::Display
{
    /// Should return the ID as an array of length [MAX_UNIQ_ID_LEN_BYTES] bytes.
    fn into_bytes(&self) -> Vec<u8>;

    /// Should return the length in bytes of the array.
    fn get_len(&self) -> u16;
}

/// A V2 OP code.
pub trait ProxyV2OpCode: fmt::Debug + Clone
{
    /// An operational code of the specific proto msg type identifier.
    const OPCODE: u8;
}

pub trait PP2TlvDump: fmt::Debug + fmt::Display
{
    /// Returns the type number of the TLV.
    fn get_type(&self) -> u8;

    /// Writes the content of the instance to the TLV's payload. It must NOT 
    /// write the TLV header, it is written before and after.
    /// 
    /// # Arguments
    /// 
    /// * `cur` - a [Cursor] which points to the beginning of the payload.
    /// The packet size should not exceed the MTU of your network.
    /// 
    /// # Returns 
    /// 
    /// A [Result] should be returned without any inner data.
    fn dump(&self, cur: &mut Cursor<Vec<u8>>) -> HaProxRes<()>;
}

/// A trait which provides functionality for `protocol_parser`. A user's program can
/// implement this on the own set of TLV in order to parse the received data and 
/// return the result.
pub trait PP2TlvRestore: fmt::Debug + fmt::Display
{
    /// Checks if the current TLV is in range of the `tlv_parent_type` parent. If
    /// `tlv_parent_type` is `None` then the `tlv_type` can be checked against the
    /// main range. The `tlv_parent_type` is set when the current `tlv_type` is a 
    /// subset of the parent.
    /// 
    /// It is called by the TLV iterator to determine which parser should be called next 
    /// or if it is out of range then error.
    /// 
    /// # Arguments
    /// 
    /// * `tlv_type` - a current tlv ID.
    /// 
    /// * `tlv_parent_type` - a parent TLV ID if any.
    /// 
    /// # Returns 
    /// 
    /// Either true or false. If not in range then false.
    fn is_in_range(tlv_type: u8, tlv_parent_type: Option<u8>) -> bool;

    /// A function which is called when the parsing reaches the TLV's payload. The cursor
    /// is poiniting to the beginning of the payload and the inner buffer is a slice 
    /// from the main buffer of size of the TLV's payload.
    /// 
    /// # Arguments
    /// 
    /// * `tlv_type` - a current TLV type.
    /// 
    /// * `cur` - a cursor pointing to the beginning of the TLV's payload.
    /// 
    /// # Returns 
    /// 
    /// A [HaProxRes] should be returned with
    /// 
    /// * [Result::Ok] - with the `self` instance.
    /// 
    /// * [Result::Err] - an error description.
    fn restore(tlv_type: u8, cur: &mut Cursor<&[u8]>) -> HaProxRes<Self> where Self: Sized;

    /// Should return `true` if the current instance contains subtypes.
    fn contains_subtype(&self) -> bool;
}