Crate connect

This Rust crate provides a simple, brokerless message-queue abstraction over asynchronous network streams. It guarantees ordered message delivery and reception, and both TCP and TLS transports are supported.

Examples

// create a client connection to the server
let mut conn = Connection::tcp_client(ip_address).await?;

// construct a new message
let msg = String::from("Hello world!");
let envelope: ConnectDatagram = ConnectDatagram::new(65535, msg.into_bytes())?;

// send a message to the server
conn.writer().send(envelope).await?;

// wait for the echo-server to reply with an echo
if let Some(mut envelope) = conn.reader().next().await {
    // take the message payload from the envelope
    let data: Vec<u8> = envelope.take_data().unwrap();

    // reconstruct the original message
    let msg = String::from_utf8(data)?;
    assert_eq!("Hello world!", msg.as_str());
}

In addition to the crate documentation, please use the provided example programs as a practical reference for crate usage.

• TCP
  • TCP Echo Server
  • TCP Client
• TLS (enable tls feature flag)
  • TLS Echo Server
  • TLS Client

Why?

When building networked applications, developers shouldn’t have to focus on repeatedly solving the problem of reliable, ordered message delivery over byte-streams. By using a message queue abstraction, crate users can focus on core application logic and leave the low-level networking and message-queue guarantees to the abstraction.

Connect provides a ConnectionWriter and ConnectionReader interface to concurrently send and receive messages over a network connection. Each user-provided message is prefixed by 8 bytes, containing a size-prefix (4 bytes), version tag (2 bytes), and recipient tag (2 bytes). The size-prefix and version tag are used internally to deserialize messages received from the network connection. The recipient tag is intended for crate users to identify the message recipient, although the library leaves that up to the user’s discretion.

Library users must serialize their custom messages into bytes (Vec<u8>), prior to constructing a ConnectDatagram, which can then be passed to a ConnectionWriter. Consequently, ConnectionReaders will return ConnectDatagrams containing the message payload (Vec<u8> again) to the user to deserialize.

Requiring crate users to serialize data before constructing a datagram may appear redundant, but gives the developer the freedom to use a serialization format of their choosing. This means that library users can do interesting things such as:

• Use the recipient tag to signify which serialization format was used for that message
• Use the recipient tag to signify the type of message being sent

Feature Flags

• tls: enables usage of tls transport functionality

Modules

tcp

TCP transport client and listener implementations.

tls

TLS transport client and listener implementations.

Structs

ConnectDatagram

A simple size-prefixed packet format containing a version tag, recipient tag, and message body.

Connection

Wrapper around a ConnectionReader and ConnectionWriter to read and write on a network connection.

ConnectionReader

An interface to read messages from the network connection.

ConnectionWriter

An interface to write messages to the network connection.

Enums

ConnectionWriteError

Encountered when there is an issue with writing messages on the network stream.

DatagramError

Encountered when there is an issue constructing, serializing, or deserializing a ConnectDatagram.

Traits

SinkExt

An extension trait for Sinks that provides a variety of convenient combinator functions.

StreamExt

An extension trait for Streams that provides a variety of convenient combinator functions.