haddocks: added a note on resource allocation

cabal.project

@@ -1,4 +1,4 @@
-index-state:  2025-01-30T00:54:30Z
+index-state:  2025-05-05T00:00:00Z
 
 packages: ./typed-protocols
           ./typed-protocols-cborg
@@ -11,11 +11,8 @@ test-show-details: direct
 
 if impl(ghc >= 9.12)
   allow-newer:
-    -- https://github.com/well-typed/cborg/pull/339
-    , cborg:base
-    , cborg:ghc-prim
-    , serialise:base
-    , serialise:ghc-prim
+    , serdoc-core:template-haskell
+    , serdoc-core:th-abstraction
 
 if os(windows)
   package text

typed-protocols-doc/typed-protocols-doc.cabal

@@ -40,7 +40,7 @@ library
                  , base64-bytestring >=1.2.1.0 && <1.3
                  , blaze-html >=0.9.1.2 && <0.10
                  , bytestring >=0.11 && <0.13
-                 , containers >=0.6.8 && <0.7
+                 , containers >=0.6.8 && <0.8
                  , fgl >=5.7 && <5.9
                  , filepath >=1.4.2.2 && <1.6
                  , graphviz >=2999.20.1 && <2999.21.0
@@ -51,7 +51,7 @@ library
                  , template-haskell >=2.13.0.0
                  , temporary >=1.3 && <1.4
                  , text >=1.1 && <2.2
-                 , th-abstraction >=0.6.0.0 && <0.7
+                 , th-abstraction >=0.6.0.0 && <0.8
                  , time >=1.12 && <1.14
                  , serdoc-core
                  , typed-protocols

typed-protocols-stateful/src/Network/TypedProtocol/Stateful/Peer.hs

@@ -67,7 +67,14 @@ import Network.TypedProtocol.Core as Core
 -- 'Network.TypedProtocol.Peer.Client' or 'Network.TypedProtocol.Peer.Server'
 -- pattern synonyms provide this evidence automatically.
 --
--- TODO:
+-- __NOTE__:
+-- one should not allocate resources within a `Peer` since there's no way to
+-- safely clean-up resources in case of an asynchronous exception.  The proper
+-- way to allocate resources is to call
+-- `Network.TypedProtocol.Stateful.Driver.runPeerWithDriver` within
+-- a `Control.Exception.bracket`.
+--
+-- __TODO__:
 -- We are not exposing pipelined version, since it is not possible to write
 -- a driver & proofs in a type safe which take into account the state when the
 -- peer type only tracks depth of pipelining rather than pipelined transitions.

typed-protocols/src/Network/TypedProtocol/Peer.hs

@@ -79,6 +79,13 @@ import           Network.TypedProtocol.Core as Core
 -- "Network.TypedProtocol.Peer.Client" supply this evidence for you, and hence
 -- are easier to use and let you avoid some kinds of type errors.
 --
+-- __NOTE__:
+-- one should not allocate resources within a `Peer` since there's no way to
+-- safely clean-up resources in case of an asynchronous exception.  The proper
+-- way to allocate resources is to call
+-- `Network.TypedProtocol.Driver.runPeerWithDriver` (or `runPeer`,
+-- `runPipelinedPeer`) within a `Control.Exception.bracket`.
+--
 type Peer :: forall ps
           -> PeerRole
           -> IsPipelined