# OCI import — internals

> **Advanced reading.** This document describes implementation details of the
> OCI import pipeline. It is not needed for day-to-day use of
> `banger image pull`. User-facing documentation is in
> [`docs/oci-import.md`](oci-import.md).

## Architecture

`internal/imagepull/` owns the mechanics:

- **`Pull`** wraps `go-containerregistry`'s `remote.Image` with the
  `linux/amd64` platform pinned. Layer blobs cache under
  `~/.cache/banger/oci/blobs/` and populate lazily during flatten.
- **`Flatten`** replays layers oldest-first into a staging directory,
  applies whiteouts, rejects unsafe paths plus filenames that banger's
  debugfs ownership fixup cannot encode safely. Returns a `Metadata`
  map of per-file uid/gid/mode from tar headers.
- **`BuildExt4`** runs `mkfs.ext4 -F -d <staging> -E root_owner=0:0`
  at the size of the pre-truncated file — no mount, no sudo, no
  loopback. Requires `e2fsprogs ≥ 1.43`.
- **`ApplyOwnership`** streams a batched `set_inode_field` script to
  `debugfs -w` to rewrite per-file uid/gid/mode to the captured tar-
  header values.
- **`InjectGuestAgents`** uses the same `debugfs` scripting to drop
  banger's guest assets into the ext4 with root ownership:
  vsock agent binary, network bootstrap + unit, first-boot script +
  unit, `multi-user.target.wants` symlinks, vsock modules-load
  config, `/var/lib/banger/first-boot-pending` marker.

`internal/daemon/images_pull.go` orchestrates `pullFromOCI`:

1. Parse + validate the OCI ref, derive a default name when `--name`
   is omitted (`debian-bookworm` from
   `docker.io/library/debian:bookworm`).
2. Resolve kernel info via `resolveKernelInputs` (auto-pulls from
   `kernelcat` if `--kernel-ref` names a catalog entry that isn't
   yet local).
3. Stage at `<ImagesDir>/<id>.staging`; extract layers to a temp
   tree under `$TMPDIR`.
4. `BuildExt4` → `ApplyOwnership` → `InjectGuestAgents`.
5. `imagemgr.StageBootArtifacts` stages the kernel triple alongside.
6. Atomic `os.Rename` publishes the artifact dir.
7. Persist a `model.Image{Managed: true, …}` record.