-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | A memcached client library.
--   
--   A client library for a Memcached cluster. Memcached is an in-memory
--   key-value store typically used as a distributed and shared cache.
--   Clients connect to a group of Memcached servers and perform
--   out-of-band caching for things like SQL results, rendered pages, or
--   third-party APIs.
--   
--   It supports the binary Memcached protocol and SASL authentication. No
--   support for the ASCII protocol is provided. It supports connecting to
--   a single, or a cluster of Memcached servers. When connecting to a
--   cluser, consistent hashing is used for routing requests to the
--   appropriate server. Timeouts, retrying failed operations, and failover
--   to a different server are all supported.
--   
--   Complete coverage of the Memcached protocol is provided except for
--   multi-get and other pipelined operations.
--   
--   Basic usage is:
--   
--   <pre>
--   import qualified Database.Memcache.Client as M
--   
--   mc &lt;- M.newClient [M.ServerSpec "localhost" "11211" M.NoAuth] M.def
--   M.set mc "key" "value" 0 0
--   v &lt;- M.get mc "key"
--   </pre>
--   
--   You should only need to import <a>Database.Memcache.Client</a>, but
--   for now other modules are exposed.
@package memcache
@version 0.3.0.2


-- | Stores the various types needed by Memcached. Mostly concerned with
--   the representation of the protocol.
module Database.Memcache.Types

-- | SASL Authentication information for a server.
data Authentication
Auth :: !Username -> !Password -> Authentication
[username] :: Authentication -> !Username
[password] :: Authentication -> !Password
NoAuth :: Authentication

-- | Username for authentication.
type Username = ByteString

-- | Password for authentication.
type Password = ByteString
data Q
Loud :: Q
Quiet :: Q
data K
NoKey :: K
IncludeKey :: K
type Key = ByteString
type Value = ByteString
type Extras = ByteString
type Initial = Word64
type Delta = Word64
type Expiration = Word32
type Flags = Word32
type Version = Word64

-- | The status (success or error) of a Memcached operation returned in a
--   <a>Response</a>.
data Status

-- | Operation successful.
NoError :: Status

-- | Key not found.
ErrKeyNotFound :: Status

-- | Key exists when not expected.
ErrKeyExists :: Status

-- | Value too large to store at server.
ErrValueTooLarge :: Status

-- | Invalid arguments for operation.
ErrInvalidArgs :: Status

-- | Key-Value pair not stored at server (internal error).
ErrItemNotStored :: Status

-- | Value not numeric when increment or decrement requested.
ErrValueNonNumeric :: Status

-- | Server doesn't know requested command.
ErrUnknownCommand :: Status

-- | Server out of memory.
ErrOutOfMemory :: Status

-- | SASL authentication failed.
SaslAuthFail :: Status

-- | SASL authentication requires more steps.
SaslAuthContinue :: Status

-- | Memcached packet header (for both <a>Request</a> and <a>Response</a>).
data Header
Header :: Word8 -> Word16 -> Word8 -> Status -> Word32 -> Word32 -> Version -> Header
[op] :: Header -> Word8
[keyLen] :: Header -> Word16
[extraLen] :: Header -> Word8
[status] :: Header -> Status
[bodyLen] :: Header -> Word32
[opaque] :: Header -> Word32
[cas] :: Header -> Version
mEMCACHE_HEADER_SIZE :: Int
data PktType
PktRequest :: PktType
PktResponse :: PktType
data Request
Req :: OpRequest -> Word32 -> Version -> Request
[reqOp] :: Request -> OpRequest
[reqOpaque] :: Request -> Word32
[reqCas] :: Request -> Version
data OpRequest
ReqGet :: Q -> K -> Key -> OpRequest
ReqSet :: Q -> Key -> Value -> SESet -> OpRequest
ReqAdd :: Q -> Key -> Value -> SESet -> OpRequest
ReqReplace :: Q -> Key -> Value -> SESet -> OpRequest
ReqDelete :: Q -> Key -> OpRequest
ReqIncrement :: Q -> Key -> SEIncr -> OpRequest
ReqDecrement :: Q -> Key -> SEIncr -> OpRequest
ReqAppend :: Q -> Key -> Value -> OpRequest
ReqPrepend :: Q -> Key -> Value -> OpRequest
ReqTouch :: Key -> SETouch -> OpRequest
ReqGAT :: Q -> K -> Key -> SETouch -> OpRequest
ReqFlush :: Q -> Maybe SETouch -> OpRequest
ReqNoop :: OpRequest
ReqVersion :: OpRequest
ReqStat :: Maybe Key -> OpRequest
ReqQuit :: Q -> OpRequest
ReqSASLList :: OpRequest
ReqSASLStart :: Key -> Value -> OpRequest
ReqSASLStep :: Key -> Value -> OpRequest

-- | Raw request is custom requests, dangerous as no corresponding raw
--   response...

-- | <i>Warning: This is dangerous; no future compatability guaranteed</i>
ReqRaw :: Word8 -> Maybe Key -> Maybe Value -> SERaw -> OpRequest
data SESet
SESet :: Flags -> Expiration -> SESet
data SEIncr
SEIncr :: Initial -> Delta -> Expiration -> SEIncr
data SETouch
SETouch :: Expiration -> SETouch
data SERaw
SERaw :: Builder -> Int -> SERaw

-- | Noop request.
emptyReq :: Request

-- | Memcached response packet.
data Response
Res :: OpResponse -> Status -> Word32 -> Version -> Response
[resOp] :: Response -> OpResponse
[resStatus] :: Response -> Status
[resOpaque] :: Response -> Word32
[resCas] :: Response -> Version
data OpResponse
ResGet :: Q -> Value -> Flags -> OpResponse
ResGetK :: Q -> Key -> Value -> Flags -> OpResponse
ResSet :: Q -> OpResponse
ResAdd :: Q -> OpResponse
ResReplace :: Q -> OpResponse
ResDelete :: Q -> OpResponse
ResIncrement :: Q -> Word64 -> OpResponse
ResDecrement :: Q -> Word64 -> OpResponse
ResAppend :: Q -> OpResponse
ResPrepend :: Q -> OpResponse
ResTouch :: OpResponse
ResGAT :: Q -> Value -> Flags -> OpResponse
ResGATK :: Q -> Key -> Value -> Flags -> OpResponse
ResFlush :: Q -> OpResponse
ResNoop :: OpResponse
ResVersion :: Value -> OpResponse
ResStat :: Key -> Value -> OpResponse
ResQuit :: Q -> OpResponse
ResSASLList :: Value -> OpResponse
ResSASLStart :: OpResponse
ResSASLStep :: OpResponse

-- | Noop response.
emptyRes :: Response
instance GHC.Show.Show Database.Memcache.Types.Authentication
instance GHC.Classes.Eq Database.Memcache.Types.Authentication
instance GHC.Show.Show Database.Memcache.Types.PktType
instance GHC.Classes.Eq Database.Memcache.Types.PktType
instance GHC.Show.Show Database.Memcache.Types.Q
instance GHC.Classes.Eq Database.Memcache.Types.Q
instance GHC.Show.Show Database.Memcache.Types.K
instance GHC.Classes.Eq Database.Memcache.Types.K
instance GHC.Show.Show Database.Memcache.Types.SESet
instance GHC.Classes.Eq Database.Memcache.Types.SESet
instance GHC.Show.Show Database.Memcache.Types.SEIncr
instance GHC.Classes.Eq Database.Memcache.Types.SEIncr
instance GHC.Show.Show Database.Memcache.Types.SETouch
instance GHC.Classes.Eq Database.Memcache.Types.SETouch
instance GHC.Show.Show Database.Memcache.Types.OpRequest
instance GHC.Classes.Eq Database.Memcache.Types.OpRequest
instance GHC.Show.Show Database.Memcache.Types.Request
instance GHC.Classes.Eq Database.Memcache.Types.Request
instance GHC.Show.Show Database.Memcache.Types.OpResponse
instance GHC.Classes.Eq Database.Memcache.Types.OpResponse
instance GHC.Show.Show Database.Memcache.Types.Status
instance GHC.Classes.Eq Database.Memcache.Types.Status
instance GHC.Show.Show Database.Memcache.Types.Header
instance GHC.Classes.Eq Database.Memcache.Types.Header
instance GHC.Show.Show Database.Memcache.Types.Response
instance GHC.Classes.Eq Database.Memcache.Types.Response
instance GHC.Show.Show Database.Memcache.Types.SERaw
instance GHC.Classes.Eq Database.Memcache.Types.SERaw


-- | Memcached related errors and exception handling.
module Database.Memcache.Errors

-- | All exceptions that a Memcached client may throw.
data MemcacheError

-- | Memcached operation error.
OpError :: Status -> MemcacheError

-- | Error occuring on client side.
ClientError :: ClientError -> MemcacheError

-- | Errors occurring communicating with Memcached server.
ProtocolError :: ProtocolError -> MemcacheError

-- | The status (success or error) of a Memcached operation returned in a
--   <a>Response</a>.
data Status

-- | Operation successful.
NoError :: Status

-- | Key not found.
ErrKeyNotFound :: Status

-- | Key exists when not expected.
ErrKeyExists :: Status

-- | Value too large to store at server.
ErrValueTooLarge :: Status

-- | Invalid arguments for operation.
ErrInvalidArgs :: Status

-- | Key-Value pair not stored at server (internal error).
ErrItemNotStored :: Status

-- | Value not numeric when increment or decrement requested.
ErrValueNonNumeric :: Status

-- | Server doesn't know requested command.
ErrUnknownCommand :: Status

-- | Server out of memory.
ErrOutOfMemory :: Status

-- | SASL authentication failed.
SaslAuthFail :: Status

-- | SASL authentication requires more steps.
SaslAuthContinue :: Status

-- | Errors that occur on the client.
data ClientError

-- | All servers are currently marked failed.
NoServersReady :: ClientError

-- | Timeout occurred sending request to server.
Timeout :: ClientError

-- | Errors related to Memcached protocol and bytes on the wire.
data ProtocolError

-- | Received an unknown response packet.
UnknownPkt :: String -> ProtocolError
[protocolError] :: ProtocolError -> String

-- | Unknown Memcached operation.
UnknownOp :: String -> ProtocolError
[protocolError] :: ProtocolError -> String

-- | Unknown Memcached status field value.
UnknownStatus :: String -> ProtocolError
[protocolError] :: ProtocolError -> String

-- | Unexpected length of a Memcached field (extras, key, or value).
BadLength :: String -> ProtocolError
[protocolError] :: ProtocolError -> String

-- | Response packet is for a different operation than expected.
WrongOp :: String -> ProtocolError
[protocolError] :: ProtocolError -> String

-- | Network socket closed without receiving enough bytes.
UnexpectedEOF :: String -> ProtocolError
[protocolError] :: ProtocolError -> String

-- | Convert a status to <a>MemcacheError</a> exception.
throwStatus :: Status -> IO a

-- | Create a properly formatted <a>WrongOp</a> protocol error.
wrongOp :: Response -> String -> MemcacheError
instance GHC.Show.Show Database.Memcache.Errors.ClientError
instance GHC.Classes.Eq Database.Memcache.Errors.ClientError
instance GHC.Show.Show Database.Memcache.Errors.ProtocolError
instance GHC.Classes.Eq Database.Memcache.Errors.ProtocolError
instance GHC.Show.Show Database.Memcache.Errors.MemcacheError
instance GHC.Classes.Eq Database.Memcache.Errors.MemcacheError
instance GHC.Exception.Type.Exception Database.Memcache.Errors.MemcacheError


-- | Handles a single Memcached connection, sending and receiving requests.
module Database.Memcache.Socket

-- | Basic type for a socket.
data () => Socket
data Request
Req :: OpRequest -> Word32 -> Version -> Request
[reqOp] :: Request -> OpRequest
[reqOpaque] :: Request -> Word32
[reqCas] :: Request -> Version

-- | Memcached response packet.
data Response
Res :: OpResponse -> Status -> Word32 -> Version -> Response
[resOp] :: Response -> OpResponse
[resStatus] :: Response -> Status
[resOpaque] :: Response -> Word32
[resCas] :: Response -> Version

-- | Send a request to the Memcached server.
send :: Socket -> Request -> IO ()

-- | Retrieve a single response from the Memcached server. FIXME: read into
--   buffer to minimize read syscalls
recv :: Socket -> IO Response

-- | Serialize a request to a ByteString Builder.
szRequest :: Request -> Builder

-- | Serialize a response to a ByteString Builder.
szResponse :: Response -> Builder

-- | Deserialize a Header from a ByteString.
dzHeader :: PktType -> Get Header

-- | Deserialize a Response body.
dzResponse :: Header -> ByteString -> Response


-- | SASL authentication support for Memcached.
module Database.Memcache.SASL

-- | SASL Authentication information for a server.
data Authentication
Auth :: !Username -> !Password -> Authentication
[username] :: Authentication -> !Username
[password] :: Authentication -> !Password
NoAuth :: Authentication

-- | Username for authentication.
type Username = ByteString

-- | Password for authentication.
type Password = ByteString

-- | Perform SASL authentication with the server.
authenticate :: Socket -> Authentication -> IO ()


-- | Handles the connections between a Memcached client and a single
--   server.
--   
--   Memcached expected errors (part of protocol) are returned in the
--   Response, unexpected errors (e.g., network failure) are thrown as
--   exceptions. While the Server datatype supports a <a>failed</a> and
--   <tt>failedAt</tt> flag for managing retries, it's up to consumers to
--   use this.
module Database.Memcache.Server

-- | Memcached server connection.
data Server

-- | Create a new Memcached server connection.
newServer :: HostName -> ServiceName -> Authentication -> IO Server

-- | Send and receive a single request/response pair to the Memcached
--   server.
sendRecv :: Server -> Request -> IO Response

-- | Run a function with access to an server socket for using <a>send</a>
--   and <a>recv</a>.
withSocket :: Server -> (Socket -> IO a) -> IO a

-- | Close the server connection. If you perform another operation after
--   this, the connection will be re-established.
close :: Server -> IO ()
instance GHC.Show.Show Database.Memcache.Server.Server
instance GHC.Classes.Eq Database.Memcache.Server.Server
instance GHC.Classes.Ord Database.Memcache.Server.Server


-- | Handles a group of connections to different Memcached servers.
--   
--   We use consistent hashing to choose which server to route a request
--   to. On an error, we mark the server as failed and remove it
--   temporarialy from the set of servers available.
module Database.Memcache.Cluster

-- | Memcached cluster.
data Cluster

-- | ServerSpec specifies a server configuration for connection.
data ServerSpec
ServerSpec :: HostName -> ServiceName -> Authentication -> ServerSpec

-- | Hostname of server to connect to.
[ssHost] :: ServerSpec -> HostName

-- | Port number server is running on.
[ssPort] :: ServerSpec -> ServiceName

-- | Authentication values to use for SASL authentication with this server.
[ssAuth] :: ServerSpec -> Authentication

-- | Options specifies how a Memcached cluster should be configured.
data Options
Options :: Retries -> Milli -> Milli -> Milli -> (Cluster -> Key -> IO (Maybe Server)) -> Options

-- | Number of times to retry an operation on failure. If consecutive
--   failures exceed this value for a server, we mark it as down and
--   failover to a different server for the next operation.
--   
--   Default is 2.
[optsServerRetries] :: Options -> Retries

-- | After an operation has failed, how long to wait before retrying it
--   while still within the <a>optsServerRetries</a> count?
--   
--   Default is 200ms.
[optsFailRetryDelay] :: Options -> Milli

-- | How long to wait after a server has been marked down, before trying to
--   use it again.
--   
--   Default is 1500ms.
[optsDeadRetryDelay] :: Options -> Milli

-- | How long to wait for an operation to complete before considering it
--   failed.
--   
--   Default is 750ms.
[optsServerTimeout] :: Options -> Milli

-- | Figure out which server to talk to for a given key.
--   
--   Default is <a>getServerForKeyDefault</a>.
[optsGetServerForKey] :: Options -> Cluster -> Key -> IO (Maybe Server)

-- | Establish a new connection to a group of Memcached servers.
newCluster :: [ServerSpec] -> Options -> IO Cluster

-- | Number of times to retry an operation before considering it failed.
type Retries = Int

-- | Run a Memcached operation against a particular server, handling any
--   failures that occur, retrying the specified number of times.
keyedOp :: Cluster -> Key -> Request -> IO Response

-- | Run a Memcached operation against any single server in the cluster,
--   handling any failures that occur, retrying the specified number of
--   times.
anyOp :: Cluster -> Request -> IO Response

-- | Run a Memcached operation against all servers in the cluster, handling
--   any failures that occur, retrying the specified number of times.
allOp :: Cluster -> Request -> IO [(Server, Response)]

-- | Run a Memcached operation against all servers in the cluster, handling
--   any failures that occur, retrying the specified number of times.
--   Similar to <a>anyOp</a> but allows more flexible interaction with the
--   <a>Server</a> than a single request and response.
allOp' :: Cluster -> (Server -> IO a) -> IO [(Server, a)]
instance GHC.Show.Show Database.Memcache.Cluster.ServerSpec
instance GHC.Classes.Eq Database.Memcache.Cluster.ServerSpec
instance Data.Default.Class.Default Database.Memcache.Cluster.Options
instance Data.Default.Class.Default Database.Memcache.Cluster.ServerSpec


-- | A Memcached client. Memcached is an in-memory key-value store
--   typically used as a distributed and shared cache. Clients connect to a
--   group of Memcached servers and perform out-of-band caching for things
--   like SQL results, rendered pages, or third-party APIs.
--   
--   A client can connect to a single Memcached server or a cluster of
--   them. In the later case, consistent hashing is used to route requests
--   to the appropriate server. The <i>binary</i> Memcached protocol is
--   used and <i>SASL authentication</i> is supported.
--   
--   Expected return values (like misses) are returned as part of the
--   return type, while unexpected errors are thrown as exceptions.
--   Exceptions are either of type <a>MemcacheError</a> or an <a>IO</a>
--   exception thrown by the network.
--   
--   We support the following logic for handling failure in operations:
--   
--   <ul>
--   <li><b>Timeouts</b>: we timeout any operation that takes too long and
--   consider it failed.</li>
--   <li><b>Retry</b>: on operation failure (timeout, network error) we
--   close the connection and retry the operation, doing this up to a
--   configurable maximum.</li>
--   <li><b>Failover</b>: when an operation against a server in a cluster
--   fails all retries, we mark that server as dead and use the remaining
--   servers in the cluster to handle all operations. After a configurable
--   period of time has passed, we consider the server alive again and try
--   to use it. This can lead to consistency issues (stale data), but is
--   usually fine for caching purposes and is the common approach in
--   Memcached clients.</li>
--   </ul>
--   
--   Some of this behavior can be configured through the <a>Options</a>
--   data type. We also have the following concepts exposed by Memcached:
--   
--   <ul>
--   <li><i><tt>version</tt></i> Each value has a <a>Version</a> associated
--   with it. This is simply a numeric, monotonically increasing value. The
--   version field allows for a primitive version of <a>cas</a> to be
--   implemented.</li>
--   <li><i><tt>expiration</tt></i> Each value pair has an
--   <a>Expiration</a> associated with it. Once a a value expires, it will
--   no longer be returned from the cache until a new value for that key is
--   set. Expirations come in two forms, the first form interprets the
--   expiration value as the number of seconds in the future at which the
--   value should be considered expired. For example, an expiration of
--   <tt>3600</tt> expires the value in 1 hour. When the value of the
--   expiration is greater than 30 days however (<tt>2592000</tt>), the
--   expiration field is instead interpreted as a UNIX timestamp (the
--   number of seconds since epoch). The timestamp specifies the date at
--   which the value should expire.</li>
--   <li><i><tt>flags</tt></i> Each value can have a small amount of fixed
--   metadata associated with it beyond the value itself, these are the
--   <a>Flags</a>.</li>
--   </ul>
--   
--   Usage is roughly as follows:
--   
--   <pre>
--   module Main where
--   
--   import qualified Database.Memcache.Client as M
--   
--   main = do
--       -- use default values: connects to localhost:11211
--       mc &lt;- M.newClient [M.def] M.def
--   
--       -- store and then retrieve a key-value pair
--       M.set mc "key" "value" 0 0
--       v' &lt;- M.get mc "key"
--       case v' of
--           Nothing        -&gt; putStrLn "Miss!"
--           Just (v, _, _) -&gt; putStrLn $ "Hit: " + show v
--   </pre>
module Database.Memcache.Client

-- | Establish a new connection to a group of Memcached servers.
newClient :: [ServerSpec] -> Options -> IO Client

-- | A Memcached client, connected to a collection of Memcached servers.
type Client = Cluster

-- | ServerSpec specifies a server configuration for connection.
data ServerSpec
ServerSpec :: HostName -> ServiceName -> Authentication -> ServerSpec

-- | Hostname of server to connect to.
[ssHost] :: ServerSpec -> HostName

-- | Port number server is running on.
[ssPort] :: ServerSpec -> ServiceName

-- | Authentication values to use for SASL authentication with this server.
[ssAuth] :: ServerSpec -> Authentication

-- | Options specifies how a Memcached cluster should be configured.
data Options
Options :: Retries -> Milli -> Milli -> Milli -> (Cluster -> Key -> IO (Maybe Server)) -> Options

-- | Number of times to retry an operation on failure. If consecutive
--   failures exceed this value for a server, we mark it as down and
--   failover to a different server for the next operation.
--   
--   Default is 2.
[optsServerRetries] :: Options -> Retries

-- | After an operation has failed, how long to wait before retrying it
--   while still within the <a>optsServerRetries</a> count?
--   
--   Default is 200ms.
[optsFailRetryDelay] :: Options -> Milli

-- | How long to wait after a server has been marked down, before trying to
--   use it again.
--   
--   Default is 1500ms.
[optsDeadRetryDelay] :: Options -> Milli

-- | How long to wait for an operation to complete before considering it
--   failed.
--   
--   Default is 750ms.
[optsServerTimeout] :: Options -> Milli

-- | Figure out which server to talk to for a given key.
--   
--   Default is <a>getServerForKeyDefault</a>.
[optsGetServerForKey] :: Options -> Cluster -> Key -> IO (Maybe Server)

-- | SASL Authentication information for a server.
data Authentication
Auth :: !Username -> !Password -> Authentication
[username] :: Authentication -> !Username
[password] :: Authentication -> !Password
NoAuth :: Authentication

-- | Username for authentication.
type Username = ByteString

-- | Password for authentication.
type Password = ByteString

-- | The default value for this type.
def :: Default a => a

-- | Gracefully close a connection to a Memcached cluster.
quit :: Cluster -> IO ()

-- | Retrieve the value for the given key from Memcached.
get :: Cluster -> Key -> IO (Maybe (Value, Flags, Version))

-- | Get-and-touch: Retrieve the value for the given key from Memcached,
--   and also update the stored key-value pairs expiration time at the
--   server. Use an expiration value of <tt>0</tt> to store forever.
gat :: Cluster -> Key -> Expiration -> IO (Maybe (Value, Flags, Version))

-- | Update the expiration time of a stored key-value pair, returning its
--   version identifier. Use an expiration value of <tt>0</tt> to store
--   forever.
touch :: Cluster -> Key -> Expiration -> IO (Maybe Version)

-- | Store a new (or overwrite exisiting) key-value pair, returning its
--   version identifier. Use an expiration value of <tt>0</tt> to store
--   forever.
set :: Cluster -> Key -> Value -> Flags -> Expiration -> IO Version

-- | Store a key-value pair, but only if the version specified by the
--   client matches the Version of the key-value pair at the server. The
--   version identifier of the stored key-value pair is returned, or if the
--   version match fails, <tt>Nothing</tt> is returned. Use an expiration
--   value of <tt>0</tt> to store forever.
cas :: Cluster -> Key -> Value -> Flags -> Expiration -> Version -> IO (Maybe Version)

-- | Store a new key-value pair, returning it's version identifier. If the
--   key-value pair already exists, then fail (return <a>Nothing</a>). Use
--   an expiration value of <tt>0</tt> to store forever.
add :: Cluster -> Key -> Value -> Flags -> Expiration -> IO (Maybe Version)

-- | Update the value of an existing key-value pair, returning it's new
--   version identifier. If the key doesn't already exist, the fail and
--   return Nothing. Use an expiration value of <tt>0</tt> to store
--   forever.
replace :: Cluster -> Key -> Value -> Flags -> Expiration -> Version -> IO (Maybe Version)

-- | Increment a numeric value stored against a key, returning the
--   incremented value and the version identifier of the key-value pair.
--   Use an expiration value of <tt>0</tt> to store forever.
increment :: Cluster -> Key -> Initial -> Delta -> Expiration -> Version -> IO (Maybe (Word64, Version))

-- | Decrement a numeric value stored against a key, returning the
--   decremented value and the version identifier of the key-value pair.
--   Use an expiration value of <tt>0</tt> to store forever.
decrement :: Cluster -> Key -> Initial -> Delta -> Expiration -> Version -> IO (Maybe (Word64, Version))

-- | Append a value to an existing key-value pair, returning the new
--   version identifier of the key-value pair when successful.
append :: Cluster -> Key -> Value -> Version -> IO (Maybe Version)

-- | Prepend a value to an existing key-value pair, returning the new
--   version identifier of the key-value pair when successful.
prepend :: Cluster -> Key -> Value -> Version -> IO (Maybe Version)

-- | Delete a key-value pair at the server, returning true if successful.
delete :: Cluster -> Key -> Version -> IO Bool

-- | Remove (delete) all currently stored key-value pairs from the cluster.
--   The expiration value can be used to cause this flush to occur in the
--   future rather than immediately.
flush :: Cluster -> Maybe Expiration -> IO ()

-- | StatResults are a list of key-value pairs.
type StatResults = [(ByteString, ByteString)]

-- | Return statistics on the stored key-value pairs at each server in the
--   cluster. The optional key can be used to select a different set of
--   statistics from the server than the default. Most Memcached servers
--   support <tt>"items"</tt>, <tt>"slabs"</tt> or <tt>"settings"</tt>.
stats :: Cluster -> Maybe Key -> IO [(Server, Maybe StatResults)]

-- | Version returns the version string of the Memcached cluster. We just
--   query one server and assume all servers in the cluster are the same
--   version.
version :: Cluster -> IO ByteString

-- | All exceptions that a Memcached client may throw.
data MemcacheError

-- | Memcached operation error.
OpError :: Status -> MemcacheError

-- | Error occuring on client side.
ClientError :: ClientError -> MemcacheError

-- | Errors occurring communicating with Memcached server.
ProtocolError :: ProtocolError -> MemcacheError

-- | The status (success or error) of a Memcached operation returned in a
--   <a>Response</a>.
data Status

-- | Operation successful.
NoError :: Status

-- | Key not found.
ErrKeyNotFound :: Status

-- | Key exists when not expected.
ErrKeyExists :: Status

-- | Value too large to store at server.
ErrValueTooLarge :: Status

-- | Invalid arguments for operation.
ErrInvalidArgs :: Status

-- | Key-Value pair not stored at server (internal error).
ErrItemNotStored :: Status

-- | Value not numeric when increment or decrement requested.
ErrValueNonNumeric :: Status

-- | Server doesn't know requested command.
ErrUnknownCommand :: Status

-- | Server out of memory.
ErrOutOfMemory :: Status

-- | SASL authentication failed.
SaslAuthFail :: Status

-- | SASL authentication requires more steps.
SaslAuthContinue :: Status

-- | Errors that occur on the client.
data ClientError

-- | All servers are currently marked failed.
NoServersReady :: ClientError

-- | Timeout occurred sending request to server.
Timeout :: ClientError

-- | Errors related to Memcached protocol and bytes on the wire.
data ProtocolError

-- | Received an unknown response packet.
UnknownPkt :: String -> ProtocolError
[protocolError] :: ProtocolError -> String

-- | Unknown Memcached operation.
UnknownOp :: String -> ProtocolError
[protocolError] :: ProtocolError -> String

-- | Unknown Memcached status field value.
UnknownStatus :: String -> ProtocolError
[protocolError] :: ProtocolError -> String

-- | Unexpected length of a Memcached field (extras, key, or value).
BadLength :: String -> ProtocolError
[protocolError] :: ProtocolError -> String

-- | Response packet is for a different operation than expected.
WrongOp :: String -> ProtocolError
[protocolError] :: ProtocolError -> String

-- | Network socket closed without receiving enough bytes.
UnexpectedEOF :: String -> ProtocolError
[protocolError] :: ProtocolError -> String