Vendor after merging mtrmac/image:schema12

vendor/github.com/containers/image/copy/copy.go

@@ -7,13 +7,13 @@ import (
 	"io"
 	"io/ioutil"
 	"reflect"
+	"strings"
 	"time"
 
 	pb "gopkg.in/cheggaaa/pb.v1"
 
 	"github.com/Sirupsen/logrus"
 	"github.com/containers/image/image"
-	"github.com/containers/image/manifest"
 	"github.com/containers/image/pkg/compression"
 	"github.com/containers/image/signature"
 	"github.com/containers/image/transports"
@@ -22,11 +22,6 @@ import (
 	"github.com/pkg/errors"
 )
 
-// preferredManifestMIMETypes lists manifest MIME types in order of our preference, if we can't use the original manifest and need to convert.
-// Prefer v2s2 to v2s1 because v2s2 does not need to be changed when uploading to a different location.
-// Include v2s1 signed but not v2s1 unsigned, because docker/distribution requires a signature even if the unsigned MIME type is used.
-var preferredManifestMIMETypes = []string{manifest.DockerV2Schema2MediaType, manifest.DockerV2Schema1SignedMediaType}
-
 type digestingReader struct {
 	source           io.Reader
 	digester         digest.Digester
@@ -186,8 +181,12 @@ func Image(policyContext *signature.PolicyContext, destRef, srcRef types.ImageRe
 
 	canModifyManifest := len(sigs) == 0
 	manifestUpdates := types.ManifestUpdateOptions{}
+	manifestUpdates.InformationOnly.Destination = dest
 
-	if err := determineManifestConversion(&manifestUpdates, src, destSupportedManifestMIMETypes, canModifyManifest); err != nil {
+	// We compute preferredManifestMIMEType only to show it in error messages.
+	// Without having to add this context in an error message, we would be happy enough to know only that no conversion is needed.
+	preferredManifestMIMEType, otherManifestMIMETypeCandidates, err := determineManifestConversion(&manifestUpdates, src, destSupportedManifestMIMETypes, canModifyManifest)
+	if err != nil {
 		return err
 	}
 
@@ -210,54 +209,58 @@ func Image(policyContext *signature.PolicyContext, destRef, srcRef types.ImageRe
 		return err
 	}
 
-	pendingImage := src
+	// With docker/distribution registries we do not know whether the registry accepts schema2 or schema1 only;
-	if !reflect.DeepEqual(manifestUpdates, types.ManifestUpdateOptions{InformationOnly: manifestUpdates.InformationOnly}) {
+	// and at least with the OpenShift registry "acceptschema2" option, there is no way to detect the support
-		if !canModifyManifest {
+	// without actually trying to upload something and getting a types.ManifestTypeRejectedError.
-			return errors.Errorf("Internal error: copy needs an updated manifest but that was known to be forbidden")
+	// So, try the preferred manifest MIME type. If the process succeeds, fine…
-		}
+	manifest, err := ic.copyUpdatedConfigAndManifest()
-		manifestUpdates.InformationOnly.Destination = dest
-		pendingImage, err = src.UpdatedImage(manifestUpdates)
-		if err != nil {
-			return errors.Wrap(err, "Error creating an updated image manifest")
-		}
-	}
-	manifest, _, err := pendingImage.Manifest()
 	if err != nil {
-		return errors.Wrap(err, "Error reading manifest")
+		logrus.Debugf("Writing manifest using preferred type %s failed: %v", preferredManifestMIMEType, err)
-	}
+		// … if it fails, _and_ the failure is because the manifest is rejected, we may have other options.
+		if _, isManifestRejected := errors.Cause(err).(types.ManifestTypeRejectedError); !isManifestRejected || len(otherManifestMIMETypeCandidates) == 0 {
+			// We don’t have other options.
+			// In principle the code below would handle this as well, but the resulting  error message is fairly ugly. Do
+			// Don’t bother the user with MIME types if we have no choice.
+			return err
+		}
+		// If the original MIME type is acceptable, determineManifestConversion always uses it as preferredManifestMIMEType.
+		// So if we are here, we will definitely be trying to convert the manifest.
+		// With !canModifyManifest, that would just be a string of repeated failures for the same reason,
+		// so let’s bail out early and with a better error message.
+		if !canModifyManifest {
+			return errors.Wrap(err, "Writing manifest failed (and converting it is not possible)")
+		}
 
-	if err := ic.copyConfig(pendingImage); err != nil {
+		// errs is a list of errors when trying various manifest types. Also serves as an "upload succeeded" flag when set to nil.
-		return err
+		errs := []string{fmt.Sprintf("%s(%v)", preferredManifestMIMEType, err)}
+		for _, manifestMIMEType := range otherManifestMIMETypeCandidates {
+			logrus.Debugf("Trying to use manifest type %s…", manifestMIMEType)
+			manifestUpdates.ManifestMIMEType = manifestMIMEType
+			attemptedManifest, err := ic.copyUpdatedConfigAndManifest()
+			if err != nil {
+				logrus.Debugf("Upload of manifest type %s failed: %v", manifestMIMEType, err)
+				errs = append(errs, fmt.Sprintf("%s(%v)", manifestMIMEType, err))
+				continue
+			}
+
+			// We have successfully uploaded a manifest.
+			manifest = attemptedManifest
+			errs = nil // Mark this as a success so that we don't abort below.
+			break
+		}
+		if errs != nil {
+			return fmt.Errorf("Uploading manifest failed, attempted the following formats: %s", strings.Join(errs, ", "))
+		}
 	}
 
 	if options.SignBy != "" {
-		mech, err := signature.NewGPGSigningMechanism()
+		newSig, err := createSignature(dest, manifest, options.SignBy, reportWriter)
 		if err != nil {
-			return errors.Wrap(err, "Error initializing GPG")
+			return err
-		}
-		defer mech.Close()
-		if err := mech.SupportsSigning(); err != nil {
-			return errors.Wrap(err, "Signing not supported")
-		}
-
-		dockerReference := dest.Reference().DockerReference()
-		if dockerReference == nil {
-			return errors.Errorf("Cannot determine canonical Docker reference for destination %s", transports.ImageName(dest.Reference()))
-		}
-
-		writeReport("Signing manifest\n")
-		newSig, err := signature.SignDockerManifest(manifest, dockerReference.String(), mech, options.SignBy)
-		if err != nil {
-			return errors.Wrap(err, "Error creating signature")
 		}
 		sigs = append(sigs, newSig)
 	}
 
-	writeReport("Writing manifest to image destination\n")
-	if err := dest.PutManifest(manifest); err != nil {
-		return errors.Wrap(err, "Error writing manifest")
-	}
-
 	writeReport("Storing signatures\n")
 	if err := dest.PutSignatures(sigs); err != nil {
 		return errors.Wrap(err, "Error writing signatures")
@@ -322,6 +325,45 @@ func layerDigestsDiffer(a, b []types.BlobInfo) bool {
 	return false
 }
 
+// copyUpdatedConfigAndManifest updates the image per ic.manifestUpdates, if necessary,
+// stores the resulting config and manifest ot the destination, and returns the stored manifest.
+func (ic *imageCopier) copyUpdatedConfigAndManifest() ([]byte, error) {
+	pendingImage := ic.src
+	if !reflect.DeepEqual(*ic.manifestUpdates, types.ManifestUpdateOptions{InformationOnly: ic.manifestUpdates.InformationOnly}) {
+		if !ic.canModifyManifest {
+			return nil, errors.Errorf("Internal error: copy needs an updated manifest but that was known to be forbidden")
+		}
+		if !ic.diffIDsAreNeeded && ic.src.UpdatedImageNeedsLayerDiffIDs(*ic.manifestUpdates) {
+			// We have set ic.diffIDsAreNeeded based on the preferred MIME type returned by determineManifestConversion.
+			// So, this can only happen if we are trying to upload using one of the other MIME type candidates.
+			// Because UpdatedImageNeedsLayerDiffIDs only when converting from s1 to s2, this case should only arise
+			// when ic.dest.SupportedManifestMIMETypes() includes both s1 and s2, the upload using s1 failed, and we are now trying s2.
+			// Supposedly s2-only registries do not exist or are extremely rare, so failing with this error message is good enough for now.
+			// If handling such registries turned out to be necessary, we could compute ic.diffIDsAreNeeded based on the full list of manifest MIME type candidates.
+			return nil, errors.Errorf("Can not convert image to %s, preparing DiffIDs for this case is not supported", ic.manifestUpdates.ManifestMIMEType)
+		}
+		pi, err := ic.src.UpdatedImage(*ic.manifestUpdates)
+		if err != nil {
+			return nil, errors.Wrap(err, "Error creating an updated image manifest")
+		}
+		pendingImage = pi
+	}
+	manifest, _, err := pendingImage.Manifest()
+	if err != nil {
+		return nil, errors.Wrap(err, "Error reading manifest")
+	}
+
+	if err := ic.copyConfig(pendingImage); err != nil {
+		return nil, err
+	}
+
+	fmt.Fprintf(ic.reportWriter, "Writing manifest to image destination\n")
+	if err := ic.dest.PutManifest(manifest); err != nil {
+		return nil, errors.Wrap(err, "Error writing manifest")
+	}
+	return manifest, nil
+}
+
 // copyConfig copies config.json, if any, from src to dest.
 func (ic *imageCopier) copyConfig(src types.Image) error {
 	srcInfo := src.ConfigInfo()
@@ -575,41 +617,3 @@ func compressGoroutine(dest *io.PipeWriter, src io.Reader) {
 
 	_, err = io.Copy(zipper, src) // Sets err to nil, i.e. causes dest.Close()
 }
-
-// determineManifestConversion updates manifestUpdates to convert manifest to a supported MIME type, if necessary and canModifyManifest.
-// Note that the conversion will only happen later, through src.UpdatedImage
-func determineManifestConversion(manifestUpdates *types.ManifestUpdateOptions, src types.Image, destSupportedManifestMIMETypes []string, canModifyManifest bool) error {
-	if len(destSupportedManifestMIMETypes) == 0 {
-		return nil // Anything goes
-	}
-	supportedByDest := map[string]struct{}{}
-	for _, t := range destSupportedManifestMIMETypes {
-		supportedByDest[t] = struct{}{}
-	}
-
-	_, srcType, err := src.Manifest()
-	if err != nil { // This should have been cached?!
-		return errors.Wrap(err, "Error reading manifest")
-	}
-	if _, ok := supportedByDest[srcType]; ok {
-		logrus.Debugf("Manifest MIME type %s is declared supported by the destination", srcType)
-		return nil
-	}
-
-	// OK, we should convert the manifest.
-	if !canModifyManifest {
-		logrus.Debugf("Manifest MIME type %s is not supported by the destination, but we can't modify the manifest, hoping for the best...")
-		return nil // Take our chances - FIXME? Or should we fail without trying?
-	}
-
-	var chosenType = destSupportedManifestMIMETypes[0] // This one is known to be supported.
-	for _, t := range preferredManifestMIMETypes {
-		if _, ok := supportedByDest[t]; ok {
-			chosenType = t
-			break
-		}
-	}
-	logrus.Debugf("Will convert manifest from MIME type %s to %s", srcType, chosenType)
-	manifestUpdates.ManifestMIMEType = chosenType
-	return nil
-}

vendor/github.com/containers/image/copy/manifest.go

@@ -0,0 +1,102 @@
+package copy
+
+import (
+	"strings"
+
+	"github.com/Sirupsen/logrus"
+	"github.com/containers/image/manifest"
+	"github.com/containers/image/types"
+	"github.com/pkg/errors"
+)
+
+// preferredManifestMIMETypes lists manifest MIME types in order of our preference, if we can't use the original manifest and need to convert.
+// Prefer v2s2 to v2s1 because v2s2 does not need to be changed when uploading to a different location.
+// Include v2s1 signed but not v2s1 unsigned, because docker/distribution requires a signature even if the unsigned MIME type is used.
+var preferredManifestMIMETypes = []string{manifest.DockerV2Schema2MediaType, manifest.DockerV2Schema1SignedMediaType}
+
+// orderedSet is a list of strings (MIME types in our case), with each string appearing at most once.
+type orderedSet struct {
+	list     []string
+	included map[string]struct{}
+}
+
+// newOrderedSet creates a correctly initialized orderedSet.
+// [Sometimes it would be really nice if Golang had constructors…]
+func newOrderedSet() *orderedSet {
+	return &orderedSet{
+		list:     []string{},
+		included: map[string]struct{}{},
+	}
+}
+
+// append adds s to the end of os, only if it is not included already.
+func (os *orderedSet) append(s string) {
+	if _, ok := os.included[s]; !ok {
+		os.list = append(os.list, s)
+		os.included[s] = struct{}{}
+	}
+}
+
+// determineManifestConversion updates manifestUpdates to convert manifest to a supported MIME type, if necessary and canModifyManifest.
+// Note that the conversion will only happen later, through src.UpdatedImage
+// Returns the preferred manifest MIME type (whether we are converting to it or using it unmodified),
+// and a list of other possible alternatives, in order.
+func determineManifestConversion(manifestUpdates *types.ManifestUpdateOptions, src types.Image, destSupportedManifestMIMETypes []string, canModifyManifest bool) (string, []string, error) {
+	_, srcType, err := src.Manifest()
+	if err != nil { // This should have been cached?!
+		return "", nil, errors.Wrap(err, "Error reading manifest")
+	}
+
+	if len(destSupportedManifestMIMETypes) == 0 {
+		return srcType, []string{}, nil // Anything goes; just use the original as is, do not try any conversions.
+	}
+	supportedByDest := map[string]struct{}{}
+	for _, t := range destSupportedManifestMIMETypes {
+		supportedByDest[t] = struct{}{}
+	}
+
+	// destSupportedManifestMIMETypes is a static guess; a particular registry may still only support a subset of the types.
+	// So, build a list of types to try in order of decreasing preference.
+	// FIXME? This treats manifest.DockerV2Schema1SignedMediaType and manifest.DockerV2Schema1MediaType as distinct,
+	// although we are not really making any conversion, and it is very unlikely that a destination would support one but not the other.
+	// In practice, schema1 is probably the lowest common denominator, so we would expect to try the first one of the MIME types
+	// and never attempt the other one.
+	prioritizedTypes := newOrderedSet()
+
+	// First of all, prefer to keep the original manifest unmodified.
+	if _, ok := supportedByDest[srcType]; ok {
+		prioritizedTypes.append(srcType)
+	}
+	if !canModifyManifest {
+		// We could also drop the !canModifyManifest parameter and have the caller
+		// make the choice; it is already doing that to an extent, to improve error
+		// messages.  But it is nice to hide the “if !canModifyManifest, do no conversion”
+		// special case in here; the caller can then worry (or not) only about a good UI.
+		logrus.Debugf("We can't modify the manifest, hoping for the best...")
+		return srcType, []string{}, nil // Take our chances - FIXME? Or should we fail without trying?
+	}
+
+	// Then use our list of preferred types.
+	for _, t := range preferredManifestMIMETypes {
+		if _, ok := supportedByDest[t]; ok {
+			prioritizedTypes.append(t)
+		}
+	}
+
+	// Finally, try anything else the destination supports.
+	for _, t := range destSupportedManifestMIMETypes {
+		prioritizedTypes.append(t)
+	}
+
+	logrus.Debugf("Manifest has MIME type %s, ordered candidate list [%s]", srcType, strings.Join(prioritizedTypes.list, ", "))
+	if len(prioritizedTypes.list) == 0 { // Coverage: destSupportedManifestMIMETypes is not empty (or we would have exited in the “Anything goes” case above), so this should never happen.
+		return "", nil, errors.New("Internal error: no candidate MIME types")
+	}
+	preferredType := prioritizedTypes.list[0]
+	if preferredType != srcType {
+		manifestUpdates.ManifestMIMEType = preferredType
+	} else {
+		logrus.Debugf("... will first try using the original manifest unmodified")
+	}
+	return preferredType, prioritizedTypes.list[1:], nil
+}

vendor/github.com/containers/image/copy/sign.go

@@ -0,0 +1,35 @@
+package copy
+
+import (
+	"fmt"
+	"io"
+
+	"github.com/containers/image/signature"
+	"github.com/containers/image/transports"
+	"github.com/containers/image/types"
+	"github.com/pkg/errors"
+)
+
+// createSignature creates a new signature of manifest at (identified by) dest using keyIdentity.
+func createSignature(dest types.ImageDestination, manifest []byte, keyIdentity string, reportWriter io.Writer) ([]byte, error) {
+	mech, err := signature.NewGPGSigningMechanism()
+	if err != nil {
+		return nil, errors.Wrap(err, "Error initializing GPG")
+	}
+	defer mech.Close()
+	if err := mech.SupportsSigning(); err != nil {
+		return nil, errors.Wrap(err, "Signing not supported")
+	}
+
+	dockerReference := dest.Reference().DockerReference()
+	if dockerReference == nil {
+		return nil, errors.Errorf("Cannot determine canonical Docker reference for destination %s", transports.ImageName(dest.Reference()))
+	}
+
+	fmt.Fprintf(reportWriter, "Signing manifest\n")
+	newSig, err := signature.SignDockerManifest(manifest, dockerReference.String(), mech, keyIdentity)
+	if err != nil {
+		return nil, errors.Wrap(err, "Error creating signature")
+	}
+	return newSig, nil
+}

vendor/github.com/containers/image/directory/directory_dest.go

@@ -118,6 +118,10 @@ func (d *dirImageDestination) ReapplyBlob(info types.BlobInfo) (types.BlobInfo,
 	return info, nil
 }
 
+// PutManifest writes manifest to the destination.
+// FIXME? This should also receive a MIME type if known, to differentiate between schema versions.
+// If the destination is in principle available, refuses this manifest type (e.g. it does not recognize the schema),
+// but may accept a different manifest type, the returned error must be an ManifestTypeRejectedError.
 func (d *dirImageDestination) PutManifest(manifest []byte) error {
 	return ioutil.WriteFile(d.ref.manifestPath(), manifest, 0644)
 }

vendor/github.com/containers/image/docker/docker_image_dest.go

@@ -16,6 +16,9 @@ import (
 	"github.com/containers/image/docker/reference"
 	"github.com/containers/image/manifest"
 	"github.com/containers/image/types"
+	"github.com/docker/distribution/registry/api/errcode"
+	"github.com/docker/distribution/registry/api/v2"
+	"github.com/docker/distribution/registry/client"
 	"github.com/opencontainers/go-digest"
 	"github.com/pkg/errors"
 )
@@ -209,6 +212,10 @@ func (d *dockerImageDestination) ReapplyBlob(info types.BlobInfo) (types.BlobInf
 	return info, nil
 }
 
+// PutManifest writes manifest to the destination.
+// FIXME? This should also receive a MIME type if known, to differentiate between schema versions.
+// If the destination is in principle available, refuses this manifest type (e.g. it does not recognize the schema),
+// but may accept a different manifest type, the returned error must be an ManifestTypeRejectedError.
 func (d *dockerImageDestination) PutManifest(m []byte) error {
 	digest, err := manifest.Digest(m)
 	if err != nil {
@@ -233,16 +240,31 @@ func (d *dockerImageDestination) PutManifest(m []byte) error {
 	}
 	defer res.Body.Close()
 	if res.StatusCode != http.StatusCreated {
-		body, err := ioutil.ReadAll(res.Body)
+		err = errors.Wrapf(client.HandleErrorResponse(res), "Error uploading manifest to %s", path)
-		if err == nil {
+		if isManifestInvalidError(errors.Cause(err)) {
-			logrus.Debugf("Error body %s", string(body))
+			err = types.ManifestTypeRejectedError{Err: err}
 		}
-		logrus.Debugf("Error uploading manifest, status %d, %#v", res.StatusCode, res)
+		return err
-		return errors.Errorf("Error uploading manifest to %s, status %d", path, res.StatusCode)
 	}
 	return nil
 }
 
+// isManifestInvalidError returns true iff err from client.HandleErrorReponse is a “manifest invalid” error.
+func isManifestInvalidError(err error) bool {
+	errors, ok := err.(errcode.Errors)
+	if !ok || len(errors) == 0 {
+		return false
+	}
+	ec, ok := errors[0].(errcode.ErrorCoder)
+	if !ok {
+		return false
+	}
+	// ErrorCodeManifestInvalid is returned by OpenShift with acceptschema2=false.
+	// ErrorCodeTagInvalid is returned by docker/distribution (at least as of ec87e9b6971d831f0eff752ddb54fb64693e51cd)
+	// when uploading to a tag (because it can’t find a matching tag inside the manifest)
+	return ec.ErrorCode() == v2.ErrorCodeManifestInvalid || ec.ErrorCode() == v2.ErrorCodeTagInvalid
+}
+
 func (d *dockerImageDestination) PutSignatures(signatures [][]byte) error {
 	// Do not fail if we don’t really need to support signatures.
 	if len(signatures) == 0 {

vendor/github.com/containers/image/docker/tarfile/dest.go

@@ -156,10 +156,13 @@ func (d *Destination) ReapplyBlob(info types.BlobInfo) (types.BlobInfo, error) {
 	return info, nil
 }
 
-// PutManifest sends the given manifest blob to the destination.
+// PutManifest writes manifest to the destination.
-// FIXME? This should also receive a MIME type if known, to differentiate
+// FIXME? This should also receive a MIME type if known, to differentiate between schema versions.
-//        between schema versions.
+// If the destination is in principle available, refuses this manifest type (e.g. it does not recognize the schema),
+// but may accept a different manifest type, the returned error must be an ManifestTypeRejectedError.
 func (d *Destination) PutManifest(m []byte) error {
+	// We do not bother with types.ManifestTypeRejectedError; our .SupportedManifestMIMETypes() above is already providing only one alternative,
+	// so the caller trying a different manifest kind would be pointless.
 	var man schema2Manifest
 	if err := json.Unmarshal(m, &man); err != nil {
 		return errors.Wrap(err, "Error parsing manifest")

vendor/github.com/containers/image/oci/layout/oci_dest.go

@@ -138,6 +138,10 @@ func (d *ociImageDestination) ReapplyBlob(info types.BlobInfo) (types.BlobInfo,
 	return info, nil
 }
 
+// PutManifest writes manifest to the destination.
+// FIXME? This should also receive a MIME type if known, to differentiate between schema versions.
+// If the destination is in principle available, refuses this manifest type (e.g. it does not recognize the schema),
+// but may accept a different manifest type, the returned error must be an ManifestTypeRejectedError.
 func (d *ociImageDestination) PutManifest(m []byte) error {
 	digest, err := manifest.Digest(m)
 	if err != nil {

vendor/github.com/containers/image/openshift/openshift.go

@@ -383,6 +383,10 @@ func (d *openshiftImageDestination) ReapplyBlob(info types.BlobInfo) (types.Blob
 	return d.docker.ReapplyBlob(info)
 }
 
+// PutManifest writes manifest to the destination.
+// FIXME? This should also receive a MIME type if known, to differentiate between schema versions.
+// If the destination is in principle available, refuses this manifest type (e.g. it does not recognize the schema),
+// but may accept a different manifest type, the returned error must be an ManifestTypeRejectedError.
 func (d *openshiftImageDestination) PutManifest(m []byte) error {
 	manifestDigest, err := manifest.Digest(m)
 	if err != nil {

vendor/github.com/containers/image/ostree/ostree_dest.go

@@ -218,6 +218,10 @@ func (d *ostreeImageDestination) ReapplyBlob(info types.BlobInfo) (types.BlobInf
 	return info, nil
 }
 
+// PutManifest writes manifest to the destination.
+// FIXME? This should also receive a MIME type if known, to differentiate between schema versions.
+// If the destination is in principle available, refuses this manifest type (e.g. it does not recognize the schema),
+// but may accept a different manifest type, the returned error must be an ManifestTypeRejectedError.
 func (d *ostreeImageDestination) PutManifest(manifest []byte) error {
 	d.manifest = string(manifest)
 

vendor/github.com/containers/image/storage/storage_image.go

@@ -420,6 +420,10 @@ func (s *storageImageDestination) SupportedManifestMIMETypes() []string {
 	return nil
 }
 
+// PutManifest writes manifest to the destination.
+// FIXME? This should also receive a MIME type if known, to differentiate between schema versions.
+// If the destination is in principle available, refuses this manifest type (e.g. it does not recognize the schema),
+// but may accept a different manifest type, the returned error must be an ManifestTypeRejectedError.
 func (s *storageImageDestination) PutManifest(manifest []byte) error {
 	s.Manifest = make([]byte, len(manifest))
 	copy(s.Manifest, manifest)

vendor/github.com/containers/image/types/types.go

@@ -167,8 +167,11 @@ type ImageDestination interface {
 	HasBlob(info BlobInfo) (bool, int64, error)
 	// ReapplyBlob informs the image destination that a blob for which HasBlob previously returned true would have been passed to PutBlob if it had returned false.  Like HasBlob and unlike PutBlob, the digest can not be empty.  If the blob is a filesystem layer, this signifies that the changes it describes need to be applied again when composing a filesystem tree.
 	ReapplyBlob(info BlobInfo) (BlobInfo, error)
+	// PutManifest writes manifest to the destination.
 	// FIXME? This should also receive a MIME type if known, to differentiate between schema versions.
-	PutManifest([]byte) error
+	// If the destination is in principle available, refuses this manifest type (e.g. it does not recognize the schema),
+	// but may accept a different manifest type, the returned error must be an ManifestTypeRejectedError.
+	PutManifest(manifest []byte) error
 	PutSignatures(signatures [][]byte) error
 	// Commit marks the process of storing the image as successful and asks for the image to be persisted.
 	// WARNING: This does not have any transactional semantics:
@@ -177,6 +180,16 @@ type ImageDestination interface {
 	Commit() error
 }
 
+// ManifestTypeRejectedError is returned by ImageDestination.PutManifest if the destination is in principle available,
+// refuses specifically this manifest type, but may accept a different manifest type.
+type ManifestTypeRejectedError struct { // We only use a struct to allow a type assertion, without limiting the contents of the error otherwise.
+	Err error
+}
+
+func (e ManifestTypeRejectedError) Error() string {
+	return e.Err.Error()
+}
+
 // UnparsedImage is an Image-to-be; until it is verified and accepted, it only caries its identity and caches manifest and signature blobs.
 // Thus, an UnparsedImage can be created from an ImageSource simply by fetching blobs without interpreting them,
 // allowing cryptographic signature verification to happen first, before even fetching the manifest, or parsing anything else.