protocol and client specs

src/Simplex/Messaging/Client.hs

@@ -641,6 +641,7 @@ getProtocolClient g nm transportSession@(_, srv, _) cfg@ProtocolClientConfig {qS
           atomically $ do
             writeTVar (connected c) True
             putTMVar cVar $ Right c'
+          -- spec: spec/modules/Simplex/Messaging/Client.md#four-concurrent-threads--teardown-semantics
           raceAny_ ([send c' th, process c', receive c' th] <> [monitor c' | smpPingInterval > 0])
             `E.finally` disconnected c'
 
@@ -689,6 +690,7 @@ getProtocolClient g nm transportSession@(_, srv, _) cfg@ProtocolClientConfig {qS
       forM_ msgQ $ \q ->
         mapM_ (atomically . writeTBQueue q . serverTransmission c) (L.nonEmpty ts')
 
+    -- spec: spec/modules/Simplex/Messaging/Client.md#processmsg--server-events-vs-expired-responses
     processMsg :: ProtocolClient v err msg -> Transmission (Either err msg) -> IO (Maybe (EntityId, ServerTransmission err msg))
     processMsg ProtocolClient {client_ = PClient {sentCommands}} (corrId, entId, respOrErr)
       | B.null $ bs corrId = sendMsg $ STEvent clientResp
@@ -1338,11 +1340,13 @@ sendProtocolCommand_ c@ProtocolClient {client_ = PClient {sndQ}, thParams = THan
             | batch = tEncodeBatch1 serviceAuth t
             | otherwise = tEncode serviceAuth t
 
+-- spec: spec/modules/Simplex/Messaging/Client.md#nonblockingwritetbqueue--fork-on-full
 nonBlockingWriteTBQueue :: TBQueue a -> a -> IO ()
 nonBlockingWriteTBQueue q x = do
   sent <- atomically $ tryWriteTBQueue q x
   unless sent $ void $ forkIO $ atomically $ writeTBQueue q x
 
+-- spec: spec/modules/Simplex/Messaging/Client.md#getresponse--pending-flag-race-contract
 getResponse :: ProtocolClient v err msg -> NetworkRequestMode -> Maybe Int -> Request err msg -> IO (Response err msg)
 getResponse ProtocolClient {client_ = PClient {tcpTimeout, timeoutErrorCount}} nm tOut Request {entityId, pending, responseVar} = do
   r <- fromMaybe (netTimeoutInt tcpTimeout nm) tOut `timeout` atomically (takeTMVar responseVar)
@@ -1382,6 +1386,7 @@ mkTransmission_ ProtocolClient {thParams, client_ = PClient {clientCorrId, sentC
       atomically $ TM.insert corrId r sentCommands
       pure r
 
+-- spec: spec/modules/Simplex/Messaging/Client.md#authtransmission--dual-auth-with-service-signature
 authTransmission :: Maybe (THandleAuth 'TClient) -> Bool -> Maybe C.APrivateAuthKey -> C.CbNonce -> ByteString -> Either TransportError (Maybe TAuthorizations)
 authTransmission thAuth serviceAuth pKey_ nonce t = traverse authenticate pKey_
   where

src/Simplex/Messaging/Client/Agent.hs

@@ -275,6 +275,7 @@ connectClient ca@SMPClientAgent {agentCfg, dbService, smpClients, smpSessions, m
 
     removeClientAndSubs :: SMPClient -> IO (Maybe ServiceSub, Maybe (Map QueueId C.APrivateAuthKey))
     removeClientAndSubs smp = do
+      -- spec: spec/modules/Simplex/Messaging/Client/Agent.md#removeclientandsubs--outside-stm-lookup-optimization
       -- Looking up subscription vars outside of STM transaction to reduce re-evaluation.
       -- It is possible because these vars are never removed, they are only added.
       sVar_ <- TM.lookupIO srv $ activeServiceSubs ca
@@ -452,6 +453,7 @@ smpSubscribeQueues ca smp srv subs = do
       pure acc
     sessId = sessionId $ thParams smp
     smpServiceId = smpClientServiceId smp
+    -- spec: spec/modules/Simplex/Messaging/Client/Agent.md#groupsub--subscription-response-classification
     groupSub ::
       Map QueueId C.APrivateAuthKey ->
       ((QueueId, C.APrivateAuthKey), Either SMPClientError (Maybe ServiceId)) ->

src/Simplex/Messaging/Protocol.hs

@@ -527,6 +527,7 @@ tEncodeAuth serviceAuth = \case
       TASignature s -> C.signatureBytes s
       TAAuthenticator (C.CbAuthenticator s) -> s
 
+-- spec: spec/modules/Simplex/Messaging/Protocol.md#transmissionauth--size-based-type-discrimination
 decodeTAuthBytes :: ByteString -> Maybe (C.Signature 'C.Ed25519) -> Either String (Maybe TAuthorizations)
 decodeTAuthBytes s serviceSig
   | B.null s = Right Nothing
@@ -1703,6 +1704,7 @@ instance ToJSON BlockingReason where
 instance FromJSON BlockingReason where
   parseJSON = strParseJSON "BlockingReason"
 
+-- spec: spec/modules/Simplex/Messaging/Protocol.md#transmissionp--implysessid
 -- | SMP transmission parser.
 transmissionP :: THandleParams v p -> Parser RawTransmission
 transmissionP THandleParams {sessionId, implySessId, serviceAuth} = do
@@ -2244,6 +2246,7 @@ batchTransmissions' THandleParams {batch, blockSize = bSize, serviceAuth} ts
           s = tEncode serviceAuth t
 
 -- | Pack encoded transmissions into batches
+-- spec: spec/modules/Simplex/Messaging/Protocol.md#batchtransmissions_--constraints-and-ordering
 batchTransmissions_ :: Int -> NonEmpty (Either TransportError ByteString, r) -> [TransportBatch r]
 batchTransmissions_ bSize = addBatch . foldr addTransmission ([], 0, 0, [], [])
   where