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.
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:
```rust
pub struct StunHeader {
#[packetrs(fixed = "0")]
pub reserved: u2,
pub msgtype: u14,
pub msglength: u16,
#[packetrs(fixed = "0x2112A442")]
pub cookie: u32,
#[packetrs(count = "12")]
pub transaction_id: Vec
Deriving PacketrsRead on a struct or enum generates an implementation of the PacketrsRead trait for that type:
rust
pub trait PacketRsRead<Ctx>: Sized {
fn read(buf: &mut BitCursor, ctx: Ctx) -> PacketRsResult<Self>;
}
TODO: link to BitCursor repo once it's up
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.
```rust
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
rust
pub enum StunAttribute {
#[packetrs(id = "0x0001")]
MappedAddress {
reserved: u8,
addressfamily: u8,
port: u16,
#[packetrs(ctx = "addressfamily")]
address: Address,
},
#[packetrs(id = "0x0020")]
XorMappedAddress {
reserved: u8,
addressfamily: u8,
xport: u16,
#[packetrs(ctx = "addressfamily")]
xaddress: Address,
},
#[packetrs(id = "0x0006", count = "length")]
Username(Vec
These attributes can be applied to fields of a struct or enum variant
The count attribute can be used on collection fields (VecT) 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.
```rust
struct MyStruct {
pub length: u8
#[packetrs(count = "length")]
pub values: Vec
rust
fn getlength(lengthval: u8) -> u8 { ... }
struct MyOtherStruct {
pub length: u8
#[packetrs(count = "get_length(length)")]
pub values: Vec
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.
rust
struct Foo {
#[packetrs(fixed = "0b0000")]
reserved: u4,
other_field: u8
}
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.
```rust
fn parsestunattributes(buf: &mut BitCursor, _ctx: ()) -> PacketRsResult
pub struct StunPacket {
pub header: StunHeader,
#[packetrs(reader = "parsestunattributes")]
pub attributes: Vec
These attributes are valid on either enums or enum variants
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.
```rust
pub enum Address { #[packetrs(id = "0x01")] IpV4(u32), #[packetrs(id = "0x02")] IpV6(u128), } ```
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
[ ] 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.