1 unstable release
0.5.0 | May 26, 2022 |
---|
#2451 in Rust patterns
8KB
Packetrs
Packetrs is a Rust macro which auto generates deserialzation and serialization (eventually) code for struct packets on macro attributes. Its API is heavily inspired by/ripped off from Deku. This was implemented mainly for my own fun/educational purposes.
Examples
Say you wanted to parse a STUN header, which has the following layout:
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|0 0| STUN Message Type | Message Length |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Magic Cookie |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| |
| Transaction ID (96 bits) |
| |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
In Packetrs, you'd do:
#[derive(Debug, PacketrsRead)]
pub struct StunHeader {
#[packetrs(fixed = "0")]
pub reserved: u2,
pub msg_type: u14,
pub msg_length: u16,
#[packetrs(fixed = "0x2112A442")]
pub cookie: u32,
#[packetrs(count = "12")]
pub transaction_id: Vec<u8>,
}
PacketrsRead Trait
Deriving PacketrsRead
on a struct or enum generates an implementation of the PacketrsRead
trait for that type:
pub trait PacketRsRead<Ctx>: Sized {
fn read(buf: &mut BitCursor, ctx: Ctx) -> PacketRsResult<Self>;
}
TODO: link to BitCursor repo once it's up
PacketrsRead Attributes
Context & Required Context
Structs, fields, enums and enum variants all may need additional context in order to be read. The required_ctx
attribute allows a Struct, field, enum or enum variant to define a required value or values that must be passed to its PacketrsRead::read
method. The other side of this is the ctx
attribute, which defines what will be passed to the read method of whatever is annotated.
In this example, the Address
enum requires a u8
named address_family
to be passed, and then uses that value as the key
to distinguish enum variants.
#[derive(Debug, PacketrsRead)]
#[packetrs(required_ctx = "address_family: u8", key = "address_family")]
pub enum Address {
#[packetrs(id = "0x01")]
IpV4(u32),
#[packetrs(id = "0x02")]
IpV6(u128),
}
Here, another enum passes an address_family
field as context to an Address
field
#[derive(Debug, PacketrsRead)]
#[packetrs(required_ctx = "message_type: u16, length: u16", key = "message_type")]
pub enum StunAttribute {
#[packetrs(id = "0x0001")]
MappedAddress {
reserved: u8,
address_family: u8,
port: u16,
#[packetrs(ctx = "address_family")]
address: Address,
},
#[packetrs(id = "0x0020")]
XorMappedAddress {
reserved: u8,
address_family: u8,
x_port: u16,
#[packetrs(ctx = "address_family")]
x_address: Address,
},
#[packetrs(id = "0x0006", count = "length")]
Username(Vec<u8>),
#[packetrs(id = "0x0008", count = "length")]
MessageIntegrity(Vec<u8>),
}
Generic Field attributes
These attributes can be applied to fields of a struct or enum variant
Count
The count
attribute can be used on collection fields (Vec) to describe how many of the inner type (T
) should be read into the collection. The count can be an expression, and can refer to any field or method that will be in scope.
#[derive(PacketrsRead)]
struct MyStruct {
pub length: u8
#[packetrs(count = "length")]
pub values: Vec<u8>
}
fn get_length(length_val: u8) -> u8 { ... }
#[derive(PacketrsRead)]
struct MyOtherStruct {
pub length: u8
#[packetrs(count = "get_length(length)")]
pub values: Vec<u8>
}
Fixed
The fixed
attribute describe allows defining a value which a read field must have. After reading the field, if the read value doesn't match the value defined in the fixed
attribute, then an error is returned.
struct Foo {
#[packetrs(fixed = "0b0000")]
reserved: u4,
other_field: u8
}
Reader
The reader
attribute allows using a custom-defined reader method instead of auto-generating one. The method must return a PacketRsResult<T>
where T
matches the type of the annotated field.
fn parse_stun_attributes(buf: &mut BitCursor, _ctx: ()) -> PacketRsResult<Vec<StunAttribute>> { ... }
#[derive(Debug, PacketrsRead)]
pub struct StunPacket {
pub header: StunHeader,
#[packetrs(reader = "parse_stun_attributes")]
pub attributes: Vec<StunAttribute>,
}
Enum/enum variant attributes
These attributes are valid on either enums or enum variants
Key & Id
The key
attribute must be present on an enum, and is an expression that's used in a match statement to differentiate between the variants. Its counterpart is the id
attribute, which must be present on enum variants. It should correspond to a result of the key
that distinguishes its annotated variant.
#[derive(Debug, PacketrsRead)]
#[packetrs(required_ctx = "address_family: u8", key = "address_family")]
pub enum Address {
#[packetrs(id = "0x01")]
IpV4(u32),
#[packetrs(id = "0x02")]
IpV6(u128),
}
Struct or enum variants with unnamed fields
Unnamed fields can't be annotated, but they're common enough that there's special support to "pass down" annotations from the struct or enum variant itself onto the unnamed fields. Any annotation on the struct or enum variant will be treated as though it exists on all of the unnamed fields. TODO: example
TODO
[ ] More/better documentation [ ] Better compile-time error messages [ ] Unit tests - still need to research how best to do those for proc macros [ ] Implement PacketrsWrite [ ] More features: read until/while for collection fields.
Dependencies
~4MB
~84K SLoC