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.