protocol

プロトコル

ドキュメント

Rust での簡単なプロトコル定義。

このクレートは型に追加できるカスタム派生を追加し、任意の IO ストリームから構造化データを送受信できるようにします。

ネットワークが組み込まれており、TCP と UDP を特別にサポートします。

定義したプロトコルはネットワークの外でも使用できます。Parcel Parcel::from_raw_bytesとParcel::raw_bytesメソッドを参照してください。

このクレートには次のものも含まれます。

• Parcelの送受信を容易にする TCP および UDP モジュール
• 送受信データを自動変換する汎用ミドルウェアライブラリ
  • ミドルウェアは圧縮をサポートするようにすでに作成されています
  • カスタムミドルウェアは 2 つの方法でトレイト経由で実装できます

使用方法については、サンプル フォルダーをチェックアウトしてください。

使用法

これを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 (デフォルト)
  • これにより、列挙型バリアント名が回線上の識別子として送信されます。
  • これにより、メッセージあたりにより多くのバイトが使用されますが、非常に柔軟です
• integer
  • これにより、1 から始まるバリアント番号が有線判別式として送信されます。
  • enum バリアントに明示的な識別子がある場合、
  • 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 ,
}