Add support for manifest list ("fat manifest")

Signed-off-by: Aaron Lehmann <aaron.lehmann@docker.com>

manifest/manifestlist/manifestlist.go

@@ -0,0 +1,151 @@
+package manifestlist
+
+import (
+	"encoding/json"
+	"errors"
+	"fmt"
+
+	"github.com/docker/distribution"
+	"github.com/docker/distribution/digest"
+	"github.com/docker/distribution/manifest"
+)
+
+// MediaTypeManifestList specifies the mediaType for manifest lists.
+const MediaTypeManifestList = "application/vnd.docker.distribution.manifest.list.v2+json"
+
+// SchemaVersion provides a pre-initialized version structure for this
+// packages version of the manifest.
+var SchemaVersion = manifest.Versioned{
+	SchemaVersion: 2,
+}
+
+func init() {
+	manifestListFunc := func(b []byte) (distribution.Manifest, distribution.Descriptor, error) {
+		m := new(DeserializedManifestList)
+		err := m.UnmarshalJSON(b)
+		if err != nil {
+			return nil, distribution.Descriptor{}, err
+		}
+
+		dgst := digest.FromBytes(b)
+		return m, distribution.Descriptor{Digest: dgst, Size: int64(len(b)), MediaType: MediaTypeManifestList}, err
+	}
+	err := distribution.RegisterManifestSchema(MediaTypeManifestList, manifestListFunc)
+	if err != nil {
+		panic(fmt.Sprintf("Unable to register manifest: %s", err))
+	}
+}
+
+// PlatformSpec specifies a platform where a particular image manifest is
+// applicable.
+type PlatformSpec struct {
+	// Architecture field specifies the CPU architecture, for example
+	// `amd64` or `ppc64`.
+	Architecture string `json:"architecture"`
+
+	// OS specifies the operating system, for example `linux` or `windows`.
+	OS string `json:"os"`
+
+	// Variant is an optional field specifying a variant of the CPU, for
+	// example `ppc64le` to specify a little-endian version of a PowerPC CPU.
+	Variant string `json:"variant,omitempty"`
+
+	// Features is an optional field specifuing an array of strings, each
+	// listing a required CPU feature (for example `sse4` or `aes`).
+	Features []string `json:"features,omitempty"`
+}
+
+// A ManifestDescriptor references a platform-specific manifest.
+type ManifestDescriptor struct {
+	distribution.Descriptor
+
+	// Platform specifies which platform the manifest pointed to by the
+	// descriptor runs on.
+	Platform PlatformSpec `json:"platform"`
+}
+
+// ManifestList references manifests for various platforms.
+type ManifestList struct {
+	manifest.Versioned
+
+	// MediaType is the media type of this document. It should always
+	// be set to MediaTypeManifestList.
+	MediaType string `json:"mediaType"`
+
+	// Config references the image configuration as a blob.
+	Manifests []ManifestDescriptor `json:"manifests"`
+}
+
+// References returnes the distribution descriptors for the referenced image
+// manifests.
+func (m ManifestList) References() []distribution.Descriptor {
+	dependencies := make([]distribution.Descriptor, len(m.Manifests))
+	for i := range m.Manifests {
+		dependencies[i] = m.Manifests[i].Descriptor
+	}
+
+	return dependencies
+}
+
+// DeserializedManifestList wraps ManifestList with a copy of the original
+// JSON.
+type DeserializedManifestList struct {
+	ManifestList
+
+	// canonical is the canonical byte representation of the Manifest.
+	canonical []byte
+}
+
+// FromDescriptors takes a slice of descriptors, and returns a
+// DeserializedManifestList which contains the resulting manifest list
+// and its JSON representation.
+func FromDescriptors(descriptors []ManifestDescriptor) (*DeserializedManifestList, error) {
+	m := ManifestList{
+		Versioned: SchemaVersion,
+		MediaType: MediaTypeManifestList,
+	}
+
+	m.Manifests = make([]ManifestDescriptor, len(descriptors), len(descriptors))
+	copy(m.Manifests, descriptors)
+
+	deserialized := DeserializedManifestList{
+		ManifestList: m,
+	}
+
+	var err error
+	deserialized.canonical, err = json.MarshalIndent(&m, "", "   ")
+	return &deserialized, err
+}
+
+// UnmarshalJSON populates a new ManifestList struct from JSON data.
+func (m *DeserializedManifestList) UnmarshalJSON(b []byte) error {
+	m.canonical = make([]byte, len(b), len(b))
+	// store manifest list in canonical
+	copy(m.canonical, b)
+
+	// Unmarshal canonical JSON into ManifestList object
+	var manifestList ManifestList
+	if err := json.Unmarshal(m.canonical, &manifestList); err != nil {
+		return err
+	}
+
+	m.ManifestList = manifestList
+
+	return nil
+}
+
+// MarshalJSON returns the contents of canonical. If canonical is empty,
+// marshals the inner contents.
+func (m *DeserializedManifestList) MarshalJSON() ([]byte, error) {
+	if len(m.canonical) > 0 {
+		return m.canonical, nil
+	}
+
+	return nil, errors.New("JSON representation not initialized in DeserializedManifestList")
+}
+
+// Payload returns the raw content of the manifest list. The contents can be
+// used to calculate the content identifier.
+func (m DeserializedManifestList) Payload() (string, []byte, error) {
+	return m.MediaType, m.canonical, nil
+}

manifest/manifestlist/manifestlist_test.go

@@ -0,0 +1,111 @@
+package manifestlist
+
+import (
+	"bytes"
+	"encoding/json"
+	"reflect"
+	"testing"
+
+	"github.com/docker/distribution"
+)
+
+var expectedManifestListSerialization = []byte(`{
+   "schemaVersion": 2,
+   "mediaType": "application/vnd.docker.distribution.manifest.list.v2+json",
+   "manifests": [
+      {
+         "mediaType": "application/vnd.docker.distribution.manifest.v2+json",
+         "size": 985,
+         "digest": "sha256:1a9ec845ee94c202b2d5da74a24f0ed2058318bfa9879fa541efaecba272e86b",
+         "platform": {
+            "architecture": "amd64",
+            "os": "linux",
+            "features": [
+               "sse4"
+            ]
+         }
+      },
+      {
+         "mediaType": "application/vnd.docker.distribution.manifest.v2+json",
+         "size": 2392,
+         "digest": "sha256:6346340964309634683409684360934680934608934608934608934068934608",
+         "platform": {
+            "architecture": "sun4m",
+            "os": "sunos"
+         }
+      }
+   ]
+}`)
+
+func TestManifestList(t *testing.T) {
+	manifestDescriptors := []ManifestDescriptor{
+		{
+			Descriptor: distribution.Descriptor{
+				Digest:    "sha256:1a9ec845ee94c202b2d5da74a24f0ed2058318bfa9879fa541efaecba272e86b",
+				Size:      985,
+				MediaType: "application/vnd.docker.distribution.manifest.v2+json",
+			},
+			Platform: PlatformSpec{
+				Architecture: "amd64",
+				OS:           "linux",
+				Features:     []string{"sse4"},
+			},
+		},
+		{
+			Descriptor: distribution.Descriptor{
+				Digest:    "sha256:6346340964309634683409684360934680934608934608934608934068934608",
+				Size:      2392,
+				MediaType: "application/vnd.docker.distribution.manifest.v2+json",
+			},
+			Platform: PlatformSpec{
+				Architecture: "sun4m",
+				OS:           "sunos",
+			},
+		},
+	}
+
+	deserialized, err := FromDescriptors(manifestDescriptors)
+	if err != nil {
+		t.Fatalf("error creating DeserializedManifestList: %v", err)
+	}
+
+	mediaType, canonical, err := deserialized.Payload()
+
+	if mediaType != MediaTypeManifestList {
+		t.Fatalf("unexpected media type: %s", mediaType)
+	}
+
+	// Check that the canonical field is the same as json.MarshalIndent
+	// with these parameters.
+	p, err := json.MarshalIndent(&deserialized.ManifestList, "", "   ")
+	if err != nil {
+		t.Fatalf("error marshaling manifest list: %v", err)
+	}
+	if !bytes.Equal(p, canonical) {
+		t.Fatalf("manifest bytes not equal: %q != %q", string(canonical), string(p))
+	}
+
+	// Check that the canonical field has the expected value.
+	if !bytes.Equal(expectedManifestListSerialization, canonical) {
+		t.Fatalf("manifest bytes not equal: %q != %q", string(canonical), string(expectedManifestListSerialization))
+	}
+
+	var unmarshalled DeserializedManifestList
+	if err := json.Unmarshal(deserialized.canonical, &unmarshalled); err != nil {
+		t.Fatalf("error unmarshaling manifest: %v", err)
+	}
+
+	if !reflect.DeepEqual(&unmarshalled, deserialized) {
+		t.Fatalf("manifests are different after unmarshaling: %v != %v", unmarshalled, *deserialized)
+	}
+
+	references := deserialized.References()
+	if len(references) != 2 {
+		t.Fatalf("unexpected number of references: %d", len(references))
+	}
+	for i := range references {
+		if !reflect.DeepEqual(references[i], manifestDescriptors[i].Descriptor) {
+			t.Fatalf("unexpected value %d returned by References: %v", i, references[i])
+		}
+	}
+}