Manifest list should not be identified by HTTP headers

[aecolley]

The manifest-list spec says:

A client will distinguish a manifest list from an image manifest based on the Content-Type returned in the HTTP response.

This is incorrect. A client will always discover a manifest list by following a descriptor in the refs/ directory, and the descriptor will state the media type. The media type will unambiguously distinguish manifests from manifest lists. No part of the spec requires obtaining a manifest/manifest list over HTTP.

In the event that a manifest list is obtained over HTTP, any mismatch between the Content-Type in the HTTP response header and the mediaType in the corresponding descriptor should be resolved in the spec rather than being implementation-defined. I suggest that the descriptor's mediaType should win.

[wking]

On Sat, Oct 15, 2016 at 05:09:41PM -0700, Adrian Colley wrote:

The manifest-list spec says:

A client will distinguish a manifest list from an image manifest
based on the Content-Type returned in the HTTP response.

This is incorrect. A client will always discover a manifest list by
following a descriptor in the refs/ directory, and the descriptor
will state the media type. The media type will unambiguously
distinguish manifests from manifest lists. No part of the spec
requires obtaining a manifest/manifest list over HTTP.

“will always discover … by following a descriptor” is too strict the
other way ;). Let's just drop the line about how folks get a
manifest-list (since they can get it any number of ways). In most
cases, folks will know (from a Content-Type header, a descriptor media
type, or other means) what type of blob they're dealing with before
they look at the blob.

In the event that a manifest list is obtained over HTTP, any
mismatch between the Content-Type in the HTTP response header and
the mediaType in the corresponding descriptor should be resolved
in the spec rather than being implementation-defined. I suggest that
the descriptor's mediaType should win.

I think it's less absolute. If you can verify the digest, ignore
Content-Type (this sounds like what you're suggesting here). If you
can't verify the digest, respect the Content-Type and require it to
match your expected media type (if any).

As an example of the “can't verify the digest” case, you could have an
HTTP interface like Docker's 1 with name-based references to
non-descriptor content. Requesters know they're asking for a
manifest, and can ask for a specific type, but they should check the
Content-Type to make sure the registry was able to fulfill their
request (or maybe they're happy with any manifest type and didn't set
Accept, in which case trusting Content-Type is probably their only
option).

And regardless of how you determine the content type, I'd recommend we
allow consumers to die if they don't have a media type by the time
they'd be parsing the blob. If clients want to look inside the blob
and try to guess its type (e.g. by unmarshalling into Versioned 2),
they can do that. But I don't think we should require anyone to look
inside the blob to figure out what it is (and I don't think we
currenly require this, but the presense of Versioned hints in this
direction).

[aecolley]

Yes, @wking is correct. I was wrong when I said that manifests were reached only through refs/. I still think that the spec should not assume that the manifest is obtained over HTTP.

Other than the sentence that mentions HTTP headers (quoted above), the spec does not attempt to resolve conflicts between media types, and this is fine.

[wking]

On Mon, Oct 17, 2016 at 03:42:10PM -0700, Adrian Colley wrote:

Other than the sentence that mentions HTTP headers (quoted above),
the spec does not attempt to resolve conflicts between media types,
and this is fine.

I've filed #392 to drop the line.