@@ -96,6 +96,7 @@ import GHC.Generics (Generic)
9696import Prelude hiding (all, tail)
9797import Text.Read (readMaybe)
9898
99+-- | List of Docker Engine API endpoints
99100data Endpoint =
100101 VersionEndpoint
101102 | ListContainersEndpoint ListOpts
@@ -113,14 +114,23 @@ data Endpoint =
113114 | InspectContainerEndpoint ContainerID
114115 deriving (Eq, Show)
115116
117+-- | We should newtype this
116118type URL = Text
119+
120+-- | We should newtype this
117121type ApiVersion = Text
122+
123+
124+-- | ID of a contianer
118125newtype ContainerID = ContainerID Text
119126 deriving (Eq, Show)
120127
128+-- | Used for extracting the id of the container from the newtype
121129fromContainerID :: ContainerID -> Text
122130fromContainerID (ContainerID t) = t
123131
132+-- | Used for parsing a Text value into a ContainerID. We apply some basic
133+-- validation here.
124134toContainerID :: Text -> Maybe ContainerID
125135toContainerID t =
126136 if T.all (\c -> isAlphaNum c || c == ':') t then -- Note: Can we improve this whitelist?
@@ -128,12 +138,16 @@ toContainerID t =
128138 else
129139 Nothing
130140
141+-- ID of an image.
131142newtype ImageID = ImageID Text
132143 deriving (Eq, Show)
133144
145+-- | Used for extracting the id of the image from the newtype.
134146fromImageID :: ImageID -> Text
135147fromImageID (ImageID t) = t
136148
149+-- | Helper function used for parsing a Text value into an ImageID. For now
150+-- just basic validation is used.
137151toImageID :: Text -> Maybe ImageID
138152toImageID t =
139153 if T.all (\c -> isAlphaNum c || c == ':') t then -- Note: Can we improve this whitelist?
@@ -141,9 +155,12 @@ toImageID t =
141155 else
142156 Nothing
143157
158+-- | Timeout used for stopping a container. DefaultTimeout is 10 seconds.
144159data Timeout = Timeout Integer | DefaultTimeout deriving (Eq, Show)
145160
146161-- TODO: Add more Signals or use an existing lib
162+-- | Signal used for sending to the process running in the container.
163+-- The default signal is SIGTERM.
147164data Signal = SIGHUP
148165 | SIGINT
149166 | SIGQUIT
@@ -197,6 +214,8 @@ data ContainerDetails = ContainerDetails {
197214 }
198215 deriving (Eq, Show, Generic)
199216
217+-- | Data type used for parsing the mount information from a container
218+-- list.
200219data Mount = Mount {
201220 mountName :: Text
202221 , mountSource :: FilePath
@@ -220,6 +239,8 @@ instance FromJSON Mount where
220239 return $ Mount name src dest driver mode rw prop
221240 parseJSON _ = fail "Mount is not an object"
222241
242+-- | Data type used for parsing the container state from a list of
243+-- containers.
223244data ContainerState = ContainerState {
224245 containerError :: Text
225246 , exitCode :: Int
@@ -251,23 +272,30 @@ instance FromJSON ContainerState where
251272 return $ ContainerState err exit finished oomKilled dead paused pid restarting running started st
252273 parseJSON _ = fail "ContainerState is not an object"
253274
275+
276+-- | Client options used to configure the remote engine we're talking to
254277data DockerClientOpts = DockerClientOpts {
255278 apiVer :: ApiVersion
256279 , baseUrl :: URL
257280 }
258281 deriving (Eq, Show)
259282
283+-- | Default "DockerClientOpts" used for talking to the docker engine.
260284defaultClientOpts :: DockerClientOpts
261285defaultClientOpts = DockerClientOpts {
262286 apiVer = "v1.24"
263287 , baseUrl = "http://127.0.0.1:2375"
264288 }
265289
290+-- | List options used for filtering the list of container or images.
266291data ListOpts = ListOpts { all :: Bool } deriving (Eq, Show)
267292
293+-- | Default "ListOpts". Doesn't list stopped containers.
268294defaultListOpts :: ListOpts
269295defaultListOpts = ListOpts { all=False }
270296
297+-- | Data type used for represneting the version of the docker engine
298+-- remote API.
271299data DockerVersion = DockerVersion {
272300 version :: Text
273301 , apiVersion :: ApiVersion
@@ -337,6 +365,8 @@ instance FromJSON ImageID where
337365 return iid
338366 parseJSON _ = fail "ImageID is not an object."
339367
368+-- | Data type used for representing the information of various ports that
369+-- a contianer may expose.
340370data ContainerPortInfo = ContainerPortInfo {
341371 ipAddressInfo :: Maybe Text
342372 , privatePortInfo :: Port
@@ -353,6 +383,8 @@ instance FromJSON ContainerPortInfo where
353383 parseJSON _ = fail "ContainerPortInfo: Not a JSON object."
354384
355385-- For inspecting container details.
386+-- | Data type used for parsing the network information of each container
387+-- when listing them.
356388data NetworkOptions = NetworkOptions {
357389-- ipamConfig :: Maybe Text -- Don't see in 1.24
358390-- , links :: Maybe Text -- Don't see in 1.24
@@ -382,6 +414,7 @@ instance FromJSON NetworkOptions where
382414 return $ NetworkOptions networkId endpointId gateway ip ipLen ip6Gateway globalIP6 globalIP6Len mac
383415 parseJSON _ = fail "NetworkOptions is not an object"
384416
417+-- TODO: Not sure what this is used for anymore.
385418newtype Networks = Networks (M.Map NetworkMode NetworkOptions) -- Note: Is it ever possible that there will be duplicates of network modes?
386419 deriving (Eq, Show)
387420
@@ -398,6 +431,7 @@ instance FromJSON Networks where
398431
399432 parseJSON _ = fail "Networks is not an object"
400433
434+-- | Data type reprsenting the various network settings a container can have.
401435data NetworkSettings = NetworkSettings {
402436 networkSettingsBridge :: Text
403437 , networkSettingsSandboxId :: Text
@@ -443,6 +477,7 @@ instance FromJSON NetworkSettings where
443477 return $ NetworkSettings bridge sandbox hairpin localIP6 localIP6Len ports sandboxKey secondaryIP secondayIP6 endpointID gateway globalIP6 globalIP6Len ip ipLen ip6Gateway mac networks
444478 parseJSON _ = fail "NetworkSettings is not an object."
445479
480+-- | Data type used for parsing a list of containers.
446481data Container = Container
447482 { containerId :: ContainerID
448483 , containerNames :: [Text]
@@ -477,6 +512,7 @@ instance FromJSON Container where
477512
478513 parseJSON _ = fail "Container: Not a JSON object."
479514
515+-- | Represents the status of the container life cycle.
480516data Status = Created | Restarting | Running | Paused | Exited | Dead
481517 deriving (Eq, Show, Generic)
482518
@@ -489,8 +525,11 @@ instance FromJSON Status where
489525 parseJSON (JSON.String "dead") = return Dead
490526 parseJSON _ = fail "Unknown Status"
491527
528+-- | Alias for representing a RepoDigest. We could newtype this and add
529+-- some validation.
492530type Digest = Text
493531
532+-- | Container and Image Labels.
494533newtype Labels = Labels (M.Map Name Value) deriving (Eq, Show)
495534
496535instance FromJSON Labels where
@@ -499,8 +538,10 @@ instance FromJSON Labels where
499538instance ToJSON Labels where
500539 toJSON (Labels kvs) = object [k .= v | (k,v) <- (M.toList kvs)]
501540
541+-- | Alias for Tags.
502542type Tag = Text
503543
544+-- | Data type used for parsing information from a list of images.
504545data Image = DockerImage {
505546 imageId :: ImageID
506547 , imageCreated :: Integer
@@ -512,6 +553,8 @@ data Image = DockerImage {
512553 , imageLabels :: Maybe Labels
513554 } deriving (Show, Eq, Generic)
514555
556+-- | Helper function used for dropping the "image" prefix when serializing
557+-- the Image data type to and from json.
515558dropImagePrefix :: [a] -> [a]
516559dropImagePrefix = drop 5
517560
@@ -519,6 +562,7 @@ instance FromJSON Image where
519562 parseJSON = genericParseJSON defaultOptions {
520563 fieldLabelModifier = dropImagePrefix}
521564
565+-- | Options used for creating a Container.
522566data CreateOpts = CreateOpts {
523567 containerConfig :: ContainerConfig
524568 , hostConfig :: HostConfig
@@ -533,6 +577,8 @@ instance ToJSON CreateOpts where
533577 JSON.Object $ HM.insert "HostConfig" hcJSON o
534578 _ -> error "ContainerConfig is not an object." -- This should never happen.
535579
580+-- | Container configuration used for creating a container with sensible
581+-- defaults.
536582defaultContainerConfig :: Text -> ContainerConfig
537583defaultContainerConfig imageName = ContainerConfig {
538584 hostname=Nothing
@@ -557,6 +603,7 @@ defaultContainerConfig imageName = ContainerConfig {
557603 , stopSignal=SIGTERM
558604 }
559605
606+-- | Default host confiratuon used for creating a container.
560607defaultHostConfig :: HostConfig
561608defaultHostConfig = HostConfig {
562609 binds=[]
@@ -584,6 +631,7 @@ defaultHostConfig = HostConfig {
584631 , resources=defaultContainerResources
585632 }
586633
634+-- Default container resource contstraints (None).
587635defaultContainerResources :: ContainerResources
588636defaultContainerResources = ContainerResources {
589637 cpuShares=Nothing
@@ -605,30 +653,43 @@ defaultContainerResources = ContainerResources {
605653 , ulimits=[]
606654 }
607655
608−
656+-- | Default create options when creating a container. You only need to
657+-- specify an image name and the rest is all sensible defaults.
609658defaultCreateOpts :: T.Text -> CreateOpts
610659defaultCreateOpts imageName = CreateOpts { containerConfig = defaultContainerConfig imageName, hostConfig = defaultHostConfig }
611660
612−-- detachKeys – Override the key sequence for detaching a container.
661+-- | Override the key sequence for detaching a container.
613662-- Format is a single character [a-Z] or ctrl-<value> where <value> is one of: a-z, @, ^, [, , or _.
614663data DetachKeys = WithCtrl Char | WithoutCtrl Char | DefaultDetachKey deriving (Eq, Show)
615664
665+-- | Options for starting a container.
616666data StartOpts = StartOpts { detachKeys :: DetachKeys } deriving (Eq, Show)
617667
668+-- | Default options for staring a container.
618669defaultStartOpts :: StartOpts
619670defaultStartOpts = StartOpts { detachKeys = DefaultDetachKey }
620671
672+-- | Options for deleting a container.
621673data DeleteOpts = DeleteOpts {
622674 deleteVolumes :: Bool -- ^ Automatically cleanup volumes that the container created as well.
623675 , force :: Bool -- ^ If the container is still running force deletion anyway.
624676 } deriving (Eq, Show)
625677
678+-- | Default options for deleting a container. Most of the time we DON'T
679+-- want to delete the container's volumes or force delete it if it's
680+-- running.
626681defaultDeleteOpts :: DeleteOpts
627682defaultDeleteOpts = DeleteOpts { deleteVolumes = False, force = False }
628683
684+-- | Timestamp alias.
629685type Timestamp = Integer
686+
687+-- | Used for requesting N number of lines when tailing a containers log
688+-- output.
630689data TailLogOpt = Tail Integer | All deriving (Eq, Show)
631690
691+
692+-- | Log options used when requesting the log output from a container.
632693data LogOpts = LogOpts {
633694 stdout :: Bool
634695 , stderr :: Bool
@@ -637,6 +698,7 @@ data LogOpts = LogOpts {
637698 , tail :: TailLogOpt
638699 } deriving (Eq, Show)
639700
701+-- | Sensible default for log options.
640702defaultLogOpts :: LogOpts
641703defaultLogOpts = LogOpts { stdout = True
642704 , stderr = True