connection handler: renamed HandleError as HandlerError

This exception is not just used when a `Handle` is created but also when
the connection handler is running.

Author: coot

ouroboros-network-framework/CHANGELOG.md

@@ -4,6 +4,8 @@
 
 ### Breaking changes
 
+* `HandleError` renamed as `HandlerError`, also `HandlerErrorType` and `classifyHandlerError`.
+
 ### Non-breaking changes
 
 ## 0.19.0.0 -- 28.06.2025

ouroboros-network-framework/demo/connection-manager.hs

@@ -280,7 +280,7 @@ withBidirectionalConnectionManager snocket makeBearer socket
                     },
                   updateVersionData = \a _ -> a,
                   connStateIdSupply,
-                  classifyHandleError = (\_ -> HandshakeFailure)
+                  classifyHandlerError = (\_ -> HandshakeFailure)
                 }
               (InResponderMode inbgovInfoChannel)
               connectionHandler
@@ -566,7 +566,7 @@ bidirectionalExperiment
                             (HandleWithExpandedCtx
                               Mux.InitiatorResponderMode peerAddr
                               UnversionedProtocolData ByteString IO () ())
-                            (HandleError
+                            (HandlerError
                               UnversionedProtocol))
     connect n cm | n <= 1 =
       acquireOutboundConnection cm InitiatorAndResponderDiffusionMode remoteAddr

ouroboros-network-framework/sim-tests/Test/Ouroboros/Network/ConnectionManager.hs

@@ -784,7 +784,7 @@ prop_valid_transitions (Fixed rnd) (SkewedBool bindToLocalAddress) scheduleMap =
             outboundIdleTimeout = testOutboundIdleTimeout,
             updateVersionData = \a _ -> a,
             connStateIdSupply,
-            classifyHandleError = \_ -> HandshakeFailure }
+            classifyHandlerError = \_ -> HandshakeFailure }
           (InResponderMode inbgovInfoChannel)
           connectionHandler
           $ \(connectionManager

ouroboros-network-framework/src/Ouroboros/Network/ConnectionHandler.hs

@@ -31,8 +31,8 @@ module Ouroboros.Network.ConnectionHandler
   ( Handle (..)
   , HandleWithExpandedCtx
   , HandleWithMinimalCtx
-  , HandleError (..)
-  , classifyHandleError
+  , HandlerError (..)
+  , classifyHandlerError
   , MkMuxConnectionHandler (..)
   , MuxConnectionHandler
   , makeConnectionHandler
@@ -110,7 +110,7 @@ sduHandshakeTimeout = 10
 -- * 'HandleHandshakeServerError'
 --                - the connection handler thread was running server side of the
 --                handshake protocol, which fail with 'HandshakeException'
--- * 'HandleError'
+-- * 'HandlerError'
 --                - the multiplexer thrown 'MuxError'.
 --
 data Handle (muxMode :: Mx.Mode) initiatorCtx responderCtx versionData bytes m a b =
@@ -155,48 +155,46 @@ type HandleWithMinimalCtx muxMode peerAddr versionData bytes m a b =
                           (ResponderContext peerAddr)
                           versionData bytes m a b
 
-data HandleError versionNumber where
-    HandleHandshakeClientError
-      :: !(HandshakeException versionNumber)
-      -> HandleError versionNumber
-
-    HandleHandshakeServerError
-      :: !(HandshakeException versionNumber)
-      -> HandleError versionNumber
+-- | A connection handler error.
+--
+-- It is returned either when creating the `Handle` or raised by the connection
+-- handler.
+--
+data HandlerError versionNumber =
+    -- | A handshake exception when creating `Handle`.
+    HandleHandshakeClientError !(HandshakeException versionNumber)
 
-    HandleError
-     :: !SomeException
-     -> HandleError versionNumber
+    -- | A handshake exception when creating `Handle`.
+  | HandleHandshakeServerError !(HandshakeException versionNumber)
 
-instance Show versionNumber
-      => Show (HandleError versionNumber) where
-    show (HandleHandshakeServerError err) = "HandleHandshakeServerError " ++ show err
-    show (HandleHandshakeClientError err) = "HandleHandshakeClientError " ++ show err
-    show (HandleError err)                = "HandleError " ++ show err
+    -- | A connection handler exception (e.g. might be a mini-protocol error, io
+    -- exception, etc).
+  | HandlerError !SomeException
+  deriving Show
 
 instance ( Typeable versionNumber
          , Show versionNumber
          )
-      => Exception (HandleError versionNumber) where
-    displayException (HandleHandshakeClientError err) = "handshake client error: " ++ displayException err
-    displayException (HandleHandshakeServerError err) = "handshake server error: " ++ displayException err
-    displayException (HandleError err)                = show err
+      => Exception (HandlerError versionNumber) where
+    displayException (HandleHandshakeClientError err) = "handshake client error: " ++ show err
+    displayException (HandleHandshakeServerError err) = "handshake server error: " ++ show err
+    displayException (HandlerError err)                = "connection handler error: " ++ show err
 
 
-classifyHandleError :: HandleError versionNumber
-                    -> HandleErrorType
-classifyHandleError (HandleHandshakeClientError (HandshakeProtocolLimit _)) =
+classifyHandlerError :: HandlerError versionNumber
+                     -> HandlerErrorType
+classifyHandlerError (HandleHandshakeClientError (HandshakeProtocolLimit _)) =
     HandshakeProtocolViolation
 -- TODO: 'HandshakeProtocolError' is not a protocol error! It is just
 -- a negotiation failure.  It should be renamed.
-classifyHandleError (HandleHandshakeClientError (HandshakeProtocolError _)) =
+classifyHandlerError (HandleHandshakeClientError (HandshakeProtocolError _)) =
     HandshakeFailure
-classifyHandleError (HandleHandshakeServerError (HandshakeProtocolLimit _)) =
+classifyHandlerError (HandleHandshakeServerError (HandshakeProtocolLimit _)) =
     HandshakeProtocolViolation
-classifyHandleError (HandleHandshakeServerError (HandshakeProtocolError _)) =
+classifyHandlerError (HandleHandshakeServerError (HandshakeProtocolError _)) =
     HandshakeFailure
 -- any other exception, e.g. MuxError \/ IOError, codec errors, etc.
-classifyHandleError (HandleError _) =
+classifyHandlerError (HandlerError _) =
     HandshakeProtocolViolation
 
 
@@ -208,7 +206,7 @@ type MuxConnectionHandler muxMode socket initiatorCtx responderCtx peerAddr vers
                       socket
                       peerAddr
                       (Handle muxMode initiatorCtx responderCtx versionData bytes m a b)
-                      (HandleError versionNumber)
+                      (HandlerError versionNumber)
                       versionNumber
                       versionData
                       m
@@ -218,15 +216,15 @@ type MuxConnectionHandler muxMode socket initiatorCtx responderCtx peerAddr vers
 type MuxConnectionManager muxMode socket initiatorCtx responderCtx peerAddr versionData versionNumber bytes m a b =
     ConnectionManager muxMode socket peerAddr
                       (Handle muxMode initiatorCtx responderCtx versionData bytes m a b)
-                      (HandleError versionNumber)
+                      (HandlerError versionNumber)
                       m
 
 -- | Type alias for 'ConnectionManager' which is using expanded context.
 --
 type ConnectionManagerWithExpandedCtx muxMode socket peerAddr versionData versionNumber bytes m a b =
     ConnectionManager muxMode socket peerAddr
                       (HandleWithExpandedCtx muxMode peerAddr versionData bytes m a b)
-                      (HandleError versionNumber)
+                      (HandlerError versionNumber)
                       m
 
 -- | To be used as `makeConnectionHandler` field of 'ConnectionManagerArguments'.
@@ -311,7 +309,7 @@ makeConnectionHandler muxTracers forkPolicy
                              socket
                              peerAddr
                              (Handle muxMode initiatorCtx responderCtx versionData ByteString m a b)
-                             (HandleError versionNumber)
+                             (HandlerError versionNumber)
                              versionNumber
                              versionData
                              m
@@ -344,7 +342,7 @@ makeConnectionHandler muxTracers forkPolicy
               -- handshake negotiation failures, but not with 'IOException's or
               -- 'MuxError's.
               `catch` \(err :: SomeException) -> do
-                atomically $ writePromise (Left (HandleError err))
+                atomically $ writePromise (Left (HandlerError err))
                 throwIO err
             case hsResult of
               Left !err -> do
@@ -393,7 +391,7 @@ makeConnectionHandler muxTracers forkPolicy
                              socket
                              peerAddr
                              (Handle muxMode initiatorCtx responderCtx versionData ByteString m a b)
-                             (HandleError versionNumber)
+                             (HandlerError versionNumber)
                              versionNumber
                              versionData
                              m
@@ -426,7 +424,7 @@ makeConnectionHandler muxTracers forkPolicy
               -- handshake negotiation failures, but not with 'IOException's or
               -- 'MuxError's.
               `catch` \(err :: SomeException) -> do
-                atomically $ writePromise (Left (HandleError err))
+                atomically $ writePromise (Left (HandlerError err))
                 throwIO err
 
             case hsResult of

ouroboros-network-framework/src/Ouroboros/Network/ConnectionManager/Core.hs

@@ -155,7 +155,7 @@ data Arguments handlerTrace socket peerAddr handle handleError versionNumber ver
         --
         connStateIdSupply   :: ConnStateIdSupply m,
 
-        classifyHandleError :: handleError -> HandleErrorType
+        classifyHandlerError :: handleError -> HandlerErrorType
       }
 
 
@@ -404,7 +404,7 @@ with args@Arguments {
          connectionsLimits,
          updateVersionData,
          connStateIdSupply,
-         classifyHandleError
+         classifyHandlerError
        }
      inboundGovernorInfoChannel
      ConnectionHandler {
@@ -1079,7 +1079,7 @@ with args@Arguments {
           connState <- readTVar connVar
 
           let connState' =
-                case classifyHandleError <$> connectionError of
+                case classifyHandlerError <$> connectionError of
                   ConnectionHandlerError HandshakeFailure ->
                     TerminatingState connId connThread
                                      (case connectionError of
@@ -1815,7 +1815,7 @@ with args@Arguments {
           connState <- readTVar connVar
 
           let connState' =
-                case classifyHandleError <$> connectionError of
+                case classifyHandlerError <$> connectionError of
                   ConnectionHandlerError HandshakeFailure ->
                     TerminatingState connId connThread
                                      (case connectionError of

ouroboros-network-framework/src/Ouroboros/Network/ConnectionManager/Types.hs

@@ -100,7 +100,7 @@ module Ouroboros.Network.ConnectionManager.Types
   , ConnectionHandler (..)
   , Inactive (..)
   , ExceptionInHandler (..)
-  , HandleErrorType (..)
+  , HandlerErrorType (..)
   , HandshakeConnectionResult (..)
     -- ** Prune Policy
   , PrunePolicy
@@ -413,7 +413,7 @@ instance Exception ExceptionInHandler
 
 -- | Data type used to classify 'handleErrors'.
 --
-data HandleErrorType =
+data HandlerErrorType =
     -- | Handshake negotiation failed.  This is not a protocol error.
     HandshakeFailure
 

ouroboros-network-framework/testlib/Test/Ouroboros/Network/ConnectionManager/Experiments.hs

@@ -326,7 +326,7 @@ withInitiatorOnlyConnectionManager name timeouts trTracer tracer stdGen snocket
     connectionsLimits = acceptedConnLimit,
     updateVersionData = \a _ -> a,
     connStateIdSupply,
-    classifyHandleError = \_ -> HandshakeFailure
+    classifyHandlerError = \_ -> HandshakeFailure
     }
     NotInResponderMode
     mkConnectionHandler
@@ -527,7 +527,7 @@ withBidirectionalConnectionManager name timeouts
                                                     InitiatorAndResponderDiffusionMode -> Duplex
                                               },
             connStateIdSupply,
-            classifyHandleError = (\_ -> HandshakeFailure)
+            classifyHandlerError = (\_ -> HandshakeFailure)
             }
             (InResponderMode inbgovInfoChannel)
             connectionHandler

ouroboros-network/src/Ouroboros/Network/Diffusion.hs

@@ -345,10 +345,10 @@ runM Interfaces
               :: InformationChannel
                    (IG.Event 'ResponderMode handle initiatorCtx ntcAddr versionData m c b) m
               -> ConnectionHandler 'ResponderMode (ConnectionHandlerTrace ntcVersion ntcVersionData)
-                                   ntcFd ntcAddr handle (HandleError versionNumber) version
+                                   ntcFd ntcAddr handle (HandlerError versionNumber) version
                                    versionData m
               -> (   ConnectionManager 'ResponderMode ntcFd ntcAddr handle
-                                       (HandleError versionNumber) m
+                                       (HandlerError versionNumber) m
                   -> m x)
               -> m x
             localWithConnectionManager responderInfoChannel connectionHandler k =
@@ -370,7 +370,7 @@ runM Interfaces
                   CM.connectionsLimits   = localConnectionLimits,
                   CM.updateVersionData   = \a _ -> a,
                   CM.connStateIdSupply   = diConnStateIdSupply,
-                  CM.classifyHandleError
+                  CM.classifyHandlerError
               }
               (InResponderMode responderInfoChannel)
               connectionHandler
@@ -472,7 +472,7 @@ runM Interfaces
             -> StdGen
             -> CM.Arguments
                  (ConnectionHandlerTrace ntnVersion ntnVersionData)
-                 ntnFd ntnAddr handle (HandleError ntnVersion) ntnVersion ntnVersionData m a b
+                 ntnFd ntnAddr handle (HandlerError ntnVersion) ntnVersion ntnVersionData m a b
           connectionManagerArguments' prunePolicy stdGen =
             CM.Arguments {
               CM.tracer              = dtConnectionManagerTracer,
@@ -494,7 +494,7 @@ runM Interfaces
               CM.outboundIdleTimeout = dcProtocolIdleTimeout,
               CM.updateVersionData   = daUpdateVersionData,
               CM.connStateIdSupply   = diConnStateIdSupply,
-              CM.classifyHandleError
+              CM.classifyHandlerError
             }
 
       let makeConnectionHandler'

ouroboros-network/src/Ouroboros/Network/Diffusion/Types.hs

@@ -21,6 +21,7 @@ module Ouroboros.Network.Diffusion.Types
     -- * NodeToClient type aliases
   , NodeToClientHandle
   , NodeToClientHandleError
+  , NodeToClientHandlerError
   , MkNodeToClientConnectionHandler
     -- * NodeToNode type aliases
   , NodeToNodeHandle
@@ -610,7 +611,11 @@ type NodeToClientHandle ntcAddr versionData m =
     HandleWithMinimalCtx Mx.ResponderMode ntcAddr versionData ByteString m Void ()
 
 type NodeToClientHandleError ntcVersion =
-    HandleError ntcVersion
+    HandlerError ntcVersion
+{-# DEPRECATED NodeToClientHandleError "Use NodeToClientHandlerError" #-}
+
+type NodeToClientHandlerError ntcVersion =
+    HandlerError ntcVersion
 
 type MkNodeToClientConnectionHandler
       ntcFd ntcAddr ntcVersion ntcVersionData m =
@@ -622,7 +627,7 @@ type MkNodeToClientConnectionHandler
          ntcFd
          ntcAddr
          (NodeToClientHandle ntcAddr ntcVersionData m)
-         (NodeToClientHandleError ntcVersion)
+         (NodeToClientHandlerError ntcVersion)
          ntcVersion
          ntcVersionData
          m
@@ -646,7 +651,7 @@ type NodeToNodeConnectionManager
       ntnFd
       ntnAddr
       (NodeToNodeHandle mode ntnAddr ntnVersionData m a b)
-      (HandleError ntnVersion)
+      (HandlerError ntnVersion)
       m
 
 --

ouroboros-network/src/Ouroboros/Network/PeerSelection/PeerStateActions.hs

@@ -66,7 +66,7 @@ import Ouroboros.Network.PeerSelection.Governor.Types (PeerStateActions (..))
 import Ouroboros.Network.Protocol.Handshake (HandshakeException)
 import Ouroboros.Network.RethrowPolicy
 
-import Ouroboros.Network.ConnectionHandler (Handle (..), HandleError (..),
+import Ouroboros.Network.ConnectionHandler (Handle (..), HandlerError (..),
            MuxConnectionManager)
 import Ouroboros.Network.ConnectionManager.Types
 import Ouroboros.Network.PeerSelection.PeerSharing (PeerSharing)
@@ -852,7 +852,7 @@ withPeerStateActions PeerStateActionsArguments {
                                             (HandshakeServerFailure err))
                       throwIO (ServerException err)
 
-                    HandleError err -> do
+                    HandlerError err -> do
                       traceWith spsTracer (PeerStatusChangeFailure
                                             (ColdToWarm Nothing remotePeerAddr )
                                             (HandleFailure err))