memcache-0.5.0.0: Database/Memcache/Server.hs
{-# LANGUAGE RecordWildCards #-}
{-# LANGUAGE CPP #-}
{-# LANGUAGE OverloadedStrings #-}
{-|
Module : Database.Memcache.Server
Description : Server Handling
Copyright : (c) David Terei, 2016
License : BSD
Maintainer : code@davidterei.com
Stability : stable
Portability : GHC
Handles the connections between a Memcached client and a single server.
Each new connection is authenticated, when its 'ServerSpec' has credentials,
and then asks the server for its version before it is used. Unless the server
reports memcached 1.6.10 or later, the connection is closed, having sent
nothing but the authentication exchange, when there are credentials, and
@version@, and v'ProtocolError' 'UnknownOp' is thrown (or, for an error reply,
what that reply throws for any request).
Memcached expected errors (part of the protocol) are returned in the Response;
unexpected errors, such as network failures, are thrown as exceptions. The
server's 'failed' timestamp is used by cluster retry handling.
-}
module Database.Memcache.Server (
-- * Server
Server(sid, failed), serverHost, serverPort, newServerDefault,
withSocket, close, closeAll,
-- * ServerOptions
ServerOptions(..), defaultServerOptions
) where
import Database.Memcache.Auth
import Database.Memcache.Errors
import Database.Memcache.Socket
import Database.Memcache.Types.Server
import Control.Monad (void, when)
import qualified Data.ByteString.Char8 as C
import Data.Char (isDigit)
import Data.Default
import Data.Hashable
import Data.IORef
import qualified Data.Pool as P
import Data.Pool (Pool)
import Database.Memcache.Types (ServerSpec (..))
import UnliftIO.Exception
import Network.Socket (HostName, ServiceName, getAddrInfo)
import qualified Network.Socket as S
#if MIN_VERSION_resource_pool(0,4,0)
#else
import Data.Time.Clock (NominalDiffTime)
#endif
-- | The host the server was configured with, as given in its 'ServerSpec'.
serverHost :: Server -> HostName
serverHost = addr
-- | The port or service name the server was configured with, as given in its
-- 'ServerSpec'.
serverPort :: Server -> ServiceName
serverPort = port
-- | Configurable options when creating a @Server@.
--
-- At the moment, this only applies to the @Pool@ information. This can be expanded in the future.
--
data ServerOptions
= ServerOptions
-- | Maximum number of pooled connections per stripe. With resource-pool 0.3,
-- see 'soNumStripes'. With 0.4 or later, it is split between the stripes
-- instead, and must be at least 'soNumStripes', or creating the server (and
-- so a client) throws an @ErrorCall@. Each stripe then holds up to
-- 'soNumResources' divided by 'soNumStripes', rounded up with 0.4, and
-- rounded down or up with 0.5 so that the total is 'soNumResources'.
{ soNumResources :: Int
-- | Number of pool stripes. With resource-pool 0.3, a pool has a stripe for
-- each capability instead, and each stripe holds up to 'soNumResources'
-- times 'soNumStripes' connections divided by the number of capabilities,
-- rounded up. A thread then takes connections from its own capability's
-- stripe, so a request can wait for one while other stripes have room. With
-- 0.4 and 0.5.0.0, stripes beyond the number of capabilities are never used.
, soNumStripes :: Int
#if MIN_VERSION_resource_pool(0,4,0)
-- | Connection keep-alive duration.
, soKeepAlive :: Double
#else
-- | Connection keep-alive duration.
, soKeepAlive :: NominalDiffTime
#endif
}
-- | The default server options:
--
-- * 'soNumResources': 1
-- * 'soNumStripes': 1
-- * 'soKeepAlive': 300 seconds
--
-- That is, at most one connection to each server (with resource-pool 0.3, one
-- for each capability), closed once it has been idle for 300 seconds.
defaultServerOptions :: ServerOptions
defaultServerOptions = ServerOptions
{ soNumResources = 1
, soNumStripes = 1
, soKeepAlive = 300
}
-- | 'def' is 'defaultServerOptions'.
instance Default ServerOptions where
def = defaultServerOptions
-- | Create a server using the default socket-pool implementation.
newServerDefault :: ServerOptions -> ServerSpec -> IO Server
newServerDefault serverOptions ServerSpec{..} = do
fat <- newIORef 0
gen <- newIORef 0
pSock <- getNewPool serverOptions
return Server
{ sid = serverHash
, pool = pSock
, addr = ssHost
, port = ssPort
, auth = ssAuth
, failed = fat
, generation = gen
, slotTaken = Nothing
}
where
serverHash = hash (ssHost, ssPort)
-- | Run a function with access to a pooled server connection. Afterwards the
-- connection goes back to the pool, unless the function threw or 'closeAll'
-- has run since the connection was opened, in which case it is closed. The
-- function is never given a connection opened before the latest 'closeAll'.
withSocket :: Server -> (Connection -> IO a) -> IO a
{-# INLINE withSocket #-}
withSocket svr act = mask $ \restore -> do
(slot, local) <- P.takeResource (pool svr)
-- Record that the request has stopped waiting (see 'slotTaken').
mapM_ (`writeIORef` True) (slotTaken svr)
(born, conn) <- connectionIn slot `onException` P.destroyResource (pool svr) local slot
r <- restore (act conn) `onException` P.destroyResource (pool svr) local slot
stale <- (/= born) <$> currentGeneration svr
if stale
then P.destroyResource (pool svr) local slot
else do
P.putResource local slot
-- 'closeAll' may have run between the check and the put, and closed
-- the idle connections before this one was back. If so, close them
-- again, without letting an exception cut that short.
raced <- (/= born) <$> currentGeneration svr
when raced $ uninterruptibleMask_ $ P.destroyAllResources (pool svr)
return r
where
-- The slot's connection, opening one if the slot has none or closing and
-- replacing one opened before the latest 'closeAll'. 'closeAll' may run
-- while a connection is being opened, so check the new one too.
connectionIn slot = do
held <- readIORef slot
current <- currentGeneration svr
case held of
Just res@(born, _) | born == current -> return res
_ -> do
releaseSlot slot
writeIORef slot Nothing
res <- connectTagged (generation svr) (ServerSpec (addr svr) (port svr) (auth svr))
writeIORef slot (Just res)
connectionIn slot
-- | Close the connections that are idle in the pool. Connections in use stay
-- open and go back to the pool when their request finishes; 'closeAll' closes
-- those too. A later request re-establishes connections as needed. An
-- asynchronous exception can't cut 'close' short: it is delivered once every
-- idle connection is closed.
close :: Server -> IO ()
{-# INLINE close #-}
close srv = uninterruptibleMask_ $ P.destroyAllResources $ pool srv
-- | Close every connection to the server: idle connections now, and each
-- connection in use as soon as the request using it finishes, instead of
-- returning it to the pool. It doesn't wait for those requests or interrupt
-- them, and it never connects or throws. Requests that start later never use
-- a connection opened before 'closeAll'; they open new ones. Like 'close', it
-- can't be cut short by an asynchronous exception.
closeAll :: Server -> IO ()
closeAll srv = uninterruptibleMask_ $ do
atomicModifyIORef' (generation srv) (\g -> (g + 1, ()))
P.destroyAllResources (pool srv)
-- | Read the generation. The read is atomic for simplicity; what makes the
-- checks in 'withSocket' sound is that it and 'closeAll' both go through the
-- pool's per-stripe lock, which orders the bump against a returned connection.
currentGeneration :: Server -> IO Int
currentGeneration svr = atomicModifyIORef' (generation svr) (\g -> (g, g))
-- Slots start empty: 'withSocket' opens a connection in a slot once it holds
-- the slot, so that connecting isn't part of waiting for one.
#if MIN_VERSION_resource_pool(0,4,0)
getNewPool :: ServerOptions -> IO (Pool Slot)
getNewPool serverOptions =
P.newPool
$ P.setNumStripes (Just $ soNumStripes serverOptions)
$ P.defaultPoolConfig (newIORef Nothing) releaseSlot (soKeepAlive serverOptions) (soNumResources serverOptions)
#else
getNewPool :: ServerOptions -> IO (Pool Slot)
getNewPool serverOptions =
P.createPool (newIORef Nothing) releaseSlot (soNumStripes serverOptions) (soKeepAlive serverOptions) (soNumResources serverOptions)
#endif
-- | Close the slot's connection, if it has one.
releaseSlot :: Slot -> IO ()
releaseSlot slot = readIORef slot >>= mapM_ (releaseSocket . snd)
-- | Open a connection, paired with the generation current when it was opened.
connectTagged :: IORef Int -> ServerSpec -> IO (Int, Connection)
connectTagged gen ss = do
born <- atomicModifyIORef' gen (\g -> (g, g))
conn <- connectSocket ss
return (born, conn)
connectSocket :: ServerSpec -> IO Connection
connectSocket ServerSpec{..} = do
let hints = S.defaultHints {
S.addrSocketType = S.Stream
}
-- A path is a Unix socket: there is nothing to look up, so it is the
-- only address to try.
addr:addrs <- case ssHost of
'/' : _ -> return [S.defaultHints {
S.addrFamily = S.AF_UNIX,
S.addrSocketType = S.Stream,
S.addrAddress = S.SockAddrUnix ssHost
}]
_ -> getAddrInfo (Just hints) (Just ssHost) (Just ssPort)
bracketOnError
(connectFirst addr addrs)
S.close
(\s -> do
-- A Unix socket rejects NoDelay, and has no TCP connection to
-- keep alive.
when (S.addrFamily addr /= S.AF_UNIX) $ do
S.setSocketOption s S.KeepAlive 1
S.setSocketOption s S.NoDelay 1
buffered <- newConnection s
authenticate buffered ssAuth
checkVersion buffered
return buffered
)
-- | The oldest memcached this client works with. From 1.6.10, the meta set
-- command that every store sends takes the data length as the token after
-- the key. Older servers reject the command without reading the data that
-- follows it, and then run the stored value's bytes as commands.
minimumVersion :: (Integer, Integer, Integer)
minimumVersion = (1, 6, 10)
-- | Ask the server for its version, and throw unless it is at least
-- @minimumVersion@. Every new connection does this, after authenticating when
-- there are credentials, before it is used for anything else, whichever of
-- the host's addresses it connected to, or through a Unix socket;
-- @connectSocket@ closes the connection when this throws.
--
-- An error reply, such as @CLIENT_ERROR unauthenticated@ from a server in
-- auth-file mode when no credentials are set, throws what it throws as the
-- reply to any request. Any other reply that isn't @VERSION@ and a version of
-- at least @minimumVersion@ throws v'ProtocolError' 'UnknownOp', quoting the
-- reply and naming the minimum. Retries treat that as a client fault, like a
-- rejected command: the server's version won't change on a retry, so the
-- operation fails at once and the server isn't marked as failed.
checkVersion :: Connection -> IO ()
checkVersion connection = do
sendRaw connection versionRequest
response <- recvResponse connection
when (responseCode response `elem` ["ERROR", "CLIENT_ERROR", "SERVER_ERROR"]) $
void (responseStatus response)
case responseVersion response of
Just v | v >= minimumVersion -> return ()
_ -> throwIO $ ProtocolError UnknownOp
{ protocolError = "memcached " <> showVersion minimumVersion
<> " or later is required, but the server answered version with "
<> show (C.unwords (responseCode response : responseTokens response))
}
where
showVersion (major, minor, patch) =
show major <> "." <> show minor <> "." <> show patch
-- | The version in a @VERSION@ reply, as its first three numbers: major,
-- minor and patch, separated by dots. Anything after the third number, such
-- as a @-rc1@ suffix or a word after the version, is ignored.
responseVersion :: Response -> Maybe (Integer, Integer, Integer)
responseVersion (Response "VERSION" (token:_) _) = do
(major, afterMajor) <- number token
(minor, afterMinor) <- number =<< C.stripPrefix "." afterMajor
(patch, _) <- number =<< C.stripPrefix "." afterMinor
return (major, minor, patch)
where
number bytes = case C.span isDigit bytes of
(digits, remainder) | not (C.null digits) -> Just (read (C.unpack digits), remainder)
_ -> Nothing
responseVersion _ = Nothing
-- | Connect a socket to the first of the resolved addresses that accepts,
-- trying them in order, so a host whose first address refuses the connection
-- (such as ::1 when the server listens on 127.0.0.1 only) can still be reached
-- through the others. If none accepts, rethrows the first address's error:
-- the resolver sorts addresses this host cannot use, such as IPv6 where it is
-- disabled, last, so the later errors are often just about those.
--
-- Only an 'IOException' from creating or connecting a socket moves on to the
-- next address, so the attempt's timeout ends the loop. Errors once
-- connected, such as rejected credentials, are raised after this returns:
-- they come from the server, and trying another address would hide them.
connectFirst :: S.AddrInfo -> [S.AddrInfo] -> IO S.Socket
connectFirst addr addrs = do
result <- tryIO $ connectTo addr
case result of
Right s -> return s
Left err -> foldr orElse (throwIO err) addrs
where
orElse next rest = tryIO (connectTo next) >>= either (const rest) return
connectTo a = bracketOnError
(S.socket (S.addrFamily a) (S.addrSocketType a) (S.addrProtocol a))
S.close
(\s -> S.connect s (S.addrAddress a) >> return s)
releaseSocket :: Connection -> IO ()
releaseSocket = closeConnection