Tank.Image.Registry (Tank v0.1.0)

Minimal OCI Distribution (registry HTTP API v2) client.

Covers exactly what an image pull needs:

an anonymous bearer token -- obtained from the WWW-Authenticate challenge a registry returns to an unauthenticated request;
a manifest fetch (an image index / manifest list, or a single image manifest);
a blob fetch by digest (a layer or the image config).

The functions are stateless: manifest/4 hands back the token it obtained, and the caller threads it into further manifest/4 / blob/4 calls.

Summary

Types

info()

A fetched manifest: its media type, content digest, raw bytes, and parsed JSON. digest is nil when the registry omitted the Docker-Content-Digest header (the caller computes it from raw).

token()

An anonymous bearer token, or nil before one has been obtained.

Functions

blob(registry, repo, digest, token)

Downloads the blob digest (a sha256: string) from repo on registry.

manifest(registry, repo, reference, token \\ nil)

Fetches the manifest for repo:reference from registry.

Types

info()

@type info() :: %{
  media_type: String.t() | nil,
  digest: String.t() | nil,
  raw: binary(),
  json: map()
}

A fetched manifest: its media type, content digest, raw bytes, and parsed JSON. digest is nil when the registry omitted the Docker-Content-Digest header (the caller computes it from raw).

token()

@type token() :: String.t() | nil

An anonymous bearer token, or nil before one has been obtained.

Functions

blob(registry, repo, digest, token)

@spec blob(String.t(), String.t(), String.t(), token()) ::
  {:ok, binary()} | {:error, term()}

Downloads the blob digest (a sha256: string) from repo on registry.

Returns {:ok, bytes}. Registries redirect blob requests to a CDN; Req follows the redirect and -- importantly -- drops the Authorization header when the redirect crosses to a different host, so the bearer token is never handed to the CDN.

manifest(registry, repo, reference, token \\ nil)

@spec manifest(String.t(), String.t(), String.t(), token()) ::
  {:ok, info(), token()} | {:error, term()}

Fetches the manifest for repo:reference from registry.

reference is a tag or a sha256: digest. token may be nil on the first call: a 401 response is answered by parsing its WWW-Authenticate challenge, exchanging it for an anonymous pull token, and retrying once.

Returns {:ok, info, token} where info is %{media_type:, digest:, raw:, json:} and token is the (possibly newly obtained) bearer token, ready to thread into blob/4.