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


-- | Docker containers for your integration tests.
--   
--   testcontainers is a Haskell library that provides a friendly API to
--   run Docker containers. It is designed to create a runtime environment
--   to use during your integration tests
@package testcontainers
@version 0.1.0.0

module TestContainers.Docker

-- | Docker related functionality is parameterized over this <a>Monad</a>.
type MonadDocker m = (MonadIO m, MonadMask m, MonadThrow m, MonadCatch m, MonadResource m)

-- | A tag to a Docker image.
type ImageTag = Text

-- | Handle to a Docker image.
data Image

-- | The image tag assigned by Docker. Uniquely identifies an <a>Image</a>
--   within Docker.
imageTag :: Image -> ImageTag

-- | Identifies a container within the Docker runtime. Assigned by
--   <tt>docker run</tt>.
type ContainerId = Text

-- | Handle to a Docker container.
data Container

-- | Returns the id of the container.
containerId :: Container -> ContainerId

-- | Returns the underlying image of the container.
containerImage :: Container -> Image

-- | Looks up the ip address of the container.
containerIp :: Container -> Text

-- | Looks up an exposed port on the host.
containerPort :: Container -> Int -> Int

-- | Returns the internal release key used for safely shutting down the
--   container. Use this with care. This function is considered an internal
--   detail.
containerReleaseKey :: Container -> ReleaseKey

-- | A description of how to build an <a>Image</a>.
data ToImage

-- | Get an <a>Image</a> from a tag.
fromTag :: ImageTag -> ToImage

-- | Build the image from a build path and an optional path to the
--   Dockerfile (default is Dockerfile)
fromBuildContext :: FilePath -> Maybe FilePath -> ToImage

-- | Build a contextless image only from a Dockerfile passed as
--   <a>Text</a>.
fromDockerfile :: Text -> ToImage

-- | Build the <a>Image</a> referred to by the argument. If the
--   construction of the image is expensive (e.g. a call to
--   <a>fromBuildContext</a>) we don't want to repeatedly build the image.
--   Instead, <a>build</a> can be used to execute the underlying Docker
--   build once and re-use the resulting <a>Image</a>.
build :: MonadDocker m => ToImage -> m ToImage

-- | Failing to interact with Docker results in this exception being
--   thrown.
data DockerException
DockerException :: ExitCode -> [Text] -> Text -> DockerException

-- | Exit code of the underlying Docker process.
[$sel:exitCode:DockerException] :: DockerException -> ExitCode

-- | Arguments that were passed to Docker.
[$sel:args:DockerException] :: DockerException -> [Text]

-- | Docker's STDERR output.
[$sel:stderr:DockerException] :: DockerException -> Text
InspectUnknownContainerId :: ContainerId -> DockerException

-- | Id of the <a>Container</a> that we tried to lookup the port mapping.
[$sel:id:DockerException] :: DockerException -> ContainerId
InspectOutputInvalidJSON :: ContainerId -> DockerException

-- | Id of the <a>Container</a> that we tried to lookup the port mapping.
[$sel:id:DockerException] :: DockerException -> ContainerId
InspectOutputUnexpected :: ContainerId -> DockerException

-- | Id of the <a>Container</a> that we tried to lookup the port mapping.
[$sel:id:DockerException] :: DockerException -> ContainerId
UnknownPortMapping :: ContainerId -> Text -> DockerException

-- | Id of the <a>Container</a> that we tried to lookup the port mapping.
[$sel:id:DockerException] :: DockerException -> ContainerId

-- | Textual representation of port mapping we were trying to look up.
[$sel:port:DockerException] :: DockerException -> Text

-- | Parameters for a running a Docker container.
data ContainerRequest

-- | Default <a>ContainerRequest</a>. Used as base for every Docker
--   container.
containerRequest :: ToImage -> ContainerRequest

-- | Set the name of a Docker container.
setName :: Text -> ContainerRequest -> ContainerRequest

-- | The command to execute inside the Docker container.
setCmd :: [Text] -> ContainerRequest -> ContainerRequest

-- | Wether to remove the container once exited.
setRm :: Bool -> ContainerRequest -> ContainerRequest

-- | Set the environment for the container.
setEnv :: [(Text, Text)] -> ContainerRequest -> ContainerRequest

-- | Set link on the container.
setLink :: [ContainerId] -> ContainerRequest -> ContainerRequest

-- | Set exposed ports on the container.
--   
--   Example:
--   
--   <pre>
--   redis
--       <a>&amp;</a> <a>setExpose</a> [ 6379 ]
--   </pre>
setExpose :: [Int] -> ContainerRequest -> ContainerRequest

-- | Set the waiting strategy on the container.
setWaitingFor :: WaitUntilReady -> ContainerRequest -> ContainerRequest

-- | Runs a Docker container from an <a>Image</a> and
--   <a>ContainerRequest</a>. A finalizer is registered so that the
--   container is aways stopped when it goes out of scope.
run :: MonadDocker m => ContainerRequest -> m Container

-- | The parsed JSON output of docker inspect command.
type InspectOutput = Value

-- | Runs the `docker inspect` command. Memoizes the result.
inspect :: MonadDocker m => Container -> m InspectOutput

-- | Stops a Docker container.
stop :: MonadDocker m => Container -> m ()

-- | Kills a Docker container.
kill :: MonadDocker m => Container -> m ()

-- | Remove a Docker container.
rm :: MonadDocker m => Container -> m ()

-- | Get the logs from a Docker container.
withLogs :: forall m a. MonadDocker m => Container -> (Handle -> Handle -> m a) -> m a

-- | A strategy that describes how to asses readiness of a
--   <a>Container</a>. Allows Users to plug in their definition of
--   readiness.
data WaitUntilReady

-- | Blocks until the container is ready. <a>waitUntilReady</a> might throw
--   exceptions depending on the used <a>WaitUntilReady</a> on the
--   container.
waitUntilReady :: MonadDocker m => Container -> WaitUntilReady -> m ()

-- | The exception thrown by <a>waitUntilTimeout</a>.
newtype TimeoutException
TimeoutException :: ContainerId -> TimeoutException

-- | The id of the underlying container that was not ready in time.
[$sel:id:TimeoutException] :: TimeoutException -> ContainerId

-- | <tt>waitUntilTimeout n waitUntilReady</tt> waits <tt>n</tt> seconds
--   for the container to be ready. If the container is not ready by then a
--   <a>TimeoutException</a> will be thrown.
waitUntilTimeout :: Int -> WaitUntilReady -> WaitUntilReady

-- | A low-level primitive that allows scanning the logs for specific log
--   lines that indicate readiness of a container.
--   
--   The <a>Handle</a>s passed to the function argument represent
--   <tt>stdout</tt> and <tt>stderr</tt> of the container.
waitWithLogs :: (Container -> Handle -> Handle -> IO ()) -> WaitUntilReady

-- | The exception thrown by <tt>waitForLine</tt> in case the expected log
--   line wasn't found.
newtype UnexpectedEndOfPipe
UnexpectedEndOfPipe :: ContainerId -> UnexpectedEndOfPipe

-- | The id of the underlying container.
[$sel:id:UnexpectedEndOfPipe] :: UnexpectedEndOfPipe -> ContainerId

-- | A data type indicating which pipe to scan for a specific log line.
data Pipe

-- | Refer to logs on STDOUT.
Stdout :: Pipe

-- | Refer to logs on STDERR.
Stderr :: Pipe

-- | Waits for a specific line to occur in the logs. Throws a
--   <a>UnexpectedEndOfPipe</a> exception in case the desired line can not
--   be found on the logs.
--   
--   Say you want to find "Ready to accept connections" in the logs on
--   Stdout try:
--   
--   <pre>
--   wairForLogLine Stdout ("Ready to accept connections" `<a>isInfixOf</a>`)
--   </pre>
waitForLogLine :: Pipe -> (Text -> Bool) -> WaitUntilReady

-- | Waits until the port of a container is ready to accept connections.
--   This combinator should always be used with <a>waitUntilTimeout</a>.
waitUntilMappedPortReachable :: Int -> WaitUntilReady

-- | Convenient alias for <tt>ResourceT IO</tt>.
type ResIO = ResourceT IO

-- | Unwrap a <a>ResourceT</a> transformer, and call all registered release
--   actions.
--   
--   Note that there is some reference counting involved due to
--   <a>resourceForkIO</a>. If multiple threads are sharing the same
--   collection of resources, only the last call to <tt>runResourceT</tt>
--   will deallocate the resources.
--   
--   <i>NOTE</i> Since version 1.2.0, this function will throw a
--   <a>ResourceCleanupException</a> if any of the cleanup functions throw
--   an exception.
runResourceT :: MonadUnliftIO m => ResourceT m a -> m a

-- | <a>&amp;</a> is a reverse application operator. This provides
--   notational convenience. Its precedence is one higher than that of the
--   forward application operator <a>$</a>, which allows <a>&amp;</a> to be
--   nested in <a>$</a>.
--   
--   <pre>
--   &gt;&gt;&gt; 5 &amp; (+1) &amp; show
--   "6"
--   </pre>
(&) :: () => a -> (a -> b) -> b
infixl 1 &
instance GHC.Show.Show TestContainers.Docker.Image
instance GHC.Classes.Eq TestContainers.Docker.Image
instance GHC.Show.Show TestContainers.Docker.Pipe
instance GHC.Classes.Ord TestContainers.Docker.Pipe
instance GHC.Classes.Eq TestContainers.Docker.Pipe
instance GHC.Show.Show TestContainers.Docker.TimeoutException
instance GHC.Classes.Eq TestContainers.Docker.TimeoutException
instance GHC.Show.Show TestContainers.Docker.UnexpectedEndOfPipe
instance GHC.Classes.Eq TestContainers.Docker.UnexpectedEndOfPipe
instance GHC.Show.Show TestContainers.Docker.DockerException
instance GHC.Classes.Eq TestContainers.Docker.DockerException
instance GHC.Exception.Type.Exception TestContainers.Docker.TimeoutException
instance GHC.Exception.Type.Exception TestContainers.Docker.UnexpectedEndOfPipe
instance GHC.Exception.Type.Exception TestContainers.Docker.DockerException

module TestContainers.Image

-- | Image for Redis database.
--   
--   <pre>
--   redis = fromTag "redis:5.0"
--   </pre>
redis :: ToImage

-- | Image for Mongo database.
--   
--   <pre>
--   mongo = Tag "mongo:4.0.17"
--   </pre>
mongo :: ToImage

-- | Handle to a Docker image.
data Image

-- | A description of how to build an <a>Image</a>.
data ToImage

-- | Build the <a>Image</a> referred to by the argument. If the
--   construction of the image is expensive (e.g. a call to
--   <a>fromBuildContext</a>) we don't want to repeatedly build the image.
--   Instead, <a>build</a> can be used to execute the underlying Docker
--   build once and re-use the resulting <a>Image</a>.
build :: MonadDocker m => ToImage -> m ToImage

-- | Get an <a>Image</a> from a tag.
fromTag :: ImageTag -> ToImage

-- | Build the image from a build path and an optional path to the
--   Dockerfile (default is Dockerfile)
fromBuildContext :: FilePath -> Maybe FilePath -> ToImage

-- | Build a contextless image only from a Dockerfile passed as
--   <a>Text</a>.
fromDockerfile :: Text -> ToImage

module TestContainers

-- | <a>&amp;</a> is a reverse application operator. This provides
--   notational convenience. Its precedence is one higher than that of the
--   forward application operator <a>$</a>, which allows <a>&amp;</a> to be
--   nested in <a>$</a>.
--   
--   <pre>
--   &gt;&gt;&gt; 5 &amp; (+1) &amp; show
--   "6"
--   </pre>
(&) :: () => a -> (a -> b) -> b
infixl 1 &

-- | Unwrap a <a>ResourceT</a> transformer, and call all registered release
--   actions.
--   
--   Note that there is some reference counting involved due to
--   <a>resourceForkIO</a>. If multiple threads are sharing the same
--   collection of resources, only the last call to <tt>runResourceT</tt>
--   will deallocate the resources.
--   
--   <i>NOTE</i> Since version 1.2.0, this function will throw a
--   <a>ResourceCleanupException</a> if any of the cleanup functions throw
--   an exception.
runResourceT :: MonadUnliftIO m => ResourceT m a -> m a

-- | Convenient alias for <tt>ResourceT IO</tt>.
type ResIO = ResourceT IO

-- | The parsed JSON output of docker inspect command.
type InspectOutput = Value

-- | Handle to a Docker container.
data Container

-- | Handle to a Docker image.
data Image

-- | A data type indicating which pipe to scan for a specific log line.
data Pipe

-- | Refer to logs on STDOUT.
Stdout :: Pipe

-- | Refer to logs on STDERR.
Stderr :: Pipe

-- | The exception thrown by <a>waitUntilTimeout</a>.
newtype TimeoutException
TimeoutException :: ContainerId -> TimeoutException

-- | The id of the underlying container that was not ready in time.
[$sel:id:TimeoutException] :: TimeoutException -> ContainerId

-- | The exception thrown by <tt>waitForLine</tt> in case the expected log
--   line wasn't found.
newtype UnexpectedEndOfPipe
UnexpectedEndOfPipe :: ContainerId -> UnexpectedEndOfPipe

-- | The id of the underlying container.
[$sel:id:UnexpectedEndOfPipe] :: UnexpectedEndOfPipe -> ContainerId

-- | A strategy that describes how to asses readiness of a
--   <a>Container</a>. Allows Users to plug in their definition of
--   readiness.
data WaitUntilReady

-- | Identifies a container within the Docker runtime. Assigned by
--   <tt>docker run</tt>.
type ContainerId = Text

-- | A description of how to build an <a>Image</a>.
data ToImage

-- | A tag to a Docker image.
type ImageTag = Text

-- | Parameters for a running a Docker container.
data ContainerRequest

-- | Docker related functionality is parameterized over this <a>Monad</a>.
type MonadDocker m = (MonadIO m, MonadMask m, MonadThrow m, MonadCatch m, MonadResource m)

-- | Failing to interact with Docker results in this exception being
--   thrown.
data DockerException
DockerException :: ExitCode -> [Text] -> Text -> DockerException

-- | Exit code of the underlying Docker process.
[$sel:exitCode:DockerException] :: DockerException -> ExitCode

-- | Arguments that were passed to Docker.
[$sel:args:DockerException] :: DockerException -> [Text]

-- | Docker's STDERR output.
[$sel:stderr:DockerException] :: DockerException -> Text
InspectUnknownContainerId :: ContainerId -> DockerException

-- | Id of the <a>Container</a> that we tried to lookup the port mapping.
[$sel:id:DockerException] :: DockerException -> ContainerId
InspectOutputInvalidJSON :: ContainerId -> DockerException

-- | Id of the <a>Container</a> that we tried to lookup the port mapping.
[$sel:id:DockerException] :: DockerException -> ContainerId
InspectOutputUnexpected :: ContainerId -> DockerException

-- | Id of the <a>Container</a> that we tried to lookup the port mapping.
[$sel:id:DockerException] :: DockerException -> ContainerId
UnknownPortMapping :: ContainerId -> Text -> DockerException

-- | Id of the <a>Container</a> that we tried to lookup the port mapping.
[$sel:id:DockerException] :: DockerException -> ContainerId

-- | Textual representation of port mapping we were trying to look up.
[$sel:port:DockerException] :: DockerException -> Text

-- | Default <a>ContainerRequest</a>. Used as base for every Docker
--   container.
containerRequest :: ToImage -> ContainerRequest

-- | Set the name of a Docker container.
setName :: Text -> ContainerRequest -> ContainerRequest

-- | The command to execute inside the Docker container.
setCmd :: [Text] -> ContainerRequest -> ContainerRequest

-- | Wether to remove the container once exited.
setRm :: Bool -> ContainerRequest -> ContainerRequest

-- | Set the environment for the container.
setEnv :: [(Text, Text)] -> ContainerRequest -> ContainerRequest

-- | Set link on the container.
setLink :: [ContainerId] -> ContainerRequest -> ContainerRequest

-- | Set exposed ports on the container.
--   
--   Example:
--   
--   <pre>
--   redis
--       <a>&amp;</a> <a>setExpose</a> [ 6379 ]
--   </pre>
setExpose :: [Int] -> ContainerRequest -> ContainerRequest

-- | Set the waiting strategy on the container.
setWaitingFor :: WaitUntilReady -> ContainerRequest -> ContainerRequest

-- | Runs a Docker container from an <a>Image</a> and
--   <a>ContainerRequest</a>. A finalizer is registered so that the
--   container is aways stopped when it goes out of scope.
run :: MonadDocker m => ContainerRequest -> m Container

-- | Kills a Docker container.
kill :: MonadDocker m => Container -> m ()

-- | Stops a Docker container.
stop :: MonadDocker m => Container -> m ()

-- | Remove a Docker container.
rm :: MonadDocker m => Container -> m ()

-- | Get the logs from a Docker container.
withLogs :: forall m a. MonadDocker m => Container -> (Handle -> Handle -> m a) -> m a

-- | Build the <a>Image</a> referred to by the argument. If the
--   construction of the image is expensive (e.g. a call to
--   <a>fromBuildContext</a>) we don't want to repeatedly build the image.
--   Instead, <a>build</a> can be used to execute the underlying Docker
--   build once and re-use the resulting <a>Image</a>.
build :: MonadDocker m => ToImage -> m ToImage

-- | Get an <a>Image</a> from a tag.
fromTag :: ImageTag -> ToImage

-- | Build the image from a build path and an optional path to the
--   Dockerfile (default is Dockerfile)
fromBuildContext :: FilePath -> Maybe FilePath -> ToImage

-- | Build a contextless image only from a Dockerfile passed as
--   <a>Text</a>.
fromDockerfile :: Text -> ToImage

-- | <tt>waitUntilTimeout n waitUntilReady</tt> waits <tt>n</tt> seconds
--   for the container to be ready. If the container is not ready by then a
--   <a>TimeoutException</a> will be thrown.
waitUntilTimeout :: Int -> WaitUntilReady -> WaitUntilReady

-- | Waits until the port of a container is ready to accept connections.
--   This combinator should always be used with <a>waitUntilTimeout</a>.
waitUntilMappedPortReachable :: Int -> WaitUntilReady

-- | A low-level primitive that allows scanning the logs for specific log
--   lines that indicate readiness of a container.
--   
--   The <a>Handle</a>s passed to the function argument represent
--   <tt>stdout</tt> and <tt>stderr</tt> of the container.
waitWithLogs :: (Container -> Handle -> Handle -> IO ()) -> WaitUntilReady

-- | Waits for a specific line to occur in the logs. Throws a
--   <a>UnexpectedEndOfPipe</a> exception in case the desired line can not
--   be found on the logs.
--   
--   Say you want to find "Ready to accept connections" in the logs on
--   Stdout try:
--   
--   <pre>
--   wairForLogLine Stdout ("Ready to accept connections" `<a>isInfixOf</a>`)
--   </pre>
waitForLogLine :: Pipe -> (Text -> Bool) -> WaitUntilReady

-- | Blocks until the container is ready. <a>waitUntilReady</a> might throw
--   exceptions depending on the used <a>WaitUntilReady</a> on the
--   container.
waitUntilReady :: MonadDocker m => Container -> WaitUntilReady -> m ()

-- | The image tag assigned by Docker. Uniquely identifies an <a>Image</a>
--   within Docker.
imageTag :: Image -> ImageTag

-- | Returns the id of the container.
containerId :: Container -> ContainerId

-- | Returns the underlying image of the container.
containerImage :: Container -> Image

-- | Returns the internal release key used for safely shutting down the
--   container. Use this with care. This function is considered an internal
--   detail.
containerReleaseKey :: Container -> ReleaseKey

-- | Looks up the ip address of the container.
containerIp :: Container -> Text

-- | Looks up an exposed port on the host.
containerPort :: Container -> Int -> Int

-- | Runs the `docker inspect` command. Memoizes the result.
inspect :: MonadDocker m => Container -> m InspectOutput

-- | Image for Redis database.
--   
--   <pre>
--   redis = fromTag "redis:5.0"
--   </pre>
redis :: ToImage

-- | Image for Mongo database.
--   
--   <pre>
--   mongo = Tag "mongo:4.0.17"
--   </pre>
mongo :: ToImage

module TestContainers.Hspec

-- | Allow <a>Spec</a> to depend on Docker containers. Hspec takes care of
--   initialization and de-initialization of the containers.
--   
--   <pre>
--   containers :: MonadDocker m =&gt; m Boolean
--   containers = do
--     _redis &lt;- TestContainers.run $ TestContainers.containerRequest TestContainers.redis
--     _kafka &lt;- TestContainers.run $ TestContainers.containerRequest TestContainers.kafka
--     pure True
--   
--   example :: Spec
--   example =
--     around (withContainers containers) $ describe "Example tests"
--       it "first test" $ \isBoolean -&gt; do
--         isBoolean <tt>shouldBe</tt> True
--   </pre>
--   
--   <a>withContainers</a> allows you naturally scope the handling of
--   containers for your tests.
withContainers :: forall a. (forall m. MonadDocker m => m a) -> (a -> IO ()) -> IO ()

module TestContainers.Tasty

-- | Allow <a>TestTree</a> to depend on Docker containers. Tasty takes care
--   of initialization and de-initialization of the containers.
--   
--   <pre>
--   containers :: MonadDocker m =&gt; m ()
--   containers = do
--     _redis &lt;- TestContainers.run $ TestContainers.containerRequest TestContainers.redis
--     _kafka &lt;- TestContainers.run $ TestContainers.containerRequest TestContainers.kafka
--     pure ()
--   
--   example :: TestTree
--   example =
--     withContainers containers $ \runContainers -&gt; testGroup "Example tests"
--       [
--         testCase "first test" $ do
--           -- Actually runs the container.
--           runContainers
--         testCase "second test" $ do
--           -- Start containers. Tasty makes sure to only initialize once as
--           --  `first test` might already have started them.
--           runContainers
--       ]
--   </pre>
--   
--   <a>withContainers</a> allows you naturally scope the handling of
--   containers for your tests.
withContainers :: forall a. (forall m. MonadDocker m => m a) -> (IO a -> TestTree) -> TestTree