fix(oci): cache tag lists and normalize manifest variants

[abhinavgautam01]

Fixes #249

Summary

• Cache OCI /v2/<name>/tags/list responses automatically, including when general metadata caching is disabled.
• Serve stale cached tag lists when the upstream registry or token service is temporarily unavailable.
• Normalize manifest Accept headers before deriving cache keys, so equivalent media-type lists reuse the same cached variant.
• Verify a cached manifest's content type is acceptable for the requesting client before serving it.
• Document OCI manifest and tag-list offline caching behavior.

Validation

• gofmt
• go tool golangci-lint run ./...
• go vet ./...
• go test -race ./...
• git diff --check

[Copilot]

Pull request overview

This PR improves OCI offline behavior by caching tag-list responses and making manifest caching more robust across equivalent Accept header variants, so previously warmed caches can be reused when upstream registry/token services are unavailable.

Changes:

• Add automatic caching (with stale fallback) for OCI /v2/<name>/tags/list responses, independent of general metadata caching.
• Normalize manifest Accept headers for cache-key derivation and validate cached manifest content types against the caller’s Accept.
• Add tests and documentation for OCI tag-list + manifest offline caching behavior.

Reviewed changes

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

Show a summary per file

File	Description
internal/handler/container.go	Routes tag-list requests through the new cached implementation.
internal/handler/container_tags.go	Implements tag-list caching, ETag revalidation, and stale fallback behavior.
internal/handler/container_manifest.go	Normalizes Accept for cache keys and validates cached manifest content type against request.
internal/handler/container_test.go	Adds coverage for stale tag-list fallback and manifest variant normalization/content-type gating.
docs/configuration.md	Documents always-cached OCI manifests and tag lists + stale behavior.
docs/architecture.md	Updates architecture notes to include tag lists as always-cached metadata.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[andrew]

Please address these cache compatibility issues:

• Preserve reads of existing manifest cache keys. Previous releases hashed the raw Accept value, so the normalized key misses warmed entries after an upgrade. On a normalized-key miss, try the legacy key and rewrite the entry under the normalized key. Add an upgrade test using previous-format data.
• Apply quality to the most specific matching Accept media range. Accept: application/vnd.oci.image.index.v1+json;q=0, */*;q=1 currently accepts the explicitly excluded index through the wildcard. Add a regression test.

[abhinavgautam01]

Thanks, implemented the legacy raw-Accept cache-key fallback with migration and upgrade coverage. Also fixed specificity-aware Accept matching so an explicit q=0 exclusion overrides a wildcard, with regression coverage.

[andrew]

Please preserve mixed-version and rollback cache access. Fresh manifests are now stored only under the normalized Accept key. Older replicas and rollback releases still hash the raw Accept value, so they cannot read entries first cached by the new release. Dual-write the raw key when it differs, including the digest alias. Add a handler-level test that warms through the public route and verifies the previous-format key is written.

[abhinavgautam01]

Implemented dual-write support for normalized and legacy raw-Accept keys, including digest aliases. Added a handler-level warm-route test that verifies both previous-format keys are written.