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