protocol

protocolo

Documentação

Definições fáceis de protocolo em Rust.

Essa caixa adiciona uma derivação personalizada que pode ser adicionada aos tipos, permitindo que dados estruturados sejam enviados e recebidos de qualquer fluxo de IO.

A rede é integrada, com suporte especial para TCP e UDP.

O protocolo que você define também pode ser usado fora da rede - consulte os métodos Parcel::from_raw_bytes e Parcel::raw_bytes .

Esta caixa também fornece:

• Módulos TCP e UDP para fácil envio e recebimento de Parcel
• Uma biblioteca genérica de middleware para transformação automática de dados enviados/recebidos
  • Middleware já foi escrito para suportar compactação
  • O middleware personalizado pode ser implementado por meio de uma característica com dois métodos

Confira a pasta de exemplos para uso.

Uso

Adicione isto ao seu Cargo.toml :

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

E então defina um tipo com o atributo #[derive(protocol::Protocol)] :

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

Sob o capô

A parte mais interessante aqui é a característica protocol::Parcel . Qualquer tipo que implemente essa característica pode então ser serializado de e para um fluxo de bytes. Todos os tipos primitivos, coleções padrão, tuplas e arrays implementam essa característica.

Esta caixa se torna particularmente útil quando você define seus próprios tipos Parcel . Você pode usar #[derive(protocol::Protocol)] para fazer isso. Observe que para que um tipo implemente Parcel , ele também deve implementar Clone , Debug e 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 > ,
}

Derivação personalizada

Qualquer tipo definido pelo usuário pode ter a característica Parcel derivada automaticamente.

Exemplo

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

Enums

Discriminadores

Os valores enum podem ser transmitidos por seu índice de variante baseado em 1 ou pela transmissão do nome da string de cada variante.

NOTA: O comportamento padrão é usar o nome da variante como uma string ( string ).

Este comportamento pode ser alterado pelo atributo #[protocol(discriminant = "<type>")] .

Tipos discriminantes suportados:

• string (padrão)
  • Isso transmite o nome da variante enum como o discriminante over-the-wire
  • Isso usa mais bytes por mensagem, mas é muito flexível
• integer
  • Isso transmite o número da variante baseado em 1 como o discriminante over-the-wire
  • Se as variantes enum tiverem discriminadores explícitos, o
  • As variantes Enum não podem ser reordenadas na origem sem quebrar o 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 } ,
}

Diversos

Você pode renomear a variante para sua serialização.

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