Remove Exception instance for TLSError, bump to 1.8.0

core/Network/TLS.hs

@@ -31,6 +31,9 @@ module Network.TLS
     , recvData
     , bye
 
+    -- * Exceptions
+    -- $exceptions
+
     -- * Backend abstraction
     , HasBackend(..)
     , Backend(..)
@@ -198,3 +201,10 @@ type Bytes = B.ByteString
 --   both cases of full-negotiation and resumption.
 getClientCertificateChain :: Context -> IO (Maybe CertificateChain)
 getClientCertificateChain ctx = usingState_ ctx S.getClientCertificateChain
+
+{- $exceptions
+    Since 1.8.0, this library only throws exceptions of type 'TLSException'.
+    In the common case where the chosen backend is socket, 'IOException'
+    may be thrown as well. This happens because the backend for sockets,
+    opaque to most modules in the @tls@ library, throws those exceptions.
+-}

core/Network/TLS/Context/Internal.hs

@@ -234,7 +234,7 @@ withLog :: Context -> (Logging -> IO ()) -> IO ()
 withLog ctx f = ctxWithHooks ctx (f . hookLogging)
 
 throwCore :: MonadIO m => TLSError -> m a
-throwCore = liftIO . throwIO
+throwCore = liftIO . throwIO . Uncontextualized
 
 failOnEitherError :: MonadIO m => m (Either TLSError a) -> m a
 failOnEitherError f = do
@@ -255,7 +255,7 @@ usingState_ ctx f = failOnEitherError $ usingState ctx f
 usingHState :: MonadIO m => Context -> HandshakeM a -> m a
 usingHState ctx f = liftIO $ modifyMVar (ctxHandshake ctx) $ \mst ->
     case mst of
-        Nothing -> throwCore $ Error_Misc "missing handshake"
+        Nothing -> liftIO $ throwIO $ MissingHandshake
         Just st -> return $ swap (Just <$> runHandshake st f)
 
 getHState :: MonadIO m => Context -> m (Maybe HandshakeState)

core/Network/TLS/Handshake/Common.hs

@@ -58,7 +58,12 @@ handshakeFailed err = throwIO $ HandshakeFailed err
 
 handleException :: Context -> IO () -> IO ()
 handleException ctx f = catchException f $ \exception -> do
-    let tlserror = fromMaybe (Error_Misc $ show exception) $ fromException exception
+    -- If the error was an Uncontextualized TLSException, we replace the
+    -- context with HandshakeFailed. If it's anything else, we convert
+    -- it to a string and wrap it with Error_Misc and HandshakeFailed.
+    let tlserror = case fromException exception of
+          Just e | Uncontextualized e' <- e -> e'
+          _ -> Error_Misc (show exception)
     setEstablished ctx NotEstablished
     handle ignoreIOErr $ do
         tls13 <- tls13orLater ctx

core/Network/TLS/IO.hs

@@ -26,7 +26,6 @@ import Control.Monad.Reader
 import Control.Monad.State.Strict
 import qualified Data.ByteString as B
 import Data.IORef
-import System.IO.Error (mkIOError, eofErrorType)
 
 import Network.TLS.Context.Internal
 import Network.TLS.Hooks
@@ -172,7 +171,7 @@ checkValid ctx = do
     established <- ctxEstablished ctx
     when (established == NotEstablished) $ throwIO ConnectionNotEstablished
     eofed <- ctxEOF ctx
-    when eofed $ throwIO $ mkIOError eofErrorType "data" Nothing Nothing
+    when eofed $ throwIO $ PostHandshake Error_EOF
 
 ----------------------------------------------------------------
 

core/Network/TLS/Struct.hs

@@ -156,7 +156,11 @@ data ProtocolType =
     | ProtocolType_DeprecatedHandshake
     deriving (Eq, Show)
 
--- | TLSError that might be returned through the TLS stack
+-- | TLSError that might be returned through the TLS stack.
+--
+-- Prior to version 1.8.0, this type had an @Exception@ instance.
+-- In version 1.8.0, this instance was removed, and functions in
+-- this library now only throw 'TLSException'.
 data TLSError =
       Error_Misc String        -- ^ mainly for instance of Error
     | Error_Protocol (String, Bool, AlertDescription)
@@ -168,16 +172,29 @@ data TLSError =
     | Error_Packet_Parsing String
     deriving (Eq, Show, Typeable)
 
-instance Exception TLSError
-
--- | TLS Exceptions related to bad user usage or
--- asynchronous errors
+-- | TLS Exceptions. Some of the data constructors indicate incorrect use of
+--   the library, and the documentation for those data constructors calls
+--   this out. The others wrap 'TLSError' with some kind of context to explain
+--   when the exception occurred.
 data TLSException =
-      Terminated Bool String TLSError -- ^ Early termination exception with the reason
-                                      --   and the error associated
-    | HandshakeFailed TLSError        -- ^ Handshake failed for the reason attached
-    | ConnectionNotEstablished        -- ^ Usage error when the connection has not been established
-                                      --   and the user is trying to send or receive data
+      Terminated Bool String TLSError
+      -- ^ Early termination exception with the reason and the error associated
+    | HandshakeFailed TLSError
+      -- ^ Handshake failed for the reason attached.
+    | PostHandshake TLSError
+      -- ^ Failure occurred while sending or receiving data after the
+      --   TLS handshake succeeded.
+    | Uncontextualized TLSError
+      -- ^ Lifts a 'TLSError' into 'TLSException' without provided any context
+      --   around when the error happened.
+    | ConnectionNotEstablished
+      -- ^ Usage error when the connection has not been established
+      --   and the user is trying to send or receive data.
+      --   Indicates that this library has been used incorrectly. 
+    | MissingHandshake
+      -- ^ Expected that a TLS handshake had already taken place, but no TLS
+      --   handshake had occurred.
+      --   Indicates that this library has been used incorrectly. 
     deriving (Show,Eq,Typeable)
 
 instance Exception TLSException

core/tls.cabal

@@ -1,6 +1,6 @@
 cabal-version:      >=1.10
 name:               tls
-version:            1.7.0
+version:            1.8.0
 license:            BSD3
 license-file:       LICENSE
 copyright:          Vincent Hanquez <vincent@snarc.org>