01856e7 · docker-hs · git.iko.soy

git.iko.soy/docker-hs

on master help sign in

Adds some more docs

01856e7Deni Bertovic10 years ago

src/Docker/Client/Types.hs+64−2

compare with master

unifiedsplit

@@ -96,6 +96,7 @@ import GHC.Generics (Generic)

96import Prelude hiding (all, tail)

97import Text.Read (readMaybe)

99+-- | List of Docker Engine API endpoints

99data Endpoint =

100data Endpoint =

100 VersionEndpoint

101 VersionEndpoint

101 | ListContainersEndpoint ListOpts

102 | ListContainersEndpoint ListOpts

@@ -113,14 +114,23 @@ data Endpoint =

113 | InspectContainerEndpoint ContainerID

114 | InspectContainerEndpoint ContainerID

114 deriving (Eq, Show)

115 deriving (Eq, Show)

115

116

117+-- | We should newtype this

116type URL = Text

118type URL = Text

119+

120+-- | We should newtype this

117type ApiVersion = Text

121type ApiVersion = Text

122+

123+

124+-- | ID of a contianer

118newtype ContainerID = ContainerID Text

125newtype ContainerID = ContainerID Text

119 deriving (Eq, Show)

126 deriving (Eq, Show)

120

127

128+-- | Used for extracting the id of the container from the newtype

121fromContainerID :: ContainerID -> Text

129fromContainerID :: ContainerID -> Text

122fromContainerID (ContainerID t) = t

130fromContainerID (ContainerID t) = t

123

131

132+-- | Used for parsing a Text value into a ContainerID. We apply some basic

133+-- validation here.

124toContainerID :: Text -> Maybe ContainerID

134toContainerID :: Text -> Maybe ContainerID

125toContainerID t =

135toContainerID t =

126 if T.all (\c -> isAlphaNum c || c == ':') t then -- Note: Can we improve this whitelist?

136 if T.all (\c -> isAlphaNum c || c == ':') t then -- Note: Can we improve this whitelist?

@@ -128,12 +138,16 @@ toContainerID t =

128 else

138 else

129 Nothing

139 Nothing

130

140

141+-- ID of an image.

131newtype ImageID = ImageID Text

142newtype ImageID = ImageID Text

132 deriving (Eq, Show)

143 deriving (Eq, Show)

133

144

145+-- | Used for extracting the id of the image from the newtype.

134fromImageID :: ImageID -> Text

146fromImageID :: ImageID -> Text

135fromImageID (ImageID t) = t

147fromImageID (ImageID t) = t

136

148

149+-- | Helper function used for parsing a Text value into an ImageID. For now

150+-- just basic validation is used.

137toImageID :: Text -> Maybe ImageID

151toImageID :: Text -> Maybe ImageID

138toImageID t =

152toImageID t =

139 if T.all (\c -> isAlphaNum c || c == ':') t then -- Note: Can we improve this whitelist?

153 if T.all (\c -> isAlphaNum c || c == ':') t then -- Note: Can we improve this whitelist?

@@ -141,9 +155,12 @@ toImageID t =

141 else

155 else

142 Nothing

156 Nothing

143

157

158+-- | Timeout used for stopping a container. DefaultTimeout is 10 seconds.

144data Timeout = Timeout Integer | DefaultTimeout deriving (Eq, Show)

159data Timeout = Timeout Integer | DefaultTimeout deriving (Eq, Show)

145

160

146-- TODO: Add more Signals or use an existing lib

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

147data Signal = SIGHUP

164data Signal = SIGHUP

148 | SIGINT

165 | SIGINT

149 | SIGQUIT

166 | SIGQUIT

@@ -197,6 +214,8 @@ data ContainerDetails = ContainerDetails {

197 }

214 }

198 deriving (Eq, Show, Generic)

215 deriving (Eq, Show, Generic)

199

216

217+-- | Data type used for parsing the mount information from a container

218+-- list.

200data Mount = Mount {

219data Mount = Mount {

201 mountName :: Text

220 mountName :: Text

202 , mountSource :: FilePath

221 , mountSource :: FilePath

@@ -220,6 +239,8 @@ instance FromJSON Mount where

220 return $ Mount name src dest driver mode rw prop

239 return $ Mount name src dest driver mode rw prop

221 parseJSON _ = fail "Mount is not an object"

240 parseJSON _ = fail "Mount is not an object"

222

241

242+-- | Data type used for parsing the container state from a list of

243+-- containers.

223data ContainerState = ContainerState {

244data ContainerState = ContainerState {

224 containerError :: Text

245 containerError :: Text

225 , exitCode :: Int

246 , exitCode :: Int

@@ -251,23 +272,30 @@ instance FromJSON ContainerState where

251 return $ ContainerState err exit finished oomKilled dead paused pid restarting running started st

272 return $ ContainerState err exit finished oomKilled dead paused pid restarting running started st

252 parseJSON _ = fail "ContainerState is not an object"

273 parseJSON _ = fail "ContainerState is not an object"

253

274

275+

276+-- | Client options used to configure the remote engine we're talking to

254data DockerClientOpts = DockerClientOpts {

277data DockerClientOpts = DockerClientOpts {

255 apiVer :: ApiVersion

278 apiVer :: ApiVersion

256 , baseUrl :: URL

279 , baseUrl :: URL

257 }

280 }

258 deriving (Eq, Show)

281 deriving (Eq, Show)

259

282

283+-- | Default "DockerClientOpts" used for talking to the docker engine.

260defaultClientOpts :: DockerClientOpts

284defaultClientOpts :: DockerClientOpts

261defaultClientOpts = DockerClientOpts {

285defaultClientOpts = DockerClientOpts {

262 apiVer = "v1.24"

286 apiVer = "v1.24"

263 , baseUrl = "http://127.0.0.1:2375"

287 , baseUrl = "http://127.0.0.1:2375"

264 }

288 }

265

289

290+-- | List options used for filtering the list of container or images.

266data ListOpts = ListOpts { all :: Bool } deriving (Eq, Show)

291data ListOpts = ListOpts { all :: Bool } deriving (Eq, Show)

267

292

293+-- | Default "ListOpts". Doesn't list stopped containers.

268defaultListOpts :: ListOpts

294defaultListOpts :: ListOpts

269defaultListOpts = ListOpts { all=False }

295defaultListOpts = ListOpts { all=False }

270

296

297+-- | Data type used for represneting the version of the docker engine

298+-- remote API.

271data DockerVersion = DockerVersion {

299data DockerVersion = DockerVersion {

272 version :: Text

300 version :: Text

273 , apiVersion :: ApiVersion

301 , apiVersion :: ApiVersion

@@ -337,6 +365,8 @@ instance FromJSON ImageID where

337 return iid

365 return iid

338 parseJSON _ = fail "ImageID is not an object."

366 parseJSON _ = fail "ImageID is not an object."

339

367

368+-- | Data type used for representing the information of various ports that

369+-- a contianer may expose.

340data ContainerPortInfo = ContainerPortInfo {

370data ContainerPortInfo = ContainerPortInfo {

341 ipAddressInfo :: Maybe Text

371 ipAddressInfo :: Maybe Text

342 , privatePortInfo :: Port

372 , privatePortInfo :: Port

@@ -353,6 +383,8 @@ instance FromJSON ContainerPortInfo where

353 parseJSON _ = fail "ContainerPortInfo: Not a JSON object."

383 parseJSON _ = fail "ContainerPortInfo: Not a JSON object."

354

384

355-- For inspecting container details.

385-- For inspecting container details.

386+-- | Data type used for parsing the network information of each container

387+-- when listing them.

356data NetworkOptions = NetworkOptions {

388data NetworkOptions = NetworkOptions {

357-- ipamConfig :: Maybe Text -- Don't see in 1.24

389-- ipamConfig :: Maybe Text -- Don't see in 1.24

358-- , links :: Maybe Text -- Don't see in 1.24

390-- , links :: Maybe Text -- Don't see in 1.24

@@ -382,6 +414,7 @@ instance FromJSON NetworkOptions where

382 return $ NetworkOptions networkId endpointId gateway ip ipLen ip6Gateway globalIP6 globalIP6Len mac

414 return $ NetworkOptions networkId endpointId gateway ip ipLen ip6Gateway globalIP6 globalIP6Len mac

383 parseJSON _ = fail "NetworkOptions is not an object"

415 parseJSON _ = fail "NetworkOptions is not an object"

384

416

417+-- TODO: Not sure what this is used for anymore.

385newtype Networks = Networks (M.Map NetworkMode NetworkOptions) -- Note: Is it ever possible that there will be duplicates of network modes?

418newtype Networks = Networks (M.Map NetworkMode NetworkOptions) -- Note: Is it ever possible that there will be duplicates of network modes?

386 deriving (Eq, Show)

419 deriving (Eq, Show)

387

420

@@ -398,6 +431,7 @@ instance FromJSON Networks where

398

431

399 parseJSON _ = fail "Networks is not an object"

432 parseJSON _ = fail "Networks is not an object"

400

433

434+-- | Data type reprsenting the various network settings a container can have.

401data NetworkSettings = NetworkSettings {

435data NetworkSettings = NetworkSettings {

402 networkSettingsBridge :: Text

436 networkSettingsBridge :: Text

403 , networkSettingsSandboxId :: Text

437 , networkSettingsSandboxId :: Text

@@ -443,6 +477,7 @@ instance FromJSON NetworkSettings where

443 return $ NetworkSettings bridge sandbox hairpin localIP6 localIP6Len ports sandboxKey secondaryIP secondayIP6 endpointID gateway globalIP6 globalIP6Len ip ipLen ip6Gateway mac networks

477 return $ NetworkSettings bridge sandbox hairpin localIP6 localIP6Len ports sandboxKey secondaryIP secondayIP6 endpointID gateway globalIP6 globalIP6Len ip ipLen ip6Gateway mac networks

444 parseJSON _ = fail "NetworkSettings is not an object."

478 parseJSON _ = fail "NetworkSettings is not an object."

445

479

480+-- | Data type used for parsing a list of containers.

446data Container = Container

481data Container = Container

447 { containerId :: ContainerID

482 { containerId :: ContainerID

448 , containerNames :: [Text]

483 , containerNames :: [Text]

@@ -477,6 +512,7 @@ instance FromJSON Container where

477

512

478 parseJSON _ = fail "Container: Not a JSON object."

513 parseJSON _ = fail "Container: Not a JSON object."

479

514

515+-- | Represents the status of the container life cycle.

481 deriving (Eq, Show, Generic)

517 deriving (Eq, Show, Generic)

482

518

@@ -489,8 +525,11 @@ instance FromJSON Status where

489 parseJSON (JSON.String "dead") = return Dead

525 parseJSON (JSON.String "dead") = return Dead

490 parseJSON _ = fail "Unknown Status"

526 parseJSON _ = fail "Unknown Status"

491

527

528+-- | Alias for representing a RepoDigest. We could newtype this and add

529+-- some validation.

492type Digest = Text

530type Digest = Text

493

531

532+-- | Container and Image Labels.

494newtype Labels = Labels (M.Map Name Value) deriving (Eq, Show)

533newtype Labels = Labels (M.Map Name Value) deriving (Eq, Show)

495

534

496instance FromJSON Labels where

535instance FromJSON Labels where

@@ -499,8 +538,10 @@ instance FromJSON Labels where

499instance ToJSON Labels where

538instance ToJSON Labels where

500 toJSON (Labels kvs) = object [k .= v | (k,v) <- (M.toList kvs)]

539 toJSON (Labels kvs) = object [k .= v | (k,v) <- (M.toList kvs)]

501

540

541+-- | Alias for Tags.

502type Tag = Text

542type Tag = Text

503

543

544+-- | Data type used for parsing information from a list of images.

504data Image = DockerImage {

545data Image = DockerImage {

505 imageId :: ImageID

546 imageId :: ImageID

506 , imageCreated :: Integer

547 , imageCreated :: Integer

@@ -512,6 +553,8 @@ data Image = DockerImage {

512 , imageLabels :: Maybe Labels

553 , imageLabels :: Maybe Labels

513 } deriving (Show, Eq, Generic)

554 } deriving (Show, Eq, Generic)

514

555

556+-- | Helper function used for dropping the "image" prefix when serializing

557+-- the Image data type to and from json.

515dropImagePrefix :: [a] -> [a]

558dropImagePrefix :: [a] -> [a]

516dropImagePrefix = drop 5

559dropImagePrefix = drop 5

517

560

@@ -519,6 +562,7 @@ instance FromJSON Image where

519 parseJSON = genericParseJSON defaultOptions {

562 parseJSON = genericParseJSON defaultOptions {

520 fieldLabelModifier = dropImagePrefix}

563 fieldLabelModifier = dropImagePrefix}

521

564

565+-- | Options used for creating a Container.

522data CreateOpts = CreateOpts {

566data CreateOpts = CreateOpts {

523 containerConfig :: ContainerConfig

567 containerConfig :: ContainerConfig

524 , hostConfig :: HostConfig

568 , hostConfig :: HostConfig

@@ -533,6 +577,8 @@ instance ToJSON CreateOpts where

533 JSON.Object $ HM.insert "HostConfig" hcJSON o

577 JSON.Object $ HM.insert "HostConfig" hcJSON o

534 _ -> error "ContainerConfig is not an object." -- This should never happen.

578 _ -> error "ContainerConfig is not an object." -- This should never happen.

535

579

580+-- | Container configuration used for creating a container with sensible

581+-- defaults.

536defaultContainerConfig :: Text -> ContainerConfig

582defaultContainerConfig :: Text -> ContainerConfig

537defaultContainerConfig imageName = ContainerConfig {

583defaultContainerConfig imageName = ContainerConfig {

538 hostname=Nothing

584 hostname=Nothing

@@ -557,6 +603,7 @@ defaultContainerConfig imageName = ContainerConfig {

557 , stopSignal=SIGTERM

603 , stopSignal=SIGTERM

558 }

604 }

559

605

606+-- | Default host confiratuon used for creating a container.

560defaultHostConfig :: HostConfig

607defaultHostConfig :: HostConfig

561defaultHostConfig = HostConfig {

608defaultHostConfig = HostConfig {

562 binds=[]

609 binds=[]

@@ -584,6 +631,7 @@ defaultHostConfig = HostConfig {

584 , resources=defaultContainerResources

631 , resources=defaultContainerResources

585 }

632 }

586

633

634+-- Default container resource contstraints (None).

587defaultContainerResources :: ContainerResources

635defaultContainerResources :: ContainerResources

588defaultContainerResources = ContainerResources {

636defaultContainerResources = ContainerResources {

589 cpuShares=Nothing

637 cpuShares=Nothing

@@ -605,30 +653,43 @@ defaultContainerResources = ContainerResources {

605 , ulimits=[]

653 , ulimits=[]

606 }

654 }

607

655

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.

609defaultCreateOpts :: T.Text -> CreateOpts

658defaultCreateOpts :: T.Text -> CreateOpts

610defaultCreateOpts imageName = CreateOpts { containerConfig = defaultContainerConfig imageName, hostConfig = defaultHostConfig }

659defaultCreateOpts imageName = CreateOpts { containerConfig = defaultContainerConfig imageName, hostConfig = defaultHostConfig }

611

660

612−-- detachKeys – Override the key sequence for detaching a container.

661+-- | Override the key sequence for detaching a container.

613-- Format is a single character [a-Z] or ctrl-<value> where <value> is one of: a-z, @, ^, [, , or _.

662-- Format is a single character [a-Z] or ctrl-<value> where <value> is one of: a-z, @, ^, [, , or _.

614data DetachKeys = WithCtrl Char | WithoutCtrl Char | DefaultDetachKey deriving (Eq, Show)

663data DetachKeys = WithCtrl Char | WithoutCtrl Char | DefaultDetachKey deriving (Eq, Show)

615

664

665+-- | Options for starting a container.

616data StartOpts = StartOpts { detachKeys :: DetachKeys } deriving (Eq, Show)

666data StartOpts = StartOpts { detachKeys :: DetachKeys } deriving (Eq, Show)

617

667

668+-- | Default options for staring a container.

618defaultStartOpts :: StartOpts

669defaultStartOpts :: StartOpts

619defaultStartOpts = StartOpts { detachKeys = DefaultDetachKey }

670defaultStartOpts = StartOpts { detachKeys = DefaultDetachKey }

620

671

672+-- | Options for deleting a container.

621data DeleteOpts = DeleteOpts {

673data DeleteOpts = DeleteOpts {

622 deleteVolumes :: Bool -- ^ Automatically cleanup volumes that the container created as well.

674 deleteVolumes :: Bool -- ^ Automatically cleanup volumes that the container created as well.

623 , force :: Bool -- ^ If the container is still running force deletion anyway.

675 , force :: Bool -- ^ If the container is still running force deletion anyway.

624 } deriving (Eq, Show)

676 } deriving (Eq, Show)

625

677

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.

626defaultDeleteOpts :: DeleteOpts

681defaultDeleteOpts :: DeleteOpts

627defaultDeleteOpts = DeleteOpts { deleteVolumes = False, force = False }

682defaultDeleteOpts = DeleteOpts { deleteVolumes = False, force = False }

628

683

684+-- | Timestamp alias.

629type Timestamp = Integer

685type Timestamp = Integer

686+

687+-- | Used for requesting N number of lines when tailing a containers log

688+-- output.

630data TailLogOpt = Tail Integer | All deriving (Eq, Show)

689data TailLogOpt = Tail Integer | All deriving (Eq, Show)

631

690

691+

692+-- | Log options used when requesting the log output from a container.

632data LogOpts = LogOpts {

693data LogOpts = LogOpts {

633 stdout :: Bool

694 stdout :: Bool

634 , stderr :: Bool

695 , stderr :: Bool

@@ -637,6 +698,7 @@ data LogOpts = LogOpts {

637 , tail :: TailLogOpt

698 , tail :: TailLogOpt

638 } deriving (Eq, Show)

699 } deriving (Eq, Show)

639

700

701+-- | Sensible default for log options.

640defaultLogOpts :: LogOpts

702defaultLogOpts :: LogOpts

641defaultLogOpts = LogOpts { stdout = True

703defaultLogOpts = LogOpts { stdout = True

642 , stderr = True

704 , stderr = True