tmp-proc-0.5.0.0: Run 'tmp' processes in integration tests
Copyright(c) 2020-2021 Tim Emiola
LicenseBSD3
MaintainerTim Emiola <adetokunbo@users.noreply.github.com>
Safe HaskellNone
LanguageHaskell2010

System.TmpProc.Docker

Description

Provides the core data types and combinators used to launch temporary (tmp) processes (procs) using docker.

tmp-proc aims to simplify integration tests that use dockerizable services.

  • Basically, tmp-proc helps launch services used in integration test on docker
  • While it's possible to write integration tests that use services hosted on docker without tmp-proc, tmp-proc aims to make writing those kind of tests easier, by providing types and combinators that take care of

    • launching services on docker
    • obtaining references to the launched service
    • cleaning up docker once the tests are finished

This module does all that via its data types:

  • A Proc specifies a docker image that provides a service and other details related to its use in tests.
  • A ProcHandle is created whenever a service specifed by a Proc is started, and is used to access and eventually terminate the running service.
  • Some Procs will also be Connectable; these specify how access the service via some Conn-ection type.
Synopsis

Proc

class (KnownSymbol (Image a), KnownSymbol (Name a)) => Proc a where Source #

Specifies how to launch a temporary process using Docker.

Minimal complete definition

uriOf, reset, ping

Associated Types

type Image a :: Symbol Source #

The image name of the docker image, e.g, postgres:10.6

type Name a = (labelName :: Symbol) | labelName -> a Source #

A label used to refer to running process created from this image, e.g, a-postgres-db

Methods

runArgs :: [Text] Source #

Additional arguments to the docker command that launches the tmp proc.

uriOf :: HostIpAddress -> SvcURI Source #

Determines the service URI of the process, when applicable.

reset :: ProcHandle a -> IO () Source #

Resets some state in a tmp proc service.

ping :: ProcHandle a -> IO Pinged Source #

Checks if the tmp proc started ok.

pingCount :: Natural Source #

Maximum number of pings to perform during startup.

pingGap :: Natural Source #

Number of milliseconds between pings.

data Pinged Source #

Indicates the result of pinging a Proc.

If the ping succeeds, ping2 should return OK.

ping2 should catch any exceptions that are expected when the Procs service is not available and return NotOK.

startupAll uses PingFailed to report any unexpected exceptions that escape ping2.

Constructors

OK

The service is running OK.

NotOK

The service is not running.

PingFailed Text

Contact to the service failed unexpectedly.

Instances

Instances details
Eq Pinged Source # 
Instance details

Defined in System.TmpProc.Docker

Methods

(==) :: Pinged -> Pinged -> Bool #

(/=) :: Pinged -> Pinged -> Bool #

Show Pinged Source # 
Instance details

Defined in System.TmpProc.Docker

class AreProcs as Source #

Declares a proof that a list of types only contains Procs.

Minimal complete definition

procProof

Instances

Instances details
AreProcs ('[] :: [Type]) Source # 
Instance details

Defined in System.TmpProc.Docker

Methods

procProof :: SomeProcs '[]

(Proc a, AreProcs as, IsAbsent a as) => AreProcs (a ': as) Source # 
Instance details

Defined in System.TmpProc.Docker

Methods

procProof :: SomeProcs (a ': as)

data SomeProcs (as :: [*]) where Source #

Used by AreProcs to prove a list of types just contains Procs.

Constructors

SomeProcsNil :: SomeProcs '[] 
SomeProcsCons :: (Proc a, IsAbsent a as) => SomeProcs as -> SomeProcs (a ': as) 

nameOf :: forall a. Proc a => a -> Text Source #

Name of a process.

startup :: forall a. Proc a => a -> IO (ProcHandle a) Source #

Starts a Proc.

It uses ping to determine if the Proc started up ok, and will fail by throwing an exception if it did not.

Returns the ProcHandle used to control the Proc once a ping has succeeded.

toPinged :: forall e a. Exception e => Proxy e -> IO a -> IO Pinged Source #

Use an action that might throw an exception as a ping.

uriOf' :: forall a. Proc a => a -> HostIpAddress -> SvcURI Source #

Simplifies use of uriOf.

runArgs' :: forall a. Proc a => a -> [Text] Source #

Simplifies use of runArgs.

ProcHandle

data ProcHandle a Source #

Provides access to a Proc that has been started.

Constructors

ProcHandle 

Fields

type family Proc2Handle (as :: [*]) = (handleTys :: [*]) | handleTys -> as where ... Source #

Converts list of types to the corresponding ProcHandle types.

Equations

Proc2Handle '[] = '[] 
Proc2Handle (a ': as) = ProcHandle a ': Proc2Handle as 

type HandlesOf procs = HList (Proc2Handle procs) Source #

A list of ProcHandle values.

startupAll :: AreProcs procs => HList procs -> IO (HandlesOf procs) Source #

Start up processes for each Proc type.

terminateAll :: AreProcs procs => HandlesOf procs -> IO () Source #

Terminate all processes owned by some ProcHandles.

withTmpProcs :: AreProcs procs => HList procs -> (HandlesOf procs -> IO b) -> IO b Source #

Set up some Procs, run an action that uses them, then terminate them.

manyNamed :: SomeNamedHandles names namedProcs someProcs sortedProcs => Proxy names -> HandlesOf someProcs -> HandlesOf namedProcs Source #

Select the named ProcHandles from an HList of ProcHandle.

handleOf :: HandleOf a procs b => Proxy a -> HandlesOf procs -> ProcHandle b Source #

Obtain the handle matching the given type from a HList of ProcHandle.

ixReset :: IxReset a procs => Proxy a -> HandlesOf procs -> IO () Source #

Resets the handle whose index is specified by the proxy type.

ixPing :: IxPing a procs => Proxy a -> HandlesOf procs -> IO Pinged Source #

Pings the handle whose index is specified by the proxy type.

ixUriOf :: IxUriOf a procs => Proxy a -> HandlesOf procs -> SvcURI Source #

Obtains the service URI of the handle whose index is specified by the proxy type.

type HasHandle aProc procs = (Proc aProc, AreProcs procs, IsInProof (ProcHandle aProc) (Proc2Handle procs)) Source #

Constraint alias used to constrain types where proxy of a Proc type looks up a value in an HList of ProcHandle.

type HasNamedHandle name a procs = (name ~ Name a, Proc a, AreProcs procs, MemberKV name (ProcHandle a) (Handle2KV (Proc2Handle procs))) Source #

Constraint alias used to constrain types where a Name looks up a type in an HList of ProcHandle.

type SomeNamedHandles names procs someProcs sortedProcs = (names ~ Proc2Name procs, ManyMemberKV (SortSymbols names) (SortHandles (Proc2Handle procs)) (Handle2KV (Proc2Handle sortedProcs)), ReorderH (SortHandles (Proc2Handle procs)) (Proc2Handle procs), ReorderH (Proc2Handle someProcs) (Proc2Handle sortedProcs), AreProcs sortedProcs, SortHandles (Proc2Handle someProcs) ~ Proc2Handle sortedProcs) Source #

Constraint alias when several Names are used to find matching types in an HList of ProcHandle.

Connectable

class Proc a => Connectable a where Source #

Specifies how to a get a connection to a Proc.

Minimal complete definition

openConn

Associated Types

type Conn a = (conn :: *) | conn -> a Source #

The connection type.

Methods

openConn :: ProcHandle a -> IO (Conn a) Source #

Get a connection to the Proc via its ProcHandle,

closeConn :: Conn a -> IO () Source #

Close a connection to a Proc,

class Connectables as Source #

Declares a proof that a list of types only contains Connectables.

Minimal complete definition

connProof

Instances

Instances details
Connectables ('[] :: [Type]) Source # 
Instance details

Defined in System.TmpProc.Docker

Methods

connProof :: SomeConns '[]

(Connectable a, Connectables as, IsAbsent a as) => Connectables (a ': as) Source # 
Instance details

Defined in System.TmpProc.Docker

Methods

connProof :: SomeConns (a ': as)

withTmpConn :: Connectable a => ProcHandle a -> (Conn a -> IO b) -> IO b Source #

Run an action on a Connectable handle as a callback on its Conn

withConnOf :: (HandleOf idx procs namedConn, Connectable namedConn) => Proxy idx -> HandlesOf procs -> (Conn namedConn -> IO b) -> IO b Source #

Builds on handleOf; gives the Conn of the ProcHandle to a callback.

openAll :: Connectables xs => HandlesOf xs -> IO (HList (ConnsOf xs)) Source #

Open all the Connectable types to corresponding Conn types.

closeAll :: Connectables procs => HList (ConnsOf procs) -> IO () Source #

Close some Connectable types.

withConns :: Connectables procs => HandlesOf procs -> (HList (ConnsOf procs) -> IO b) -> IO b Source #

Open some connections, use them in an action; close them.

withKnownConns :: (AreProcs someProcs, Connectables conns, ReorderH (Proc2Handle someProcs) (Proc2Handle conns)) => HandlesOf someProcs -> (HList (ConnsOf conns) -> IO b) -> IO b Source #

Open all known connections; use them in an action; close them.

withNamedConns :: (SomeNamedHandles names namedConns someProcs sortedProcs, Connectables namedConns) => Proxy names -> HandlesOf someProcs -> (HList (ConnsOf namedConns) -> IO b) -> IO b Source #

Open the named connections; use them in an action; close them.

Docker status

hasDocker :: IO Bool Source #

Determines if the docker daemon is accessible.

Aliases

type HostIpAddress = Text Source #

The IP address of the docker host.

type SvcURI = ByteString Source #

A connection string used to access the service once its running.

Re-exports

type family SortSymbols (xs :: [Symbol]) :: [Symbol] where ... Source #

Sort a list of type-level symbols using merge sort.

Examples

Expand
>>> :kind! SortSymbols '["xyz", "def", "abc"]
SortSymbols '["xyz", "def", "abc"] :: [Symbol]
= '["abc", "def", "xyz"]

Equations

SortSymbols '[] = '[] 
SortSymbols '[x] = '[x] 
SortSymbols '[x, y] = MergeSymbols '[x] '[y] 
SortSymbols xs = SortSymbolsStep xs (HalfOf (LengthOf xs)) 

type family HalfOf (n :: Nat) :: Nat where ... Source #

Computes the midpoint of a number.

N.B: maximum value that this works for depends on the reduction limit of the type-checker.

Examples

Expand
>>> :kind! HalfOf 99
HalfOf 99 :: Nat
= 49
>>> :kind! HalfOf 100
HalfOf 100 :: Nat
= 50

Equations

HalfOf 0 = 0 
HalfOf 1 = 1 
HalfOf 2 = 1 
HalfOf 3 = 1 
HalfOf 4 = 2 
HalfOf 5 = 2 
HalfOf 6 = 3 
HalfOf 7 = 3 
HalfOf n = HalfOfImpl n 0 n 'LT 

type family LengthOf (xs :: [k]) :: Nat where ... Source #

Counts a list, 1 element at a time.

Examples

Expand
>>> :kind! LengthOf '[1, 2, 3, 4]
LengthOf '[1, 2, 3, 4] :: Nat
= 4

Equations

LengthOf '[] = 0 
LengthOf (x ': xs) = 1 + LengthOf xs 

type family Drop (xs :: [k]) (n :: Nat) :: [k] where ... Source #

Drops 1 element at a time until the the dropped target is reached.

Examples

Expand
>>> :kind! Drop '[1, 2, 3, 4] 2
Drop '[1, 2, 3, 4] 2 :: [Nat]
= '[3, 4]
>>> :kind! Drop '[1] 2
Drop '[1] 2 :: [Nat]
= '[]

Equations

Drop '[] n = '[] 
Drop xs 0 = xs 
Drop (x ': xs) n = Drop xs (n - 1) 

type family Take (xs :: [k]) (n :: Nat) :: [k] where ... Source #

Takes 1 element at a time from a list until the desired length is reached.

Examples

Expand
>>> :kind! Take '[1, 2, 3, 4] 2
Take '[1, 2, 3, 4] 2 :: [Nat]
= '[1, 2]

Equations

Take '[] n = '[] 
Take xs 0 = '[] 
Take (x ': xs) n = x ': Take xs (n - 1) 

class IsInProof t (tys :: [Type]) Source #

Generate proof instances of IsIn.

Minimal complete definition

provedIsIn

Instances

Instances details
IsInProof t tys => IsInProof t (a ': tys) Source # 
Instance details

Defined in System.TmpProc.TypeLevel

Methods

provedIsIn :: IsIn t (a ': tys)

IsInProof t (t ': tys) Source # 
Instance details

Defined in System.TmpProc.TypeLevel

Methods

provedIsIn :: IsIn t (t ': tys)

class ReorderH xs ys where Source #

Allows reordering of similar HLists.

Examples

Expand
>>> hReorder @_ @'[Bool, Int] ('c' &: (3 :: Int) &: True &: (3.1 :: Double) &: HNil)
True &: 3 &: HNil
>>> hReorder @_ @'[Double, Bool, Int] ('c' &: (3 :: Int) &: True &: (3.1 :: Double) &: HNil)
3.1 &: True &: 3 &: HNil

Methods

hReorder :: HList xs -> HList ys Source #

Instances

Instances details
ReorderH xs ('[] :: [Type]) Source # 
Instance details

Defined in System.TmpProc.TypeLevel

Methods

hReorder :: HList xs -> HList '[] Source #

(IsInProof y xs, ReorderH xs ys) => ReorderH xs (y ': ys) Source # 
Instance details

Defined in System.TmpProc.TypeLevel

Methods

hReorder :: HList xs -> HList (y ': ys) Source #

class ManyMemberKV (ks :: [Symbol]) (ts :: [*]) (kvs :: [*]) Source #

Generate proof instances of LookupMany.

Minimal complete definition

manyProof

Instances

Instances details
ManyMemberKV ks ts kvs => ManyMemberKV ks ts (KV ok ot ': kvs) Source # 
Instance details

Defined in System.TmpProc.TypeLevel

Methods

manyProof :: LookupMany ks ts (KV ok ot ': kvs) Source #

ManyMemberKV ks ts kvs => ManyMemberKV (k ': ks) (t ': ts) (KV k t ': kvs) Source # 
Instance details

Defined in System.TmpProc.TypeLevel

Methods

manyProof :: LookupMany (k ': ks) (t ': ts) (KV k t ': kvs) Source #

ManyMemberKV '[k] '[t] (KV k t ': ks) Source # 
Instance details

Defined in System.TmpProc.TypeLevel

Methods

manyProof :: LookupMany '[k] '[t] (KV k t ': ks) Source #

class MemberKV (k :: Symbol) (t :: *) (xs :: [*]) Source #

Generate proof instances of LookupKV.

Minimal complete definition

lookupProof

Instances

Instances details
MemberKV k t kvs => MemberKV k t (KV ok ot ': kvs) Source # 
Instance details

Defined in System.TmpProc.TypeLevel

Methods

lookupProof :: LookupKV k t (KV ok ot ': kvs) Source #

MemberKV k t (KV k t ': kvs) Source # 
Instance details

Defined in System.TmpProc.TypeLevel

Methods

lookupProof :: LookupKV k t (KV k t ': kvs) Source #

MemberKV k t '[KV k t] Source # 
Instance details

Defined in System.TmpProc.TypeLevel

Methods

lookupProof :: LookupKV k t '[KV k t] Source #

type family IsAbsent e r :: Constraint where ... Source #

A constraint that confirms that a type is not present in a type-level list.

Equations

IsAbsent e '[] = () 
IsAbsent e (e ': _) = TypeError (NotAbsentErr e) 
IsAbsent e (e' ': tail) = IsAbsent e tail 

data KV :: Symbol -> * -> * where Source #

Use a type-level symbol as key type that indexes a value type.

Constructors

V :: a -> KV s a 

Instances

Instances details
ManyMemberKV ks ts kvs => ManyMemberKV ks ts (KV ok ot ': kvs) Source # 
Instance details

Defined in System.TmpProc.TypeLevel

Methods

manyProof :: LookupMany ks ts (KV ok ot ': kvs) Source #

MemberKV k t kvs => MemberKV k t (KV ok ot ': kvs) Source # 
Instance details

Defined in System.TmpProc.TypeLevel

Methods

lookupProof :: LookupKV k t (KV ok ot ': kvs) Source #

MemberKV k t (KV k t ': kvs) Source # 
Instance details

Defined in System.TmpProc.TypeLevel

Methods

lookupProof :: LookupKV k t (KV k t ': kvs) Source #

MemberKV k t '[KV k t] Source # 
Instance details

Defined in System.TmpProc.TypeLevel

Methods

lookupProof :: LookupKV k t '[KV k t] Source #

ManyMemberKV ks ts kvs => ManyMemberKV (k ': ks) (t ': ts) (KV k t ': kvs) Source # 
Instance details

Defined in System.TmpProc.TypeLevel

Methods

manyProof :: LookupMany (k ': ks) (t ': ts) (KV k t ': kvs) Source #

ManyMemberKV '[k] '[t] (KV k t ': ks) Source # 
Instance details

Defined in System.TmpProc.TypeLevel

Methods

manyProof :: LookupMany '[k] '[t] (KV k t ': ks) Source #

data HList :: [*] -> * where Source #

Defines a Heterogenous list.

Constructors

HNil :: HList '[] 
HCons :: anyTy -> HList manyTys -> HList (anyTy ': manyTys) infixr 5 

Instances

Instances details
(Eq x, Eq (HList xs)) => Eq (HList (x ': xs)) Source # 
Instance details

Defined in System.TmpProc.TypeLevel

Methods

(==) :: HList (x ': xs) -> HList (x ': xs) -> Bool #

(/=) :: HList (x ': xs) -> HList (x ': xs) -> Bool #

Eq (HList ('[] :: [Type])) Source # 
Instance details

Defined in System.TmpProc.TypeLevel

Methods

(==) :: HList '[] -> HList '[] -> Bool #

(/=) :: HList '[] -> HList '[] -> Bool #

(Show x, Show (HList xs)) => Show (HList (x ': xs)) Source # 
Instance details

Defined in System.TmpProc.TypeLevel

Methods

showsPrec :: Int -> HList (x ': xs) -> ShowS #

show :: HList (x ': xs) -> String #

showList :: [HList (x ': xs)] -> ShowS #

Show (HList ('[] :: [Type])) Source # 
Instance details

Defined in System.TmpProc.TypeLevel

Methods

showsPrec :: Int -> HList '[] -> ShowS #

show :: HList '[] -> String #

showList :: [HList '[]] -> ShowS #

hOf :: forall y xs. IsInProof y xs => Proxy y -> HList xs -> y Source #

Get an item in an HList given its type.

(&:) :: x -> HList xs -> HList (x ': xs) infixr 5 Source #

An infix alias for HCons.

select :: forall k t xs. MemberKV k t xs => HList xs -> t Source #

Select an item from an HList of KVs by key.

N.B Returns the first item. It assumes the keys in the KV HList are unique. TODO: enforce this rule using a constraint.

Examples

Expand
>>> select @"d" @Double  @'[KV "b" Bool, KV "d" Double] (V True &:  V (3.1 :: Double) &: HNil)
3.1

selectMany :: forall ks ts xs. ManyMemberKV ks ts xs => HList xs -> HList ts Source #

Select items with specified keys from an HList of KVs by key.

N.B. this this is an internal function.

The keys must be provided in the same order as they occur in the HList, any other order will likely result in an compiler error.

Examples

Expand
>>> selectMany @'["b"] @'[Bool] @'[KV "b" Bool, KV "d" Double] (V True &:  V (3.1 :: Double) &: HNil)
True &: HNil