content-negotiation: bring over the table from Sebastiaan

[vbatts]

From #212
Tagging @jonjohnsonjr and @thaJeztah, to wrap up that thread

I think this is missing expected status codes.

[vbatts]

and

We should probably link to https://docs.docker.com/registry/spec/manifest-v2-2/#backward-compatibility in a backwards compatibility section or something.

[jdolitsky]

👍

[vbatts]

k. Updated a little. And with the reference to the docker docs, I wonder if it may be good to also copy-paste the paragraph here for posterity sake? @thaJeztah

[jonjohnsonjr]

I think we need something like this, but I also think this is something incomplete.

At one point I put something together to decide what kind of down-conversion GCR would do, copying over from a spreadsheet, I think this is what we settled on:

Schema requested	Pushed as S1	Pushed as S2	Pushed as Manifest List	Pushed as OCI	Pushed as Image Index
S1		S2 -> S1	ML (-> S2) -> S1	x	x
S2	x		ML -> S2	x	x
Manifest List	x	x		x	x
OCI	x	x	x		II -> OCI
Image Index	x	x	x	x

Diagonal is reading what you wrote, so it works fine (blank space).

An x represents an error -- GCR returns a 404 here, which is misaligned with the HTTP spec, I think.

Anything else describes how we down-convert for backward compatibility stuff.

We don't consider the ordering of accept headers, just "Do they accept what we have? If not do they accept anything we can convert to?"

There were other variants of what is possible, but we decided to be conservative, because mutating content-addressable stuff is... not a great idea. I think we require you to put OCI accept headers, for example, even though most clients would probably do just fine if we returned an OCI manifest when they accept schema 2 manifests. Alas.

I'd like to be explicit about what status codes should be returned by a registry in these situations.

ECR has a similar diagram: https://docs.aws.amazon.com/AmazonECR/latest/userguide/image-manifest-formats.html

Note that ECR will freely translate between OCI and Docker media types, which is different from what GCR does, mostly because this isn't in the spec 😄

[stevvooe]

LGTM

I think there are some other comments to address but this documents an interesting history of datatypes.

[dmcgowan]

LGTM

[thaJeztah]

LGTM

sorry, not sure why I didn't see this one.

Would be good if someone could re-run the curl command for these combinations that I mentioned in #212

(to be sure I didn't mess up any of the combinations .. it's been a while 😂)

[vbatts]

(not sure why pullapprove is only seeing 1 of the approvals, but that won't matter as we've moved away from pullapprove)