Collum

The name comes from the anatomical neck or cervix, which connect the head to the rest of the body. Although this crate does not fully focus on headers, it is one of the core reasons this crate came to be. Thus, coming back to the etymology of the name, this crate aims to allow users to parse the head(er) of a packet from the rest of its body, essentially serving as a way to analyze the connection between the two.

What does it do?

When using the derive feature of the crate (currently using the syn crate) one can define a data type with elementary types and derive the Collum trait (note that the collum::Sized trait is also needed and can also be derived).

Once these traits are defined or derived, the main functionality lies in Collum::from_bytes, which allows us to parse a byte stream into the defined data structure.

Examples

A primary example here is the TCP/IP stack. As a start we'll take a look at the UDP header, which does not require any manipulation at the bit-level.

use collum::{Collum, Sized};

#[derive(Collum, Sized, Debug, PartialEq)]
#[collum(endian(big))] // This tells Collum that every primitive integer type is in big-endian.
struct UdpHeader {
    src: u16,
    dst: u16,
    len: u16,
    checksum: u16,
}

assert_eq!(
    UdpHeader::from_bytes(&[0x01, 0xbb, 0xbf, 0xe5, 0x00, 0x21, 0x00, 0x00]),
    Some(UdpHeader {
        src: 443,
        dst: 49125,
        len: 33,
        checksum: 0,
    })
);