protocol

โปรโตคอล

เอกสารประกอบ

คำจำกัดความโปรโตคอลง่าย ๆ ใน Rust

ลังนี้เพิ่มการสืบทอดแบบกำหนดเองที่สามารถเพิ่มลงในประเภทได้ ทำให้สามารถส่งและรับข้อมูลที่มีโครงสร้างจากสตรีม IO ใดก็ได้

ระบบเครือข่ายมีอยู่แล้วภายใน พร้อมการสนับสนุนพิเศษสำหรับ TCP และ UDP

โปรโตคอลที่คุณกำหนดสามารถใช้นอกเครือข่ายได้เช่นกัน - ดูวิธี Parcel::from_raw_bytes และ Parcel::raw_bytes

ลังนี้ยังมี:

• โมดูล TCP และ UDP เพื่อการส่งและรับ Parcel ที่ง่ายดาย
• ไลบรารีมิดเดิลแวร์ทั่วไปสำหรับการแปลงข้อมูลที่ส่ง/รับโดยอัตโนมัติ
  • มิดเดิลแวร์ได้รับการเขียนเพื่อรองรับการบีบอัดข้อมูลแล้ว
  • มิดเดิลแวร์แบบกำหนดเองสามารถนำไปใช้ผ่านลักษณะด้วยสองวิธี

ชำระเงินโฟลเดอร์ตัวอย่างสำหรับการใช้งาน

การใช้งาน

เพิ่มสิ่งนี้ลงใน Cargo.toml ของคุณ:

[ dependencies ]
protocol = { version = " 3.4 " , features = [ " derive " ] }

จากนั้นกำหนดประเภทด้วยแอตทริบิวต์ #[derive(protocol::Protocol)] :

 # [ derive ( protocol :: Protocol ) ]
struct Hello {
    pub a : String ,
    pub b : u32 ,
} 

ภายใต้ประทุน

ส่วนที่น่าสนใจที่สุดคือ protocol::Parcel ประเภทใดๆ ที่ใช้คุณลักษณะนี้สามารถซีเรียลไลซ์ไปและกลับจากสตรีมไบต์ได้ ประเภทดั้งเดิม คอลเลกชันมาตรฐาน สิ่งอันดับ และอาร์เรย์ทั้งหมดใช้คุณลักษณะนี้

ลังนี้จะมีประโยชน์อย่างยิ่งเมื่อคุณกำหนดประเภท Parcel ของคุณเอง คุณสามารถใช้ #[derive(protocol::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 ได้โดยอัตโนมัติ

ตัวอย่าง

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

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

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

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

# [ protocol ( discriminant = "integer" ) ]
# [ derive ( protocol :: 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 ;
        }
    }
} 

เอนัม

ผู้เลือกปฏิบัติ

ค่า Enum สามารถส่งผ่านดัชนีตัวแปรแบบ 1 หรือโดยการส่งชื่อสตริงของแต่ละตัวแปร

หมายเหตุ: การทำงานเริ่มต้นคือการใช้ ชื่อตัวแปรเป็นสตริง ( string )

ลักษณะการทำงานนี้สามารถเปลี่ยนแปลงได้โดยแอตทริบิวต์ #[protocol(discriminant = "<type>")]

ประเภทการเลือกปฏิบัติที่รองรับ:

• string (ค่าเริ่มต้น)
  • สิ่งนี้จะส่งชื่อตัวแปร enum เป็นตัวจำแนกแบบ over-the-wire
  • สิ่งนี้ใช้ไบต์ต่อข้อความมากกว่า แต่มีความยืดหยุ่นมาก
• integer
  • สิ่งนี้จะส่งหมายเลขตัวแปรฐาน 1 เป็นตัวแยกแยะแบบโอเวอร์เดอะไวร์
  • หากตัวแปรแจงนับมีการเลือกปฏิบัติที่ชัดเจน
  • ไม่สามารถเรียงลำดับตัวแปร Enum ใหม่ในแหล่งที่มาได้โดยไม่ทำให้โปรโตคอลเสียหาย

 # [ derive ( protocol :: 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 :: 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 ,
}