packages feed

memcache-0.5.0.0: Database/Memcache/Errors.hs

{-|
Module      : Database.Memcache.Errors
Description : Errors Handling
Copyright   : (c) David Terei, 2016
License     : BSD
Maintainer  : code@davidterei.com
Stability   : stable
Portability : GHC

Memcached related errors and exception handling.
-}
module Database.Memcache.Errors (
        -- * Error types
        MemcacheError(..),
        Status(..),
        ClientError(..),
        ProtocolError(..),

        -- * Error creation
        throwStatus
    ) where

import           Database.Memcache.Types
import           Database.Memcache.Util (withDetail)

import           UnliftIO.Exception

-- | All exceptions that a Memcached client may throw.
--
-- 'displayException' gives a one-line message for logs and users, such as
-- @memcached operation failed: key not found@. Any detail, such as text the
-- server sent, is cut to its first 200 characters and has characters outside
-- printable ASCII escaped. 'show' gives the derived form.
data MemcacheError
    -- | Memcached operation error.
    = OpError Status
    -- | Error occurring on client side.
    | ClientError ClientError
    -- | Errors occurring communicating with Memcached server.
    | ProtocolError ProtocolError
    deriving (Eq, Show)

instance Exception MemcacheError where
    displayException (OpError s) =
        "memcached operation failed: " <> describeStatus s
    displayException (ClientError e) =
        "memcache client error: " <> describeClientError e
    displayException (ProtocolError e) =
        "memcached protocol error: " <> describeProtocolError e

-- | Errors that occur on the client.
data ClientError
    -- | No server is available: the cluster has none, every server is marked
    -- failed, or the router ('Database.Memcache.Cluster.optsGetServerForKey')
    -- chose none.
    = NoServersReady
    -- | The attempt that ended an operation ran out of time
    -- ('Database.Memcache.Cluster.optsServerTimeout'): the last attempt, or,
    -- for a request that mustn't be sent twice, the attempt that had started
    -- sending it. The attempt may have been waiting for a free connection to
    -- the server, connecting, authenticating, checking the server's version,
    -- sending a request or reading a reply; the error doesn't say which. An
    -- attempt that only waited for its first connection sent nothing, but for
    -- an operation that is retried after any failure, an earlier attempt may
    -- have sent the request. The server may have carried out any request that
    -- was sent. ElastiCache's 'Database.Memcache.ElastiCacheClient.newClient'
    -- also throws it when its first discovery takes longer than the timeout.
    | Timeout
    -- | Credentials were rejected before being sent: they contain a
    -- forbidden delimiter, or the server is not in auth-file mode.
    | InvalidAuthentication String
    -- | A key or stats argument was rejected before being sent: it is empty,
    -- too long, or contains forbidden bytes.
    | KeyTooLong String
    deriving (Eq, Show)

-- | Errors related to Memcached protocol and bytes on the wire.
data ProtocolError
    -- | Received an unknown response line.
    = UnknownPkt    { protocolError :: String }
    -- | Unknown Memcached operation. Also thrown when a new connection asks
    -- the server for its version and the reply is a version below 1.6.10, or
    -- any other reply that is neither an error nor a readable version; the
    -- message quotes the reply. The connection is then closed, having sent
    -- only the authentication exchange, when credentials are set, and
    -- @version@.
    | UnknownOp     { protocolError :: String }
    -- | Unknown Memcached status field value.
    | UnknownStatus { protocolError :: String }
    -- | Unexpected length of a Meta Text value or other field.
    | BadLength     { protocolError :: String }
    -- | Response is for a different operation than expected.
    | UnexpectedResponse { protocolError :: String }
    -- | Memcached reported a server failure.
    | ServerError   { protocolError :: String }
    -- | Memcached rejected the command.
    | BadCommand    { protocolError :: String }
    -- | Network socket closed without receiving enough bytes.
    | UnexpectedEOF { protocolError :: String }
    deriving (Eq, Show)

-- | Convert a status to 'MemcacheError' exception.
throwStatus :: Status -> IO a
throwStatus s = throwIO $ OpError s

describeStatus :: Status -> String
describeStatus s = case s of
    NoError            -> "no error"
    ErrKeyNotFound     -> "key not found"
    ErrKeyExists       -> "key already exists"
    ErrValueTooLarge   -> "value too large"
    ErrItemNotStored   -> "item not stored"
    ErrValueNonNumeric -> "value is not numeric"
    ErrOutOfMemory     -> "server out of memory"
    TextAuthFail       -> "authentication failed"

describeClientError :: ClientError -> String
describeClientError e = case e of
    NoServersReady          -> "no servers ready"
    Timeout                 -> "request timed out"
    InvalidAuthentication m -> "invalid authentication" `withDetail` m
    KeyTooLong m            -> "invalid key or argument" `withDetail` m

-- The library throws 'UnknownPkt' with no detail for an empty response line.
describeProtocolError :: ProtocolError -> String
describeProtocolError e = problem `withDetail` protocolError e
  where
    problem = case e of
        UnknownPkt ""        -> "empty response line"
        UnknownPkt _         -> "unrecognized response line"
        UnknownOp _          -> "command not recognized by server"
        UnknownStatus _      -> "unknown response code"
        BadLength _          -> "malformed response"
        UnexpectedResponse _ -> "unexpected response"
        ServerError _        -> "server error"
        BadCommand _         -> "command rejected by server"
        UnexpectedEOF _      -> "connection closed by server"