registrypush: push core for exporting cached images to remote registries

[chruffins]

Layer 1 of remote registry push support (first layer of a stack).

What

Hypeman can pull from remote registries and accept pushes into its embedded registry, but has no outbound push path. This adds the registry-agnostic push core that later layers (manager integration, API endpoint) build on.

lib/ocicache (new)

• ImageFromCache reconstructs a v1.Image from the OCI blob cache, extracted from lib/registry (previously the private imageFromBlobStore). Preserves the transparent Docker v2 → OCI conversion and adds a typed ErrNotFound for missing digests.
• lib/registry now uses this package; the inbound push path is otherwise unchanged.

lib/registrypush (new)

• Push / PushFromCache: write a cached image to any registry via remote.Write. Blobs are pushed as stored, so manifest digests are preserved end to end.
• Provider interface for credential resolution — the modularity point for registry-specific auth (e.g. ECR token exchange in a later phase). Ships with:
  • KeychainProvider — docker config.json incl. credential helpers
  • StaticProvider — fixed credentials
  • Multi — per-host routing with default fallback
• Errors classified via images.ClassifyRegistryError (exported from lib/images, renamed from wrapRegistryError) so rate limits and missing repos map to the existing typed errors.

Tests

• Hermetic: in-process go-containerregistry registry as push destination, no external deps.
• Covers: round-trip through the cache, digest preservation on push, Docker v2 → OCI conversion, bearer auth, rate-limit and not-found classification, keychain config resolution, per-host provider routing.

Verification

• go build -tags containers_image_openpgp ./... — full tree builds
• go test -tags containers_image_openpgp ./... — all packages pass, including the full lib/images suite (with mkfs.erofs installed) and lib/builds, except 42 VM-instance/integration tests that require Docker Hub pulls (anonymous rate limit) and instance networking. Verified these 42 fail identically on main (same test names, side-by-side run), so they are environmental, not caused by this change.
• Wrote a test program utilizing the public functions to push an image to an AWS ECR repository
• Pulled the pushed image from AWS ECR using hypeman

---

Note

Medium Risk
Touches registry error mapping, embedded-registry GC roots, and a large new cache read path; behavior changes are mostly additive but misclassification or GC regressions could break pulls/pushes.

Overview
Adds the outbound push foundation: read images from hypeman's OCI blob cache and write them to any remote registry, with pluggable credentials and shared error typing for API layers.

lib/ocicache extracts cache-backed v1.Image construction (formerly private registry code). It validates digest paths, converts Docker v2 manifests to OCI on read, and serves layers with proper gzip handling. lib/registry delegates layout append to this package and broadens in-memory tag tracking from BuildKit-only cacheTags to pushedTags for every accepted manifest so OCI GC keeps blobs still served by tag/digest pulls.

lib/registrypush implements Push / PushFromCache via remote.Write, plus Provider implementations (Docker keychain, static creds, per-host Multi). Push auth failures map to ErrUnauthorized; other registry errors use exported images.ClassifyRegistryError, which now prefers typed transport.Error status/codes so URLs or tag names (e.g. v404) cannot be misclassified as not-found.

ClassifyRegistryError replaces the private wrapRegistryError at pull/mirror/oci call sites, with expanded tests for transport-shaped errors.

^{Reviewed by Cursor Bugbot for commit 7471a0c. Bugbot is set up for automated code reviews on this repo. Configure here.}

[chruffins]

reviewed — clean extraction of the OCI cache reader into lib/ocicache with a tidy provider/push seam and solid tests. all bugs, nits, and structural items on this layer are fixed across 05de62e3 and a3b3d9e8 (typed push error classification, digest path validation, real Uncompressed/DiffID, parse-once v1.Manifest with field preservation, and GC-rooting of pushed manifests); one structural note remains open by choice.

Structural / Maintainability (open)

• lib/registrypush/provider.go — Multi has no consumers outside tests and its host-dispatch semantics are speculative; kept for now by decision, revisit if a real per-host routing requirement appears.

status: all review findings addressed except Multi, kept intentionally

[cursor]

Cursor Bugbot has reviewed your changes using high effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 56e884f. Configure here.}

[sjmiller609]

lib/ocicache/image.go:216-230 — actual DockerForeignLayer media types are left unchanged inside the converted OCI manifest. map them to OCIRestrictedLayer and update the test to use DockerForeignLayer.
lib/registrypush/provider.go:29-34 — KeychainProvider drops the caller’s context. use authn.Resolve(ctx, kc, ref.Context()) so context-aware keychains receive cancellation and deadlines.