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


-- | DepTrack applied to DevOps.
--   
--   Describe your infrastructure with a directed-acyclic graph. Please see
--   README.md
@package deptrack-devops
@version 0.1.0.0

module Devops.Base

-- | Encapsulates a deferred <a>Op</a> along with an <tt>a</tt> argument to
--   generate it.
--   
--   The PreOp is more or less a continuation to produce an Op (which is a
--   set of actions to turnup/turndown system states).
--   
--   This definition uses existential quantification with a Typeable
--   constraint: * generally, we do not care about the intermediate type *
--   however, we may want to inspect dependency nodes to apply some
--   tree/graph conversion * we don't want to explicitly require library
--   users to create a gigantic sum-type
data PreOp
PreOp :: !a -> !(a -> Op) -> PreOp

-- | Projects a Typeable object to a Preop using a projection function.
--   This is a low-level projection function.
rawpreop :: Typeable a => a -> (a -> Op) -> PreOp

-- | An actual system-level operation that can be tracked and depended on.
--   <a>Op</a>s provide standard <a>OpFunctions</a> for actually enacting
--   commands. They are identified by a <a>OpUniqueId</a> which is, as it
--   name implies, is guaranteed to be unique across a whole
--   <tt>DepTrack</tt> graph.
data Op
Op :: !OpDescription -> !OpFunctions -> !OpUniqueId -> Op
[opDescription] :: Op -> !OpDescription
[opFunctions] :: Op -> !OpFunctions
[opUniqueId] :: Op -> !OpUniqueId
data OpDescription
OpDescription :: !Name -> !Text -> OpDescription
[opName] :: OpDescription -> !Name
[opDocumentation] :: OpDescription -> !Text

-- | Functions that can be run on an <a>Op</a> object, e.g. a system
--   dependency to enact commands.
data OpFunctions
OpFunctions :: !OpCheck -> !OpAction -> !OpAction -> !OpAction -> OpFunctions
[opCheck] :: OpFunctions -> !OpCheck
[opTurnup] :: OpFunctions -> !OpAction
[opTurndown] :: OpFunctions -> !OpAction
[opReload] :: OpFunctions -> !OpAction

-- | Handy name for tracking DevOp dependencies using a pure computation
--   (recommended).
type DevOp env = DevOpT env []

-- | Handy name for tracking DevOp dependencies.
type DevOpT e m = ReaderT e (DepTrackT PreOp m)

-- | Applies the argument and the function in a PreOp to get an Op.
runPreOp :: PreOp -> Op

-- | Reads the runtime representation of the PreOp argument.
--   
--   This function is useful to display or filter dependency nodes at
--   runtime.
preopType :: PreOp -> TypeRep
type OpUniqueId = Int

-- | The identifier for a PreOp.
preOpUniqueId :: PreOp -> OpUniqueId
type OpCheck = IO CheckResult
data CheckResult

-- | the Check was skipped (e.g., it's not meaningful or the actions are
--   idempotent and cheap =&gt; checking is not useful)
Skipped :: CheckResult

-- | the Check has not taken place or not succeeded for unknown reasons
Unknown :: CheckResult

-- | the Check finished and determined a success
Success :: CheckResult

-- | the Check finished and determined a failure
Failure :: !Reason -> CheckResult

-- | Transforms True into Success, False into a Failure.
fromBool :: Bool -> CheckResult
noCheck :: OpCheck
type OpAction = IO ()
noAction :: OpAction

-- | Build the internal representation for an <a>Op</a>.
buildOp :: Name -> Text -> OpCheck -> OpAction -> OpAction -> OpAction -> Op

-- | Build the internal representation for a <a>PreOp</a>.
buildPreOp :: Name -> Text -> OpCheck -> OpAction -> OpAction -> OpAction -> PreOp

-- | Returns a noop.
noop :: Name -> Text -> PreOp

-- | Takes an Op and makes it a PreOp with same description but with noop
--   checks and actions.
neutralize :: Op -> PreOp

-- | Almost like a PreOp, but which exposes the type of the intermediary
--   value.
type TypedPreOp a = (a, a -> Op)

-- | Convert a PreOp to a TypedPreOp at runtime.
castPreop :: Typeable a => Proxy a -> PreOp -> Maybe (TypedPreOp a)

-- | Tracks dependencies to build an object given a pair of projection --
--   functions and a DepTrackT computation tracking predecessors.
devop :: (Typeable b, Monad m) => (a -> b) -> (a -> Op) -> DevOpT e m a -> DevOpT e m b
type Name = Text
track :: (Monad m) => (a -> PreOp) -> DevOpT e m a -> DevOpT e m a
declare :: (Monad m) => PreOp -> DevOpT e m a -> DevOpT e m a
inject :: (Monad m) => DevOpT e m a -> DevOpT e m b -> DevOpT e m (a, b)
guardEnv :: (Monad m, Alternative m) => (e -> Bool) -> DevOpT e m ()

-- | Evaluates the return value of a DevOp, discarding the dependencies.
runDevOp :: env -> DevOp env a -> Maybe a

-- | Evaluates the dependencies of a DevOp, discarding any result.
getDependenciesOnly :: env -> DevOp env a -> Forest PreOp
instance GHC.Show.Show Devops.Base.NoOp
instance GHC.Classes.Ord Devops.Base.CheckResult
instance GHC.Classes.Eq Devops.Base.CheckResult
instance GHC.Read.Read Devops.Base.CheckResult
instance GHC.Show.Show Devops.Base.CheckResult
instance GHC.Generics.Generic Devops.Base.OpDescription
instance GHC.Classes.Ord Devops.Base.OpDescription
instance GHC.Classes.Eq Devops.Base.OpDescription
instance GHC.Show.Show Devops.Base.OpDescription
instance GHC.Show.Show Devops.Base.PreOp
instance GHC.Classes.Eq Devops.Base.PreOp
instance GHC.Show.Show Devops.Base.Op
instance Data.Hashable.Class.Hashable Devops.Base.OpDescription


-- | Set of constraints useful for declaring DevOp.
module Devops.Constraints
class HasOS a
os :: HasOS a => a -> String
type OSName = String

-- | Guards an action if it is not on a given OS.
onOS :: (Monad m, Applicative m, Alternative m, HasOS env) => OSName -> DevOpT env m a -> DevOpT env m a

module Devops.Graph

-- | The intended direction of an operation.
data WantedDirection
TurnedUp :: WantedDirection
TurnedDown :: WantedDirection

-- | The stability an operation reached.
data Stability
Stable :: Stability
Transient :: Stability

-- | An OpGraph is a Graph containing PreOp.
type OpGraph = GraphData PreOp OpUniqueId

-- | The observed status for an operation.
data OpStatus
opCheckResult :: Lens' OpStatus CheckResult

-- | A map representing the mutable status for a set of operations.
type OpStatusesMap = Map OpUniqueId (TVar OpStatus)

-- | A snapshot representing the intent for a single operation at a given
--   time.
data OpIntent
intentPreOp :: Lens' OpIntent PreOp
intentDirection :: Lens' OpIntent WantedDirection

-- | A map representing the collection of histories for a set of
--   operations.
type Intents = Map OpUniqueId OpHistory
emptyIntents :: Intents
type Broadcast = (OpUniqueId, CheckResult, Stability, WantedDirection) -> IO ()
noBroadcast :: Broadcast

-- | Computes a snapshot of an OpGraph.
snapshot :: WantedDirection -> OpGraph -> Intents -> Intents

-- | Returns an operation to atomically build a status map from a graph
--   snapshot.
makeStatusesMap :: Intents -> STM OpStatusesMap
asyncTurnupGraph :: Broadcast -> OpStatusesMap -> Intents -> OpGraph -> IO ()

-- | TODO: no longer transpose graph at the calling sites
asyncTurndownGraph :: Broadcast -> OpStatusesMap -> Intents -> OpGraph -> IO ()
checkWholeGraph :: Broadcast -> OpStatusesMap -> Intents -> OpGraph -> IO [Async (OpUniqueId, CheckResult, Stability, WantedDirection)]

-- | Turns a graph up and keep it up.
upkeepGraph :: Broadcast -> OpStatusesMap -> Intents -> OpGraph -> UpkeepFSM -> DownkeepFSM -> IO ()
defaultUpKeepFSM :: UpkeepFSM
defaultDownKeepFSM :: DownkeepFSM

-- | Atomically wait until all statuses are stable after reaching a given
--   direction.
waitStability :: WantedDirection -> Stability -> [TVar OpStatus] -> STM ()

-- | Turn-up a graph sequentially
--   
--   Topologically sorts the graph then invokes <tt>TurnUp</tt> action
--   synchronously through each node. Note the order of execution is
--   deterministic.
syncTurnupGraph :: Broadcast -> OpGraph -> IO ()

-- | Turn-down a graph sequentially
--   
--   Topologically sorts the graph then invokes <tt>TurnDown</tt> action
--   synchronously through each node. Note the order of execution is
--   deterministic.
syncTurnDownGraph :: Broadcast -> OpGraph -> IO ()
instance GHC.Show.Show Devops.Graph.OpStatus
instance GHC.Generics.Generic Devops.Graph.Stability
instance GHC.Classes.Ord Devops.Graph.Stability
instance GHC.Classes.Eq Devops.Graph.Stability
instance GHC.Show.Show Devops.Graph.Stability
instance GHC.Base.Functor Devops.Graph.Stream
instance GHC.Generics.Generic Devops.Graph.WantedDirection
instance GHC.Classes.Ord Devops.Graph.WantedDirection
instance GHC.Classes.Eq Devops.Graph.WantedDirection
instance GHC.Show.Show Devops.Graph.WantedDirection
instance GHC.Base.Applicative Devops.Graph.Stream

module Devops.Actions

-- | Turns up a graph concurrently.
concurrentTurnup :: OpGraph -> IO ()

-- | Turns down a graph concurrently.
concurrentTurndown :: OpGraph -> IO ()

-- | Keeps a graph up concurrently.
concurrentUpkeep :: OpGraph -> IO ()

-- | Checks the graph and returns a dot formatted graph.
checkStatuses :: OpGraph -> IO (Map OpUniqueId CheckResult)
sequentialTurnup :: OpGraph -> IO ()
sequentialTurnDown :: OpGraph -> IO ()

-- | Display a forest of operations.
display :: [Tree PreOp] -> IO ()

-- | Builds a dot-formatted representation of the graph
defaultDotify :: OpGraph -> String

-- | Same as dotify but also colorize based on statuses passed in second
--   argument.
dotifyWithStatuses :: OpGraph -> Map OpUniqueId CheckResult -> String

-- | Lists the uniq list of nodes.
listUniqNodes :: [Tree PreOp] -> IO ()


-- | Building-block methods to build a command-line tool able to inspect
--   and turnup/turndown DevOps.
module Devops.Cli
data Method
TurnUp :: Concurrency -> Method
TurnDown :: Concurrency -> Method
Upkeep :: Method
Print :: Method
Dot :: Method
CheckDot :: Method
List :: Method
data Concurrency
Concurrently :: Concurrency
Sequentially :: Concurrency
applyMethod :: [(Forest PreOp -> Forest PreOp)] -> Forest PreOp -> Method -> IO ()

-- | Simple main function for a single operation.
--   
--   You should use this <a>simpleMain</a> for simple configuration
--   binaries, more involved architectures shoul almost need a <a>App</a>
--   or <a>appMain</a>.
simpleMain :: DevOp env a -> [(Forest PreOp -> Forest PreOp)] -> [String] -> env -> IO ()

-- | A FilePath corresponding to the file with the currently-executing
--   binary.
type SelfPath = FilePath

-- | An optimization on PreOp forests.
type ForestOptimization = Forest PreOp -> Forest PreOp

-- | A builder for app that can be useful for defining an infrastructure as
--   a recursive structure where the "main entry point" of the recursion is
--   the binary itself.
data App env node
App :: [String] -> (node, Method) -> node -> Method -> [String] -> node -> SelfPath -> (node -> Method -> [String]) -> DevOp env () -> [ForestOptimization] -> node -> IO env -> App env node

-- | Parses arguments, returns a parsed architecture and a set of args for
--   the real defaulMain.
[_parseArgs] :: App env node -> [String] -> (node, Method)

-- | Reverse parse arguments, for instance when building a callback.
[_revParse] :: App env node -> node -> Method -> [String]

-- | Generates a target from the argument and the selfPath
[_target] :: App env node -> node -> SelfPath -> (node -> Method -> [String]) -> DevOp env ()

-- | Optimizations to run.
[_opts] :: App env node -> [ForestOptimization]

-- | IO to retrieve the current environment.
[_retrieveEnv] :: App env node -> node -> IO env

-- | DefaultMain for <a>App</a>.
appMain :: App env a -> IO ()

-- | Unsafely parse a <a>Method</a> from what could be a command line
--   argument.
--   
--   (NB. unsafe means this function is partial, you should use this
--   function in conjunction with <a>methodArg</a> for the reverse parse
--   and you will be fine).
appMethod :: String -> Method

-- | Serializes a <a>Method</a> to what should be a command-line argument
--   later parsed via <a>appMethod</a>.
methodArg :: Method -> String

-- | Evaluates the dependencies of a DevOp, discarding any result.
getDependenciesOnly :: env -> DevOp env a -> Forest PreOp

-- | Builds a Graph from dependencies represented as a Forest.
--   
--   Nodes with a same hash in the Forest will correspond to the same node
--   in the graph, hence, it's possible to create cycles by mistake if two
--   nodes have a same hash by mistake (this is possible if the hash does
--   not depend on all arguments to a DevOp).
graphize :: Forest PreOp -> GraphData PreOp OpUniqueId

-- | Helper to deal with App when you want to use Closures as a
--   serialization/deserialization mechanism.
--   
--   You will likely add <a>opClosureFromB64</a> in the <a>_parseArgs</a>
--   field of your <a>App</a> and <a>opClosureToB64</a> in the
--   <a>_revParse</a> field.
opClosureFromB64 :: (Typeable env, Typeable a) => ByteString -> Closure (DevOp env a)

-- | Dual to <a>opClosureFromB64</a>.
opClosureToB64 :: (Typeable env, Typeable a) => Closure (DevOp env a) -> ByteString