README.md

   1 # connect-rs
   2
   3 [![Crates.io][crates-badge]][crates-url]
   4 [![Docs.rs][docs-badge]][docs-url]
   5
   6 [crates-badge]: https://img.shields.io/crates/v/connect.svg
   7 [crates-url]: https://crates.io/crates/connect
   8 [docs-badge]: https://docs.rs/connect/badge.svg
   9 [docs-url]: https://docs.rs/connect
  10
  11 This Rust crate provides a simple, brokerless message-queue abstraction over asynchronous
  12 network streams. It guarantees ordered message delivery and reception, and both TCP and TLS
  13 transports are supported.
  14
  15 ## Examples
  16
  17 ````rust
  18 // create a client connection to the server
  19 let mut conn = Connection::tcp_client(ip_address).await?;
  20
  21 // construct a new message
  22 let msg = String::from("Hello world!");
  23 let envelope: ConnectDatagram = ConnectDatagram::with_tag(65535, msg.into_bytes())?;
  24
  25 // send a message to the server
  26 conn.writer().send(envelope).await?;
  27
  28 // wait for the echo-server to reply with an echo
  29 if let Some(mut envelope) = conn.reader().next().await {
  30     // take the message payload from the envelope
  31     let data: Vec<u8> = envelope.data().to_vec();
  32
  33     // reconstruct the original message
  34     let msg = String::from_utf8(data)?;
  35     assert_eq!("Hello world!", msg.as_str());
  36 }
  37 ````
  38
  39 In addition to the [crate documentation](https://docs.rs/connect/latest/connect/), please use
  40 the provided [example programs](https://github.com/sachanganesh/connect-rs/tree/main/examples)
  41 as a practical reference for crate usage.
  42
  43 - TCP
  44     - [TCP Echo Server](https://github.com/sachanganesh/connect-rs/tree/main/examples/tcp-echo-server)
  45     - [TCP Client](https://github.com/sachanganesh/connect-rs/tree/main/examples/tcp-client)
  46 - TLS (enable `tls` feature flag)
  47     - [TLS Echo Server](https://github.com/sachanganesh/connect-rs/tree/main/examples/tls-echo-server)
  48     - [TLS Client](https://github.com/sachanganesh/connect-rs/tree/main/examples/tls-client)
  49
  50 ## Why?
  51
  52 When building networked applications, developers shouldn't have to focus on repeatedly solving
  53 the problem of reliable, ordered message delivery over byte-streams. By using a message
  54 queue abstraction, crate users can focus on core application logic and leave the low-level
  55 networking and message-queue guarantees to the abstraction.
  56
  57 Connect provides a `ConnectionWriter` and `ConnectionReader` interface to concurrently send
  58 and receive messages over a network connection. Each user-provided message is prefixed by 8
  59 bytes, containing a size-prefix (4 bytes), version field (2 bytes), and tag field (2 bytes).
  60 The size-prefix and version field are used internally to deserialize messages received from the
  61 network connection. The tag field is intended for crate users to label the message for a
  62 recipient, although the library leaves that up to the user's discretion.
  63
  64 Library users must serialize their custom messages into bytes (`Vec<u8>`), prior to
  65 constructing a `ConnectDatagram`, which can then be passed to a `ConnectionWriter`.
  66 Consequently, `ConnectionReader`s will return `ConnectDatagram`s containing the message payload
  67 (`Vec<u8>` again) to the user to deserialize.
  68
  69 Requiring crate users to serialize data before constructing a datagram may appear redundant, but
  70 gives the developer the freedom to use a serialization format of their choosing. This means that
  71 library users can do interesting things such as:
  72
  73 - Use the tag field to signify which serialization format was used for that message
  74 - Use the tag field to signify the type of message being sent
  75
  76 ## Feature Flags
  77
  78 - `tls`: enables usage of tls transport functionality
  79
  80 ## Feature Status
  81
  82 | Feature                                               | Status        |
  83 |-----------------------------------------------------  |--------       |
  84 | [TCP Client](examples/tcp-client)                         |    ✓    |
  85 | [TCP Server](examples/tcp-echo-server)                    |    ✓    |
  86 | [TLS Client](examples/tls-client)                         |    ✓    |
  87 | [TLS Server](examples/tls-echo-server)                    |    ✓    |
  88 | SCTP Client                                           |               |
  89 | SCTP Server                                           |               |
  90 | DTLS-SCTP Client                                      |               |
  91 | DTLS-SCTP Server                                      |               |
  92
  93 ## Contributing
  94
  95 This crate gladly accepts contributions. Please don't hesitate to open issues or PRs.