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


-- | Shows how to run a PostgreSQL database as a tmp proc
--   
--   An example of using tmp-proc to launch dockerized PostgreSQL in
--   integration tests.
@package tmp-proc-postgres
@version 0.5.2.2


-- | Provides an instance of <a>Proc</a> that launches <tt>postgres</tt> as
--   a <tt>tmp proc</tt>.
--   
--   The instance this module provides can be used in integration tests as
--   is.
--   
--   It's also possible to write other instances that launch
--   <tt>postgres</tt> in different ways; for those, this instance can be
--   used as a reference example.
module System.TmpProc.Docker.Postgres

-- | Provides the capability to launch a Postgres database as a <tt>tmp
--   proc</tt>.
--   
--   The constructor receives the names of the tables to be dropped on
--   <a>reset</a>.
data TmpPostgres
TmpPostgres :: [Text] -> TmpPostgres

-- | A singleton <a>HList</a> containing a <a>TmpPostgres</a>.
aProc :: HList '[TmpPostgres]

-- | An <a>HList</a> that contains the handle created from <a>aProc</a>.
aHandle :: IO (HandlesOf '[TmpPostgres])

-- | Run an action on a <a>Connectable</a> handle as a callback on its
--   <a>Conn</a>
withTmpConn :: Connectable a => ProcHandle a -> (Conn a -> IO b) -> IO b

-- | Start up processes for each <a>Proc</a> type.
startupAll :: forall (procs :: [Type]). AreProcs procs => HList procs -> IO (HandlesOf procs)

-- | Provides access to a <a>Proc</a> that has been started.
data ProcHandle a
ProcHandle :: !a -> !String -> !SvcURI -> !HostIpAddress -> ProcHandle a
[hProc] :: ProcHandle a -> !a
[hPid] :: ProcHandle a -> !String
[hUri] :: ProcHandle a -> !SvcURI
[hAddr] :: ProcHandle a -> !HostIpAddress

-- | The connection type.
type family Conn a = (conn :: Type) | conn -> a

-- | Specifies how to a get a connection to a <a>Proc</a>.
class Proc a => Connectable a where {
    
    -- | The connection type.
    type family Conn a = (conn :: Type) | conn -> a;
}

-- | Get a connection to the Proc via its <a>ProcHandle</a>.
openConn :: Connectable a => ProcHandle a -> IO (Conn a)

-- | Close a connection to a <a>Proc</a>.
closeConn :: Connectable a => Conn a -> IO ()

-- | A label used to refer to running process created from this image, e.g,
--   <i>a-postgres-db</i>
type family Name a = (labelName :: Symbol) | labelName -> a

-- | The image name of the docker image, e.g, <i>postgres:10.6</i>
type family Image a :: Symbol

-- | Specifies how to launch a temporary process using Docker.
class (KnownSymbol Image a, KnownSymbol Name a) => Proc a where {
    
    -- | The image name of the docker image, e.g, <i>postgres:10.6</i>
    type family Image a :: Symbol;
    
    -- | A label used to refer to running process created from this image, e.g,
    --   <i>a-postgres-db</i>
    type family Name a = (labelName :: Symbol) | labelName -> a;
}

-- | Additional arguments to the docker command that launches the tmp proc.
runArgs :: Proc a => [Text]

-- | Determines the service URI of the process, when applicable.
uriOf :: Proc a => HostIpAddress -> SvcURI

-- | Resets some state in a tmp proc service.
reset :: Proc a => ProcHandle a -> IO ()

-- | Checks if the tmp proc started ok.
ping :: Proc a => ProcHandle a -> IO Pinged

-- | Maximum number of pings to perform during startup.
pingCount :: Proc a => Natural

-- | Number of milliseconds between pings.
pingGap :: Proc a => Natural

-- | Indicates the result of pinging a <a>Proc</a>.
--   
--   If the ping succeeds, <a>ping</a> should return <a>OK</a>.
--   
--   <a>ping</a> should catch any exceptions that are expected when the
--   <tt><a>Proc</a>s</tt> service is not available and return
--   <a>NotOK</a>.
--   
--   <a>startupAll</a> uses <a>PingFailed</a> to report any unexpected
--   exceptions that escape <a>ping</a>.
data Pinged

-- | The service is running OK.
OK :: Pinged

-- | The service is not running.
NotOK :: Pinged

-- | Contact to the service failed unexpectedly.
PingFailed :: Text -> Pinged

-- | The IP address of the docker host.
type HostIpAddress = Text

-- | A connection string used to access the service once its running.
type SvcURI = ByteString

-- | A list of <tt><a>ProcHandle</a></tt> values.
type HandlesOf (procs :: [Type]) = HList Proc2Handle procs

-- | Defines a Heterogenous list.
data HList (a :: [Type])
[HNil] :: HList ('[] :: [Type])
[HCons] :: forall anyTy (manyTys :: [Type]). anyTy -> HList manyTys -> HList (anyTy : manyTys)
infixr 5 `HCons`
instance System.TmpProc.Docker.Proc System.TmpProc.Docker.Postgres.TmpPostgres
instance System.TmpProc.Docker.Connectable System.TmpProc.Docker.Postgres.TmpPostgres