protocol

protocole

Documentation

Définitions de protocoles simples dans Rust.

Cette caisse ajoute une dérivée personnalisée qui peut être ajoutée aux types, permettant d'envoyer et de recevoir des données structurées à partir de n'importe quel flux IO.

La mise en réseau est intégrée, avec une prise en charge spéciale de TCP et UDP.

Le protocole que vous définissez peut également être utilisé en dehors du réseau - voir les méthodes Parcel::from_raw_bytes et Parcel::raw_bytes .

Cette caisse fournit également :

• Modules TCP et UDP pour faciliter l'envoi et la réception de Parcel
• Une bibliothèque middleware générique pour la transformation automatique des données envoyées/reçues
  • Un middleware a déjà été écrit pour prendre en charge la compression
  • Un middleware personnalisé peut être implémenté via un trait avec deux méthodes

Consultez le dossier d'exemples pour son utilisation.

Usage

Ajoutez ceci à votre Cargo.toml :

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

Et puis définissez un type avec l'attribut #[derive(protocol::Protocol)] :

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

Sous le capot

La partie la plus intéressante ici est le trait protocol::Parcel . Tout type qui implémente ce trait peut ensuite être sérialisé vers et depuis un flux d'octets. Tous les types primitifs, collections standard, tuples et tableaux implémentent ce trait.

Cette caisse devient particulièrement utile lorsque vous définissez vos propres types Parcel . Vous pouvez utiliser #[derive(protocol::Protocol)] pour ce faire. Notez que pour qu'un type implémente Parcel , il doit également implémenter Clone , Debug et 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 > ,
}

Dérive personnalisée

Tout type défini par l'utilisateur peut dériver automatiquement le trait Parcel .

Exemple

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

Énumérations

Discriminateurs

Les valeurs d'énumération peuvent être transmises soit par leur index de variante basé sur 1, soit en transmettant le nom de chaîne de chaque variante.

REMARQUE : Le comportement par défaut consiste à utiliser le nom de la variante sous forme de chaîne ( string ).

Ce comportement peut être modifié par l'attribut #[protocol(discriminant = "<type>")] .

Types discriminants pris en charge :

• string (par défaut)
  • Ceci transmet le nom de la variante d'énumération en tant que discriminant via le réseau.
  • Cela utilise plus d'octets par message, mais c'est très flexible
• integer
  • Celui-ci transmet le numéro de variante basé sur 1 comme discriminant par fil.
  • Si les variantes d'énumération ont des discriminateurs explicites, le
  • Les variantes d'énumération ne peuvent pas être réorganisées dans la source sans rompre le protocole

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

Divers

Vous pouvez renommer la variante pour sa sérialisation.

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