packetwire-derive 0.1.0

Derive macros for the packetwire binary packet codec
Documentation
  • Coverage
  • 100%
    3 out of 3 items documented0 out of 2 items with examples
  • Size
  • Source code size: 26.4 kB This is the summed size of all the files inside the crates.io package for this release.
  • Documentation size: 72.1 kB This is the summed size of all files generated by rustdoc for all configured targets
  • Ø build duration
  • this release: 5s Average build duration of successful builds.
  • all releases: 5s Average build duration of successful builds in releases after 2024-10-23.
  • Links
  • crates.io
  • Dependencies
  • Versions
  • Owners
  • Glomzzz

packetwire-derive

Procedural attribute macros for packetwire, a bounded binary packet codec with stream and datagram framing.

Most applications should depend only on packetwire. It re-exports these macros together with the traits and framing types used by the generated code:

[dependencies]
packetwire = "0.1"

Packet structs

#[packet] assigns a stable 16-bit packet ID and implements BinaryEncode, BinaryDecode, and Packet. Named, tuple, unit, and generic structs are supported. Fields are encoded and decoded in declaration order.

Both attribute forms are equivalent:

use packetwire::packet;

#[packet(1)]
struct Ping {
    sequence: u32,
}

#[packet(id = 2)]
struct Pong;

Every field type must implement both BinaryEncode and BinaryDecode. The macro adds those bounds to generated implementations for generic structs.

Place #[packet] before ordinary derive attributes so those attributes remain attached to the emitted struct:

use packetwire::packet;

#[packet(id = 3)]
#[derive(Debug, Clone, PartialEq, Eq)]
struct Message(String);

Packet sets

#[packet_set] turns a non-empty enum of single-field tuple variants into a packet dispatcher. Each variant field must be a type implementing Packet, normally through #[packet].

The macro implements PacketSet, PacketEncode, and From<PacketType> for the enum. Duplicate packet IDs are rejected at compile time.

use packetwire::{PacketDecoder, PacketEncoder, packet, packet_set};

#[packet(id = 1)]
#[derive(Debug, Clone, PartialEq, Eq)]
struct Ping {
    sequence: u32,
}

#[packet(id = 2)]
#[derive(Debug, Clone, PartialEq, Eq)]
struct Pong {
    sequence: u32,
}

#[packet_set]
#[derive(Debug, Clone, PartialEq, Eq)]
enum Message {
    Ping(Ping),
    Pong(Pong),
}

fn round_trip() -> packetwire::Result<()> {
    let frame = PacketEncoder::default().encode(&Ping { sequence: 7 })?;
    let message = PacketDecoder::<Message>::default().decode_datagram(&frame)?;
    assert_eq!(message, Message::Ping(Ping { sequence: 7 }));
    Ok(())
}

Packet-set enums cannot be generic, cannot contain discriminants, and must use exactly one unnamed packet field per variant.

Direct dependency

This crate is primarily an implementation detail of packetwire. Depending on it directly does not provide the traits referenced by generated code, so the main packetwire crate must still be available. Renamed packetwire dependencies are detected automatically.

License

MIT