Trait AsyncNetstringRead

pub trait AsyncNetstringRead: AsyncRead + Unpin {
    // Provided methods
    fn read_netstring<'life0, 'life1, 'async_trait>(
        &'life0 mut self,
        buffer: &'life1 mut [u8],
    ) -> Pin<Box<dyn Future<Output = Result<usize>> + Send + 'async_trait>>
       where Self: Send + 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait { ... }
    fn read_netstring_alloc<'life0, 'async_trait>(
        &'life0 mut self,
    ) -> Pin<Box<dyn Future<Output = Result<Vec<u8>>> + Send + 'async_trait>>
       where Self: Send + 'async_trait,
             'life0: 'async_trait { ... }
}

The AsyncNetstringRead trait allows you to read one netstring at a time from any stream that has AsyncRead implemented. No implementation is thread-safe and multiple simultaneous reads can corrupt the message stream irreparably.

Provided Methods

fn read_netstring<'life0, 'life1, 'async_trait>( &'life0 mut self, buffer: &'life1 mut [u8], ) -> Pin<Box<dyn Future<Output = Result<usize>> + Send + 'async_trait>>

where Self: Send + 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

This method allows to read one netstring into the buffer given. It is advised to use this Trait on a tokio::io::BufReader to avoid repeated system calls during parsing.

Usage

use tokio_netstring::NetstringReader;

let buf = [0; 1024];
let len: usize = stream.read_netstring(&mut buf).await.unwrap();
let buf: &[u8] = &buf[..len];

Errors

This method returns a tokio::io::Result which is a re-export from std::io::Result.

ErrorKind::UnexpectedEof

This error kind is returned, if the stream got closed, before a Netstring could be fully read.

ErrorKind::BrokenPipe

This error type indicates that the buffer provided is to small for the netstring to fit in. In the current implementation this error is irrecoverable as it has corrupted the stream. Future implementations may allow to recover from this.

Is the feature err_drop_message set, then the netstring will be dropped. Therefor is the stream afterwards in a known stream an can be further used.

ErrorKind::InvalidData

This error can be returned on three occasions:

1. The size provided is to big. The length of the netstring is stored as a usize. Should the message provide a longer value, it is most likely an error and will be returned as such.

2. The Separator between length and the netstring is not b':'.

3. The Netstring does not end with a b','.

In all cases the stream is irreparably corrupted and the connection should therefor be dropped.

fn read_netstring_alloc<'life0, 'async_trait>( &'life0 mut self, ) -> Pin<Box<dyn Future<Output = Result<Vec<u8>>> + Send + 'async_trait>>

where Self: Send + 'async_trait, 'life0: 'async_trait,

This method allows to read one netstring. It returns the netstring as a Vec<u8> and allocates the memory itself, therefore avoiding a to small buffer.

While this may be use full during development, it should be avoided in production, since it can allocate memory and a DDOS attack is therefore easily possible.

Usage

use tokio_netstring::NetstringReader;

let netstring: Vec<u8> = stream.read_netstring_alloc(&mut buf).await.unwrap();

Errors

It returns the same errors as AsyncNetstringRead::read_netstring, but can’t fail because the buffer is to small.

Implementors

impl<Reader: AsyncRead + Unpin + ?Sized> AsyncNetstringRead for Reader