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::new(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.take_data().unwrap();
  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
  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 tag (2 bytes), and recipient tag (2 bytes).
  60 The size-prefix and version tag are used internally to deserialize messages received from the
  61 network connection. The recipient tag is intended for crate users to identify the message
  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 recipient tag to signify which serialization format was used for that message
  74 - Use the recipient tag to signify the type of message being sent
  75
  76 ## Contributing
  77
  78 This crate gladly accepts contributions. Don't hesitate to open issues or PRs.
  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                                      |               |