2个稳定版本
3.3.1 | 2021年7月24日 |
---|---|
3.2.0 | 2021年7月24日 |
3.1.9 |
|
#79 in #tcp-udp
72 每月下载
在 2 crate 中使用
46KB
946 行
协议
Rust中易于定义协议。
此crate添加了一个自定义 derive,可以添加到类型中,允许结构化数据从任何IO流中发送和接收。
内置网络支持,特别支持TCP和UDP。
您定义的协议也可以在网络之外使用 - 请参阅 Parcel::from_raw_bytes
和 Parcel::raw_bytes
方法。
此crate还提供
请查看 示例 文件夹以了解使用方法。
用法
将此添加到您的 Cargo.toml
[dependencies]
protocol = "3.1"
protocol-derive = "3.1"
内部机制
这里最有趣的部分是 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>,
}
自定义派生
任何用户定义的类型都可以自动派生 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