# `Stevedore.Image`
[🔗](https://github.com/oshlabs/stevedore/blob/v0.2.0/lib/stevedore/image.ex#L1)

An assembled image held in memory: a manifest, its config, the ordered layer descriptors, and
the blob bytes backing them.

This is the unit `Stevedore.Build` and `Stevedore.Mutate` produce and that `Stevedore.copy/3`
consumes (a built image can be copied straight to any transport). `assemble/3` is the single
place that turns a config plus a list of layers into a digest-correct manifest — it always
recomputes the config's `rootfs.diff_ids`, the per-layer/per-config sizes and digests, and the
manifest digest, so callers never hand-maintain them.

Spec: [OCI image-spec, config](https://github.com/opencontainers/image-spec/blob/main/config.md)
(the `rootfs.diff_ids` / history relationship) and `manifest.md`.

# `layer`

```elixir
@type layer() :: %{
  descriptor: Stevedore.Descriptor.t(),
  diff_id: Stevedore.Digest.t(),
  blob: binary()
}
```

A layer being assembled: its (compressed) descriptor, uncompressed diff_id, and bytes.

# `t`

```elixir
@type t() :: %Stevedore.Image{
  blobs: %{optional(String.t()) => binary()},
  config: Stevedore.Config.t(),
  layers: [Stevedore.Descriptor.t()],
  manifest: Stevedore.Manifest.t(),
  referrers: [Stevedore.Descriptor.t()] | nil,
  tag: String.t() | nil
}
```

# `annotations`

```elixir
@spec annotations(t()) :: map() | nil
```

The manifest's annotations, if any.

# `assemble`

```elixir
@spec assemble(map(), [layer()], keyword()) :: {:ok, t()} | {:error, term()}
```

Assembles an image from a full image-config JSON map and a list of `t:layer/0`.

Recomputes `rootfs.diff_ids` from the layers, ensures the history length matches, and builds the
config and manifest blobs with correct sizes and digests. `opts`: `:format` (`:oci`/`:docker`),
`:annotations` (manifest annotations), `:tag`.

# `blob`

```elixir
@spec blob(t(), Stevedore.Digest.t()) :: {:ok, binary()} | {:error, :not_found}
```

Fetches a blob's bytes by digest.

# `digest`

```elixir
@spec digest(t()) :: Stevedore.Digest.t()
```

The image's manifest digest.

# `format`

```elixir
@spec format(t()) :: :oci | :docker
```

The image's manifest format (`:oci` or `:docker`), inferred from its media type.

# `layers`

```elixir
@spec layers(t()) :: [layer()]
```

Reconstructs the `t:layer/0` records (descriptor + diff_id + bytes) from an assembled image,
pairing each layer descriptor with its `rootfs.diff_ids` entry.

---

*Consult [api-reference.md](api-reference.md) for complete listing*