TestcontainerEx.Docker.Auth (testcontainer_ex v0.1.0)

Resolves Docker registry credentials from the user's Docker config file (typically ~/.docker/config.json) and returns a ready-to-send X-Registry-Auth header value.

Scope:

Only the auths map in config.json is supported.
Credential helpers (credsStore, credHelpers) are intentionally out of scope — if encountered, a debug log is emitted and nil is returned so the caller can fall back to anonymous access.

The DOCKER_CONFIG environment variable is honoured: when set, the config file is read from $DOCKER_CONFIG/config.json; otherwise the default path ~/.docker/config.json is used.

The header value is a URL-safe base64 encoding (without padding) of a JSON document describing the credentials, as specified by the Docker Engine API.

Third-party registries (quay.io, ghcr.io, gcr.io, registry.gitlab.com, etc.) are fully supported. The registry key is extracted from the image reference and looked up directly in the auths map.

Summary

Functions

candidate_keys(registry)

Returns the list of candidate keys to try when looking up credentials for a given registry in the Docker config.json auths map.

registry_for_image(image)

Returns the registry key that should be used for looking up credentials for the given image (Docker config convention).

resolve(image, config_path \\ nil)

Resolves registry credentials for the given image and returns the ready-to-send X-Registry-Auth header value, or nil if no matching credentials can be found.

Functions

candidate_keys(registry)

@spec candidate_keys(String.t()) :: [String.t()]

Returns the list of candidate keys to try when looking up credentials for a given registry in the Docker config.json auths map.

Docker config files may store registry keys in various formats (with or without scheme, with or without trailing slash). This function generates all plausible variants so that lookups succeed regardless of how the key was originally stored.

Examples

iex> TestcontainerEx.Docker.Auth.candidate_keys("quay.io")
["quay.io", "https://quay.io", "http://quay.io", "https://quay.io/", "http://quay.io/"]

iex> TestcontainerEx.Docker.Auth.candidate_keys("https://index.docker.io/v1/")
["https://index.docker.io/v1/", "index.docker.io", "docker.io", "https://index.docker.io/v1", "https://index.docker.io", "https://docker.io"]

registry_for_image(image)

@spec registry_for_image(String.t()) :: String.t()

Returns the registry key that should be used for looking up credentials for the given image (Docker config convention).

Unnamespaced or explicitly docker.io-hosted images resolve to https://index.docker.io/v1/; everything else resolves to the registry host component of the image reference.

Examples

iex> TestcontainerEx.Docker.Auth.registry_for_image("nginx")
"https://index.docker.io/v1/"

iex> TestcontainerEx.Docker.Auth.registry_for_image("library/nginx")
"https://index.docker.io/v1/"

iex> TestcontainerEx.Docker.Auth.registry_for_image("docker.io/library/nginx")
"https://index.docker.io/v1/"

iex> TestcontainerEx.Docker.Auth.registry_for_image("quay.io/org/image")
"quay.io"

iex> TestcontainerEx.Docker.Auth.registry_for_image("ghcr.io/org/image")
"ghcr.io"

iex> TestcontainerEx.Docker.Auth.registry_for_image("gcr.io/project/image")
"gcr.io"

iex> TestcontainerEx.Docker.Auth.registry_for_image("registry.gitlab.com/org/image")
"registry.gitlab.com"

iex> TestcontainerEx.Docker.Auth.registry_for_image("myregistry:5000/image")
"myregistry:5000"

resolve(image, config_path \\ nil)

@spec resolve(String.t(), String.t() | nil) :: String.t() | nil

Resolves registry credentials for the given image and returns the ready-to-send X-Registry-Auth header value, or nil if no matching credentials can be found.

config_path may be nil, in which case the default lookup logic is used (respecting the DOCKER_CONFIG environment variable).