tobytcp

TobyTcp is a protocol that allows for the use of a raw tcp stream for communicating messages, bi-directionally. It frames the messages with a length prefix to deliniate messages. This library provides methods to encode/decode that message prefix, but also provides async send & receive methods.

NOTE: Maybe ready for Production use. See below Disclaimer section.

Documentation

Writing

Look at the /examples and the unit tests for compiling examples!

let prefix = protocol::tobytcp_prefix(data.len());

stream.write_all(&prefix)?;
stream.write_all(&data)?;

// OR use the send method in lib, which does almost exactly ^
send(&mut data, &mut stream).await?;

Reading

Look at the /examples and the unit tests for compiling examples!

let mut len_buf = [0; 8];
stream.read_exact(&mut len_buf)?;
let length = protocol::tobytcp_len(len_buf);

let mut msg_buf = [0; length as usize];
stream.read_exact(&mut msg_buf)?; // Done, we have received the message into msg_buf

// OR use the receive method in lib which does almost exactly ^
let data = receive(&mut buf, &mut stream).await?;;

TobyTcp Protocol

The TobyTcp protocol uses length prefixing for message framing.

Specification

Messages must be prefixed by eight (8) bytes, for a total of 64 bits. This 8 byte/64 bit segment of every message must contain the number of bytes present in the message being sent (NOT including the 8 bytes used for describing the size). The length prefix must be big-endian.

Examples

You can use the protocol module to retreive the prefix, which has the length of your data.

Here is an example of an encoded messages. The message has 18 bytes of data, and in the end, 18 + 8 = 26 bytes are sent, with the first 8 bytes representing the length.

00 00 00 00 00 00 00 12 74 6f 62 79 20 69 73 20 61 20 67 6f 6f 64 20 64 6f 67

Also see the protocol tests to see what is expected!

Disclaimer

• This library provides async methods that are not usable with stable rust (check out areweasyncyet!), which is a large blocker for me considering this 1.0.
  • I could put the async methods behind a 'feature', but I'm unsure how to do that and no-one uses this so...
• Untested on 32 bit machines, not sure it will work!

License

The University of Illinois/NCSA (National Center for Supercomputing Applications) Open Source License

See LICENSE file. This a permissive open source license similar to Apache-2.0.