protocol

protokol

Dokumentasi

Definisi protokol yang mudah di Rust.

Peti ini menambahkan turunan khusus yang dapat ditambahkan ke tipe, memungkinkan data terstruktur dikirim dan diterima dari aliran IO mana pun.

Jaringan sudah terpasang, dengan dukungan khusus untuk TCP dan UDP.

Protokol yang Anda tentukan juga dapat digunakan di luar jaringan - lihat metode Parcel::from_raw_bytes dan Parcel::raw_bytes .

Peti ini juga menyediakan:

• Modul TCP dan UDP untuk kemudahan pengiriman dan penerimaan Parcel
• Pustaka middleware generik untuk transformasi otomatis data yang dikirim/diterima
  • Middleware telah ditulis untuk mendukung kompresi
  • Middleware khusus dapat diimplementasikan melalui suatu sifat dengan dua metode

Lihat folder contoh untuk penggunaan.

Penggunaan

Tambahkan ini ke Cargo.toml Anda :

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

Dan kemudian tentukan tipe dengan atribut #[derive(protocol::Protocol)] :

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

Di bawah tenda

Bagian yang paling menarik di sini adalah protocol::Parcel . Tipe apa pun yang mengimplementasikan sifat ini kemudian dapat diserialkan ke dan dari aliran byte. Semua tipe primitif, koleksi standar, tupel, dan array menerapkan sifat ini.

Peti ini sangat berguna saat Anda menentukan jenis Parcel Anda sendiri. Anda dapat menggunakan #[derive(protocol::Protocol)] untuk melakukan ini. Perhatikan bahwa agar suatu tipe dapat diimplementasikan Parcel , tipe tersebut juga harus mengimplementasikan Clone , Debug , dan 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 > ,
}

Turunan khusus

Tipe apa pun yang ditentukan pengguna dapat memperoleh sifat Parcel secara otomatis.

Contoh

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

Diskriminator

Nilai enum dapat dikirimkan melalui indeks varian berbasis 1, atau dengan mengirimkan nama string setiap varian.

CATATAN: Perilaku defaultnya adalah menggunakan nama varian sebagai string ( string ).

Perilaku ini dapat diubah dengan atribut #[protocol(discriminant = "<type>")] .

Jenis diskriminan yang didukung:

• string (standar)
  • Ini mentransmisikan nama varian enum sebagai diskriminan over-the-wire
  • Ini menggunakan lebih banyak byte per pesan, tetapi sangat fleksibel
• integer
  • Ini mentransmisikan nomor varian berbasis 1 sebagai diskriminan over-the-wire
  • Jika varian enum memiliki diskriminator eksplisit, maka
  • Varian enum tidak dapat disusun ulang di sumbernya tanpa melanggar protokol

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

Lain-lain

Anda dapat mengganti nama varian untuk serialisasinya.

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