Crate npsd

source ·
Expand description

§npsd (Network Payload Serializer / Deserializer)

The npsd crate provides a flexible and efficient way to serialize and deserialize network payloads. It supports converting Rust types into byte streams suitable for network transmission and reconstructing those types from byte streams received over the network. This is particularly useful for networked applications that require efficient and reliable data exchange.

§Features

  • Serialize and deserialize complex Rust types to and from byte streams.
  • Support for custom serialization contexts.
  • Middleware support for extensible processing during serialization/deserialization.

§Examples

§Sync Schema

Requires the sync feature to be enabled.

use npsd::{Payload, Schema, Next, Info};

#[derive(Schema, Info, PartialEq, Debug)]
enum Animal {
    Dog,
    Frog(String, Vec<isize>),
    Cat { age: usize, name: String },
    AntHive(Vec<String>),
}

#[test]
fn test_schema() {
    // Create Middleware
    let mut next = Next::default();
 
    // Create an instance of `Animal`.
    let animal = Animal::Frog("Frog".to_string(), vec![12393818, -19383812, 11111, -1093838482]);

    // Serialize the `animal` instance into a packet.
    animal.into_packet(&mut (), &mut next).unwrap();

    // Create a copy of serialized data if needed
    let _serialized = next.serialized();

    // Deserialize the packet back into an `Animal` instance.
    let deserialized = Animal::from_packet(&mut (), &mut next).unwrap();

    // Ensure the deserialized instance matches the original.
    assert_eq!(deserialized, animal);
}

§Async Schema

Requires the async feature to be enabled.

use npsd::{AsyncPayload, AsyncSchema, Next, Info};

#[derive(AsyncSchema, Info, PartialEq, Debug)]
enum Animal {
    Dog,
    Frog(String, Vec<isize>),
    Cat { age: usize, name: String },
    AntHive(Vec<String>),
}

#[tokio::test]
async fn test_schema() {
    // Create Middleware
    let mut next = Next::default();

    // Create an instance of `Animal`.
    let animal = Animal::Frog("Frog".to_string(), vec![12393818, -19383812, 11111, -1093838482]);

    // Serialize the `animal` instance into a packet.
    animal.poll_into_packet(&mut (), &mut next).await.unwrap();

    // Create a copy of serialized data if needed
    let _serialized = next.serialized();

    // Deserialize the packet back into an `Animal` instance.
    let deserialized = Animal::poll_from_packet(&mut (), &mut next).await.unwrap();

    // Ensure the deserialized instance matches the original.
    assert_eq!(deserialized, animal);
}

§Sync Bitmap

Requires the sync feature to be enabled.

use npsd::{Payload, Bitmap, Next, Info};

#[derive(Bitmap, Info, PartialEq, Debug)]
struct Flags {
   a: bool,
   b: bool,
   c: bool,
}

#[test]
fn test_bitmap() {
   // Create Middleware
   let mut next = Next::default();

   // Create an u8 bitmap of `Flags`.
   let flags = Flags { a: true, b: false, c: true };

   // Serialize the `Flags` into a packet.
   flags.into_packet(&mut (), &mut next).unwrap();

   // Create a copy of serialized data if needed
   let _serialized = next.serialized();

   // Deserialize the packet back into an `Flags`.
   let deserialized = Flags::from_packet(&mut (), &mut next).unwrap();

   // Ensure the deserialized matches the original.
   assert_eq!(deserialized, flags);
}

§Async Bitmap

Requires the async feature to be enabled.

use npsd::{AsyncPayload, AsyncBitmap, Next, Info};

#[derive(AsyncBitmap, Info, PartialEq, Debug)]
struct Flags {
   a: bool,
   b: bool,
   c: bool,
}

#[tokio::test]
async fn test_async_bitmap() {
   // Create Middleware
   let mut next = Next::default();

   // Create an u8 bitmap of `Flags`.
   let flags = Flags { a: true, b: false, c: true };

   // Serialize the `Flags` into a packet.
   flags.poll_into_packet(&mut (), &mut next).await.unwrap();

   // Create a copy of serialized data if needed
   let _serialized = next.serialized();

   // Deserialize the packet back into an `Flags`.
   let deserialized = Flags::poll_from_packet(&mut (), &mut next).await.unwrap();

   // Ensure the deserialized matches the original.
   assert_eq!(deserialized, flags);
}

§Middleware Trait

The Middleware trait defines methods for converting types to and from payloads of bytes.

§Methods

  • fn into_payload<C, T: IntoPayload<C>>(&mut self, value: &T, ctx: &mut C) -> Result<(), Error>:
    • Converts a value into a payload of bytes. This method takes a value and a context, serializes the value into a byte stream, and writes the resulting bytes into the handler.
  • fn from_payload<'a, 'b, C, T: FromPayload<'a, C>>(&mut self, ctx: &mut C) -> Result<T, Error>:
    • Converts a payload of bytes back into a value. This method reads bytes from the handler, uses the context to interpret them, and reconstructs the original value.
  • fn write<T>(&mut self, data: &[T]) -> Result<(), Error>:
    • Writes raw data into the handler. This method takes a slice of data and appends it to the handler after ensuring that the size of the data elements is 1 byte.
  • fn read<'a, 'b, T>(&'b mut self, nbytes: usize) -> Result<&'a [T], Error>:
    • Reads raw data from the handler. This method reads a specified number of bytes from the handler, splits the handler’s data accordingly, and returns a slice of the read data.
  • fn serialized(&self) -> Vec<u8>:
    • Returns the serialized data as a Vec<u8>.

Re-exports§

Modules§

Macros§

Traits§

  • FromPayload
    The FromPayload trait is used to convert a payload of bytes back into a type.
  • IntoPayload
    The IntoPayload trait is used to convert a type into a payload of bytes.
  • Middleware
  • Payload
    The Payload trait combines IntoPayload and FromPayload to facilitate complete serialization and deserialization of types.
  • PayloadInfo
    The PayloadInfo trait provides metadata about the payload.

Derive Macros§