Database.Memcache.Client

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 binary Memcached protocol is used and SASL authentication 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 MemcacheError or an IO exception thrown by the network.

We support the following logic for handling failure in operatins:

• Timeouts: we timeout any operation that takes too long and consider it failed.
• Retry: on operation failure (timeout, network error) we close the connection and rety the operation, doing this up to a configurable maximum.
• Failover: 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 as 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.

Some of this behavior can be configured through the Options data type. We also have the following concepts exposed by Memcached:

version

Each value has a Version associated with it. This is simply a numeric, monontonically increasing value. The version field allows for a primitive version of cas to be implemented.

expiration

Each value pair has an Expiration 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 3600 expires the value in 1 hour. When the value of the expiration is greater than 30 days however (2592000), the expiration field is instead interpretted as a UNIX timestamp (the number of seconds since epoch).

flags

Each value can have a small amount of fixed metadata associated with it beyond the value itself, these are the Flags.

Usage is roughly as follows:

module Main where

import qualified Database.Memcache.Client as M

main = do
    -- use default values: connects to localhost:11211
    mc <- M.newClient M.def M.def

    -- store and then retrieve a key-value pair
    M.set mc "key" "value" 0 0
    v' <- M.get mc "key"
    case v' of
        Nothing        -> putStrLn "Miss!"
        Just (v, _, _) -> putStrLn $ "Hit: " + show v

Client creation

newClient :: [ServerSpec] -> Options -> IO Client

Establish a new connection to a group of Memcached servers.

type Client = Cluster

A Memcached client, connected to a collection of Memcached servers.

data ServerSpec

ServerSpec specifies a server configuration for connection.

Constructors

ServerSpec

Fields

ssHost :: HostName

Hostname of server to connect to.

ssPort :: PortNumber

Port number server is running on.

ssAuth :: Authentication

Authentication values to use for SASL authentication with this server.

Instances

Eq ServerSpec

Show ServerSpec

Default ServerSpec

Default [ServerSpec]

data Options

Options specifies how a Memcached cluster should be configured.

Constructors

Options

Fields

optsServerRetries :: Retries

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.

optsFailRetryDelay :: Milli

After an operation has failed, how long to wait before retrying it while still within the optsServerRetries count?

Default is 200ms.

optsDeadRetryDelay :: Milli

How long to wait after a server has been marked down, before trying to use it again.

Default is 1500ms.

optsServerTimeout :: Milli

How long to wait for an operation to complete before considering it failed.

Default is 750ms.

Instances

Eq Options

Show Options

Default Options

data Authentication

SASL Authentication information for a server.

Constructors

Auth

Fields

username :: !Username

password :: !Password

NoAuth

Instances

Eq Authentication

Show Authentication

type Username = ByteString

Username for authentication.

type Password = ByteString

Password for authentication.

def :: Default a => a

The default value for this type.

quit :: Cluster -> IO ()

Gracefully close a connection to a Memcached cluster.

Operations

Get operations

get :: Cluster -> Key -> IO (Maybe (Value, Flags, Version))

Retrieve the value for the given key from Memcached.

gat :: Cluster -> Key -> Expiration -> 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 0 to store forever.

touch :: Cluster -> Key -> Expiration -> IO (Maybe Version)

Update the expiration time of a stored key-value pair, returning its version identifier. Use an expiration value of 0 to store forever.

Set operations

set :: Cluster -> Key -> Value -> Flags -> Expiration -> IO Version

Store a new (or overwrite exisiting) key-value pair, returning its version identifier. Use an expiration value of 0 to store forever.

cas :: Cluster -> Key -> Value -> Flags -> Expiration -> Version -> IO (Maybe 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, Nothing is returned. Use an expiration value of 0 to store forever.

add :: Cluster -> Key -> Value -> Flags -> Expiration -> IO (Maybe Version)

Store a new key-value pair, returning it's version identifier. If the key-value pair already exists, then fail (return Nothing). Use an expiration value of 0 to store forever.

replace :: Cluster -> Key -> Value -> Flags -> Expiration -> Version -> 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 0 to store forever.

Modify operations

increment :: Cluster -> Key -> Initial -> Delta -> Expiration -> Version -> IO (Maybe (Word64, 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 0 to store forever.

decrement :: 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 0 to store forever.

append :: Cluster -> Key -> Value -> Version -> IO (Maybe Version)

Append 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)

Prepend a value to an existing key-value pair, returning the new version identifier of the key-value pair when successful.

Delete operations

delete :: Cluster -> Key -> Version -> IO Bool

Delete a key-value pair at the server, returning true if successful.

flush :: Cluster -> Maybe Expiration -> IO ()

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.

Information operations

type StatResults = [(ByteString, ByteString)]

StatResults are a list of key-value pairs.

stats :: Cluster -> Maybe Key -> IO [(Server, Maybe StatResults)]

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 "items", "slabs" or "settings".

version :: Cluster -> IO ByteString

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.

Errors

data MemcacheError

All exceptions that a Memcached client may throw.

Constructors

OpError Status

Memcached operation error.

ClientError ClientError

Error occuring on client side.

ProtocolError ProtocolError

Errors occurring communicating with Memcached server.

Instances

Eq MemcacheError

Show MemcacheError

Exception MemcacheError

data Status

The status (success or error) of a Memcached operation returned in a Response.

Constructors

NoError

Operation successful.

ErrKeyNotFound

Key not found.

ErrKeyExists

Key exists when not expected.

ErrValueTooLarge

Value too large to store at server.

ErrInvalidArgs

Invalid arguments for operation.

ErrItemNotStored

Key-Value pair not stored at server (internal error).

ErrValueNonNumeric

Value not numeric when increment or decrement requested.

ErrUnknownCommand

Server doesn't know requested command.

ErrOutOfMemory

Server out of memory.

SaslAuthFail

SASL authentication failed.

SaslAuthContinue

SASL authentication requires more steps.

Instances

Eq Status

Show Status

data ClientError

Errors that occur on the client.

Constructors

NoServersReady

All servers are currently marked failed.

Timeout

Timeout occurred sending request to server.

Instances

Eq ClientError

Show ClientError

data ProtocolError

Errors related to Memcached protocol and bytes on the wire.

Constructors

UnknownPkt

Received an unknown response packet.

Fields

protocolError :: String

UnknownOp

Unknown Memcached operation.

Fields

protocolError :: String

UnknownStatus

Unknown Memcached status field value.

Fields

protocolError :: String

BadLength

Unexpected length of a Memcached field (extras, key, or value).

Fields

protocolError :: String

WrongOp

Response packet is for a different operation than expected.

Fields

protocolError :: String

UnexpectedEOF

Network socket closed without receiving enough bytes.

Fields

protocolError :: String

Instances

Eq ProtocolError

Show ProtocolError