9 releases
0.2.4 | Feb 15, 2021 |
---|---|
0.2.3 |
|
0.1.2 | Feb 4, 2021 |
0.1.1 |
|
0.0.8 | Feb 4, 2021 |
#2 in #aio
43 downloads per month
Used in twirl
51KB
771 lines
connect-rs
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
- TLS (enable
tls
feature flag)
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, ConnectionReader
s will return ConnectDatagram
s 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
Feature Status
Feature | Status |
---|---|
TCP Client | ✓ |
TCP Server | ✓ |
TLS Client | ✓ |
TLS Server | ✓ |
SCTP Client | |
SCTP Server | |
DTLS-SCTP Client | |
DTLS-SCTP Server |
Contributing
This crate gladly accepts contributions. Don't hesitate to open issues or PRs.
Dependencies
~5–17MB
~261K SLoC