Documented Network.Tox.Session.

1 files changed, 58 insertions, 17 deletions

diff --git a/src/Network/Tox/Session.hs b/src/Network/Tox/Session.hs
index 7b84ba80..e8be4d01 100644
--- a/src/Network/Tox/Session.hs
+++ b/src/Network/Tox/Session.hs
@@ -1,5 +1,11 @@
+-- | This module implements the lossless Tox session protocol.
 {-# LANGUAGE TupleSections #-}
-module Network.Tox.Session where
+module Network.Tox.Session
+    ( SessionParams(..)
+    , SessionKey
+    , Session(..)
+    , handshakeH
+    ) where
 
 import Control.Concurrent.STM
 import Control.Monad
@@ -18,35 +24,64 @@ import Network.Tox.Crypto.Transport
 import Network.Tox.DHT.Transport    (Cookie,key2id)
 import Network.Tox.Handshake
 
+-- | Alias for 'SecretKey' to document that it is used as the temporary Tox
+-- session key corresponding to the 'PublicKey' we sent in the handshake.
 type SessionKey = SecretKey
 
+-- | These inputs to 'handshakeH' indicate how to respond to handshakes, how to
+-- assign packets to sessions, and what to do with established sessions after
+-- they are made lossless by queuing packets and appending sequence numbers.
 data SessionParams = SessionParams
-    { spCrypto           :: TransportCrypto
+    { -- | The database of secret keys necessary to encrypt handshake packets.
+      spCrypto           :: TransportCrypto
+      -- | This is used to create sessions and dispatch packets to them.
     , spSessions         :: Sessions (CryptoPacket Encrypted)
+      -- | This method returns the session information corresponding to the
+      -- cookie pair for the remote address.  If no handshake was sent, this
+      -- should send one immediately.  It should return 'Nothing' if anything
+      -- goes wrong.
     , spGetSentHandshake :: SecretKey -> SockAddr
                                       -> Cookie Identity
                                       -> Cookie Encrypted
                                       -> IO (Maybe (SessionKey, HandshakeData))
+      -- | This method is invoked on each new session and is responsible for
+      -- launching any threads necessary to keep the session alive.
     , spOnNewSession     :: Session -> IO ()
     }
 
+-- | After a session is established, this information is given to the
+-- 'spOnNewSession' callback.
 data Session = Session
-    { sOurKey            :: SecretKey
+    { -- | This is the secret user (toxid) key that corresponds to the
+      -- local-end of this session.
+      sOurKey            :: SecretKey
+      -- | The remote address for this session. (Not unique, see 'sSessionID').
     , sTheirAddr         :: SockAddr
+      -- | The information we sent in the handshake for this session.
     , sSentHandshake     :: HandshakeData
+      -- | The information we received in a handshake for this session.
     , sReceivedHandshake :: Handshake Identity
+      -- | This method can be used to trigger packets to be re-sent given a
+      -- list of their sequence numbers.  It should be used when the remote end
+      -- indicates they lost packets.
     , sResendPackets     :: [Word32] -> IO ()
-      -- ^ If they request that we re-send certain packets, this method is how
-      -- that is accomplished.
-    , sMissingInbound    :: IO ([Word32],Word32)
-      -- ^ This list of sequence numbers should be periodically polled and if
+      -- | This list of sequence numbers should be periodically polled and if
       -- it is not empty, we should request they re-send these packets.  For
       -- convenience, a lower bound for the numbers in the list is also
       -- returned.  Suggested polling interval: a few seconds.
+    , sMissingInbound    :: IO ([Word32],Word32)
+      -- | A lossless transport for sending and receiving packets in this
+      -- session.  It is up to the caller to spawn the await-loop to handle
+      -- inbound packets.
     , sTransport         :: Transport String () CryptoMessage
+      -- | A unique small integer that identifies this session for as long as
+      -- it is established.
     , sSessionID         :: Int
     }
 
+-- | Call this whenever a new handshake arrives so that a session is
+-- negotiated.  It always returns Nothing which makes it convenient to use with
+-- 'Network.QueryResponse.addHandler'.
 handshakeH :: SessionParams
               -> SockAddr
               -> Handshake Encrypted
@@ -101,6 +136,18 @@ plainHandshakeH sp saddr skey handshake = do
             }
     return ()
 
+
+-- | The per-session nonce and key state maintained by 'decryptPacket' and
+-- 'encryptPacket'.
+data SessionKeys = SessionKeys
+    { skCrypto        :: TransportCrypto -- ^ Cache of shared-secrets.
+    , skMe            :: SessionKey      -- ^ My session key
+    , skThem          :: PublicKey       -- ^ Their session key
+    , skNonceIncoming :: TVar Nonce24    -- ^ +21845 when a threshold is reached.
+    , skNonceOutgoing :: TVar Nonce24    -- ^ +1 on every packet
+    }
+
+-- | Decrypt an inbound session packet and update the nonce for the next one.
 decryptPacket :: SessionKeys -> SockAddr -> CryptoPacket Encrypted -> IO (Maybe (CryptoPacket Identity, ()))
 decryptPacket sk saddr (CryptoPacket n16 ciphered) = do
     (n24,δ) <- atomically $ do
@@ -121,6 +168,7 @@ decryptPacket sk saddr (CryptoPacket n16 ciphered) = do
 
             return $ Just ( CryptoPacket n16 (pure x), () )
 
+-- | Encrypt an outbound session packet and update the nonce for the next one.
 encryptPacket :: SessionKeys -> CryptoData -> IO (CryptoPacket Encrypted)
 encryptPacket sk plain = do
     n24 <- atomically $ do
@@ -136,15 +184,9 @@ encryptPacket sk plain = do
 
     return $ CryptoPacket (nonce24ToWord16 n24) ciphered
 
-data SessionKeys = SessionKeys
-    { skCrypto        :: TransportCrypto
-    , skMe            :: SecretKey -- My session key
-    , skThem          :: PublicKey -- Their session key
-    , skNonceIncoming :: TVar Nonce24 -- +21845 when a threshold is reached.
-    , skNonceOutgoing :: TVar Nonce24 -- +1 on every packet
-    }
-
 
+-- | Add sequence information to an outbound packet.
+--
 -- From spec.md:
 --
 --   Data in the encrypted packets:
@@ -152,8 +194,6 @@ data SessionKeys = SessionKeys
 --    [our recvbuffers buffer_start, (highest packet number handled + 1), (big endian)]
 --    [uint32_t packet number if lossless, sendbuffer buffer_end if lossy, (big endian)]
 --    [data]
-
-
 bookKeeping :: SequenceInfo -> CryptoMessage -> CryptoData
 bookKeeping (SequenceInfo seqno ack) m = CryptoData
     { bufferStart = ack   :: Word32
@@ -161,6 +201,7 @@ bookKeeping (SequenceInfo seqno ack) m = CryptoData
     , bufferData  = m
     }
 
+-- | Classify an inbound packet as lossy or lossless based on its id byte.
 checkLossless :: CryptoData -> PacketInboundEvent CryptoMessage
 checkLossless cd@CryptoData{ bufferStart = ack
                            , bufferEnd   = no