search

opencontainers / distribution-spec

OCI Distribution Specification
https://opencontainers.org
Apache License 2.0
811 stars 202 forks source link

Move filtersApplied annotation to a response header #376

Closed imjasonh closed 1 year ago

imjasonh commented 1 year ago

If filtering is requested and applied, the response MUST include an annotation (org.opencontainers.referrers.filtersApplied) denoting that an artifactType filter was applied. If multiple filters are applied, the annotation MUST contain a comma separated list of applied filters.

I think this would make more sense to be a response header, e.g., X-OCI-Referrers-Filters-Applied (naming obviously open to debate).

A few reasons, in decreasing order of strength:

  1. requesting a filter is done at the HTTP level, in a query parameter. An indication that the filter was respected should belong at the HTTP level, and a response header is a good place.
  2. adding the annotation changes the index manifest contents, which feels kinda gross. If my filter doesn't change the result (I only have SBOMs and I filtered to only show SBOMs) then the index manifest response would be the same, except one includes that annotation.
  3. It's a reserved annotation, but folks can still add that annotation to their index manifests and POST them. They might not even mean to; they might pull a referrers index manifest from /referrers?artifactType=foo, including the annotation, and push that unchanged to a registry that doesn't support referrers, to the fallback tag, with the annotation included. This might be fine, but gets confusing, and it's completely avoidable.
imjasonh commented 1 year ago

I think https://github.com/opencontainers/image-spec/pull/1005 makes me even more convinced that this is the better way to do this. Image-spec shouldn't have to have any awareness of whether or how a registry communicates that it applied filters; image-spec is theoretically agnostic to the existence of any registry implementations, as otherwise written. Removing these lets it remain blissfully unaware of registries, would that we all could be.