diff --git a/README.md b/README.md new file mode 100644 index 0000000..6b6baae --- /dev/null +++ b/README.md @@ -0,0 +1,34 @@ +# Sequential Exchange Protocol + +The reference implementation of the **Sequential Exchange Protocol**, or SEP. + +SEP is a peer-to-peer transport protocol that guarantees packets of data will always be received +in the same order they were sent. In addition, it also guarantees the sequential consistency of +stateful exchanges between the two communicating peers. + +A "stateful exchange" is defined here as a sequence of packets, where the first packet +initiates the exchange, and all subsequent packets are replies to the previous packet in the +exchange. + +SEP guarantees both peers will agree upon which packets are members of which exchanges, +and it guarantees each packet is received by each peer in sequential order. + +SEP is a tiny, dead simple protocol and we have implemented it here in less than 500 lines of code. + +## Why not TCP? + +TCP only guarantees packets will be received in the same order they were sent. +It has no inherent concept of "replying to a packet" and as such it cannot guarantee both sides +of a conversation have the same view of any stateful exchanges that take place. + +TCP is also much higher overhead. It requires a 1.5 RTT handshake to begin any connection, +it has a larger amount of metadata that must be transported with packets, and it has quite a few +features that slow down runtime regardless of whether or not they are used. +A lot of this overhead owes to TCPs sizeable complexity. + +That being said SEP does lack many of TCP's additional features, such as a dynamic resend timer, +keep-alives, and expiration handling. This can be both a pro and a con, as it means there is a +lot of efficiency to be gained if these features are not needed or are implemented at a +different protocol layer. + +Neither SEP nor TCP are cryptographically secure. diff --git a/src/lib.rs b/src/lib.rs index 893e7fb..e0057d6 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -13,7 +13,7 @@ //! //! SEP is a tiny, dead simple protocol and we have implemented it here in less than 500 lines of code. //! -//! # Why not TCP? +//! ## Why not TCP? //! //! TCP only guarantees packets will be received in the same order they were sent. //! It has no inherent concept of "replying to a packet" and as such it cannot guarantee both sides @@ -31,7 +31,7 @@ //! //! Neither SEP nor TCP are cryptographically secure. //! -//! # Examples +//! ## Examples //! #![no_std] #![forbid(unsafe_code)] @@ -63,7 +63,7 @@ impl IntoRecvData for TL::RecvData { } } -pub struct SeqQueue { +pub struct SeqEx { pub retry_interval: i64, next_send_seq_num: SeqNum, pre_recv_seq_num: SeqNum, @@ -93,14 +93,14 @@ pub enum Error { /// If it is dropped without calling `reply` an empty reply will be sent to the remote peer. pub struct ReplyGuard<'a, TL: TransportLayer> { app: Option<&'a TL>, - seq_queue: &'a mut SeqQueue, + seq_queue: &'a mut SeqEx, reply_num: SeqNum, } pub struct Iter<'a, TL: TransportLayer>(core::slice::Iter<'a, Option>>); pub struct IterMut<'a, TL: TransportLayer>(core::slice::IterMut<'a, Option>>); -impl SeqQueue { +impl SeqEx { pub fn new(retry_interval: i64, initial_seq_num: SeqNum) -> Self { Self { retry_interval, @@ -287,7 +287,7 @@ impl SeqQueue { IterMut(self.send_window.iter_mut()) } } -impl<'a, TL: TransportLayer> IntoIterator for &'a SeqQueue { +impl<'a, TL: TransportLayer> IntoIterator for &'a SeqEx { type Item = &'a TL::SendData; type IntoIter = Iter<'a, TL>; @@ -295,7 +295,7 @@ impl<'a, TL: TransportLayer> IntoIterator for &'a SeqQueue { self.iter() } } -impl<'a, TL: TransportLayer> IntoIterator for &'a mut SeqQueue { +impl<'a, TL: TransportLayer> IntoIterator for &'a mut SeqEx { type Item = &'a mut TL::SendData; type IntoIter = IterMut<'a, TL>;