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.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()}
  defdelegate check_image(reference, opts \\ []), to: Regc.Oci.Client, as: :check

  @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()}
  defdelegate inspect_image(reference, opts \\ []), to: Regc.Oci.Client

  @doc """
  Returns the image creation timestamp.
  """
  @spec image_created(String.t(), keyword()) ::
          {:ok, String.t() | nil} | {:error, Error.t()}
  defdelegate image_created(reference, opts \\ []), to: Regc.Oci.Client
end