Network.Wreq.Docker.Registry

Convenience functions for interacting with an instance of Docker Distribution (Docker Registry V2). I've kept the module naming consistent with the docker registry terms since that appears to be what everyone uses colloquially even though the formal name for the software is "docker distribution".

Documentation

defaultRegistry :: URIRef Absolute

Default docker hub registry (https://registry-1.docker.io/v2/).

mkAuth

Arguments

:: RegistryURI

Docker registry

-> ImageName

Docker image name

-> Maybe Credentials

Docker registry authentication credentials

-> IO (Maybe Auth)

Given Credentials, produce a Auth.

If Credentials is either BearerToken or Basic then produce a Auth value for that type of credential.

If Nothing is provided _and_ the provided RegistryURI matches the default registry, make a request to https://auth.docker.io/token for a temporary pull-only bearer token, assuming the request we want to make is to the public docker hub and without any other credentials.

Otherwise, return Nothing so that an unauthenticated request can be made.

pluckLayersFrom :: Manifest -> [Layer]

Retrieve a list of layer hash digests from a docker registry image manifest JSON.

TODO: pluck out the layer's size and digest into a tuple.

pluckRefLayersFrom :: ImageConfigJSON -> [Layer]

Retrieve a list of layer hash digests from an image's configuration JSON.

This is subtly different from pluckLayersFrom because both list hash digests for the image's layers but the manifest's layer hash digests are keys into the registry's blob storage referencing _compressed_ layer archives. The configuration JSON's layer hash digests reference the uncompressed layer tar archives within the image.

fetchManifest :: Hocker RspBS

Request a V2 registry manifest for the specified docker image.

fetchImageConfig :: Digest SHA256 -> Hocker RspBS

Retrieve the configuratino JSON of an image by its hash digest (found in the V2 manifest for an image given by a name and a tag).

fetchLayer :: Layer -> Hocker RspBS

Retrieve a compressed layer blob by its hash digest.

TODO: take advantage of registry's support for the Range header so we can stream downloads.

writeRespBody

Arguments

:: FilePath

Filesystem path to write the content to

-> StrippedDigest

Hash digest, stripped of its algorithm identifier prefix

-> RspBS

Wreq lazy bytestring response object

-> Hocker FilePath

Write a responseBody to the specified FilePath, checking the integrity of the file with its sha256 hash digest.

The second argument, the StrippedDigest, must be a hash digest stripped of the sha256: algorithm identifier prefix.

writeRespBody'

Arguments

:: FilePath

Filesystem path to write the content to

-> RspBS

Wreq lazy bytestring response object

-> Hocker FilePath

Write a response to the filesystem without a request hash digest. Attempt to fetch the value of the ETag header to verify the integrity of the content received.

The Docker docs do _not_ recommended this method for verification because the ETag and Docker-Content-Digest headers may change between the time you issue a request with a digest and when you receive a response back!

We do it anyway and leave this warning.

checkResponseIntegrity

Arguments

:: MonadError HockerException m

=> RspBS

Wreq lazy bytestring response object

-> StrippedDigest

Hash digest, stripped of its hash algorithm identifier prefix

-> m RspBS

Compute a sha256 hash digest of the response body and compare it against the supplied hash digest.

checkResponseIntegrity'

Arguments

:: MonadError HockerException m

=> RspBS

Wreq lazy bytestring response object

-> m RspBS

Compute a sha256 hash digest of the response body and compare it against the Docker-Content-Digest header from the response.

The Docker docs do *not* recommended this method for verification because the Docker-Content-Digest header may change between the time you issue a request with a digest and when you receive a response back!

NB: some registries do not send a Docker-Content-Digest header, I'm not sure yet what the cause for this is but this function's behavior lacking that information is to ignore the hash check.

checkFileIntegrity

Arguments

:: FilePath

Filesystem path of file to verify

-> StrippedDigest

Hash digest, stripped of its hash algorithm identifier prefix

-> IO (Either String FilePath)

Compute a sha256 hash digest for a file and compare that hash to the supplied hash digest.