regc

defmodule Regc do
  @moduledoc """

  Resolve and validate OCI/Docker image metadata.



  `check_image/2` validates manifest metadata and reports the platforms

  advertised by an image index. Pass `platform: "os/architecture"`, a

  qualifier map, or `platform: :local` to select an image from an index.



  `inspect_image/2` additionally downloads and verifies an image

  configuration. Inspecting an index requires an explicit platform.

  """

  alias Regc.Client
  alias Regc.Oci.{Error, Image}

  @doc """

  Checks the manifest graph addressed by an image tag.



  Without a `:platform` option, an image index is validated but not resolved

  to one of its child manifests. Its advertised platforms are returned in

  `image.platforms`.



  ## Examples



      iex> is_function(&Regc.check_image/2)

      true



  """
  @spec check_image(String.t(), keyword()) ::

          {:ok, Image.Resolved.t()} | {:error, Error.t()}
  def check_image(reference, opts \\ [])

  def check_image(%Client{} = client, reference),
    do: check_image(client, reference, [])

  def check_image(reference, opts),
    do: Regc.Oci.Client.check(reference, opts)

  @spec check_image(Client.t(), String.t(), keyword()) ::

          {:ok, Image.Resolved.t()} | {:error, Error.t()}
  def check_image(%Client{} = client, reference, opts) do
    Regc.Oci.Client.check(reference, Client.option_keyword(client, opts))
  end

  @doc """

  Checks an image and returns its decoded, verified configuration.



  A platform must be specified when the tag addresses an image index. A

  single-image tag can be inspected without one; its platform is read from

  the verified configuration.



  The top-level image creation timestamp is available as

  `image.config.created`.

  """
  @spec inspect_image(String.t(), keyword()) ::

          {:ok, Image.Resolved.t()} | {:error, Error.t()}
  def inspect_image(reference, opts \\ [])

  def inspect_image(%Client{} = client, reference),
    do: inspect_image(client, reference, [])

  def inspect_image(reference, opts),
    do: Regc.Oci.Client.inspect_image(reference, opts)

  @spec inspect_image(Client.t(), String.t(), keyword()) ::

          {:ok, Image.Resolved.t()} | {:error, Error.t()}
  def inspect_image(%Client{} = client, reference, opts) do
    Regc.Oci.Client.inspect_image(reference, Client.option_keyword(client, opts))
  end

  @doc """

  Returns the image creation timestamp.

  """
  @spec image_created(String.t(), keyword()) ::

          {:ok, String.t() | nil} | {:error, Error.t()}
  def image_created(reference, opts \\ [])

  def image_created(%Client{} = client, reference),
    do: image_created(client, reference, [])

  def image_created(reference, opts),
    do: Regc.Oci.Client.image_created(reference, opts)

  @spec image_created(Client.t(), String.t(), keyword()) ::

          {:ok, String.t() | nil} | {:error, Error.t()}
  def image_created(%Client{} = client, reference, opts) do
    Regc.Oci.Client.image_created(reference, Client.option_keyword(client, opts))
  end
end