-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/
-- | Web application deployment manager, focusing on Haskell web frameworks
--
-- Handles deployment of web apps, providing a reverse proxy to achieve
-- zero downtime deployments. For more information, please see the README
-- on Github: https://github.com/snoyberg/keter#readme
--
-- Release history:
--
--
-- - 0.4.0 Switch to fsnotify to get cross-platform support. No
-- longer using raw proxies, but instead WAI proxies.
-- - 0.3.7 Sending a HUP signal reloads the list of deployed
-- apps. This is useful for circumstances where inotify does not work
-- correctly, such as on file systems which do not support it.
-- - 0.3.5 You can now create Keter bundles without any
-- applications. These can contain static hosts and redirects.
--
@package keter
@version 0.4.0
module Keter.SSL
data TLSConfigNoDir
setDir :: FilePath -> TLSConfigNoDir -> (Settings, TLSSettings)
instance FromJSON TLSConfigNoDir
module Keter.ReverseProxy
data ReverseProxyConfig
ReverseProxyConfig :: Text -> Int -> Text -> Bool -> Maybe Int -> Set RewriteRule -> Set RewriteRule -> ReverseProxyConfig
reversedHost :: ReverseProxyConfig -> Text
reversedPort :: ReverseProxyConfig -> Int
reversingHost :: ReverseProxyConfig -> Text
reverseUseSSL :: ReverseProxyConfig -> Bool
reverseTimeout :: ReverseProxyConfig -> Maybe Int
rewriteResponseRules :: ReverseProxyConfig -> Set RewriteRule
rewriteRequestRules :: ReverseProxyConfig -> Set RewriteRule
data RewriteRule
RewriteRule :: Text -> Text -> Text -> RewriteRule
ruleHeader :: RewriteRule -> Text
ruleRegex :: RewriteRule -> Text
ruleReplacement :: RewriteRule -> Text
data RPEntry
RPEntry :: ReverseProxyConfig -> Manager -> RPEntry
config :: RPEntry -> ReverseProxyConfig
httpManager :: RPEntry -> Manager
simpleReverseProxy :: RPEntry -> Application
instance Eq RewriteRule
instance Ord RewriteRule
instance Eq ReverseProxyConfig
instance Ord ReverseProxyConfig
instance FromJSON RewriteRule
instance Default ReverseProxyConfig
instance FromJSON ReverseProxyConfig
-- | Ensures that processes are stopped when Keter shuts down.
module Keter.ProcessTracker
data ProcessTracker
trackProcess :: ProcessTracker -> ProcessHandle -> IO (IO ())
initProcessTracker :: IO ProcessTracker
module Keter.Prelude
-- | A space efficient, packed, unboxed Unicode text type.
data Text :: *
type String = Text
-- | The Monad class defines the basic operations over a
-- monad, a concept from a branch of mathematics known as
-- category theory. From the perspective of a Haskell programmer,
-- however, it is best to think of a monad as an abstract datatype
-- of actions. Haskell's do expressions provide a convenient
-- syntax for writing monadic expressions.
--
-- Minimal complete definition: >>= and return.
--
-- Instances of Monad should satisfy the following laws:
--
--
-- return a >>= k == k a
-- m >>= return == m
-- m >>= (\x -> k x >>= h) == (m >>= k) >>= h
--
--
-- Instances of both Monad and Functor should additionally
-- satisfy the law:
--
--
-- fmap f xs == xs >>= return . f
--
--
-- The instances of Monad for lists, Maybe and IO
-- defined in the Prelude satisfy these laws.
class Monad (m :: * -> *)
(>>=) :: Monad m => m a -> (a -> m b) -> m b
(>>) :: Monad m => m a -> m b -> m b
return :: Monad m => a -> m a
fail :: Monad m => String -> m a
-- | The Maybe type encapsulates an optional value. A value of type
-- Maybe a either contains a value of type a
-- (represented as Just a), or it is empty (represented
-- as Nothing). Using Maybe is a good way to deal with
-- errors or exceptional cases without resorting to drastic measures such
-- as error.
--
-- The Maybe type is also a monad. It is a simple kind of error
-- monad, where all errors are represented by Nothing. A richer
-- error monad can be built using the Either type.
data Maybe a :: * -> *
Nothing :: Maybe a
Just :: a -> Maybe a
data Bool :: *
False :: Bool
True :: Bool
-- | Application operator. This operator is redundant, since ordinary
-- application (f x) means the same as (f $ x).
-- However, $ has low, right-associative binding precedence, so it
-- sometimes allows parentheses to be omitted; for example:
--
--
-- f $ g $ h x = f (g (h x))
--
--
-- It is also useful in higher-order situations, such as map
-- ($ 0) xs, or zipWith ($) fs xs.
($) :: (a -> b) -> a -> b
-- | Function composition.
(.) :: (b -> c) -> (a -> b) -> a -> c
data LogMessage
ProcessCreated :: FilePath -> LogMessage
InvalidBundle :: FilePath -> SomeException -> LogMessage
ProcessDidNotStart :: FilePath -> LogMessage
ExceptionThrown :: Text -> SomeException -> LogMessage
RemovingPort :: Int -> LogMessage
UnpackingBundle :: FilePath -> FilePath -> LogMessage
TerminatingApp :: Text -> LogMessage
FinishedReloading :: Text -> LogMessage
TerminatingOldProcess :: Text -> LogMessage
RemovingOldFolder :: FilePath -> LogMessage
ReceivedInotifyEvent :: Text -> LogMessage
ProcessWaiting :: FilePath -> LogMessage
log :: LogMessage -> KIO ()
logEx :: Q Exp
data KIO a
toString :: ToString a => a -> String
-- | map f xs is the list obtained by applying f
-- to each element of xs, i.e.,
--
--
-- map f [x1, x2, ..., xn] == [f x1, f x2, ..., f xn]
-- map f [x1, x2, ...] == [f x1, f x2, ...]
--
map :: (a -> b) -> [a] -> [b]
-- | Split the input between the two argument arrows and combine their
-- output. Note that this is in general not a functor.
--
-- The default definition may be overridden with a more efficient version
-- if desired.
(***) :: Arrow a => forall b c b' c'. a b c -> a b' c' -> a (b, b') (c, c')
readFileLBS :: FilePath -> KIO (Either SomeException ByteString)
-- | The Either type represents values with two possibilities: a
-- value of type Either a b is either Left
-- a or Right b.
--
-- The Either type is sometimes used to represent a value which is
-- either correct or an error; by convention, the Left constructor
-- is used to hold an error value and the Right constructor is
-- used to hold a correct value (mnemonic: "right" also means "correct").
data Either a b :: * -> * -> *
Left :: a -> Either a b
Right :: b -> Either a b
-- | Case analysis for the Either type. If the value is
-- Left a, apply the first function to a; if it
-- is Right b, apply the second function to b.
either :: (a -> c) -> (b -> c) -> Either a b -> c
-- | The SomeException type is the root of the exception type
-- hierarchy. When an exception of type e is thrown, behind the
-- scenes it is encapsulated in a SomeException.
data SomeException :: *
runKIO :: (LogMessage -> IO ()) -> KIO a -> IO a
void :: Monad m => m a -> m ()
liftIO :: IO a -> KIO (Either SomeException a)
forkKIO :: KIO () -> KIO ()
forkKIO' :: KIO () -> KIO (Either SomeException ThreadId)
(++) :: Monoid m => m -> m -> m
minBound :: Bounded a => a
-- | the successor of a value. For numeric types, succ adds 1.
succ :: Enum a => a -> a
show :: Show a => a -> Text
-- | Conditional execution of monadic expressions. For example,
--
--
-- when debug (putStr "Debugging\n")
--
--
-- will output the string Debugging\n if the Boolean value
-- debug is True, and otherwise do nothing.
when :: Monad m => Bool -> m () -> m ()
fromText :: FromText a => Text -> a
-- | flip f takes its (first) two arguments in the reverse
-- order of f.
flip :: (a -> b -> c) -> b -> a -> c
-- | Conversion of values to readable Strings.
--
-- Minimal complete definition: showsPrec or show.
--
-- Derived instances of Show have the following properties, which
-- are compatible with derived instances of Read:
--
--
-- - The result of show is a syntactically correct Haskell
-- expression containing only constants, given the fixity declarations in
-- force at the point where the type is declared. It contains only the
-- constructor names defined in the data type, parentheses, and spaces.
-- When labelled constructor fields are used, braces, commas, field
-- names, and equal signs are also used.
-- - If the constructor is defined to be an infix operator, then
-- showsPrec will produce infix applications of the
-- constructor.
-- - the representation will be enclosed in parentheses if the
-- precedence of the top-level constructor in x is less than
-- d (associativity is ignored). Thus, if d is
-- 0 then the result is never surrounded in parentheses; if
-- d is 11 it is always surrounded in parentheses,
-- unless it is an atomic expression.
-- - If the constructor is defined using record syntax, then
-- show will produce the record-syntax form, with the fields given
-- in the same order as the original declaration.
--
--
-- For example, given the declarations
--
--
-- infixr 5 :^:
-- data Tree a = Leaf a | Tree a :^: Tree a
--
--
-- the derived instance of Show is equivalent to
--
--
-- instance (Show a) => Show (Tree a) where
--
-- showsPrec d (Leaf m) = showParen (d > app_prec) $
-- showString "Leaf " . showsPrec (app_prec+1) m
-- where app_prec = 10
--
-- showsPrec d (u :^: v) = showParen (d > up_prec) $
-- showsPrec (up_prec+1) u .
-- showString " :^: " .
-- showsPrec (up_prec+1) v
-- where up_prec = 5
--
--
-- Note that right-associativity of :^: is ignored. For example,
--
--
-- - show (Leaf 1 :^: Leaf 2 :^: Leaf 3) produces the
-- string "Leaf 1 :^: (Leaf 2 :^: Leaf 3)".
--
class Show a
data KeterException
CannotParsePostgres :: FilePath -> KeterException
ExitCodeFailure :: FilePath -> ExitCode -> KeterException
NoPortsAvailable :: KeterException
InvalidConfigFile :: KeterException
toException :: Exception e => e -> SomeException
newStdGen :: KIO StdGen
-- | A class for types with a default value.
class Default a
def :: Default a => a
-- | A fixed-precision integer type with at least the range [-2^29 ..
-- 2^29-1]. The exact range for a given implementation can be
-- determined by using minBound and maxBound from the
-- Bounded class.
data Int :: *
-- | Boolean "and"
(&&) :: Bool -> Bool -> Bool
(==) :: Eq a => a -> a -> Bool
(/=) :: Eq a => a -> a -> Bool
(*) :: Num a => a -> a -> a
-- | general coercion from integral types
fromIntegral :: (Integral a, Num b) => a -> b
-- | reverse xs returns the elements of xs in
-- reverse order. xs must be finite.
reverse :: [a] -> [a]
-- | otherwise is defined as the value True. It helps to make
-- guards more readable. eg.
--
--
-- f x | x < 0 = ...
-- | otherwise = ...
--
otherwise :: Bool
timeout :: Int -> KIO a -> KIO (Maybe a)
threadDelay :: Int -> KIO ()
-- | Identity function.
id :: a -> a
-- | filter, applied to a predicate and a list, returns the list of
-- those elements that satisfy the predicate; i.e.,
--
--
-- filter p xs = [ x | x <- xs, p x]
--
filter :: (a -> Bool) -> [a] -> [a]
-- | mapM_ f is equivalent to sequence_ .
-- map f.
mapM_ :: Monad m => (a -> m b) -> [a] -> m ()
fmap :: Functor f => forall a b. (a -> b) -> f a -> f b
-- | Boolean "not"
not :: Bool -> Bool
-- | The maybe function takes a default value, a function, and a
-- Maybe value. If the Maybe value is Nothing, the
-- function returns the default value. Otherwise, it applies the function
-- to the value inside the Just and returns the result.
maybe :: b -> (a -> b) -> Maybe a -> b
(>) :: Ord a => a -> a -> Bool
(<) :: Ord a => a -> a -> Bool
(<=) :: Ord a => a -> a -> Bool
(+) :: Num a => a -> a -> a
(-) :: Num a => a -> a -> a
getCurrentTime :: KIO UTCTime
-- | An alias for append.
() :: FilePath -> FilePath -> FilePath
-- | An alias for addExtension.
(<.>) :: FilePath -> Text -> FilePath
data FilePath :: *
-- | Check if a directory exists at the given path.
--
-- Symbolic links are resolved to their targets before checking their
-- type.
--
-- This computation does not throw exceptions.
isDirectory :: FilePath -> IO Bool
-- | Check if a file exists at the given path.
--
-- Any non‐directory object, including devices and pipes, are considered
-- to be files. Symbolic links are resolved to their targets before
-- checking their type.
--
-- This computation does not throw exceptions.
isFile :: FilePath -> IO Bool
-- | Recursively remove a directory tree rooted at the given path.
--
-- This computation does not follow symlinks. If the tree contains
-- symlinks, the links themselves will be removed, but not the objects
-- they point to.
--
-- If the root path is a symlink, then it will be treated as if it were a
-- regular directory.
--
-- This computation throws IOError on failure. See “Classifying
-- I/O errors” in the System.IO.Error documentation for
-- information on why the failure occured.
removeTree :: FilePath -> IO ()
-- | Create a directory at a given path, including any parents which might
-- be missing.
--
-- This computation throws IOError on failure. See “Classifying
-- I/O errors” in the System.IO.Error documentation for
-- information on why the failure occured.
createTree :: FilePath -> IO ()
-- | Retrieves the FilePath’s directory. If the path is already a
-- directory, it is returned unchanged.
directory :: FilePath -> FilePath
-- | Rename a filesystem object.
--
-- This computation throws IOError on failure. See “Classifying
-- I/O errors” in the System.IO.Error documentation for
-- information on why the failure occured.
rename :: FilePath -> FilePath -> IO ()
-- | Retrieve a FilePath’s basename component.
--
--
-- basename "foo/bar.txt" == "bar"
--
basename :: FilePath -> FilePath
-- | Attempt to convert a FilePath to human‐readable text.
--
-- If the path is decoded successfully, the result is a Right
-- containing the decoded text. Successfully decoded text can be
-- converted back to the original path using fromText.
--
-- If the path cannot be decoded, the result is a Left containing
-- an approximation of the original path. If displayed to the user, this
-- value should be accompanied by some warning that the path has an
-- invalid encoding. Approximated text cannot be converted back to the
-- original path.
--
-- This function ignores the user’s locale, and assumes all file paths
-- are encoded in UTF8. If you need to display file paths with an unusual
-- or obscure encoding, use encode and then decode them manually.
--
-- Since: 0.2
toText :: FilePath -> Either Text Text
-- | Get whether a FilePath’s last extension is the predicate.
hasExtension :: FilePath -> Text -> Bool
-- | List objects in a directory, excluding "." and "..".
-- Each returned FilePath includes the path of the directory.
-- Entries are not sorted.
--
-- This computation throws IOError on failure. See “Classifying
-- I/O errors” in the System.IO.Error documentation for
-- information on why the failure occured.
listDirectory :: FilePath -> IO [FilePath]
-- | Attempt to parse a FilePath from a string suitable for use with
-- functions in System.IO. Do not use this function for parsing
-- human‐readable paths, as the character set decoding is
-- platform‐dependent. For converting human‐readable text to a
-- FilePath, use fromText.
--
-- Since: 0.3.1
decodeString :: String -> FilePath
-- | An MVar (pronounced "em-var") is a synchronising variable, used
-- for communication between concurrent threads. It can be thought of as
-- a a box, which may be empty or full.
data MVar a :: * -> *
newMVar :: a -> KIO (MVar a)
newEmptyMVar :: KIO (MVar a)
modifyMVar :: MVar a -> (a -> KIO (a, b)) -> KIO b
modifyMVar_ :: MVar a -> (a -> KIO a) -> KIO ()
swapMVar :: MVar a -> a -> KIO a
takeMVar :: MVar a -> KIO a
tryTakeMVar :: MVar a -> KIO (Maybe a)
putMVar :: MVar a -> a -> KIO ()
-- | A mutable variable in the IO monad
data IORef a :: * -> *
newIORef :: a -> KIO (IORef a)
atomicModifyIORef :: IORef a -> (a -> (a, b)) -> KIO b
-- | Chan is an abstract type representing an unbounded FIFO
-- channel.
data Chan a :: * -> *
newChan :: KIO (Chan a)
readChan :: Chan a -> KIO a
writeChan :: Chan a -> a -> KIO ()
instance Typeable KeterException
instance Show KeterException
instance Exception KeterException
instance FromText Builder
instance FromText Builder
instance FromText FilePath
instance FromText Text
instance ToString FilePath
instance ToString Text
instance ToString String
instance Show LogMessage
instance Applicative KIO
instance Functor KIO
instance Monad KIO
module Keter.Postgres
-- | Name of the application. Should just be the basename of the
-- application file.
type Appname = Text
-- | Information on an individual PostgreSQL database.
data DBInfo
DBInfo :: Text -> Text -> Text -> DBInfo
dbiName :: DBInfo -> Text
dbiUser :: DBInfo -> Text
dbiPass :: DBInfo -> Text
-- | Abstract type allowing access to config information via getInfo
data Postgres
data Settings
-- | How to create the given user/database. Default: uses the psql
-- command line tool and sudo -u postgres.
setupDBInfo :: Settings -> DBInfo -> IO ()
-- | Load a set of existing connections from a config file. If the file
-- does not exist, it will be created. Any newly created databases will
-- automatically be saved to this file.
load :: Settings -> FilePath -> KIO (Either SomeException Postgres)
-- | Get information on an individual app's database information. If no
-- information exists, it will create a random database, add it to the
-- config file, and return it.
getInfo :: Postgres -> Appname -> KIO (Either SomeException DBInfo)
instance Show DBInfo
instance FromJSON DBInfo
instance ToJSON DBInfo
instance Default Settings
module Keter.TempFolder
data TempFolder
setup :: FilePath -> KIO (Either SomeException TempFolder)
getFolder :: Maybe (UserID, GroupID) -> TempFolder -> Appname -> KIO (Either SomeException FilePath)
module Keter.PortManager
-- | A port for an individual app to listen on.
type Port = Int
-- | A virtual host we want to serve content from.
type Host = String
-- | An abstract type which can accept commands and sends them to a
-- background nginx thread.
data PortManager
data PortEntry
PEPort :: Port -> PortEntry
PEStatic :: FilePath -> PortEntry
PERedirect :: ByteString -> PortEntry
PEReverseProxy :: RPEntry -> PortEntry
-- | Controls execution of the nginx thread. Follows the settings type
-- pattern. See: http://www.yesodweb.com/book/settings-types.
data Settings
-- | Which ports to assign to apps. Default: 4000-4999
portRange :: Settings -> [Port]
-- | Gets an unassigned port number.
getPort :: PortManager -> KIO (Either SomeException Port)
-- | Inform the nginx thread that the given port number is no longer being
-- used, and may be reused by a new process. Note that recycling puts the
-- new ports at the end of the queue (FIFO), so that if an application
-- holds onto the port longer than expected, there should be no issues.
releasePort :: PortManager -> Port -> KIO ()
-- | Add a new entry to the configuration for the given hostname and reload
-- nginx. Will overwrite any existing configuration for the given host.
-- The second point is important: it is how we achieve zero downtime
-- transitions between an old and new version of an app.
addEntry :: PortManager -> Host -> PortEntry -> KIO ()
-- | Remove an entry from the configuration and reload nginx.
removeEntry :: PortManager -> Host -> KIO ()
lookupPort :: PortManager -> ByteString -> KIO (Maybe PortEntry)
-- | Start running a separate thread which will accept commands and modify
-- Nginx's behavior accordingly.
start :: Settings -> KIO (Either SomeException PortManager)
instance FromJSON Settings
instance Default Settings
-- | A light-weight, minimalistic reverse HTTP proxy.
module Keter.Proxy
reverseProxy :: Bool -> Manager -> Settings -> PortLookup -> IO ()
-- | Mapping from virtual hostname to port number.
type PortLookup = ByteString -> IO (Maybe PortEntry)
reverseProxySsl :: Bool -> Manager -> TLSSettings -> Settings -> PortLookup -> IO ()
setDir :: FilePath -> TLSConfigNoDir -> (Settings, TLSSettings)
data TLSConfigNoDir
module Keter.LogFile
data LogFile
start :: FilePath -> KIO (Either SomeException LogFile)
addChunk :: LogFile -> ByteString -> KIO ()
close :: LogFile -> KIO ()
module Keter.Logger
data Logger
start :: LogFile -> LogFile -> KIO Logger
attach :: Logger -> LogPipes -> KIO ()
detach :: Logger -> KIO ()
data LogPipes
LogPipes :: LogPipe -> LogPipe -> LogPipes
stdOut :: LogPipes -> LogPipe
stdErr :: LogPipes -> LogPipe
data LogPipe
mkLogPipe :: KIO (LogPipe, Sink ByteString IO ())
dummy :: Logger
module Keter.Process
-- | Run the given command, restarting if the process dies.
run :: ProcessTracker -> Maybe Text -> FilePath -> FilePath -> [String] -> [(String, String)] -> Logger -> KIO Process
-- | Terminate the process and prevent it from being restarted.
terminate :: Process -> KIO ()
-- | Abstract type containing information on a process which will be
-- restarted.
data Process
module Keter.App
data App
start :: TempFolder -> Maybe (Text, (UserID, GroupID)) -> ProcessTracker -> PortManager -> Postgres -> Logger -> Appname -> FilePath -> KIO () -> KIO (App, KIO ())
reload :: App -> KIO ()
terminate :: App -> KIO ()
instance Eq StaticHost
instance Ord StaticHost
instance Eq Redirect
instance Ord Redirect
instance FromJSON Redirect
instance FromJSON StaticHost
instance FromJSON Config
instance FromJSON AppConfig
module Keter.Main
keter :: FilePath -> IO ()
instance FromJSON Config
instance Default Config