memcache-0.5.0.0: Database/Memcache/Types/ServerSpec.hs
{-# LANGUAGE OverloadedStrings #-}
{-|
Module : Database.Memcache.Types.ServerSpec
Description : Memcached server specifications
Copyright : (c) David Terei, 2016
License : BSD
Maintainer : code@davidterei.com
Stability : stable
Portability : GHC
Server connection settings, including optional Meta Text auth-file
credentials.
-}
module Database.Memcache.Types.ServerSpec
( ServerSpec (..),
defaultServerSpec,
parseServerSpec,
)
where
import Control.Monad (guard)
import Data.ByteString (ByteString)
import qualified Data.ByteString as B
import qualified Data.ByteString.Char8 as C
import Data.Char (digitToInt, isHexDigit, ord)
import Data.Default
import Data.Maybe (fromMaybe)
import Database.Memcache.Types.Authentication (Authentication (..), validateCredentials)
import Database.Memcache.Util (note)
import Network.Socket (HostName, ServiceName)
import Network.URI (URI (..), URIAuth (..), parseAbsoluteURI, unEscapeString)
-- | A Memcached server connection configuration.
--
-- 'show' hides the password; see 'Authentication'.
data ServerSpec = ServerSpec
{ -- | Hostname of server to connect to. If it resolves to several
-- addresses, each is tried in turn until one accepts the connection. If
-- each refuses it or fails in some other way, connecting fails with the
-- first address's error. The addresses share the time an attempt at an
-- operation has (@optsServerTimeout@): an address that doesn't answer in
-- that time uses it up, and that attempt then tries none of the later
-- ones.
--
-- If it begins with @/@, it is instead the path of a Unix socket. The
-- client connects to it without looking it up or using 'ssPort', though
-- the port still names the server: see 'ssPort'. Each 'Char' of the path
-- is one byte of it, both to connect and to name the server, so a path
-- outside ASCII is given as its bytes, as 'parseServerSpec' gives it.
ssHost :: HostName,
-- | Port number server is running on. A Unix socket has none, and the
-- client doesn't use this to connect to one, but it still names the
-- server, as it does any other: the host and port make the server's name
-- on the hash ring that routes keys (see "Database.Memcache.Cluster") and
-- its @sid@, so changing a socket's port moves keys to other servers.
-- @\"11211\"@ names a socket by its path alone, as libmemcached's
-- @memcached_server_add@ does, and @\"0\"@ names it @path:0@, as
-- libmemcached's @memcached_server_add_unix_socket@ and pylibmc do.
ssPort :: ServiceName,
-- | Credentials to use for text auth-file authentication with this server.
ssAuth :: Authentication
}
deriving (Eq, Show)
-- | Parse a @memcached://@ URI into a @ServerSpec@.
--
-- The username and password are percent-decoded, so
-- @memcached:\/\/user:p%40ss\@cache.example@ has the password @p\@ss@, and
-- must pass 'validateCredentials'; one given without the other is ignored.
-- An IPv6 address goes in brackets, as in @memcached:\/\/[::1]:11211@.
--
-- A path after an empty host is a Unix socket, as in
-- @memcached:\/\/\/run\/memcached.sock@, or
-- @memcached:\/\/user:secret\@\/run\/memcached.sock@ with credentials. The
-- path is percent-decoded to bytes too, which 'ssHost' holds one per 'Char',
-- so @%C3%A9@ is the two bytes that encode U+00E9 in UTF-8. It mustn't contain
-- @%00@, and an @\@@ in it must be written @%40@: a URI with one slash too
-- many, such as @memcached:\/\/\/user:secret\@cache.example@, is then an
-- error, not a socket whose path holds the password. The error says that
-- credentials go right after @memcached:\/\/@: such a URI needs a slash fewer,
-- not its @\@@ written @%40@, which would make it that socket after all. A
-- socket takes no port, so @memcached:\/\/:11211\/run\/memcached.sock@ is an
-- error, and its 'ssPort' is @\"11211\"@, which names it by its path alone
-- (see 'ssPort'). A path of only slashes is no socket: @memcached:\/\/\/@,
-- @memcached:\/\/\/\/@ and @memcached:\/\/:11211\/@ are @127.0.0.1@ on port
-- @11211@, as @memcached:\/\/@ is.
--
-- Error messages never quote the URI, as it may contain a password.
parseServerSpec :: String -> Either String ServerSpec
parseServerSpec s = do
uri <- note "Not a valid URI" $ parseAbsoluteURI s
note "Must begin memcached://" $ guard $ uriScheme uri == "memcached:"
let mAuth = uriAuthority uri
auth <- maybe (pure Nothing) (readAuthentication . uriUserInfo) mAuth
socketPath <- readSocketPath uri
pure
. maybe id setSocketPath socketPath
. maybe id setHost mAuth
. maybe id setPort mAuth
. maybe id setAuth auth
$ defaultServerSpec
-- | Read the credentials from a URI's user information, @user:password\@@.
-- There are none unless both parts are non-empty.
readAuthentication :: String -> Either String (Maybe Authentication)
readAuthentication userInfo = case break (== ':') (takeWhile (/= '@') userInfo) of
(u@(_ : _), ':' : p@(_ : _)) -> do
let user = unEscapeBytes u
pass = unEscapeBytes p
validateCredentials user pass
pure $ Just $ Auth user pass
_ -> pure Nothing
-- | Read the path of a Unix socket from a URI whose host is empty, such as
-- @memcached:\/\/\/run\/memcached.sock@. There is none unless the URI has
-- the @\/\/@ of an authority, so that a URI missing a slash, such as
-- @memcached:\/user:secret\@cache.example@, never puts its password in
-- 'ssHost', which 'show' prints, and unless the path has more than slashes,
-- so that @memcached:\/\/\/@ is still the default server, and
-- @memcached:\/\/\/\/@ isn't the root directory.
--
-- The path is percent-decoded to bytes, one 'Char' each, as
-- 'Network.Socket.SockAddrUnix' writes a path one byte per 'Char'. A NUL
-- would end the path early, so it is an error. So is an @\@@ that isn't
-- written @%40@, as in @memcached:\/\/\/user:secret\@cache.example@, which
-- has one slash too many: as a path, its password would be in 'ssHost' too.
-- The error says that credentials go right after @memcached:\/\/@ before it
-- says that an @\@@ in a socket path is written @%40@: in such a URI, a @%40@
-- would put the password in 'ssHost' after all.
readSocketPath :: URI -> Either String (Maybe FilePath)
readSocketPath uri = case uriAuthority uri of
Just a | null (uriRegName a), any (/= '/') path -> do
note "A Unix socket path takes no port" $ guard $ null (uriPort a)
note "Unix socket path contains NUL" $ guard $ notElem '\0' path
note rawAtMessage $ guard $ notElem '@' (uriPath uri)
pure (Just path)
_ -> pure Nothing
where
-- After an authority, a path is empty or begins with a slash, so this
-- one begins with a slash whenever it has more than slashes.
path = C.unpack (unEscapeBytes (uriPath uri))
rawAtMessage =
"Unix socket path contains @; credentials go right after memcached://, as in "
<> "memcached://user:password@host, and an @ in a socket path is written %40"
-- | Percent-decode a string to the bytes it encodes. Unlike
-- 'unEscapeString', this doesn't decode them as UTF-8, which would replace
-- invalid sequences such as @%FF@ with U+FFFD. 'parseAbsoluteURI' has already
-- rejected malformed escapes and any character outside ASCII.
unEscapeBytes :: String -> ByteString
unEscapeBytes = B.pack . go
where
go ('%' : a : b : rest)
| isHexDigit a && isHexDigit b =
fromIntegral (digitToInt a * 16 + digitToInt b) : go rest
go (c : rest) = fromIntegral (ord c) : go rest
go [] = []
setHost :: URIAuth -> ServerSpec -> ServerSpec
setHost auth ss = case uriRegName auth of
"" -> ss
-- An IP literal such as an IPv6 address: drop the brackets, and decode the
-- "%25" that introduces a zone ID (RFC 6874).
'[' : literal -> ss {ssHost = unEscapeString $ takeWhile (/= ']') literal}
rn -> ss {ssHost = rn}
setPort :: URIAuth -> ServerSpec -> ServerSpec
setPort auth ss = fromMaybe ss $ do
p <- case uriPort auth of
"" -> Nothing
(':' : p) -> Just p
p -> Just p
pure $ ss {ssPort = p}
setSocketPath :: FilePath -> ServerSpec -> ServerSpec
setSocketPath path ss = ss {ssHost = path}
setAuth :: Authentication -> ServerSpec -> ServerSpec
setAuth auth ss = ss {ssAuth = auth}
-- | The default server: @127.0.0.1@ on memcached's default port, @11211@,
-- without authentication ('NoAuth').
defaultServerSpec :: ServerSpec
defaultServerSpec = ServerSpec "127.0.0.1" "11211" NoAuth
-- | 'def' is 'defaultServerSpec'.
instance Default ServerSpec where
def = defaultServerSpec