Stevedore.Reference (Stevedore v0.2.0)

A parsed, normalized image reference: registry, repository, and a tag or digest.

Parsing applies Docker/OCI normalization (the distribution/reference rules): a name with no registry component defaults to Docker Hub (registry-1.docker.io), a single-segment Hub repo gets the library/ prefix, and a reference with neither tag nor digest defaults to the latest tag.

This models only the name part. Transport prefixes (docker://, oci:) are parsed by the transport layer in a later phase.

Spec: distribution/reference grammar and Docker Registry HTTP API v2.

Summary

Types

t()

Functions

parse(string)

Parses an image reference string, applying Docker/OCI normalization.

to_string(ref)

Renders a reference back to its canonical registry/repository[:tag][@digest] string.

Types

t()

@type t() :: %Stevedore.Reference{
  digest: Stevedore.Digest.t() | nil,
  registry: String.t(),
  repository: String.t(),
  tag: String.t() | nil
}

Functions

parse(string)

@spec parse(String.t()) :: {:ok, t()} | {:error, {:bad_input, term()}}

Parses an image reference string, applying Docker/OCI normalization.

Examples

iex> {:ok, ref} = Stevedore.Reference.parse("alpine:3.20")
iex> {ref.registry, ref.repository, ref.tag}
{"registry-1.docker.io", "library/alpine", "3.20"}

iex> {:ok, ref} = Stevedore.Reference.parse("ghcr.io/owner/app")
iex> {ref.registry, ref.repository, ref.tag}
{"ghcr.io", "owner/app", "latest"}

iex> {:ok, ref} = Stevedore.Reference.parse("localhost:5000/app@sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855")
iex> {ref.registry, ref.tag, ref.digest.algorithm}
{"localhost:5000", nil, :sha256}

to_string(ref)

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

Renders a reference back to its canonical registry/repository[:tag][@digest] string.

The output re-parses to an equal reference.

Examples

iex> {:ok, ref} = Stevedore.Reference.parse("alpine")
iex> Stevedore.Reference.to_string(ref)
"registry-1.docker.io/library/alpine:latest"