Regc.Mutate (regc v0.0.2)

Pure, immutable mutation of OCI/Docker manifest and image-config documents.

Mutation is deliberately separate from registry persistence:

with {:ok, mutation} <- Regc.Mutate.new(manifest, config_bytes),
     {:ok, mutation} <-
       Regc.Mutate.Config.put_label(
         mutation,
         "org.example.release",
         "stable"
       ),
     {:ok, result} <- Regc.Mutate.finalize(mutation) do
  # Upload result.config_raw, then publish result.manifest_raw.
  {:ok, result}
end

new/3 verifies exact input bytes against their descriptors. finalize/2 validates the transformed documents, updates the config descriptor in the manifest, and computes publishable manifest/config descriptors. No network or filesystem write occurs.

Summary

Functions

finalize(mutation, opts \\ [])

Produces validated bytes and descriptors after one or more transformations.

new(manifest, config \\ nil, opts \\ [])

Builds verified mutation state from a manifest and optional config body.

Functions

finalize(mutation, opts \\ [])

@spec finalize(
  Regc.Mutate.Image.t(),
  keyword()
) :: {:ok, Regc.Mutate.Result.t()} | {:error, Regc.Error.t()}

Produces validated bytes and descriptors after one or more transformations.

:digest_algorithm may be :sha256, :sha384, or :sha512. It applies to materialized manifest and config bytes; referenced layer and child-manifest digests remain unchanged because their bytes are not part of mutation state.

new(manifest, config \\ nil, opts \\ [])

@spec new(
  Regc.Oci.Manifest.t() | binary() | map(),
  binary() | map() | Regc.Oci.Image.Config.t() | nil,
  keyword()
) :: {:ok, Regc.Mutate.Image.t()} | {:error, Regc.Error.t()}

Builds verified mutation state from a manifest and optional config body.

manifest accepts a decoded Regc.Oci.Manifest, exact JSON bytes, or a document map. For an image, config should be the exact config blob bytes whenever config or layer fields will be changed.

Raw manifest bytes require :media_type when the document does not declare one. A caller-supplied :manifest_descriptor is strictly verified.