protocol

протокол

Документация

Простое определение протоколов в Rust.

Этот набор добавляет пользовательский производный код, который можно добавлять к типам, позволяя отправлять и получать структурированные данные из любого потока ввода-вывода.

Сеть встроена со специальной поддержкой TCP и UDP.

Определенный вами протокол можно использовать и вне сети — см. методы Parcel::from_raw_bytes и Parcel::raw_bytes .

В этом ящике также предусмотрено:

• Модули TCP и UDP для удобной отправки и получения Parcel .
• Универсальная библиотека промежуточного программного обеспечения для автоматического преобразования отправленных/полученных данных.
  • Промежуточное программное обеспечение уже написано для поддержки сжатия.
  • Пользовательское промежуточное программное обеспечение может быть реализовано с помощью типажа двумя методами.

Ознакомьтесь с папкой примеров для использования.

Использование

Добавьте это в свой 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 ;
        }
    }
} 

Перечисления

Дискриминаторы

Значения перечисления могут передаваться либо по индексу варианта, начинающемуся с 1, либо путем передачи имени строки каждого варианта.

ПРИМЕЧАНИЕ. По умолчанию имя варианта используется в виде строки ( string ).

Это поведение можно изменить с помощью атрибута #[protocol(discriminant = "<type>")] .

Поддерживаемые типы дискриминантов:

• string (по умолчанию)
  • Это передает имя варианта перечисления в качестве дискриминанта по беспроводной сети.
  • При этом используется больше байтов на сообщение, но это очень гибко.
• integer
  • Это передает номер варианта, отсчитываемый от 1, в качестве дискриминанта по проводной связи.
  • Если варианты перечисления имеют явные дискриминаторы,
  • Варианты перечисления не могут быть переупорядочены в исходном коде без нарушения протокола.

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