//! Please use the [examples](https://github.com/sachanganesh/connect-rs/tree/main/examples)
//! provided to help understand crate usage.
//!
-//! # Protobuf
-//! This crate relies on the use of [Protocol Buffers](https://developers.google.com/protocol-buffers)
-//! due to it being widely adopted and industry-proven. All messages are Protobuf messages that
-//! are packed into a Protobuf `Any` type and then sent over the wire. Message recipients must
-//! decide what Protobuf message type it is, and correspondingly unpack the `Any` into a particular
-//! message type.
-//!
-//! Protobuf was chosen when the library hit a roadblock with Rust's `TypeId` potentially not being
-//! consistent between Rust compiler versions. The crate requires a consistent way to determine what
-//! type of message is received, so it can appropriately deserialize the message from network bytes.
-//! Until the Rust ecosystem around reflection improves, the crate will use Protobuf to fill the
-//! void.
-pub mod protocol;
+mod protocol;
mod reader;
pub mod tcp;
pub mod tls;
pub use futures::{SinkExt, StreamExt};
/// Wrapper around a [`ConnectionReader`] and [`ConnectionWriter`] to read and write on a network
-/// connection
+/// connection.
pub struct Connection {
- local_addr: SocketAddr,
- peer_addr: SocketAddr,
reader: ConnectionReader,
writer: ConnectionWriter,
}
write_stream: Pin<Box<dyn AsyncWrite + Send + Sync>>,
) -> Self {
Self {
- local_addr,
- peer_addr,
reader: ConnectionReader::new(local_addr, peer_addr, read_stream),
writer: ConnectionWriter::new(local_addr, peer_addr, write_stream),
}
}
- /// Get the local IP address and port
+ /// Get the local IP address and port.
pub fn local_addr(&self) -> SocketAddr {
- self.local_addr.clone()
+ self.reader.local_addr()
}
- /// Get the peer IP address and port
+ /// Get the peer IP address and port.
pub fn peer_addr(&self) -> SocketAddr {
- self.peer_addr.clone()
+ self.reader.peer_addr()
}
/// Consume the [`Connection`] to split into separate [`ConnectionReader`] and
- /// [`ConnectionWriter`] halves
+ /// [`ConnectionWriter`] halves.
///
/// [`Connection`]s are split when reading and writing must be concurrent operations.
pub fn split(self) -> (ConnectionReader, ConnectionWriter) {
(self.reader, self.writer)
}
- /// Re-wrap the [`ConnectionReader`] and [`ConnectionWriter`] halves into a [`Connection`]
+ /// Re-wrap the [`ConnectionReader`] and [`ConnectionWriter`] halves into a [`Connection`].
pub fn join(reader: ConnectionReader, writer: ConnectionWriter) -> Self {
- Self {
- local_addr: reader.local_addr(),
- peer_addr: reader.peer_addr(),
- reader,
- writer,
- }
+ Self { reader, writer }
}
- /// Get mutable access to the underlying [`ConnectionReader`]
+ /// Get mutable access to the underlying [`ConnectionReader`].
pub fn reader(&mut self) -> &mut ConnectionReader {
&mut self.reader
}
- /// Get mutable access to the underlying [`ConnectionWriter`]
+ /// Get mutable access to the underlying [`ConnectionWriter`].
pub fn writer(&mut self) -> &mut ConnectionWriter {
&mut self.writer
}
- /// Close the connection by closing both the reading and writing halves
+ /// Close the connection by closing both the reading and writing halves.
pub async fn close(self) -> SocketAddr {
let peer_addr = self.peer_addr();
let (reader, writer) = self.split();
pub use futures::StreamExt;
use std::io::Cursor;
-/// A default buffer size to read in bytes and then deserialize as messages
+/// A default buffer size to read in bytes and then deserialize as messages.
const BUFFER_SIZE: usize = 8192;
-/// An interface to read messages from the network connection
+/// An interface to read messages from the network connection.
///
/// Implements the [`Stream`] trait to asynchronously read messages from the network connection.
///
impl ConnectionReader {
/// Creates a new [`ConnectionReader`] from an [`AsyncRead`] trait object and the local and peer
- /// socket metadata
+ /// socket metadata.
pub fn new(
local_addr: SocketAddr,
peer_addr: SocketAddr,
}
}
- /// Get the local IP address and port
+ /// Get the local IP address and port.
pub fn local_addr(&self) -> SocketAddr {
self.local_addr.clone()
}
- /// Get the peer IP address and port
+ /// Get the peer IP address and port.
pub fn peer_addr(&self) -> SocketAddr {
self.peer_addr.clone()
}
- /// Check if the [`Stream`] of messages from the network is closed
+ /// Check if the [`Stream`] of messages from the network is closed.
pub fn is_closed(&self) -> bool {
self.closed
}
pub use futures::SinkExt;
pub use futures::StreamExt;
-/// An interface to write messages to the network connection
+/// An interface to write messages to the network connection.
///
/// Implements the [`Sink`] trait to asynchronously write messages to the network connection.
///
impl ConnectionWriter {
/// Creates a new [`ConnectionWriter`] from an [`AsyncWrite`] trait object and the local and peer
- /// socket metadata
+ /// socket metadata.
pub fn new(
local_addr: SocketAddr,
peer_addr: SocketAddr,
}
}
- /// Get the local IP address and port
+ /// Get the local IP address and port.
pub fn local_addr(&self) -> SocketAddr {
self.local_addr.clone()
}
- /// Get the peer IP address and port
+ /// Get the peer IP address and port.
pub fn peer_addr(&self) -> SocketAddr {
self.peer_addr.clone()
}
- /// Check if the [`Sink`] of messages to the network is closed
+ /// Check if the [`Sink`] of messages to the network is closed.
pub fn is_closed(&self) -> bool {
self.closed
}
projects / connect-rs.git / commitdiff