protocol

protocolo

Documentación

Definiciones de protocolo sencillas en Rust.

Esta caja agrega una derivación personalizada que se puede agregar a los tipos, lo que permite enviar y recibir datos estructurados desde cualquier flujo de IO.

La conexión en red está integrada, con soporte especial para TCP y UDP.

El protocolo que defina también se puede utilizar fuera de la red; consulte los métodos Parcel::from_raw_bytes y Parcel::raw_bytes .

Esta caja también proporciona:

• Módulos TCP y UDP para enviar y recibir Parcel fácilmente
• Una biblioteca de middleware genérica para la transformación automática de datos enviados/recibidos.
  • Ya se ha escrito middleware para soportar la compresión.
  • El middleware personalizado se puede implementar mediante un rasgo con dos métodos

Consulte la carpeta de ejemplos para conocer su uso.

Uso

Agregue esto a su Cargo.toml :

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

Y luego defina un tipo con el atributo #[derive(protocol::Protocol)] :

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

Debajo del capó

La parte más interesante aquí es el rasgo protocol::Parcel . Cualquier tipo que implemente este rasgo se puede serializar hacia y desde un flujo de bytes. Todos los tipos primitivos, colecciones estándar, tuplas y matrices implementan este rasgo.

Esta caja resulta particularmente útil cuando define sus propios tipos Parcel . Puedes usar #[derive(protocol::Protocol)] para hacer esto. Tenga en cuenta que para que un tipo implemente Parcel , también debe implementar Clone , Debug y 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 > ,
}

derivación personalizada

Cualquier tipo definido por el usuario puede tener el rasgo Parcel derivado automáticamente.

Ejemplo

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

Enumeraciones

Discriminadores

Los valores de enumeración se pueden transmitir mediante su índice de variante basado en 1 o transmitiendo el nombre de cadena de cada variante.

NOTA: El comportamiento predeterminado es utilizar el nombre de la variante como una cadena ( string ).

Este comportamiento se puede cambiar mediante el atributo #[protocol(discriminant = "<type>")] .

Tipos discriminantes soportados:

• string (predeterminada)
  • Esto transmite el nombre de la variante de enumeración como discriminante por cable
  • Esto utiliza más bytes por mensaje, pero es muy flexible.
• integer
  • Esto transmite el número de variante basado en 1 como discriminante por cable
  • Si las variantes de enumeración tienen discriminadores explícitos, el
  • Las variantes de enumeración no se pueden reordenar en la fuente sin romper el protocolo

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

Varios

Puede cambiar el nombre de la variante para su serialización.

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