improve documentation and logging

[connect-rs.git] / src / lib.rs

diff --git a/src/lib.rs b/src/lib.rs
index b3c3232504eda596d25d1227fd4e4b7a0b82d975..b99dd986ef6b9c5189b54edd59e990f4cbe8689c 100644 (file)
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -1,16 +1,68 @@
-//! This crate provides a simple, brokerless message-queue abstraction over asynchronous network
-//! streams.
+//! This Rust crate provides a simple, brokerless message-queue abstraction over asynchronous
+//! network streams. It guarantees ordered message delivery and reception, and both TCP and TLS
+//! transports are supported.
 //!
 //! # Examples
-//! Please use the [example programs](https://github.com/sachanganesh/connect-rs/tree/main/examples)
-//! provided to help understand crate usage.
+//!
+//! ````ignore
+//! // create a client connection to the server
+//! let mut conn = Connection::tcp_client(ip_address).await?;
+//!
+//! // construct a new message
+//! let msg = String::from("Hello world!");
+//! let envelope: ConnectDatagram = ConnectDatagram::new(65535, msg.into_bytes())?;
+//!
+//! // send a message to the server
+//! conn.writer().send(envelope).await?;
+//!
+//! // wait for the echo-server to reply with an echo
+//! if let Some(mut envelope) = conn.reader().next().await {
+//!     // take the message payload from the envelope
+//!     let data: Vec<u8> = envelope.take_data().unwrap();
+//!
+//!     // reconstruct the original message
+//!     let msg = String::from_utf8(data)?;
+//!     assert_eq!("Hello world!", msg.as_str());
+//! }
+//! ````
+//!
+//! In addition to the [crate documentation](https://docs.rs/connect/latest/connect/), please use
+//! the provided [example programs](https://github.com/sachanganesh/connect-rs/tree/main/examples)
+//! as a practical reference for crate usage.
+//!
+//! - TCP
+//!     - [TCP Echo Server](https://github.com/sachanganesh/connect-rs/tree/main/examples/tcp-echo-server)
+//!     - [TCP Client](https://github.com/sachanganesh/connect-rs/tree/main/examples/tcp-client)
+//! - TLS
+//!     - [TLS Echo Server](https://github.com/sachanganesh/connect-rs/tree/main/examples/tls-echo-server)
+//!     - [TLS Client](https://github.com/sachanganesh/connect-rs/tree/main/examples/tls-client)
 //!
 //! # Why?
+//!
 //! When building networked applications, developers shouldn't have to focus on repeatedly solving
-//! the problem of reliable, fault-tolerant message delivery over byte-streams. By using a message
+//! the problem of reliable, ordered message delivery over byte-streams. By using a message
 //! queue abstraction, crate users can focus on core application logic and leave the low-level
 //! networking and message-queue guarantees to the abstraction.
 //!
+//! Connect provides a `ConnectionWriter` and `ConnectionReader` interface to concurrently send
+//! and receive messages over a network connection. Each user-provided message is prefixed by 8
+//! bytes, containing a size-prefix (4 bytes), version tag (2 bytes), and recipient tag (2 bytes).
+//! The size-prefix and version tag are used internally to deserialize messages received from the
+//! network connection. The recipient tag is intended for crate users to identify the message
+//! recipient, although the library leaves that up to the user's discretion.
+//!
+//! Library users must serialize their custom messages into bytes (`Vec<u8>`), prior to
+//! constructing a `ConnectDatagram`, which can then be passed to a `ConnectionWriter`.
+//! Consequently, `ConnectionReader`s will return `ConnectDatagram`s containing the message payload
+//! (`Vec<u8>` again) to the user to deserialize.
+//!
+//! Requiring crate users to serialize data before constructing a datagram may appear redundant, but
+//! gives the developer the freedom to use a serialization format of their choosing. This means that
+//! library users can do interesting things such as:
+//!
+//! - Use the recipient tag to signify which serialization format was used for that message
+//! - Use the recipient tag to signify the type of message being sent
+//!
 
 #![feature(doc_cfg)]