fix(container): serve cached images when upstream is unavailable

[andrew]

Summary

• check the blob cache before any upstream authentication or network request for both GET and HEAD
• persist OCI manifests and serve digest-addressed manifests directly from cache
• cache tag responses under their returned digest so later digest pulls work offline
• revalidate mutable tags by TTL and serve stale manifests when the registry returns a network error, 429, or 5xx
• add an idempotent metadata-cache migration for persisted manifest digests
• remove hard-coded Docker Hub token requests in favor of the challenge-aware transport from fix(upstream): apply authentication through shared transport #198

Why

Previously cached blobs were unreachable when the Docker Hub token service was down, and manifests were never cached. A previously fetched image therefore could not be pulled when its registry or authentication service was unavailable.

Depends on #198. Once #198 merges, this PR can be retargeted to main.

Fixes #186.

Validation

• go test ./... -count=1
• go test -race ./... -count=1
• go tool golangci-lint run ./...

[Copilot]

Pull request overview

This PR improves the OCI (container) proxy’s offline behavior by ensuring previously fetched images remain pullable when the upstream registry or its auth/token service is unavailable. It does this by checking the blob cache before any upstream access, adding persistent manifest caching (including digest aliasing), and serving stale tag manifests on retryable upstream failures.

Changes:

• Add GetCachedArtifact to support cache-only lookups (no upstream contact) and use it in container blob handling for both GET and HEAD.
• Introduce persistent OCI manifest caching with TTL-based revalidation for tags, digest-addressed immutable serving, digest aliasing, and stale fallback on network/429/5xx.
• Extend metadata cache storage to persist content_digest, including schema migration and tests; update docs to describe the OCI manifest caching exception.

Reviewed changes

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

Show a summary per file

File	Description
internal/handler/handler.go	Adds GetCachedArtifact and reuses it in artifact fetch paths.
internal/handler/handler_test.go	Updates test helpers to use purl.MakePURLString.
internal/handler/container.go	Checks blob cache before upstream for GET/HEAD; routes manifest handling through new caching logic.
internal/handler/container_test.go	Adds coverage for bearer challenge discovery and offline/cache behaviors for blobs/manifests.
internal/handler/container_manifest.go	Implements manifest caching, TTL revalidation, digest aliasing, and stale serving behavior.
internal/database/types.go	Adds ContentDigest to MetadataCacheEntry.
internal/database/schema.go	Adds content_digest column + migration.
internal/database/queries.go	Updates metadata cache queries/upsert to include content_digest.
internal/database/metadata_cache_test.go	Adds tests for digest persistence and migration behavior.
docs/configuration.md	Documents OCI manifest caching behavior and TTL/stale semantics.
docs/architecture.md	Notes OCI manifests as an exception that are cached automatically for offline pulls.

---

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