protocol

Protokoll

Dokumentation

Einfache Protokolldefinitionen in Rust.

Diese Kiste fügt eine benutzerdefinierte Ableitung hinzu, die zu Typen hinzugefügt werden kann, sodass strukturierte Daten von jedem E/A-Stream gesendet und empfangen werden können.

Die Vernetzung ist integriert, mit spezieller Unterstützung für TCP und UDP.

Das von Ihnen definierte Protokoll kann auch außerhalb des Netzwerks verwendet werden – siehe die Methoden Parcel::from_raw_bytes und Parcel::raw_bytes .

Diese Kiste bietet außerdem:

• TCP- und UDP-Module zum einfachen Senden und Empfangen von Parcel
• Eine generische Middleware-Bibliothek zur automatischen Transformation gesendeter/empfangener Daten
  • Es wurde bereits Middleware geschrieben, die die Komprimierung unterstützt
  • Benutzerdefinierte Middleware kann über ein Trait mit zwei Methoden implementiert werden

Sehen Sie sich den Beispielordner zur Verwendung an.

Verwendung

Fügen Sie dies zu Ihrem Cargo.toml hinzu:

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

Und dann definieren Sie einen Typ mit dem Attribut #[derive(protocol::Protocol)] :

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

Unter der Haube

Der interessanteste Teil hier ist das protocol::Parcel Merkmal. Jeder Typ, der dieses Merkmal implementiert, kann dann in und aus einem Bytestream serialisiert werden. Alle primitiven Typen, Standardsammlungen, Tupel und Arrays implementieren dieses Merkmal.

Diese Kiste ist besonders nützlich, wenn Sie Ihre eigenen Parcel definieren. Dazu können Sie #[derive(protocol::Protocol)] verwenden. Beachten Sie, dass ein Typ, damit er Parcel implementieren kann, auch Clone , Debug und PartialEq implementieren muss.

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

Benutzerdefinierte Ableitung

Für jeden benutzerdefinierten Typ kann das Merkmal Parcel automatisch abgeleitet werden.

Beispiel

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

Aufzählungen

Diskriminatoren

Enum-Werte können entweder über ihren 1-basierten Variantenindex oder durch die Übermittlung des Zeichenfolgennamens jeder Variante übertragen werden.

HINWEIS: Das Standardverhalten besteht darin , den Variantennamen als Zeichenfolge ( string ) zu verwenden.

Dieses Verhalten kann durch das Attribut #[protocol(discriminant = "<type>")] geändert werden.

Unterstützte Diskriminanztypen:

• string (Standard)
  • Dadurch wird der Enum-Variantenname als Over-the-Wire-Diskriminante übertragen
  • Dies verbraucht mehr Bytes pro Nachricht, ist aber sehr flexibel
• integer
  • Dadurch wird die 1-basierte Variantennummer als Over-the-Wire-Diskriminante übertragen
  • Wenn Enum-Varianten explizite Diskriminatoren haben, wird die
  • Enum-Varianten können in der Quelle nicht neu angeordnet werden, ohne das Protokoll zu beschädigen

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

Sonstiges

Sie können die Variante für ihre Serialisierung umbenennen.

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