System.TmpProc.Docker

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.

Proc

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

Specifies how to launch a temporary process using Docker.

Minimal complete definition

uriOf, reset, ping

Associated Types

type Image a :: Symbol

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

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

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

Methods

runArgs :: [Text]

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

uriOf :: HostIpAddress -> SvcURI

Determines the service URI of the process, when applicable.

reset :: ProcHandle a -> IO ()

Resets some state in a tmp proc service.

ping :: ProcHandle a -> IO Pinged

Checks if the tmp proc started ok.

pingCount :: Natural

Maximum number of pings to perform during startup.

pingGap :: Natural

Number of milliseconds between pings.

data Pinged

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

Eq Pinged

Defined in System.TmpProc.Docker

Methods

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

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

Show Pinged

Defined in System.TmpProc.Docker

Methods

showsPrec :: Int -> Pinged -> ShowS

show :: Pinged -> String

showList :: [Pinged] -> ShowS

class AreProcs as

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

Minimal complete definition

procProof

Instances

AreProcs ('[] :: [Type])

Defined in System.TmpProc.Docker

Methods

procProof :: SomeProcs '[]

(Proc a, AreProcs as, IsAbsent a as) => AreProcs (a ': as)

Defined in System.TmpProc.Docker

Methods

procProof :: SomeProcs (a ': as)

data SomeProcs (as :: [*]) where

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

Name of a process.

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

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

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

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

Simplifies use of uriOf.

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

Simplifies use of runArgs.

ProcHandle

data ProcHandle a

Provides access to a Proc that has been started.

Constructors

ProcHandle

Fields

• hProc :: !a
• hPid :: !String
• hUri :: !SvcURI
• hAddr :: !HostIpAddress

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

Converts list of types to the corresponding ProcHandle types.

Equations

Proc2Handle '[] = '[]

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

type HandlesOf procs = HList (Proc2Handle procs)

A list of ProcHandle values.

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

Start up processes for each Proc type.

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

Terminate all processes owned by some ProcHandles.

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

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

Select the named ProcHandles from an HList of ProcHandle.

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

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

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

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

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

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

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

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))

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)))

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)

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

Connectable

class Proc a => Connectable a where

Specifies how to a get a connection to a Proc.

Minimal complete definition

openConn

Associated Types

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

The connection type.

Methods

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

Get a connection to the Proc via its ProcHandle,

closeConn :: Conn a -> IO ()

Close a connection to a Proc,

class Connectables as

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

Minimal complete definition

connProof

Instances

Connectables ('[] :: [Type])

Defined in System.TmpProc.Docker

Methods

connProof :: SomeConns '[]

(Connectable a, Connectables as, IsAbsent a as) => Connectables (a ': as)

Defined in System.TmpProc.Docker

Methods

connProof :: SomeConns (a ': as)

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

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

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

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

Open all the Connectable types to corresponding Conn types.

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

Close some Connectable types.

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

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

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

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

Docker status

hasDocker :: IO Bool

Determines if the docker daemon is accessible.

Aliases

type HostIpAddress = Text

The IP address of the docker host.

type SvcURI = ByteString

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

Re-exports

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

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

Examples

>>> :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 ...

Computes the midpoint of a number.

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

Examples

>>> :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 ...

Counts a list, 1 element at a time.

Examples

>>> :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 ...

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

Examples

>>> :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 ...

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

Examples

>>> :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])

Generate proof instances of IsIn.

Minimal complete definition

provedIsIn

Instances

IsInProof t tys => IsInProof t (a ': tys)

Defined in System.TmpProc.TypeLevel

Methods

provedIsIn :: IsIn t (a ': tys)

IsInProof t (t ': tys)

Defined in System.TmpProc.TypeLevel

Methods

provedIsIn :: IsIn t (t ': tys)

class ReorderH xs ys where

Allows reordering of similar HLists.

Examples

>>> 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

Instances

ReorderH xs ('[] :: [Type])

Defined in System.TmpProc.TypeLevel

Methods

hReorder :: HList xs -> HList '[]

(IsInProof y xs, ReorderH xs ys) => ReorderH xs (y ': ys)

Defined in System.TmpProc.TypeLevel

Methods

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

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

Generate proof instances of LookupMany.

Minimal complete definition

manyProof

Instances

ManyMemberKV ks ts kvs => ManyMemberKV ks ts (KV ok ot ': kvs)

Defined in System.TmpProc.TypeLevel

Methods

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

ManyMemberKV ks ts kvs => ManyMemberKV (k ': ks) (t ': ts) (KV k t ': kvs)

Defined in System.TmpProc.TypeLevel

Methods

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

ManyMemberKV '[k] '[t] (KV k t ': ks)

Defined in System.TmpProc.TypeLevel

Methods

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

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

Generate proof instances of LookupKV.

Minimal complete definition

lookupProof

Instances

MemberKV k t kvs => MemberKV k t (KV ok ot ': kvs)

Defined in System.TmpProc.TypeLevel

Methods

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

MemberKV k t (KV k t ': kvs)

Defined in System.TmpProc.TypeLevel

Methods

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

MemberKV k t '[KV k t]

Defined in System.TmpProc.TypeLevel

Methods

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

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

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

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

Constructors

V :: a -> KV s a

Instances

ManyMemberKV ks ts kvs => ManyMemberKV ks ts (KV ok ot ': kvs)

Defined in System.TmpProc.TypeLevel

Methods

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

MemberKV k t kvs => MemberKV k t (KV ok ot ': kvs)

Defined in System.TmpProc.TypeLevel

Methods

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

MemberKV k t (KV k t ': kvs)

Defined in System.TmpProc.TypeLevel

Methods

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

MemberKV k t '[KV k t]

Defined in System.TmpProc.TypeLevel

Methods

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

ManyMemberKV ks ts kvs => ManyMemberKV (k ': ks) (t ': ts) (KV k t ': kvs)

Defined in System.TmpProc.TypeLevel

Methods

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

ManyMemberKV '[k] '[t] (KV k t ': ks)

Defined in System.TmpProc.TypeLevel

Methods

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

data HList :: [*] -> * where

Defines a Heterogenous list.

Constructors

HNil :: HList '[]

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

Instances

(Eq x, Eq (HList xs)) => Eq (HList (x ': xs))

Defined in System.TmpProc.TypeLevel

Methods

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

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

Eq (HList ('[] :: [Type]))

Defined in System.TmpProc.TypeLevel

Methods

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

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

(Show x, Show (HList xs)) => Show (HList (x ': xs))

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]))

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

Get an item in an HList given its type.

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

An infix alias for HCons.

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

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

>>> 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

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

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