src/lib.rs

   1 //! This Rust crate provides a simple, brokerless message-queue abstraction over asynchronous
   2 //! network streams. It guarantees ordered message delivery and reception, and both TCP and TLS
   3 //! transports are supported.
   4 //!
   5 //! # Examples
   6 //!
   7 //! ````ignore
   8 //! // create a client connection to the server
   9 //! let mut conn = Connection::tcp_client(ip_address).await?;
  10 //!
  11 //! // construct a new message
  12 //! let msg = String::from("Hello world!");
  13 //! let envelope: ConnectDatagram = ConnectDatagram::new(65535, msg.into_bytes())?;
  14 //!
  15 //! // send a message to the server
  16 //! conn.writer().send(envelope).await?;
  17 //!
  18 //! // wait for the echo-server to reply with an echo
  19 //! if let Some(mut envelope) = conn.reader().next().await {
  20 //!     // take the message payload from the envelope
  21 //!     let data: Vec<u8> = envelope.take_data().unwrap();
  22 //!
  23 //!     // reconstruct the original message
  24 //!     let msg = String::from_utf8(data)?;
  25 //!     assert_eq!("Hello world!", msg.as_str());
  26 //! }
  27 //! ````
  28 //!
  29 //! In addition to the [crate documentation](https://docs.rs/connect/latest/connect/), please use
  30 //! the provided [example programs](https://github.com/sachanganesh/connect-rs/tree/main/examples)
  31 //! as a practical reference for crate usage.
  32 //!
  33 //! - TCP
  34 //!     - [TCP Echo Server](https://github.com/sachanganesh/connect-rs/tree/main/examples/tcp-echo-server)
  35 //!     - [TCP Client](https://github.com/sachanganesh/connect-rs/tree/main/examples/tcp-client)
  36 //! - TLS
  37 //!     - [TLS Echo Server](https://github.com/sachanganesh/connect-rs/tree/main/examples/tls-echo-server)
  38 //!     - [TLS Client](https://github.com/sachanganesh/connect-rs/tree/main/examples/tls-client)
  39 //!
  40 //! # Why?
  41 //!
  42 //! When building networked applications, developers shouldn't have to focus on repeatedly solving
  43 //! the problem of reliable, ordered message delivery over byte-streams. By using a message
  44 //! queue abstraction, crate users can focus on core application logic and leave the low-level
  45 //! networking and message-queue guarantees to the abstraction.
  46 //!
  47 //! Connect provides a `ConnectionWriter` and `ConnectionReader` interface to concurrently send
  48 //! and receive messages over a network connection. Each user-provided message is prefixed by 8
  49 //! bytes, containing a size-prefix (4 bytes), version tag (2 bytes), and recipient tag (2 bytes).
  50 //! The size-prefix and version tag are used internally to deserialize messages received from the
  51 //! network connection. The recipient tag is intended for crate users to identify the message
  52 //! recipient, although the library leaves that up to the user's discretion.
  53 //!
  54 //! Library users must serialize their custom messages into bytes (`Vec<u8>`), prior to
  55 //! constructing a `ConnectDatagram`, which can then be passed to a `ConnectionWriter`.
  56 //! Consequently, `ConnectionReader`s will return `ConnectDatagram`s containing the message payload
  57 //! (`Vec<u8>` again) to the user to deserialize.
  58 //!
  59 //! Requiring crate users to serialize data before constructing a datagram may appear redundant, but
  60 //! gives the developer the freedom to use a serialization format of their choosing. This means that
  61 //! library users can do interesting things such as:
  62 //!
  63 //! - Use the recipient tag to signify which serialization format was used for that message
  64 //! - Use the recipient tag to signify the type of message being sent
  65 //!
  66
  67 #![feature(doc_cfg)]
  68
  69 mod protocol;
  70 mod reader;
  71 pub mod tcp;
  72 mod writer;
  73
  74 #[cfg(feature = "tls")]
  75 #[doc(cfg(feature = "tls"))]
  76 pub mod tls;
  77
  78 use async_std::{net::SocketAddr, pin::Pin};
  79 use futures::{AsyncRead, AsyncWrite};
  80
  81 pub use crate::protocol::{ConnectDatagram, DatagramError};
  82 pub use crate::reader::ConnectionReader;
  83 pub use crate::writer::{ConnectionWriteError, ConnectionWriter};
  84 pub use futures::{SinkExt, StreamExt};
  85
  86 /// Wrapper around a [`ConnectionReader`] and [`ConnectionWriter`] to read and write on a network
  87 /// connection.
  88 pub struct Connection {
  89     reader: ConnectionReader,
  90     writer: ConnectionWriter,
  91 }
  92
  93 #[allow(dead_code)]
  94 impl Connection {
  95     pub(crate) fn new(
  96         local_addr: SocketAddr,
  97         peer_addr: SocketAddr,
  98         read_stream: Pin<Box<dyn AsyncRead + Send + Sync>>,
  99         write_stream: Pin<Box<dyn AsyncWrite + Send + Sync>>,
 100     ) -> Self {
 101         Self {
 102             reader: ConnectionReader::new(local_addr, peer_addr, read_stream),
 103             writer: ConnectionWriter::new(local_addr, peer_addr, write_stream),
 104         }
 105     }
 106
 107     /// Get the local IP address and port.
 108     pub fn local_addr(&self) -> SocketAddr {
 109         self.reader.local_addr()
 110     }
 111
 112     /// Get the peer IP address and port.
 113     pub fn peer_addr(&self) -> SocketAddr {
 114         self.reader.peer_addr()
 115     }
 116
 117     /// Consume the [`Connection`] to split into separate [`ConnectionReader`] and
 118     /// [`ConnectionWriter`] halves.
 119     ///
 120     /// [`Connection`]s are split when reading and writing must be concurrent operations.
 121     pub fn split(self) -> (ConnectionReader, ConnectionWriter) {
 122         (self.reader, self.writer)
 123     }
 124
 125     /// Re-wrap the [`ConnectionReader`] and [`ConnectionWriter`] halves into a [`Connection`].
 126     pub fn join(reader: ConnectionReader, writer: ConnectionWriter) -> Self {
 127         Self { reader, writer }
 128     }
 129
 130     /// Get mutable access to the underlying [`ConnectionReader`].
 131     pub fn reader(&mut self) -> &mut ConnectionReader {
 132         &mut self.reader
 133     }
 134
 135     /// Get mutable access to the underlying [`ConnectionWriter`].
 136     pub fn writer(&mut self) -> &mut ConnectionWriter {
 137         &mut self.writer
 138     }
 139
 140     /// Close the connection by closing both the reading and writing halves.
 141     pub async fn close(self) -> SocketAddr {
 142         let peer_addr = self.peer_addr();
 143         let (reader, writer) = self.split();
 144
 145         drop(reader);
 146
 147         // writer.close().await;
 148         drop(writer);
 149
 150         return peer_addr;
 151     }
 152 }
 153
 154 #[cfg(test)]
 155 mod tests {}