fix(image): force-pull when digest pinned but missing locally

[CMGS]

Summary

cmd/core/helpers.go:EnsureImage already proves at the first Inspect(lookupRef=ImageDigest) that the requested digest isn't in the local cache. The subsequent Pull then passed force=false, which lets images/cloudimg/pull.go:62's URL-level short-circuit win:

if !force {
    if _, entry, ok := idx.Lookup(url); ok {
        if utils.ValidFile(conf.BlobPath(entry.ContentSum.Hex())) {
            skip = true   // skip HTTP re-download
        }
    }
}

That short-circuit's policy is "any cached blob for this URL is fine" — perfect for non-digest-pinned reuse, wrong when the caller wants a specific digest. The URL→blob mapping in the local index can point at a stale digest (cached from a previous version of the upstream tag); the post-pull Inspect(ImageDigest) then warns and returns, and the failure surfaces deep in vm.restore as a Backing file I/O error against a qcow2 backing file that doesn't exist locally.

This PR flips force=true exactly when vmCfg.ImageDigest != "". Same semantics users get manually from cocoon image pull --force.

needForce := vmCfg.ImageDigest != ""
if pullErr := b.Pull(ctx, pullRef, needForce, progress.Nop); pullErr != nil { ... }

Why is this fine

• Cheap path stays cheap: no digest pinned → force=false, URL cache short-circuit fires when blob present
• Slow path triggers only when the caller has shown the digest isn't local. Re-download recomputes sha256, overwrites the URL→blob index entry, post-pull Inspect(ImageDigest) validates
• No behavior change for the OCI backend: digestPullRef already converts image@sha256:... for OCI refs, which are digest-immutable; the OCI Pull happily handles the redundant force flag
• No new error paths: existing warning-on-failure semantics preserved for imported images

Test plan

• New unit tests in cmd/core/ensure_image_test.go — fake backend records Pull(force), asserts:
  • ImageDigest pinned + digest missing locally → force=true
  • No ImageDigest set → force=false
  • ImageDigest pinned + digest already local → Pull not called at all
• go test ./cmd/core/... -v passes
• go build ./... clean
• Integration regression on testbed: reproduce issue 37 scenario by manually planting a stale URL→digest entry, then verify clone now succeeds instead of dying in VerifyBaseFiles

Related

Closes #37.

Companion work:

• cocoonstack/epoch#4 — /dl/{name}/{ref} route adds tag- and digest-aware URL forms, so issue 38's cocoonstack.snapshot.baseimage annotations can use immutable digest URLs that pin perfectly via this fix

[Copilot]

Pull request overview

This PR fixes a clone/restore failure mode for cloud image URLs when the VM config pins a specific ImageDigest but the local URL→blob cache points at stale content. It makes EnsureImage force a re-pull when a digest is pinned, aligning EnsureImage behavior with cocoon image pull --force.

Changes:

• Update cmd/core/helpers.go:EnsureImage to call Pull(..., force=true, ...) when vmCfg.ImageDigest != "".
• Add unit tests to assert the force decision and that Pull is skipped when the digest is already local.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.

File	Description
cmd/core/helpers.go	Forces pulls when ImageDigest is pinned to bypass cloudimg URL-cache short-circuiting.
cmd/core/ensure_image_test.go	Adds regression tests verifying EnsureImage passes the expected force flag and skips pulling when already local.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated no new comments.