协议

这是从protocol分支出来，添加了一些其他项目需要的额外功能

文档

Rust中易于定义的协议。

此crate添加了一个自定义 derive，可以添加到类型中，允许结构化数据从任何IO流发送和接收。

网络功能已内置，特别支持TCP和UDP。

定义的协议不仅可以用于网络 - 请参阅 Parcel::from_raw_bytes 和 Parcel::raw_bytes 方法。

此crate还提供

• TCP 和 UDP 模块，用于轻松发送和接收 Parcel
• 一个通用的 中间件 库，用于自动转换发送/接收数据
  • 已编写中间件以支持 压缩
  • 可以通过具有两个方法的trait实现自定义中间件

请查看examples文件夹以了解使用方法。

用法

将以下内容添加到您的 Cargo.toml

[dependencies]
protocol = "3.1"
protocol-derive = "3.1"

底层实现

这里最有趣的部分是djin_protocol::Parcel trait。任何实现了此trait的类型都可以将数据序列化为字节流。所有原始类型、标准集合、元组和数组都实现了此trait。

当您定义自己的 Parcel 类型时，这个crate特别有用。您可以使用 #[derive(Protocol)] 来实现这一点。请注意，为了使类型实现 Parcel，它还必须实现 Clone、Debug 和 PartialEq。

#[derive(Parcel, Clone, Debug, PartialEq]
pub struct Health(f32);

#[derive(Parcel, Clone, Debug, PartialEq]
pub struct SetPlayerPosition {
    pub position: (f32, f32),
    pub health: Health,
    pub values: Vec<String>,
}

自定义 derive

任何用户定义的类型都可以自动推导出 Parcel trait。

示例

#[macro_use] extern crate djin_protocol_derive;#[macro_use] extern crate djin_protocol;

#[derive(Protocol, Clone, Debug, PartialEq)]
pub struct Handshake;

#[derive(Protocol, Clone, Debug, PartialEq)]
pub struct Hello {
    id: i64,
    data: Vec<u8>,
}

#[derive(Protocol, Clone, Debug, PartialEq)]
pub struct Goodbye {
    id: i64,
    reason: String,
}

#[derive(Protocol, Clone, Debug, PartialEq)]
pub struct Node {
    name: String,
    enabled: bool
}

#[protocol(discriminant = "integer")]
#[derive(Protocol, Clone, Debug, PartialEq)]
pub enum PacketKind {
    #[protocol(discriminator(0x00))]
    Handshake(Handshake),
    #[protocol(discriminator(0xaa))]
    Hello(Hello),
    #[protocol(discriminator(0xaf))]
    Goodbye(Goodbye),
}

fn main() {
    use std::net::TcpStream;

    let stream = TcpStream::connect("127.0.0.1:34254").unwrap();
    let mut connection = djin_protocol::wire::stream::Connection::new(stream, djin_protocol::wire::middleware::pipeline::default());

    connection.send_packet(&Packet::Handshake(Handshake)).unwrap();
    connection.send_packet(&Packet::Hello(Hello { id: 0, data: vec![ 55 ]})).unwrap();
    connection.send_packet(&Packet::Goodbye(Goodbye { id: 0, reason: "leaving".to_string() })).unwrap();

    loop {
        if let Some(response) = connection.receive_packet().unwrap() {
            println!("{:?}", response);
            break;
        }
    }
}

枚举

区分符

枚举值可以通过其基于1的变体索引或通过传输每个变体的字符串名称来传输。

注意： 默认行为是使用 变体名称作为字符串 (string)。

可以通过 #[protocol(discriminant = "<type>")] 属性来改变这种行为。

支持的区分符类型

• string (默认)
  • 这会将枚举变体名称作为网络上的区分符传输
  • 这会占用每个消息更多的字节，但非常灵活
• 整数
  • 这会将基于1的变体编号作为网络上的区分符传输
  • 如果枚举变体有显式的区分符，
  • 枚举变体不能在源代码中重新排序，否则会破坏协议

#[derive(Protocol, Clone, Debug, PartialEq)]
#[protocol(discriminant = "string")]
pub enum PlayerState {
  Stationary,
  Flying { velocity: (f32,f32,f32) },
  // Discriminators can be explicitly specified.
  #[protocol(discriminator("ArbitraryOverTheWireName"))]
  Jumping { height: f32 },
}

杂项

您可以为它们的序列化重命名变体。

#[derive(Protocol, Clone, Debug, PartialEq)]
#[protocol(discriminant = "string")]
pub enum Foo {
  Bar,
  #[protocol(name = "Biz")] // the Bing variant will be send/received as 'Biz'.
  Bing,
  Baz,
}