src/lib.rs

   1 //! This crate provides a simple brokerless message-queue abstraction over asynchronous network
   2 //! streams.
   3 //!
   4 //! # Why?
   5 //! When building networked applications, developers shouldn't have to focus on repeatedly solving
   6 //! the problem of reliable, fault-tolerant message delivery over byte-streams. By using a message
   7 //! queue abstraction, crate users can focus on core application logic and leave the low-level
   8 //! networking and message-queue guarantees to the abstraction.
   9 //!
  10 //! # Examples
  11 //! Please use the [examples](https://github.com/sachanganesh/connect-rs/tree/main/examples)
  12 //! provided to help understand crate usage.
  13 //!
  14
  15 mod protocol;
  16 mod reader;
  17 pub mod tcp;
  18 pub mod tls;
  19 mod writer;
  20
  21 pub use crate::protocol::{ConnectDatagram, DatagramEmptyError};
  22 pub use crate::reader::ConnectionReader;
  23 pub use crate::writer::ConnectionWriter;
  24 use async_std::{net::SocketAddr, pin::Pin};
  25 use futures::{AsyncRead, AsyncWrite};
  26 pub use futures::{SinkExt, StreamExt};
  27
  28 /// Wrapper around a [`ConnectionReader`] and [`ConnectionWriter`] to read and write on a network
  29 /// connection.
  30 pub struct Connection {
  31     reader: ConnectionReader,
  32     writer: ConnectionWriter,
  33 }
  34
  35 #[allow(dead_code)]
  36 impl Connection {
  37     pub(crate) fn new(
  38         local_addr: SocketAddr,
  39         peer_addr: SocketAddr,
  40         read_stream: Pin<Box<dyn AsyncRead + Send + Sync>>,
  41         write_stream: Pin<Box<dyn AsyncWrite + Send + Sync>>,
  42     ) -> Self {
  43         Self {
  44             reader: ConnectionReader::new(local_addr, peer_addr, read_stream),
  45             writer: ConnectionWriter::new(local_addr, peer_addr, write_stream),
  46         }
  47     }
  48
  49     /// Get the local IP address and port.
  50     pub fn local_addr(&self) -> SocketAddr {
  51         self.reader.local_addr()
  52     }
  53
  54     /// Get the peer IP address and port.
  55     pub fn peer_addr(&self) -> SocketAddr {
  56         self.reader.peer_addr()
  57     }
  58
  59     /// Consume the [`Connection`] to split into separate [`ConnectionReader`] and
  60     /// [`ConnectionWriter`] halves.
  61     ///
  62     /// [`Connection`]s are split when reading and writing must be concurrent operations.
  63     pub fn split(self) -> (ConnectionReader, ConnectionWriter) {
  64         (self.reader, self.writer)
  65     }
  66
  67     /// Re-wrap the [`ConnectionReader`] and [`ConnectionWriter`] halves into a [`Connection`].
  68     pub fn join(reader: ConnectionReader, writer: ConnectionWriter) -> Self {
  69         Self { reader, writer }
  70     }
  71
  72     /// Get mutable access to the underlying [`ConnectionReader`].
  73     pub fn reader(&mut self) -> &mut ConnectionReader {
  74         &mut self.reader
  75     }
  76
  77     /// Get mutable access to the underlying [`ConnectionWriter`].
  78     pub fn writer(&mut self) -> &mut ConnectionWriter {
  79         &mut self.writer
  80     }
  81
  82     /// Close the connection by closing both the reading and writing halves.
  83     pub async fn close(self) -> SocketAddr {
  84         let peer_addr = self.peer_addr();
  85         let (reader, writer) = self.split();
  86
  87         drop(reader);
  88
  89         // writer.close().await;
  90         drop(writer);
  91
  92         return peer_addr;
  93     }
  94 }