1 files changed, 65 insertions, 1 deletions

diff --git a/Connection/Tox/Threads.hs b/Connection/Tox/Threads.hs
index 8b19c7cf..dcee37d1 100644
--- a/Connection/Tox/Threads.hs
+++ b/Connection/Tox/Threads.hs
@@ -12,7 +12,7 @@
 module Connection.Tox.Threads where
 
 import Connection
-import Connection.Tox
+-- import Connection.Tox
 import Data.IP (IP)
 import Network.Tox.Crypto.Transport
 import Network.Tox.NodeId
@@ -27,6 +27,70 @@ import Data.Function
 import Data.Functor.Identity
 import System.Timeout
 
+
+-- | This type indicates the progress of a tox encrypted friend link
+-- connection.  Two scenarios are illustrated below.  The parenthesis show the
+-- current 'G.Status' 'ToxProgress' of the session.
+--
+--
+-- Perfect handshake scenario:
+--
+--  Peer 1                                  Peer 2
+--  (InProgress AcquiringCookie)            (Dormant/InProgress AcquiringCookie)
+--                     Cookie request ->
+--                                       <- Cookie response
+--  (InProgress AwaitingHandshake)          (Dormant/InProgress AcquiringCookie)
+--                   Handshake packet ->
+--                                          * accepts connection
+--                                          (InProgress AwaitingSessionPacket)
+--                                       <- Handshake packet
+--  *accepts connection
+--  (InProgress AwaitingSessionPacket)
+--                   Encrypted packet -> <- Encrypted packet
+--  *confirms connection                    *confirms connection
+--  (Established)                           (Established)
+--
+--                           Connection successful.
+--
+--                  Encrypted packets -> <- Encrypted packets
+--
+--
+--
+--
+--  More realistic handshake scenario:
+--  Peer 1                                  Peer 2
+--  (InProgress AcquiringCookie)            (Dormant/InProgress AcquiringCookie)
+--                      Cookie request ->   *packet lost*
+--                      Cookie request ->
+--                                        <- Cookie response
+--  (InProgress AwaitingHandshake)           (Dormant/InProgress AcquiringCookie)
+--
+--                                           *Peer 2 randomly starts new connection to peer 1
+--                                           (InProgress AcquiringCookie)
+--                                        <- Cookie request
+--                     Cookie response ->
+--                                           (InProgress AwaitingHandshake)
+--
+--                    Handshake packet -> <- Handshake packet
+--  *accepts connection                      * accepts connection
+--  (InProgress AwaitingSessionPacket)      (InProgress AwaitingSessionPacket)
+--
+--                    Encrypted packet -> <- Encrypted packet
+--  *confirms connection                     *confirms connection
+--  (Established)                           (Established)
+--
+--                              Connection successful.
+--
+--                   Encrypted packets -> <- Encrypted packets
+data ToxProgress
+    = AwaitingDHTKey        -- ^ Waiting to receive their DHT key.
+    | AcquiringIPAddress    -- ^ Searching DHT to obtain their node's IP & port.
+    | AcquiringCookie       -- ^ Attempting to obtain a cookie.
+    | AwaitingHandshake     -- ^ Waiting to receive a handshake.
+    | AwaitingSessionPacket -- ^ Connection is "accepted" but not yet "confirmed".
+    deriving (Eq,Ord,Enum,Show)
+
+
 type NodeSearch = Search NodeId (IP,PortNumber) () NodeInfo NodeInfo
 
 data AcceptContactMethods = AcceptContactMethods