#协议 #tcp-udp #udp #tcp #连接 #编码

djin-protocol-derive

为aoe-djin设计的协议

2个稳定版本

3.3.1 2021年7月24日
3.2.0 2021年7月24日
3.1.9 2021年7月24日

#79 in #tcp-udp

Download history 3/week @ 2024-02-15 13/week @ 2024-02-22 2/week @ 2024-02-29 4/week @ 2024-03-07 7/week @ 2024-03-14 36/week @ 2024-03-28 36/week @ 2024-04-04

72 每月下载
2 crate 中使用

MIT 许可

46KB
946

协议

Build Status Crates.io MIT licensed

文档

Rust中易于定义协议。

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

内置网络支持,特别支持TCP和UDP。

您定义的协议也可以在网络之外使用 - 请参阅 Parcel::from_raw_bytesParcel::raw_bytes 方法。

此crate还提供

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

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

用法

将此添加到您的 Cargo.toml

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

内部机制

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

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

#[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>,
}

自定义派生

任何用户定义的类型都可以自动派生 Parcel 特性。

示例

#[macro_use] extern crate protocol_derive;
#[macro_use] extern crate 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 = protocol::wire::stream::Connection::new(stream, 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,
}

依赖关系

~1.5MB
~34K SLoC